forgedock 1.1.11 → 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

@@ -951,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);
@@ -2721,7 +2736,7 @@ 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"],
@@ -2755,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);
     }
@@ -2805,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,
@@ -2822,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.