@deeeed/metamask-harness 0.5.0 → 0.6.0

package/src/mm-harness-cli.ts

@@ -1,655 +0,0 @@
-// mm-harness — the single front door for the MetaMask recipe loop.
-//
-// This is the commander-based CLI entry (same stack as @farmslot/recipe-harness,
-// which depends on commander ^12). It presents ONLY the end-state surface
-// (docs/MENTAL-MODEL.md + docs/CLI-SPEC.md) and delegates to the dispatch in
-// `cli.ts` (`main`) so no orchestration logic is forked. Retired names still
-// teach; genuinely-unknown commands fall to commander's default.
-
-import { spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import { Command } from 'commander';
-
-import { color } from './cli-color.ts';
-import { handleUpdate, maybeNudge } from './commands/update.ts';
-
-// …/src → its parent is the package root that holds scripts/.
-const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-
-// Signal cli.ts NOT to auto-run its own dispatch when we import it below: we
-// reuse its `main` in-process. Must be set BEFORE the dynamic import runs the
-// module body. (A dynamic import guarantees ordering; a static import would hoist
-// and execute cli.ts first.)
-(globalThis as Record<string, unknown>).__MM_HARNESS_WRAPPER__ = true;
-const { main: recipeMain } = await import('./cli.ts');
-
-const rawArgv = process.argv.slice(2);
-
-// --- Surface definition (single source for both dispatch and grouped help) ----
-
-interface CliCommand {
-  name: string;
-  summary: string;
-  example: string;
-  /** Per-command flags help printed when the user passes --help / -h. */
-  helpText: string;
-}
-
-
-// Commands that route straight to the dispatch in cli.ts. `actions --raw` is the
-// one translation (raw manifest dump).
-const REAL: CliCommand[] = [
-  {
-    name: 'actions',
-    summary: 'List the action vocabulary + field schemas (--raw dumps the raw action registry JSON).',
-    example: 'mm-harness actions --adapter mobile',
-    helpText: `mm-harness actions [flags]
-
-  List the action vocabulary + field schemas for the checkout adapter.
-
-  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --raw                              Dump raw action registry JSON
-  --json                             Machine-readable output
-
-Example:
-  mm-harness actions --adapter mobile
-  mm-harness actions --adapter extension --raw`,
-  },
-  {
-    name: 'stop',
-    summary: 'Stop the dev server this checkout owns (mobile Metro / extension webpack watcher) and close its log window.',
-    example: 'mm-harness stop',
-    helpText: `mm-harness stop [flags]
-
-  Stop the dev server this checkout owns and close its tmux log-tail window,
-  scoped to this checkout so concurrent slots are untouched. Idempotent —
-  nothing running is success, not an error. Behavior is per platform:
-    mobile     stop the port-scoped Metro dev server
-    extension  stop the checkout's webpack watcher (pid file + orphan scan)
-    core       headless — no dev server to stop (teaching error)
-
-  --port <port>                      Dev-server port (default: the checkout's slot context)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable output
-
-Example:
-  mm-harness stop
-  mm-harness stop --port 8061`,
-  },
-  {
-    name: 'call',
-    summary: 'Run one action in isolation as a one-node recipe through the real engine path (fuzzy short names; --arg k=v; same trace/evidence as run).',
-    example: 'mm-harness call ensure_unlocked',
-    helpText: `mm-harness call <action> [--arg k=v ...] [flags]
-
-  Run one action in isolation as a one-node recipe through the real engine path.
-  Fuzzy short-name: 'ensure_unlocked' resolves to 'metamask.wallet.ensure_unlocked'
-  if unique; ambiguous = exit 2. Actions differ per adapter — list this checkout's
-  with: mm-harness actions.
-
-  --arg k=v                          Action field value (repeatable)
-  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --artifacts-dir <dir>              Where to write evidence (default: temp dir)
-  --action-manifest <path>           Override the action manifest
-  --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
-  --json                             Machine-readable output
-
-Example (real actions; run mm-harness actions for this checkout's full set):
-  mm-harness call ensure_unlocked --adapter extension   # a wallet action (extension/mobile)
-  mm-harness call command --arg cmd="echo hi" --adapter core   # the universal action (all adapters)`,
-  },
-  {
-    name: 'flows',
-    summary: 'Browse the reusable flow library (bare = list; `flows promote` publishes a flow up a tier). Resolves across libraries — personal > team > canonical, highest tier wins.',
-    example: 'mm-harness flows',
-    helpText: `mm-harness flows [flags]
-
-  Browse the reusable flow library. Flows resolve across libraries by precedence
-  (personal > team > canonical); the highest-tier copy wins and shadows lower ones.
-  Flow resolution is adapter-global, so there is no --adapter flag here.
-
-  --library <name=path>              Add/override a library source (repeatable)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable output
-
-Example:
-  mm-harness flows`,
-  },
-  {
-    name: 'run',
-    summary: 'Validate + run a recipe and write evidence (summary/trace/artifacts). --plan validates + prints the plan, touching nothing.',
-    example: 'mm-harness run recipe.json',
-    helpText: `mm-harness run <recipe.json> [flags]
-
-  Validate + run a recipe and write evidence (summary / trace / artifacts).
-
-  --plan                             Validate + print execution plan, touching nothing. Exit 5 if invalid.
-  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --artifacts-dir <dir>              Where to write evidence (required unless --plan)
-  --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
-  --json                             Machine-readable output
-  --record-video=full-run            Record a video of the run
-
-Example:
-  mm-harness run recipe.json --plan --adapter mobile
-  mm-harness run recipe.json --adapter extension --artifacts-dir ./out`,
-  },
-  {
-    name: 'doctor',
-    summary: 'Readiness check for a checkout — no app launch. --fix repairs the overlay/runtime without launching.',
-    example: 'mm-harness doctor',
-    helpText: `mm-harness doctor [flags]
-
-  Readiness check for a checkout — no app launch. Reports the fixture and runtime-context
-  sections so there is no hunting for files.
-
-  --fix                              Repair the overlay/runtime-context WITHOUT launching (no fixture reseed); --json adds fixed[]/failed[]
-  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable output
-
-Example:
-  mm-harness doctor
-  mm-harness doctor --fix --json
-  mm-harness doctor --adapter mobile --target /path/to/checkout`,
-  },
-  {
-    name: 'provision',
-    summary: 'Install the cached Runway iOS dev client on a prepared mobile slot (no deps, no Metro).',
-    example: 'mm-harness provision runway ios --adapter mobile',
-    helpText: `mm-harness provision [runway ios] [flags]
-
-  Install the cached Runway iOS dev client on the slot simulator. This is a thin
-  provisioning path only: artifact cache + simulator create + simctl install.
-  JavaScript dependencies and Metro remain dispatch-time launch concerns.
-
-  --adapter <mobile|extension|core>  Target adapter (mobile supported; extension/core teach)
-  --target <path>                    Slot checkout path (default: cwd)
-  --platform <ios>                   Platform (default ios)
-  --simulator <name|udid>            Override agentic-runtime.json simulator (alias: --device)
-  --device <name|udid>               Alias for --simulator
-  --slot <id>                        Farm slot id recorded in the provision baseline
-  --watcher-port <port>              Farm Metro/watcher port carried through context and Next:
-  --runtime-dir <dir>                Runtime dir containing agentic-runtime.json (relative to target)
-  --runtime <id>                     iOS runtime id used if simulator must be created
-  --device-type <id>                 Device type id used if simulator must be created
-  --branch <ref>                     Probe this ref before default branch
-  --default-branch <ref>             Fallback ref (default main)
-  --run <id>                         Exact GitHub Actions run id
-  --cache-root <dir>                 Override shared runway cache root
-  --force                            Reinstall even when the app is already present
-  --resolve-only                     Resolve artifact metadata only; no simulator/cache/install
-  --json                             Machine-readable envelope; progress stays stderr
-
-Example:
-  mm-harness provision runway ios --adapter mobile --target /path/to/slot
-  mm-harness provision runway ios --adapter mobile --slot scratch-1 --runtime-dir temp/recipe/runtime-8081
-  mm-harness provision runway ios --run 28676856835 --resolve-only --json`,
-  },
-  {
-    name: 'install',
-    summary: 'Install the per-checkout runtime overlay, or --runway to install a cached mobile dev client.',
-    example: 'mm-harness install',
-    helpText: `mm-harness install [flags]
-
-  Install the per-checkout runtime overlay (for CI / agents).
-  Add --runway on a mobile slot to install the cached Runway iOS dev client only:
-  artifact cache + simulator create + simctl install. JavaScript dependencies
-  and Metro remain dispatch-time launch concerns.
-
-  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --runway                           Thin mobile Runway artifact install instead of overlay install
-  --platform <ios>                   Runway platform (default ios)
-  --simulator <name|udid>            Override agentic-runtime.json simulator
-  --runtime <id>                     iOS runtime id used if simulator must be created
-  --device-type <id>                 Device type id used if simulator must be created
-  --branch <ref>                     Probe this ref before default branch
-  --default-branch <ref>             Fallback ref (default main)
-  --run <id>                         Exact GitHub Actions run id
-  --cache-root <dir>                 Override shared runway cache root
-  --force                            Reinstall even when the app is already present
-  --resolve-only                     Runway metadata only; no simulator/cache/install
-
-Example:
-  mm-harness install
-  mm-harness install --adapter extension --target /path/to/checkout
-  mm-harness install --runway --adapter mobile --target /path/to/slot`,
-  },
-  {
-    name: 'verify',
-    summary: 'Check the overlay/runtime is present and healthy (no launch).',
-    example: 'mm-harness verify',
-    helpText: `mm-harness verify [flags]
-
-  Check the runtime overlay is present and healthy (no app launch).
-
-  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable output
-
-Example:
-  mm-harness verify
-  mm-harness verify --adapter core --target /path/to/checkout`,
-  },
-  {
-    name: 'cleanup',
-    summary: 'Remove the installed overlay and restore the checkout.',
-    example: 'mm-harness cleanup',
-    helpText: `mm-harness cleanup [flags]
-
-  Remove the installed overlay and restore the checkout.
-
-  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-
-Example:
-  mm-harness cleanup
-  mm-harness cleanup --adapter mobile --target /path/to/checkout`,
-  },
-  {
-    name: 'launch',
-    summary: 'Launch the app (Metro/build + boot), auto-ensuring the runtime overlay first. Mobile: ios|android required.',
-    example: 'mm-harness launch ios',
-    helpText: `mm-harness launch [ios|android] [flags]
-
-  Launch the app — quick relaunch by default; --build for a full native/webpack build.
-  Mobile: target is MANDATORY (ios | android). Extension: no target (--fullscreen default;
-  --sidepanel to override). core is headless (teaching error — use verify/run).
-
-  --build                            Full native/webpack build tier (default = quick relaunch)
-  --verify                           Launch then poll CDP/bridge until ready (absorbs the old \`live\`)
-  --runway                           Post-launch runway check (mobile only; teaching error elsewhere)
-  --watch                            Persistent webpack watcher then relaunch (extension only)
-  --sidepanel | --fullscreen         Extension display mode (default --fullscreen)
-  --heal <off|infra-only|auto>       Healing policy (default auto); bounds always enforced
-  --device <udid|name>               Target simulator/device (env: IOS_SIMULATOR / ADB_SERIAL)
-  --cdp-port <port>                  Extension CDP port (env: CDP_PORT / RECIPE_CDP_PORT)
-  --watcher-port <port>              Metro/webpack port (env: WATCHER_PORT / METRO_PORT)
-  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable summary (recovered[] / mutations[] / phase)
-
-Example:
-  mm-harness launch ios
-  mm-harness launch ios --build
-  mm-harness launch --verify --json`,
-  },
-  {
-    name: 'logs',
-    summary: 'Tail Metro/webpack + app logs for the active checkout.',
-    example: 'mm-harness logs',
-    helpText: `mm-harness logs [flags]
-
-  Tail Metro/webpack + app logs for the active checkout.
-  Teaching error if nothing is running (points at launch).
-
-  --full                             Raw log tail (default = compact) (env: RECIPE_LOG_UI)
-  --events <n>                       Compact event count (default 10) (env: RECIPE_LOG_EVENTS)
-  --source <label>                   Log source per adapter — mobile: metro|app (default metro);
-                                     extension: webpack|watcher|rebuild|app (default webpack).
-                                     Core is headless (teaching error).
-  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable output
-
-Example:
-  mm-harness logs
-  mm-harness logs --full`,
-  },
-  {
-    name: 'debug',
-    summary: 'Open the debug console — extension: Chrome DevTools via CDP; mobile: RN DevTools.',
-    example: 'mm-harness debug',
-    helpText: `mm-harness debug [flags]
-
-  Open the debug console — extension: Chrome DevTools via CDP; mobile: RN DevTools.
-
-  --worker                           Extension service-worker DevTools
-  --dev-menu                         Mobile RN developer menu
-  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable output
-
-Example:
-  mm-harness debug
-  mm-harness debug --worker`,
-  },
-  {
-    name: 'update',
-    summary: 'Update the installed mm-harness to the published latest (--check reports only; --json = {current, latest, updateAvailable}).',
-    example: 'mm-harness update',
-    helpText: `mm-harness update [flags]
-
-  Update the globally-installed mm-harness to the npm registry's latest.
-  Bare form upgrades (npm i -g @deeeed/metamask-harness@latest) and prints old → new;
-  already-current exits 0.
-
-  --check                            Report only — exit 0 up-to-date / exit 1 update available (no install)
-  --json                             Machine-readable { current, latest, updateAvailable }
-
-  A passive once-a-day nudge also prints one stderr line when a newer version exists.
-  Silence it with MM_HARNESS_NO_UPDATE_CHECK=1 (auto-off in CI).
-
-Example:
-  mm-harness update
-  mm-harness update --check --json`,
-  },
-  {
-    name: 'fixtures',
-    summary: 'Manage the canonical wallet fixture (wallet DATA only) — sync files / set the wallet.',
-    example: 'mm-harness fixtures set',
-    helpText: `mm-harness fixtures <sync|set> [flags]
-
-  Manage the ONE canonical wallet fixture per checkout — wallet DATA only.
-  sync   Refresh the wallet fixture files on the target.
-  set    Apply the canonical fixture (SRP/password/accounts); the password is read
-         FROM the fixture, never typed.
-  Want different accounts? Edit the fixture file directly:
-    <checkout>/temp/recipe/runtime/wallet-fixture.json
-
-  --fixture <path>                   Override the fixture path (agent form; env: RECIPE_WALLET_FIXTURE)
-  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable output
-
-Example:
-  mm-harness fixtures sync
-  mm-harness fixtures set`,
-  },
-];
-
-// Retired names: NOT on the surface, but they must TEACH rather than fall to
-// commander's generic "unknown command" path. Each names its replacement and
-// exits 2 (bad-args/unsupported, distinct from a genuinely-unknown command's
-// exit 1). Genuinely-unknown commands stay on commander's default (which points
-// at --help via showHelpAfterError).
-interface RetiredCommand {
-  name: string;
-  message: string;
-}
-
-const RETIRED_INTERNAL = [
-  'runtime-health',
-  'runtime-decision',
-  'runtime-launch',
-  'resolve-extension',
-  'ensure-ready',
-  'self-test',
-];
-
-const RETIRED: RetiredCommand[] = [
-  {
-    name: 'live',
-    message:
-      `mm-harness live is retired (exit 2).\n\n` +
-      `Replacement: mm-harness launch --verify (install overlay → launch → CDP/bridge poll → smoke verify).`,
-  },
-  {
-    name: 'manifest',
-    message:
-      `mm-harness manifest is retired (exit 2).\n\n` +
-      `Replacement: mm-harness actions --raw   (works now — dumps the raw action registry JSON,\n` +
-      `identical to the old \`manifest --json\`). Manifest validation moved into doctor / run --plan.`,
-  },
-  ...RETIRED_INTERNAL.map((name) => ({
-    name,
-    message:
-      `mm-harness ${name} is retired (exit 2).\n\n` +
-      `It is internal now — its logic lives inside doctor / launch / verify self-healing.\n` +
-      `Use: mm-harness doctor`,
-  })),
-];
-
-// --- Grouped help (custom formatHelp; commander owns parse/dispatch) ---------
-
-interface HelpGroup {
-  title: string;
-  blurb: string;
-  commands: string[];
-}
-
-const HELP_GROUPS: HelpGroup[] = [
-  {
-    title: 'DAILY LOOP',
-    blurb: 'what a teammate runs many times a day (auto-ensures the overlay; --heal owns recovery)',
-    commands: ['launch', 'stop', 'logs', 'debug', 'fixtures'],
-  },
-  {
-    title: 'DISCOVER',
-    blurb: 'compose recipes from the action vocabulary + flow library (--json is the agent-primary form)',
-    commands: ['actions', 'call', 'flows'],
-  },
-  {
-    title: 'PROVE',
-    blurb: 'run recipes and inspect readiness',
-    commands: ['run', 'doctor'],
-  },
-  {
-    title: 'RUNTIME OVERLAY',
-    blurb: 'install/verify/clean the overlay, plus thin mobile slot provisioning',
-    commands: ['provision', 'install', 'verify', 'cleanup'],
-  },
-  {
-    title: 'MAINTAIN',
-    blurb: 'keep the installed harness current with the npm registry',
-    commands: ['update'],
-  },
-];
-
-function commandMeta(name: string): { summary: string; example: string; planned: boolean } {
-  const real = REAL.find((command) => command.name === name);
-  if (real) return { summary: real.summary, example: real.example, planned: false };
-  return { summary: '', example: '', planned: false };
-}
-
-// Slot context the orchestrator's prepare wrote into the checkout, when the
-// help is run from inside one. Presence-gated: no context, no line.
-function detectedSlotLine(out: (style: string, text: string) => string): string | null {
-  const ctxPath = path.join(
-    process.cwd(),
-    process.env.RECIPE_RUNTIME_DIR || 'temp/recipe/runtime',
-    'agentic-runtime.json',
-  );
-  try {
-    const ctx = JSON.parse(fs.readFileSync(ctxPath, 'utf8')) as Record<string, unknown>;
-    const parts: string[] = [];
-    if (ctx.slotId) parts.push(`slot ${out('ok', String(ctx.slotId))}`);
-    if (ctx.simulator) parts.push(`device ${out('ok', String(ctx.simulator))}`);
-    if (ctx.metroPort) parts.push(`metro :${out('ok', String(ctx.metroPort))}`);
-    if (ctx.gitBranch) parts.push(`branch ${out('info', String(ctx.gitBranch))}`);
-    if (parts.length === 0) return null;
-    return `${out('label', 'SLOT')} — this checkout is a prepared slot: ${parts.join(' · ')}`;
-  } catch {
-    return null;
-  }
-}
-
-function groupedHelp(): string {
-  const out = (style: string, text: string) => color(style, text, { stream: process.stdout });
-  const lines: string[] = [];
-  lines.push(`${out('bold', 'mm-harness')} — one front door for the MetaMask recipe loop: launch the app, prove behavior, manage the runtime overlay.`);
-  lines.push('Run it from inside a MetaMask checkout; the platform (mobile | extension | core) is auto-detected.');
-  lines.push(`Grammar: ${out('cmd', 'mm-harness <command> [target] [flags]')}   (target is a positional: ios | android; flags add agent depth; --json is the agent contract)`);
-  if (process.env.MM_HARNESS_BIN) {
-    lines.push('');
-    lines.push(`${out('warn', 'DEV OVERRIDE ACTIVE')} — this run is served by MM_HARNESS_BIN=${out('path', process.env.MM_HARNESS_BIN)} (unset it to return to the installed/global bin).`);
-  }
-  const slotLine = detectedSlotLine(out);
-  if (slotLine) {
-    lines.push('');
-    lines.push(slotLine);
-  }
-  for (const group of HELP_GROUPS) {
-    lines.push('');
-    lines.push(`${out('label', group.title)} — ${group.blurb}:`);
-    for (const name of group.commands) {
-      const meta = commandMeta(name);
-      const planned = meta.planned ? '   (planned)' : '';
-      lines.push(`  ${out('cmd', name.padEnd(10))} ${meta.summary}${planned}`);
-      lines.push(`               ${out('comment', meta.example)}`);
-    }
-  }
-  lines.push('');
-  lines.push('ONE bin: mm-harness is the only command. Platform is auto-detected; the positional target forces it');
-  lines.push('(mm-harness launch ios); platform-specific needs are FLAGS on the same command. Human happy path = the bare');
-  lines.push('command; agents add depth via flags (--json, --target, ports).');
-  lines.push('');
-  lines.push('SETUP — tab-completion (zsh + bash), sourced from the bundled scripts:');
-  lines.push('  mm-harness completions install   # print the lines to add to ~/.zshrc / ~/.bashrc');
-  lines.push('');
-  lines.push('DEV/PROD — the global npm install is prod; set MM_HARNESS_BIN to a dev checkout to override:');
-  lines.push('  MM_HARNESS_BIN=/path/to/checkout/bin/mm-harness   # unset = the installed/global bin');
-  lines.push('');
-  lines.push('See docs/MENTAL-MODEL.md (overview) and docs/CLI-SPEC.md (full contract).');
-  return `${lines.join('\n')}\n`;
-}
-
-// --- Delegation -------------------------------------------------------------
-
-async function delegate(argv: string[]): Promise<number> {
-  try {
-    return await recipeMain(argv);
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    // CliError (from cli.ts) carries an exitCode so usage errors (2) and
-    // validation errors (5) propagate correctly rather than always returning 1.
-    return error !== null &&
-      typeof error === 'object' &&
-      'exitCode' in error &&
-      typeof (error as Record<string, unknown>).exitCode === 'number'
-      ? (error as { exitCode: number }).exitCode
-      : 1;
-  }
-}
-
-// `actions --raw` == the retired `manifest --adapter <p> --json` raw dump.
-function translateActionsRaw(argv: string[]): string[] {
-  const rest = argv.slice(1).filter((arg) => arg !== '--raw');
-  const withJson = rest.includes('--json') ? rest : [...rest, '--json'];
-  return ['manifest', ...withJson];
-}
-
-// --- Program ----------------------------------------------------------------
-
-const program = new Command();
-program
-  .name('mm-harness')
-  .description('the MetaMask recipe harness: launch the app, prove behavior, manage the runtime overlay')
-  .helpOption('-h, --help', 'Show grouped help')
-  .showHelpAfterError('(run `mm-harness --help` for the full surface)')
-  .configureHelp({ formatHelp: () => groupedHelp() });
-
-for (const command of REAL) {
-  program
-    .command(command.name)
-    .description(command.summary)
-    .allowUnknownOption()
-    .helpOption(false)
-    .argument('[args...]')
-    .action(async () => {
-      // Intercept --help / -h before delegation: the hand-rolled parser in cli.ts
-      // treats unknown flags as value-consuming and throws "Missing value for --help".
-      // Each command exposes its own flags via helpText; exit 0 so shell completion
-      // and tooling work correctly.
-      // Only check flags BEFORE the `--` separator so `install -- --help` correctly
-      // forwards --help to the underlying install script rather than intercepting it.
-      const ddIdx = rawArgv.indexOf('--');
-      const flagsBeforeSep = ddIdx === -1 ? rawArgv : rawArgv.slice(0, ddIdx);
-      if (flagsBeforeSep.includes('--help') || flagsBeforeSep.includes('-h')) {
-        process.stdout.write(`${command.helpText}\n`);
-        process.exit(0);
-      }
-      // `update` is self-contained registry tooling (no engine, no overlay), so it
-      // runs directly rather than through the dispatch in cli.ts.
-      if (command.name === 'update') {
-        process.exit(await handleUpdate(rawArgv.slice(1)));
-      }
-      const argv = command.name === 'actions' && rawArgv.includes('--raw') ? translateActionsRaw(rawArgv) : rawArgv;
-      process.exit(await delegate(argv));
-    });
-}
-
-// Hidden commands: real routing, but intentionally absent from the grouped help.
-// `completion-candidates <actions|flows>` is what the shell completion scripts
-// source; humans never type it.
-const HIDDEN: readonly string[] = ['completion-candidates'];
-for (const name of HIDDEN) {
-  program
-    .command(name, { hidden: true })
-    .allowUnknownOption()
-    .helpOption(false)
-    .argument('[args...]')
-    .action(async () => {
-      process.exit(await delegate(rawArgv));
-    });
-}
-
-// `completions` installs/prints the bundled zsh + bash tab-completion. It is
-// shell tooling (no engine), so it runs the bundled installer script directly
-// rather than routing through the dispatch in cli.ts.
-program
-  .command('completions')
-  .description('Install/print bundled shell tab-completion (zsh + bash)')
-  .allowUnknownOption()
-  .helpOption(false)
-  .argument('[args...]')
-  .action(() => {
-    const script = path.join(packageRoot, 'scripts', 'install-completions.sh');
-    const result = spawnSync('bash', [script, ...rawArgv.slice(1)], { stdio: 'inherit' });
-    process.exit(result.status ?? 1);
-  });
-
-// Retired names teach their replacement and exit 2 (not commander's generic
-// "unknown command" exit 1). They are NOT listed in the grouped help.
-for (const retired of RETIRED) {
-  program
-    .command(retired.name)
-    .description(`${retired.name} is retired (see teaching error)`)
-    .allowUnknownOption()
-    .helpOption(false)
-    .argument('[args...]')
-    .action(async () => {
-      // `live --adapter mobile` (or android) is handled in-process via handleMobileLive.
-      // All other `live` invocations still teach the replacement.
-      if (retired.name === 'live') {
-        const adapterIdx = rawArgv.indexOf('--adapter');
-        const aliasIdx = rawArgv.indexOf('-a');
-        const adapterVal =
-          adapterIdx !== -1
-            ? rawArgv[adapterIdx + 1]
-            : aliasIdx !== -1
-              ? rawArgv[aliasIdx + 1]
-              : undefined;
-        if (adapterVal === 'mobile' || adapterVal === 'android') {
-          process.exit(await delegate(rawArgv));
-          return;
-        }
-      }
-      console.error(retired.message);
-      process.exit(2);
-    });
-}
-
-// Passive update nudge: one throttled stderr line if a newer version is published.
-// Skipped for update itself (redundant) and for shell/completion tooling (whose
-// stdout is consumed by the shell). stderr-only keeps every --json stdout clean.
-const NUDGE_SKIP: readonly string[] = ['update', 'completions', 'completion-candidates'];
-if (rawArgv.length > 0 && !NUDGE_SKIP.includes(rawArgv[0])) {
-  // Fully deferred: no nudge code runs before parseAsync starts. The exit hook
-  // registered inside maybeNudge prints the line after command output.
-  setImmediate(() => void maybeNudge());
-}
-
-if (rawArgv.length === 0) {
-  process.stdout.write(groupedHelp());
-  process.exit(0);
-}
-
-await program.parseAsync(process.argv);