forgedock 1.0.22 → 1.1.2

package/bin/demo.mjs

@@ -61,6 +61,9 @@ export const DEFAULT_DEMO_DIRNAME = "forgedock-demo";
  *   --repo <slug> | --repo=<slug> Override the demo repo (owner/name).
  *   --open                        Launch Claude Code in the demo dir when found.
  *   --no-open                     Explicitly disable launching (the default).
+ *   --run                         Run the seeded issue through /work-on automatically
+ *                                 (requires ANTHROPIC_API_KEY; falls back to print-only
+ *                                 instructions when the key is absent).
  *   --help | -h                   Show usage.
  *
  * The first non-flag argument is treated as the target directory (positional
@@ -68,8 +71,8 @@ export const DEFAULT_DEMO_DIRNAME = "forgedock-demo";
  *
  * @param {string[]} args
  * @returns {{positional: string|undefined, dir: string|undefined,
- *            repo: string|undefined, open: boolean, help: boolean,
- *            error: string|null}}
+ *            repo: string|undefined, open: boolean, run: boolean,
+ *            help: boolean, error: string|null}}
  */
 export function parseDemoArgs(args = []) {
   const out = {
@@ -77,6 +80,7 @@ export function parseDemoArgs(args = []) {
     dir: undefined,
     repo: undefined,
     open: false,
+    run: false,
     help: false,
     error: null,
   };
@@ -88,6 +92,8 @@ export function parseDemoArgs(args = []) {
       out.open = true;
     } else if (a === "--no-open") {
       out.open = false;
+    } else if (a === "--run") {
+      out.run = true;
     } else if (a === "--dir") {
       out.dir = args[++i];
       if (out.dir === undefined) out.error = "--dir requires a path argument";
@@ -145,7 +151,7 @@ function isEmptyDir(dir, fsx) {
 
 export function demoUsage() {
   return [
-    "Usage: forgedock demo [dir] [--dir <path>] [--repo <owner/name>] [--open]",
+    "Usage: forgedock demo [dir] [--dir <path>] [--repo <owner/name>] [--open] [--run]",
     "",
     "Stand up a runnable ForgeDock demo at a predictable location (default",
     "~/forgedock-demo) and print the exact next steps. No configuration needed.",
@@ -155,6 +161,9 @@ export function demoUsage() {
     "  --repo <slug>    Demo repo to clone (default: RapierCraftStudios/forgedock-demo).",
     "  --open           Launch Claude Code in the demo directory if available.",
     "  --no-open        Do not launch Claude Code (default).",
+    "  --run            Automatically run the seeded issue through /work-on to a",
+    "                   merged PR (requires ANTHROPIC_API_KEY; falls back to",
+    "                   print-only instructions when the key is absent).",
     "  -h, --help       Show this help.",
   ].join("\n");
 }
@@ -186,10 +195,10 @@ export function demoForgeYaml(repoSlug) {
 
 /**
  * Render the success / next-steps card.
- * @param {{target: string, source: string, claudeAvailable: boolean}} ctx
+ * @param {{target: string, source: string, claudeAvailable: boolean, apiKeyAvailable?: boolean}} ctx
  * @returns {string}
  */
-export function renderNextSteps({ target, source, claudeAvailable }) {
+export function renderNextSteps({ target, source, claudeAvailable, apiKeyAvailable = false }) {
   const sourceNote = {
     cloned: "Cloned the live demo repo.",
     pulled: "Demo already present — pulled the latest.",
@@ -214,6 +223,15 @@ export function renderNextSteps({ target, source, claudeAvailable }) {
       ? "  claude            # open Claude Code here (or re-run with --open)"
       : "  # then open Claude Code in this directory",
   ];
+
+  if (!apiKeyAvailable) {
+    lines.push(
+      "",
+      "Tip: set ANTHROPIC_API_KEY and re-run with --run to execute the pipeline",
+      "automatically and watch a PR merge without opening Claude Code.",
+    );
+  }
+
   return lines.join("\n");
 }
 
@@ -261,11 +279,12 @@ const defaultLogger = {
  * Stand up the demo.
  *
  * @param {object} opts
- * @param {string}  opts.forgeHome            - Package root (for bundled scaffold).
+ * @param {string}  opts.forgeHome            - Package root (for bundled scaffold and commands/).
  * @param {string[]} [opts.args]              - CLI args after `demo`.
  * @param {string}  [opts.home]               - Home dir (default os.homedir()).
  * @param {string}  [opts.cwd]                - Working dir (default process.cwd()).
  * @param {string}  [opts.demoRepo]           - Override demo repo slug.
+ * @param {string}  [opts.apiKey]             - Anthropic API key (default ANTHROPIC_API_KEY env).
  * @param {Function} [opts.exec]              - (cmd, args, {cwd}) => {status,...}.
  * @param {object}  [opts.fsx]                - Filesystem facade.
  * @param {Function} [opts.commandExists]     - (bin) => boolean.
@@ -279,6 +298,7 @@ export async function runDemo(opts = {}) {
     args = [],
     home = homedir(),
     cwd = process.cwd(),
+    apiKey = process.env.ANTHROPIC_API_KEY,
     exec = defaultExec,
     fsx = defaultFsx,
     commandExists = defaultCommandExists,
@@ -371,7 +391,72 @@ export async function runDemo(opts = {}) {
   }
 
   const claudeAvailable = commandExists("claude");
-  logger.log(renderNextSteps({ target, source, claudeAvailable }));
+  const apiKeyAvailable = Boolean(apiKey);
+
+  // --run: drive the seeded issue through /work-on automatically.
+  // Requires ANTHROPIC_API_KEY; falls back to print-only instructions gracefully.
+  if (parsed.run) {
+    if (!apiKeyAvailable) {
+      logger.log(
+        "\nANTHROPIC_API_KEY is not set — cannot run the pipeline automatically.\n" +
+        "Export your key and re-run with --run, or open Claude Code manually:\n",
+      );
+      logger.log(renderNextSteps({ target, source, claudeAvailable, apiKeyAvailable: false }));
+      return { status: "ok", target, source };
+    }
+
+    const commandsDir = forgeHome ? join(forgeHome, "commands") : null;
+    if (!commandsDir || !fsx.existsSync(commandsDir)) {
+      logger.error(
+        "Could not locate the ForgeDock commands/ directory. " +
+        "Falling back to manual instructions.",
+      );
+      logger.log(renderNextSteps({ target, source, claudeAvailable, apiKeyAvailable }));
+      return { status: "ok", target, source };
+    }
+
+    logger.log(
+      "\nRunning /work-on 1 in the demo repo — watch the full pipeline execute…\n",
+    );
+
+    let runCommand;
+    try {
+      ({ runCommand } = await import("./runner.mjs"));
+    } catch {
+      logger.error(
+        "Could not load bin/runner.mjs. Falling back to manual instructions.",
+      );
+      logger.log(renderNextSteps({ target, source, claudeAvailable, apiKeyAvailable }));
+      return { status: "ok", target, source };
+    }
+
+    try {
+      const result = await runCommand({
+        commandsDir,
+        commandName: "work-on",
+        args: ["1"],
+        cwd: target,
+        apiKey,
+        logger: { log: logger.log, error: logger.error },
+      });
+      logger.log(`\nDemo pipeline finished with status: ${result.status}`);
+      return { status: result.status === "ok" ? "ok" : result.status, target, source };
+    } catch (err) {
+      if (err.code === "NO_SDK") {
+        logger.error(
+          "\n@anthropic-ai/sdk is not installed. Install it with:\n" +
+          "  npm install @anthropic-ai/sdk\n" +
+          "Then re-run with --run, or open Claude Code manually:\n",
+        );
+      } else {
+        logger.error(`\nPipeline error: ${err.message}\nFalling back to manual instructions.\n`);
+      }
+      logger.log(renderNextSteps({ target, source, claudeAvailable, apiKeyAvailable }));
+      return { status: "ok", target, source };
+    }
+  }
+
+  logger.log(renderNextSteps({ target, source, claudeAvailable, apiKeyAvailable }));
 
   if (parsed.open) {
     if (claudeAvailable) {

package/bin/engine/phases.mjs

@@ -0,0 +1,168 @@
+/**
+ * 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 reconcile(state, io) {
+      // Idempotent resume: FORGE:CONTEXT already present → skip the LLM re-run.
+      const m = await issueMarkers(state.issue, io);
+      return has(m, "FORGE:CONTEXT") ? { satisfied: true } : { satisfied: false };
+    },
+    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 reconcile(state, io) {
+      // Idempotent resume: FORGE:ARCHITECT already present → skip the LLM re-run.
+      const m = await issueMarkers(state.issue, io);
+      return has(m, "FORGE:ARCHITECT") ? { satisfied: true } : { satisfied: false };
+    },
+    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 reconcile(state, io) {
+      // Idempotent resume: issue already closed or workflow:merged label set → skip the LLM re-run.
+      const out = await io.gh(["issue", "view", String(state.issue), "--json", "state,labels"]);
+      let j;
+      try { j = JSON.parse(out || "{}"); } catch { return { satisfied: false }; }
+      const labels = (j.labels || []).map((l) => l.name || l);
+      return (j.state === "CLOSED" || labels.includes("workflow:merged"))
+        ? { satisfied: true }
+        : { satisfied: false };
+    },
+    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,32 @@
+/**
+ * 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 = "-->";
+const BLOCK_RE = /<!-- FORGE:STATE\s*([\s\S]*?)-->/;
+
+/** @param {import("./phases.mjs").RunState} index */
+export function serializeState(index) {
+  // Escape both HTML comment-close forms: the standard "-->" and the "--!>"
+  // variant that browsers/HTML parsers also honour. JSON.stringify does not
+  // escape either, so a payload value containing them could otherwise close
+  // the <!-- FORGE:STATE ... --> block early (CodeQL js/bad-tag-filter).
+  const payload = JSON.stringify(index).replace(/--(!?)>/g, "--$1&gt;");
+  return `${OPEN}\n${payload}\n${CLOSE}`;
+}
+
+/** @returns {import("./phases.mjs").RunState|null} */
+export function parseState(issueBody) {
+  const m = BLOCK_RE.exec(issueBody || "");
+  if (!m) return null;
+  // Inverse of serializeState: restore both "--&gt;" and "--!&gt;".
+  try { return JSON.parse(m[1].trim().replace(/--(!?)&gt;/g, "--$1>")); } 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();
+}