create-cmp-cli 0.7.1 → 0.9.0

package/template/docs/adr/0004-fakes-not-mocks-for-unit-tests.md

@@ -0,0 +1,48 @@
+# ADR-0004: Fakes, not mocks, for unit tests
+
+- **Status:** accepted
+- **Date:** (scaffold date)
+
+## Context
+
+Every repository/source interface in this project's domain layer (`domain/repository/*.kt`)
+needs a test double for ViewModel and use-case unit tests — see `FakeItemRepository`
+(`composeApp/src/commonTest/.../testing/fakes/`), used by `HomeViewModelTest` and
+`GetItemsUseCaseTest`. Mocking frameworks (MockK, Mockito) are the conventional default for
+this in JVM-only Android projects, but this project is Kotlin Multiplatform: `commonTest` runs
+on Android, iOS (native), and desktop (JVM) targets from one source set, and the bytecode-proxy
+mechanism mocking frameworks rely on doesn't exist on Kotlin/Native. A mock-based test suite
+would either be JVM-only (silently untested on iOS) or need a second, divergent native-only
+test strategy.
+
+## Decision
+
+This project uses **hand-written fakes**, never mocking frameworks, for every domain-layer
+interface under test. A fake lives in `testing/fakes/` (commonTest), implements the real
+interface, and is configurable in the shape the exemplar establishes: a typed
+`failure: DomainError?` to force the error path, seeded data for the success path, and
+call-recording where a test needs to assert an interaction happened. A fake returns
+`AppResult.Failure` when configured to fail — it never throws, because the domain contract it
+implements (`domain/repository/*.kt`, ARCH-06) doesn't either.
+
+## Consequences
+
+- One test double works identically on every target `commonTest` runs on — no JVM-only
+  behavior gap between what Android/desktop CI proves and what iOS actually ships.
+- Fakes are slightly more code up front than a one-line `every { } returns` mock stub, but
+  they read as real (if simplified) implementations, which makes failure-path tests
+  (`failure = DomainError.Network`) as readable as success-path tests instead of relying on
+  stubbing syntax a reviewer has to decode.
+- No mocking-framework dependency to keep on the frozen version set (`gradle/libs.versions.toml`)
+  or track for Kotlin/Native compatibility on every version bump.
+- The cost: a new repository interface needs its fake hand-written before its consumers can be
+  tested — there is no "just mock it inline" escape hatch. This is intentional: an interface
+  too awkward to fake by hand is usually an interface with the wrong shape.
+
+## Related
+
+- `CLAUDE.md` — "Testing" section: "**Hand-written fakes** in `testing/fakes/` — never mocking
+  frameworks", the contract this ADR records the reasoning for.
+- `docs/TESTING.md` — "Fakes, never mocks" under Unit conventions.
+- `composeApp/src/commonTest/.../testing/fakes/FakeItemRepository.kt` — the exemplar fake this
+  ADR's shape is drawn from.

package/template/qa/approvals.json

@@ -0,0 +1,42 @@
+{
+  "schema": "cmp-approvals/1",
+  "exemplarFeature": "home",
+  "artifacts": [
+    {
+      "artifact": "intent",
+      "status": "unreviewed",
+      "hash": null,
+      "approvedAt": null
+    },
+    {
+      "artifact": "design-system",
+      "status": "unreviewed",
+      "hash": null,
+      "approvedAt": null
+    },
+    {
+      "artifact": "architecture",
+      "status": "unreviewed",
+      "hash": null,
+      "approvedAt": null
+    },
+    {
+      "artifact": "components",
+      "status": "unreviewed",
+      "hash": null,
+      "approvedAt": null
+    },
+    {
+      "artifact": "exemplar-feature",
+      "status": "unreviewed",
+      "hash": null,
+      "approvedAt": null
+    },
+    {
+      "artifact": "exemplar-spec",
+      "status": "unreviewed",
+      "hash": null,
+      "approvedAt": null
+    }
+  ]
+}

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/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"}
       ]}