@moretea-labs/forge 1.5.0-rc.1

package/src/cli/hook-entry.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env bun
+/**
+ * Minimal hook-only CLI entrypoint for host adapters.
+ *
+ * Host hooks run after almost every tool call and may be invoked concurrently.
+ * Keep this file self-contained so the hot hook path does not cold-load the
+ * full commander CLI or non-hook command modules.
+ */
+
+import { runHook as runHookRuntime, type RunHookOptions, type RunHookResult } from './hook/runtime';
+import { runPromptGuardDecideCli } from './commands/prompt-guard-decision';
+import { runStateSnapshotCli } from './hook/state-snapshot';
+import type { HookEvent, RouteId } from './hook/route-registry';
+
+export type RunHookEntryOptions = RunHookOptions;
+export type RunHookEntryResult = RunHookResult;
+
+export function runHookEntry(opts: RunHookEntryOptions): RunHookEntryResult {
+  return runHookRuntime({ ...opts, commandName: 'forge-hook' });
+}
+
+function parseCliArgs(argv: readonly string[]): { event: HookEvent; routeId: RouteId } | null {
+  const event = argv[0] as HookEvent | undefined;
+  const routeFlagIndex = argv.indexOf('--route');
+  const routeId = routeFlagIndex >= 0 ? argv[routeFlagIndex + 1] : undefined;
+  if (!event || !routeId) return null;
+  return { event, routeId: routeId as RouteId };
+}
+
+if (import.meta.main) {
+  const argv = process.argv.slice(2);
+  if (argv[0] === 'prompt-guard-decide') {
+    console.log(runPromptGuardDecideCli());
+    process.exit(0);
+  }
+
+  if (argv[0] === 'state-snapshot') {
+    const result = runStateSnapshotCli(argv.slice(1));
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+    process.exit(result.exitCode);
+  }
+
+  const parsed = parseCliArgs(argv);
+  if (!parsed) {
+    process.stderr.write('forge-hook: usage: forge-hook <event> --route <route>\n');
+    process.exit(2);
+  }
+  const result = runHookEntry(parsed);
+  process.exit(result.exitCode);
+}

package/src/cli/index.ts

@@ -0,0 +1,574 @@
+#!/usr/bin/env bun
+/**
+ * Forge CLI entry with forge compatibility aliases.
+ *
+ * Wires commander.js to the global runtime bootstrap, repo-local update,
+ * hook adapter, status, doctor, migrate, security, and tool command bodies.
+ */
+
+import { Command } from 'commander';
+import { pathToFileURL } from 'node:url';
+import { runInstall, runUninstall, type InstallTargetSpec } from './commands/install';
+import { runInit, runInteractiveInit, type InitBrainMode } from './commands/init';
+import { runHook } from './commands/hook';
+import { CLI_VERSION, formatStatus, runStatus } from './commands/status';
+import { formatDoctor, runDoctor } from './commands/doctor';
+import { buildInitHookCommand, buildSetupCommand, formatInitHook, runInitHook } from './commands/init-hook';
+import { formatMigratePlan, runMigrate } from './commands/migrate';
+import { buildToolsCommand } from './commands/tools';
+import { buildPluginCommand } from './commands/plugin';
+import { buildBrainCommand } from './commands/brain';
+import { buildCapabilityContextCommand } from './commands/capability-context';
+import { buildDocsCommand } from './commands/docs';
+import { buildMcpCommand } from './commands/mcp';
+import { buildChatgptCommand } from './commands/chatgpt';
+import { buildRunCommand } from './commands/run';
+import { buildControllerCommand } from './commands/controller';
+import { buildRepositoryCommand } from './commands/repository';
+import { buildRuntimeCommand } from './commands/runtime';
+import { buildRecoveryCommand } from './commands/recovery';
+import { formatSecurityScan, runSecurityScan } from './commands/security';
+import { runGlobalRuntimeSetup } from './commands/global-runtime';
+import { runPromptGuardDecideCli } from './commands/prompt-guard-decision';
+import { runAdoptionPlan, runExperimentalTsApply } from './commands/adopt-plan';
+import { runRuntimeReclaim, runRuntimeRollback } from './repo-adoption/reclaim-runtime';
+import { rollbackAdoptionTransaction } from '../effects/fs-transaction';
+import type { Location } from './installer/types';
+import type { HookEvent, RouteId } from './hook/route-registry';
+import type { AdoptionMode } from '../core/adoption/modes';
+import { bootstrapManagedRuntimeEnv } from '../runtime/shared/managed-env';
+
+bootstrapManagedRuntimeEnv();
+
+export const SUBCOMMANDS = [
+  'init',
+  'init-hook',
+  'install',
+  'uninstall',
+  'hook',
+  'status',
+  'doctor',
+  'migrate',
+  'security',
+  'update',
+  'adopt',
+  'run',
+  'setup',
+  'tools',
+  'plugin',
+  'brain',
+  'capability-context',
+  'docs',
+  'mcp',
+  'chatgpt',
+  'controller',
+  'repo',
+  'runtime',
+  'recovery',
+] as const;
+export type Subcommand = (typeof SUBCOMMANDS)[number];
+
+const VALID_TARGETS: readonly InstallTargetSpec[] = ['codex', 'claude', 'both'];
+const VALID_LOCATIONS: readonly Location[] = ['global', 'local'];
+
+interface GlobalRuntimeCommandOptions {
+  target: string;
+  cli?: boolean;
+  syncSkill?: boolean;
+  hooks?: string | false;
+  externalSkills?: boolean;
+  codegraph?: boolean;
+  brainRoot?: string;
+  json?: boolean;
+}
+
+function runGlobalRuntimeBootstrap(commandName: 'init' | 'install', rawOpts: GlobalRuntimeCommandOptions): never {
+  if (!VALID_TARGETS.includes(rawOpts.target as InstallTargetSpec)) {
+    console.error(
+      `forge ${commandName}: invalid --target "${rawOpts.target}" (expected: ${VALID_TARGETS.join(', ')})`,
+    );
+    process.exit(2);
+  }
+  const result = runGlobalRuntimeSetup({
+    target: rawOpts.target as InstallTargetSpec,
+    installCli: rawOpts.cli !== false,
+    syncSkill: rawOpts.syncSkill !== false,
+    hostAdapters: rawOpts.hooks !== false,
+    externalSkills: rawOpts.externalSkills !== false,
+    codegraph: rawOpts.codegraph !== false,
+    brainRoot: rawOpts.brainRoot,
+  });
+  if (rawOpts.json === true) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    for (const line of result.lines) console.log(line);
+  }
+  process.exit(result.exitCode);
+}
+
+export function buildProgram(): Command {
+  const program = new Command();
+  program
+    .name('forge')
+    .description('Local-first action assistant for durable, reviewable software work')
+    .addHelpText('after', '\nGlobal shortcuts:\n  -V, --version  output the version number')
+    .exitOverride();
+
+  program
+    .command('init')
+    .description('Install the Forge CLI, global hook adapters, and required runtime dependencies')
+    .option('--target <target>', `Host target for adapters and runtime skills: ${VALID_TARGETS.join('|')}`, 'both')
+    .option('--no-cli', 'Skip installing the Forge CLI globally')
+    .option('--no-sync-skill', 'Skip refreshing legacy forge skill aliases under host skill roots')
+    .option('--no-hooks', 'Skip global hook adapter installation')
+    .option('--no-external-skills', 'Skip Waza, Mermaid, and cross-review (codex-review/claude-review) skill bootstrap')
+    .option('--no-codegraph', 'Skip CodeGraph CLI/MCP configuration')
+    .option('--brain-root <path>', 'Brain vault root to persist for Forge brain commands')
+    .option('--refresh', 'Compatibility no-op; init already refreshes the idempotent user-level runtime')
+    .option('--json', 'Output JSON instead of human-readable text')
+    .action((rawOpts: GlobalRuntimeCommandOptions & { refresh?: boolean }) => {
+      runGlobalRuntimeBootstrap('init', rawOpts);
+    });
+
+  program
+    .command('update')
+    .description('Update the global Forge CLI and user-level managed runtime')
+    .option('--target <target>', `Host target for adapters and runtime skills: ${VALID_TARGETS.join('|')}`, 'both')
+    .option('--version <version>', 'Install a specific Forge package version')
+    .option('--channel <channel>', 'Install package channel: latest|next')
+    .option('--check', 'Run the read-only setup check without refreshing runtime')
+    .option('--check-updates', 'Include network-backed version update advisories in setup check output')
+    .option('--no-runtime-refresh', 'Skip runtime refresh and run the read-only setup check only')
+    .option('--no-cli', 'Skip installing the Forge CLI globally')
+    .option('--no-sync-skill', 'Skip refreshing legacy forge skill aliases under host skill roots')
+    .option('--no-hooks', 'Skip global hook adapter installation')
+    .option('--with-external-skills', 'Also bootstrap third-party Waza, Mermaid, and cross-review skills')
+    .option('--no-external-skills', 'Compatibility no-op; update no longer bootstraps third-party skills by default')
+    .option('--configure-codegraph', 'Also configure CodeGraph CLI/MCP during runtime refresh')
+    .option('--no-codegraph', 'Compatibility no-op; update no longer configures CodeGraph by default')
+    .option('--brain-root <path>', 'Brain vault root for manifest sync')
+    .option('--repo <path>', 'Deprecated: use forge adopt --repo <path>')
+    .option('--dry-run', 'Deprecated: use forge adopt --dry-run for repo-level planning')
+    .option('--interactive', 'Deprecated: use forge adopt --interactive for repo-level planning')
+    .option('--json', 'Output JSON instead of human-readable text')
+    .action((rawOpts: {
+      repo?: string;
+      dryRun?: boolean;
+      target: string;
+      version?: string;
+      channel?: string;
+      check?: boolean;
+      checkUpdates?: boolean;
+      runtimeRefresh?: boolean;
+      cli?: boolean;
+      syncSkill?: boolean;
+      hooks?: string | false;
+      withExternalSkills?: boolean;
+      externalSkills?: boolean;
+      codegraph?: boolean;
+      configureCodegraph?: boolean;
+      brainRoot?: string;
+      interactive?: boolean;
+      json?: boolean;
+    }) => {
+      if (!VALID_TARGETS.includes(rawOpts.target as InstallTargetSpec)) {
+        console.error(
+          `forge update: invalid --target "${rawOpts.target}" (expected: ${VALID_TARGETS.join(', ')})`,
+        );
+        process.exit(2);
+      }
+      if (rawOpts.channel !== undefined && !['latest', 'next'].includes(rawOpts.channel)) {
+        console.error('forge update: invalid --channel (expected: latest, next)');
+        process.exit(2);
+      }
+      if (rawOpts.repo || rawOpts.dryRun || rawOpts.interactive) {
+        console.error(
+          'forge update no longer refreshes repositories. For repo-level refresh, run: forge adopt --repo <path>',
+        );
+        process.exit(2);
+      }
+      if (rawOpts.check === true || rawOpts.runtimeRefresh === false) {
+        const report = runInitHook({
+          target: rawOpts.target as InstallTargetSpec,
+          checkUpdates: rawOpts.checkUpdates === true,
+        });
+        console.log(formatInitHook(report, rawOpts.json === true));
+        process.exit(report.status === 'blocked' ? 1 : 0);
+      }
+      const installSpec = rawOpts.version
+        ? `@moretea-labs/forge@${rawOpts.version}`
+        : rawOpts.channel
+          ? `@moretea-labs/forge@${rawOpts.channel}`
+          : '@moretea-labs/forge@latest';
+      const result = runGlobalRuntimeSetup({
+        target: rawOpts.target as InstallTargetSpec,
+        installCli: rawOpts.cli !== false,
+        installSpec,
+        syncSkill: rawOpts.syncSkill !== false,
+        hostAdapters: rawOpts.hooks !== false,
+        externalSkills: rawOpts.withExternalSkills === true,
+        codegraph: rawOpts.configureCodegraph === true,
+        brainRoot: rawOpts.brainRoot,
+      });
+      if (rawOpts.json === true) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        for (const line of result.lines) console.log(line);
+      }
+      process.exit(result.exitCode);
+    });
+
+  program
+    .command('adopt')
+    .description('Install or refresh the repo-local harness workflow in an existing repo')
+    .argument('[action]', 'Optional action: rollback')
+    .option('--repo <path>', 'Target repository path (defaults to cwd)')
+    .option('--archive <path>', 'Runtime reclaim archive to restore when action is rollback')
+    .option('--transaction <path>', 'Adoption transaction manifest to restore when action is rollback')
+    .option('--dry-run', 'Plan Forge changes without applying them')
+    .option('--target <target>', `Host target for readiness checks and optional global bootstrap: ${VALID_TARGETS.join('|')}`, 'both')
+    .option('--no-sync-skill', 'Compatibility no-op; adopt never refreshes user-level skill aliases')
+    .option('--no-host-adapters', 'Compatibility no-op; adopt never writes global Codex/Claude hook adapters')
+    .option('--no-external-skills', 'Compatibility no-op; adopt never bootstraps user-level external skills')
+    .option('--no-verify', 'Skip repo workflow verification after apply')
+    .option('--no-codegraph', 'Skip building the CodeGraph index and MCP readiness check')
+    .option('--reclaim-runtime', 'Reclaim generated repo-local hook/helper runtime copies after replacement paths verify')
+    .option('--compact', 'Compact repo surface; includes --reclaim-runtime plus package script rewrite')
+    .option('--mode <mode>', 'Adoption mode: minimal|standard|self-host', 'standard')
+    .option('--configure-codegraph', 'Deprecated: user-level MCP config belongs to Forge update/setup')
+    .option('--sync-codegraph', 'Sync the CodeGraph index after ensure')
+    .option('--brain-root <path>', 'Deprecated: user-level brain config belongs to Forge update/setup')
+    .option('--brain-mode <mode>', 'Deprecated: adopt does not perform user-level brain sync', 'skip')
+    .option('--interactive', 'Run the numbered interactive install planner')
+    .option('--experimental-ts-apply', 'Apply the current TypeScript safe-subset adoption plan instead of the shell migrator')
+    .option('--json', 'Output JSON instead of human-readable text')
+    .action(async (action: string | undefined, rawOpts: {
+      repo?: string;
+      archive?: string;
+      transaction?: string;
+      dryRun?: boolean;
+      target: string;
+      syncSkill?: boolean;
+      hostAdapters?: boolean;
+      externalSkills?: boolean;
+      verify?: boolean;
+      codegraph?: boolean;
+      reclaimRuntime?: boolean;
+      compact?: boolean;
+      mode?: string;
+      configureCodegraph?: boolean;
+      syncCodegraph?: boolean;
+      brainRoot?: string;
+      brainMode?: string;
+      interactive?: boolean;
+      experimentalTsApply?: boolean;
+      json?: boolean;
+    }) => {
+      if (action) {
+        if (action !== 'rollback') {
+          console.error(`forge adopt: unknown action "${action}"`);
+          process.exit(2);
+        }
+        if (rawOpts.transaction) {
+          const rollback = rollbackAdoptionTransaction({ repoRoot: rawOpts.repo ?? process.cwd(), transaction: rawOpts.transaction });
+          if (rawOpts.json === true) {
+            console.log(JSON.stringify(rollback, null, 2));
+          } else {
+            console.log(`[adopt] ${rollback.ok ? 'ok' : 'failed'}: rollback transaction ${rollback.transactionManifestPath}`);
+            for (const result of rollback.results) {
+              const target = result.path ? ` ${result.path}` : '';
+              const detail = result.error ? ` - ${result.error}` : '';
+              console.log(`[adopt] ${result.status}: ${result.action}${target}${detail}`);
+            }
+          }
+          process.exit(rollback.ok ? 0 : 1);
+        }
+        if (!rawOpts.archive) {
+          console.error('forge adopt rollback: --archive or --transaction is required');
+          process.exit(2);
+        }
+        const rollback = runRuntimeRollback({ repo: rawOpts.repo, archive: rawOpts.archive });
+        if (rawOpts.json === true) {
+          console.log(JSON.stringify(rollback, null, 2));
+        } else {
+          console.log(`[adopt] ${rollback.status}: rollback runtime archive ${rollback.archive}`);
+          for (const restored of rollback.restored) console.log(`[adopt] restored: ${restored}`);
+          for (const missing of rollback.missing) console.log(`[adopt] missing: ${missing}`);
+        }
+        process.exit(rollback.status === 'ok' ? 0 : 1);
+      }
+      if (!VALID_TARGETS.includes(rawOpts.target as InstallTargetSpec)) {
+        console.error(
+          `forge adopt: invalid --target "${rawOpts.target}" (expected: ${VALID_TARGETS.join(', ')})`,
+        );
+        process.exit(2);
+      }
+      if (!['skip', 'manifest-only', 'install-gbrain-cli'].includes(rawOpts.brainMode ?? 'skip')) {
+        console.error('forge adopt: invalid --brain-mode (expected: skip, manifest-only, install-gbrain-cli)');
+        process.exit(2);
+      }
+      if (!['minimal', 'standard', 'self-host'].includes(rawOpts.mode ?? 'standard')) {
+        console.error('forge adopt: invalid --mode (expected: minimal, standard, self-host)');
+        process.exit(2);
+      }
+      if (rawOpts.configureCodegraph === true) {
+        console.error('forge adopt: --configure-codegraph writes user-level MCP config; run forge update instead');
+        process.exit(2);
+      }
+      if (rawOpts.brainRoot || rawOpts.brainMode !== 'skip') {
+        console.error('forge adopt: brain configuration writes user-level state; run forge update instead');
+        process.exit(2);
+      }
+      const mode = (rawOpts.mode ?? 'standard') as AdoptionMode;
+      const routesToTsDryRunPlan =
+        rawOpts.dryRun === true &&
+        (rawOpts.json === true ||
+          (rawOpts.interactive !== true && rawOpts.reclaimRuntime !== true && rawOpts.compact !== true));
+      if (
+        mode !== 'standard' &&
+        routesToTsDryRunPlan !== true &&
+        rawOpts.experimentalTsApply !== true
+      ) {
+        console.error(
+          `forge adopt: --mode ${mode} is only supported with ordinary --dry-run or --experimental-ts-apply; default apply still uses the shell migrator`,
+        );
+        process.exit(2);
+      }
+      if (routesToTsDryRunPlan) {
+        const plan = runAdoptionPlan({
+          repo: rawOpts.repo,
+          mode,
+          json: rawOpts.json === true,
+          explicitRepo: rawOpts.repo !== undefined,
+        });
+        process.stdout.write(plan.output);
+        process.exit(plan.exitCode);
+      }
+      if (rawOpts.experimentalTsApply === true) {
+        if (rawOpts.interactive === true || rawOpts.reclaimRuntime === true || rawOpts.compact === true) {
+          console.error(
+            'forge adopt: --experimental-ts-apply cannot be combined with --interactive, --reclaim-runtime, or --compact',
+          );
+          process.exit(2);
+        }
+        const apply = runExperimentalTsApply({
+          repo: rawOpts.repo,
+          mode,
+          json: rawOpts.json === true,
+          explicitRepo: rawOpts.repo !== undefined,
+        });
+        process.stdout.write(apply.output);
+        process.exit(apply.exitCode);
+      }
+      const common = {
+        repo: rawOpts.repo,
+        apply: rawOpts.dryRun !== true,
+        target: rawOpts.target as InstallTargetSpec,
+        syncSkill: false,
+        hostAdapters: false,
+        externalSkills: false,
+        verify: rawOpts.verify !== false,
+        codegraph: rawOpts.codegraph !== false,
+        configureCodegraphMcp: false,
+        syncCodegraph: rawOpts.syncCodegraph === true,
+        brainRoot: rawOpts.brainRoot,
+        brainMode: rawOpts.brainMode as InitBrainMode,
+      };
+      const result = rawOpts.interactive === true
+        ? await runInteractiveInit({
+            ...common,
+            output: rawOpts.json === true ? process.stderr : process.stdout,
+          })
+        : runInit(common);
+      const shouldReclaim = rawOpts.reclaimRuntime === true || rawOpts.compact === true;
+      const reclaim = shouldReclaim && (result.exitCode === 0 || rawOpts.dryRun === true)
+        ? runRuntimeReclaim({
+            repo: result.repoRoot,
+            apply: rawOpts.dryRun !== true,
+            compact: rawOpts.compact === true,
+            verify: rawOpts.verify !== false,
+            mode: rawOpts.mode as 'minimal' | 'standard' | 'self-host',
+          })
+        : null;
+      if (rawOpts.json === true) {
+        console.log(JSON.stringify(reclaim ? { adopt: result, runtime_reclaim: reclaim } : result, null, 2));
+      } else {
+        for (const line of result.lines) console.log(line);
+        if (reclaim) {
+          console.log(`[adopt] ${reclaim.status}: reclaim runtime - files=${reclaim.runtime_reclaim.files.length}`);
+          if (reclaim.runtime_reclaim.archive) console.log(`[adopt] archive: ${reclaim.runtime_reclaim.archive}`);
+          for (const blocked of reclaim.runtime_reclaim.blocked) console.log(`[adopt] blocked: ${blocked}`);
+        }
+      }
+      process.exit(result.exitCode || (reclaim?.status === 'blocked' ? 1 : 0));
+    });
+
+  program
+    .command('install')
+    .description('Install the Forge global runtime; with --location, install only hook adapters')
+    .option('--target <target>', `Target host: ${VALID_TARGETS.join('|')}`, 'both')
+    .option('--location <location>', `Adapter-only install location: ${VALID_LOCATIONS.join('|')}`)
+    .option('--no-cli', 'Skip installing the Forge CLI globally')
+    .option('--no-sync-skill', 'Skip refreshing legacy forge skill aliases under host skill roots')
+    .option('--no-hooks', 'Skip global hook adapter installation during full runtime install')
+    .option('--no-external-skills', 'Skip Waza, Mermaid, and cross-review (codex-review/claude-review) skill bootstrap')
+    .option('--no-codegraph', 'Skip CodeGraph CLI/MCP configuration')
+    .option('--brain-root <path>', 'Brain vault root to persist for Forge brain commands')
+    .option('--json', 'Output JSON instead of human-readable text')
+    .action((rawOpts: GlobalRuntimeCommandOptions & { location?: string }) => {
+      if (!VALID_TARGETS.includes(rawOpts.target as InstallTargetSpec)) {
+        console.error(
+          `forge install: invalid --target "${rawOpts.target}" (expected: ${VALID_TARGETS.join(', ')})`,
+        );
+        process.exit(2);
+      }
+      if (rawOpts.location === undefined) {
+        runGlobalRuntimeBootstrap('install', rawOpts);
+      }
+      if (!VALID_LOCATIONS.includes(rawOpts.location as Location)) {
+        console.error(
+          `forge install: invalid --location "${rawOpts.location}" (expected: ${VALID_LOCATIONS.join(', ')})`,
+        );
+        process.exit(2);
+      }
+      const result = runInstall({
+        target: rawOpts.target as InstallTargetSpec,
+        location: rawOpts.location as Location,
+      });
+      for (const line of result.lines) console.log(line);
+      process.exit(result.exitCode);
+    });
+
+  program
+    .command('uninstall')
+    .description('Remove Forge-managed hook adapters from Codex and/or Claude host config')
+    .option('--target <target>', `Target host: ${VALID_TARGETS.join('|')}`, 'both')
+    .option('--location <location>', `Install location: ${VALID_LOCATIONS.join('|')}`, 'global')
+    .action((rawOpts: { target: string; location: string }) => {
+      if (!VALID_TARGETS.includes(rawOpts.target as InstallTargetSpec)) {
+        console.error(
+          `forge uninstall: invalid --target "${rawOpts.target}" (expected: ${VALID_TARGETS.join(', ')})`,
+        );
+        process.exit(2);
+      }
+      if (!VALID_LOCATIONS.includes(rawOpts.location as Location)) {
+        console.error(
+          `forge uninstall: invalid --location "${rawOpts.location}" (expected: ${VALID_LOCATIONS.join(', ')})`,
+        );
+        process.exit(2);
+      }
+      const result = runUninstall({
+        target: rawOpts.target as InstallTargetSpec,
+        location: rawOpts.location as Location,
+      });
+      for (const line of result.lines) console.log(line);
+      process.exit(result.exitCode);
+    });
+
+  program
+    .command('hook')
+    .description('Dispatch a hook event to opt-in repo .ai/hooks/<script>')
+    .argument('<event>', 'Hook event name')
+    .requiredOption('--route <route>', 'Route id (default, edit, bash, always)')
+    .action((event: string, rawOpts: { route: string }) => {
+      const result = runHook({
+        event: event as HookEvent,
+        routeId: rawOpts.route as RouteId,
+      });
+      process.exit(result.exitCode);
+    });
+
+  program
+    .command('status')
+    .description('Show CLI version, host install status, route coverage, and repo opt-in state')
+    .option('--json', 'Output JSON instead of human-readable text')
+    .action((rawOpts: { json?: boolean }) => {
+      const report = runStatus();
+      console.log(formatStatus(report, rawOpts.json === true));
+      process.exit(0);
+    });
+
+  program
+    .command('doctor')
+    .description('Run read-only readiness diagnostics (PATH, version, hosts, trust state)')
+    .option('--json', 'Output JSON instead of human-readable text')
+    .action((rawOpts: { json?: boolean }) => {
+      const report = runDoctor();
+      console.log(formatDoctor(report, rawOpts.json === true));
+      process.exit(report.summary.fail > 0 ? 1 : 0);
+    });
+
+  program.addCommand(buildInitHookCommand());
+  program.addCommand(buildSetupCommand());
+
+  program
+    .command('migrate')
+    .description('Migrate legacy project-level hook adapters to the global CLI (dry-run by default)')
+    .option('--apply', 'Commit changes (default is dry-run)')
+    .option('--json', 'Output JSON plan')
+    .action((rawOpts: { apply?: boolean; json?: boolean }) => {
+      const plan = runMigrate({ apply: rawOpts.apply === true });
+      console.log(formatMigratePlan(plan, rawOpts.json === true));
+      process.exit(0);
+    });
+
+  const security = program
+    .command('security')
+    .description('Read-only security checks for local hook and editor task configs');
+  security
+    .command('scan')
+    .description('Scan Claude/Codex hook configs and VS Code folder-open tasks')
+    .option('--json', 'Output JSON instead of human-readable text')
+    .option('--strict', 'Exit non-zero when high-risk or failed findings are present')
+    .action((rawOpts: { json?: boolean; strict?: boolean }) => {
+      const report = runSecurityScan();
+      console.log(formatSecurityScan(report, rawOpts.json === true));
+      const strictFailure = report.findings.some((finding) => finding.severity === 'high' || finding.severity === 'fail');
+      process.exit(rawOpts.strict === true && strictFailure ? 1 : 0);
+    });
+
+  program.addCommand(buildToolsCommand());
+  program.addCommand(buildPluginCommand());
+  program.addCommand(buildBrainCommand());
+  program.addCommand(buildCapabilityContextCommand());
+  program.addCommand(buildDocsCommand());
+  program.addCommand(buildMcpCommand());
+  program.addCommand(buildChatgptCommand());
+  program.addCommand(buildRunCommand());
+  program.addCommand(buildControllerCommand());
+  program.addCommand(buildRepositoryCommand());
+  program.addCommand(buildRuntimeCommand());
+  program.addCommand(buildRecoveryCommand());
+  program
+    .command('prompt-guard-decide', { hidden: true })
+    .description('Internal prompt-guard intent/state decision engine')
+    .action(() => {
+      console.log(runPromptGuardDecideCli());
+      process.exit(0);
+    });
+
+  return program;
+}
+
+export async function runCli(argv: string[] = process.argv): Promise<void> {
+  const args = argv.slice(2);
+  if (args.length === 1 && (args[0] === '--version' || args[0] === '-V')) {
+    console.log(CLI_VERSION);
+    return;
+  }
+  await buildProgram().parseAsync(argv);
+}
+
+const isDirectExecution = import.meta.main === true
+  || Boolean(process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href);
+
+if (isDirectExecution) {
+  try {
+    await runCli(process.argv);
+  } catch (err) {
+    const e = err as { exitCode?: number; message?: string };
+    if (typeof e.exitCode === 'number') process.exit(e.exitCode);
+    if (e.message) console.error(e.message);
+    process.exit(1);
+  }
+}