tokenlean 0.2.0 → 0.3.0

package/README.md

@@ -18,7 +18,7 @@ the API surface.
 
 ## The Solution
 
-tokenlean provides **25 specialized CLI tools** that give you (or your AI agent) exactly the information needed - no
+tokenlean provides **26 specialized CLI tools** that give you (or your AI agent) exactly the information needed - no
 more, no less. Each tool is designed to answer a specific question about your codebase with minimal token overhead.
 
 Instead of reading a 500-line file to understand its exports, run `tl-exports` (~50 tokens). Instead of reading all your
@@ -128,6 +128,7 @@ Search and discover code patterns.
 
 | Tool        | Description                    | Example               |
 |-------------|--------------------------------|-----------------------|
+| `tl-cache`  | Manage ripgrep result cache    | `tl-cache stats`      |
 | `tl-config` | Show/manage configuration      | `tl-config --init`    |
 | `tl-prompt` | Generate AI agent instructions | `tl-prompt --minimal` |
 
@@ -190,6 +191,48 @@ Project config overrides global config. Both are optional.
 
 Config values extend built-in defaults (they don't replace them).
 
+## Caching
+
+tokenlean caches expensive ripgrep operations to speed up repeated searches. The cache uses **git-based invalidation** - it automatically invalidates when you make commits or modify files.
+
+```bash
+tl-cache stats      # View cache statistics
+tl-cache clear      # Clear cache for current project
+tl-cache clear-all  # Clear all cached data
+```
+
+Cache is stored in `~/.tokenlean/cache/` and is enabled by default.
+
+### Cache Configuration
+
+```json
+{
+  "cache": {
+    "enabled": true,
+    "ttl": 300,
+    "maxSize": "100MB",
+    "location": null
+  }
+}
+```
+
+| Option     | Default            | Description                                |
+|------------|--------------------|--------------------------------------------|
+| `enabled`  | `true`             | Enable/disable caching                     |
+| `ttl`      | `300`              | Max age in seconds (fallback for non-git)  |
+| `maxSize`  | `"100MB"`          | Max cache size per project                 |
+| `location` | `null`             | Override default `~/.tokenlean/cache`      |
+
+### Disable Caching
+
+```bash
+# Disable for a single command
+TOKENLEAN_CACHE=0 tl-search hooks
+
+# Disable in config
+echo '{"cache":{"enabled":false}}' > .tokenleanrc.json
+```
+
 ## Example Workflows
 
 ### Starting work on an unfamiliar codebase

package/bin/tl-cache.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+/**
+ * tl-cache - Manage tokenlean cache
+ *
+ * View cache statistics and clear cached data.
+ *
+ * Usage: tl-cache [command]
+ */
+
+// Prompt info for tl-prompt
+if (process.argv.includes('--prompt')) {
+  console.log(JSON.stringify({
+    name: 'tl-cache',
+    desc: 'Manage tokenlean cache (stats, clear)',
+    when: 'maintenance',
+    example: 'tl-cache stats'
+  }));
+  process.exit(0);
+}
+
+import {
+  createOutput,
+  parseCommonArgs,
+  COMMON_OPTIONS_HELP
+} from '../src/output.mjs';
+import { findProjectRoot } from '../src/project.mjs';
+import {
+  getCacheConfig,
+  getCacheStats,
+  clearCache,
+  getCacheDir
+} from '../src/cache.mjs';
+
+const HELP = `
+tl-cache - Manage tokenlean cache
+
+Usage: tl-cache <command> [options]
+
+Commands:
+  stats       Show cache statistics (default)
+  clear       Clear cache for current project
+  clear-all   Clear cache for all projects
+
+${COMMON_OPTIONS_HELP}
+
+Examples:
+  tl-cache                   # Show stats for current project
+  tl-cache stats             # Same as above
+  tl-cache clear             # Clear cache for this project
+  tl-cache clear-all         # Clear all cached data
+
+Configuration:
+  Cache can be configured in .tokenleanrc.json:
+  {
+    "cache": {
+      "enabled": true,       // Enable/disable caching
+      "ttl": 300,            // Max age in seconds (for non-git repos)
+      "maxSize": "100MB",    // Max cache size per project
+      "location": null       // Override ~/.tokenlean/cache
+    }
+  }
+
+Environment:
+  TOKENLEAN_CACHE=0          Disable caching for this run
+`;
+
+// ─────────────────────────────────────────────────────────────
+// Commands
+// ─────────────────────────────────────────────────────────────
+
+function showStats(out, projectRoot) {
+  const config = getCacheConfig();
+  const projectStats = getCacheStats(projectRoot);
+  const globalStats = getCacheStats(null);
+
+  out.header('Cache Configuration:');
+  out.add(`  Enabled:    ${config.enabled ? 'yes' : 'no'}`);
+  out.add(`  Location:   ${config.location}`);
+  out.add(`  Max size:   ${projectStats.maxSizeFormatted}`);
+  out.add(`  TTL:        ${config.ttl}s (fallback for non-git repos)`);
+  out.blank();
+
+  out.header('Current Project Cache:');
+  out.add(`  Directory:  ${projectStats.location}`);
+  out.add(`  Entries:    ${projectStats.entries}`);
+  out.add(`  Size:       ${projectStats.sizeFormatted}`);
+  out.blank();
+
+  out.header('Global Cache:');
+  out.add(`  Projects:   ${globalStats.projects}`);
+  out.add(`  Entries:    ${globalStats.totalEntries}`);
+  out.add(`  Total size: ${globalStats.totalSizeFormatted}`);
+  out.blank();
+
+  // Set JSON data
+  out.setData('config', config);
+  out.setData('project', projectStats);
+  out.setData('global', globalStats);
+}
+
+function doClear(out, projectRoot) {
+  const before = getCacheStats(projectRoot);
+  clearCache(projectRoot);
+  const after = getCacheStats(projectRoot);
+
+  out.add(`Cleared ${before.entries} cache entries (${before.sizeFormatted})`);
+  out.blank();
+
+  out.setData('cleared', {
+    entries: before.entries,
+    size: before.size,
+    sizeFormatted: before.sizeFormatted
+  });
+}
+
+function doClearAll(out) {
+  const before = getCacheStats(null);
+  clearCache(null);
+  const after = getCacheStats(null);
+
+  out.add(`Cleared ${before.totalEntries} cache entries across ${before.projects} projects (${before.totalSizeFormatted})`);
+  out.blank();
+
+  out.setData('cleared', {
+    projects: before.projects,
+    entries: before.totalEntries,
+    size: before.totalSize,
+    sizeFormatted: before.totalSizeFormatted
+  });
+}
+
+// ─────────────────────────────────────────────────────────────
+// Main
+// ─────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const options = parseCommonArgs(args);
+
+if (options.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+const command = options.remaining.find(a => !a.startsWith('-')) || 'stats';
+const projectRoot = findProjectRoot();
+const out = createOutput(options);
+
+switch (command) {
+  case 'stats':
+    showStats(out, projectRoot);
+    break;
+
+  case 'clear':
+    doClear(out, projectRoot);
+    break;
+
+  case 'clear-all':
+    doClearAll(out);
+    break;
+
+  default:
+    console.error(`Unknown command: ${command}`);
+    console.log('Use: stats, clear, or clear-all');
+    process.exit(1);
+}
+
+out.print();

package/bin/tl-entry.mjs

@@ -30,6 +30,7 @@ import {
   COMMON_OPTIONS_HELP
 } from '../src/output.mjs';
 import { findProjectRoot } from '../src/project.mjs';
+import { withCache } from '../src/cache.mjs';
 
 const HELP = `
 tl-entry - Find entry points in a codebase
@@ -130,7 +131,12 @@ function findEntryPoints(searchPath, projectRoot, filterType) {
     for (const { pattern, desc } of config.patterns) {
       try {
         const cmd = `rg -n -g "*.{ts,tsx,js,jsx,mjs}" --no-heading -e "${shellEscape(pattern)}" "${shellEscape(searchPath)}" 2>/dev/null || true`;
-        const output = execSync(cmd, { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
+        const cacheKey = { op: 'rg-entry-pattern', pattern, path: searchPath };
+        const output = withCache(
+          cacheKey,
+          () => execSync(cmd, { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 }),
+          { projectRoot }
+        );
 
         for (const line of output.trim().split('\n')) {
           if (!line) continue;

package/bin/tl-impact.mjs

@@ -33,6 +33,7 @@ import {
   COMMON_OPTIONS_HELP
 } from '../src/output.mjs';
 import { findProjectRoot, categorizeFile } from '../src/project.mjs';
+import { withCache } from '../src/cache.mjs';
 
 const HELP = `
 tl-impact - Analyze the blast radius of changing a file
@@ -79,8 +80,15 @@ function findDirectImporters(filePath, projectRoot) {
   const patterns = searchTerms.map(t => `-e "${rgEscape(t)}"`).join(' ');
 
   try {
-    const rgCommand = `rg -l --type-add 'code:*.{js,jsx,ts,tsx,mjs,mts,cjs}' -t code ${patterns} "${projectRoot}" 2>/dev/null || true`;
-    const result = execSync(rgCommand, { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
+    const cacheKey = { op: 'rg-find-candidates', terms: searchTerms.sort() };
+    const result = withCache(
+      cacheKey,
+      () => {
+        const rgCommand = `rg -l --type-add 'code:*.{js,jsx,ts,tsx,mjs,mts,cjs}' -t code ${patterns} "${projectRoot}" 2>/dev/null || true`;
+        return execSync(rgCommand, { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
+      },
+      { projectRoot }
+    );
     const candidates = result.trim().split('\n').filter(Boolean);
 
     for (const candidate of candidates) {

package/bin/tl-related.mjs

@@ -32,6 +32,7 @@ import {
   COMMON_OPTIONS_HELP
 } from '../src/output.mjs';
 import { findProjectRoot } from '../src/project.mjs';
+import { withCache } from '../src/cache.mjs';
 
 const HELP = `
 tl-related - Find related files (tests, types, usages)
@@ -120,11 +121,16 @@ function findImporters(filePath, projectRoot) {
   const name = basename(filePath, extname(filePath));
   const importers = new Set();
 
-  // Search for files that might import this module
+  // Search for files that might import this module (with caching)
   try {
-    const result = execSync(
-      `rg -l -g "*.{js,mjs,ts,tsx,jsx}" -e "${shellEscape(name)}" "${shellEscape(projectRoot)}" 2>/dev/null || true`,
-      { encoding: 'utf-8', maxBuffer: 5 * 1024 * 1024 }
+    const cacheKey = { op: 'rg-find-importers', module: name, glob: '*.{js,mjs,ts,tsx,jsx}' };
+    const result = withCache(
+      cacheKey,
+      () => execSync(
+        `rg -l -g "*.{js,mjs,ts,tsx,jsx}" -e "${shellEscape(name)}" "${shellEscape(projectRoot)}" 2>/dev/null || true`,
+        { encoding: 'utf-8', maxBuffer: 5 * 1024 * 1024 }
+      ),
+      { projectRoot }
     );
 
     for (const line of result.trim().split('\n')) {

package/bin/tl-search.mjs

@@ -28,6 +28,7 @@ import {
   COMMON_OPTIONS_HELP
 } from '../src/output.mjs';
 import { loadConfig, CONFIG_FILENAME } from '../src/config.mjs';
+import { withCache } from '../src/cache.mjs';
 
 const HELP = `
 tl-search - Run pre-defined search patterns
@@ -165,10 +166,15 @@ function runSearch(name, config, rootDir, jsonMode) {
 
   if (jsonMode) {
     try {
-      const result = execSync(`rg ${args.map(a => `"${a}"`).join(' ')} 2>/dev/null || true`, {
-        encoding: 'utf-8',
-        maxBuffer: 10 * 1024 * 1024
-      });
+      const cacheKey = { op: 'rg-search-pattern', name, pattern: config.pattern, glob: config.glob };
+      const result = withCache(
+        cacheKey,
+        () => execSync(`rg ${args.map(a => `"${a}"`).join(' ')} 2>/dev/null || true`, {
+          encoding: 'utf-8',
+          maxBuffer: 10 * 1024 * 1024
+        }),
+        { projectRoot: rootDir }
+      );
       const matches = result.trim().split('\n')
         .filter(line => line.startsWith('{'))
         .map(line => {

package/bin/tl-todo.mjs

@@ -32,6 +32,7 @@ import {
   COMMON_OPTIONS_HELP
 } from '../src/output.mjs';
 import { findProjectRoot, shouldSkip, SKIP_DIRS } from '../src/project.mjs';
+import { withCache } from '../src/cache.mjs';
 
 const HELP = `
 tl-todo - Extract TODOs, FIXMEs, and other markers from codebase
@@ -102,7 +103,13 @@ function findTodos(searchPath, projectRoot) {
     // Require : or ( after marker to avoid false positives like "Todo Extraction"
     const commentPattern = `(${commentPrefixes.join('|')})\\s*(${markerPattern})[:(]`;
     const cmd = `rg -n --no-heading -i "${commentPattern}" "${shellEscape(searchPath)}" ${excludes} 2>/dev/null || true`;
-    const output = execSync(cmd, { encoding: 'utf-8', maxBuffer: 50 * 1024 * 1024 });
+
+    const cacheKey = { op: 'rg-todo-markers', pattern: commentPattern, path: searchPath };
+    const output = withCache(
+      cacheKey,
+      () => execSync(cmd, { encoding: 'utf-8', maxBuffer: 50 * 1024 * 1024 }),
+      { projectRoot }
+    );
 
     if (!output.trim()) {
       return todos;

package/bin/tl-unused.mjs

@@ -29,6 +29,7 @@ import {
   COMMON_OPTIONS_HELP
 } from '../src/output.mjs';
 import { findProjectRoot, shouldSkip, isCodeFile } from '../src/project.mjs';
+import { withCache } from '../src/cache.mjs';
 
 const HELP = `
 tl-unused - Find potentially unused exports and unreferenced files
@@ -221,26 +222,35 @@ function extractImports(content) {
 }
 
 function findReferencesWithGrep(name, projectRoot, excludeFile) {
-  // Use ripgrep for fast reference counting
-  const args = [
-    '-l',  // Files only
-    '--type', 'js',
-    '--type', 'ts',
-    '-w',  // Word boundary
-    name,
-    '.'
-  ];
-
-  const result = spawnSync('rg', args, {
-    cwd: projectRoot,
-    encoding: 'utf-8'
-  });
-
-  if (result.error || result.status !== 0) {
-    return 0;
-  }
+  // Use ripgrep for fast reference counting (with caching)
+  const cacheKey = { op: 'rg-ref-count', name, types: 'js,ts' };
+
+  const files = withCache(
+    cacheKey,
+    () => {
+      const args = [
+        '-l',  // Files only
+        '--type', 'js',
+        '--type', 'ts',
+        '-w',  // Word boundary
+        name,
+        '.'
+      ];
+
+      const result = spawnSync('rg', args, {
+        cwd: projectRoot,
+        encoding: 'utf-8'
+      });
+
+      if (result.error || result.status !== 0) {
+        return [];
+      }
+
+      return result.stdout.trim().split('\n').filter(Boolean);
+    },
+    { projectRoot }
+  );
 
-  const files = result.stdout.trim().split('\n').filter(Boolean);
   // Exclude the file that exports it
   const relExclude = relative(projectRoot, excludeFile);
   const otherFiles = files.filter(f => f !== relExclude && !f.includes(relExclude));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenlean",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Lean CLI tools for AI agents and developers - reduce context, save tokens",
   "type": "module",
   "engines": {
@@ -22,6 +22,7 @@
   "bin": {
     "tl-api": "./bin/tl-api.mjs",
     "tl-blame": "./bin/tl-blame.mjs",
+    "tl-cache": "./bin/tl-cache.mjs",
     "tl-config": "./bin/tl-config.mjs",
     "tl-context": "./bin/tl-context.mjs",
     "tl-coverage": "./bin/tl-coverage.mjs",

package/src/cache.mjs

@@ -0,0 +1,493 @@
+/**
+ * Shared caching system for tokenlean CLI tools
+ *
+ * Provides disk-based caching with git-based invalidation for expensive
+ * ripgrep operations. Falls back to TTL-based invalidation when not in a git repo.
+ *
+ * Cache storage: ~/.tokenlean/cache/<project-hash>/<key-hash>.json
+ *
+ * Usage:
+ *   // High-level API (preferred)
+ *   const result = withCache(
+ *     { op: 'rg-search', pattern: 'useState', glob: '*.tsx' },
+ *     () => execSync('rg ...'),
+ *     { projectRoot }
+ *   );
+ *
+ *   // Low-level API
+ *   let data = getCached(key, projectRoot);
+ *   if (!data) {
+ *     data = computeExpensiveResult();
+ *     setCached(key, data, projectRoot);
+ *   }
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync, unlinkSync, rmSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { execSync } from 'child_process';
+import { createHash } from 'crypto';
+import { loadConfig } from './config.mjs';
+
+// ─────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────
+
+const DEFAULT_CACHE_DIR = join(homedir(), '.tokenlean', 'cache');
+const DEFAULT_TTL = 300; // 5 minutes fallback for non-git repos
+const DEFAULT_MAX_SIZE = 100 * 1024 * 1024; // 100MB
+
+// ─────────────────────────────────────────────────────────────
+// Configuration
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Get cache configuration from config system
+ */
+export function getCacheConfig() {
+  const { config } = loadConfig();
+  const cacheConfig = config.cache || {};
+
+  return {
+    enabled: cacheConfig.enabled !== false && process.env.TOKENLEAN_CACHE !== '0',
+    ttl: cacheConfig.ttl ?? DEFAULT_TTL,
+    maxSize: parseSize(cacheConfig.maxSize) ?? DEFAULT_MAX_SIZE,
+    location: cacheConfig.location ?? DEFAULT_CACHE_DIR
+  };
+}
+
+/**
+ * Parse size string like '100MB' to bytes
+ */
+function parseSize(size) {
+  if (typeof size === 'number') return size;
+  if (typeof size !== 'string') return null;
+
+  const match = size.match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB)?$/i);
+  if (!match) return null;
+
+  const num = parseFloat(match[1]);
+  const unit = (match[2] || 'B').toUpperCase();
+
+  const multipliers = {
+    'B': 1,
+    'KB': 1024,
+    'MB': 1024 * 1024,
+    'GB': 1024 * 1024 * 1024
+  };
+
+  return Math.floor(num * multipliers[unit]);
+}
+
+// ─────────────────────────────────────────────────────────────
+// Hashing Utilities
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Create a short hash from any value
+ */
+function hash(value) {
+  const str = typeof value === 'string' ? value : JSON.stringify(value);
+  return createHash('sha256').update(str).digest('hex').slice(0, 16);
+}
+
+/**
+ * Get hash of project root path for cache directory
+ */
+function getProjectHash(projectRoot) {
+  return hash(projectRoot);
+}
+
+/**
+ * Get cache key hash from operation key object
+ */
+function getCacheKeyHash(key) {
+  return hash(key);
+}
+
+// ─────────────────────────────────────────────────────────────
+// Git State Detection
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Check if directory is a git repository
+ */
+function isGitRepo(dir) {
+  try {
+    execSync('git rev-parse --git-dir', { cwd: dir, stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get current git state (HEAD commit + dirty files)
+ * Returns null if not in a git repo
+ */
+export function getGitState(projectRoot) {
+  if (!isGitRepo(projectRoot)) {
+    return null;
+  }
+
+  try {
+    // Get HEAD commit
+    const head = execSync('git rev-parse HEAD', {
+      cwd: projectRoot,
+      encoding: 'utf-8'
+    }).trim();
+
+    // Get list of modified/untracked files (sorted for consistency)
+    const status = execSync('git status --porcelain', {
+      cwd: projectRoot,
+      encoding: 'utf-8'
+    });
+
+    const dirtyFiles = status
+      .split('\n')
+      .filter(line => line.trim())
+      .map(line => line.slice(3)) // Remove status prefix
+      .sort();
+
+    return {
+      head,
+      dirtyFiles
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if git state matches stored state
+ */
+function gitStateMatches(stored, current) {
+  if (!stored || !current) return false;
+  if (stored.head !== current.head) return false;
+  if (stored.dirtyFiles.length !== current.dirtyFiles.length) return false;
+
+  for (let i = 0; i < stored.dirtyFiles.length; i++) {
+    if (stored.dirtyFiles[i] !== current.dirtyFiles[i]) return false;
+  }
+
+  return true;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Cache Directory Management
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Get or create cache directory for a project
+ */
+export function getCacheDir(projectRoot) {
+  const config = getCacheConfig();
+  const projectHash = getProjectHash(projectRoot);
+  const cacheDir = join(config.location, projectHash);
+
+  if (!existsSync(cacheDir)) {
+    mkdirSync(cacheDir, { recursive: true });
+  }
+
+  return cacheDir;
+}
+
+/**
+ * Get cache file path for a key
+ */
+function getCacheFilePath(key, projectRoot) {
+  const cacheDir = getCacheDir(projectRoot);
+  const keyHash = getCacheKeyHash(key);
+  return join(cacheDir, `${keyHash}.json`);
+}
+
+// ─────────────────────────────────────────────────────────────
+// Cache Size Management
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Get total size of cache directory in bytes
+ */
+function getCacheDirSize(cacheDir) {
+  if (!existsSync(cacheDir)) return 0;
+
+  let total = 0;
+  try {
+    const files = readdirSync(cacheDir);
+    for (const file of files) {
+      try {
+        const stat = statSync(join(cacheDir, file));
+        if (stat.isFile()) {
+          total += stat.size;
+        }
+      } catch { /* skip unreadable files */ }
+    }
+  } catch { /* directory read error */ }
+
+  return total;
+}
+
+/**
+ * Get all cache entries with metadata
+ */
+function getCacheEntries(cacheDir) {
+  if (!existsSync(cacheDir)) return [];
+
+  const entries = [];
+  try {
+    const files = readdirSync(cacheDir).filter(f => f.endsWith('.json'));
+    for (const file of files) {
+      try {
+        const filePath = join(cacheDir, file);
+        const stat = statSync(filePath);
+        entries.push({
+          path: filePath,
+          size: stat.size,
+          mtime: stat.mtime.getTime()
+        });
+      } catch { /* skip unreadable files */ }
+    }
+  } catch { /* directory read error */ }
+
+  return entries;
+}
+
+/**
+ * Remove oldest cache entries until under maxSize
+ */
+function enforceMaxSize(projectRoot) {
+  const config = getCacheConfig();
+  const cacheDir = getCacheDir(projectRoot);
+
+  const entries = getCacheEntries(cacheDir);
+  let totalSize = entries.reduce((sum, e) => sum + e.size, 0);
+
+  if (totalSize <= config.maxSize) return;
+
+  // Sort by modification time (oldest first)
+  entries.sort((a, b) => a.mtime - b.mtime);
+
+  // Remove oldest entries until under limit
+  for (const entry of entries) {
+    if (totalSize <= config.maxSize) break;
+
+    try {
+      unlinkSync(entry.path);
+      totalSize -= entry.size;
+    } catch { /* skip if can't delete */ }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// Low-Level Cache API
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Read from cache if valid
+ * Returns cached data or null if cache miss/invalid
+ */
+export function getCached(key, projectRoot) {
+  const config = getCacheConfig();
+  if (!config.enabled) return null;
+
+  const filePath = getCacheFilePath(key, projectRoot);
+  if (!existsSync(filePath)) return null;
+
+  try {
+    const cached = JSON.parse(readFileSync(filePath, 'utf-8'));
+
+    // Git-based invalidation
+    const currentGitState = getGitState(projectRoot);
+    if (currentGitState) {
+      // If we have git state, use it for validation
+      if (!gitStateMatches(cached.gitState, currentGitState)) {
+        return null;
+      }
+    } else {
+      // Fall back to TTL-based invalidation
+      const age = (Date.now() - cached.timestamp) / 1000;
+      if (age > config.ttl) {
+        return null;
+      }
+    }
+
+    return cached.data;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write to cache with git state
+ */
+export function setCached(key, data, projectRoot) {
+  const config = getCacheConfig();
+  if (!config.enabled) return;
+
+  const filePath = getCacheFilePath(key, projectRoot);
+  const gitState = getGitState(projectRoot);
+
+  const cacheEntry = {
+    data,
+    gitState,
+    timestamp: Date.now(),
+    key: typeof key === 'string' ? key : JSON.stringify(key)
+  };
+
+  try {
+    // Ensure directory exists
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    writeFileSync(filePath, JSON.stringify(cacheEntry));
+
+    // Enforce size limit
+    enforceMaxSize(projectRoot);
+  } catch {
+    // Silently fail - caching is best-effort
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// High-Level Cache API
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Execute function with caching
+ * Preferred API for caching expensive operations
+ *
+ * @param {Object|string} key - Cache key (operation + args)
+ * @param {Function} fn - Function to execute if cache miss
+ * @param {Object} options - Options including projectRoot
+ * @returns {*} Cached or computed result
+ */
+export function withCache(key, fn, options = {}) {
+  const { projectRoot = process.cwd() } = options;
+
+  // Check cache first
+  const cached = getCached(key, projectRoot);
+  if (cached !== null) {
+    return cached;
+  }
+
+  // Execute function and cache result
+  const result = fn();
+  setCached(key, result, projectRoot);
+
+  return result;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Cache Management Utilities
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Clear cache for a project or all projects
+ * @param {string|null} projectRoot - Project to clear, or null for all
+ */
+export function clearCache(projectRoot = null) {
+  const config = getCacheConfig();
+
+  if (projectRoot) {
+    // Clear single project cache
+    const cacheDir = getCacheDir(projectRoot);
+    if (existsSync(cacheDir)) {
+      try {
+        rmSync(cacheDir, { recursive: true });
+      } catch { /* ignore errors */ }
+    }
+  } else {
+    // Clear all caches
+    if (existsSync(config.location)) {
+      try {
+        rmSync(config.location, { recursive: true });
+      } catch { /* ignore errors */ }
+    }
+  }
+}
+
+/**
+ * Get cache statistics
+ */
+export function getCacheStats(projectRoot = null) {
+  const config = getCacheConfig();
+
+  if (projectRoot) {
+    // Stats for single project
+    const cacheDir = getCacheDir(projectRoot);
+    const entries = getCacheEntries(cacheDir);
+    const totalSize = entries.reduce((sum, e) => sum + e.size, 0);
+
+    return {
+      enabled: config.enabled,
+      location: cacheDir,
+      entries: entries.length,
+      size: totalSize,
+      sizeFormatted: formatSize(totalSize),
+      maxSize: config.maxSize,
+      maxSizeFormatted: formatSize(config.maxSize)
+    };
+  }
+
+  // Stats for all projects
+  if (!existsSync(config.location)) {
+    return {
+      enabled: config.enabled,
+      location: config.location,
+      projects: 0,
+      totalEntries: 0,
+      totalSize: 0,
+      totalSizeFormatted: '0 B',
+      maxSize: config.maxSize,
+      maxSizeFormatted: formatSize(config.maxSize)
+    };
+  }
+
+  let totalEntries = 0;
+  let totalSize = 0;
+  let projects = 0;
+
+  try {
+    const projectDirs = readdirSync(config.location);
+    for (const dir of projectDirs) {
+      const projectDir = join(config.location, dir);
+      try {
+        if (statSync(projectDir).isDirectory()) {
+          projects++;
+          const entries = getCacheEntries(projectDir);
+          totalEntries += entries.length;
+          totalSize += entries.reduce((sum, e) => sum + e.size, 0);
+        }
+      } catch { /* skip */ }
+    }
+  } catch { /* location doesn't exist yet */ }
+
+  return {
+    enabled: config.enabled,
+    location: config.location,
+    projects,
+    totalEntries,
+    totalSize,
+    totalSizeFormatted: formatSize(totalSize),
+    maxSize: config.maxSize,
+    maxSizeFormatted: formatSize(config.maxSize)
+  };
+}
+
+/**
+ * Format bytes to human readable
+ */
+function formatSize(bytes) {
+  if (bytes >= 1024 * 1024 * 1024) {
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+  }
+  if (bytes >= 1024 * 1024) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  }
+  if (bytes >= 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
+  return `${bytes} B`;
+}

package/src/config.mjs

@@ -81,6 +81,12 @@ const DEFAULT_CONFIG = {
   },
   impact: {
     depth: 2
+  },
+  cache: {
+    enabled: true,           // Enable/disable caching
+    ttl: 300,                // Max age in seconds (fallback for non-git)
+    maxSize: '100MB',        // Max cache directory size
+    location: null           // Override ~/.tokenlean/cache
   }
 };