fix(sdk,cli): evict stale local bundle cache entries, add cache info/clear commands (#60, #78, #79, #95)

packages/cli/src/commands/cache/clear.ts

@@ -0,0 +1,49 @@
+import { createInterface } from 'node:readline';
+import { existsSync, rmSync } from 'node:fs';
+import { mpak } from '../../utils/config.js';
+import { formatSize, logger } from '../../utils/format.js';
+
+export interface CacheClearOptions {
+  force?: boolean;
+}
+
+async function confirmPrompt(question: string): Promise<boolean> {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+    });
+  });
+}
+
+export async function handleCacheClear(
+  options: CacheClearOptions = {},
+  _confirm = confirmPrompt,
+): Promise<void> {
+  const info = mpak.bundleCache.getCacheInfo();
+  const entryCount = info.registryBundles.length + info.localBundles.length;
+
+  if (entryCount === 0) {
+    logger.info('Cache is already empty.');
+    return;
+  }
+
+  const sizeStr = formatSize(info.totalBytes);
+  const summary = `${entryCount} bundle(s), ${sizeStr}`;
+
+  if (!options.force) {
+    const ok = await _confirm(`Clear the entire cache (${summary})? [y/N] `);
+    if (!ok) {
+      logger.info('Aborted.');
+      return;
+    }
+  }
+
+  const cacheHome = mpak.bundleCache.cacheHome;
+  if (existsSync(cacheHome)) {
+    rmSync(cacheHome, { recursive: true, force: true });
+  }
+
+  logger.info(`Cleared cache. Freed ${sizeStr}.`);
+}

packages/cli/src/commands/cache/index.ts

@@ -0,0 +1,2 @@
+export { handleCacheInfo } from './info.js';
+export { handleCacheClear } from './clear.js';

packages/cli/src/commands/cache/info.ts

@@ -0,0 +1,55 @@
+import { mpak } from '../../utils/config.js';
+import { formatSize, logger, table } from '../../utils/format.js';
+
+export interface CacheInfoOptions {
+  json?: boolean;
+}
+
+export async function handleCacheInfo(options: CacheInfoOptions = {}): Promise<void> {
+  const info = mpak.bundleCache.getCacheInfo();
+
+  if (options.json) {
+    console.log(JSON.stringify(info, null, 2));
+    return;
+  }
+
+  if (info.registryBundles.length === 0 && info.localBundles.length === 0) {
+    logger.info('Cache is empty.');
+    return;
+  }
+
+  if (info.registryBundles.length > 0) {
+    logger.info('Registry bundles:\n');
+    logger.info(
+      table(
+        ['Bundle', 'Version', 'Pulled', 'Size'],
+        info.registryBundles.map((b) => [
+          b.name,
+          b.version,
+          b.pulledAt.slice(0, 10),
+          formatSize(b.bytes),
+        ]),
+        { rightAlign: [3] },
+      ),
+    );
+    logger.info('');
+  }
+
+  if (info.localBundles.length > 0) {
+    logger.info('Local bundles:\n');
+    logger.info(
+      table(
+        ['Path', 'Extracted', 'Size'],
+        info.localBundles.map((b) => [
+          b.localPath,
+          b.extractedAt.slice(0, 10),
+          formatSize(b.bytes),
+        ]),
+        { rightAlign: [2] },
+      ),
+    );
+    logger.info('');
+  }
+
+  logger.info(`Total: ${formatSize(info.totalBytes)}`);
+}

packages/cli/src/commands/packages/outdated.ts

@@ -24,20 +24,16 @@ export async function getOutdatedBundles(): Promise<OutdatedEntry[]> {
 
   await Promise.all(
     cached.map(async (bundle) => {
-      try {
-        const latest = await mpak.bundleCache.checkForUpdate(bundle.name, { force: true });
-        if (latest) {
-          results.push({
-            name: bundle.name,
-            current: bundle.version,
-            latest,
-            pulledAt: bundle.pulledAt,
-          });
-        }
-      } catch {
-        process.stderr.write(
-          `=> Warning: could not check ${bundle.name} (may have been removed from registry)\n`,
-        );
+      const result = await mpak.bundleCache.checkForUpdate(bundle.name, { force: true });
+      if (result.status === 'update-available') {
+        results.push({
+          name: bundle.name,
+          current: bundle.version,
+          latest: result.latestVersion,
+          pulledAt: bundle.pulledAt,
+        });
+      } else if (result.status === 'check-failed') {
+        process.stderr.write(`=> Warning: could not check ${bundle.name}: ${result.reason}\n`);
       }
     }),
   );

packages/cli/src/commands/packages/pull.ts

@@ -45,6 +45,7 @@ export async function handlePull(packageSpec: string, options: PullOptions = {})
 
     logger.info(`\n=> Downloading to ${outputPath}...`);
     writeFileSync(outputPath, data);
+    await mpak.bundleCache.extractBundle(name, data, metadata);
 
     logger.info(`\n=> Bundle downloaded successfully!`);
     logger.info(`   File: ${outputPath}`);

packages/cli/src/program.ts

@@ -23,6 +23,7 @@ import {
   handleSkillInstall,
   handleSkillList,
 } from "./commands/skills/index.js";
+import { handleCacheInfo, handleCacheClear } from "./commands/cache/index.js";
 
 /**
  * Creates and configures the CLI program
@@ -264,6 +265,28 @@ export function createProgram(): Command {
       await handleConfigClear(packageName, key);
     });
 
+  // ==========================================================================
+  // Cache commands
+  // ==========================================================================
+
+  const cache = program.command("cache").description("Manage the local bundle cache");
+
+  cache
+    .command("info")
+    .description("Show cache contents and disk usage")
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+      await handleCacheInfo(options);
+    });
+
+  cache
+    .command("clear")
+    .description("Delete all cached bundles and free disk space")
+    .option("--force", "Skip confirmation prompt")
+    .action(async (options) => {
+      await handleCacheClear(options);
+    });
+
   // ==========================================================================
   // Shell completion
   // ==========================================================================

packages/cli/tests/bundles/outdated.test.ts

@@ -145,7 +145,7 @@ describe('getOutdatedBundles', () => {
     expect(result[1]!.name).toBe('@scope/zebra');
   });
 
-  it('skips bundles that fail to resolve from registry', async () => {
+  it('warns and skips bundles that fail to resolve from registry', async () => {
     seedCacheEntry(testDir, 'scope-exists', {
       manifest: validManifest('@scope/exists', '1.0.0'),
       metadata: validMetadata('1.0.0'),
@@ -159,9 +159,15 @@ describe('getOutdatedBundles', () => {
       { mpakHome: testDir },
     );
 
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+
     const result = await getOutdatedBundles();
+
     expect(result).toHaveLength(1);
     expect(result[0]!.name).toBe('@scope/exists');
+    expect(stderrSpy).toHaveBeenCalledWith(
+      expect.stringContaining('could not check @scope/deleted'),
+    );
   });
 
   it('ignores TTL and always checks the registry', async () => {

packages/cli/tests/bundles/pull.test.ts

@@ -11,11 +11,13 @@ import { handlePull } from '../../src/commands/packages/pull.js';
 vi.mock('fs', () => ({ writeFileSync: vi.fn() }));
 
 let mockDownloadBundle: ReturnType<typeof vi.fn>;
+let mockExtractBundle: ReturnType<typeof vi.fn>;
 
 vi.mock('../../src/utils/config.js', () => ({
   get mpak() {
     return {
       client: { downloadBundle: mockDownloadBundle } as unknown as MpakClient,
+      bundleCache: { extractBundle: mockExtractBundle },
     };
   },
 }));
@@ -55,6 +57,7 @@ describe('handlePull', () => {
   beforeEach(() => {
     vi.mocked(writeFileSync).mockClear();
     mockDownloadBundle = vi.fn().mockResolvedValue({ data: bundleData, metadata });
+    mockExtractBundle = vi.fn().mockResolvedValue(undefined);
     stdoutSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
     stderrSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
   });
@@ -140,4 +143,5 @@ describe('handlePull', () => {
 
     expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('Bundle not found'));
   });
+
 });

packages/cli/tests/bundles/update.test.ts

@@ -30,6 +30,7 @@ let stdout: string;
 let stderr: string;
 
 beforeEach(() => {
+  vi.clearAllMocks();
   stdout = '';
   stderr = '';
   vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => {
@@ -138,7 +139,9 @@ describe('handleUpdate — bulk update', () => {
       },
     ]);
     mockCheckForUpdate.mockImplementation(async (name: string) => {
-      return name === '@scope/a' ? '2.0.0' : '3.0.0';
+      return name === '@scope/a'
+        ? { status: 'update-available', latestVersion: '2.0.0' }
+        : { status: 'update-available', latestVersion: '3.0.0' };
     });
     mockLoadBundle.mockImplementation(async (name: string) => {
       const versions: Record<string, string> = { '@scope/a': '2.0.0', '@scope/b': '3.0.0' };
@@ -168,7 +171,7 @@ describe('handleUpdate — bulk update', () => {
         cacheDir: '/cache/bad',
       },
     ]);
-    mockCheckForUpdate.mockImplementation(async () => '2.0.0');
+    mockCheckForUpdate.mockResolvedValue({ status: 'update-available', latestVersion: '2.0.0' });
     mockLoadBundle.mockImplementation(async (name: string) => {
       if (name === '@scope/bad') throw new MpakNotFoundError('@scope/bad@latest');
       return { cacheDir: '/cache/good', version: '2.0.0', pulled: true };
@@ -189,7 +192,7 @@ describe('handleUpdate — bulk update', () => {
         cacheDir: '/cache/a',
       },
     ]);
-    mockCheckForUpdate.mockResolvedValue('2.0.0');
+    mockCheckForUpdate.mockResolvedValue({ status: 'update-available', latestVersion: '2.0.0' });
     mockLoadBundle.mockRejectedValue(new MpakNetworkError('timeout'));
 
     await expect(handleUpdate(undefined)).rejects.toThrow('process.exit called');
@@ -198,6 +201,25 @@ describe('handleUpdate — bulk update', () => {
     expect(stderr).toContain('All updates failed');
   });
 
+  it('warns and skips bundles whose update check fails', async () => {
+    mockListCachedBundles.mockReturnValue([
+      {
+        name: '@scope/a',
+        version: '1.0.0',
+        pulledAt: '2025-01-01T00:00:00.000Z',
+        cacheDir: '/cache/a',
+      },
+    ]);
+    mockCheckForUpdate.mockResolvedValue({ status: 'check-failed', reason: 'timeout' });
+
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+
+    await handleUpdate(undefined);
+
+    expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('could not check @scope/a'));
+    expect(mockLoadBundle).not.toHaveBeenCalled();
+  });
+
   it('outputs JSON for bulk update with --json', async () => {
     mockListCachedBundles.mockReturnValue([
       {
@@ -207,7 +229,7 @@ describe('handleUpdate — bulk update', () => {
         cacheDir: '/cache/a',
       },
     ]);
-    mockCheckForUpdate.mockResolvedValue('2.0.0');
+    mockCheckForUpdate.mockResolvedValue({ status: 'update-available', latestVersion: '2.0.0' });
     mockLoadBundle.mockResolvedValue({ cacheDir: '/cache/a', version: '2.0.0', pulled: true });
 
     await handleUpdate(undefined, { json: true });