@delegance/claude-autopilot 1.0.0-alpha.4

package/src/adapters/base.ts

@@ -0,0 +1,19 @@
+// src/adapters/base.ts
+
+export interface AdapterBase {
+  name: string;
+  apiVersion: string;
+  getCapabilities(): Capabilities;
+}
+
+export interface Capabilities {
+  [feature: string]: boolean | number | string;
+}
+
+export const CORE_ADAPTER_API_VERSION_MAJOR = 1;
+
+export function checkApiVersionCompatibility(adapterApiVersion: string): boolean {
+  const parts = adapterApiVersion.split('.');
+  const major = parseInt(parts[0] ?? '0', 10);
+  return major === CORE_ADAPTER_API_VERSION_MAJOR;
+}

package/src/adapters/loader.ts

@@ -0,0 +1,101 @@
+import * as path from 'node:path';
+import { AutopilotError } from '../core/errors.ts';
+import { checkApiVersionCompatibility, type AdapterBase } from './base.ts';
+
+export type IntegrationPoint = 'review-engine' | 'vcs-host' | 'migration-runner' | 'review-bot-parser';
+
+export interface LoadAdapterOptions {
+  point: IntegrationPoint;
+  ref: string;
+  options?: Record<string, unknown>;
+  /** Allow loading adapters from arbitrary local paths. Off by default for security. */
+  unsafeAllowLocalAdapters?: boolean;
+}
+
+const BUILTIN_PATHS: Record<IntegrationPoint, Record<string, string>> = {
+  'review-engine': { codex: './review-engine/codex.ts' },
+  'vcs-host': { github: './vcs-host/github.ts' },
+  'migration-runner': { supabase: './migration-runner/supabase.ts' },
+  'review-bot-parser': { cursor: './review-bot-parser/cursor.ts' },
+};
+
+const REQUIRED_BY_POINT: Record<IntegrationPoint, string[]> = {
+  'review-engine': ['review', 'estimateTokens'],
+  'vcs-host': ['getPrDiff', 'getPrMetadata', 'postComment', 'getReviewComments', 'replyToComment', 'createPr', 'push'],
+  'migration-runner': ['discover', 'dryRun', 'apply', 'ledger', 'alreadyApplied'],
+  'review-bot-parser': ['detect', 'fetchFindings', 'detectDismissal'],
+};
+
+function isPathRef(ref: string): boolean {
+  return ref.startsWith('./') || ref.startsWith('/') || ref.startsWith('../') || ref.endsWith('.ts') || ref.endsWith('.js');
+}
+
+export async function loadAdapter<T extends AdapterBase>(options: LoadAdapterOptions): Promise<T> {
+  const { point, ref } = options;
+  let modulePath: string;
+
+  if (isPathRef(ref)) {
+    if (!options.unsafeAllowLocalAdapters) {
+      throw new AutopilotError(
+        `Path-based adapter refs require unsafeAllowLocalAdapters:true — set this only for trusted local adapters`,
+        { code: 'invalid_config', details: { point, ref } }
+      );
+    }
+    modulePath = path.resolve(ref);
+  } else {
+    const builtin = BUILTIN_PATHS[point]?.[ref];
+    if (!builtin) {
+      throw new AutopilotError(`Unknown built-in ${point} adapter: "${ref}"`, {
+        code: 'invalid_config',
+        details: { point, ref, available: Object.keys(BUILTIN_PATHS[point] ?? {}) },
+      });
+    }
+    modulePath = new URL(builtin, import.meta.url).pathname;
+  }
+
+  let mod: { default?: T } | T;
+  try {
+    mod = (await import(modulePath)) as { default?: T } | T;
+  } catch (err) {
+    throw new AutopilotError(`Failed to import adapter from ${modulePath}`, {
+      code: 'invalid_config',
+      details: { point, ref, modulePath, cause: err instanceof Error ? err.message : String(err) },
+    });
+  }
+
+  const adapter = ('default' in mod ? mod.default : mod) as T;
+  if (!adapter || typeof adapter !== 'object') {
+    throw new AutopilotError(`Adapter module did not export a valid adapter object`, {
+      code: 'invalid_config',
+      details: { point, ref, modulePath },
+    });
+  }
+
+  validateShape(adapter, point, modulePath);
+
+  if (!checkApiVersionCompatibility(adapter.apiVersion)) {
+    throw new AutopilotError(`Adapter apiVersion ${adapter.apiVersion} incompatible with core`, {
+      code: 'invalid_config',
+      details: { point, ref, adapterApiVersion: adapter.apiVersion },
+    });
+  }
+
+  return adapter;
+}
+
+function validateShape(adapter: AdapterBase, point: IntegrationPoint, modulePath: string): void {
+  const missing: string[] = [];
+  const required = ['getCapabilities', ...REQUIRED_BY_POINT[point]];
+  for (const method of required) {
+    if (typeof (adapter as unknown as Record<string, unknown>)[method] !== 'function') missing.push(method);
+  }
+  if (typeof adapter.name !== 'string' || typeof adapter.apiVersion !== 'string') {
+    missing.push('name/apiVersion');
+  }
+  if (missing.length > 0) {
+    throw new AutopilotError(
+      `Adapter at ${modulePath} missing required methods: ${missing.join(', ')}`,
+      { code: 'invalid_config', details: { point, modulePath, missing } }
+    );
+  }
+}

package/src/adapters/migration-runner/supabase.ts

@@ -0,0 +1,56 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { runSafe } from '../../core/shell.ts';
+import type { Capabilities } from '../base.ts';
+import type { MigrationRunner, Migration, MigrationEnv, DryRunResult, ApplyResult, LedgerEntry } from './types.ts';
+
+export const supabaseAdapter: MigrationRunner = {
+  name: 'supabase',
+  apiVersion: '1.0.0',
+
+  getCapabilities(): Capabilities {
+    return { structuredOutput: false, streaming: false, maxContextTokens: 0, inlineComments: false };
+  },
+
+  discover(touchedFiles: string[]): Migration[] {
+    const sqlFiles = touchedFiles.filter(f => f.match(/data\/deltas\/[^/]+\.sql$/));
+    return sqlFiles.map(p => ({
+      name: path.basename(p, '.sql'),
+      path: p,
+    }));
+  },
+
+  async dryRun(migration: Migration): Promise<DryRunResult> {
+    try {
+      const content = migration.content ?? fs.readFileSync(migration.path, 'utf8');
+      if (!content.trim()) return { ok: false, errors: ['Migration file is empty'] };
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, errors: [err instanceof Error ? err.message : String(err)] };
+    }
+  },
+
+  async apply(migration: Migration, env: MigrationEnv): Promise<ApplyResult> {
+    const start = Date.now();
+    const envFlag = env === 'prod' ? '--prod' : env === 'qa' ? '--qa' : '';
+    const args = ['tsx', 'scripts/supabase/migrate.ts', migration.path];
+    if (envFlag) args.push(envFlag);
+    const result = runSafe('npx', args);
+    if (result === null) {
+      return { ok: false, errors: [`Migration apply failed for ${migration.name} on ${env}`] };
+    }
+    return { ok: true, durationMs: Date.now() - start };
+  },
+
+  async ledger(_env: MigrationEnv): Promise<LedgerEntry[]> {
+    // alpha.1: full ledger query lands in alpha.2
+    return [];
+  },
+
+  async alreadyApplied(migration: Migration, _env: MigrationEnv): Promise<boolean> {
+    const result = runSafe('npx', ['tsx', 'scripts/supabase/migrate.ts', migration.path, '--inspect']);
+    return result !== null && result.includes('already applied');
+  },
+};
+
+export default supabaseAdapter;

package/src/adapters/migration-runner/types.ts

@@ -0,0 +1,36 @@
+import type { AdapterBase } from '../base.ts';
+
+export type MigrationEnv = 'dev' | 'qa' | 'prod';
+
+export interface Migration {
+  name: string;
+  path: string;
+  content?: string;
+}
+
+export interface DryRunResult {
+  ok: boolean;
+  errors?: string[];
+  warnings?: string[];
+}
+
+export interface ApplyResult {
+  ok: boolean;
+  appliedSha?: string;
+  durationMs?: number;
+  errors?: string[];
+}
+
+export interface LedgerEntry {
+  name: string;
+  appliedAt: string;
+  sha?: string;
+}
+
+export interface MigrationRunner extends AdapterBase {
+  discover(touchedFiles: string[]): Migration[];
+  dryRun(migration: Migration): Promise<DryRunResult>;
+  apply(migration: Migration, env: MigrationEnv): Promise<ApplyResult>;
+  ledger(env: MigrationEnv): Promise<LedgerEntry[]>;
+  alreadyApplied(migration: Migration, env: MigrationEnv): Promise<boolean>;
+}

package/src/adapters/review-bot-parser/cursor.ts

@@ -0,0 +1,13 @@
+import { makeDeclarativeParser } from './declarative-base.ts';
+
+export const cursorAdapter = makeDeclarativeParser({
+  name: 'cursor',
+  author: 'cursor[bot]',
+  severityMap: {
+    critical: /\bhigh\b|\bcritical\b/i,
+    warning: /\bmedium\b|\bwarning\b/i,
+  },
+  dismissalKeywords: ['false positive', 'not an issue', 'intentional', 'wontfix'],
+});
+
+export default cursorAdapter;

package/src/adapters/review-bot-parser/declarative-base.ts

@@ -0,0 +1,64 @@
+import type { Finding } from '../../core/findings/types.ts';
+import type { GenericComment, VcsHost } from '../vcs-host/types.ts';
+import type { Capabilities } from '../base.ts';
+import type { ReviewBotParser } from './types.ts';
+
+export interface DeclarativeParserConfig {
+  name: string;
+  author: string | RegExp;
+  severityMap: { critical?: RegExp; warning?: RegExp; note?: RegExp };
+  dismissalKeywords: string[];
+}
+
+export function makeDeclarativeParser(config: DeclarativeParserConfig): ReviewBotParser {
+  const authorTest = typeof config.author === 'string'
+    ? (a: string) => a === config.author
+    : (a: string) => (config.author as RegExp).test(a);
+
+  return {
+    name: config.name,
+    apiVersion: '1.0.0',
+
+    getCapabilities(): Capabilities {
+      return { structuredOutput: false, streaming: false, maxContextTokens: 0, inlineComments: true };
+    },
+
+    detect(comment: GenericComment): boolean {
+      return authorTest(comment.author);
+    },
+
+    async fetchFindings(vcs: VcsHost, pr: number | string): Promise<Finding[]> {
+      const comments = await vcs.getReviewComments(pr);
+      const botComments = comments.filter(c => authorTest(c.author));
+      return botComments.map((c, idx) => {
+        const body = c.body ?? '';
+        const severity = matchSeverity(body, config.severityMap);
+        return {
+          id: `${config.name}-${idx}-${c.id}`,
+          source: `review-bot:${config.name}` as const,
+          severity,
+          category: `${config.name}-finding`,
+          file: c.path ?? '<unspecified>',
+          line: c.line,
+          message: body.split('\n')[0]?.trim() ?? body,
+          protectedPath: false,
+          createdAt: new Date().toISOString(),
+        };
+      });
+    },
+
+    detectDismissal(reply: string): boolean {
+      const lower = reply.toLowerCase();
+      return config.dismissalKeywords.some(kw => lower.includes(kw));
+    },
+  };
+}
+
+function matchSeverity(
+  body: string,
+  map: DeclarativeParserConfig['severityMap']
+): Finding['severity'] {
+  if (map.critical && map.critical.test(body)) return 'critical';
+  if (map.warning && map.warning.test(body)) return 'warning';
+  return 'note';
+}

package/src/adapters/review-bot-parser/types.ts

@@ -0,0 +1,9 @@
+import type { AdapterBase } from '../base.ts';
+import type { Finding } from '../../core/findings/types.ts';
+import type { GenericComment, VcsHost } from '../vcs-host/types.ts';
+
+export interface ReviewBotParser extends AdapterBase {
+  detect(comment: GenericComment): boolean;
+  fetchFindings(vcs: VcsHost, pr: number | string): Promise<Finding[]>;
+  detectDismissal(reply: string): boolean;
+}

package/src/adapters/review-engine/codex.ts

@@ -0,0 +1,108 @@
+import OpenAI from 'openai';
+import type { Finding } from '../../core/findings/types.ts';
+import { AutopilotError } from '../../core/errors.ts';
+import type { Capabilities } from '../base.ts';
+import type { ReviewEngine, ReviewInput, ReviewOutput } from './types.ts';
+
+const DEFAULT_MODEL = process.env.CODEX_MODEL ?? 'gpt-5.3-codex';
+const MAX_OUTPUT_TOKENS = 4096;
+
+const SYSTEM_PROMPT_TEMPLATE = `You are a senior software architect providing feedback on designs, proposals, and ideas.
+
+The codebase context:
+{STACK}
+
+Provide structured feedback in exactly this format:
+
+## Review Summary
+One paragraph overall assessment.
+
+## Findings
+
+For each finding, use this format:
+### [CRITICAL|WARNING|NOTE] <short title>
+<explanation>
+**Suggestion:** <actionable fix>
+
+Rules:
+- CRITICAL: Blocks implementation
+- WARNING: Should address before implementing
+- NOTE: Improvement suggestion
+- Maximum 10 findings, ranked by severity
+- Be specific and constructive`;
+
+export const codexAdapter: ReviewEngine = {
+  name: 'codex',
+  apiVersion: '1.0.0',
+
+  getCapabilities(): Capabilities {
+    return { structuredOutput: false, streaming: false, maxContextTokens: 128000, inlineComments: false };
+  },
+
+  estimateTokens(content: string): number {
+    return Math.ceil(content.length / 4);
+  },
+
+  async review(input: ReviewInput): Promise<ReviewOutput> {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      throw new AutopilotError('OPENAI_API_KEY not set', { code: 'auth', provider: 'codex' });
+    }
+    const stack = input.context?.stack ?? 'A web application — stack details unspecified.';
+    const systemPrompt = SYSTEM_PROMPT_TEMPLATE.replace('{STACK}', stack);
+
+    const client = new OpenAI({ apiKey });
+    let response;
+    try {
+      response = await client.responses.create({
+        model: DEFAULT_MODEL,
+        instructions: systemPrompt,
+        input: `Please review the following:\n\n---\n\n${input.content}`,
+        max_output_tokens: MAX_OUTPUT_TOKENS,
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const isRateLimit = /rate.limit|429/i.test(message);
+      const isAuth = /unauthorized|401|invalid.api.key/i.test(message);
+      throw new AutopilotError(`Codex review call failed: ${message}`, {
+        code: isAuth ? 'auth' : isRateLimit ? 'rate_limit' : 'transient_network',
+        provider: 'codex',
+        retryable: isRateLimit,
+      });
+    }
+
+    const rawOutput = response.output_text ?? '';
+    return {
+      findings: parseCodexOutput(rawOutput),
+      rawOutput,
+      usage: response.usage ? { input: response.usage.input_tokens, output: response.usage.output_tokens } : undefined,
+    };
+  },
+};
+
+export default codexAdapter;
+
+function parseCodexOutput(output: string): Finding[] {
+  const findings: Finding[] = [];
+  const regex = /### \[(CRITICAL|WARNING|NOTE)\]\s*(.+?)(?=\n### \[|## Review Summary|$)/gs;
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(output)) !== null) {
+    const severity = match[1]!.toLowerCase() as Finding['severity'];
+    const body = match[2]!.trim();
+    const titleEnd = body.indexOf('\n');
+    const title = (titleEnd > 0 ? body.slice(0, titleEnd) : body).trim();
+    const suggestion = body.match(/\*\*Suggestion:\*\*\s*(.+)/s)?.[1]?.trim();
+    findings.push({
+      id: `codex-${findings.length}`,
+      source: 'review-engine',
+      severity,
+      category: 'codex-review',
+      file: '<unspecified>',
+      message: title,
+      suggestion,
+      protectedPath: false,
+      createdAt: new Date().toISOString(),
+    });
+  }
+  return findings;
+}

package/src/adapters/review-engine/types.ts

@@ -0,0 +1,19 @@
+import type { AdapterBase } from '../base.ts';
+import type { Finding } from '../../core/findings/types.ts';
+
+export interface ReviewInput {
+  content: string;
+  kind: 'spec' | 'pr-diff' | 'file-batch';
+  context?: { spec?: string; plan?: string; stack?: string };
+}
+
+export interface ReviewOutput {
+  findings: Finding[];
+  rawOutput: string;
+  usage?: { input: number; output: number; costUSD?: number };
+}
+
+export interface ReviewEngine extends AdapterBase {
+  review(input: ReviewInput): Promise<ReviewOutput>;
+  estimateTokens(content: string): number;
+}

package/src/adapters/vcs-host/github.ts

@@ -0,0 +1,77 @@
+import { runSafe, runThrowing } from '../../core/shell.ts';
+import { AutopilotError } from '../../core/errors.ts';
+import type { Capabilities } from '../base.ts';
+import type { VcsHost, GenericComment, PrMetadata, CreatePrOptions, CreatePrResult } from './types.ts';
+
+export const githubAdapter: VcsHost = {
+  name: 'github',
+  apiVersion: '1.0.0',
+
+  getCapabilities(): Capabilities {
+    return { structuredOutput: true, streaming: false, maxContextTokens: 0, inlineComments: true };
+  },
+
+  async getPrDiff(pr: number | string): Promise<string> {
+    const result = runSafe('gh', ['pr', 'diff', String(pr)]);
+    if (result === null) throw new AutopilotError(`Failed to get diff for PR ${pr}`, { code: 'transient_network' });
+    return result;
+  },
+
+  async getPrMetadata(pr: number | string): Promise<PrMetadata> {
+    const raw = runThrowing('gh', ['pr', 'view', String(pr), '--json', 'title,body,files,headRefOid,baseRefName,headRefName'], { errorCode: 'transient_network' });
+    const data = JSON.parse(raw) as { title: string; body: string; files: { path: string }[]; headRefOid: string; baseRefName: string; headRefName: string };
+    return {
+      title: data.title,
+      body: data.body ?? '',
+      files: (data.files ?? []).map((f: { path: string }) => f.path),
+      headSha: data.headRefOid,
+      baseRef: data.baseRefName,
+      headRef: data.headRefName,
+    };
+  },
+
+  async postComment(pr: number | string, body: string): Promise<void> {
+    runThrowing('gh', ['pr', 'comment', String(pr), '--body', body], { errorCode: 'transient_network' });
+  },
+
+  async getReviewComments(pr: number | string): Promise<GenericComment[]> {
+    const raw = runSafe('gh', ['api', `repos/{owner}/{repo}/pulls/${pr}/comments`, '--paginate']);
+    if (!raw) return [];
+    try {
+      const parsed = JSON.parse(raw) as Array<{ id: number; user: { login: string }; body: string; path: string; line?: number; html_url: string }>;
+      return parsed.map(c => ({ id: c.id, author: c.user.login, body: c.body, path: c.path, line: c.line, url: c.html_url }));
+    } catch { return []; }
+  },
+
+  async replyToComment(pr: number | string, commentId: string | number, body: string): Promise<void> {
+    runThrowing('gh', ['api', `repos/{owner}/{repo}/pulls/${pr}/comments/${commentId}/replies`, '--method', 'POST', '--field', `body=${body}`], { errorCode: 'transient_network' });
+  },
+
+  async createPr(opts: CreatePrOptions): Promise<CreatePrResult> {
+    const existing = runSafe('gh', ['pr', 'list', '--head', opts.head, '--json', 'number,url', '--limit', '1']);
+    if (existing) {
+      try {
+        const parsed = JSON.parse(existing) as Array<{ number: number; url: string }>;
+        if (parsed.length > 0 && parsed[0]) {
+          return { number: parsed[0].number, url: parsed[0].url, alreadyExisted: true };
+        }
+      } catch { /* fall through to create */ }
+    }
+
+    const args = ['pr', 'create', '--title', opts.title, '--body', opts.body, '--base', opts.base, '--head', opts.head];
+    if (opts.draft) args.push('--draft');
+    const raw = runThrowing('gh', args, { errorCode: 'transient_network' });
+    const url = raw.trim();
+    const match = url.match(/\/pull\/(\d+)$/);
+    const number = match ? parseInt(match[1]!, 10) : 0;
+    return { number, url, alreadyExisted: false };
+  },
+
+  async push(branch: string, opts?: { setUpstream?: boolean }): Promise<void> {
+    const args = ['push', 'origin', branch];
+    if (opts?.setUpstream) args.splice(1, 0, '-u');
+    runThrowing('git', args, { errorCode: 'transient_network' });
+  },
+};
+
+export default githubAdapter;

package/src/adapters/vcs-host/types.ts

@@ -0,0 +1,44 @@
+import type { AdapterBase } from '../base.ts';
+
+export interface GenericComment {
+  id: string | number;
+  author: string;
+  body: string;
+  path?: string;
+  line?: number;
+  url?: string;
+}
+
+export interface PrMetadata {
+  title: string;
+  body: string;
+  files: string[];
+  headSha: string;
+  baseRef: string;
+  headRef: string;
+}
+
+export interface CreatePrOptions {
+  title: string;
+  body: string;
+  base: string;
+  head: string;
+  draft?: boolean;
+  idempotencyKey?: string;
+}
+
+export interface CreatePrResult {
+  number: number;
+  url: string;
+  alreadyExisted: boolean;
+}
+
+export interface VcsHost extends AdapterBase {
+  getPrDiff(pr: number | string): Promise<string>;
+  getPrMetadata(pr: number | string): Promise<PrMetadata>;
+  postComment(pr: number | string, body: string, idempotencyKey?: string): Promise<void>;
+  getReviewComments(pr: number | string): Promise<GenericComment[]>;
+  replyToComment(pr: number | string, commentId: string | number, body: string, idempotencyKey?: string): Promise<void>;
+  createPr(opts: CreatePrOptions): Promise<CreatePrResult>;
+  push(branch: string, opts?: { setUpstream?: boolean }): Promise<void>;
+}

package/src/cli/index.ts

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * autopilot CLI — entry point
+ *
+ * Usage:
+ *   autopilot init              scaffold autopilot.config.yaml from a preset
+ *   autopilot run               run the pipeline on git-changed files
+ *   autopilot run --base main   diff against a specific branch
+ *   autopilot run --dry-run     show what would run, no execution
+ *   autopilot watch             re-run pipeline on every file save (debounced)
+ *   autopilot preflight         check prerequisites
+ */
+import { runInit } from './init.ts';
+import { runCommand } from './run.ts';
+import { runWatch } from './watch.ts';
+
+const args = process.argv.slice(2);
+
+const SUBCOMMANDS = ['init', 'run', 'preflight', 'help', '--help', '-h'] as const;
+const VALUE_FLAGS = ['base', 'config', 'files'];
+
+// Detect first non-flag arg as subcommand, default to 'run'
+const subcommand = (args[0] && !args[0].startsWith('--')) ? args[0] : 'run';
+
+/** Returns value for --name <value>. Exits if value is missing (next token is another flag or absent). */
+function flag(name: string): string | undefined {
+  const idx = args.indexOf(`--${name}`);
+  if (idx < 0) return undefined;
+  const val = args[idx + 1];
+  if (val === undefined || val.startsWith('--')) {
+    console.error(`\x1b[31m[autopilot] --${name} requires a value\x1b[0m`);
+    process.exit(1);
+  }
+  return val;
+}
+
+function boolFlag(name: string): boolean {
+  return args.includes(`--${name}`);
+}
+
+function printUsage(): void {
+  console.log(`
+Usage: autopilot <command> [options]
+
+Commands:
+  run          Run the pipeline on git-changed files (default)
+  watch        Watch for file changes and re-run pipeline on each save
+  init         Scaffold autopilot.config.yaml from a preset
+  preflight    Check prerequisites
+
+Options (run):
+  --base <ref>         Git base ref for diff (default: HEAD~1)
+  --config <path>      Path to config file (default: ./autopilot.config.yaml)
+  --files <a,b,c>      Explicit comma-separated file list (skips git detection)
+  --dry-run            Show what would run without executing
+
+Options (watch):
+  --config <path>      Path to config file (default: ./autopilot.config.yaml)
+  --debounce <ms>      Debounce delay in ms (default: 300)
+`);
+}
+
+switch (subcommand) {
+  case 'init':
+    await runInit(process.cwd());
+    break;
+
+  case 'preflight':
+    await import('./preflight.ts');
+    break;
+
+  case 'help':
+  case '--help':
+  case '-h':
+    printUsage();
+    break;
+
+  case 'watch': {
+    const config = flag('config');
+    const debounceArg = flag('debounce');
+    const debounceMs = debounceArg ? parseInt(debounceArg, 10) : undefined;
+    if (debounceArg && (isNaN(debounceMs!) || debounceMs! < 0)) {
+      console.error(`\x1b[31m[autopilot] --debounce must be a non-negative integer\x1b[0m`);
+      process.exit(1);
+    }
+    await runWatch({ configPath: config, debounceMs });
+    break;
+  }
+
+  case 'run': {
+    const base = flag('base');
+    const config = flag('config');
+    const filesArg = flag('files');
+    const dryRun = boolFlag('dry-run');
+
+    const code = await runCommand({
+      base,
+      configPath: config,
+      files: filesArg ? filesArg.split(',').map(f => f.trim()) : undefined,
+      dryRun,
+    });
+    process.exit(code);
+    break;
+  }
+
+  default:
+    console.error(`\x1b[31m[autopilot] Unknown subcommand: "${subcommand}"\x1b[0m`);
+    printUsage();
+    process.exit(1);
+}