cool-workflow 0.1.90 → 0.1.92

package/scripts/agents/codex-agent.js

@@ -20,10 +20,10 @@ const path = require("node:path");
 const { spawn } = require("node:child_process");
 const {
   buildPrompt,
+  createRenderer,
   emitReport,
   flushJsonLines,
   parseJsonLines,
-  trace,
   writeResult
 } = require("./agent-adapter-core");
 
@@ -42,7 +42,9 @@ try {
 }
 
 const prompt = buildPrompt(inputPath);
-const state = { provider: "codex", buffer: "", model: undefined, usage: undefined };
+const render = createRenderer({ env: process.env, stderr: process.stderr, label: "codex" });
+const transcriptPath = path.join(path.dirname(resultPath), "transcript.md");
+const state = { provider: "codex", buffer: "", model: undefined, usage: undefined, renderer: render };
 const capturedStdout = [];
 let childStderr = "";
 function recordJsonLine(line) {
@@ -54,7 +56,7 @@ function recordJsonLine(line) {
   }
 }
 
-trace("* codex: reading the repo (read-only)...");
+render.action("codex: reading the repo (read-only)…");
 
 const args = [
   "exec",
@@ -83,21 +85,23 @@ child.stdout.on("data", (chunk) => {
   parseJsonLines("codex", chunk, state, recordJsonLine);
 });
 
+// Capture codex's own stderr (do NOT inherit) so it can never corrupt the live region; it's
+// surfaced only on a non-zero exit.
 child.stderr.setEncoding("utf8");
 child.stderr.on("data", (chunk) => {
-  childStderr += chunk;
-  if (process.env.CW_AGENT_STREAM !== "0" && process.env.CW_NO_STREAM !== "1" && process.stderr.isTTY) {
-    process.stderr.write(chunk);
-  }
+  if (childStderr.length < 1024 * 1024) childStderr += chunk;
 });
 
 child.on("error", (error) => {
+  render.finishLive();
   process.stderr.write(`codex spawn failed: ${error.message}\n`);
   process.exit(1);
 });
 
 child.on("close", (code) => {
   flushJsonLines("codex", state, recordJsonLine);
+  render.finishLive();
+  render.writeTranscript(transcriptPath);
   if (code !== 0) {
     const detail = childStderr.trim() || `codex exited ${code === null ? "(timeout/killed)" : code}`;
     process.stderr.write(`${detail}\n`);
@@ -129,6 +133,5 @@ child.on("close", (code) => {
     process.exit(1);
   }
 
-  trace("* done - result captured");
   emitReport(state.model, state.usage, resultText);
 });

package/scripts/agents/gemini-agent.js

@@ -14,13 +14,14 @@
 // stdout: one JSON object { model, usage, result } for CW provenance.
 // stderr: optional live trace when CW_AGENT_STREAM=1 and attached to a TTY.
 
+const path = require("node:path");
 const { spawn } = require("node:child_process");
 const {
   buildPrompt,
+  createRenderer,
   emitReport,
   flushJsonLines,
   parseJsonLines,
-  trace,
   writeResult
 } = require("./agent-adapter-core");
 
@@ -32,7 +33,9 @@ if (!inputPath || !resultPath) {
 }
 
 const prompt = buildPrompt(inputPath);
-const state = { provider: "gemini", buffer: "", model: undefined, usage: undefined, textFragments: [], finalResult: undefined };
+const render = createRenderer({ env: process.env, stderr: process.stderr, label: "gemini" });
+const transcriptPath = path.join(path.dirname(resultPath), "transcript.md");
+const state = { provider: "gemini", buffer: "", model: undefined, usage: undefined, textFragments: [], finalResult: undefined, renderer: render };
 let childStderr = "";
 function recordJsonLine(line) {
   let ev;
@@ -51,7 +54,7 @@ function recordJsonLine(line) {
   }
 }
 
-trace("* gemini: reading the repo (read-only)...");
+render.action("gemini: reading the repo (read-only)…");
 
 const args = [
   "-p",
@@ -72,21 +75,22 @@ child.stdout.on("data", (chunk) => {
   parseJsonLines("gemini", chunk, state, recordJsonLine);
 });
 
+// Capture gemini's own stderr (do NOT inherit) so it can never corrupt the live region.
 child.stderr.setEncoding("utf8");
 child.stderr.on("data", (chunk) => {
-  childStderr += chunk;
-  if (process.env.CW_AGENT_STREAM !== "0" && process.env.CW_NO_STREAM !== "1" && process.stderr.isTTY) {
-    process.stderr.write(chunk);
-  }
+  if (childStderr.length < 1024 * 1024) childStderr += chunk;
 });
 
 child.on("error", (error) => {
+  render.finishLive();
   process.stderr.write(`gemini spawn failed: ${error.message}\n`);
   process.exit(1);
 });
 
 child.on("close", (code) => {
   flushJsonLines("gemini", state, recordJsonLine);
+  render.finishLive();
+  render.writeTranscript(transcriptPath);
   if (code !== 0) {
     const detail = childStderr.trim() || `gemini exited ${code === null ? "(timeout/killed)" : code}`;
     process.stderr.write(`${detail}\n`);
@@ -110,6 +114,5 @@ child.on("close", (code) => {
     process.exit(1);
   }
 
-  trace("* done - result captured");
   emitReport(state.model, state.usage, resultText);
 });

package/scripts/agents/opencode-agent.js

@@ -19,13 +19,14 @@
 // via execution-backend boundary controls. If OpenCode adds a cleaner read-only
 // flag, prefer that here.
 
+const path = require("node:path");
 const { spawn } = require("node:child_process");
 const {
   buildPrompt,
+  createRenderer,
   emitReport,
   flushJsonLines,
   parseJsonLines,
-  trace,
   writeResult
 } = require("./agent-adapter-core");
 
@@ -37,7 +38,9 @@ if (!inputPath || !resultPath) {
 }
 
 const prompt = buildPrompt(inputPath);
-const state = { provider: "opencode", buffer: "", model: undefined, usage: undefined, textFragments: [], finalResult: undefined };
+const render = createRenderer({ env: process.env, stderr: process.stderr, label: "opencode" });
+const transcriptPath = path.join(path.dirname(resultPath), "transcript.md");
+const state = { provider: "opencode", buffer: "", model: undefined, usage: undefined, textFragments: [], finalResult: undefined, renderer: render };
 let childStderr = "";
 function recordJsonLine(line) {
   let ev;
@@ -55,7 +58,7 @@ function recordJsonLine(line) {
   }
 }
 
-trace("* opencode: reading the repo...");
+render.action("opencode: reading the repo…");
 
 const args = [
   "run",
@@ -76,21 +79,22 @@ child.stdout.on("data", (chunk) => {
   parseJsonLines("opencode", chunk, state, recordJsonLine);
 });
 
+// Capture opencode's own stderr (do NOT inherit) so it can never corrupt the live region.
 child.stderr.setEncoding("utf8");
 child.stderr.on("data", (chunk) => {
-  childStderr += chunk;
-  if (process.env.CW_AGENT_STREAM !== "0" && process.env.CW_NO_STREAM !== "1" && process.stderr.isTTY) {
-    process.stderr.write(chunk);
-  }
+  if (childStderr.length < 1024 * 1024) childStderr += chunk;
 });
 
 child.on("error", (error) => {
+  render.finishLive();
   process.stderr.write(`opencode spawn failed: ${error.message}\n`);
   process.exit(1);
 });
 
 child.on("close", (code) => {
   flushJsonLines("opencode", state, recordJsonLine);
+  render.finishLive();
+  render.writeTranscript(transcriptPath);
   if (code !== 0) {
     const detail = childStderr.trim() || `opencode exited ${code === null ? "(timeout/killed)" : code}`;
     process.stderr.write(`${detail}\n`);
@@ -114,6 +118,5 @@ child.on("close", (code) => {
     process.exit(1);
   }
 
-  trace("* done - result captured");
   emitReport(state.model, state.usage, resultText);
 });

package/scripts/bump-version.js

@@ -167,7 +167,10 @@ function contentSurfaceFiles(next) {
   // All files the version-sync-check script validates for VERSION or vX.Y.Z.
   // Keep in sync with scripts/version-sync-check.js.
   return [
-    { path: "plugins/cool-workflow/README.md", needle: `v${next}`,          desc: "README version tag" },
+    // The npm package README (plugins/cool-workflow/README.md) is GENERATED from the GitHub
+    // README.md by scripts/sync-readme.js and shows the version via the live npm/release shields
+    // badges, not a hand-maintained literal — so it is NOT a version-bump surface. After a bump,
+    // `npm run sync:readme` keeps it byte-identical to the GitHub README (guarded by readme:check).
     { path: "plugins/cool-workflow/docs/multi-agent-cli-mcp-surface.7.md",   needle: next, desc: "multi-agent CLI/MCP surface doc" },
     { path: "plugins/cool-workflow/docs/multi-agent-operator-ux.7.md",       needle: next, desc: "multi-agent operator UX doc" },
     { path: "plugins/cool-workflow/docs/multi-agent-eval-replay-harness.7.md", needle: next, desc: "multi-agent eval/replay doc" },

package/scripts/canonical-apps.js

@@ -83,7 +83,7 @@ const canonicalApps = [
       "--source",
       "plugins/cool-workflow/docs/workflow-app-framework.7.md",
       "--scope",
-      "Cool Workflow v0.1.90",
+      "Cool Workflow v0.1.92",
       "--freshness",
       "as of release preparation"
     ]
@@ -117,14 +117,14 @@ function main() {
     assert.ok(summary, `${app.id} must appear in app list`);
     assert.equal(summary.sourceKind, "app-directory");
     assert.equal(summary.legacy, false);
-    assert.equal(summary.version, "0.1.90");
+    assert.equal(summary.version, "0.1.92");
 
     const validation = runJson(["app", "validate", manifestPath]);
     assert.equal(validation.valid, true, `${app.id} manifest must validate`);
 
     const shown = runJson(["app", "show", app.id]);
     assert.equal(shown.app.id, app.id);
-    assert.equal(shown.app.version, "0.1.90");
+    assert.equal(shown.app.version, "0.1.92");
     assert.ok(shown.app.metadata.canonical, `${app.id} must be marked canonical`);
     assert.ok(shown.app.sandboxProfiles.length > 0, `${app.id} must declare sandbox profiles`);
     assertTaskIdsUnique(shown);
@@ -135,7 +135,7 @@ function main() {
     const plan = runJson(["plan", app.id, ...app.args(workspace)]);
     const state = JSON.parse(fs.readFileSync(plan.statePath, "utf8"));
     assert.equal(state.workflow.app.id, app.id);
-    assert.equal(state.workflow.app.version, "0.1.90");
+    assert.equal(state.workflow.app.version, "0.1.92");
     assert.equal(state.workflow.app.metadata.canonical, true);
     assert.ok(state.tasks.some((task) => task.requiresEvidence), `${app.id} plan must include evidence gates`);
     assert.ok(state.tasks.every((task) => task.sandboxProfileId), `${app.id} plan must include sandbox hints`);

package/scripts/dogfood-release.js

@@ -6,7 +6,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 const { CoolWorkflowRunner } = require("../dist/orchestrator.js");
 
-const TARGET_VERSION = "0.1.90";
+const TARGET_VERSION = "0.1.92";
 const PREVIOUS_VERSION = "0.1.31";
 const pluginRoot = path.resolve(__dirname, "..");
 const repoRoot = path.resolve(pluginRoot, "..", "..");

package/scripts/golden-path.js

@@ -33,7 +33,7 @@ function main() {
     const appValidation = runJson(["app", "validate", "end-to-end-golden-path"], pluginRoot);
     assert.equal(appValidation.valid, true);
     assert.equal(appValidation.summary.id, "end-to-end-golden-path");
-    assert.equal(appValidation.summary.version, "0.1.90");
+    assert.equal(appValidation.summary.version, "0.1.92");
 
     const plan = runJson(
       [
@@ -42,7 +42,7 @@ function main() {
         "--repo",
         tmp,
         "--question",
-        "Prove the deterministic v0.1.90 end-to-end golden path."
+        "Prove the deterministic v0.1.92 end-to-end golden path."
       ],
       pluginRoot
     );
@@ -52,7 +52,7 @@ function main() {
 
     let state = readJson(plan.statePath);
     assert.equal(state.workflow.app.id, "end-to-end-golden-path");
-    assert.equal(state.workflow.app.version, "0.1.90");
+    assert.equal(state.workflow.app.version, "0.1.92");
     assert.equal(state.loopStage, "interpret");
 
     const dispatch = runJson(["dispatch", plan.runId, "--limit", "1", "--sandbox", "readonly"], tmp);
@@ -195,7 +195,7 @@ function main() {
     assert.equal(reportPath, plan.reportPath);
     assert.ok(fs.existsSync(reportPath));
     const report = fs.readFileSync(reportPath, "utf8");
-    assert.match(report, /Workflow App: end-to-end-golden-path@0\.1\.90/);
+    assert.match(report, /Workflow App: end-to-end-golden-path@0\.1\.92/);
     assert.match(report, /## Candidates/);
     assert.match(report, /## Trust Audit/);
     assert.match(report, /## Acceptance Rationale/);

package/scripts/release-check.js

@@ -74,7 +74,11 @@ const checks = [
   // drifted from a fresh source scan. The teeth-on-the-gate live in
   // test/project-index-sync-smoke.js (run by `npm test`); this entry gives the
   // real-doc check its own visible PASS/FAIL line in the release summary.
-  { name: "project index sync", command: ["npm", "run", "index:check"] }
+  { name: "project index sync", command: ["npm", "run", "index:check"] },
+  // Fail closed if the npm README (plugins/cool-workflow/README.md) has drifted
+  // from the GitHub README.md it is generated from. Keeps the two pages identical
+  // by construction; teeth live in test/readme-sync-smoke.js (run by `npm test`).
+  { name: "readme sync", command: ["npm", "run", "readme:check"] }
 ];
 
 function main() {

package/scripts/sync-readme.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+"use strict";
+
+// sync-readme — keep the npm package README in lockstep with the GitHub README.
+//
+// The repo-root README.md is the SINGLE SOURCE OF TRUTH. This generates the npm
+// page (plugins/cool-workflow/README.md) from it, changing ONLY what npm needs to
+// render: relative URLs become absolute, because npm cannot resolve a repo's
+// relative `docs/assets/...` image paths or `](LICENSE)` links the way GitHub can.
+//
+//   <img src="docs/assets/x.svg">  ->  raw.githubusercontent.com/<owner>/<repo>/main/docs/assets/x.svg
+//   ](LICENSE) / ](plugins/...)     ->  github.com/<owner>/<repo>/blob/main/...
+//
+// The text content is otherwise identical, so the two pages can never drift.
+//
+// --check : regenerate in memory, compare to the committed npm README, write
+//           nothing, exit non-zero on drift (the release/CI gate). Mirrors
+//           sync-project-index.js. Fork-safe: the owner/repo in the absolute URLs
+//           is normalized out of the compare, so a fork clone never false-REDs.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const pluginRoot = path.resolve(__dirname, "..");
+const repoRoot = path.resolve(pluginRoot, "..", "..");
+const sourceReadme = path.join(repoRoot, "README.md");
+// CW_README_PATH overrides the npm README that --check compares against (used by
+// the smoke to point --check at a throwaway drifted fixture). Default: the real one.
+const targetReadme = process.env.CW_README_PATH
+  ? path.resolve(process.env.CW_README_PATH)
+  : path.join(pluginRoot, "README.md");
+
+const repoUrl = normalizeGitRemote(git(["config", "--get", "remote.origin.url"]).trim())
+  || "https://github.com/coo1white/cool-workflow";
+const ownerRepo = repoUrl.replace(/^https:\/\/github\.com\//, "");
+const RAW_BASE = `https://raw.githubusercontent.com/${ownerRepo}/main`;
+const BLOB_BASE = `${repoUrl}/blob/main`;
+
+const MARKER =
+  "<!-- AUTO-GENERATED from /README.md by scripts/sync-readme.js — edit the root README, " +
+  "then run `npm run sync:readme`. DO NOT edit this file directly. -->";
+
+const CHECK = process.argv.includes("--check");
+
+function render() {
+  if (!fs.existsSync(sourceReadme)) {
+    process.stderr.write(`sync-readme FAILED: source ${path.relative(repoRoot, sourceReadme)} does not exist.\n`);
+    process.exit(1);
+  }
+  const source = fs.readFileSync(sourceReadme, "utf8");
+  // NOTE: a relative path must be free of a literal "(", ")", or '"' — the [^)]+ / [^"]+
+  // captures below stop at those. The repo README has none; readme:check catches any drift.
+  const absolutized = source
+    // HTML image sources: <img src="docs/assets/x.svg"> -> raw URL (skip already-absolute / anchors)
+    .replace(/\bsrc="(?!https?:|#|data:)([^"]+)"/g, (_m, rel) => `src="${RAW_BASE}/${rel}"`)
+    // Markdown links: ](LICENSE) / ](plugins/...) -> blob URL (skip absolute / in-page anchors / mailto)
+    .replace(/\]\((?!https?:|#|mailto:)([^)]+)\)/g, (_m, rel) => `](${BLOB_BASE}/${rel})`);
+  return `${MARKER}\n${absolutized}`;
+}
+
+function normalizeForCompare(text) {
+  // Strip the owner/repo from the generated absolute URLs so a fork (whose git
+  // remote differs) does not false-RED against the canonical committed README.
+  // The CONTENT is what this gate guards; the owner/repo is environment-derived.
+  return text
+    .replace(/\r\n/g, "\n")
+    .replace(/https:\/\/raw\.githubusercontent\.com\/[^/]+\/[^/]+\/main/g, "<RAW>")
+    .replace(/https:\/\/github\.com\/[^/]+\/[^/]+\/blob\/main/g, "<BLOB>");
+}
+
+function main() {
+  const rendered = render();
+  const rel = path.relative(repoRoot, targetReadme);
+
+  if (CHECK) {
+    if (!fs.existsSync(targetReadme)) {
+      process.stderr.write(`readme check FAILED: ${rel} does not exist.\nRun: (cd plugins/cool-workflow && npm run sync:readme)\n`);
+      process.exit(1);
+    }
+    const committed = normalizeForCompare(fs.readFileSync(targetReadme, "utf8"));
+    const fresh = normalizeForCompare(rendered);
+    if (committed === fresh) {
+      process.stdout.write(`${JSON.stringify({ ok: true, check: true, source: "README.md", doc: rel }, null, 2)}\n`);
+      return;
+    }
+    const a = committed.split("\n");
+    const b = fresh.split("\n");
+    let i = 0;
+    while (i < a.length && i < b.length && a[i] === b[i]) i++;
+    process.stderr.write(
+      `readme check FAILED: ${rel} is stale (does not match the GitHub README.md).\n` +
+      `First difference at line ${i + 1}:\n` +
+      `  committed: ${JSON.stringify(a[i] ?? "<missing>")}\n` +
+      `  expected:  ${JSON.stringify(b[i] ?? "<missing>")}\n` +
+      `Regenerate with: (cd plugins/cool-workflow && npm run sync:readme)\n`
+    );
+    process.exit(1);
+  }
+
+  fs.writeFileSync(targetReadme, rendered, "utf8");
+  process.stdout.write(`${JSON.stringify({
+    ok: true,
+    source: "README.md",
+    output: rel,
+    repoUrl
+  }, null, 2)}\n`);
+}
+
+function git(args) {
+  const result = spawnSync("git", args, { cwd: repoRoot, encoding: "utf8" });
+  return result.status === 0 ? result.stdout : "";
+}
+
+function normalizeGitRemote(remote) {
+  if (!remote) return "";
+  if (remote.endsWith(".git")) remote = remote.slice(0, -4);
+  const sshMatch = remote.match(/^git@github\.com:(.+)$/);
+  if (sshMatch) return `https://github.com/${sshMatch[1]}`;
+  return remote;
+}
+
+main();

package/scripts/version-sync-check.js

@@ -92,7 +92,11 @@ function main() {
   checkIncludes("plugins/cool-workflow/dist/mcp-server.js", "CURRENT_COOL_WORKFLOW_VERSION", checks);
   checkIncludes("plugins/cool-workflow/dist/workflow-app-framework.js", "CURRENT_COOL_WORKFLOW_VERSION", checks);
 
-  checkIncludes("plugins/cool-workflow/README.md", `v${VERSION}`, checks);
+  // The npm package README (plugins/cool-workflow/README.md) is GENERATED from the GitHub
+  // README.md (scripts/sync-readme.js) and conveys the version via the live npm/release shields
+  // badges — not a hand-maintained literal — exactly like the GitHub page. It is no longer
+  // version-pinned here; readme:check guards that the two pages stay identical, and the surfaces
+  // above (version.ts/dist/package.json/manifests/docs) still pin the release.
   checkIncludes("plugins/cool-workflow/docs/index.md", "release and migration", checks);
   checkIncludes("plugins/cool-workflow/docs/multi-agent-topologies.7.md", "Multi-Agent Topologies", checks);
   checkIncludes("plugins/cool-workflow/docs/multi-agent-cli-mcp-surface.7.md", VERSION, checks);