forgedock 1.1.10 → 1.2.0

package/README.md

@@ -250,7 +250,7 @@ Then just open Claude Code and run `/work-on <issue>`.
 
 Commands then appear as `/forgedock:work-on`, etc. You still run `npx forgedock init` to generate `forge.yaml`.
 
-**Headless / CI:** the pipeline also runs outside Claude Code. `npx forgedock run work-on <issue> --dry-run` previews the assembled prompt and tool plan; with an `ANTHROPIC_API_KEY`, `npx forgedock run` drives the same command specs through a hardened tool-use loop, and `npx forgedock run-issue <issue>` executes them on the durable engine (event-sourced run log, leases, crash-safe resume).
+**Headless / CI:** the pipeline also runs outside Claude Code. `npx forgedock run work-on <issue> --dry-run` previews the assembled prompt and tool plan. `npx forgedock run` picks an execution backend automatically (`--backend auto`, the default): if the Claude Code CLI (`claude`) is installed and already authenticated (Pro/Max subscription or a CLI-managed key), it drives the command through that — **no separate `ANTHROPIC_API_KEY` required**. Otherwise it falls back to the Anthropic API directly (`ANTHROPIC_API_KEY` required). Force either path explicitly with `--backend cli` / `--backend api` (or `FORGEDOCK_BACKEND=cli|api`) — the API backend is what CI environments without an interactive `claude` login should use. `npx forgedock run-issue <issue>` executes the same command specs on the durable engine (event-sourced run log, leases, crash-safe resume).
 
 **Explicit install command:**
 

package/bin/cli-spawn-shared.mjs

@@ -0,0 +1,25 @@
+/**
+ * cli-spawn-shared.mjs — shared constants for `claude` CLI `spawnSync`
+ * invocations across the codebase.
+ *
+ * Extracted (issue #2032) to stop `maxBuffer: 50 * 1024 * 1024` from
+ * drifting independently at each spawn call site (bin/runner.mjs's
+ * `runCliBackend` and `run_bash`, bin/init-enrich-cli.mjs's `enrich()`) —
+ * all three invoke the same local `claude` CLI and should share one
+ * default rather than three copies of the same magic number.
+ *
+ * Isolated: imports no external modules, so it is safe to import from any
+ * module without creating a cycle.
+ */
+
+/**
+ * Default `maxBuffer` (bytes) for a `spawnSync` call against the local
+ * `claude` CLI. 50 MB comfortably covers a full headless response (stdout)
+ * plus any diagnostic stderr without risking silent truncation.
+ *
+ * `bin/runner.mjs`'s `run_bash` tool handler additionally allows this
+ * default to be overridden per-call via `FORGEDOCK_MAX_BUFFER_BYTES` — that
+ * override logic lives in `runner.mjs` itself; this constant is only the
+ * shared *default*.
+ */
+export const DEFAULT_SPAWN_MAX_BUFFER_BYTES = 50 * 1024 * 1024;

package/bin/engine-cli.mjs

@@ -224,6 +224,21 @@ export function lastLocalRun(dir) {
  * @param {{io?: {gh: Function}, runIssue?: Function}} [deps]
  *   Injectable for tests — defaults to real `gh`/`git` (makeIo()) and the real
  *   `runIssue` engine driver.
+ *
+ * Flags:
+ *   --lane <lane>          Required — e.g. `main` or `staging`.
+ *   --repo <owner/repo>    Optional — must match the cwd-resolved repo (forge#1593).
+ *   --backend <cli|api|auto>  Optional (forge#2028). Forwarded to every phase's
+ *                          `runCommand()` call. Omit to keep runner.mjs's own
+ *                          default ("auto" ladder — probes the `claude` CLI, falls
+ *                          back to the API). Mirrors `bin/forgedock.mjs`'s `run()`
+ *                          `--backend` semantics — validation (rejecting invalid
+ *                          values) is left to `runCommand()`'s own `resolveBackend()`
+ *                          rather than duplicated here.
+ *   --model <id>           Optional (forge#2028). Forwarded to every phase's
+ *                          `runCommand()` call; only applies on the "api" backend.
+ *                          Omit to keep runner.mjs's default (`FORGEDOCK_MODEL` env
+ *                          or its built-in default).
  */
 export async function runFromCli(argv, deps = {}) {
   const issue = parseInt(argv[0], 10);
@@ -231,12 +246,18 @@ export async function runFromCli(argv, deps = {}) {
   const lane = flag(argv, "--lane");
   if (!lane) throw new Error("--lane is required: e.g. --lane main or --lane staging. No default to prevent accidental production targeting.");
   const repo = flag(argv, "--repo");
+  const backend = flag(argv, "--backend");
+  const model = flag(argv, "--model");
   const io = deps.io ?? makeIo();
   await assertRepoMatchesCwd(io, repo);
   const runIssueFn = deps.runIssue ?? runIssue;
   const agentId = `cli_${process.pid}`;
   const res = await runIssueFn({ issue, dir: runDir(), agentId, lane, io,
-    runner: (await import("./runner.mjs")).runCommand, now: () => Date.now() });
+    runner: (await import("./runner.mjs")).runCommand, now: () => Date.now(),
+    // Only forwarded when explicitly provided — omitting them preserves
+    // runIssue's/runner.mjs's existing defaults (forge#2028).
+    ...(backend ? { backend } : {}),
+    ...(model ? { model } : {}) });
   console.log(`issue #${issue} → ${res.terminalReason}`);
   return res;
 }

package/bin/engine.mjs

@@ -8,13 +8,49 @@ import { appendEvent, readLog, deriveState, rewriteLog } from "./engine/runlog.m
 import { pickPhase, TERMINAL_REASONS } from "./engine/phases.mjs";
 import { reconcileState } from "./engine/reconcile.mjs";
 import { makeProjector } from "./engine/projector.mjs";
+import { VALID_BACKENDS } from "./runner.mjs";
 
 const DEFAULT_MAX_ATTEMPTS = 3;
 
+/**
+ * @param {object} opts
+ * @param {string} [opts.backend] - "cli" | "api" | "auto" (forge#2028). Forwarded
+ *   to every phase's `runner()` call when supplied. Omit to keep runner.mjs's own
+ *   default ("auto" ladder — probes the `claude` CLI, falls back to the API).
+ *   An invalid value throws synchronously (see below) rather than being forwarded.
+ * @param {string} [opts.model] - Model id (forge#2028). Forwarded to every phase's
+ *   `runner()` call when supplied; only applies on the "api" backend. Omit to keep
+ *   runner.mjs's default (`FORGEDOCK_MODEL` env or its built-in default).
+ */
 export async function runIssue(opts) {
   const { issue, dir, agentId, lane = "staging", io, runner,
           now = () => Date.now(), maxAttempts = DEFAULT_MAX_ATTEMPTS,
-          commandsDir = fileURLToPath(new URL("../commands", import.meta.url)) } = opts;
+          commandsDir = fileURLToPath(new URL("../commands", import.meta.url)),
+          // Optional execution-backend override for every phase's `runner()`
+          // call (forge#2028 / MAT-3). Left undefined by default so existing
+          // callers keep runner.mjs's own "auto" ladder default unchanged —
+          // this is purely additive pass-through, not a new default.
+          backend, model } = opts;
+
+  // forge#2054: validate `backend` before anything else — before state is
+  // read/written and before the phase/retry loop begins below. An invalid
+  // value must fail fast and non-retryably. Without this check, an invalid
+  // backend instead reaches runner.mjs's resolveBackend() deep inside
+  // runPhaseWithRetry()'s per-attempt try/catch, throws an uncoded Error, and
+  // is silently retried up to `maxAttempts` times (the catch there only
+  // fast-fails on `.code === "NO_API_KEY"/"NO_SDK"`) before escalating to
+  // needs-human — burning retries on what is actually a config error, not a
+  // transient phase failure. runIssue() is the single production choke point
+  // (its only caller is bin/engine-cli.mjs's runFromCli()), so validating
+  // here protects every current and future caller without requiring each one
+  // to remember to validate independently.
+  if (backend !== undefined && !VALID_BACKENDS.has(backend)) {
+    throw Object.assign(
+      new Error(`Invalid backend "${backend}". Must be one of: ${[...VALID_BACKENDS].join(", ")}.`),
+      { code: "INVALID_BACKEND" },
+    );
+  }
+
   const projector = makeProjector(io);
 
   // 1. Load + reconcile (GitHub wins).
@@ -67,7 +103,7 @@ export async function runIssue(opts) {
       outcome = { status: "committed", outputs: reconciled.outputs || {} };
     } else {
       if (reconciled.outputs?.pr) state.pr = reconciled.outputs.pr;
-      outcome = await runPhaseWithRetry(phase, state, { io, runner, dir, issue, commandsDir, maxAttempts });
+      outcome = await runPhaseWithRetry(phase, state, { io, runner, dir, issue, commandsDir, maxAttempts, backend, model });
     }
 
     if (outcome.status === "blocked") return await terminate(state, "needs-human", outcome.detail);
@@ -95,11 +131,17 @@ export async function runIssue(opts) {
 }
 
 async function runPhaseWithRetry(phase, state, ctx) {
-  const { io, runner, dir, issue, commandsDir, maxAttempts } = ctx;
+  const { io, runner, dir, issue, commandsDir, maxAttempts, backend, model } = ctx;
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     appendEvent(dir, issue, { event: "PHASE_START", phase: phase.id, attempt });
     try {
-      await runner({ commandsDir, commandName: phase.command, args: [String(issue)] });
+      await runner({
+        commandsDir, commandName: phase.command, args: [String(issue)],
+        // Only forwarded when explicitly provided — omitting them preserves
+        // runner.mjs's existing default ("auto" backend / DEFAULT_MODEL).
+        ...(backend ? { backend } : {}),
+        ...(model ? { model } : {}),
+      });
     } catch (e) {
       // A missing API key / SDK is a config error, not a transient phase
       // failure — surface it distinctly instead of burning retries and

package/bin/forgedock.mjs

@@ -28,6 +28,7 @@ import {
   parseInstallTier,
   writeForgeYaml,
   backupExisting,
+  backfillForgeYaml,
   manualLowConfidenceKeys,
   isEphemeralCachePath,
   writeInstallReceipt,
@@ -950,6 +951,21 @@ async function statusScreen(c) {
   c.stdout.write("\n");
 }
 
+/**
+ * `npx forgedock init` — detect + AI-enrich + review `forge.yaml`.
+ *
+ * AI enrichment backend selection (bin/init-enrich.mjs `resolveEnrichBackend`,
+ * issue #2004): prefers a local, authenticated `claude` CLI when present,
+ * otherwise falls back to the Anthropic API when ANTHROPIC_API_KEY is set,
+ * otherwise skips enrichment.
+ *
+ * Env:
+ *   FORGEDOCK_INIT_BACKEND   Override ("cli"|"api"|"none"|"auto"; default
+ *                            "auto") — pins the enrichment backend instead of
+ *                            the auto-detect ladder above (issue #2023).
+ *                            Independent of FORGEDOCK_BACKEND, which controls
+ *                            the separate `forgedock run` engine backend.
+ */
 async function initFlow(c) {
   const outputPath = join(c.cwd, "forge.yaml");
   const hasExisting = existsSync(outputPath);
@@ -1874,6 +1890,16 @@ async function doctor(fix = false) {
    * Reuses forge() (bin/journey.mjs) verbatim — the same repair path already
    * used by `npx forgedock update` (see relinkAndHint()) — rather than
    * duplicating symlink/copy-mode or hook-registration logic here.
+   *
+   * NOTE: `installRepairRan` only memoizes whether the repair primitive
+   * itself has executed during this invocation — it is a cross-check flag
+   * by necessity (any of the three checks below can trigger it, and it must
+   * not re-run for the other two). It must NOT be read by an individual
+   * check to decide whether THAT check was fixed — a check that was already
+   * healthy before a sibling check triggered repair would incorrectly
+   * report "repaired" too. Each check below tracks its own pre-repair
+   * broken state in a local `*WasBroken` variable for that decision instead.
+   * (forge#1975)
    */
   let installRepairRan = false;
   async function runInstallRepairOnce() {
@@ -1954,7 +1980,9 @@ async function doctor(fix = false) {
     }
 
     let cmdFiles = await detectCommandFiles();
+    let cmdFilesWasBroken = false;
     if (!cmdFiles.error && !cmdFiles.ok && fix) {
+      cmdFilesWasBroken = true;
       await runInstallRepairOnce();
       cmdFiles = await detectCommandFiles();
     }
@@ -1962,7 +1990,7 @@ async function doctor(fix = false) {
     if (cmdFiles.error) {
       fail("Command files", `Could not read commands directory: ${cmdFiles.error}`);
     } else if (cmdFiles.ok) {
-      if (fix && installRepairRan) {
+      if (fix && cmdFilesWasBroken) {
         fixed("Command files", `${cmdFiles.checked} files installed (repaired)`);
       } else {
         pass("Command files", `${cmdFiles.checked} files installed`);
@@ -2153,7 +2181,9 @@ async function doctor(fix = false) {
     }
 
     let hookReg = detectSessionStartHookRegistered();
+    let hookRegWasBroken = false;
     if (!hookReg.error && !hookReg.ok && fix) {
+      hookRegWasBroken = true;
       await runInstallRepairOnce();
       hookReg = detectSessionStartHookRegistered();
     }
@@ -2161,7 +2191,7 @@ async function doctor(fix = false) {
     if (hookReg.error) {
       fail("SessionStart hook", `Cannot read ~/.claude/settings.json: ${hookReg.error}. Run: npx forgedock install`);
     } else if (hookReg.ok) {
-      if (fix && installRepairRan) {
+      if (fix && hookRegWasBroken) {
         fixed("SessionStart hook", "registered in ~/.claude/settings.json (repaired)");
       } else {
         pass("SessionStart hook", "registered in ~/.claude/settings.json");
@@ -2221,7 +2251,9 @@ async function doctor(fix = false) {
   // ever surfaced. This check catches that silent-failure case. (forge#1895)
   {
     let hookPathResult = detectSessionStartHookPath();
+    let hookPathWasBroken = false;
     if (hookPathResult.state === "dangling" && fix) {
+      hookPathWasBroken = true;
       await runInstallRepairOnce();
       hookPathResult = detectSessionStartHookPath();
     }
@@ -2237,7 +2269,7 @@ async function doctor(fix = false) {
         `Could not parse a script path out of the registered hook command ("${hookPathResult.command}"). Run: npx forgedock install`,
       );
     } else if (hookPathResult.state === "ok") {
-      if (fix && installRepairRan) {
+      if (fix && hookPathWasBroken) {
         fixed("SessionStart hook script path", `refreshed to a valid path (${hookPathResult.path})`);
       } else {
         pass("SessionStart hook script path", `exists on disk (${hookPathResult.path})`);
@@ -2704,17 +2736,19 @@ function help() {
     ["npx forgedock enable [dir]", "Activate ForgeDock in a directory"],
     ["npx forgedock disable [dir]", "Opt a directory out of ForgeDock"],
     ["npx forgedock status [dir]", "Show ForgeDock state for a directory"],
-    ["npx forgedock run <cmd> [args]", "Run a command headlessly via the Anthropic API"],
+    ["npx forgedock run <cmd> [args]", "Run a command headlessly (local claude CLI or Anthropic API)"],
     ["npx forgedock run-issue <issue>", "Drive one issue through the durable engine"],
     ["npx forgedock resume-stalled [--dry-run]", "Fleet stall recovery — re-dispatch expired-lease issues"],
     ["npx forgedock demo", "Set up a risk-free demo repo and print next steps"],
     ["npx forgedock labels [setup] [--repo owner/repo]", "Bootstrap ForgeDock-managed labels on a GitHub repo (idempotent)"],
+    ["npx forgedock config migrate [dir]", "Backfill missing optional sections into an existing forge.yaml (idempotent)"],
     ["npx forgedock watch [--repo owner/repo]", "Live per-agent orchestration view (Ctrl+C to exit)"],
     ["npx forgedock report [--days 30] [--md] [--json]", "30-day pipeline impact receipts for your repo"],
     ["npx forgedock doctor", "Check installation health"],
     ["npx forgedock doctor --fix", "Auto-fix deterministic issues (symlinks, hook, labels, legacy block)"],
     ["npx forgedock update", "Pull latest & reinstall"],
     ["npx forgedock uninstall", "Remove commands"],
+    ["npx forgedock version", "Print the installed version and check for updates"],
     ["npx forgedock help", "Show this help"],
   ];
   const flagRows = [
@@ -2723,6 +2757,7 @@ function help() {
     ["--manual", "Plain text prompts instead of the review screen (init)"],
     ["--verbose", "Show detection sources for every field (init)"],
     ["--minimal", "Generate a minimal forge.yaml with required sections only (init)"],
+    ["--version, -v", "Print the installed version and check for updates"],
   ];
 
   process.stdout.write(
@@ -2735,46 +2770,88 @@ function help() {
 
 /**
  * `forgedock run <command> [args...]` — execute a ForgeDock command spec
- * directly via the Anthropic API, outside of Claude Code (headless / CI).
+ * headlessly, outside of an interactive Claude Code session (CI or local).
  *
  * Flags:
- *   --dry-run               Preview the assembled prompt + tool plan; no API call.
- *   --model <id>            Override the model (see resolution order below).
- *   --max-iterations <n>    Bound the tool-use loop (default: 50).
+ *   --dry-run                    Preview the assembled prompt + tool plan; no call made.
+ *   --model <id>                 Override the model (see resolution order below; api backend only).
+ *   --max-iterations <n>         Bound the tool-use loop (default: 50; api backend only).
+ *   --backend <cli|api|auto>     Execution backend (see below; default: auto).
  *
- * The live loop requires ANTHROPIC_API_KEY and the optional @anthropic-ai/sdk
- * dependency. The runtime itself lives in bin/runner.mjs.
+ * Two execution backends (issue #2003):
+ *   - "cli": shells out to the local Claude Code CLI (`claude --print ...`),
+ *     reusing whatever credentials it already has (Pro/Max OAuth or a
+ *     CLI-managed key). No ANTHROPIC_API_KEY needed. Requires `claude` on PATH.
+ *   - "api": drives the Anthropic SDK directly. Requires ANTHROPIC_API_KEY and
+ *     the optional @anthropic-ai/sdk dependency. Needed for CI/headless
+ *     environments without an interactively-authenticated `claude` CLI.
+ *   - "auto" (default): prefers "cli" when a working `claude` install is
+ *     detected, otherwise falls back to "api" unchanged — existing callers
+ *     that never pass --backend see no behavior change when `claude` isn't
+ *     installed.
  *
- * Model resolution order (highest precedence first):
+ * The runtime itself lives in bin/runner.mjs.
+ *
+ * Model resolution order (highest precedence first; api backend only — the
+ * cli backend uses whatever model the `claude` CLI itself is configured for):
  *   1. --model <id>                        This flag.
  *   2. $FORGEDOCK_MODEL                    Env var, below.
  *   3. forge.yaml `agents.default_model`   Read from the run's cwd, if present.
  *   4. Hardcoded default                   "claude-sonnet-5" (bin/runner.mjs DEFAULT_MODEL).
  *
  * Env:
- *   FORGEDOCK_MODEL   Default model id when --model is omitted.
- *   FORGEDOCK_SHELL   Override the shell used by run_bash. Defaults to bash when
- *                     found (Git Bash / WSL on Windows, /bin/bash on POSIX),
- *                     falling back to the platform default shell otherwise.
+ *   FORGEDOCK_BACKEND      Default backend ("cli"|"api"|"auto") when --backend is omitted.
+ *   FORGEDOCK_MODEL        Default model id when --model is omitted.
+ *   FORGEDOCK_CLI_TIMEOUT_MS  Wall-clock timeout (ms) for the cli backend invocation.
+ *   FORGEDOCK_SHELL        Override the shell used by run_bash / the cli backend.
+ *                          Defaults to bash when found (Git Bash / WSL on
+ *                          Windows, /bin/bash on POSIX), falling back to the
+ *                          platform default shell otherwise.
  */
 async function run() {
   const runArgs = restArgs;
   let dryRun = false;
   let model;
   let maxIterations;
+  let backend;
   const positional = [];
+  // Consume the value for a `--flag <value>` pair at index `idx` (the flag
+  // itself). Errors loudly instead of silently returning `undefined` when
+  // the flag is the last token or is immediately followed by another flag —
+  // both cases previously left the corresponding variable `undefined`,
+  // which downstream validation treats identically to "flag omitted",
+  // silently falling back to the default instead of erroring. Returns the
+  // consumed value; the caller is responsible for advancing its own loop
+  // index past the consumed token.
+  const requireFlagValue = (flagName, idx) => {
+    const value = runArgs[idx + 1];
+    if (value === undefined || value.startsWith("--")) {
+      process.stderr.write(
+        `${RED}Missing value for ${flagName}. Usage: ${flagName} <value>${RESET}\n`,
+      );
+      process.exit(1);
+    }
+    return value;
+  };
   for (let i = 0; i < runArgs.length; i++) {
     const a = runArgs[i];
     if (a === "--dry-run") {
       dryRun = true;
     } else if (a === "--model") {
-      model = runArgs[++i];
+      model = requireFlagValue("--model", i);
+      i++;
     } else if (a.startsWith("--model=")) {
       model = a.slice("--model=".length);
     } else if (a === "--max-iterations") {
-      maxIterations = parseInt(runArgs[++i], 10);
+      maxIterations = parseInt(requireFlagValue("--max-iterations", i), 10);
+      i++;
     } else if (a.startsWith("--max-iterations=")) {
       maxIterations = parseInt(a.slice("--max-iterations=".length), 10);
+    } else if (a === "--backend") {
+      backend = requireFlagValue("--backend", i);
+      i++;
+    } else if (a.startsWith("--backend=")) {
+      backend = a.slice("--backend=".length);
     } else {
       positional.push(a);
     }
@@ -2785,12 +2862,25 @@ async function run() {
 
   if (!commandName) {
     process.stderr.write(
-      `${RED}Usage: forgedock run <command> [args...] [--dry-run] [--model <id>] [--max-iterations <n>]${RESET}\n`,
+      `${RED}Usage: forgedock run <command> [args...] [--dry-run] [--model <id>] [--max-iterations <n>] [--backend <cli|api|auto>]${RESET}\n`,
+    );
+    process.exit(1);
+  }
+
+  // VALID_BACKENDS is imported from bin/runner.mjs (not re-hardcoded here) so
+  // this CLI-layer flag check and runner.mjs's own library-layer
+  // resolveBackend() validation can never structurally diverge on the set of
+  // accepted values or the wording of the resulting error message (issue
+  // #2013 — the two were previously independently-hardcoded Sets with
+  // near-identical but not-quite-matching error text).
+  const { runCommand, VALID_BACKENDS } = await import("./runner.mjs");
+  if (backend !== undefined && !VALID_BACKENDS.has(backend)) {
+    process.stderr.write(
+      `${RED}Invalid --backend "${backend}". Must be one of: ${[...VALID_BACKENDS].join(", ")}.${RESET}\n`,
     );
     process.exit(1);
   }
 
-  const { runCommand } = await import("./runner.mjs");
   try {
     const result = await runCommand({
       commandsDir: COMMANDS_DIR,
@@ -2802,6 +2892,7 @@ async function run() {
       ...(Number.isInteger(maxIterations) && maxIterations > 0
         ? { maxIterations }
         : {}),
+      ...(backend ? { backend } : {}),
     });
     // Treat a non-clean stop (iteration cap hit, or a max_tokens-truncated
     // turn) as a failed run so CI/headless callers notice.
@@ -3051,7 +3142,8 @@ async function watch() {
 const SPLASH_COMMANDS = new Set(["run", "run-issue", "resume-stalled", "demo", "doctor", "watch", "help", "--help", "-h"]);
 const KNOWN_COMMANDS = new Set([
   "install", "init", "enable", "disable", "status", "uninstall", "update",
-  "run", "run-issue", "resume-stalled", "demo", "doctor", "watch", "labels", "help", "--help", "-h",
+  "run", "run-issue", "resume-stalled", "demo", "doctor", "watch", "labels", "config", "help", "--help", "-h",
+  "version", "--version", "-v",
 ]);
 if (SPLASH_COMMANDS.has(command) || !KNOWN_COMMANDS.has(command)) splash(command);
 
@@ -3200,6 +3292,60 @@ switch (command) {
     }
     break;
   }
+  case "config": {
+    const subcommand = positional[1];
+    if (subcommand === "migrate") {
+      // Directory override mirrors `status [dir]` — defaults to cwd.
+      const dir = positional[2] ? resolve(positional[2]) : process.cwd();
+      const result = backfillForgeYaml(dir);
+      if (!result.present) {
+        console.log(
+          `${RED}No forge.yaml found in ${dir}.${RESET}\n` +
+            `  Run ${cyan("npx forgedock init")} to generate one.`,
+        );
+        exitCode = 1;
+      } else if (result.added.length === 0) {
+        console.log(
+          `${GREEN}forge.yaml already has all ${result.alreadyPresent.length} optional sections.${RESET} Nothing to migrate.`,
+        );
+      } else {
+        console.log(`${GREEN}Backfilled ${result.added.length} missing optional section(s) into forge.yaml:${RESET}`);
+        for (const key of result.added) console.log(`  ${GREEN}+${RESET} ${key}`);
+        console.log(`\n  Sections already present (unchanged): ${result.alreadyPresent.join(", ") || "none"}`);
+        console.log(`\n  All added sections are commented out — edit forge.yaml to enable the ones you need.`);
+      }
+    } else {
+      console.log(`${RED}Unknown config subcommand: ${subcommand ?? "(none)"}${RESET}`);
+      console.log(
+        `Usage: ${CYAN}npx forgedock config migrate [dir]${RESET}\n` +
+          `  Backfills any of the 16 optional forge.yaml sections missing from an existing config (idempotent).`,
+      );
+      exitCode = 1;
+    }
+    break;
+  }
+  case "version":
+  case "--version":
+  case "-v": {
+    // Print the local version immediately — must work offline/instantly,
+    // no network dependency for the primary output (getVersion() reads
+    // package.json off disk only). The latest-version check below is
+    // best-effort: fetchLatestVersion() has its own 5s timeout and never
+    // rejects, so a slow/offline network never blocks or fails this
+    // command. Mirrors the version-check message pattern already used by
+    // update() (see the npm/npx branch above).
+    const localVersion = getVersion();
+    console.log(`forgedock ${localVersion ? `v${localVersion}` : `${YELLOW}version unknown${RESET}`}`);
+
+    const latestVersion = await fetchLatestVersion();
+    if (latestVersion && localVersion && compareVersions(latestVersion, localVersion) > 0) {
+      console.log(
+        `  ${GREEN}New version available: v${latestVersion}${RESET} (you have v${localVersion}). ` +
+          `Run ${CYAN}npx forgedock update${RESET} to fetch it.`,
+      );
+    }
+    break;
+  }
   case "help":
   case "--help":
   case "-h":