mcpctl/.taskmaster/tasks/task_102.md

# Task ID: 102

**Title:** Implement mcpctl cache stats Command

**Status:** done

**Dependencies:** 98 ✓

**Priority:** low

**Description:** Add CLI command to show cache statistics including hit rates, total size, and entry counts.

**Details:**

Create `src/cli/src/commands/cache-stats.ts`:

```typescript
import { Command } from 'commander';
import { readdir, stat } from 'fs/promises';
import { join } from 'path';

const CACHE_DIR = join(process.env.HOME ?? '', '.mcpctl', 'cache', 'proxymodel');

export function registerCacheStats(program: Command): void {
  program
    .command('cache stats')
    .description('Show cache statistics')
    .action(async () => {
      try {
        const files = await readdir(CACHE_DIR);
        
        let totalSize = 0;
        let oldest = Date.now();
        let newest = 0;
        
        for (const file of files) {
          const filePath = join(CACHE_DIR, file);
          const stats = await stat(filePath);
          totalSize += stats.size;
          oldest = Math.min(oldest, stats.mtimeMs);
          newest = Math.max(newest, stats.mtimeMs);
        }
        
        console.log(`Entries: ${files.length}`);
        console.log(`Total size: ${formatSize(totalSize)}`);
        console.log(`Oldest entry: ${formatAge(Date.now() - oldest)} ago`);
        console.log(`Newest entry: ${formatAge(Date.now() - newest)} ago`);
        
        // Note: hit rate tracking would require runtime instrumentation
        console.log('\nNote: Hit rate statistics require runtime instrumentation.');
      } catch {
        console.log('No cache data available');
      }
    });
}
```

**Test Strategy:**

CLI test: shows correct stats for populated cache, handles empty cache gracefully, size formatting is correct.