@delegance/claude-autopilot 1.0.0-alpha.4

package/src/cli/init.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import * as fs from 'node:fs';
+import * as fsAsync from 'node:fs/promises';
+import * as path from 'node:path';
+import * as readline from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import { stdin as input, stdout as output } from 'node:process';
+
+const PRESET_DESCRIPTIONS: Record<string, string> = {
+  'nextjs-supabase': 'Next.js App Router + Supabase (Postgres + RLS)',
+  't3': 'T3 Stack (Next.js + tRPC + Prisma + NextAuth)',
+  'rails-postgres': 'Ruby on Rails 7 + PostgreSQL',
+  'python-fastapi': 'Python FastAPI + SQLAlchemy + Alembic',
+  'go': 'Go + PostgreSQL (pgx/v5)',
+};
+
+const PRESET_NAMES = Object.keys(PRESET_DESCRIPTIONS);
+
+export async function runInit(cwd: string = process.cwd()): Promise<void> {
+  const dest = path.join(cwd, 'autopilot.config.yaml');
+
+  if (fs.existsSync(dest)) {
+    console.error(`\x1b[33m[init] autopilot.config.yaml already exists — remove it first to re-init\x1b[0m`);
+    process.exit(1);
+  }
+
+  console.log('\n\x1b[1m[autopilot init] Choose a preset:\x1b[0m\n');
+  PRESET_NAMES.forEach((name, i) => {
+    console.log(`  ${i + 1}. ${name.padEnd(22)} ${PRESET_DESCRIPTIONS[name]}`);
+  });
+  console.log('');
+
+  const rl = readline.createInterface({ input, output });
+  let choice: number;
+  try {
+    const answer = await rl.question('  Enter number (or preset name): ');
+    rl.close();
+    const trimmed = answer.trim();
+    const byName = PRESET_NAMES.indexOf(trimmed);
+    if (byName >= 0) {
+      choice = byName;
+    } else {
+      const n = parseInt(trimmed, 10);
+      if (isNaN(n) || n < 1 || n > PRESET_NAMES.length) {
+        console.error(`\x1b[31m[init] Invalid selection: "${trimmed}"\x1b[0m`);
+        process.exit(1);
+      }
+      choice = n - 1;
+    }
+  } catch {
+    rl.close();
+    process.exit(0);
+  }
+
+  const presetName = PRESET_NAMES[choice]!;
+  const presetConfigPath = findPresetConfig(presetName);
+  if (!presetConfigPath) {
+    console.error(`\x1b[31m[init] Preset config not found for: ${presetName}\x1b[0m`);
+    console.error(`       Looked in: ${presetSearchPaths(presetName).join(', ')}`);
+    process.exit(1);
+  }
+
+  const presetContent = await fsAsync.readFile(presetConfigPath, 'utf8');
+  await fsAsync.writeFile(dest, presetContent, 'utf8');
+
+  console.log(`\n\x1b[32m✓\x1b[0m  Created autopilot.config.yaml from preset \x1b[1m${presetName}\x1b[0m`);
+  console.log('\nNext steps:');
+  console.log('  1. Review autopilot.config.yaml and adjust testCommand / protectedPaths');
+  console.log('  2. Set OPENAI_API_KEY in your .env file for Codex review');
+  console.log('  3. Run: npx autopilot run\n');
+}
+
+function presetSearchPaths(name: string): string[] {
+  // fileURLToPath handles encoded chars and Windows drive letters safely
+  const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+  return [
+    path.join(pkgRoot, 'presets', name, 'autopilot.config.yaml'),
+    path.join(process.cwd(), 'presets', name, 'autopilot.config.yaml'),
+    path.join(process.cwd(), 'node_modules', '@delegance', 'claude-autopilot', 'presets', name, 'autopilot.config.yaml'),
+  ];
+}
+
+function findPresetConfig(name: string): string | null {
+  for (const p of presetSearchPaths(name)) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}

package/src/cli/preflight.ts

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { runSafe } from '../core/shell.ts';
+
+const PASS = '\x1b[32m✓\x1b[0m';
+const FAIL = '\x1b[31m✗\x1b[0m';
+const WARN = '\x1b[33m!\x1b[0m';
+
+const ENV_CANDIDATES = ['.env.local', '.env.dev', '.env.development', '.env'];
+
+interface Check {
+  name: string;
+  result: 'pass' | 'fail' | 'warn';
+  message?: string;
+}
+
+function loadEnvFile(filePath: string): Record<string, string> {
+  const vars: Record<string, string> = {};
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const eq = trimmed.indexOf('=');
+      if (eq < 0) continue;
+      vars[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim().replace(/^['"]|['"]$/g, '');
+    }
+  } catch { /* ignore */ }
+  return vars;
+}
+
+const checks: Check[] = [];
+
+// 1. Node version
+const nodeVersion = process.version;
+const nodeMajor = parseInt(nodeVersion.slice(1).split('.')[0]!, 10);
+checks.push({
+  name: `Node.js ${nodeVersion}`,
+  result: nodeMajor >= 22 ? 'pass' : 'fail',
+  message: nodeMajor < 22 ? `Node 22+ required — current: ${nodeVersion}. Install via nvm: nvm install 22` : undefined,
+});
+
+// 2. tsx available
+const localTsx = path.join(process.cwd(), 'node_modules', '.bin', 'tsx');
+const tsxVersion = fs.existsSync(localTsx)
+  ? runSafe(localTsx, ['--version'])
+  : runSafe('tsx', ['--version']);
+checks.push({
+  name: 'tsx available',
+  result: tsxVersion ? 'pass' : 'fail',
+  message: !tsxVersion ? 'tsx not found — run: npm install --save-dev tsx' : undefined,
+});
+
+// 3. gh CLI authenticated
+const ghAuth = runSafe('gh', ['auth', 'status']);
+checks.push({
+  name: 'gh CLI authenticated',
+  result: ghAuth !== null ? 'pass' : 'fail',
+  message: ghAuth === null ? 'gh CLI not authenticated — run: gh auth login' : undefined,
+});
+
+// 4. autopilot.config.yaml in cwd
+const configYaml = path.join(process.cwd(), 'autopilot.config.yaml');
+checks.push({
+  name: 'autopilot.config.yaml',
+  result: fs.existsSync(configYaml) ? 'pass' : 'warn',
+  message: !fs.existsSync(configYaml)
+    ? 'autopilot.config.yaml not found in current directory — copy from a preset: presets/nextjs-supabase/autopilot.config.yaml'
+    : undefined,
+});
+
+// 5. Local env file exists
+const envFile = ENV_CANDIDATES.find(f => fs.existsSync(f));
+checks.push({
+  name: `Local env file (${envFile ?? 'none found'})`,
+  result: envFile ? 'pass' : 'warn',
+  message: !envFile
+    ? `No env file found. Looked for: ${ENV_CANDIDATES.join(', ')}. Create one with your OPENAI_API_KEY.`
+    : undefined,
+});
+
+// 6. OPENAI_API_KEY set
+const envVars = envFile ? loadEnvFile(envFile) : {};
+const hasOpenAI = !!process.env.OPENAI_API_KEY || !!envVars['OPENAI_API_KEY'];
+checks.push({
+  name: 'OPENAI_API_KEY',
+  result: hasOpenAI ? 'pass' : 'warn',
+  message: !hasOpenAI
+    ? `OPENAI_API_KEY not set — Codex review steps will be skipped`
+    : undefined,
+});
+
+// 7. claude CLI available
+const claudeVersion = runSafe('claude', ['--version']);
+checks.push({
+  name: 'claude CLI',
+  result: claudeVersion ? 'pass' : 'fail',
+  message: !claudeVersion
+    ? 'claude CLI not found — required for autofix. Install Claude Code: https://claude.ai/claude-code'
+    : undefined,
+});
+
+// 8. git user config
+const gitName = runSafe('git', ['config', 'user.name']);
+const gitEmail = runSafe('git', ['config', 'user.email']);
+const gitConfigOk = !!(gitName?.trim()) && !!(gitEmail?.trim());
+checks.push({
+  name: 'git user config',
+  result: gitConfigOk ? 'pass' : 'warn',
+  message: !gitConfigOk
+    ? 'git user.name / user.email not set — commits will fail.'
+    : undefined,
+});
+
+// 9. superpowers plugin
+const home = process.env.HOME ?? '';
+const superpowersPaths = [
+  path.join(home, '.claude', 'plugins', 'cache', 'claude-plugins-official', 'superpowers'),
+  path.join(home, '.claude', 'plugins', 'cache', 'superpowers-marketplace', 'superpowers'),
+  path.join(home, '.claude', 'plugins', 'superpowers'),
+];
+const superpowersOk = superpowersPaths.some(p => fs.existsSync(p));
+checks.push({
+  name: 'superpowers plugin',
+  result: superpowersOk ? 'pass' : 'warn',
+  message: !superpowersOk
+    ? 'superpowers plugin not detected — install: /plugin install superpowers@claude-plugins-official'
+    : undefined,
+});
+
+// Print results
+console.log('\n\x1b[1m[preflight] Autopilot prerequisite check\x1b[0m\n');
+let failures = 0;
+let warnings = 0;
+for (const check of checks) {
+  const icon = check.result === 'pass' ? PASS : check.result === 'warn' ? WARN : FAIL;
+  console.log(`  ${icon}  ${check.name}`);
+  if (check.message) {
+    console.log(`       \x1b[2m${check.message}\x1b[0m`);
+  }
+  if (check.result === 'fail') failures++;
+  if (check.result === 'warn') warnings++;
+}
+
+console.log('');
+if (failures > 0) {
+  console.log(`\x1b[31m[preflight] ${failures} check(s) failed — fix before running /autopilot\x1b[0m\n`);
+  process.exit(1);
+} else if (warnings > 0) {
+  console.log(`\x1b[33m[preflight] ${warnings} warning(s) — pipeline will run but some steps may be degraded\x1b[0m\n`);
+} else {
+  console.log(`\x1b[32m[preflight] All checks passed\x1b[0m\n`);
+}

package/src/cli/run.ts

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { loadConfig } from '../core/config/loader.ts';
+import { resolvePreset } from '../core/config/preset-resolver.ts';
+import { mergeConfigs } from '../core/config/preset-resolver.ts';
+import { loadAdapter } from '../adapters/loader.ts';
+import { runAutopilot } from '../core/pipeline/run.ts';
+import { resolveGitTouchedFiles } from '../core/git/touched-files.ts';
+import type { RunInput } from '../core/pipeline/run.ts';
+import type { ReviewEngine } from '../adapters/review-engine/types.ts';
+import type { AutopilotConfig } from '../core/config/types.ts';
+
+const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+};
+
+function fmt(color: keyof typeof C, text: string): string {
+  return `${C[color]}${text}${C.reset}`;
+}
+
+export interface RunCommandOptions {
+  cwd?: string;
+  configPath?: string;
+  base?: string;       // git base ref (default HEAD~1)
+  files?: string[];    // explicit file list (skips git detection)
+  dryRun?: boolean;    // skip review, print what would run
+}
+
+/**
+ * Returns an exit code (0 = pass/warn, 1 = fail/error).
+ * Never calls process.exit directly — caller decides when to exit.
+ */
+export async function runCommand(options: RunCommandOptions = {}): Promise<number> {
+  const cwd = options.cwd ?? process.cwd();
+  const configPath = options.configPath ?? path.join(cwd, 'autopilot.config.yaml');
+
+  if (!fs.existsSync(configPath)) {
+    console.error(fmt('red', `[run] autopilot.config.yaml not found at ${configPath}`));
+    console.error(fmt('dim', '      Run: npx autopilot init'));
+    return 1;
+  }
+
+  // Load + merge config
+  let config: AutopilotConfig;
+  try {
+    const userConfig = await loadConfig(configPath);
+    if (userConfig.preset) {
+      const preset = await resolvePreset(userConfig.preset);
+      config = mergeConfigs(preset.config, userConfig);
+    } else {
+      config = userConfig;
+    }
+  } catch (err) {
+    console.error(fmt('red', `[run] Config error: ${err instanceof Error ? err.message : String(err)}`));
+    return 1;
+  }
+
+  // Resolve touched files
+  const touchedFiles = options.files ?? resolveGitTouchedFiles({ cwd, base: options.base });
+  if (touchedFiles.length === 0) {
+    console.log(fmt('yellow', '[run] No changed files detected — nothing to review.'));
+    console.log(fmt('dim', '      Pass --base <ref> to compare against a different branch/commit.'));
+    return 0;
+  }
+
+  console.log(`\n${fmt('bold', '[autopilot run]')} ${fmt('dim', configPath)}`);
+  console.log(`${fmt('dim', `  ${touchedFiles.length} changed file(s):`)} ${touchedFiles.slice(0, 5).join(', ')}${touchedFiles.length > 5 ? ` … +${touchedFiles.length - 5} more` : ''}`);
+
+  if (options.dryRun) {
+    console.log(fmt('yellow', '\n[run] Dry run — skipping pipeline execution.\n'));
+    return 0;
+  }
+
+  // Load review engine (optional — skip if no OPENAI_API_KEY or not configured)
+  let reviewEngine: ReviewEngine | undefined;
+  if (config.reviewEngine) {
+    const ref = typeof config.reviewEngine === 'string' ? config.reviewEngine : config.reviewEngine.adapter;
+    const hasKey = !!(process.env.OPENAI_API_KEY);
+    if (!hasKey && ref === 'codex') {
+      console.log(fmt('yellow', '\n  [run] OPENAI_API_KEY not set — Codex review step will be skipped'));
+    } else {
+      try {
+        reviewEngine = await loadAdapter<ReviewEngine>({
+          point: 'review-engine',
+          ref,
+          options: typeof config.reviewEngine === 'string' ? undefined : config.reviewEngine.options,
+        });
+      } catch (err) {
+        console.error(fmt('yellow', `  [run] Could not load review engine (${ref}): ${err instanceof Error ? err.message : String(err)} — skipping`));
+      }
+    }
+  }
+
+  // Execute pipeline
+  const input: RunInput = {
+    touchedFiles,
+    config,
+    reviewEngine,
+    cwd,
+  };
+
+  console.log('');
+  const result = await runAutopilot(input);
+
+  // Print phase summaries
+  for (const phase of result.phases) {
+    const icon = phase.status === 'pass' ? fmt('green', '✓') :
+                 phase.status === 'skip' ? fmt('dim', '–') :
+                 phase.status === 'warn' ? fmt('yellow', '!') : fmt('red', '✗');
+    const phaseLabel = phase.phase.padEnd(14);
+    const findingCount = phase.findings.length;
+    const extra = findingCount > 0 ? fmt('dim', ` (${findingCount} finding${findingCount !== 1 ? 's' : ''})`) : '';
+    const dur = 'durationMs' in phase ? fmt('dim', ` ${phase.durationMs}ms`) : '';
+    console.log(`  ${icon}  ${phaseLabel}${extra}${dur}`);
+
+    // Print critical/warning findings inline
+    for (const f of phase.findings) {
+      if (f.severity === 'critical' || f.severity === 'warning') {
+        const sev = f.severity === 'critical' ? fmt('red', 'CRITICAL') : fmt('yellow', 'WARNING ');
+        console.log(`       ${sev}  ${f.file}${f.line ? `:${f.line}` : ''} — ${f.message}`);
+        if (f.suggestion) console.log(fmt('dim', `                ${f.suggestion}`));
+      }
+    }
+  }
+
+  // Cost summary
+  if (result.totalCostUSD !== undefined) {
+    console.log(`\n  ${fmt('dim', `cost: $${result.totalCostUSD.toFixed(4)}`)}  ${fmt('dim', `${result.durationMs}ms total`)}`);
+  } else {
+    console.log(`\n  ${fmt('dim', `${result.durationMs}ms total`)}`);
+  }
+
+  // Final verdict
+  console.log('');
+  if (result.status === 'pass') {
+    console.log(fmt('green', '[run] ✓ All phases passed\n'));
+    return 0;
+  } else if (result.status === 'warn') {
+    console.log(fmt('yellow', '[run] ! Passed with warnings\n'));
+    return 0;
+  } else {
+    console.log(fmt('red', '[run] ✗ Pipeline failed — see findings above\n'));
+    return 1;
+  }
+}

package/src/cli/watch.ts

@@ -0,0 +1,169 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { loadConfig } from '../core/config/loader.ts';
+import { resolvePreset, mergeConfigs } from '../core/config/preset-resolver.ts';
+import { loadAdapter } from '../adapters/loader.ts';
+import { runAutopilot } from '../core/pipeline/run.ts';
+import type { ReviewEngine } from '../adapters/review-engine/types.ts';
+import type { AutopilotConfig } from '../core/config/types.ts';
+
+const C = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  green: '\x1b[32m', yellow: '\x1b[33m', red: '\x1b[31m', cyan: '\x1b[36m',
+};
+const fmt = (c: keyof typeof C, t: string) => `${C[c]}${t}${C.reset}`;
+
+// Anchored to path segment boundaries — avoids matching "mynode_modules" or similar
+export const IGNORED_PATTERNS: readonly RegExp[] = [
+  /(^|[/\\])node_modules([/\\]|$)/,
+  /(^|[/\\])\.git([/\\]|$)/,
+  /(^|[/\\])\.autopilot-cache([/\\]|$)/,
+  /\.(log|tmp|swp|swo|DS_Store)$/,
+  /~$/,
+];
+
+export function isIgnored(p: string): boolean {
+  return IGNORED_PATTERNS.some(r => r.test(p));
+}
+
+/**
+ * Pure debounce accumulator — returned functions are the testable core of watch logic.
+ * schedule(file) → adds file, starts/resets timer; when debounce fires, calls flush(batch).
+ */
+export function makeDebouncer(
+  flushFn: (batch: string[]) => void,
+  debounceMs: number,
+): { schedule: (file: string) => void; pending: () => string[] } {
+  const pending = new Set<string>();
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  return {
+    schedule(file: string) {
+      pending.add(file);
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        const batch = [...pending];
+        pending.clear();
+        timer = null;
+        flushFn(batch);
+      }, debounceMs);
+    },
+    pending() { return [...pending]; },
+  };
+}
+
+export interface WatchOptions {
+  cwd?: string;
+  configPath?: string;
+  debounceMs?: number;
+}
+
+export async function runWatch(options: WatchOptions = {}): Promise<void> {
+  const cwd = options.cwd ?? process.cwd();
+  const configPath = options.configPath ?? path.join(cwd, 'autopilot.config.yaml');
+  const debounceMs = options.debounceMs ?? 300;
+
+  if (!fs.existsSync(configPath)) {
+    console.error(fmt('red', `[watch] autopilot.config.yaml not found — run: npx autopilot init`));
+    process.exit(1);
+  }
+
+  let config: AutopilotConfig;
+  try {
+    const userConfig = await loadConfig(configPath);
+    config = userConfig.preset
+      ? mergeConfigs((await resolvePreset(userConfig.preset)).config, userConfig)
+      : userConfig;
+  } catch (err) {
+    console.error(fmt('red', `[watch] Config error: ${err instanceof Error ? err.message : String(err)}`));
+    process.exit(1);
+  }
+
+  let reviewEngine: ReviewEngine | undefined;
+  if (config.reviewEngine) {
+    const ref = typeof config.reviewEngine === 'string' ? config.reviewEngine : config.reviewEngine.adapter;
+    if (process.env.OPENAI_API_KEY) {
+      try {
+        reviewEngine = await loadAdapter<ReviewEngine>({
+          point: 'review-engine', ref,
+          options: typeof config.reviewEngine === 'string' ? undefined : config.reviewEngine.options,
+        });
+      } catch { /* skip */ }
+    }
+  }
+
+  console.log(`\n${fmt('bold', '[autopilot watch]')} ${fmt('dim', cwd)}`);
+  console.log(fmt('dim', `  debounce: ${debounceMs}ms  |  Ctrl+C to exit\n`));
+
+  let running = false;
+  const nextPending = new Set<string>();
+
+  const runBatch = async (batch: string[]) => {
+    if (running) {
+      // Queue these files for the next run after the current one completes
+      for (const f of batch) nextPending.add(f);
+      return;
+    }
+    running = true;
+
+    const rel = batch.map(f => path.isAbsolute(f) ? path.relative(cwd, f) : f);
+    const ts = new Date().toLocaleTimeString();
+    console.log(`\n${fmt('cyan', `─── ${ts} ──────────────────────────────────`)}`);
+    console.log(fmt('dim', `  changed: ${rel.slice(0, 4).join(', ')}${rel.length > 4 ? ` +${rel.length - 4} more` : ''}`));
+
+    try {
+      const result = await runAutopilot({ touchedFiles: rel, config, reviewEngine, cwd });
+
+      for (const phase of result.phases) {
+        const icon = phase.status === 'pass' ? fmt('green', '✓')
+          : phase.status === 'skip' ? fmt('dim', '–')
+          : phase.status === 'warn' ? fmt('yellow', '!')
+          : fmt('red', '✗');
+        console.log(`  ${icon}  ${phase.phase.padEnd(14)}${fmt('dim', ` ${(phase as {durationMs?: number}).durationMs ?? 0}ms`)}`);
+        for (const f of phase.findings) {
+          if (f.severity === 'critical' || f.severity === 'warning') {
+            const sev = f.severity === 'critical' ? fmt('red', 'CRITICAL') : fmt('yellow', 'WARNING ');
+            console.log(`       ${sev}  ${f.file}${f.line ? `:${f.line}` : ''} — ${f.message}`);
+          }
+        }
+      }
+
+      const verdict = result.status === 'pass' ? fmt('green', '✓ pass')
+        : result.status === 'warn' ? fmt('yellow', '! warn')
+        : fmt('red', '✗ fail');
+      const cost = result.totalCostUSD !== undefined ? fmt('dim', `  $${result.totalCostUSD.toFixed(4)}`) : '';
+      console.log(`\n  ${verdict}${cost}  ${fmt('dim', `${result.durationMs}ms`)}`);
+    } catch (err) {
+      console.error(fmt('red', `  error: ${err instanceof Error ? err.message : String(err)}`));
+    }
+
+    running = false;
+    // Flush anything that accumulated while we were running
+    if (nextPending.size > 0) {
+      const queued = [...nextPending];
+      nextPending.clear();
+      runBatch(queued);
+    }
+  };
+
+  const debouncer = makeDebouncer(batch => { runBatch(batch); }, debounceMs);
+
+  const onEvent = (_event: string, filename: string | null) => {
+    if (!filename) return;
+    const full = path.isAbsolute(filename) ? filename : path.join(cwd, filename);
+    if (isIgnored(full)) return;
+    debouncer.schedule(full);
+  };
+
+  // fs.watch recursive is supported on macOS/Linux kernel ≥5.1; Windows uses ReadDirectoryChangesW.
+  // Alpha limitation: not battle-tested in Docker/container contexts — upgrade to chokidar for beta.
+  const watcher = fs.watch(cwd, { recursive: true }, onEvent);
+
+  process.on('SIGINT', () => {
+    console.log(fmt('dim', '\n[watch] exiting'));
+    watcher.close();
+    process.exit(0);
+  });
+
+  // Keep the process alive
+  await new Promise<void>(() => { /* never resolves — watch loop runs until SIGINT */ });
+}

package/src/core/cache/cached-engine.ts

@@ -0,0 +1,32 @@
+import type { ReviewEngine, ReviewInput, ReviewOutput } from '../../adapters/review-engine/types.ts';
+import type { Capabilities } from '../../adapters/base.ts';
+import { ReviewCache, type ReviewCacheOptions } from './review-cache.ts';
+
+/**
+ * Wraps any ReviewEngine with file-based response caching.
+ * Cache key = SHA-256(adapterName + model + content).
+ */
+export function withCache(engine: ReviewEngine, options: ReviewCacheOptions = {}): ReviewEngine {
+  const cache = new ReviewCache(options);
+  const model = (engine as { model?: string }).model ?? engine.name;
+
+  return {
+    name: engine.name,
+    apiVersion: engine.apiVersion,
+    getCapabilities(): Capabilities {
+      return engine.getCapabilities();
+    },
+    estimateTokens(content: string): number {
+      return engine.estimateTokens(content);
+    },
+    async review(input: ReviewInput): Promise<ReviewOutput> {
+      const keyPayload = `${input.content}\x00${input.kind}\x00${input.context?.stack ?? ''}`;
+      const key = ReviewCache.keyFor(engine.name, model, keyPayload);
+      const cached = await cache.get(key);
+      if (cached) return { ...cached, usage: cached.usage ? { ...cached.usage, costUSD: 0 } : undefined };
+      const output = await engine.review(input);
+      await cache.set(key, output);
+      return output;
+    },
+  };
+}

package/src/core/cache/review-cache.ts

@@ -0,0 +1,70 @@
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { createHash } from 'node:crypto';
+import type { ReviewOutput } from '../../adapters/review-engine/types.ts';
+
+export interface CacheEntry {
+  key: string;
+  output: ReviewOutput;
+  createdAt: string;
+  expiresAt: string;
+}
+
+export interface ReviewCacheOptions {
+  cacheDir?: string;
+  ttlMs?: number;
+}
+
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+// Prefer env override, then ~/.autopilot-cache to survive across cwd changes and container restarts
+const DEFAULT_CACHE_DIR = process.env.AUTOPILOT_CACHE_DIR
+  ? path.join(process.env.AUTOPILOT_CACHE_DIR, 'reviews')
+  : path.join(os.homedir(), '.autopilot-cache', 'reviews');
+
+export class ReviewCache {
+  private readonly cacheDir: string;
+  private readonly ttlMs: number;
+
+  constructor(options: ReviewCacheOptions = {}) {
+    this.cacheDir = options.cacheDir ?? DEFAULT_CACHE_DIR;
+    this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+  }
+
+  static keyFor(adapterName: string, model: string, content: string): string {
+    return createHash('sha256').update(`${adapterName}:${model}:${content}`).digest('hex');
+  }
+
+  async get(key: string): Promise<ReviewOutput | undefined> {
+    const filePath = this.entryPath(key);
+    try {
+      const raw = await fs.readFile(filePath, 'utf8');
+      const entry: CacheEntry = JSON.parse(raw);
+      if (new Date(entry.expiresAt) < new Date()) {
+        await fs.unlink(filePath).catch(() => undefined);
+        return undefined;
+      }
+      return entry.output;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async set(key: string, output: ReviewOutput): Promise<void> {
+    await fs.mkdir(this.cacheDir, { recursive: true });
+    const entry: CacheEntry = {
+      key,
+      output,
+      createdAt: new Date().toISOString(),
+      expiresAt: new Date(Date.now() + this.ttlMs).toISOString(),
+    };
+    const filePath = this.entryPath(key);
+    const tmp = `${filePath}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(entry), 'utf8');
+    await fs.rename(tmp, filePath);
+  }
+
+  private entryPath(key: string): string {
+    return path.join(this.cacheDir, `${key}.json`);
+  }
+}