create-cmp-cli 0.13.0 → 0.14.1

package/template/qa/lib/harness-region.mjs

@@ -0,0 +1,159 @@
+// The harness region — which files in a stamped app are MACHINE-OWNED.
+//
+// A create-cmp app carries two kinds of file. App-owned files are the app: its
+// screens, specs, goldens, approvals, e2e flows. Machine-owned files are the
+// verify lane itself — executable harness code that is identical in every app
+// ever stamped, carrying no app content whatsoever.
+//
+// Treating the second kind like the first is what made upgrades expensive: a
+// three-way merge over 10k lines of engine code produced ~1,000 conflicted
+// lines per app with ZERO app-specific tokens in them. The right operation for
+// a derived artifact is replace, not merge. This module draws that line.
+//
+// The rule is deliberately mechanical, with no per-file list to keep in sync:
+//
+//     machine-owned  ==  the .mjs files directly under qa/ and qa/lib/
+//
+// Everything else under qa/ is app state (approvals.json, comments.json,
+// evidence/, golden/) or app content (e2e/*.yaml — seeded once at stamp time,
+// app-owned forever after, because apps edit their smoke flow as tabs change).
+//
+// Three consequences, each load-bearing:
+//
+//   1. NEVER STAMPED. The region is copied byte-identical from the engine —
+//      token replacement must not touch it. It used to: qa/lib/approvals.mjs
+//      carries a comment warning that a literal "__PACKAGE__" in lane source
+//      gets silently rewritten at stamp time, and qa/scaffold-feature.mjs
+//      shipped an error message that meant to name the unresolved token and
+//      instead named the app's real package. Anything app-specific the lane
+//      needs is read at RUNTIME from create-cmp.json.
+//
+//   2. VERIFIABLE. Because the copy is byte-identical to a known version, an
+//      app can prove offline that its lane is the real one. Without this a
+//      receipt is unfalsifiable: edit qa/verify.mjs to force every step green
+//      and the receipt still validates, since the edited file is simply part
+//      of the hashed surface.
+//
+//   3. REPLACEABLE. `create-cmp upgrade --harness` overwrites the region
+//      wholesale instead of merging it.
+//
+// SINGLE SOURCE OF TRUTH: packages/harness/src/lib/harness-region.mjs in the
+// create-cmp repo. The copy in a generated project's qa/lib/ is vendored
+// byte-identical at scaffold time — edit the package source, then run
+// `node scripts/sync-harness.mjs`.
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Directories whose direct `.mjs` children are machine-owned, relative to the
+ * project root. Direct children only — a nested directory added later is not
+ * silently swept into the region without someone editing this list.
+ */
+export const HARNESS_DIRS = ["qa", "qa/lib"];
+
+/**
+ * Is this project-relative path part of the machine-owned harness region?
+ * @param {string} relPath project-relative path, "/"-separated
+ * @returns {boolean}
+ */
+export function isHarnessFile(relPath) {
+  if (typeof relPath !== "string" || !relPath.endsWith(".mjs")) return false;
+  const dir = relPath.includes("/") ? relPath.slice(0, relPath.lastIndexOf("/")) : "";
+  return HARNESS_DIRS.includes(dir);
+}
+
+/**
+ * Every machine-owned file present under `root`, as project-relative posix
+ * paths, sorted — so the list (and any hash over it) is deterministic.
+ * @param {string} root project root
+ * @returns {string[]}
+ */
+export function listHarnessFiles(root) {
+  const found = [];
+  for (const dir of HARNESS_DIRS) {
+    let names;
+    try {
+      names = fs.readdirSync(path.join(root, dir), { withFileTypes: true });
+    } catch {
+      continue; // a project without qa/lib yet is not an error here
+    }
+    for (const ent of names) {
+      if (!ent.isFile()) continue;
+      const rel = `${dir}/${ent.name}`;
+      if (isHarnessFile(rel)) found.push(rel);
+    }
+  }
+  return found.sort();
+}
+
+/** sha256 of one file's bytes, hex. */
+function fileHash(abs) {
+  return createHash("sha256").update(fs.readFileSync(abs)).digest("hex");
+}
+
+/**
+ * Content hash of the whole region, plus the per-file hashes it was built from.
+ *
+ * The digest covers PATHS as well as content, so moving a file between the two
+ * harness directories changes the hash even if no byte of any file changed.
+ * NUL separators keep the encoding unambiguous — no filename can forge a
+ * boundary.
+ *
+ * @param {string} root project root
+ * @returns {{sha256: string, fileCount: number, files: Record<string,string>}}
+ */
+export function hashHarnessRegion(root) {
+  const rels = listHarnessFiles(root);
+  const files = {};
+  const digest = createHash("sha256");
+  for (const rel of rels) {
+    const h = fileHash(path.join(root, rel));
+    files[rel] = h;
+    digest.update(rel, "utf8").update("\0").update(h, "utf8").update("\n");
+  }
+  return { sha256: digest.digest("hex"), fileCount: rels.length, files };
+}
+
+/**
+ * Compare a tree's region against a recorded manifest of per-file hashes.
+ * Reports WHICH files differ, not just that something did — an app that
+ * patched its lane needs to see the list, and an upgrade needs it to decide
+ * what to preserve.
+ *
+ * @param {string} root project root
+ * @param {{sha256?: string, files?: Record<string,string>}} recorded
+ * @returns {{intact: boolean, sha256: string, modified: string[],
+ *            missing: string[], extra: string[]}}
+ *   modified  present in both, different content
+ *   missing   recorded but absent from the tree
+ *   extra     present in the tree but not recorded
+ */
+export function compareHarnessRegion(root, recorded) {
+  const actual = hashHarnessRegion(root);
+  // `typeof null === "object"`, and an array would enumerate as index keys —
+  // a manifest that is absent or malformed must read as NOT intact, never crash
+  // the lane step that calls this.
+  const f = recorded?.files;
+  const expected = f && typeof f === "object" && !Array.isArray(f) ? f : {};
+  const modified = [];
+  const missing = [];
+  const extra = [];
+
+  for (const [rel, hash] of Object.entries(expected)) {
+    if (!(rel in actual.files)) missing.push(rel);
+    else if (actual.files[rel] !== hash) modified.push(rel);
+  }
+  for (const rel of Object.keys(actual.files)) {
+    if (!(rel in expected)) extra.push(rel);
+  }
+
+  return {
+    intact: modified.length === 0 && missing.length === 0 && extra.length === 0,
+    sha256: actual.sha256,
+    modified: modified.sort(),
+    missing: missing.sort(),
+    extra: extra.sort(),
+  };
+}

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

@@ -8,7 +8,7 @@
 // create-cmp repo (the `cmp-receipts` package). The copy in a generated
 // project's qa/lib/ is vendored byte-identical at scaffold time and pinned by
 // test/receipts-parity.test.mjs — edit the package source, then run
-// `node scripts/sync-receipts.mjs`.
+// `node scripts/sync-harness.mjs`.
 //
 // See docs/adr/0005-evidence-binding-by-inputs-hash.md for the why.
 

package/template/qa/lib/receipt-validate.mjs

@@ -9,7 +9,7 @@
 // create-cmp repo (the `cmp-receipts` package). The copy in a generated
 // project's qa/lib/ is vendored byte-identical at scaffold time and pinned by
 // test/receipts-parity.test.mjs — edit the package source, then run
-// `node scripts/sync-receipts.mjs`.
+// `node scripts/sync-harness.mjs`.
 //
 // See docs/adr/0005-evidence-binding-by-inputs-hash.md for the why.
 

package/template/qa/preview-gallery.mjs

@@ -23,6 +23,21 @@ const previewsDir = resolve(
 const { renderTreeSvg } = await import(new URL("./lib/render.mjs", import.meta.url));
 const { auditA11y } = await import(new URL("./lib/a11y.mjs", import.meta.url));
 
+// The app's display name is read at RUNTIME from create-cmp.json, never stamped in.
+// Every .mjs under qa/ is machine-owned harness code copied byte-identical from the
+// engine — token substitution must not touch it (see qa/lib/harness-region.mjs), so
+// anything app-specific is looked up from the record that already holds that truth.
+function appName() {
+  try {
+    const rec = JSON.parse(readFileSync(join(HERE, "..", "create-cmp.json"), "utf8"));
+    if (typeof rec.name === "string" && rec.name.trim()) return rec.name;
+  } catch {
+    // Not stamped, or an unreadable record — the gallery is a report, not a gate.
+  }
+  return "App";
+}
+const APP_NAME = appName();
+
 const manifest = JSON.parse(readFileSync(join(previewsDir, "manifest.json"), "utf8"));
 const { width, height, pngScale } = manifest.viewport;
 
@@ -57,7 +72,7 @@ const esc = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replac
 
 const html = `<!doctype html>
 <meta charset="utf-8">
-<title>__APP_NAME__ — screen previews (headless)</title>
+<title>${esc(APP_NAME)} — screen previews (headless)</title>
 <style>
   :root { color-scheme: light; }
   body { font-family: -apple-system, system-ui, sans-serif; margin: 0; background: #F7F9FC; color: #1A1A1A; }
@@ -77,7 +92,7 @@ const html = `<!doctype html>
   .lbl { font-size: 10px; letter-spacing: .06em; text-transform: uppercase; color: #9CA3AF; margin: 0 0 4px; }
 </style>
 <header>
-  <h1>__APP_NAME__ — screen previews</h1>
+  <h1>${esc(APP_NAME)} — screen previews</h1>
   <p>Rendered headlessly (no device/emulator) by <code>:composeApp:renderScreens</code> —
      ${width}×${height}dp, PNG @${pngScale}x · pixels for humans, wireframe+tree for the AI ·
      regenerate: <code>./gradlew :composeApp:renderScreens && node qa/preview-gallery.mjs</code></p>

package/template/qa/verify.mjs

@@ -45,6 +45,7 @@ import { ARCH_DOC_REL_PATH, SECTION_IDS, regenerateArchDoc } from "./lib/arch-do
 import { DETERMINISM_TIMEZONES, compareOutcomes, parseJUnitOutcomes } from "./lib/determinism.mjs";
 import { evaluateAuditCadence } from "./lib/audit-cadence.mjs";
 import { appendFlightRecord, buildFlightEntry } from "./lib/flight-recorder.mjs";
+import { checkHarnessIntegrity, describeIntegrity, LOCK_PATH } from "./lib/harness-lock.mjs";
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const EVIDENCE_DIR = path.join(ROOT, "qa", "evidence");
@@ -92,6 +93,14 @@ Flags:
                                   with --profile ci (or release) it runs
                                   inside the lane and lands on the receipt.
                                   Never combinable with --fast
+  --no-journal                   skip the qa/flight-recorder.jsonl append.
+                                  qa/watch.mjs passes this on every
+                                  save-triggered run: journalling each save
+                                  would add hundreds of committed lines a day
+                                  and leave a permanently dirty tree inside
+                                  the loop the recorder exists to observe. The
+                                  gap is disclosed in the retrospective's own
+                                  output
   --json                         print the receipt as JSON instead of the
                                   human-readable step-by-step log
   --help, -h                     print this usage and exit 0 without
@@ -115,7 +124,13 @@ if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
   process.exit(0);
 }
 
-const RECOGNIZED_FLAGS = new Set(["--profile", "--json", "--fast", "--determinism"]);
+// Every flag this file CONSUMES must be listed here, or the strict check below
+// rejects it. `--no-journal` was consumed but unlisted in 0.13.0, which meant
+// qa/watch.mjs — whose spawn passes exactly these flags — exited 2 on every
+// save without ever running the lane. test/verify-flags.test.mjs now pins
+// consumed ⊆ recognized and watch's spawn ⊆ recognized so the class cannot
+// recur.
+const RECOGNIZED_FLAGS = new Set(["--profile", "--json", "--fast", "--determinism", "--no-journal"]);
 for (let i = 0; i < rawArgs.length; i += 1) {
   const arg = rawArgs[i];
   if (arg === "--profile") {
@@ -416,6 +431,62 @@ function settleAdb() {
 // itself lives in qa/lib/spec-coverage.mjs — the SAME scan feature-brief.mjs
 // derives doneness from, so this gate and the Features view can never disagree
 // about a clause. This step owns only the orphan decision + bookkeeping.
+// The first question any verdict depends on: is the lane that is about to
+// issue it the lane this app was given?
+//
+// Without this the receipt is unfalsifiable in one specific way — edit
+// qa/verify.mjs to force every step PASS and the receipt still validates,
+// because the edited file is simply part of the hashed input surface. Hashing
+// the machine-owned region against qa/harness.lock.json closes that: the lane
+// cannot vouch for itself while modified.
+//
+// DELIBERATELY NOT MEMOIZED. Every other pure-Node step can serve a cached
+// PASS when its inputs are unchanged; a cached PASS on an integrity check is
+// precisely the failure it exists to prevent, and 34 file reads are too cheap
+// to be worth the risk.
+//
+// Three states, three verdicts:
+//   intact    PASS
+//   modified  FAIL — named files, with the command that restores them
+//   unlocked  SKIP — an app stamped before locks existed. Nothing is known to
+//             be wrong, but nothing is proven either; recording the gap keeps
+//             the pipeline honest instead of quietly passing.
+function stepHarnessIntegrity() {
+  const started = Date.now();
+  const r = checkHarnessIntegrity(ROOT);
+  const base = { name: "harnessIntegrity", durationMs: Date.now() - started, harness: r };
+
+  if (r.status === "intact") {
+    return { ...base, verdict: "PASS", note: describeIntegrity(r) };
+  }
+  if (r.status === "unlocked") {
+    return {
+      ...base,
+      verdict: "SKIP",
+      reason: `no ${LOCK_PATH} — this app was stamped before harness locks existed. ` +
+        "`npx create-cmp-cli upgrade --harness` records one.",
+    };
+  }
+
+  const named = [
+    ...r.modified.map((f) => `modified  ${f}`),
+    ...r.missing.map((f) => `missing   ${f}`),
+    ...r.extra.map((f) => `unrecorded ${f}`),
+  ];
+  return {
+    ...base,
+    verdict: "FAIL",
+    reason:
+      `the verify lane has been modified since it was installed — ${describeIntegrity(r)}. ` +
+      "Lane code is machine-owned: it is byte-identical in every create-cmp app and carries " +
+      "no app content, so a local edit is either an accident, a half-applied upgrade, or an " +
+      "attempt to make this receipt say something the lane would not. Restore it with " +
+      "`npx create-cmp-cli upgrade --harness`, which also reports any genuine local patch " +
+      "instead of discarding it.",
+    files: named,
+  };
+}
+
 function stepSpecCoverage() {
   const started = Date.now();
   const specsDir = path.join(ROOT, "specs");
@@ -1307,8 +1378,11 @@ const stepArchDocMemo = memoized("archDoc", stepArchDoc);
 const stepsForProfile = {
   // scaffold: what `create-cmp --verify` proves at stamp time — specCoverage,
   // the full JVM tier (unit + conformance + golden + UI tests) plus the Android build.
-  scaffold: [stepSpecCoverageMemo, stepApprovalsMemo, stepComponentStoriesMemo, stepReachabilityMemo, stepArchDocMemo, stepSchemaHistory, stepBuild, stepUnitTests],
+  scaffold: [stepHarnessIntegrity, stepSpecCoverageMemo, stepApprovalsMemo, stepComponentStoriesMemo, stepReachabilityMemo, stepArchDocMemo, stepSchemaHistory, stepBuild, stepUnitTests],
   local: [
+    // First, always: every verdict below is only worth what the lane issuing
+    // it is worth.
+    stepHarnessIntegrity,
     stepSpecCoverageMemo,
     stepApprovalsMemo,
     stepComponentStoriesMemo,
@@ -1502,6 +1576,30 @@ if (fs.existsSync(ARTIFACTS_DIR)) {
 // Bind the receipt to the content of the verified surface (ADR-0005), NOT the
 // parent SHA (rebase/merge-fragile). Must be computed before latest.json is
 // written — the receipt is an output and must never hash itself.
+/**
+ * The receipt's harness summary — compact by design. The per-file detail lives
+ * on the harnessIntegrity step; this is the part a receipt-holder needs to
+ * identify the lane, plus the names of any modified files (an auditor told
+ * "not intact" and not told which files has been given a rumour, not a fact).
+ */
+function harnessForReceipt() {
+  const row = steps.find((st) => st.name === "harnessIntegrity");
+  const r = row?.harness ?? checkHarnessIntegrity(ROOT);
+  const summary = {
+    name: r.name,
+    version: r.version,
+    sha256: r.sha256,
+    status: r.status,
+    intact: r.status === "intact",
+  };
+  if (r.status === "modified") {
+    summary.modified = r.modified;
+    summary.missing = r.missing;
+    summary.extra = r.extra;
+  }
+  return summary;
+}
+
 const inputs = computeInputsHash(ROOT);
 
 // The receipt. Deterministic key order; ONE volatile timestamp field.
@@ -1524,6 +1622,16 @@ const receipt = {
     fileCount: inputs.fileCount,
   },
   steps,
+  // WHICH LANE issued this verdict. A receipt that cannot name its own harness
+  // can only be checked against the tree it came from; naming the version and
+  // the region digest lets a third party who holds the receipt ask the harder
+  // question — was this the real published lane? — without the tree at all.
+  //
+  // `intact` is the LOCAL claim only: unmodified since installed. It is a
+  // checksum, not a signature, and someone who edits the lane can edit this
+  // too. What they cannot edit is what the registry published under that
+  // version, which is why `version` + `sha256` travel together.
+  harness: harnessForReceipt(),
   strength: { onDeviceSteps },
   evidenceLevel: level,
   artifacts,

package/template/.gradle/buildOutputCleanup/cache.properties

@@ -1,2 +0,0 @@
-#Mon Jul 06 18:20:40 WAT 2026
-gradle.version=8.11.1