forgedock 1.6.0 → 1.7.1

package/README.md

@@ -56,7 +56,7 @@ $ /work-on #1230        "orchestrate: Layer 5 co-change signal is dead code"
 
 ### Try it in 30 seconds — on a throwaway repo, nothing to lose
 
-**Requires:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (subscription or `ANTHROPIC_API_KEY`) · [GitHub CLI](https://cli.github.com/) (authenticated) · Node.js ≥ 18.
+**Requires for this demo:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (subscription or `ANTHROPIC_API_KEY`) · [GitHub CLI](https://cli.github.com/) (authenticated) · Node.js ≥ 18.
 
 ```bash
 npx forgedock demo     # spins up a risk-free demo repo and shows you the pipeline end to end
@@ -224,12 +224,24 @@ More ship today (web-property analytics, browser QA sweeps, self-benchmarking)
 
 ## Install
 
-**Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) · [GitHub CLI](https://cli.github.com/) (authenticated) · Node.js ≥ 18.
+**Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [OpenCode](https://opencode.ai/) · [GitHub CLI](https://cli.github.com/) (authenticated) · Node.js ≥ 18.
 
 ```bash
 npx forgedock # checks your environment, installs commands into ~/.claude/commands/ (available in every Claude Code session on this machine), detects your repo, and hands you a reviewed forge.yaml
 ```
 
+For OpenCode, install namespaced native commands without changing your provider
+or user-owned settings. When migrating an older ForgeDock adapter, it removes
+only exact ForgeDock-managed legacy entries from `opencode.json`:
+
+```bash
+npx forgedock opencode install
+# restart OpenCode, then: /forge/work-on <issue>
+```
+
+See [OpenCode support](docs/OPENCODE.md) for architecture, token-loading rules,
+current parity boundaries, and lifecycle commands.
+
 **Install is always global**, to `~/.claude/commands/`. `--global` is still accepted on the command line for backward compatibility but has no effect — there's no other install location to opt out of.
 
 > **Want engine-mode dispatch?** `npx forgedock` is transient — the `forgedock` binary isn't persisted in PATH after install. `/orchestrate` and `/autopilot` use agent dispatch mode by default, which is fully functional. To enable engine-mode dispatch (`forgedock run-issue`) with its durable phase table and fail-closed review gate, run `npm install -g forgedock` instead.

package/bin/engine/orchestrate-canary.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * CLI contract for the standing-query re-resolution canary in the orchestrator.
+ */
+import { shouldReResolve } from "./resolve.mjs";
+
+const [kind, pattern, enabled, maxRounds, rounds] = process.argv.slice(2);
+
+const classified = { kind, pattern, args: [] };
+const config = {
+  enabled: enabled === "false" ? false : enabled,
+  maxRounds: maxRounds === "unbounded" ? undefined : Number(maxRounds),
+};
+
+process.stdout.write(`${JSON.stringify(shouldReResolve(classified, config, Number(rounds)))}\n`);

package/bin/engine/orchestrate-canary.test.mjs

@@ -0,0 +1,28 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const canary = join(here, "orchestrate-canary.mjs");
+
+function runCanary(...args) {
+  const result = spawnSync(process.execPath, [canary, ...args], { encoding: "utf8" });
+  assert.equal(result.status, 0, result.stderr);
+  return JSON.parse(result.stdout);
+}
+
+describe("orchestrate re-resolution canary CLI", () => {
+  it("re-resolves a query with the documented argument contract", () => {
+    assert.deepEqual(runCanary("query", "priority", "true", "unbounded", "0"), {
+      reResolve: true,
+      reason: 'query pattern "priority" is a standing predicate — re-resolving',
+    });
+  });
+
+  it("preserves literal-set and max-round termination", () => {
+    assert.equal(runCanary("literal", "literal-numbers", "true", "3", "0").reResolve, false);
+    assert.equal(runCanary("query", "milestone", "true", "3", "3").reResolve, false);
+  });
+});

package/bin/engine-cli.mjs

@@ -12,6 +12,7 @@ import { join } from "node:path";
 import { runIssue, DEFAULT_MAX_ATTEMPTS } from "./engine.mjs";
 import { makeProjector } from "./engine/projector.mjs";
 import { readLog, deriveState } from "./engine/runlog.mjs";
+import { assertOpenCodeNativeRuntime } from "./runner.mjs";
 
 /**
  * Workflow labels that mark an issue as "in the pipeline" (not yet terminal).
@@ -340,6 +341,7 @@ export function lastLocalRun(dir) {
 export async function runFromCli(argv, deps = {}) {
   const issue = parseInt(argv[0], 10);
   if (!Number.isInteger(issue)) throw new Error("usage: forgedock run-issue <issue-number> --lane <lane>");
+  assertOpenCodeNativeRuntime({ operation: "forgedock run-issue" });
   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");

package/bin/forgedock.mjs

@@ -416,6 +416,40 @@ function getVersion() {
   }
 }
 
+/**
+ * Read the branch that owns the source currently being executed.
+ *
+ * This is deliberately best-effort: diagnostics should still identify the
+ * source path and version when the checkout has no readable branch ref.
+ *
+ * @param {string} [dir]
+ * @returns {string|null}
+ */
+function getGitBranch(dir = FORGE_HOME) {
+  try {
+    const branch = execFileSync(
+      "git",
+      ["rev-parse", "--abbrev-ref", "HEAD"],
+      { cwd: dir, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] },
+    ).trim();
+    return branch || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Describe the source path the current CLI process resolves from.
+ *
+ * @param {string|null} [branch]
+ * @returns {string}
+ */
+function formatSourceIdentity(branch = null) {
+  const version = getVersion() || "unknown";
+  const branchLabel = branch ? `, branch ${branch}` : "";
+  return `${FORGE_HOME} (v${version}${branchLabel})`;
+}
+
 /**
  * Compare two dotted version strings component-wise (numeric, not
  * lexicographic — "1.9.0" must compare as older than "1.10.0").
@@ -1330,11 +1364,51 @@ async function uninstall() {
   console.log("");
 }
 
-// Reinstall = relink commands + re-register the hook. Never the full
-// journey: update must not reach read/review, which could overwrite a
-// curated forge.yaml (and re-runs AI enrichment on every update). Also
-// idempotent, so it's the repair path for a configured repo whose
-// symlinks or hook registration got out of sync.
+// Reinstall = relink commands + re-register the hook + refresh an already
+// installed OpenCode adapter. Never the full journey: update must not reach
+// read/review, which could overwrite a curated forge.yaml (and re-runs AI
+// enrichment on every update). Also idempotent, so it's the repair path for a
+// configured repo whose symlinks, hook registration, or managed OpenCode files
+// got out of sync.
+async function refreshManagedOpenCodeAdapter() {
+  try {
+    const { getOpenCodeAdapterStatus, installOpenCodeAdapter } = await import("./opencode-adapter.mjs");
+    const status = await getOpenCodeAdapterStatus({ home: HOME, env: process.env });
+    if (!status.installed) return;
+
+    // npm/npx payloads must be persisted before the generated adapter points at
+    // them; git-clone installs are already stable and persistHome returns them
+    // unchanged.
+    const persisted = await persistHome(ctx());
+    const adapterForgeHome = persisted.forgeHome || FORGE_HOME;
+    if (adapterForgeHome === FORGE_HOME && isEphemeralCachePath(FORGE_HOME)) {
+      console.log(
+        `  ${YELLOW}OpenCode adapter refresh skipped: the current ForgeDock payload is ephemeral.${RESET}`,
+      );
+      return;
+    }
+
+    const result = await installOpenCodeAdapter({
+      forgeHome: adapterForgeHome,
+      home: HOME,
+      env: process.env,
+      includeExtras: status.manifest?.includeExtras === true,
+    });
+    console.log(
+      `  ${GREEN}Refreshed managed OpenCode adapter (${result.commandCount} commands, ${result.skillCount} skills).${RESET}`,
+    );
+    for (const warning of result.migration.warnings) {
+      console.log(`  ${YELLOW}OpenCode adapter warning: ${warning}${RESET}`);
+    }
+  } catch (error) {
+    // OpenCode refresh is best-effort, matching the existing update/relink
+    // behavior: a permissions or ownership problem must not block Claude users.
+    console.log(
+      `  ${YELLOW}Could not refresh the managed OpenCode adapter: ${error?.message || String(error)}${RESET}`,
+    );
+  }
+}
+
 async function relinkAndHint() {
   const c = ctx();
   const forged = await forge(c);
@@ -1346,6 +1420,7 @@ async function relinkAndHint() {
   // (that path calls statusScreen(), never relinkAndHint()) — see the
   // writeInstallReceipt() JSDoc in journey.mjs for the full picture.
   await writeInstallReceipt(c, { forged });
+  await refreshManagedOpenCodeAdapter();
   if (!existsSync(join(c.cwd, "forge.yaml"))) {
     const dim = (s) => (c.mode === "none" ? s : `\x1b[2m${s}\x1b[22m`);
     c.stdout.write("  " + dim("Configure this repo: npx forgedock init") + "\n");
@@ -1808,24 +1883,18 @@ async function update() {
     const separateGlobalInstall = findSeparateGlobalInstall();
     if (separateGlobalInstall) {
       console.log(
-        `  ${YELLOW}Note: this updates the git clone above. Your global npm install at ${separateGlobalInstall} was NOT touched.${RESET}`,
+        `  ${YELLOW}Note: this command resolves to the git clone above. Your global npm install at ${separateGlobalInstall} is NOT touched.${RESET}`,
       );
       console.log(
         `  ${YELLOW}Run 'npm update -g forgedock', or 'npx forgedock update' from outside a clone, to update it.${RESET}`,
       );
     }
     try {
-      const branch = execSync("git rev-parse --abbrev-ref HEAD", {
-        cwd: FORGE_HOME,
-        encoding: "utf-8",
-      }).trim();
+      const branch = getGitBranch();
+      const branchLabel = branch || "unknown branch";
+      console.log(`  Source: ${formatSourceIdentity(branch)}`);
 
-      // If on a non-main branch, switch to main for the update then restore.
-      // Detached HEAD ("HEAD") is treated as non-restorable — we leave on main
-      // after the update and warn the user.
-      const isDetached = branch === "HEAD";
-      const needsCheckout = branch !== "main";
-      if (needsCheckout) {
+      if (branch !== "main") {
         // Dirty-tree guard: refuse to move HEAD in this clone if there are
         // uncommitted TRACKED changes. Untracked files are intentionally
         // excluded (--untracked-files=no) so a clean checkout with stray
@@ -1837,7 +1906,7 @@ async function update() {
         ).trim();
         if (porcelain) {
           console.log(
-            `  ${YELLOW}Working tree has uncommitted changes on branch ${branch} — skipping git-based update.${RESET}`,
+            `  ${YELLOW}Working tree has uncommitted changes on branch ${branchLabel} — skipping git-based update.${RESET}`,
           );
 
           // forge#2460 — distinguish "developing on this checkout" from a
@@ -1882,16 +1951,13 @@ async function update() {
           return;
         }
 
-        if (isDetached) {
-          console.log(
-            `  ${YELLOW}Detached HEAD state — switching to main for update.${RESET}`,
-          );
-        } else {
-          console.log(
-            `  On branch ${CYAN}${branch}${RESET} — switching to ${CYAN}main${RESET} for update...`,
-          );
-        }
-        execFileSync("git", ["checkout", "main", "--quiet"], { cwd: FORGE_HOME });
+        console.log(
+          `  ${YELLOW}Source checkout is on ${branchLabel}, not main; skipping update to preserve this source.${RESET}`,
+        );
+        console.log(
+          `  Run 'npx forgedock update' from a main-branch checkout (or use 'npx forgedock@latest') to refresh ForgeDock.`,
+        );
+        return;
       }
 
       const before = execSync("git rev-parse HEAD", {
@@ -1914,20 +1980,6 @@ async function update() {
         printGitCloneChangelogSummary(before, after);
       }
       await relinkAndHint();
-
-      // Restore original branch after a successful update.
-      if (needsCheckout && !isDetached) {
-        try {
-          execFileSync("git", ["checkout", branch, "--quiet"], { cwd: FORGE_HOME });
-          console.log(
-            `  Restored branch ${CYAN}${branch}${RESET}.`,
-          );
-        } catch {
-          console.log(
-            `  ${YELLOW}⚠  Could not restore branch ${branch} — you are now on main.${RESET}`,
-          );
-        }
-      }
     } catch (err) {
       console.log(
         `  ${YELLOW}Cannot fast-forward — local changes exist. Skipping.${RESET}`,
@@ -2190,7 +2242,14 @@ async function doctor(fix = false) {
   console.log("");
 
   const { targetDir: TARGET_DIR } = detectInstallPaths();
-  console.log(`  Mode: global (~/.claude)`);
+  const isGitCloneInstall = existsSync(join(FORGE_HOME, ".git"));
+  const sourceBranch = isGitCloneInstall ? getGitBranch() : null;
+  console.log(
+    isGitCloneInstall
+      ? `  Mode: git clone at ${CYAN}${FORGE_HOME}${RESET}`
+      : `  Mode: global (~/.claude)`,
+  );
+  console.log(`  Source: ${formatSourceIdentity(sourceBranch)}`);
   console.log("");
 
   let failures = 0;
@@ -2717,7 +2776,6 @@ async function doctor(fix = false) {
   // absence that isn't a problem should not read as one.
   {
     try {
-      const isGitCloneInstall = existsSync(join(FORGE_HOME, ".git"));
       if (isGitCloneInstall) {
         pass("Persisted toolset home (~/.forge)", "skipped — git-clone install links directly from the clone");
       } else {
@@ -3150,6 +3208,9 @@ function help() {
     ["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 opencode install", "Install token-efficient native OpenCode commands"],
+    ["npx forgedock opencode status", "Check the OpenCode adapter"],
+    ["npx forgedock opencode uninstall", "Remove ForgeDock-owned OpenCode files"],
     ["npx forgedock version", "Print the installed version and check for updates"],
     ["npx forgedock help", "Show this help"],
   ];
@@ -3711,7 +3772,7 @@ 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", "config", "help", "--help", "-h",
+  "run", "backend-check", "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);
@@ -3801,9 +3862,80 @@ switch (command) {
   case "update":
     await update();
     break;
+  case "opencode": {
+    const action = restArgs[0] || "install";
+    const {
+      getOpenCodeAdapterStatus,
+      installOpenCodeAdapter,
+      uninstallOpenCodeAdapter,
+    } = await import("./opencode-adapter.mjs");
+    if (action === "install") {
+      const persist = await persistHome({ forgeHome: FORGE_HOME, home: HOME });
+      if (persist.forgeHome === FORGE_HOME && isEphemeralCachePath(FORGE_HOME)) {
+        throw new Error(
+          `Cannot install OpenCode commands from ephemeral package path ${FORGE_HOME}: ` +
+            `${persist.reason || "failed to persist ForgeDock under ~/.forge"}.`,
+        );
+      }
+      const result = await installOpenCodeAdapter({
+        forgeHome: persist.forgeHome || FORGE_HOME,
+        home: HOME,
+        includeExtras: restArgs.includes("--extras"),
+      });
+      process.stdout.write(
+        `Installed ${result.commandCount} OpenCode commands and ${result.skillCount} skills under ${result.configDir}.\n` +
+          "Restart OpenCode, then run /forge/work-on <issue>.\n",
+      );
+      if (result.migration.removedInstructionsFile || result.migration.removedConfigEntries > 0) {
+        process.stdout.write(
+          `Removed legacy OpenCode adapter artifacts (${result.migration.removedConfigEntries} config entries).\n`,
+        );
+      }
+      for (const warning of result.migration.warnings) process.stderr.write(`Warning: ${warning}\n`);
+    } else if (action === "status") {
+      const result = await getOpenCodeAdapterStatus({ home: HOME });
+      if (result.legacy) {
+        process.stdout.write(
+          "A legacy ForgeDock OpenCode adapter is installed. Re-run: npx forgedock opencode install\n",
+        );
+        exitCode = 1;
+      } else if (!result.installed) {
+        process.stdout.write(`OpenCode adapter is not installed under ${result.configDir}.\n`);
+        exitCode = 1;
+      } else if (!result.healthy) {
+        process.stdout.write(
+          `OpenCode adapter is incomplete (${result.missing.length} missing file(s)). ` +
+            "Re-run: npx forgedock opencode install\n",
+        );
+        exitCode = 1;
+      } else {
+        process.stdout.write(
+          `OpenCode adapter is healthy (${result.manifest.commandCount} commands, ${result.manifest.skillCount ?? 0} skills) under ${result.configDir}.\n`,
+        );
+      }
+    } else if (action === "uninstall") {
+      const result = await uninstallOpenCodeAdapter({ home: HOME });
+      process.stdout.write(`Removed ${result.removed} ForgeDock-owned OpenCode file(s).\n`);
+    } else {
+      process.stderr.write(
+        `Unknown OpenCode action: ${action}. Use install, status, or uninstall.\n`,
+      );
+      exitCode = 1;
+    }
+    break;
+  }
   case "run":
     await run();
     break;
+  case "backend-check": {
+    const { checkExecutionBackend } = await import("./runner.mjs");
+    const result = checkExecutionBackend();
+    if (!restArgs.includes("--quiet")) {
+      process.stdout.write(`${result.ready ? "ready" : "unavailable"}: ${result.backend} (${result.reason})\n`);
+    }
+    if (!result.ready) exitCode = 1;
+    break;
+  }
   case "run-issue": {
     const { runFromCli } = await import("./engine-cli.mjs");
     try {