create-cmp-cli 0.8.0 → 0.10.0

package/template/qa/approve.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// The approvals CLI — thin shell over qa/lib/approvals.mjs.
+//
+//   node qa/approve.mjs <artifact>          records approval (recomputes the artifact's
+//                                            hash now, stamps the time, writes qa/approvals.json)
+//   node qa/approve.mjs --status            lists every governed artifact + live state
+//                                            (unreviewed / approved / changed-since-approval /
+//                                            reopened, + mode when set) + short hash
+//   node qa/approve.mjs --accept-defaults   express lane (GENESIS-FLOW-DESIGN.md §2): approves
+//                                            every currently-resolvable, not-yet-approved
+//                                            artifact, each stamped "defaults-accepted"
+//   node qa/approve.mjs --reopen <artifact> moves an approved artifact back to "reopened" for
+//                                            redesign (refuses anything not currently approved)
+//
+// This file has NO logic of its own — every decision (the registry, hashing,
+// state, the transitions) lives in qa/lib/approvals.mjs. That's deliberate: the
+// console (VERIFICATION-LAYER-DESIGN.md §4, `POST /api/approve`; GENESIS-FLOW-DESIGN.md
+// §2, `POST /api/reopen`) calls the SAME library this CLI calls, so this file is the
+// API surface, kept intentionally thin and easy to keep in lockstep.
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  approveAllDefaults,
+  approveArtifact,
+  getApprovalStatuses,
+  isPackageResolvable,
+  listGovernedArtifacts,
+  reopenArtifact,
+} from "./lib/approvals.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const args = process.argv.slice(2);
+
+function shortHash(hash) {
+  return hash ? hash.slice(0, 8) : "none";
+}
+
+function printStatus() {
+  const statuses = getApprovalStatuses(ROOT);
+  if (statuses.length === 0) {
+    console.log("No governed artifacts resolved in this project (no specs/, or the package could not be resolved).");
+    return;
+  }
+  console.log("Approval status:\n");
+  for (const s of statuses) {
+    const mark =
+      s.status === "approved" ? "✓" : s.status === "changed-since-approval" ? "✗" : s.status === "reopened" ? "↺" : "→";
+    // An unresolvable artifact (0 files, or a partial kotlin set in a
+    // pre-stamp tree) must never display its degraded hash as if it were
+    // approvable — approval over an unresolved file set is refused.
+    const hashInfo =
+      s.status === "reopened"
+        ? `reopened at ${s.reopenedAt} (was approved ${shortHash(s.storedHash)})`
+        : s.status === "changed-since-approval"
+          ? s.resolvable
+            ? `approved ${shortHash(s.storedHash)} -> now ${shortHash(s.hash)}`
+            : `approved ${shortHash(s.storedHash)} -> unresolvable (${s.fileCount} of expected files resolved)`
+          : s.status === "approved"
+            ? shortHash(s.hash)
+            : s.resolvable
+              ? `would approve at ${shortHash(s.hash)}`
+              : `unresolvable (${s.fileCount} of expected files resolved) — not approvable`;
+    const modeInfo = s.mode ? ` [${s.mode}]` : "";
+    console.log(`${mark} ${s.id}: ${s.status} (${hashInfo})${modeInfo} — ${s.label}`);
+    if (s.missing.length > 0) {
+      console.log(`    missing: ${s.missing.join(", ")}`);
+    }
+  }
+}
+
+if (args.includes("--status")) {
+  printStatus();
+  process.exit(0);
+}
+
+// Write guard: refuse to RECORD approvals in a tree whose package is not
+// resolvable (the raw template / a pre-stamp tree). Approvals belong to a
+// generated project; writing qa/approvals.json into the template pollutes the
+// template itself. Read-only --status (above) stays available anywhere. Applies
+// to every write operation below (single approve, express lane, reopen).
+function refuseIfUnresolvable() {
+  if (isPackageResolvable(ROOT)) return;
+  console.error(
+    "error: this tree's package is not resolvable (composeApp/build.gradle.kts namespace is missing or still a placeholder) — " +
+      "this looks like the raw template or a pre-stamp tree. Approvals are recorded in a generated project; refusing to write qa/approvals.json here.",
+  );
+  process.exit(1);
+}
+
+if (args.includes("--accept-defaults")) {
+  refuseIfUnresolvable();
+  const { approved, skipped } = approveAllDefaults(ROOT);
+  for (const id of approved) {
+    console.log(`✓ approved ${id} [defaults-accepted]`);
+  }
+  for (const s of skipped) {
+    console.log(`→ skipped ${s.id}: ${s.reason}`);
+  }
+  console.log(`\n${approved.length} approved (defaults-accepted), ${skipped.length} skipped (unresolvable).`);
+  process.exit(0);
+}
+
+const reopenFlagIdx = args.indexOf("--reopen");
+if (reopenFlagIdx !== -1) {
+  refuseIfUnresolvable();
+  const artifactId = args[reopenFlagIdx + 1];
+  if (!artifactId) {
+    console.error("usage: node qa/approve.mjs --reopen <artifact>");
+    process.exit(1);
+  }
+  const result = reopenArtifact(ROOT, artifactId);
+  if (!result.ok) {
+    console.error(`error: ${result.reason}`);
+    process.exit(1);
+  }
+  console.log(`↺ reopened ${result.artifact} for redesign — at ${result.reopenedAt}`);
+  process.exit(0);
+}
+
+if (args.length === 0) {
+  const ids = listGovernedArtifacts(ROOT).map((a) => a.id);
+  console.error(
+    "usage: node qa/approve.mjs <artifact> | --status | --accept-defaults | --reopen <artifact>\n" +
+      `  valid artifacts: ${ids.length > 0 ? ids.join(", ") : "(none resolved in this project)"}`,
+  );
+  process.exit(1);
+}
+
+refuseIfUnresolvable();
+
+const artifactId = args[0];
+const result = approveArtifact(ROOT, artifactId);
+if (!result.ok) {
+  console.error(`error: ${result.reason}`);
+  process.exit(1);
+}
+console.log(`✓ approved ${result.artifact} — hash ${shortHash(result.hash)}, at ${result.approvedAt}`);

package/template/qa/arch-doc.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// The architecture-doc generator/checker — thin shell over qa/lib/arch-doc.mjs,
+// mirroring qa/approve.mjs's CLI-over-library split.
+//
+//   node qa/arch-doc.mjs            regenerate docs/ARCHITECTURE.md's
+//                                    `cmp:generated` sections in place from a
+//                                    real tree walk — touches NOTHING outside
+//                                    the markers
+//   node qa/arch-doc.mjs --check    exit nonzero (naming every stale/missing
+//                                    section) if regenerating would change the
+//                                    file; never writes
+//
+// This file has no logic of its own — every decision (what each section
+// derives from, the marker grammar) lives in qa/lib/arch-doc.mjs. The verify
+// lane's `archDoc` step (qa/verify.mjs) calls the SAME library in --check mode.
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { ARCH_DOC_REL_PATH, regenerateArchDoc, writeArchDoc } from "./lib/arch-doc.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const checkOnly = process.argv.includes("--check");
+
+function reportUnknown(result) {
+  if (result.unknownSections.length === 0) return false;
+  console.error(
+    `error: ${ARCH_DOC_REL_PATH} has cmp:generated marker(s) with no registered generator: ${result.unknownSections.join(", ")}`,
+  );
+  return true;
+}
+
+if (checkOnly) {
+  const result = regenerateArchDoc(ROOT);
+  if (!result.ok) {
+    console.error(`error: ${result.reason}`);
+    process.exit(1);
+  }
+  if (reportUnknown(result)) process.exit(1);
+
+  const stale = result.changed || result.missingSections.length > 0;
+  if (!stale) {
+    console.log(`✓ ${ARCH_DOC_REL_PATH} is fresh — every generated section matches the tree.`);
+    process.exit(0);
+  }
+
+  console.error(`✗ ${ARCH_DOC_REL_PATH} is stale:`);
+  for (const id of result.changedSections) {
+    console.error(`  [${id}] regenerating would change this section — the tree no longer matches the doc`);
+  }
+  for (const id of result.missingSections) {
+    console.error(`  [${id}] marker missing from the doc entirely — never generated`);
+  }
+  console.error("Run: node qa/arch-doc.mjs");
+  process.exit(1);
+}
+
+const result = writeArchDoc(ROOT);
+if (!result.ok) {
+  console.error(`error: ${result.reason}`);
+  process.exit(1);
+}
+if (reportUnknown(result)) process.exit(1);
+
+if (!result.wrote) {
+  console.log(`✓ ${ARCH_DOC_REL_PATH} already fresh — nothing to regenerate.`);
+  process.exit(0);
+}
+console.log(`✓ regenerated ${ARCH_DOC_REL_PATH} — updated section(s): ${result.changedSections.join(", ")}`);

package/template/qa/comment.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// The comments CLI — thin shell over qa/lib/comments.mjs (mirrors qa/approve.mjs).
+//
+//   node qa/comment.mjs --list [--open]              readable table of the ledger,
+//                                                     including resolution notes
+//   node qa/comment.mjs --resolve <id> --note "..."  resolves a comment as "agent-cli",
+//                                                     recording the note explaining
+//                                                     what changed as a result
+//
+// This file has NO logic of its own — every decision (validation, ids, the ledger)
+// lives in qa/lib/comments.mjs. Adding a comment is a console/human action (the
+// console's `POST /api/comment` calls the same library through a bridge); this CLI
+// covers the agent's side of the loop of record: observe, act, resolve.
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { listComments, resolveComment } from "./lib/comments.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const args = process.argv.slice(2);
+
+function argValue(flag) {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx === args.length - 1) return undefined;
+  return args[idx + 1];
+}
+
+function printList(openOnly) {
+  let result;
+  try {
+    result = listComments(ROOT, openOnly ? { status: "open" } : {});
+  } catch (err) {
+    console.error(`error: ${err.message}`);
+    process.exit(1);
+  }
+  if (result.comments.length === 0) {
+    console.log(openOnly ? "No open comments." : "No comments recorded yet.");
+    return;
+  }
+  console.log(`Comments${openOnly ? " (open only)" : ""}:\n`);
+  for (const c of result.comments) {
+    const mark = c.status === "resolved" ? "✓" : "→";
+    console.log(`${mark} ${c.id} [${c.target?.type ?? "unknown"}] ${c.status} — by ${c.author} at ${c.createdAt}`);
+    console.log(`    ${c.text}`);
+    if (c.status === "resolved") {
+      const note = c.resolutionNote ? `: ${c.resolutionNote}` : " (no note)";
+      console.log(`    resolved by ${c.resolvedBy} at ${c.resolvedAt}${note}`);
+    }
+  }
+}
+
+if (args.includes("--list")) {
+  printList(args.includes("--open"));
+  process.exit(0);
+}
+
+if (args.includes("--resolve")) {
+  const id = argValue("--resolve");
+  if (!id) {
+    console.error('usage: node qa/comment.mjs --resolve <id> --note "..."');
+    process.exit(1);
+  }
+  const note = argValue("--note");
+  const result = resolveComment(ROOT, id, { note, author: "agent-cli" });
+  if (!result.ok) {
+    console.error(`error: ${result.reason}`);
+    process.exit(1);
+  }
+  const noteSuffix = result.comment.resolutionNote ? ` — ${result.comment.resolutionNote}` : "";
+  console.log(`✓ resolved ${result.comment.id}${noteSuffix}`);
+  process.exit(0);
+}
+
+console.error('usage: node qa/comment.mjs --list [--open] | --resolve <id> --note "..."');
+process.exit(1);

package/template/qa/comments.json

@@ -0,0 +1,4 @@
+{
+  "schema": "cmp-comments/1",
+  "comments": []
+}

package/template/qa/e2e/smoke.yaml

@@ -6,6 +6,12 @@
 # AppShell.kt's navItemTag (lowercase, non-[a-z0-9] runs collapsed to "_", trimmed);
 # keep these ids in sync with it if the configured tabs change.
 #
+# SETTLE RULE for the behaviour steps you add: any assertion that follows an interaction
+# triggering an async state change (search input, a toggle that persists, a load) must use
+# extendedWaitUntil — the ViewModel round-trip passes through a brief Loading arm, and a
+# lane-loaded emulator stretches that window past a bare assert's patience (a real false
+# red from the field). Bare assertVisible is for static post-navigation elements only.
+#
 # Run:  maestro test qa/e2e/smoke.yaml      (device/emulator attached)
 # The verify lane's e2eSmoke step runs this automatically when maestro + a device are present.
 appId: __PACKAGE__

package/template/qa/golden/home.json

@@ -1,12 +1,12 @@
 {"children": [
-  {"children": [
+  {"tag": "home_screen", "children": [
     {"tag": "home_title", "text": "Home"},
     {"children": [
-      {"children": [
+      {"tag": "home_item_1", "children": [
         {"text": "Golden first"},
         {"text": "Structural baseline row one"}
       ]},
-      {"children": [
+      {"tag": "home_item_2", "children": [
         {"text": "Golden second"},
         {"text": "Structural baseline row two"}
       ]}

package/template/qa/lib/a11y.mjs

@@ -5,7 +5,13 @@
 //   touch-target-too-small — a clickable node whose width or height is below the
 //                            minimum touch target (default 48px; the harness dumps
 //                            at density 1 so px == dp there — pass a different
-//                            minTouchTargetPx for device-density trees).
+//                            minTouchTargetPx for device-density trees). Judged on the
+//                            FULL composed size (the tree's additive `size` field) when
+//                            present: `bounds` is the visible slice after ancestor
+//                            clipping, so a list row bisected by a scroll fold reports
+//                            e.g. 371x36 while measuring 371x88 — a scroll-position
+//                            artifact, never an a11y defect. Trees without `size`
+//                            (older dumps) are judged on bounds, as before.
 //   missing-label          — a clickable node with no text, no contentDescription,
 //                            and no descendant text: nothing for a screen reader.
 // Rules (warnings):
@@ -61,17 +67,20 @@ export function auditA11y(tree, opts = {}) {
 
     let violated = false;
 
+    // Judge the FULL composed size when the dump carries it (`size` is unclipped; `bounds`
+    // is the visible slice after ancestor clipping — see the rule doc above). max() keeps
+    // the check honest either way: a genuinely small target is small in both.
     const b = node.bounds;
-    if (
-      b &&
-      typeof b.width === "number" &&
-      typeof b.height === "number" &&
-      (b.width < minTouchTargetPx || b.height < minTouchTargetPx)
-    ) {
+    const s = node.size;
+    const dim = (bv, sv) =>
+      Math.max(typeof bv === "number" ? bv : -1, typeof sv === "number" ? sv : -1);
+    const width = dim(b && b.width, s && s.width);
+    const height = dim(b && b.height, s && s.height);
+    if (width >= 0 && height >= 0 && (width < minTouchTargetPx || height < minTouchTargetPx)) {
       violations.push({
         ...entryBase,
         rule: "touch-target-too-small",
-        detail: `clickable node is ${b.width}x${b.height}px; minimum touch target is ${minTouchTargetPx}x${minTouchTargetPx}px`,
+        detail: `clickable node is ${width}x${height}px; minimum touch target is ${minTouchTargetPx}x${minTouchTargetPx}px`,
       });
       violated = true;
     }