create-cmp-cli 0.2.0 → 0.3.0

package/template/composeApp/src/desktopTest/kotlin/com/example/app/testing/StructuralTree.kt

@@ -0,0 +1,63 @@
+package __PACKAGE__.testing
+
+import androidx.compose.ui.semantics.SemanticsNode
+import androidx.compose.ui.semantics.SemanticsProperties
+import androidx.compose.ui.semantics.getOrNull
+
+/**
+ * Serializes a Compose semantics tree to deterministic, diffable JSON — the golden-tree
+ * format the verify lane's `goldenTrees` step compares against the committed baselines
+ * in `qa/golden/`. (NB: no glob patterns in KDoc — Kotlin block comments nest.)
+ *
+ * Structure only, no pixels and no absolute geometry: testTag, role, text, and children.
+ * That keeps baselines stable across platforms/densities while still catching structural
+ * regressions (nodes appearing/disappearing/reordering, text changes, role changes).
+ */
+object StructuralTree {
+
+    fun serialize(root: SemanticsNode): String = buildString {
+        appendNode(root, 0)
+        append('\n')
+    }
+
+    private fun StringBuilder.appendNode(node: SemanticsNode, depth: Int) {
+        val indent = "  ".repeat(depth)
+        val tag = node.config.getOrNull(SemanticsProperties.TestTag)
+        val role = node.config.getOrNull(SemanticsProperties.Role)?.toString()
+        val text = node.config.getOrNull(SemanticsProperties.Text)?.joinToString(" ") { it.text }
+        val desc = node.config.getOrNull(SemanticsProperties.ContentDescription)?.joinToString(" ")
+
+        append(indent).append("{")
+        val fields = buildList {
+            tag?.let { add(""""tag": ${json(it)}""") }
+            role?.let { add(""""role": ${json(it)}""") }
+            text?.let { add(""""text": ${json(it)}""") }
+            desc?.let { add(""""contentDescription": ${json(it)}""") }
+        }
+        append(fields.joinToString(", "))
+
+        val children = node.children.filter { it.isMeaningful() }
+        if (children.isEmpty()) {
+            append("}")
+        } else {
+            if (fields.isNotEmpty()) append(", ")
+            append("\"children\": [\n")
+            children.forEachIndexed { i, child ->
+                appendNode(child, depth + 1)
+                if (i < children.lastIndex) append(",")
+                append('\n')
+            }
+            append(indent).append("]}")
+        }
+    }
+
+    /** Nodes carrying no signal (pure layout wrappers) are elided so baselines stay tight. */
+    private fun SemanticsNode.isMeaningful(): Boolean =
+        config.getOrNull(SemanticsProperties.TestTag) != null ||
+            config.getOrNull(SemanticsProperties.Text) != null ||
+            config.getOrNull(SemanticsProperties.ContentDescription) != null ||
+            config.getOrNull(SemanticsProperties.Role) != null ||
+            children.any { it.isMeaningful() }
+
+    private fun json(s: String): String = "\"${s.replace("\\", "\\\\").replace("\"", "\\\"")}\""
+}

package/template/docs/ARCHITECTURE.md

@@ -0,0 +1,51 @@
+# Architecture
+
+Clean Architecture, three layers, one rule: **dependencies point inward.**
+
+```
+┌─────────────────────────────────────────────────────┐
+│ presentation   Screens (Compose) · ViewModels        │
+│                └─ depends on domain only             │
+├─────────────────────────────────────────────────────┤
+│ domain         models · repository INTERFACES ·      │
+│                use cases — imports nothing app-internal │
+├─────────────────────────────────────────────────────┤
+│ data           repository implementations ·          │
+│                remote/local sources                  │
+└─────────────────────────────────────────────────────┘
+           di/ wires implementations to interfaces (Koin)
+```
+
+- `presentation` never imports `data`. ViewModels call **use cases**, not repositories.
+- `domain` is pure Kotlin — no Compose, no Koin, no platform types.
+- `data` implements the domain's repository interfaces; sources stay behind them.
+
+## Data flow (unidirectional)
+
+`Screen` collects `StateFlow<UiState>` from its ViewModel → user intent calls a ViewModel
+function → the ViewModel invokes a use case → repository → sources → new immutable `UiState`
+is emitted. No state lives in composables beyond UI-local concerns.
+
+## The exemplar: the `home` feature
+
+`presentation/home` + `domain/{model,repository,usecase}` + `data/remote` is the **reference
+implementation** of the pattern — including its tests (`commonTest`). To add a feature, mirror
+it exactly:
+
+1. Domain: model + repository interface + use case (+ tests).
+2. Data: repository implementation (+ test through the domain contract).
+3. Presentation: `<Feature>Screen` (testTag-rooted) + `<Feature>ViewModel` with
+   `StateFlow<UiState>` (+ test using a fake from `testing/fakes/`).
+4. DI: register in `di/AppModule.kt`.
+5. Navigation: add the route in `presentation/navigation/`.
+6. Run `node qa/verify.mjs` — done means PASS + committed receipt.
+
+## Conventions
+
+- **Theme tokens** (`presentation/theme/`) are the only source of design values — no hardcoded
+  colors/spacing/radii in screens.
+- **testTags** on every screen root and interactive element (`TestTagAutomation` exposes them
+  to E2E tooling on both platforms).
+- **Insets** are owned by `BaseScreen` — new screens compose inside it and never re-solve
+  edge-to-edge padding.
+- Significant decisions get an ADR in [`docs/adr/`](./adr/) — see the template there.

package/template/docs/TESTING.md

@@ -0,0 +1,64 @@
+# Testing
+
+The pyramid this project uses, bottom-up. The `home` feature's tests are the exemplar —
+copy their shape.
+
+| Layer | Where | Run |
+|---|---|---|
+| Unit (majority) | `composeApp/src/commonTest` | `./gradlew :composeApp:desktopTest` |
+| Conformance gates (ARCH clauses) | `composeApp/src/desktopTest/…/conformance` | same task |
+| Screen behavior — Compose UI Test (spec-cited) | `composeApp/src/desktopTest/…/presentation` | same task |
+| Golden trees (structure) | `qa/golden/` + `HomeGoldenTreeTest` | same task |
+<!-- >>> cmp:feature e2e -->
+| E2E smoke (few) | `qa/e2e/*.yaml` (Maestro) | `maestro test qa/e2e/smoke.yaml` |
+<!-- <<< cmp:feature e2e -->
+| The lane (all of it) | `qa/verify.mjs` | `node qa/verify.mjs` |
+
+Every durable test cites the spec clause it verifies (`// SPEC: HOME-02` — see
+[`specs/`](../specs/README.md)); **new behavior begins as a spec clause.** The lane's
+`specCoverage` step enforces this: it fails on orphan clauses (no citing test) and orphan tags
+(no matching clause, or one citing a withdrawn clause).
+
+## Unit conventions
+
+- **Frameworks:** `kotlin-test` assertions · `kotlinx-coroutines-test` (`runTest`,
+  `StandardTestDispatcher`) · **Turbine** for Flow/StateFlow.
+- **Fakes, never mocks.** Every repository/source interface gets a hand-written fake in
+  `commonTest/…/testing/fakes/` — configurable (`shouldFail`, seeded data) and
+  call-recording. Mocking frameworks are banned: they're JVM-only in KMP and hide bad seams.
+- **Style:** Arrange-Act-Assert; behavior-named backtick tests
+  (`` `emits error message when repository fails` ``); one behavior per test; no shared
+  mutable state between tests.
+- **ViewModels:** install a `StandardTestDispatcher` as Main (`@BeforeTest setMain` /
+  `@AfterTest resetMain`) because `viewModelScope` launches on Main; assert state with
+  `state.test { … }` (Turbine).
+- **Suspend/delay:** always under `runTest` — virtual time makes `delay` free.
+
+## What every new piece of code brings
+
+| You added | You also add |
+|---|---|
+| a ViewModel | a `*ViewModelTest` (states: loading, success, failure, retry) |
+| a use case | a `*UseCaseTest` (behavior + failure propagation) |
+| a repository impl | a test through its DOMAIN interface |
+| a screen | a testTag root (E2E reachable) |
+
+Never delete, weaken, or `@Ignore` a failing test to get green. Fix the behavior — or if the
+test is genuinely wrong, change it and say so explicitly in your PR/summary.
+
+<!-- >>> cmp:feature e2e -->
+## E2E
+
+Maestro flows (`qa/e2e/*.yaml`) cover boot + bottom-nav — install the free CLI once
+(`curl -fsSL "https://get.maestro.mobile.dev" | bash`). Selectors go by **testTag** (`id:` —
+surfaced as resource-ids via `TestTagAutomation`), never by display text. One flow per
+journey, spec-clause cited; keep the E2E tip small — behavior belongs in unit tests.
+<!-- <<< cmp:feature e2e -->
+
+## The verify lane
+
+`node qa/verify.mjs` is the definition of done: spec coverage → build → unit tests →
+(conformance, golden trees, token drift, a11y — as they ship) → E2E smoke when a device is
+attached. It writes the evidence receipt to `qa/evidence/latest.json`; **commit the receipt
+with your change.** SKIPped steps are recorded honestly — green-with-gaps is visible, never
+silent.

package/template/docs/adr/0001-adopt-the-create-cmp-harness-conventions.md

@@ -0,0 +1,32 @@
+# ADR-0001: Adopt the create-cmp harness conventions
+
+- **Status:** accepted
+- **Date:** (scaffold date)
+
+## Context
+
+This project was generated by create-cmp, which ships an opinionated, mechanically-enforced
+set of conventions: Clean Architecture with inward-pointing dependencies, a frozen and
+CI-verified dependency version set (Kotlin/KSP/Compose/Room/AGP move as one), unit tests with
+hand-written fakes (no mocking frameworks), testTag-addressable screens, theme-token-only
+design values, and a verify lane whose committed evidence receipt is the definition of done.
+AI collaborators are bound to these via `CLAUDE.md`.
+
+## Decision
+
+We keep the harness conventions as the project's baseline. Deviations are made consciously:
+each one gets its own ADR superseding the relevant part of this record.
+
+## Consequences
+
+- Any contributor (human or AI) can rely on the exemplar `home` feature as the canonical
+  pattern, and on `node qa/verify.mjs` as the single gate.
+- Upgrades stay on proven-green version sets (`npx create-cmp-cli upgrade`) rather than
+  ad-hoc bumps.
+- The cost: less per-developer freedom in structure and tooling — accepted in exchange for a
+  codebase that stays verifiable at AI speed.
+
+This ADR also records *why ADRs*: significant decisions die in chat threads and PR comments;
+a one-page record in the repo is the industry-standard fix
+([MADR](https://adr.github.io/madr/)-style, trimmed). Copy `template.md` to
+`NNNN-<slug>.md` for the next decision.

package/template/docs/adr/template.md

@@ -0,0 +1,17 @@
+# ADR-NNNN: <short decision title>
+
+- **Status:** proposed | accepted | superseded by ADR-XXXX
+- **Date:** YYYY-MM-DD
+
+## Context
+
+What forces are at play? What problem does this decision answer? 2–5 sentences.
+
+## Decision
+
+What we chose, stated actively: "We will …". One paragraph.
+
+## Consequences
+
+What becomes easier, what becomes harder, what we accept. Include the alternatives rejected
+and the one-line reason each lost.

package/template/gitignore

@@ -11,6 +11,10 @@
 # Kotlin
 .kotlin/
 
+# Verify-lane binary evidence (screenshots, reports, page sources). The RECEIPT
+# (qa/evidence/latest.json) IS committed — these artifacts are hashed into it instead.
+qa-artifacts/
+
 # iOS / CocoaPods / XcodeGen
 iosApp/Pods/
 iosApp/Podfile.lock

package/template/gradle/libs.versions.toml

@@ -86,6 +86,8 @@ android-desugar-jdk = { module = "com.android.tools:desugar_jdk_libs", version =
 kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test", version.ref = "kotlin" }
 koin-test = { module = "io.insert-koin:koin-test", version.ref = "koin" }
 kotlinx-coroutines-test = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-test", version = "1.9.0" }
+# Turbine — Flow/StateFlow assertion library (CashApp). KMP-safe; the exemplar ViewModel tests use it.
+turbine = { module = "app.cash.turbine:turbine", version = "1.2.0" }
 
 [plugins]
 kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }

package/template/manifest.json

@@ -25,6 +25,8 @@
   ],
   "packageSourceRoots": [
     "composeApp/src/commonMain/kotlin",
+    "composeApp/src/commonTest/kotlin",
+    "composeApp/src/desktopTest/kotlin",
     "composeApp/src/androidMain/kotlin",
     "composeApp/src/androidDebug/kotlin",
     "composeApp/src/androidRelease/kotlin",
@@ -81,13 +83,12 @@
       ],
       "notes": "When off: strip `room` marker blocks in build.gradle.kts (ksp + room plugins), composeApp/build.gradle.kts (room/sqlite deps, kspAndroid/kspIos/kspDesktop room.compiler, the room {} schema block), AppApplication.kt, KoinHelper.kt and DesktopModule.kt (AppDatabase single + appContext). Delete the data/local dirs (incl. the desktopMain one when dev-client is on). The example `home` feature does NOT depend on Room (its ItemRepositoryImpl is in-memory), so it keeps building with Room off."
     },
-    "appium": {
+    "e2e": {
       "enabledByDefault": true,
       "paths": [
-        "qa/appium",
-        "tests/appium"
+        "qa/e2e"
       ],
-      "notes": "Appium harness (Python conftest + smoke, JS client + smoke runner). No in-file markers; toggled by deleting the listed paths."
+      "notes": "Device-level E2E harness — Maestro flows (qa/e2e/*.yaml; replaced the Appium Node+pytest runners 2026-07-06). Feature key renamed from `appium` to `e2e` in 0.3.0 (old `--no-appium` CLI flag kept as a deprecated alias for `--no-e2e`). testTag selectors via TestTagAutomation resource-ids. No in-file markers except the docs sections; toggled by deleting qa/e2e."
     },
     "inspector": {
       "enabledByDefault": true,
@@ -100,15 +101,17 @@
     "dev-client": {
       "enabledByDefault": true,
       "paths": [
-        "composeApp/src/desktopMain",
+        "composeApp/src/desktopMain/kotlin/com/example/app/main.kt",
+        "composeApp/src/desktopMain/kotlin/com/example/app/di/DesktopModule.kt",
         "docs/dev-client.md"
       ],
-      "notes": "Desktop dev-client: a jvm(\"desktop\") target inside composeApp running the shared commonMain UI in a phone-sized JVM window (main.kt: __APP_NAME__ dev-client, 411x891dp), with Compose Hot Reload 1.1.1 attached (task hotRunDesktop; plain run task needs no JBR). GitLive Firebase 2.1.0 publishes JVM artifacts so commonMain deps resolve for the desktop target, but the dev-client NEVER initializes/contacts Firebase — desktopMain DI (DesktopModule.kt) binds only NetworkMonitor (always-online) + Room (BundledSQLiteDriver into the OS temp dir); the example ItemRepositoryImpl is in-memory on every platform. When off: delete the desktopMain dir + docs/dev-client.md AND strip the `dev-client` marker blocks in build.gradle.kts (hot-reload plugin apply false), settings.gradle.kts (foojay-resolver-convention for JBR auto-provisioning), composeApp/build.gradle.kts (hot-reload plugin, jvm(\"desktop\") target, desktopMain deps, kspDesktop room.compiler row — nested inside the room block, compose.desktop application block). The catalog keeps the declared coordinates by design (declared-but-unused)."
+      "notes": "Desktop dev-client: the hot-reload WINDOW on top of the always-present JVM tier. IMPORTANT (changed 2026-07-06): the jvm(\"desktop\") target, desktopMain deps, platform actuals (NetworkMonitor/DatabaseBuilder/TestTagAutomation .desktop.kt), and the kspDesktop room.compiler row are HARNESS INFRASTRUCTURE and are NOT gated by this feature — the verify lane's unit/conformance/golden/UI tests run on :composeApp:desktopTest in every feature combination. This feature gates only the interactive window: main.kt (411x891dp __APP_NAME__ dev-client window) + DesktopModule.kt (initDesktopKoin), the compose-hot-reload plugin (build.gradle.kts + composeApp/build.gradle.kts markers), the settings.gradle.kts foojay-resolver (JBR auto-provisioning), and the compose.desktop application block. The dev-client NEVER initializes/contacts Firebase — desktop DI binds NetworkMonitor (always-online) + Room (BundledSQLiteDriver into the OS temp dir); the example ItemRepositoryImpl is in-memory on every platform."
     }
   },
   "verify": {
-    "android": "./gradlew :composeApp:assembleDebug",
-    "androidSmoke": "./gradlew :composeApp:installDebug && node qa/appium/run-android-smoke.mjs",
+    "android": "node qa/verify.mjs --profile scaffold",
+    "androidBuildOnly": "./gradlew :composeApp:assembleDebug",
+    "androidSmoke": "./gradlew :composeApp:installDebug && maestro test qa/e2e/smoke.yaml",
     "iosLink": "./gradlew :composeApp:linkDebugFrameworkIosSimulatorArm64",
     "ios": "cd iosApp && export LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 && xcodegen generate && pod install && SIM_UDID=$(xcrun simctl list devices available | grep -Eo '[0-9A-F-]{36}' | head -1) && xcodebuild -workspace iosApp.xcworkspace -scheme iosApp -sdk iphonesimulator -configuration Debug ARCHS=arm64 ONLY_ACTIVE_ARCH=YES EXCLUDED_ARCHS=x86_64 -destination \"id=$SIM_UDID\" build",
     "iosNote": "On Apple Silicon, the KMP embedAndSignAppleFrameworkForXcode prebuild phase produces ONLY the active-arch (arm64) slice of ComposeApp.framework. A `-destination generic/platform=iOS Simulator` build demands a universal arm64+x86_64 binary and FAILS at CreateUniversalBinary. Constrain to arm64 (ARCHS=arm64 EXCLUDED_ARCHS=x86_64) and target a concrete arm64 simulator UDID — matching the linkDebugFrameworkIosSimulatorArm64 gate."

package/template/qa/e2e/README.md

@@ -0,0 +1,29 @@
+# E2E flows — Maestro
+
+Thin device-level smoke: does the real app boot and do the critical journeys work. Behavior
+lives in unit tests; screen behavior in Compose UI Tests; structure in golden trees — keep
+this layer small.
+
+## Setup (one-time)
+
+```bash
+curl -fsSL "https://get.maestro.mobile.dev" | bash   # Apache-2.0, free CLI
+```
+
+## Run
+
+```bash
+# Android: emulator/device attached, debug build installed
+./gradlew :composeApp:installDebug
+maestro test qa/e2e/smoke.yaml
+
+# The verify lane runs this automatically when maestro + a device are present:
+node qa/verify.mjs
+```
+
+## Conventions
+
+- **Selectors by testTag** (`id:` — TestTagAutomation surfaces tags as resource-ids on
+  Android and accessibility ids on iOS); visible text only for content assertions.
+- Every flow cites the spec clauses it verifies (`# SPEC: SHELL-01`).
+- One flow per journey; deterministic start (`clearState: true`).

package/template/qa/e2e/smoke.yaml

@@ -0,0 +1,35 @@
+# E2E smoke — Maestro flow. SPEC: SHELL-01, SHELL-02.
+#
+# Proves the real app boots on a device/emulator and the bottom-nav shell works.
+# Selectors go by testTag (surfaced as resource-ids on Android via TestTagAutomation),
+# falling back to visible text only for content assertions.
+#
+# 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__
+---
+- launchApp:
+    clearState: true
+
+# SPEC: SHELL-01 — the app boots and the first tab renders inside the shell, bottom nav visible.
+# Cold-start after clearState can take longer than a bare assert's default window on a slow/CI
+# emulator (first Compose frame under load). Waiting for the first frame IS the SHELL-01 boot
+# proof, so wait explicitly with a generous budget rather than asserting immediately.
+- extendedWaitUntil:
+    visible:
+      id: "home_title"
+    timeout: 60000
+- assertVisible:
+    id: "app_bottom_nav"
+
+# SPEC: SHELL-02 — switching tabs keeps the shell
+- tapOn: "Profile"
+- assertVisible:
+    id: "profile_title"
+- assertVisible:
+    id: "app_bottom_nav"
+
+# and back
+- tapOn: "Home"
+- assertVisible:
+    id: "home_title"

package/template/qa/evidence/schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "cmp-evidence/1",
+  "title": "create-cmp verify-lane evidence receipt",
+  "type": "object",
+  "required": ["schema", "profile", "verdict", "commit", "steps", "artifacts", "toolVersions", "generatedAt"],
+  "properties": {
+    "schema": { "const": "cmp-evidence/1" },
+    "profile": { "enum": ["scaffold", "local", "ci"] },
+    "verdict": { "enum": ["PASS", "FAIL"] },
+    "commit": {
+      "type": "object",
+      "required": ["sha", "dirty"],
+      "properties": {
+        "sha": { "type": ["string", "null"], "description": "Parent HEAD at run time (the receipt is part of the NEXT commit)" },
+        "dirty": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "inputs": {
+      "type": "object",
+      "description": "Content-hash binding of the receipt to the verified surface (ADR-0005). Absent on receipts predating evidence binding.",
+      "required": ["hash", "fileCount"],
+      "properties": {
+        "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "fileCount": { "type": "number" }
+      }
+    },
+    "steps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "verdict", "durationMs"],
+        "properties": {
+          "name": { "type": "string" },
+          "verdict": { "enum": ["PASS", "FAIL", "SKIP"] },
+          "reason": { "type": "string" },
+          "durationMs": { "type": "number" },
+          "details": { "type": "object" }
+        }
+      }
+    },
+    "artifacts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "sha256"],
+        "properties": {
+          "path": { "type": "string" },
+          "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+        }
+      }
+    },
+    "toolVersions": { "type": "object" },
+    "generatedAt": { "type": "string", "format": "date-time" }
+  }
+}

package/template/qa/golden/home.json

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

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

@@ -0,0 +1,105 @@
+// Shared primitive: a content hash of the "verified surface" — every tracked
+// file whose content can change the verify lane's verdict, minus the lane's
+// own outputs. Both qa/verify.mjs (writes inputs.hash into the receipt) and
+// qa/receipt-check.mjs (recomputes it to test validity) import this module so
+// there is exactly one definition of the surface and the algorithm.
+//
+// See docs/adr/0005-evidence-binding-by-inputs-hash.md for the why.
+
+import { execSync } from "node:child_process";
+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).
+// Principle: every tracked file whose content can change the lane's verdict.
+export const VERIFIED_SURFACE = [
+  "composeApp",
+  "specs",
+  "qa",
+  "gradle/libs.versions.toml",
+  "build.gradle.kts",
+  "settings.gradle.kts",
+  "gradle.properties",
+];
+
+// Paths EXCLUDED even though they fall under an included surface dir above —
+// these are lane OUTPUTS, not inputs. Including them would make the hash
+// depend on the lane's own prior output (or, for qa-artifacts, on binary
+// scratch that is deliberately never committed).
+const EXCLUDED_PREFIXES = ["qa/evidence", "qa-artifacts"];
+
+function isExcluded(relPath) {
+  return EXCLUDED_PREFIXES.some((prefix) => relPath === prefix || relPath.startsWith(`${prefix}/`));
+}
+
+function tryGitLsFiles(root) {
+  try {
+    const out = execSync("git ls-files -z", { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return out.split("\0").filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+// Dependency-free recursive walk, used when git is unavailable (non-git scaffold).
+function walkAllFiles(dir) {
+  const out = [];
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walkAllFiles(p));
+    else if (entry.isFile()) out.push(p);
+  }
+  return out;
+}
+
+// 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) {
+  const gitFiles = tryGitLsFiles(root);
+
+  if (gitFiles) {
+    return gitFiles
+      .map((p) => p.split(path.sep).join("/"))
+      .filter((relPath) => VERIFIED_SURFACE.some((surface) => relPath === surface || relPath.startsWith(`${surface}/`)))
+      .filter((relPath) => !isExcluded(relPath))
+      .filter((relPath) => fs.existsSync(path.join(root, relPath)) && fs.statSync(path.join(root, relPath)).isFile());
+  }
+
+  // Fallback: no git available — walk the surface directories directly so a
+  // non-git scaffold still produces a stable hash.
+  const collected = [];
+  for (const surface of VERIFIED_SURFACE) {
+    const abs = path.join(root, surface);
+    if (!fs.existsSync(abs)) continue;
+    const stat = fs.statSync(abs);
+    if (stat.isFile()) {
+      collected.push(surface);
+    } else if (stat.isDirectory()) {
+      for (const file of walkAllFiles(abs)) {
+        collected.push(path.relative(root, file).split(path.sep).join("/"));
+      }
+    }
+  }
+  return collected.filter((relPath) => !isExcluded(relPath));
+}
+
+/**
+ * Compute the sha256 hash of the verified surface for the project rooted at `root`.
+ * Deterministic: same tree (same file paths + same file bytes) → same hash.
+ * @param {string} root absolute path to the project root
+ * @returns {{ hash: string, fileCount: number }}
+ */
+export function computeInputsHash(root) {
+  const files = [...new Set(resolveSurfaceFiles(root))].sort((a, b) => a.localeCompare(b));
+
+  const overall = createHash("sha256");
+  for (const relPath of files) {
+    const bytes = fs.readFileSync(path.join(root, relPath));
+    const fileSha = createHash("sha256").update(bytes).digest("hex");
+    overall.update(`${relPath}\0${fileSha}\n`);
+  }
+
+  return { hash: overall.digest("hex"), fileCount: files.length };
+}

package/template/qa/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(", ")];
+}