forgedock 1.1.8 → 1.1.9

package/README.md

@@ -221,11 +221,10 @@ More ship today (web-property analytics, browser QA sweeps, self-benchmarking)
 **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) · [GitHub CLI](https://cli.github.com/) (authenticated) · Node.js ≥ 18.
 
 ```bash
-npx forgedock          # project-scoped install: checks your environment, installs commands for this repo, detects your repo, and hands you a reviewed forge.yaml
-npx forgedock --global # global install: installs into ~/.claude/commands/ — available in every Claude Code session on this machine
+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
 ```
 
-**Project-scoped is the default.** `npx forgedock` installs commands scoped to the current project directory. Use `--global` only when you want the commands available across all your projects on this machine.
+**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.
 
@@ -253,15 +252,13 @@ Commands then appear as `/forgedock:work-on`, etc. You still run `npx forgedock
 
 **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).
 
-**Install modes:**
+**Explicit install command:**
 
 ```bash
-npx forgedock install           # project-scoped: <cwd>/.claude/commands/ (default)
-npx forgedock install --global  # global: ~/.claude/commands/ (opt-in)
+npx forgedock install           # installs into ~/.claude/commands/
+npx forgedock install --global  # same thing — --global is accepted but is a no-op
 ```
 
-`uninstall`, `update`, and `doctor` auto-detect which mode is installed — no need to re-specify `--global` after a global install. To explicitly target global: `npx forgedock doctor --global`.
-
 **Maintenance:**
 
 ```bash
@@ -269,9 +266,9 @@ npx forgedock update      # relink commands + refresh the SessionStart hook
 npx forgedock enable      # turn ForgeDock on for this directory
 npx forgedock disable     # turn ForgeDock off for this directory
 npx forgedock status      # show ForgeDock's state for this directory
-npx forgedock doctor      # installation health check with fix hints (auto-detects mode)
+npx forgedock doctor      # installation health check with fix hints
 npx forgedock report      # 30-day pipeline impact receipts (--md for Markdown, --json for scripting)
-npx forgedock uninstall   # remove commands, the hook, and tracked copies (auto-detects mode)
+npx forgedock uninstall   # remove commands, the hook, and tracked copies
 npx forgedock help        # show everything
 ```
 
@@ -280,31 +277,11 @@ npx forgedock help        # show everything
 </details>
 
 <details>
-<summary><strong>Migrating from a global install</strong></summary>
-
-If you installed ForgeDock before project-scoped became the default, your commands live in `~/.claude/commands/`. You have two paths forward:
-
-**Keep the global install** — add `--global` going forward and nothing changes:
-
-```bash
-npx forgedock --global   # install / update globally as before
-```
+<summary><strong>A note on install location</strong></summary>
 
-**Switch to project-scoped** (recommended for multi-repo setups):
-
-```bash
-# 1. Check your current install mode
-npx forgedock status
-
-# 2. Remove the global install
-npx forgedock uninstall --global
-
-# 3. Install project-scoped in each repo you use ForgeDock in
-cd /path/to/your/project
-npx forgedock
-```
+ForgeDock briefly experimented with a project-scoped-by-default install mode. It was backed out after causing a "split-brain" bug (`detect` assumed project-scoped while the installer still wrote globally — [#1589](https://github.com/RapierCraftStudios/ForgeDock/issues/1589)), so every version you'd realistically install today only ever writes to `~/.claude/commands/`. `--global` is still accepted as a flag for old scripts/muscle memory, but it changes nothing.
 
-Run `npx forgedock doctor` after switching to confirm everything is healthy.
+If you're carrying an older `--global` habit in scripts or CI, it's harmless to leave it — `npx forgedock --global` and `npx forgedock` do exactly the same thing.
 
 </details>
 

package/bin/cinema.mjs

@@ -200,14 +200,32 @@ function badgeText(badge, mode) {
   return `${fg(rgb, mode)}[${label}]\x1b[0m`;
 }
 
-/** Ember-bordered fix card (wraps tui.box; border color applied when able). */
-export function fixCard(lines, mode) {
+/**
+ * Severity-banded fix card (wraps tui.box; border color/weight applied when
+ * able).
+ *
+ * - "error"   (default): ember/red bordered box — current look, unchanged.
+ * - "warning": amber bordered box — lighter than error, still boxed.
+ * - "info":    no border — plain, dimmed lines only.
+ *
+ * @param {string[]} lines
+ * @param {string} mode
+ * @param {'error'|'warning'|'info'} [severity]
+ */
+export function fixCard(lines, mode, severity = "error") {
+  if (severity === "info") {
+    const padded = lines.map((l) => ` ${l} `);
+    if (mode === "none") return padded.join("\n");
+    return padded.map((l) => `\x1b[2m${l}\x1b[22m`).join("\n");
+  }
+
   const boxed = box(lines.map((l) => ` ${l} `), { title: "fix" });
   if (mode === "none") return boxed;
-  const ember = fg([255, 107, 53], mode);
+  const rgb = severity === "warning" ? [232, 192, 96] : [255, 107, 53];
+  const color = fg(rgb, mode);
   return boxed
     .split("\n")
-    .map((l) => l.replace(/[╭╮╰╯─│]/gu, (m) => `${ember}${m}\x1b[0m`))
+    .map((l) => l.replace(/[╭╮╰╯─│]/gu, (m) => `${color}${m}\x1b[0m`))
     .join("\n");
 }
 
@@ -253,7 +271,7 @@ export async function revealRows(
     }
     writer.write(formatRow(row.label, res, mode) + "\n");
     if (!res.ok && res.fix && res.fix.length > 0) {
-      writer.write(fixCard(res.fix, mode) + "\n");
+      writer.write(fixCard(res.fix, mode, res.severity || "error") + "\n");
     }
     results.push(res);
   }

package/bin/engine-cli.mjs

@@ -6,17 +6,48 @@
  */
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { runIssue } from "./engine.mjs";
 import { makeProjector } from "./engine/projector.mjs";
+import { readLog, deriveState } from "./engine/runlog.mjs";
+
+/**
+ * Workflow labels that mark an issue as "in the pipeline" (not yet terminal).
+ * Shared by resume-stalled's candidate enumeration and countEngineActivity()
+ * (the re-entry dashboard's in-flight/stalled counter, #1945) so both surfaces
+ * agree on what "in-flight" means — a single source of truth rather than two
+ * lists that can silently drift apart.
+ */
+export const ACTIVE_WORKFLOW_LABELS = [
+  "workflow:investigating",
+  "workflow:ready-to-build",
+  "workflow:building",
+  "workflow:in-review",
+];
 
 const pexec = promisify(execFile);
 
-/** Real gh/git accessors. */
+/**
+ * Real gh/git accessors.
+ *
+ * `timeout: 10000` matches the convention already used for the sibling
+ * `gh pr list` call in the interactive dashboard (bin/forgedock.mjs's
+ * gatherDashboardData()). Every io.gh()/io.git() call site issues a single,
+ * normally-fast metadata command (gh issue view, gh api .../comments,
+ * gh pr list/view, git rev-list --count) — none are legitimately
+ * long-running — so one shared timeout is appropriate across all callers
+ * (the interactive status dashboard, run-issue, and resume-stalled). A
+ * hung/black-holed gh process (flaky network, corporate proxy, stuck auth
+ * prompt) would otherwise hang commands like `npx forgedock status`
+ * indefinitely (#1962). Callers already wrap every io.gh()/io.git() call in
+ * try/catch and degrade to null/"unknown" on any rejection, so a timeout
+ * fails closed gracefully with no additional error handling required.
+ */
 export function makeIo() {
   const run = (bin) => async (args) => {
-    const { stdout } = await pexec(bin, args, { maxBuffer: 100 * 1024 * 1024 });
+    const { stdout } = await pexec(bin, args, { maxBuffer: 100 * 1024 * 1024, timeout: 10000 });
     return stdout;
   };
   return { gh: run("gh"), git: run("git") };
@@ -88,6 +119,106 @@ export async function scanStalls(issues, io, now) {
   return stalled;
 }
 
+/**
+ * Read-only in-flight/stalled counter for the `status`/`install` re-entry
+ * dashboard (#1945). Reuses the exact same enumeration + lease-expiry logic
+ * as `resumeStalledFromCli` (workflow-label search via `gh issue list`, then
+ * `scanStalls` against the GitHub-authoritative FORGE:STATE via the
+ * projector) — GitHub is this codebase's source of truth for run state, not
+ * the local `~/.forge/runs` hot-path log, so the dashboard counts the same
+ * way the orchestrator does. Never dispatches or mutates anything.
+ *
+ * Best-effort: a `gh issue list` failure for one label is swallowed (treated
+ * as zero matches for that label) — consistent with resumeStalledFromCli's
+ * existing tolerance — so one bad label search never blocks the others.
+ *
+ * @param {{gh: Function}} io
+ * @param {string|null} repo - "owner/repo", or null to use gh's cwd-resolved default
+ * @param {number} now
+ * @returns {Promise<{total: number, inFlight: number, stalled: number}>}
+ */
+export async function countEngineActivity(io, repo, now) {
+  const repoFlag = repo ? ["--repo", repo] : [];
+  const issueSet = new Set();
+
+  for (const label of ACTIVE_WORKFLOW_LABELS) {
+    try {
+      const out = await io.gh([
+        "issue", "list",
+        ...repoFlag,
+        "--state", "open",
+        "--label", label,
+        "--limit", "100",
+        "--json", "number",
+      ]);
+      const items = JSON.parse(out);
+      for (const { number } of items) issueSet.add(number);
+    } catch {
+      // gh may return non-zero when no issues match, or fail transiently —
+      // treat as empty for this label rather than aborting the whole count.
+    }
+  }
+
+  if (issueSet.size === 0) return { total: 0, inFlight: 0, stalled: 0 };
+
+  const projector = makeProjector(io);
+  const candidates = [...issueSet];
+  const stalled = await scanStalls(candidates, projector, now);
+  return { total: candidates.length, inFlight: candidates.length - stalled.length, stalled: stalled.length };
+}
+
+/**
+ * Best-effort summary of the most recently modified local run-log under
+ * `~/.forge/runs` (runDir()). This is a MACHINE-LOCAL view — the crash-safe
+ * hot-path log described in engine/runlog.mjs, not the GitHub-authoritative
+ * state used by countEngineActivity() above. Appropriate only for a "what did
+ * I last run here" dashboard row, not for cross-machine in-flight/stalled
+ * counts.
+ *
+ * Never throws: returns null when the runs dir doesn't exist, holds no
+ * `.jsonl` files, or the newest file can't be read/parsed. A single corrupt
+ * or unreadable file is skipped in favor of the next-newest one rather than
+ * failing the whole lookup (forge#1528 — batch operations here must not abort
+ * on one bad item).
+ *
+ * @param {string} dir - runDir()
+ * @returns {{issue: number, terminal: boolean, terminalReason: string|null} | null}
+ */
+export function lastLocalRun(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
+  } catch {
+    return null;
+  }
+
+  // Sort newest-first by mtime so a corrupt newest file falls through to the
+  // next-newest candidate instead of giving up entirely.
+  const withMtime = [];
+  for (const f of entries) {
+    try {
+      withMtime.push({ f, mtime: statSync(join(dir, f)).mtimeMs });
+    } catch {
+      // unreadable — skip
+    }
+  }
+  withMtime.sort((a, b) => b.mtime - a.mtime);
+
+  for (const { f } of withMtime) {
+    const issue = parseInt(f.slice(0, -".jsonl".length), 10);
+    if (!Number.isInteger(issue)) continue;
+    try {
+      const events = readLog(dir, issue);
+      if (events.length === 0) continue;
+      const state = deriveState(events);
+      return { issue, terminal: state.terminal, terminalReason: state.terminalReason };
+    } catch {
+      continue; // corrupt file — try the next-newest
+    }
+  }
+  return null;
+}
+
 /**
  * @param {string[]} argv
  * @param {{io?: {gh: Function}, runIssue?: Function}} [deps]
@@ -147,18 +278,13 @@ export async function resumeStalledFromCli(argv, deps = {}) {
   const projector = makeProjector(io);
   const now = Date.now();
 
-  // Collect candidate issue numbers from all non-terminal workflow labels.
-  const ACTIVE_LABELS = [
-    "workflow:investigating",
-    "workflow:ready-to-build",
-    "workflow:building",
-    "workflow:in-review",
-  ];
-
+  // Collect candidate issue numbers from all non-terminal workflow labels
+  // (ACTIVE_WORKFLOW_LABELS — shared with countEngineActivity() so both
+  // surfaces agree on what "in-flight" means).
   const repoFlag = repo ? ["--repo", repo] : [];
   const issueSet = new Set();
 
-  for (const label of ACTIVE_LABELS) {
+  for (const label of ACTIVE_WORKFLOW_LABELS) {
     try {
       const out = await io.gh([
         "issue", "list",

package/bin/env-detect.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+/**
+ * env-detect.mjs — Pure deterministic environment detection for ForgeDock.
+ *
+ * Exports a single function: detectEnvironment(opts)
+ *
+ * Returns a flat, structured description of the host environment the
+ * installer is running in — platform, WSL status, shell, and a best-guess at
+ * symlink support. Mirrors the conventions established by init-detect.mjs:
+ *
+ * Contract guarantees:
+ *   - Pure: no prompts, no writes; reads only injectable inputs (or their
+ *     process defaults) — process.platform, os.release(), process.env, and
+ *     (best-effort) /proc/version.
+ *   - Safe: every risky read is wrapped in try/catch and degrades to a
+ *     best-guess default. detectEnvironment() never throws.
+ *   - Testable: inject `platform`, `env`, `release`, and `readFileSync` to
+ *     simulate any OS/shell/WSL combination without mocking global process
+ *     state.
+ */
+
+import { readFileSync as fsReadFileSync } from "fs";
+import os from "os";
+
+// ---------------------------------------------------------------------------
+// Detection helpers — each is pure and never throws
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect whether the process is running inside WSL, and which distro.
+ *
+ * Strategy (first success wins):
+ *   1. `WSL_DISTRO_NAME` env var — set by WSL itself, authoritative when present.
+ *   2. On `linux`, best-effort read `/proc/version` and test for "microsoft"
+ *      (case-insensitive) — covers WSL setups that don't export the env var
+ *      (e.g. processes launched without inheriting the interactive shell's
+ *      environment).
+ *
+ * Never throws: a missing/unreadable /proc/version degrades to "not WSL".
+ *
+ * @param {string} platform
+ * @param {NodeJS.ProcessEnv} env
+ * @param {(path: string, encoding: string) => string} readFile
+ * @returns {{ isWSL: boolean, wslDistro: string | null }}
+ */
+function detectWSL(platform, env, readFile) {
+  if (env.WSL_DISTRO_NAME) {
+    return { isWSL: true, wslDistro: env.WSL_DISTRO_NAME };
+  }
+
+  if (platform === "linux") {
+    try {
+      const version = readFile("/proc/version", "utf-8");
+      if (/microsoft/i.test(version)) {
+        return { isWSL: true, wslDistro: null };
+      }
+    } catch {
+      // /proc/version missing or unreadable — not WSL, or undetectable; degrade quietly.
+    }
+  }
+
+  return { isWSL: false, wslDistro: null };
+}
+
+/**
+ * Derive a human-readable platform label.
+ *
+ * Windows build numbers >= 22000 report as "Windows 11" (Node's os.release()
+ * on win32 returns the kernel version, e.g. "10.0.22631" — Windows 11 never
+ * bumped the major.minor past 10.0, only the build number). Anything that
+ * doesn't match a recognized pattern falls back to a generic label rather
+ * than throwing or guessing wildly.
+ *
+ * @param {string} platform
+ * @param {string} release
+ * @returns {string}
+ */
+function detectPlatformLabel(platform, release) {
+  switch (platform) {
+    case "win32": {
+      const buildMatch = String(release).match(/^10\.0\.(\d+)/);
+      if (buildMatch && Number(buildMatch[1]) >= 22000) return "Windows 11";
+      if (String(release).startsWith("10.")) return "Windows 10";
+      return "Windows";
+    }
+    case "darwin":
+      return "macOS";
+    case "linux":
+      return "Linux";
+    default:
+      return platform;
+  }
+}
+
+/**
+ * Best-effort shell name detection.
+ *
+ * Strategy (first success wins):
+ *   1. `$SHELL` — set on POSIX (bash/zsh/fish/...) and also by Git-Bash/MSYS
+ *      environments on Windows. Basename it (strip any path).
+ *   2. On `win32` without `$SHELL`: `$PSModulePath` presence indicates
+ *      PowerShell; otherwise `$ComSpec` presence indicates cmd.exe.
+ *   3. "unknown" — no shell signal found.
+ *
+ * Never throws.
+ *
+ * @param {string} platform
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string}
+ */
+function detectShell(platform, env) {
+  if (env.SHELL) {
+    const parts = String(env.SHELL).split(/[\\/]/);
+    const name = parts[parts.length - 1];
+    return name || env.SHELL;
+  }
+
+  if (platform === "win32") {
+    if (env.PSModulePath) return "PowerShell";
+    if (env.ComSpec) return "cmd";
+  }
+
+  return "unknown";
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{
+ *   platform: string,
+ *   platformLabel: string,
+ *   isWSL: boolean,
+ *   wslDistro: string | null,
+ *   shell: string,
+ *   symlinkSupport: boolean,
+ * }} EnvironmentInfo
+ */
+
+/**
+ * Detect the current host environment: platform, WSL status, shell, and a
+ * best-guess at symlink support. Never throws — every risky read degrades to
+ * a best-guess default.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.platform] - Defaults to `process.platform`. Inject to test other OSes.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Defaults to `process.env`. Inject to test WSL/shell scenarios.
+ * @param {string} [opts.release] - Defaults to `os.release()`. Inject to force a specific Windows
+ *   build number (e.g. "10.0.22631") so Windows 10 vs 11 labeling is deterministically testable.
+ * @param {(path: string, encoding: string) => string} [opts.readFileSync] - Defaults to `fs.readFileSync`.
+ *   Inject to simulate /proc/version contents (or failures) without touching the real filesystem.
+ * @returns {EnvironmentInfo}
+ */
+export function detectEnvironment(opts = {}) {
+  const platform = opts.platform ?? process.platform;
+  const env = opts.env ?? process.env;
+  let release = opts.release;
+  if (release === undefined) {
+    try {
+      release = os.release();
+    } catch {
+      release = "";
+    }
+  }
+  const readFile = opts.readFileSync ?? fsReadFileSync;
+
+  let isWSL = false;
+  let wslDistro = null;
+  try {
+    ({ isWSL, wslDistro } = detectWSL(platform, env, readFile));
+  } catch {
+    // Best-effort — degrade to "not WSL" on any unexpected failure.
+  }
+
+  let platformLabel = platform;
+  try {
+    platformLabel = detectPlatformLabel(platform, release);
+  } catch {
+    platformLabel = platform;
+  }
+
+  let shell = "unknown";
+  try {
+    shell = detectShell(platform, env);
+  } catch {
+    shell = "unknown";
+  }
+
+  // Best-guess only — POSIX filesystems support symlinks unconditionally;
+  // Windows requires Developer Mode or elevation, which isn't reliably
+  // detectable without a live filesystem probe (out of scope: this module is
+  // pure/read-only). journey.mjs's forge() already handles the real-world
+  // EPERM/EACCES case reactively via a copy fallback.
+  const symlinkSupport = platform !== "win32";
+
+  return { platform, platformLabel, isWSL, wslDistro, shell, symlinkSupport };
+}
+
+// ---------------------------------------------------------------------------
+// Cross-environment path translation (forge#1893)
+// ---------------------------------------------------------------------------
+
+/**
+ * Translate a WSL-mounted-drive path to its native Windows equivalent.
+ *
+ * WSL exposes Windows drives under `/mnt/<drive>/...` (lowercase drive
+ * letter, single character). This is a live bind mount — `/mnt/c/Users/foo`
+ * and `C:\Users\foo` refer to the exact same files on disk. Only that shape
+ * is recognized; a plain WSL-native path (`/home/foo/...`) has no Windows
+ * equivalent and returns `null` rather than guessing.
+ *
+ * Pure, never throws.
+ *
+ * @param {string} p - Absolute POSIX path, e.g. `/mnt/c/Users/foo/repo`.
+ * @returns {string | null} e.g. `C:\Users\foo\repo`, or `null` if `p` isn't
+ *   a `/mnt/<drive>/...` path.
+ */
+export function wslPathToWindows(p) {
+  if (!p || typeof p !== "string") return null;
+  const m = p.match(/^\/mnt\/([a-z])(\/.*)?$/i);
+  if (!m) return null;
+  const drive = m[1].toUpperCase();
+  const rest = (m[2] || "").replace(/\//g, "\\");
+  return `${drive}:${rest}`;
+}
+
+/**
+ * Translate a native Windows path to its WSL-mounted-drive equivalent.
+ *
+ * Mirrors `wslPathToWindows()`: `C:\Users\foo\repo` (or the forward-slash
+ * variant `C:/Users/foo/repo`, which Node also accepts on win32) becomes
+ * `/mnt/c/Users/foo/repo`. Only a `<drive>:` prefix is recognized; anything
+ * else (UNC paths, relative paths) returns `null` rather than guessing.
+ *
+ * Pure, never throws.
+ *
+ * @param {string} p - Absolute Windows path, e.g. `C:\Users\foo\repo`.
+ * @returns {string | null} e.g. `/mnt/c/Users/foo/repo`, or `null` if `p`
+ *   isn't a `<drive>:...` path.
+ */
+export function windowsPathToWsl(p) {
+  if (!p || typeof p !== "string") return null;
+  const m = p.match(/^([a-z]):[\\/]?(.*)$/i);
+  if (!m) return null;
+  const drive = m[1].toLowerCase();
+  const rest = m[2].replace(/\\/g, "/");
+  return `/mnt/${drive}${rest ? `/${rest}` : ""}`;
+}