create-cmp-cli 0.18.0 → 0.20.0

package/template/qa/lib/inputs-hash.mjs

@@ -17,8 +17,19 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 
-// Directories / files INCLUDED in the verified surface (relative to project ROOT).
+// Directories / files included in the verified surface (relative to project ROOT).
 // Principle: every tracked file whose content can change the lane's verdict.
+//
+// THIS IS A DEFAULT, NOT A LAW (evidence-economics S8, 2026-09-03). It is the
+// surface of a Compose Multiplatform app, and it used to be hardcoded inside
+// this module — which is the SPINE, shared by every adopter. A repo whose code
+// lives in services/ or src/ that vendored this file had its verified surface
+// silently shrink to whatever happened to match: no error, no failed step, a
+// receipt that still validated and still looked identical, and a hash that had
+// quietly stopped covering the application. A gate that attests less while
+// looking the same is the worst failure this harness can have, so the surface
+// is now resolved per project (see resolveVerifiedSurface) and an empty one is
+// refused rather than hashed.
 export const VERIFIED_SURFACE = [
   "composeApp",
   "specs",
@@ -57,6 +68,7 @@ export const VERIFIED_SURFACE = [
 const EXCLUDED_PREFIXES = [
   "qa/.plan.json",
   "qa/.request.json",
+  "qa/.plan-history.jsonl",
   "qa/evidence",
   "qa-artifacts",
   "qa/comments.json",
@@ -146,9 +158,52 @@ function walkAllFiles(dir) {
   return out;
 }
 
+/** Where a project may declare its own verified surface (see resolveVerifiedSurface). */
+export const SURFACE_CONFIG_REL = "qa/verified-surface.json";
+
+/**
+ * The surface THIS project attests — its own declaration when it has one, the
+ * Compose Multiplatform default otherwise.
+ *
+ * Read from a file rather than passed as an argument on purpose: qa/verify.mjs
+ * (which writes inputs.hash) and qa/receipt-check.mjs (which recomputes it)
+ * must never disagree about what was hashed, and two call sites taking a
+ * parameter is two places to get it wrong. The file lives under qa/, so it is
+ * itself inside the surface — changing the definition invalidates receipts,
+ * which is correct: the tree's coverage changed.
+ *
+ * Shape: {"surface": ["services", "docs", "build-logic", ".github", "qa"]}.
+ * Malformed or empty content is REFUSED, never silently defaulted — a project
+ * that tried to declare a surface and failed must not fall back to a smaller
+ * one behind the operator's back.
+ *
+ * @param {string} root project root
+ * @returns {string[]} surface entries, relative to root
+ */
+export function resolveVerifiedSurface(root) {
+  const p = path.join(root, SURFACE_CONFIG_REL);
+  let raw;
+  try {
+    raw = fs.readFileSync(p, "utf8");
+  } catch {
+    return VERIFIED_SURFACE; // no declaration — the CMP default, unchanged
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`${SURFACE_CONFIG_REL} is not valid JSON (${err.message}) — refusing to hash a surface this project failed to declare.`);
+  }
+  const list = parsed && Array.isArray(parsed.surface) ? parsed.surface.filter((x) => typeof x === "string" && x.trim() !== "") : null;
+  if (!list || list.length === 0) {
+    throw new Error(`${SURFACE_CONFIG_REL} declares no surface — expected {"surface": ["dir", …]}. Refusing to hash nothing.`);
+  }
+  return list;
+}
+
 // Resolve the verified surface to a flat, sorted list of paths (relative to
 // root, POSIX-style `/` separators) that currently exist on disk.
-function resolveSurfaceFiles(root) {
+function resolveSurfaceFiles(root, VERIFIED_SURFACE) {
   const gitFiles = tryGitLsFiles(root);
 
   if (gitFiles) {
@@ -188,7 +243,20 @@ export function computeInputsHash(root) {
   // on iteration order, and ICU collation varies with the machine's locale
   // (e.g. a da_DK machine orders "aa" after "z"; en orders case-insensitively
   // where code units do not) — the same tree must hash identically everywhere.
-  const files = [...new Set(resolveSurfaceFiles(root))].sort();
+  const surface = resolveVerifiedSurface(root);
+  const files = [...new Set(resolveSurfaceFiles(root, surface))].sort();
+
+  // A surface that matches NOTHING is a misconfiguration, not a valid hash.
+  // Hashing zero files yields a stable, confident-looking digest that attests
+  // the empty set — the silent shrink this whole change exists to prevent, in
+  // its most extreme form. Refuse, and name what was looked for.
+  if (files.length === 0) {
+    throw new Error(
+      `the verified surface matched no files under ${root} — nothing would be attested. ` +
+        `Surface: ${surface.join(", ")}. ` +
+        `A project whose code lives elsewhere declares its own in ${SURFACE_CONFIG_REL}: {"surface": ["services", "qa", …]}.`,
+    );
+  }
 
   const overall = createHash("sha256");
   for (const relPath of files) {

package/template/qa/lib/lane-narrator.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// lane-narrator.mjs — the lane's pulse while a step is running.
+//
+//   node qa/lib/lane-narrator.mjs <projectRoot>
+//
+// WHY THIS IS A SEPARATE PROCESS, and not a setInterval in verify.mjs. The lane's
+// steps are SYNCHRONOUS: each one blocks on execSync/spawnSync while Gradle works.
+// A timer inside that process cannot fire — the event loop is not running — so the
+// lane could only ever print when a step FINISHED. Observed live: fourteen minutes
+// without a single byte while the release build ran, with no way to tell a grinding
+// step from a wedged one except checking the Gradle daemon's CPU by hand. A step
+// that can take minutes must emit a heartbeat, or the operator's only signal is
+// silence, and silence is exactly what a crash looks like.
+//
+// The marker verify.mjs already rewrites at each step start (.cmp-lane-in-progress,
+// JSON: step, index, total, stepStartedAt, expectedStepMs, expectedLaneMs) carries
+// everything a pulse needs, so this narrator INVENTS NOTHING — it reads what the
+// lane declared about itself and says it out loud on a timer the lane cannot run.
+//
+// It writes to STDERR and never to stdout: --json consumers parse stdout, and a
+// narrator that corrupted machine output would be worse than the silence it fixes.
+// It is spawned only for human runs, and killed with the step loop.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const ROOT = process.argv[2];
+const MARKER = path.join(ROOT ?? ".", "composeApp", "build", ".cmp-lane-in-progress");
+
+// A step under this is not a wait — saying anything about it is noise.
+const FIRST_AFTER_MS = 20_000;
+const EVERY_MS = 30_000;
+const POLL_MS = 1_000;
+
+/** "42s" / "4m12s" — short enough to sit inside one line without wrapping. */
+export function shortDuration(ms) {
+  if (!(ms > 0)) return "0s";
+  const s = Math.round(ms / 1000);
+  return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s`;
+}
+
+/**
+ * The line for one poll, or null when there is nothing worth saying yet.
+ * Pure, so the cadence and the wording are testable without a clock or a lane.
+ *
+ * @param {object|null} marker parsed marker content (null when absent/legacy)
+ * @param {number} elapsedMs how long the CURRENT step has been running
+ * @param {number|null} lastSaidAtMs elapsed value at the previous line, or null
+ * @returns {string|null}
+ */
+export function pulseLine(marker, elapsedMs, lastSaidAtMs) {
+  if (!marker || typeof marker.step !== "string") return null; // legacy marker: nothing to narrate
+  if (elapsedMs < FIRST_AFTER_MS) return null;
+  if (lastSaidAtMs !== null && elapsedMs - lastSaidAtMs < EVERY_MS) return null;
+  const where = marker.index && marker.total ? ` (${marker.index}/${marker.total})` : "";
+  // The expectation is quoted from the flight journal's last full run — measured,
+  // never estimated (walk-legibility L4). Absent until one such run exists.
+  const usually = marker.expectedStepMs > 0 ? `, usually ~${shortDuration(marker.expectedStepMs)}` : "";
+  // Past its usual time is the fact an operator actually wants: it is the
+  // difference between "grinding" and "possibly wedged", and it is derived, not
+  // guessed — so it is stated plainly rather than dressed up as a warning.
+  const over = marker.expectedStepMs > 0 && elapsedMs > marker.expectedStepMs * 1.5 ? " — longer than usual" : "";
+  return `⋯ ${marker.step}${where} — ${shortDuration(elapsedMs)} elapsed${usually}${over}`;
+}
+
+function readMarker() {
+  try {
+    return JSON.parse(fs.readFileSync(MARKER, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+if (ROOT) {
+  let currentStep = null;
+  let lastSaidAtMs = null;
+  const timer = setInterval(() => {
+    const m = readMarker();
+    if (!m) return; // between steps, or the lane has finished and cleared it
+    if (m.step !== currentStep) {
+      currentStep = m.step;
+      lastSaidAtMs = null; // each step narrates on its own clock
+    }
+    const started = Date.parse(m.stepStartedAt ?? "");
+    if (Number.isNaN(started)) return;
+    const elapsed = Date.now() - started;
+    const line = pulseLine(m, elapsed, lastSaidAtMs);
+    if (line) {
+      lastSaidAtMs = elapsed;
+      process.stderr.write(`${line}\n`);
+    }
+  }, POLL_MS);
+  timer.unref?.();
+  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(sig, () => process.exit(0));
+  // Hold the process open against the unref'd timer: the parent kills us.
+  setInterval(() => {}, 1 << 30);
+}

package/template/qa/lib/lane-runner.mjs

@@ -0,0 +1,173 @@
+// lane-runner.mjs — the lane's step loop, as a function (evidence-economics S8a).
+//
+// The SPINE, separated from the STEPS. Everything a lane does around its steps —
+// stamp the in-flight marker with the step's own narration, set the step's
+// deadline from its measured history, keep a pulse alive while a synchronous
+// step blocks, turn a throw or a timeout into one ERROR row and keep going,
+// print the mark, derive the verdict — is the same for a Compose app and for
+// a Kotlin backend. Only the steps differ. payment-blueprint re-implemented
+// all of this by hand (2,769 lines) because it lived inside verify.mjs next
+// to Gradle calls it could not use; this file is what it should have been
+// able to import.
+//
+// PURE OF PROJECT KNOWLEDGE. No ROOT, no Gradle, no composeApp path: every
+// project-specific fact arrives through `ctx`. The runner never reads argv.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+
+import { stepDeadlineMs, stepErrorResult } from "./step-outcomes.mjs";
+
+/**
+ * Per-step expected durations from the journal's LAST FULL run — the source
+ * of the marker's "usually ~Ns" and of each step's deadline. Measured, never
+ * estimated; empty until one new-format full run exists.
+ * @param {object[]} entries parsed flight-journal entries, oldest first
+ * @returns {{byName: Map<string, number>, laneMs: (number|null)}}
+ */
+export function expectedDurations(entries) {
+  const list = Array.isArray(entries) ? entries : [];
+  for (let i = list.length - 1; i >= 0; i--) {
+    const e = list[i];
+    if (!e || e.mode === "fast" || !Array.isArray(e.steps)) continue;
+    const byName = new Map();
+    for (const s of e.steps) {
+      if (s && typeof s.name === "string" && typeof s.durationMs === "number" && s.durationMs > 0) byName.set(s.name, s.durationMs);
+    }
+    return { byName, laneMs: typeof e.durationMs === "number" && e.durationMs > 0 ? e.durationMs : null };
+  }
+  return { byName: new Map(), laneMs: null };
+}
+
+/**
+ * "stepUnitTests" → "unitTests", "stepSpecCoverageMemo" → "specCoverage" — the
+ * name the result will carry. An anonymous step narrates as null rather than
+ * guessing. Exported so a step pack can name its steps the same way.
+ * @param {Function} fn
+ * @returns {string|null}
+ */
+export function stepDisplayName(fn) {
+  const raw = typeof fn?.name === "string" ? fn.name.replace(/^step/, "").replace(/Memo$/, "") : "";
+  return raw === "" ? null : raw.charAt(0).toLowerCase() + raw.slice(1);
+}
+
+/** The lane's verdict over its rows: FAIL on any FAIL or ERROR, else PASS. CACHED counts as PASS (it IS a prior PASS). */
+export function laneVerdict(steps) {
+  return steps.some((s) => s && (s.verdict === "FAIL" || s.verdict === "ERROR")) ? "FAIL" : "PASS";
+}
+
+/** The mark a row wears on the console: ✓ PASS · ⚡ CACHED · → SKIP · ⊘ ERROR (could not run) · ✗ FAIL. */
+export function verdictMark(verdict) {
+  return verdict === "PASS" ? "✓" : verdict === "CACHED" ? "⚡" : verdict === "SKIP" ? "→" : verdict === "ERROR" ? "⊘" : "✗";
+}
+
+/**
+ * Run the steps, in order, under the lane's own discipline.
+ *
+ * @param {object} ctx
+ * @param {Function[]} ctx.steps the step functions, each returning a result row
+ * @param {string} ctx.markerPath the in-flight marker (.cmp-lane-in-progress) — stamped
+ *   before every step with {pid, at, step, index, total, stepStartedAt, expectedStepMs,
+ *   expectedLaneMs}, removed when the loop ends however it ends
+ * @param {{byName: Map<string, number>, laneMs: (number|null)}} [ctx.expected] from expectedDurations
+ * @param {(ms: number) => void} [ctx.setDeadline] receives each step's deadline before it
+ *   runs — the project's subprocess helper reads it (verify.mjs's sh())
+ * @param {(line: string) => void|null} [ctx.print] one line per finished step; null = silent
+ *   (--json). Also gates the narrator: no print, no pulse.
+ * @param {{entry: string, root: string}|null} [ctx.narrator] the pulse process to spawn
+ *   beside the loop (lane-narrator.mjs) — a separate process because the steps are
+ *   synchronous and no timer in this process can fire while one runs
+ * @param {(result: object) => boolean} [ctx.stopAfter] short-circuit predicate; default:
+ *   stop after a FAILed "build" — nothing downstream is meaningful
+ * @param {() => void} [ctx.onFinally] runs in the finally (the project releases its device lease here)
+ * @param {number} [ctx.startedAt] the lane's start, for the marker's `at`
+ * @returns {{steps: object[], verdict: "PASS"|"FAIL", durationMs: number}}
+ */
+export function runLane(ctx) {
+  const {
+    steps: stepFns,
+    markerPath,
+    expected = { byName: new Map(), laneMs: null },
+    setDeadline = () => {},
+    print = null,
+    narrator = null,
+    stopAfter = (r) => r.name === "build" && r.verdict === "FAIL",
+    onFinally = () => {},
+    startedAt = Date.now(),
+  } = ctx;
+
+  const stamp = (stepFn, index, total) => {
+    try {
+      const name = stepFn ? stepDisplayName(stepFn) : null;
+      const narration = {
+        pid: process.pid,
+        at: new Date(startedAt).toISOString(),
+        step: name,
+        index,
+        total,
+        stepStartedAt: new Date().toISOString(),
+        expectedStepMs: name !== null ? (expected.byName.get(name) ?? null) : null,
+        expectedLaneMs: expected.laneMs,
+      };
+      fs.writeFileSync(markerPath, `${JSON.stringify(narration)}\n`);
+    } catch {
+      /* the narration must never break the lane it narrates */
+    }
+  };
+
+  fs.mkdirSync(path.dirname(markerPath), { recursive: true });
+  stamp(null, 0, stepFns.length);
+
+  let pulse = null;
+  if (print && narrator) {
+    try {
+      pulse = spawn(process.execPath, [narrator.entry, narrator.root], { stdio: ["ignore", "ignore", "inherit"] });
+      pulse.on("error", () => {});
+    } catch {
+      /* a missing pulse is a quieter lane, never a failed one */
+    }
+  }
+
+  const results = [];
+  try {
+    for (const [i, step] of stepFns.entries()) {
+      stamp(step, i + 1, stepFns.length);
+      const name = stepDisplayName(step) ?? `step${i + 1}`;
+      // S4: every step under a deadline from its own history (×3, floor 5 min,
+      // ceiling 30). A deadline or a throw is ONE ERROR row — the lane keeps
+      // going, because the other verdicts are still worth having.
+      setDeadline(stepDeadlineMs(expected.byName.get(name)));
+      const stepStarted = Date.now();
+      let result;
+      try {
+        result = step();
+      } catch (err) {
+        result = stepErrorResult(name, err, Date.now() - stepStarted);
+      }
+      results.push(result);
+      if (print) {
+        print(
+          `${verdictMark(result.verdict)} ${result.name}: ${result.verdict}${result.note ? ` (${result.note})` : ""}${result.reason ? ` — ${String(result.reason).split("\n")[0]}` : ""}`,
+        );
+      }
+      if (stopAfter(result)) break;
+    }
+  } finally {
+    if (pulse) {
+      try {
+        pulse.kill();
+      } catch {
+        /* the narrator holds nothing; a failed kill must not fail the lane */
+      }
+    }
+    fs.rmSync(markerPath, { force: true });
+    try {
+      onFinally();
+    } catch {
+      /* a finalizer that throws must not hide the rows already earned */
+    }
+  }
+
+  return { steps: results, verdict: laneVerdict(results), durationMs: Date.now() - startedAt };
+}