cool-workflow 0.1.79 → 0.1.81

package/scripts/architecture-review-fast.js

@@ -0,0 +1,362 @@
+#!/usr/bin/env node
+"use strict";
+
+// architecture-review-fast — userland accelerator wrapper.
+//
+// Mechanism only: prepare one cached JSONL source context, pass its digest into
+// the opt-in fast app, then optionally create a background schedule for the full
+// architecture-review app. The model still runs only through CW's external agent
+// backend; this script imports no model SDK and holds no key.
+
+const crypto = require("node:crypto");
+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 node = process.execPath;
+const cw = path.join(pluginRoot, "scripts", "cw.js");
+const sourceContext = path.join(pluginRoot, "scripts", "source-context.js");
+
+function main() {
+  const started = nowNs();
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) return usage(0);
+
+  const repo = path.resolve(required(args.repo, "repo"));
+  const question = required(args.question, "question");
+  const requestedProfile = stringArg(args.profile);
+  const ref = stringArg(args.ref) || "HEAD";
+  const requestedProfileFile = stringArg(args.profileFile || args["profile-file"]);
+  const defaultExternalProfile = !requestedProfile && !requestedProfileFile && repo !== repoRoot;
+  const profile = defaultExternalProfile ? "repo" : requestedProfile || "core";
+  const cacheDir = path.resolve(stringArg(args.cacheDir || args["cache-dir"]) || path.join(repo, ".cw", "cache", "source-context"));
+  const contextOut = path.resolve(stringArg(args.contextOut || args["context-out"]) || path.join(repo, ".cw", "context", `${profile}-source.jsonl`));
+  const profileFile = defaultExternalProfile ? writeDefaultRepoProfile(repo, contextOut) : requestedProfileFile;
+  const includeMetrics = truthy(args.metrics);
+  const fastModel = stringArg(args.fastModel || args["fast-model"]);
+  const strongModel = stringArg(args.strongModel || args["strong-model"]);
+  const modelEnv = modelPolicyEnv(fastModel, strongModel);
+
+  const contextExport = timed(() => exportSourceContext({
+    repo,
+    profile,
+    ref,
+    profileFile,
+    cacheDir
+  }));
+  const contextText = contextExport.value;
+  assertNonEmptySourceContext(contextText, profile, repo);
+  fs.mkdirSync(path.dirname(contextOut), { recursive: true });
+  fs.writeFileSync(contextOut, contextText, "utf8");
+  const digest = `sha256:${crypto.createHash("sha256").update(contextText, "utf8").digest("hex")}`;
+
+  const reviewArgs = [
+    "quickstart",
+    "architecture-review-fast",
+    "--repo",
+    repo,
+    "--question",
+    question,
+    "--sourceContext",
+    contextOut,
+    "--sourceContextDigest",
+    digest
+  ];
+  appendRepeated(reviewArgs, "--invariant", args.invariant);
+  appendOption(reviewArgs, "--focus", args.focus);
+  appendPassThrough(reviewArgs, args, [
+    "agent-command",
+    "agentCommand",
+    "agent-endpoint",
+    "agentEndpoint",
+    "agent-model",
+    "agentModel",
+    "agent-timeout-ms",
+    "agentTimeoutMs",
+    "once",
+    "preview",
+    "now"
+  ]);
+
+  const fastReviewRun = timed(() => runCwJson(reviewArgs, repo, modelEnv));
+  const fastReview = fastReviewRun.value;
+  const sourceContextMeta = {
+    path: contextOut,
+    digest,
+    profile,
+    ref,
+    cacheDir
+  };
+  const fullReviewScheduleRun = truthy(args.scheduleFull || args["schedule-full"])
+    ? timed(() => scheduleFullReview(repo, question, args, fastReview, sourceContextMeta))
+    : undefined;
+  const fullReviewSchedule = fullReviewScheduleRun?.value;
+
+  writeJson({
+    schemaVersion: 1,
+    appId: "architecture-review-fast",
+    sourceContext: sourceContextMeta,
+    fastReview,
+    ...(fastModel || strongModel ? { modelPolicy: { ...(fastModel ? { fastModel } : {}), ...(strongModel ? { strongModel } : {}) } } : {}),
+    ...(fullReviewSchedule ? { fullReviewSchedule } : {}),
+    ...(includeMetrics ? { metrics: buildMetrics(started, contextText, contextExport.elapsedMs, fastReview, fastReviewRun.elapsedMs, fullReviewScheduleRun?.elapsedMs) } : {})
+  });
+}
+
+function exportSourceContext(options) {
+  const argv = [
+    sourceContext,
+    "export",
+    "--profile",
+    options.profile,
+    "--ref",
+    options.ref,
+    "--repo-root",
+    options.repo,
+    "--cache-dir",
+    options.cacheDir
+  ];
+  if (options.profileFile) argv.push("--profile-file", path.resolve(options.profileFile));
+  const result = spawnSync(node, argv, {
+    cwd: repoRoot,
+    encoding: "utf8",
+    maxBuffer: 1024 * 1024 * 128
+  });
+  if (result.status !== 0) die(result.stderr || result.stdout || "source context export failed");
+  return result.stdout;
+}
+
+function writeDefaultRepoProfile(repo, contextOut) {
+  const file = path.join(path.dirname(contextOut), "repo-source-profile.json");
+  const profile = {
+    schemaVersion: 1,
+    profiles: {
+      repo: {
+        description: "Default external repository profile for architecture-review-fast.",
+        maxLines: 50000,
+        include: [
+          "README.md",
+          "README.*",
+          "package.json",
+          "tsconfig.json",
+          "pyproject.toml",
+          "Cargo.toml",
+          "go.mod",
+          ".github/**",
+          "src/**",
+          "lib/**",
+          "app/**",
+          "apps/**",
+          "bin/**",
+          "scripts/**",
+          "docs/**",
+          "test/**",
+          "tests/**"
+        ],
+        exclude: [
+          ".cw/**",
+          "dist/**",
+          "build/**",
+          "coverage/**",
+          "node_modules/**",
+          "vendor/**",
+          "target/**",
+          "docs/assets/**",
+          "assets/**",
+          "public/**"
+        ]
+      }
+    }
+  };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(profile, null, 2)}\n`, "utf8");
+  return file;
+}
+
+function assertNonEmptySourceContext(text, profile, repo) {
+  const records = text.trim() ? text.trim().split(/\n/).filter(Boolean).length : 0;
+  if (records > 0) return;
+  die([
+    `source context profile "${profile}" exported zero records for ${repo}`,
+    "pass --profile-file with include rules for this repository, or choose a profile that matches tracked text files"
+  ].join("; "));
+}
+
+function scheduleFullReview(repo, question, args, fastReview, sourceContextMeta) {
+  const delayMinutes = stringArg(args.fullDelayMinutes || args["full-delay-minutes"]) || "1";
+  const prompt = [
+    `Run full architecture-review for ${repo}.`,
+    `Question: ${question}`,
+    args.focus ? `Focus: ${args.focus}` : "",
+    `Fast review run: ${fastReview?.runId || "unknown"}.`,
+    fastReview?.reportPath ? `Fast review report: ${fastReview.reportPath}.` : "",
+    `Fast review status: ${fastReview?.status || "unknown"} (${fastReview?.completedWorkers || 0}/${fastReview?.plannedWorkers || 0} workers completed).`,
+    `Source context: ${sourceContextMeta.path} (${sourceContextMeta.digest}, profile ${sourceContextMeta.profile}, ref ${sourceContextMeta.ref}).`,
+    "Use the completed architecture-review-fast report as the foreground triage result; write the full review report path and digest when the background review finishes."
+  ].filter(Boolean).join(" ");
+  return runCwJson([
+    "schedule",
+    "create",
+    "--cwd",
+    repo,
+    "--kind",
+    "reminder",
+    "--delayMinutes",
+    delayMinutes,
+    "--maxRuns",
+    "1",
+    "--workflowId",
+    "architecture-review",
+    "--prompt",
+    prompt
+  ], repo);
+}
+
+function runCwJson(args, cwd, extraEnv = {}) {
+  const result = spawnSync(node, [cw, ...args], {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, ...extraEnv },
+    maxBuffer: 1024 * 1024 * 64
+  });
+  if (result.status !== 0) die(result.stderr || result.stdout || `cw ${args.join(" ")} failed`);
+  try {
+    return JSON.parse(result.stdout);
+  } catch (error) {
+    die(`cw returned non-JSON output: ${error.message}`);
+  }
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) {
+      (args._ ||= []).push(token);
+      continue;
+    }
+    const raw = token.slice(2);
+    const eq = raw.indexOf("=");
+    const key = eq >= 0 ? raw.slice(0, eq) : raw;
+    const value = eq >= 0 ? raw.slice(eq + 1) : argv[index + 1] && !argv[index + 1].startsWith("--") ? argv[++index] : true;
+    if (args[key] === undefined) args[key] = value;
+    else if (Array.isArray(args[key])) args[key].push(value);
+    else args[key] = [args[key], value];
+  }
+  return args;
+}
+
+function appendPassThrough(argv, args, keys) {
+  for (const key of keys) {
+    if (args[key] === undefined) continue;
+    const flag = key.includes("-") ? `--${key}` : `--${key}`;
+    if (args[key] === true) argv.push(flag);
+    else appendRepeated(argv, flag, args[key]);
+  }
+}
+
+function appendRepeated(argv, flag, value) {
+  if (value === undefined || value === false) return;
+  const values = Array.isArray(value) ? value : [value];
+  for (const entry of values) argv.push(flag, String(entry));
+}
+
+function appendOption(argv, flag, value) {
+  if (value === undefined || value === false || value === true || value === "") return;
+  argv.push(flag, String(value));
+}
+
+function required(value, name) {
+  const text = stringArg(value);
+  if (!text) die(`missing required --${name}`);
+  return text;
+}
+
+function stringArg(value) {
+  if (value === undefined || value === null || value === true || value === false) return "";
+  return Array.isArray(value) ? String(value[value.length - 1] || "") : String(value);
+}
+
+function truthy(value) {
+  return value === true || value === "true" || value === "1" || value === "yes";
+}
+
+function modelPolicyEnv(fastModel, strongModel) {
+  return {
+    ...(fastModel ? { CW_ARCHITECTURE_REVIEW_FAST_MODEL: fastModel } : {}),
+    ...(strongModel ? { CW_ARCHITECTURE_REVIEW_STRONG_MODEL: strongModel } : {})
+  };
+}
+
+function nowNs() {
+  return process.hrtime.bigint();
+}
+
+function elapsedMs(started) {
+  return Number((process.hrtime.bigint() - started) / 1000000n);
+}
+
+function timed(fn) {
+  const started = nowNs();
+  const value = fn();
+  return { value, elapsedMs: elapsedMs(started) };
+}
+
+function buildMetrics(started, contextText, sourceContextElapsedMs, fastReview, fastReviewElapsedMs, fullReviewScheduleElapsedMs) {
+  const steps = Array.isArray(fastReview?.steps) ? fastReview.steps : [];
+  const handleKinds = countBy(steps.map((step) => step && step.handleKind).filter(Boolean));
+  const actions = countBy(steps.map((step) => step && step.action).filter(Boolean));
+  return {
+    totalElapsedMs: elapsedMs(started),
+    sourceContext: {
+      elapsedMs: sourceContextElapsedMs,
+      bytes: Buffer.byteLength(contextText, "utf8")
+    },
+    fastReview: {
+      elapsedMs: fastReviewElapsedMs,
+      status: fastReview?.status,
+      plannedWorkers: fastReview?.plannedWorkers,
+      completedWorkers: fastReview?.completedWorkers,
+      steps: steps.length,
+      actions,
+      handleKinds,
+      resultCacheHits: Number(handleKinds["result-cache"] || 0),
+      agentSpawns: steps.filter((step) => step && step.backendId === "agent" && step.handleKind && step.handleKind !== "result-cache").length
+    },
+    ...(fullReviewScheduleElapsedMs === undefined ? {} : { fullReviewSchedule: { elapsedMs: fullReviewScheduleElapsedMs } })
+  };
+}
+
+function countBy(values) {
+  const counts = {};
+  for (const value of values) counts[String(value)] = (counts[String(value)] || 0) + 1;
+  return counts;
+}
+
+function writeJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function usage(code) {
+  process.stderr.write([
+    "usage:",
+    "  node scripts/architecture-review-fast.js --repo PATH --question TEXT [--agent-command CMD]",
+    "",
+    "options:",
+    "  --profile core --ref HEAD --profile-file PATH --cache-dir DIR --context-out PATH",
+    "  --fast-model MODEL --strong-model MODEL",
+    "  --invariant TEXT --focus TEXT --preview --once",
+    "  --schedule-full [--full-delay-minutes N]",
+    "  --metrics"
+  ].join("\n") + "\n");
+  process.exitCode = code;
+}
+
+function die(message) {
+  process.stderr.write(`architecture-review-fast: ${String(message).trim()}\n`);
+  process.exit(1);
+}
+
+main();

package/scripts/bump-version.js

@@ -22,6 +22,7 @@
 const { spawnSync } = require("node:child_process");
 const fs = require("node:fs");
 const path = require("node:path");
+const { CANONICAL_APP_IDS } = require("./canonical-apps-list.js");
 
 const pluginRoot = path.resolve(__dirname, "..");
 const repoRoot = path.resolve(pluginRoot, "..", "..");
@@ -89,16 +90,10 @@ function main() {
 
   // 5. canonical apps app.json (top-level version only; never minVersion).
   //    ONLY the canonical apps track the runtime version — workflow-app-framework-demo
-  //    is pinned (e.g. 0.1.0) and must NOT be bumped. This list mirrors the one
-  //    version-sync-check.js asserts.
-  const CANONICAL_APPS = [
-    "architecture-review",
-    "end-to-end-golden-path",
-    "pr-review-fix-ci",
-    "release-cut",
-    "research-synthesis"
-  ];
-  for (const appId of CANONICAL_APPS) {
+  //    is pinned (e.g. 0.1.0) and must NOT be bumped. The list is DERIVED from
+  //    apps/ (excluding metadata.example demos) by scripts/canonical-apps-list.js,
+  //    the single source version-sync-check.js asserts against — no hand-copy.
+  for (const appId of CANONICAL_APP_IDS) {
     const appJson = path.join(pluginRoot, "apps", appId, "app.json");
     if (fs.existsSync(appJson) && replaceFirstVersionField(appJson, next)) {
       note(`apps/${appId}/app.json`);

package/scripts/canonical-apps-list.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+"use strict";
+
+// Single source of truth for the CANONICAL app id list.
+//
+// Audit finding M5: this list was hand-copied into three scripts
+// (bump-version.js, version-sync-check.js, canonical-apps.js) with no gate
+// enforcing agreement, so drift between the copies was silent. This module
+// DERIVES the list from the `apps/` directory on disk so the three callers can
+// never disagree — there is nothing left to copy.
+//
+// What counts as canonical: every app directory under `apps/` whose `app.json`
+// is NOT a demo. The real demo marker is `metadata.example === true` (that, NOT
+// `versionPinned`, is how the only non-canonical app — workflow-app-framework-demo,
+// pinned at 0.1.0 — is flagged). Example apps are excluded because they are
+// version-pinned and must not be bumped or version-asserted with the runtime.
+//
+// Portability: node fs/path only, no external tools (CI portability rule).
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const pluginRoot = path.resolve(__dirname, "..");
+const appsDir = path.join(pluginRoot, "apps");
+
+// The end-to-end golden path is canonical (and version-tracked) but is exercised
+// by its own dedicated harness (scripts/golden-path.js), not by the per-app CLI
+// smoke in canonical-apps.js. Expose its id so that script can express
+// "canonical minus golden-path" without re-introducing a hand-copied list.
+const GOLDEN_PATH_APP_ID = "end-to-end-golden-path";
+
+function isExampleApp(appJsonPath) {
+  // An app is excluded from the canonical list iff its app.json declares
+  // metadata.example === true. Any read/parse failure is treated as
+  // "not an example" so a malformed app surfaces in the canonical list (and
+  // therefore in the version gate) rather than being silently dropped.
+  try {
+    const json = JSON.parse(fs.readFileSync(appJsonPath, "utf8"));
+    return json && json.metadata && json.metadata.example === true;
+  } catch {
+    return false;
+  }
+}
+
+function listCanonicalAppIds() {
+  return fs
+    .readdirSync(appsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((id) => {
+      const appJson = path.join(appsDir, id, "app.json");
+      if (!fs.existsSync(appJson)) return false; // not an app directory
+      return !isExampleApp(appJson);
+    })
+    .sort(); // deterministic order (replay determinism)
+}
+
+const CANONICAL_APP_IDS = listCanonicalAppIds();
+
+module.exports = {
+  CANONICAL_APP_IDS,
+  listCanonicalAppIds,
+  GOLDEN_PATH_APP_ID
+};

package/scripts/canonical-apps.js

@@ -6,6 +6,7 @@ const { execFileSync } = require("node:child_process");
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
+const { CANONICAL_APP_IDS, GOLDEN_PATH_APP_ID } = require("./canonical-apps-list.js");
 
 const pluginRoot = path.resolve(__dirname, "..");
 const cli = path.join(pluginRoot, "scripts/cw.js");
@@ -25,6 +26,23 @@ const canonicalApps = [
       "Workflow App framework"
     ]
   },
+  {
+    id: "architecture-review-fast",
+    args: (workspace) => [
+      "--repo",
+      workspace,
+      "--question",
+      "Can a user get a fast architecture answer?",
+      "--invariant",
+      "Full architecture-review remains available",
+      "--focus",
+      "Runtime speed",
+      "--sourceContext",
+      "",
+      "--sourceContextDigest",
+      ""
+    ]
+  },
   {
     id: "pr-review-fix-ci",
     args: (workspace) => [
@@ -65,7 +83,7 @@ const canonicalApps = [
       "--source",
       "plugins/cool-workflow/docs/workflow-app-framework.7.md",
       "--scope",
-      "Cool Workflow v0.1.79",
+      "Cool Workflow v0.1.81",
       "--freshness",
       "as of release preparation"
     ]
@@ -73,6 +91,20 @@ const canonicalApps = [
 ];
 
 function main() {
+  // Fail-closed drift gate (audit M5): the per-app CLI smoke below must cover
+  // exactly the DERIVED canonical set (apps/ minus metadata.example demos) less
+  // the golden-path app, which scripts/golden-path.js owns. If a new canonical
+  // app appears (or the demo marker flips) without smoke args here, this fails
+  // instead of silently skipping it — there is no second hand-copied list.
+  const expectedSmokeIds = CANONICAL_APP_IDS.filter((id) => id !== GOLDEN_PATH_APP_ID).sort();
+  const actualSmokeIds = canonicalApps.map((app) => app.id).sort();
+  assert.deepEqual(
+    actualSmokeIds,
+    expectedSmokeIds,
+    `canonical-apps smoke set drifted from derived canonical list (apps/ minus example demos, minus ${GOLDEN_PATH_APP_ID}): ` +
+      `expected ${JSON.stringify(expectedSmokeIds)}, got ${JSON.stringify(actualSmokeIds)}`
+  );
+
   const appList = runJson(["app", "list"]);
   const workflowList = runJson(["list"]);
   assertUniqueIds(appList, "app list");
@@ -85,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.79");
+    assert.equal(summary.version, "0.1.81");
 
     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.79");
+    assert.equal(shown.app.version, "0.1.81");
     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);
@@ -103,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.79");
+    assert.equal(state.workflow.app.version, "0.1.81");
     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`);