forgedock 1.0.22 → 1.1.1

package/bin/cinema.mjs

@@ -0,0 +1,320 @@
+/**
+ * bin/cinema.mjs — Cinematic rendering primitives for ForgeDock's TUI.
+ *
+ * Zero-dependency. Pure presentation: gradients, the block-art F mark, and
+ * (in Task 2) shimmer / reveal / progress animation primitives.
+ *
+ * Two independent gates (spec: degradation ladder):
+ *   colorMode()     — 'truecolor' | '256' | 'none'  (NO_COLOR, TTY, TERM)
+ *   motionEnabled() — animation frames on/off        (TTY, FORGE_NO_MOTION, CI, --fast)
+ *
+ * All functions take env/stdout/argv as parameters (with process defaults)
+ * so tests never need module-cache busting.
+ */
+
+// ---------------------------------------------------------------------------
+// Palette (spec: Chrome & Ember)
+// ---------------------------------------------------------------------------
+
+export const CHROME_STOPS = ["#f7f3ea", "#d9cfba", "#a99a82", "#6e6252"];
+export const EMBER_STOPS = ["#ff4d00", "#ff8c1a", "#ffd166"];
+
+// ---------------------------------------------------------------------------
+// Gates
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide the color capability of the terminal.
+ * @returns {'truecolor'|'256'|'none'}
+ */
+export function colorMode(env = process.env, stdout = process.stdout) {
+  if (stdout.isTTY !== true) return "none";
+  if (env.NO_COLOR) return "none";
+  if (env.TERM === "dumb") return "none";
+  const ct = (env.COLORTERM || "").toLowerCase();
+  if (ct.includes("truecolor") || ct.includes("24bit")) return "truecolor";
+  if ((env.TERM || "").includes("256")) return "256";
+  // Windows Terminal / modern conhost support truecolor but don't set COLORTERM.
+  if (process.platform === "win32") return "truecolor";
+  return "256";
+}
+
+/**
+ * Decide whether animation frames run. Independent of color:
+ * NO_COLOR keeps motion (monochrome choreography); non-TTY/CI/--fast kill it.
+ * @returns {boolean}
+ */
+export function motionEnabled(
+  argv = process.argv,
+  env = process.env,
+  stdout = process.stdout,
+) {
+  if (stdout.isTTY !== true) return false;
+  if (env.FORGE_NO_MOTION) return false;
+  if (env.CI) return false;
+  if (argv.includes("--fast")) return false;
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Gradient math
+// ---------------------------------------------------------------------------
+
+function hexToRgb(hex) {
+  const h = hex.replace("#", "");
+  return [
+    parseInt(h.slice(0, 2), 16),
+    parseInt(h.slice(2, 4), 16),
+    parseInt(h.slice(4, 6), 16),
+  ];
+}
+
+/**
+ * Sample a multi-stop gradient at position t ∈ [0,1].
+ * @returns {[number, number, number]} RGB triple.
+ */
+export function sampleGradient(stops, t) {
+  const rgb = stops.map(hexToRgb);
+  const clamped = Math.min(Math.max(t, 0), 1);
+  const seg = Math.min(Math.floor(clamped * (rgb.length - 1)), rgb.length - 2);
+  const localT = clamped * (rgb.length - 1) - seg;
+  const [a, b] = [rgb[seg], rgb[seg + 1]];
+  const mix = (x, y) => Math.round(x + (y - x) * localT);
+  return [mix(a[0], b[0]), mix(a[1], b[1]), mix(a[2], b[2])];
+}
+
+/** Quantize an RGB triple to the xterm-256 6×6×6 color cube. */
+function to256([r, g, b]) {
+  const q = (v) => Math.round((v / 255) * 5);
+  return 16 + 36 * q(r) + 6 * q(g) + q(b);
+}
+
+/** Foreground escape for an RGB triple in the given mode ('' for none). */
+function fg(rgb, mode) {
+  if (mode === "none") return "";
+  if (mode === "256") return `\x1b[38;5;${to256(rgb)}m`;
+  return `\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m`;
+}
+
+/**
+ * Render one line of text with a per-character horizontal gradient.
+ * Spaces stay uncolored. `phase` shifts the gradient start (for diagonals).
+ * In 'none' mode returns the input text verbatim (no reset appended).
+ */
+export function gradientLine(text, stops, mode, phase = 0) {
+  if (mode === "none") return text;
+  const chars = [...text];
+  const n = Math.max(chars.length - 1, 1);
+  let out = "";
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] === " ") {
+      out += " ";
+      continue;
+    }
+    const t = Math.min(i / n + phase, 1);
+    out += fg(sampleGradient(stops, t), mode) + chars[i];
+  }
+  return out + "\x1b[0m";
+}
+
+/**
+ * Render a block of lines with a diagonal gradient (each row's phase shifts
+ * slightly, approximating the logo's 135° gradient).
+ * @returns {string[]}
+ */
+export function gradientBlock(lines, stops, mode) {
+  return lines.map((line, row) => gradientLine(line, stops, mode, row * 0.06));
+}
+
+// ---------------------------------------------------------------------------
+// The mark — block-art interpretation of the ForgeDock "F" (design approved
+// from the 2026-07-03 brainstorm mockups; geometry may be pixel-tuned).
+// ---------------------------------------------------------------------------
+
+export const HERO_MARK = [
+  "            ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄",
+  "        ▄▄██████████████████",
+  "     ▄█████████████▀▀▀▀▀▀▀▀▀",
+  "   ▄██████████▀▀",
+  "    ▀▀▀▀▀  ▄▄███████▀",
+  "        ▄████████▀",
+  "      ▄██████▀",
+  "       ▀▀▀▀",
+];
+
+export const COMPACT_MARK = [
+  "   ▄▄████████",
+  " ▄█████▀▀▀▀▀",
+  " ▀▀ ▄████▀",
+  "   ▀▀▀",
+];
+
+/**
+ * Render the chrome-gradient mark.
+ * @param {'hero'|'compact'} size
+ * @param {'truecolor'|'256'|'none'} mode
+ * @returns {string[]}
+ */
+export function renderMark(size, mode) {
+  const art = size === "hero" ? HERO_MARK : COMPACT_MARK;
+  if (mode === "none") return [...art];
+  return gradientBlock(art, CHROME_STOPS, mode);
+}
+
+/** Ember-gradient text shorthand (wordmarks, act headers). */
+export function ember(text, mode) {
+  return gradientLine(text, EMBER_STOPS, mode);
+}
+
+/** Promise-based sleep for animation pacing. */
+export function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// ---------------------------------------------------------------------------
+// Animation primitives (Task 2)
+// ---------------------------------------------------------------------------
+
+import { box } from "./tui.mjs";
+
+const BRAILLE = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/** Ember-tinted status glyph for a result row. */
+function statusGlyph(ok, mode) {
+  const rgb = ok ? [255, 179, 71] : [224, 112, 80]; // amber / ember-red
+  const glyph = ok ? "✔" : "✖";
+  if (mode === "none") return glyph;
+  return `${fg(rgb, mode)}${glyph}\x1b[0m`;
+}
+
+/** Dim wrapper honoring the mode gate. */
+function dimText(s, mode) {
+  return mode === "none" ? s : `\x1b[2m${s}\x1b[22m`;
+}
+
+/** Badge like [high] / [med] / [low], colorized per confidence. */
+function badgeText(badge, mode) {
+  const label = badge === "medium" ? "med" : badge;
+  if (mode === "none") return `[${label}]`;
+  const rgb = badge === "high" ? [125, 219, 132] : badge === "medium" ? [232, 192, 96] : [224, 112, 80];
+  return `${fg(rgb, mode)}[${label}]\x1b[0m`;
+}
+
+/** Ember-bordered fix card (wraps tui.box; border color applied when able). */
+export function fixCard(lines, mode) {
+  const boxed = box(lines.map((l) => ` ${l} `), { title: "fix" });
+  if (mode === "none") return boxed;
+  const ember = fg([255, 107, 53], mode);
+  return boxed
+    .split("\n")
+    .map((l) => l.replace(/[╭╮╰╯─│]/gu, (m) => `${ember}${m}\x1b[0m`))
+    .join("\n");
+}
+
+function formatRow(label, res, mode) {
+  const parts = [`  ${statusGlyph(res.ok, mode)} ${label.padEnd(16)}`];
+  if (res.detail) parts.push(dimText(String(res.detail), mode));
+  if (res.badge) parts.push(badgeText(res.badge, mode));
+  return parts.join("  ");
+}
+
+/**
+ * Reveal rows one at a time: spinner while `run()` is in flight, settling to
+ * a ✔/✖ line (+ optional fix card). Without motion: run, print final line.
+ * Every row's `run` executes regardless of motion — this is display-only.
+ */
+export async function revealRows(
+  rows,
+  { mode, motion, writer = process.stdout, interval = 80, minDisplayMs = 120 } = {},
+) {
+  const results = [];
+  for (const row of rows) {
+    let res;
+    if (!motion) {
+      res = await row.run();
+    } else {
+      let frame = 0;
+      const spinnerColor = fg([255, 107, 53], mode);
+      const reset = mode === "none" ? "" : "\x1b[0m";
+      writer.write(`  ${spinnerColor}${BRAILLE[0]}${reset} ${row.label}\n`);
+      const timer = setInterval(() => {
+        frame = (frame + 1) % BRAILLE.length;
+        writer.write(`\x1b[1A\x1b[2K  ${spinnerColor}${BRAILLE[frame]}${reset} ${row.label}\n`);
+      }, interval);
+      const started = Date.now();
+      try {
+        res = await row.run();
+        const elapsed = Date.now() - started;
+        if (elapsed < minDisplayMs) await sleep(minDisplayMs - elapsed);
+      } finally {
+        clearInterval(timer);
+      }
+      writer.write("\x1b[1A\x1b[2K");
+    }
+    writer.write(formatRow(row.label, res, mode) + "\n");
+    if (!res.ok && res.fix && res.fix.length > 0) {
+      writer.write(fixCard(res.fix, mode) + "\n");
+    }
+    results.push(res);
+  }
+  return results;
+}
+
+/**
+ * One-pass highlight sweep over gradient block art, settling to the static
+ * gradientBlock render. In-place redraw via cursor-up; never alt-screen.
+ */
+export async function shimmer(
+  lines,
+  stops,
+  { mode, motion, writer = process.stdout, frames = 14, interval = 55 } = {},
+) {
+  const settled = gradientBlock(lines, stops, mode);
+  if (!motion || mode === "none") {
+    writer.write(settled.join("\n") + "\n");
+    return;
+  }
+  const width = Math.max(...lines.map((l) => l.length));
+  for (let f = 0; f <= frames; f++) {
+    const band = (f / frames) * (width + 16) - 8;
+    const frameLines = lines.map((line, row) => {
+      const chars = [...line];
+      let out = "";
+      for (let i = 0; i < chars.length; i++) {
+        if (chars[i] === " ") {
+          out += " ";
+          continue;
+        }
+        const t = Math.min(i / Math.max(chars.length - 1, 1) + row * 0.06, 1);
+        let rgb = sampleGradient(stops, t);
+        const dist = Math.abs(i - band + row * 1.5);
+        if (dist < 6) {
+          const boost = 1 - dist / 6;
+          rgb = rgb.map((v) => Math.round(v + (255 - v) * boost));
+        }
+        out += `\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m${chars[i]}`;
+      }
+      return out + "\x1b[0m";
+    });
+    if (f > 0) writer.write(`\x1b[${lines.length}A`);
+    writer.write(frameLines.join("\n") + "\n");
+    await sleep(interval);
+  }
+  writer.write(`\x1b[${lines.length}A`);
+  writer.write(settled.join("\n") + "\n");
+}
+
+/**
+ * One static frame of the molten progress bar: solid fill with a ▓▒ leading
+ * edge and dim ░ remainder. Caller redraws with cursor-up for animation.
+ */
+export function moltenBar(current, total, { width = 24, mode } = {}) {
+  const ratio = total === 0 ? 1 : Math.min(current / total, 1);
+  const filled = Math.round(ratio * width);
+  const solidLen = Math.max(filled - 2, 0);
+  const edge = "▓▒".slice(0, filled - solidLen);
+  const body = "█".repeat(solidLen) + edge;
+  const rest = "░".repeat(Math.max(width - filled, 0));
+  if (mode === "none") return `[${body}${rest}]`;
+  return gradientLine(body, EMBER_STOPS, mode) + dimText(rest, mode);
+}

package/bin/engine/phases.mjs

@@ -0,0 +1,148 @@
+/**
+ * Declarative phase table for the headless work-on pipeline. The ENGINE (not an
+ * LLM) chooses the next phase via pickPhase. Each phase's outcome is read from
+ * GitHub/git AFTER the run (detectOutcome); the runner's return is advisory.
+ * @typedef ... (see plan "Shared types")
+ */
+
+export const TERMINAL_REASONS = ["merged", "invalid", "needs-human", "decomposed"];
+
+/** Fetch the issue's comment bodies as one blob for marker checks. */
+async function issueMarkers(issue, io) {
+  const out = await io.gh(["api", `repos/{owner}/{repo}/issues/${issue}/comments`, "--jq", ".[].body"]);
+  return out || "";
+}
+/**
+ * Count commits on branch ahead of the lane base. On the first build the
+ * branch does not exist yet, so real git rejects the ref range — swallow
+ * that (and any other git failure) as "0 ahead" rather than letting it
+ * propagate and crash runIssue (C1).
+ */
+async function commitsAhead(state, io) {
+  try {
+    const n = await io.git(["rev-list", "--count", `origin/${state.lane}..${state.branch}`]);
+    return parseInt(String(n).trim(), 10) || 0;
+  } catch {
+    return 0;
+  }
+}
+function has(blob, marker) { return blob.includes(marker); }
+
+/** @type {Phase[]} */
+export const PHASES = [
+  {
+    id: "investigate",
+    command: "work-on/investigate",
+    entryCondition: () => true,
+    async detectOutcome(state, io) {
+      const m = await issueMarkers(state.issue, io);
+      if (has(m, "INVESTIGATION:INVALID"))
+        return { status: "committed", terminalReason: "invalid", outputs: { verdict: "INVALID" } };
+      if (has(m, "DECOMPOSE:YES"))
+        return { status: "committed", terminalReason: "decomposed", outputs: { decompose: true } };
+      if (has(m, "INVESTIGATION:COMPLETE"))
+        return { status: "committed", outputs: { verdict: "CONFIRMED" } };
+      return { status: "failed", detail: "no INVESTIGATION:COMPLETE marker" };
+    },
+    isTerminalAfter: (s) => s.terminalReason === "invalid" || s.terminalReason === "decomposed",
+  },
+  {
+    id: "context",
+    command: "work-on/build/context",
+    entryCondition: (s) => s.committed.includes("investigate"),
+    async detectOutcome(state, io) {
+      const m = await issueMarkers(state.issue, io);
+      // Context is non-critical: a missing marker is a VISIBLE skip, not a hard fail (spec §7).
+      if (has(m, "FORGE:CONTEXT")) return { status: "committed", outputs: {} };
+      return { status: "committed", outputs: { skipped: true, which: "context" } };
+    },
+  },
+  {
+    id: "architect",
+    command: "work-on/build/architect",
+    entryCondition: (s) => s.committed.includes("context"),
+    async detectOutcome(state, io) {
+      const m = await issueMarkers(state.issue, io);
+      return has(m, "FORGE:ARCHITECT")
+        ? { status: "committed", outputs: {} }
+        : { status: "failed", detail: "no FORGE:ARCHITECT" };
+    },
+  },
+  {
+    id: "build",
+    command: "work-on/build",
+    entryCondition: (s) => s.committed.includes("architect"),
+    async reconcile(state, io) {
+      // Idempotent resume: branch already ahead of base → treat as done, skip the LLM.
+      if (state.branch && (await commitsAhead(state, io)) > 0) {
+        const m = await issueMarkers(state.issue, io);
+        if (has(m, "FORGE:BUILDER:COMPLETE")) return { satisfied: true, outputs: { branch: state.branch } };
+      }
+      return { satisfied: false };
+    },
+    async detectOutcome(state, io) {
+      const m = await issueMarkers(state.issue, io);
+      const complete = has(m, "FORGE:BUILDER:COMPLETE");           // #1305: require :COMPLETE …
+      const ahead = state.branch ? await commitsAhead(state, io) : 0; // … AND real commits
+      if (complete && ahead > 0) return { status: "committed", outputs: { branch: state.branch } };
+      return { status: "failed", detail: `builder complete=${complete} commitsAhead=${ahead}` };
+    },
+  },
+  {
+    id: "review",
+    command: "work-on/review",
+    entryCondition: (s) => s.committed.includes("build"),
+    async reconcile(state, io) {
+      const pr = await openPrFor(state, io);   // adopt an existing PR instead of opening a second
+      return pr ? { satisfied: false, outputs: { pr } } : { satisfied: false };
+    },
+    async detectOutcome(state, io) {
+      const pr = await prStatusFor(state, io);
+      if (!pr) return { status: "failed", detail: "no PR created" };
+      if (pr.merged) return { status: "committed", outputs: { pr: pr.number } };
+      if (pr.needsHuman) return { status: "blocked", detail: "review escalated", outputs: { pr: pr.number } };
+      return { status: "failed", detail: "PR open, not merged" };
+    },
+  },
+  {
+    id: "close",
+    command: "work-on/close",
+    entryCondition: (s) => s.committed.includes("review"),
+    async detectOutcome(state, io) {
+      const out = await io.gh(["issue", "view", String(state.issue), "--json", "state,labels"]);
+      let j;
+      try { j = JSON.parse(out || "{}"); } catch { return { status: "failed", detail: "malformed gh response" }; }
+      const labels = (j.labels || []).map((l) => l.name || l);
+      if (j.state === "CLOSED" || labels.includes("workflow:merged"))
+        return { status: "committed", terminalReason: "merged", outputs: {} };
+      return { status: "failed", detail: "issue not closed" };
+    },
+    isTerminalAfter: () => true,
+  },
+];
+
+async function openPrFor(state, io) {
+  if (!state.branch) return null;
+  const out = await io.gh(["pr", "list", "--head", state.branch, "--json", "number", "--state", "all"]);
+  try { const a = JSON.parse(out || "[]"); return a[0]?.number ?? null; } catch { return null; }
+}
+async function prStatusFor(state, io) {
+  const n = await openPrFor(state, io);
+  if (!n) return null;
+  const out = await io.gh(["pr", "view", String(n), "--json", "number,state,labels,mergedAt"]);
+  let j;
+  try { j = JSON.parse(out || "{}"); } catch { return null; }
+  const labels = (j.labels || []).map((l) => l.name || l);
+  return { number: j.number, merged: !!j.mergedAt || j.state === "MERGED",
+           needsHuman: labels.includes("needs-human") };
+}
+
+/** The engine's transition function: first uncommitted phase whose gate holds. */
+export function pickPhase(state) {
+  if (state.terminal) return null;
+  for (const p of PHASES) {
+    if (state.committed.includes(p.id)) continue;
+    if (p.entryCondition(state)) return p;
+  }
+  return null;
+}

package/bin/engine/projector.mjs

@@ -0,0 +1,32 @@
+/**
+ * GitHub adapter: reads/writes the FORGE:STATE block and workflow labels.
+ * `io.gh(args)` is injected (async, returns stdout) so this is testable offline.
+ */
+import { parseState, upsertStateBlock } from "./state.mjs";
+
+export function makeProjector(io) {
+  const gh = io.gh;
+
+  async function getBody(issue) {
+    const out = await gh(["issue", "view", String(issue), "--json", "body"]);
+    try { return JSON.parse(out).body ?? ""; } catch { return ""; }
+  }
+
+  return {
+    /** @returns {Promise<import("./phases.mjs").RunState|null>} */
+    async readState(issue) { return parseState(await getBody(issue)); },
+
+    async writeState(issue, index) {
+      const body = upsertStateBlock(await getBody(issue), index);
+      await gh(["issue", "edit", String(issue), "--body", body]);
+    },
+
+    async setLabel(issue, label) {
+      await gh(["issue", "edit", String(issue), "--add-label", label]);
+    },
+
+    async removeLabel(issue, label) {
+      await gh(["issue", "edit", String(issue), "--remove-label", label]);
+    },
+  };
+}

package/bin/engine/reconcile.mjs

@@ -0,0 +1,11 @@
+/**
+ * Merge the local run-log state and the remote FORGE:STATE index.
+ * Rule: GitHub wins on divergence (spec §5.3).
+ */
+export function reconcileState(local, remote) {
+  if (!remote) return { state: local ?? null, action: local ? "local" : "fresh" };
+  if (!local) return { state: remote, action: "hydrate" };
+  if (remote.v > local.v) return { state: remote, action: "hydrate" };   // advanced elsewhere
+  if (remote.v < local.v) return { state: local, action: "remirror" };   // crashed pre-mirror
+  return { state: local, action: "local" };
+}

package/bin/engine/runlog.mjs

@@ -0,0 +1,79 @@
+/**
+ * Append-only per-issue run-log (the crash-safe local hot path).
+ * One JSON event per line at {dir}/{issue}.jsonl. seq is assigned monotonically.
+ */
+import { readFileSync, appendFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+function logPath(dir, issue) { return join(dir, `${issue}.jsonl`); }
+
+/** Append an event; assigns the next seq based on the current line count. */
+export function appendEvent(dir, issue, event) {
+  mkdirSync(dir, { recursive: true });
+  const path = logPath(dir, issue);
+  const seq = readLog(dir, issue).length + 1;
+  appendFileSync(path, JSON.stringify({ seq, ...event }) + "\n");
+}
+
+/**
+ * Overwrite the local run-log with a fresh set of events (fresh seq each).
+ * Used to reconstruct the local log from a remote FORGE:STATE index on
+ * hydrate (C2), so the local log and the GitHub-wins state stay consistent.
+ */
+export function rewriteLog(dir, issue, events) {
+  mkdirSync(dir, { recursive: true });
+  const path = logPath(dir, issue);
+  const lines = events.map((e, i) => JSON.stringify({ seq: i + 1, ...e }));
+  writeFileSync(path, lines.length ? lines.join("\n") + "\n" : "");
+}
+
+/** Read all complete events; a truncated final line (crash mid-write) is ignored. */
+export function readLog(dir, issue) {
+  const path = logPath(dir, issue);
+  if (!existsSync(path)) return [];
+  const lines = readFileSync(path, "utf-8").split("\n");
+  // Drop trailing empty lines to find the last non-empty line.
+  while (lines.length > 0 && !lines[lines.length - 1].trim()) lines.pop();
+
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch (err) {
+      // Only tolerate parse failure on the final non-empty line (crash mid-write).
+      if (i === lines.length - 1) {
+        break; // Ignore truncated final line.
+      }
+      throw new Error(`corrupt run-log line ${i + 1} in ${path}`);
+    }
+  }
+  return out;
+}
+
+/** Fold events into a RunState. The commit rule lives here. */
+export function deriveState(events) {
+  /** @type {import("./phases.mjs").RunState} */
+  const s = { v: 0, run: null, issue: null, lane: "staging", committed: [],
+              phase: null, branch: null, pr: null, terminal: false,
+              terminalReason: null, lease: null };
+  for (const e of events) {
+    switch (e.event) {
+      case "RUN_START":
+        s.run = e.run ?? s.run; s.issue = e.issue ?? s.issue; s.lane = e.lane ?? s.lane;
+        break;
+      case "PHASE_COMMIT":
+        if (!s.committed.includes(e.phase)) s.committed.push(e.phase);
+        s.v = e.seq;
+        if (e.outputs?.branch) s.branch = e.outputs.branch;
+        if (e.outputs?.pr != null) s.pr = e.outputs.pr;
+        break;
+      case "RUN_TERMINAL":
+        s.terminal = true; s.terminalReason = e.reason ?? "done"; s.v = e.seq;
+        break;
+      // PHASE_START / PHASE_FAILED do not change committed state
+    }
+  }
+  return s;
+}

package/bin/engine/state.mjs

@@ -0,0 +1,27 @@
+/**
+ * Codec for the single machine-readable FORGE:STATE HTML-comment block on an
+ * issue body. Carries the COMPACT INDEX only (no rich per-phase outputs).
+ */
+const OPEN = "<!-- FORGE:STATE";
+const CLOSE = "-->";
+// NOTE: a literal "-->" inside a serialized value would close the block early; terminalReason etc. should not contain it. Tracked as a follow-up.
+const BLOCK_RE = /<!-- FORGE:STATE\s*([\s\S]*?)-->/;
+
+/** @param {import("./phases.mjs").RunState} index */
+export function serializeState(index) {
+  return `${OPEN}\n${JSON.stringify(index)}\n${CLOSE}`;
+}
+
+/** @returns {import("./phases.mjs").RunState|null} */
+export function parseState(issueBody) {
+  const m = BLOCK_RE.exec(issueBody || "");
+  if (!m) return null;
+  try { return JSON.parse(m[1].trim()); } catch { return null; }
+}
+
+/** Replace the FORGE:STATE block in place, or append one if absent. */
+export function upsertStateBlock(body, index) {
+  const block = serializeState(index);
+  if (BLOCK_RE.test(body || "")) return body.replace(BLOCK_RE, () => block);
+  return `${body || ""}\n\n${block}`.trimStart();
+}

package/bin/engine-cli.mjs

@@ -0,0 +1,50 @@
+/**
+ * Headless entry point: `forgedock run-issue <issue>` drives one issue through the
+ * durable engine; scanStalls finds dead-lease issues for the orchestrator to resume.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { runIssue } from "./engine.mjs";
+
+const pexec = promisify(execFile);
+
+/** Real gh/git accessors. */
+export function makeIo() {
+  const run = (bin) => async (args) => {
+    const { stdout } = await pexec(bin, args, { maxBuffer: 100 * 1024 * 1024 });
+    return stdout;
+  };
+  return { gh: run("gh"), git: run("git") };
+}
+
+export function runDir() { return join(homedir(), ".forge", "runs"); }
+
+/**
+ * @param {number[]} issues
+ * @param {{readState:(i:number)=>Promise<{terminal:boolean,lease:?{until:number}}|null>}} io
+ * @param {number} now
+ * @returns {Promise<number[]>} issues that appear stalled (expired lease, non-terminal)
+ */
+export async function scanStalls(issues, io, now) {
+  const stalled = [];
+  for (const i of issues) {
+    const s = await io.readState(i);
+    if (s && !s.terminal && s.lease && s.lease.until < now) stalled.push(i);
+  }
+  return stalled;
+}
+
+export async function runFromCli(argv) {
+  const issue = parseInt(argv[0], 10);
+  if (!Number.isInteger(issue)) throw new Error("usage: forgedock run-issue <issue-number>");
+  const lane = flag(argv, "--lane") || "staging";
+  const io = makeIo();
+  const agentId = `cli_${process.pid}`;
+  const res = await runIssue({ issue, dir: runDir(), agentId, lane, io,
+    runner: (await import("./runner.mjs")).runCommand, now: () => Date.now() });
+  console.log(`issue #${issue} → ${res.terminalReason}`);
+  return res;
+}
+function flag(argv, name) { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : null; }