create-cmp-cli 0.13.0 → 0.14.1

package/packages/harness/src/lib/token-drift.mjs

@@ -0,0 +1,94 @@
+// token-drift.mjs — pure, dependency-free comparison of a LIVE inspector tree's
+// resolved design-token payloads against the declared design-system catalog.
+//
+// Mirrors the comparison semantics of diffAgainstDesignSystem() in the cmp-inspector
+// MCP server (inspector/mcp/src/lib/drift.mjs): for each node in the tree that carries
+// a designToken payload ({tokens:[names], resolved:{facet:value}}), and for each
+// declared token name on that node, resolve the expected value from the catalog
+// (dimens checked before colors — same lookup order as the MCP) and compare it
+// against every one of the node's resolved facet values. If NONE of them match the
+// declared value, the node has drifted from what it claims to use.
+//
+// Matching is case/whitespace-normalized string equality (trim + lowercase) — the
+// exact normalization the MCP's `normalize()` applies (so "#0A2540" == "#0a2540",
+// but "72dp" would NOT equal "72.0dp" — the MCP does not do numeric-format
+// normalization, so neither do we, to keep the comparison rule identical).
+//
+// No imports, no Node built-ins beyond what the runtime provides for free — pure
+// object-in/object-out, unit-testable with plain objects.
+
+/**
+ * @param {{colors?:Record<string,string>, dimens?:Record<string,string>}} declaredCatalog
+ * @param {{root:object}|object} tree  the parsed /inspect/tree document (or a bare node)
+ * @returns {{checked:number, drifted:Array<{node:string, token:string, facet:string, expected:string, actual:string}>}}
+ */
+export function compareTokenDrift(declaredCatalog, tree) {
+  const colors = (declaredCatalog && declaredCatalog.colors) || {};
+  const dimens = (declaredCatalog && declaredCatalog.dimens) || {};
+
+  let checked = 0;
+  const drifted = [];
+
+  for (const { node, path } of walk(tree)) {
+    const dt = node && node.designToken;
+    if (!dt || !Array.isArray(dt.tokens) || dt.tokens.length === 0) continue;
+
+    const resolved = dt.resolved && typeof dt.resolved === "object" ? dt.resolved : {};
+    const resolvedEntries = Object.entries(resolved);
+
+    for (const token of dt.tokens) {
+      let declared;
+      if (Object.prototype.hasOwnProperty.call(dimens, token)) declared = dimens[token];
+      else if (Object.prototype.hasOwnProperty.call(colors, token)) declared = colors[token];
+      else continue; // token not in the declared catalog — nothing to diff against
+
+      checked += 1;
+
+      const declaredNorm = normalize(declared);
+      const matches = resolvedEntries.some(([, v]) => normalize(v) === declaredNorm);
+      if (matches) continue;
+
+      const [facet, actual] = pickFacetForReport(resolvedEntries);
+      drifted.push({
+        node: node.testTag || path,
+        token,
+        facet,
+        expected: declared,
+        actual,
+      });
+    }
+  }
+
+  return { checked, drifted };
+}
+
+// Depth-first walk yielding every node with a stable, dotted path. Accepts either a
+// full tree ({schemaVersion, source, root}) or a bare node — same contract as the
+// MCP's tree.mjs walk().
+function* walk(tree) {
+  const root = tree && tree.root ? tree.root : tree;
+  if (!root || typeof root !== "object") return;
+  yield* walkNode(root, "root");
+}
+
+function* walkNode(node, path) {
+  yield { node, path };
+  const children = Array.isArray(node.children) ? node.children : [];
+  for (let i = 0; i < children.length; i++) {
+    yield* walkNode(children[i], `${path}.children[${i}]`);
+  }
+}
+
+// Case-insensitive, trimmed comparison — identical to the MCP's normalize().
+function normalize(v) {
+  return String(v == null ? "" : v).trim().toLowerCase();
+}
+
+// Best-effort single (facet, value) to blame in the drift report. If the node
+// resolved exactly one facet, name it directly; otherwise join every facet/value
+// so the reader sees everything the node actually resolved.
+function pickFacetForReport(entries) {
+  if (entries.length === 1) return [entries[0][0], String(entries[0][1])];
+  if (entries.length === 0) return ["(none)", "(no resolved values)"];
+  return [entries.map(([k]) => k).join(","), entries.map(([, v]) => String(v)).join(", ")];
+}

package/packages/harness/src/lib/tree.mjs

@@ -0,0 +1,108 @@
+// tree.mjs — pure helpers for loading and walking a CMP inspector tree.
+// No MCP imports here: everything is unit-testable in isolation.
+//
+// The JSON tree contract (schemaVersion 1):
+//   { schemaVersion, source, root: <Node> }
+//   Node = { testTag, text, contentDescription, bounds:{x,y,width,height},
+//            designToken: { tokens:string[], resolved:{[k]:string} } | null,
+//            children: Node[] }
+//
+// Additive optional fields (still schemaVersion 1 — absent on old trees, so every
+// consumer must treat them as optional):
+//   role:      string|null  — semantics Role (e.g. "Button", "Checkbox")
+//   clickable: boolean      — presence of the OnClick semantics action
+//   disabled:  boolean      — presence of the Disabled semantics property
+
+import { readFileSync } from "node:fs";
+
+/**
+ * Load a tree from a filesystem path, a JSON string, or an already-parsed object.
+ * Validates the minimal shape (schemaVersion + root) and throws a clear,
+ * caller-facing Error (never a raw fs/JSON stack) on failure.
+ *
+ * @param {string|object} pathOrObj
+ * @returns {object} the parsed tree ({ schemaVersion, source, root })
+ */
+export function loadTree(pathOrObj) {
+  if (pathOrObj == null) {
+    throw new Error("loadTree: no tree provided (path or object is null/undefined).");
+  }
+
+  let tree;
+  if (typeof pathOrObj === "object") {
+    tree = pathOrObj;
+  } else if (typeof pathOrObj === "string") {
+    const raw = readOrParse(pathOrObj);
+    tree = raw;
+  } else {
+    throw new Error(`loadTree: unsupported input type '${typeof pathOrObj}'.`);
+  }
+
+  if (!tree || typeof tree !== "object") {
+    throw new Error("loadTree: tree is not an object.");
+  }
+  if (!tree.root || typeof tree.root !== "object") {
+    throw new Error("loadTree: tree has no 'root' node (expected { schemaVersion, source, root }).");
+  }
+  return tree;
+}
+
+// If the string looks like a JSON document, parse it directly; otherwise treat
+// it as a filesystem path and read+parse. This lets callers pass either.
+function readOrParse(str) {
+  const trimmed = str.trim();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      return JSON.parse(trimmed);
+    } catch (err) {
+      throw new Error(`loadTree: input looked like JSON but failed to parse: ${err.message}`);
+    }
+  }
+  let contents;
+  try {
+    contents = readFileSync(str, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      throw new Error(`loadTree: tree file not found: ${str}`);
+    }
+    throw new Error(`loadTree: could not read tree file '${str}': ${err.message}`);
+  }
+  try {
+    return JSON.parse(contents);
+  } catch (err) {
+    throw new Error(`loadTree: tree file '${str}' is not valid JSON: ${err.message}`);
+  }
+}
+
+/**
+ * Depth-first walk yielding every node with a stable, dotted path.
+ * Root's path is "root"; children are "root.children[0]", etc.
+ *
+ * @param {object} tree  a full tree ({root}) OR a bare node.
+ * @yields {{ node: object, path: string }}
+ */
+export function* walk(tree) {
+  const root = tree && tree.root ? tree.root : tree;
+  if (!root || typeof root !== "object") return;
+  yield* walkNode(root, "root");
+}
+
+function* walkNode(node, path) {
+  yield { node, path };
+  const children = Array.isArray(node.children) ? node.children : [];
+  for (let i = 0; i < children.length; i++) {
+    yield* walkNode(children[i], `${path}.children[${i}]`);
+  }
+}
+
+/**
+ * Find the first node with the given testTag. Returns { node, path } or null.
+ * @param {object} tree
+ * @param {string} tag
+ */
+export function findByTestTag(tree, tag) {
+  for (const entry of walk(tree)) {
+    if (entry.node.testTag === tag) return entry;
+  }
+  return null;
+}

package/packages/harness/src/preview-gallery.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// preview-gallery.mjs — build a self-contained HTML gallery from renderScreens output.
+//
+//   node qa/preview-gallery.mjs [previewsDir]
+//
+// Reads <previewsDir>/manifest.json (default composeApp/build/previews — the output of
+// `./gradlew :composeApp:renderScreens`), renders each screen's tree.json to a wireframe
+// SVG with the vendored inspector render lib (structure for the AI), and embeds the
+// harness PNGs (pixels for the human) into ONE index.html — no server, no device, open
+// the file. Also drops <id>/wireframe.svg next to each tree.
+//
+// Zero dependencies beyond qa/lib (vendored, pure logic) — works without the create-cmp
+// plugin installed, like every other qa/ script.
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const previewsDir = resolve(
+  process.argv[2] || join(HERE, "..", "composeApp", "build", "previews"),
+);
+
+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;
+
+const cards = [];
+for (const screen of manifest.screens) {
+  const tree = JSON.parse(readFileSync(join(previewsDir, screen.tree), "utf8"));
+  const audit = auditA11y(tree);
+  const svg = renderTreeSvg(tree, { a11y: audit });
+  writeFileSync(join(previewsDir, screen.id, "wireframe.svg"), svg);
+
+  const png = readFileSync(join(previewsDir, screen.png));
+  const summary = summarize(tree);
+  cards.push({ screen, svg, pngB64: png.toString("base64"), audit, summary });
+  console.log(
+    `${screen.id}: ${summary.nodes} nodes, ${summary.tokenized} tokenized, ` +
+      `${summary.tagged} tagged, a11y ${audit.pass ? "PASS" : audit.violations.length + " violation(s)"}`,
+  );
+}
+
+function summarize(tree) {
+  let nodes = 0, tokenized = 0, tagged = 0;
+  (function walk(n) {
+    nodes++;
+    if (n.designToken) tokenized++;
+    if (n.testTag) tagged++;
+    (n.children || []).forEach(walk);
+  })(tree.root);
+  return { nodes, tokenized, tagged };
+}
+
+const esc = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+const html = `<!doctype html>
+<meta charset="utf-8">
+<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; }
+  header { padding: 20px 28px 8px; }
+  header h1 { margin: 0 0 4px; font-size: 20px; }
+  header p { margin: 0; color: #6B7280; font-size: 13px; }
+  .grid { display: flex; flex-wrap: wrap; gap: 24px; padding: 20px 28px 40px; }
+  .card { background: #fff; border: 1px solid #E5E7EB; border-radius: 16px; padding: 16px; }
+  .card h2 { margin: 0 0 2px; font-size: 15px; }
+  .meta { color: #6B7280; font-size: 12px; margin: 0 0 10px; }
+  .meta .fail { color: #DC2626; font-weight: 600; }
+  .meta .pass { color: #16A34A; font-weight: 600; }
+  .panes { display: flex; gap: 12px; align-items: flex-start; }
+  .panes img { width: ${Math.round(width * 0.62)}px; border: 1px solid #E5E7EB; border-radius: 12px; display: block; }
+  .panes .wire svg { width: ${Math.round(width * 0.78)}px; height: auto; display: block; }
+  .wire { border: 1px dashed #C8D0DA; border-radius: 12px; overflow: hidden; }
+  .lbl { font-size: 10px; letter-spacing: .06em; text-transform: uppercase; color: #9CA3AF; margin: 0 0 4px; }
+</style>
+<header>
+  <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>
+</header>
+<div class="grid">
+${cards
+  .map(
+    ({ screen, svg, pngB64, audit, summary }) => `  <div class="card">
+    <h2>${esc(screen.title)}</h2>
+    <p class="meta">id <code>${esc(screen.id)}</code> · ${summary.nodes} nodes ·
+       ${summary.tokenized} tokenized · ${summary.tagged} tagged ·
+       a11y <span class="${audit.pass ? "pass" : "fail"}">${
+      audit.pass ? "PASS" : esc(audit.violations.length + " violation(s)")
+    }</span></p>
+    <div class="panes">
+      <div><p class="lbl">pixels</p><img alt="${esc(screen.id)} pixels" src="data:image/png;base64,${pngB64}"></div>
+      <div><p class="lbl">structure</p><div class="wire">${svg}</div></div>
+    </div>
+  </div>`,
+  )
+  .join("\n")}
+</div>
+`;
+
+const outFile = join(previewsDir, "index.html");
+writeFileSync(outFile, html);
+console.log(`gallery -> ${outFile}`);

package/packages/harness/src/receipt-check.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// The evidence-binding predicate — answers one question: does the committed
+// receipt (qa/evidence/latest.json) validly attest THIS tree, right now?
+//
+//   node qa/receipt-check.mjs [--hook] [--json]
+//
+// Both enforcement points reduce to this predicate: the local Stop hook
+// (.claude/settings.json) calls it on every turn-end, and CI calls it before
+// re-running the lane. See docs/adr/0005-evidence-binding-by-inputs-hash.md.
+//
+// VALID  iff receipt.verdict === "PASS" && receipt.inputs.hash === recompute(tree)
+// Exit codes (normal mode): VALID -> 0, INVALID -> 1.
+// Exit codes (--hook mode, Claude Code Stop-hook protocol):
+//   stop_hook_active === true  -> 0 (never block twice in a row)
+//   INVALID                    -> 2, reason on stderr (Claude Code's block-and-feed-back signal)
+//   VALID                      -> 0, silent
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { computeInputsHash } from "./lib/inputs-hash.mjs";
+import { evaluateReceipt, readReceipt } from "./lib/receipt-validate.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const args = process.argv.slice(2);
+const asHook = args.includes("--hook");
+const asJson = args.includes("--json");
+
+function readStdinJson() {
+  try {
+    const raw = fs.readFileSync(0, "utf8");
+    if (!raw.trim()) return {};
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+// The predicate itself lives in qa/lib/receipt-validate.mjs (vendored from the
+// cmp-receipts package — one definition everywhere a receipt is judged); this
+// CLI only reads the receipt and frames the exit codes.
+function evaluate() {
+  const receipt = readReceipt(ROOT);
+  if (receipt === null) {
+    return { valid: false, reason: "no receipt — run `node qa/verify.mjs`", profile: undefined };
+  }
+  // A fast-mode receipt (verify --fast) is an inner-loop signal, never done
+  // evidence — refused here before the hash is even recomputed, so a session
+  // can never end on "done" while its evidence trail's last run was --fast.
+  if (receipt.mode === "fast") {
+    return {
+      valid: false,
+      reason: "the last verify run was --fast (inner-loop only); run the full lane (`node qa/verify.mjs`) before finishing",
+      profile: receipt.profile,
+    };
+  }
+  const result = evaluateReceipt(receipt, () => computeInputsHash(ROOT));
+  // Surface the receipt's evidence rung (the ladder — qa/lib/evidence-level.mjs)
+  // alongside the verdict: the rung is the receipt's own derived field, read
+  // verbatim, never recomputed here. Older receipts without it stay valid.
+  const level = receipt.evidenceLevel;
+  if (level && typeof level === "object" && typeof level.rung === "string") {
+    result.evidenceLevel = level;
+  }
+  return result;
+}
+
+const result = evaluate();
+
+if (asHook) {
+  const hookInput = readStdinJson();
+  if (hookInput.stop_hook_active === true) {
+    process.exit(0);
+  }
+  if (!result.valid) {
+    process.stderr.write(
+      `Not done: ${result.reason}. Run \`node qa/verify.mjs\` and commit the receipt, or see README §Verification enforcement to bypass.\n`,
+    );
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
+const rungSuffix = result.evidenceLevel ? ` — evidence ${result.evidenceLevel.rung} · ${result.evidenceLevel.name}` : "";
+
+if (asJson) {
+  console.log(JSON.stringify(result, null, 2));
+} else if (result.valid) {
+  console.log(`VALID — ${result.reason}${rungSuffix}`);
+} else {
+  console.error(`INVALID — ${result.reason}`);
+}
+
+process.exit(result.valid ? 0 : 1);

package/packages/harness/src/record-audit.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// Record that a cmp-audit of one androidMain subsystem happened — the
+// write half of the audit-cadence report (qa/lib/audit-cadence.mjs).
+//
+//   node qa/record-audit.mjs <subsystem> [--by <who-or-what>]
+//   node qa/record-audit.mjs --list
+//
+// Recording is a CLAIM — "this subsystem, as of this commit, was audited" —
+// so the entry's sha is derived from HEAD by the library, never passed in,
+// and the write is REFUSED when there is no git history, when the subsystem
+// is not one this app actually has (derived from the tree, printed on
+// refusal), or when the subsystem's files differ from HEAD (the record
+// would name a commit the audited bytes did not match — commit first).
+// Refusal over fabrication, the same stance as qa/approve.mjs.
+//
+// This CLI exists so the audit loop closes mechanically: the release
+// profile's receipt nudges "changed since last audit → cmp-audit <name>",
+// and the auditor's last act is this one command.
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { AUDITS_REL_PATH, ROOT_SUBSYSTEM, androidMainPackageRoot, evaluateAuditCadence, listSubsystems, recordAudit } from "./lib/audit-cadence.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const USAGE = `node qa/record-audit.mjs <subsystem> [--by <who-or-what>]
+
+Appends one audit record (subsystem, HEAD sha, ISO timestamp, recorder) to
+${AUDITS_REL_PATH}. The verify lane's release profile reports which
+subsystems changed since their last record. Subsystems are derived from the
+tree: the immediate package directories under the androidMain Kotlin source
+root ("${ROOT_SUBSYSTEM}" for files directly at the package root).
+
+  --list        print the derived subsystems and their audit status
+  --by <name>   who/what recorded this (default: git user.name)
+  --help, -h    this usage
+`;
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+  console.log(USAGE);
+  process.exit(args.length === 0 ? 2 : 0);
+}
+
+if (args.includes("--list")) {
+  const report = evaluateAuditCadence(ROOT);
+  if (!report.ok) {
+    console.log(report.reason);
+    process.exit(0);
+  }
+  console.log(`androidMain subsystems under ${report.packageRoot} (${report.summary}):`);
+  for (const s of report.subsystems) {
+    const when = s.audit?.at ? ` — last audit ${s.audit.at.slice(0, 10)} (${s.audit.sha.slice(0, 7)}, by ${s.audit.by ?? "unknown"})` : "";
+    console.log(`  ${s.name}: ${s.status}${when}`);
+  }
+  process.exit(0);
+}
+
+const byIdx = args.indexOf("--by");
+const by = byIdx >= 0 ? args[byIdx + 1] : undefined;
+if (byIdx >= 0 && !by) {
+  console.error("--by needs a value");
+  process.exit(2);
+}
+const positional = args.filter((a, i) => !(byIdx >= 0 && (i === byIdx || i === byIdx + 1)));
+if (positional.length !== 1 || positional[0].startsWith("--")) {
+  console.error(`expected exactly one subsystem name — run node qa/record-audit.mjs --help`);
+  process.exit(2);
+}
+
+const res = recordAudit(ROOT, { subsystem: positional[0], by });
+if (!res.ok) {
+  console.error(`refused: ${res.reason}`);
+  const pkgRoot = androidMainPackageRoot(ROOT);
+  if (pkgRoot.ok) {
+    console.error(`derived subsystems: ${listSubsystems(ROOT, pkgRoot.rel).join(", ")}`);
+  }
+  process.exit(1);
+}
+console.log(`recorded: audit of ${res.entry.subsystem} against ${res.sha.slice(0, 7)} (by ${res.entry.by}) → ${AUDITS_REL_PATH}`);
+console.log("commit the ledger with your change — the release profile's receipt reads it.");