forgedock 1.5.1 → 1.7.0

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,23 @@ 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 `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/forgedock.mjs

@@ -59,8 +59,8 @@ import {
   detectClaudeVersion,
   loadBreakpoints,
   hasFeature,
-  getPersistedHomeState,
   setPersistedHomeState,
+  getInstalledCommandsDriftStatus,
 } from "./registry.mjs";
 import { renderMark, ember } from "./cinema.mjs";
 import {
@@ -2740,27 +2740,16 @@ async function doctor(fix = false) {
             `incomplete (missing: ${missingDirs.join(", ")}). Run: npx forgedock install`,
           );
         } else {
-          // Prefer the version registry.mjs last recorded for this exact
-          // write (getPersistedHomeState()) — the single source of truth
-          // update()/install also write through — falling back to reading
-          // ~/.forge/version directly on disk when the registry has no entry
-          // (e.g. an older ForgeDock version wrote ~/.forge/ before #1943
-          // added registry tracking). Reading both keeps doctor() honest
-          // even if the registry ever drifts from what's actually on disk.
-          const recorded = getPersistedHomeState();
-          let persistedVersion = recorded?.version || "";
-          if (!persistedVersion) {
-            try {
-              persistedVersion = readFileSync(versionPath, "utf-8").trim();
-            } catch {
-              // version file missing/unreadable — reported below as "unknown"
-            }
-          }
-          const sourceVersion = getVersion();
-          if (persistedVersion && sourceVersion && compareVersions(persistedVersion, sourceVersion) < 0) {
+          // Package-vs-installed-commands drift comparison is factored into
+          // a single shared helper (bin/registry.mjs's
+          // getInstalledCommandsDriftStatus, forge#2719) so doctor, the
+          // `version` command, and the SessionStart hook all agree on one
+          // source of truth instead of re-deriving this logic independently.
+          const { persistedVersion, isStale, unknown } = getInstalledCommandsDriftStatus(FORGE_HOME);
+          if (!unknown && isStale) {
             warn(
               "Persisted toolset home (~/.forge)",
-              `v${persistedVersion} — source is v${sourceVersion}. Run: npx forgedock update`,
+              `v${persistedVersion} — source is v${getVersion()}. Run: npx forgedock update`,
             );
           } else {
             pass("Persisted toolset home (~/.forge)", `v${persistedVersion || "unknown"} at ${persistedHome}`);
@@ -3161,6 +3150,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"],
   ];
@@ -3722,7 +3714,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);
@@ -3812,9 +3804,75 @@ 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 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.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) 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 {
@@ -3959,6 +4017,18 @@ switch (command) {
           `Run ${CYAN}npx forgedock update${RESET} to fetch it.`,
       );
     }
+
+    // forge#2719 — surface package-vs-installed-commands drift (previously
+    // only visible via `doctor` Check 5d). Uses the same shared helper doctor
+    // calls, so both surfaces agree. Silent when versions match or when
+    // either version is unknown (e.g. a git-clone dev install, which never
+    // persists to ~/.forge — see registry.mjs's getInstalledCommandsDriftStatus).
+    const driftStatus = getInstalledCommandsDriftStatus(FORGE_HOME);
+    if (!driftStatus.unknown && driftStatus.isStale) {
+      console.log(
+        `  ${YELLOW}Installed commands are stale (v${driftStatus.persistedVersion}) vs package v${driftStatus.sourceVersion}${RESET} — run: ${CYAN}npx forgedock update${RESET}`,
+      );
+    }
     break;
   }
   case "help":

package/bin/hooks/session-start.mjs

@@ -51,6 +51,8 @@ const FORGE_HOME = resolve(__dirname, "..", "..");
 let resolveState;
 let nudgeSeen;
 let markNudgeSeen;
+// Assigned alongside the other registry.mjs helpers below — see forge#2719.
+let getInstalledCommandsDriftStatus;
 
 // ---------------------------------------------------------------------------
 // forge-utils helpers — populated inside the try block to honour fail-open
@@ -88,7 +90,7 @@ try {
   // that import() rejects with ERR_UNSUPPORTED_ESM_URL_SCHEME.
   /** @type {import('../registry.mjs')} */
   (
-    { resolveState, nudgeSeen, markNudgeSeen } = await import(
+    { resolveState, nudgeSeen, markNudgeSeen, getInstalledCommandsDriftStatus } = await import(
       pathToFileURL(join(FORGE_HOME, "bin", "registry.mjs")).href
     )
   );
@@ -126,6 +128,25 @@ try {
   const cwd = process.cwd();
   const state = resolveState(cwd);
 
+  // Surface package-vs-installed-commands drift as a single non-fatal
+  // advisory line (forge#2719). Uses the same shared helper doctor's
+  // Check 5d and the `version` command call, so all three surfaces agree.
+  // Best-effort: any failure here must never block the session, and
+  // managed-optedout directories stay completely silent per this hook's
+  // existing contract for that state (see the switch below).
+  if (state !== "managed-optedout") {
+    try {
+      const driftStatus = getInstalledCommandsDriftStatus(FORGE_HOME);
+      if (!driftStatus.unknown && driftStatus.isStale) {
+        console.log(
+          `ForgeDock: installed commands are stale (v${driftStatus.persistedVersion}) vs package v${driftStatus.sourceVersion} — run: npx forgedock update`,
+        );
+      }
+    } catch {
+      // Fail open — never let a drift-check error affect session start.
+    }
+  }
+
   switch (state) {
     case "managed-active":
       await handleManagedActive(cwd);