create-cmp-cli 0.11.0 → 0.12.0

package/README.md

@@ -76,7 +76,7 @@ http://127.0.0.1:9500/inspect/remote
 A self-contained page mirrors the running app (~700ms refresh) and **click-to-tap drives the
 real thing** — clicks scale to device pixels and dispatch as taps. This is the "two audiences,
 one app" split at its purest: the human watches and drives real pixels in a browser while the
-agent asserts on the semantics tree (`navigate_and_inspect`, `prove_change`, `db_query`). Use
+agent asserts on the semantics tree (`navigate_and_inspect`, `inspect_tree`, `db_query`). Use
 it to watch an e2e run, demo a feature, or poke at the app without touching the device. No
 install, no CORS, debug builds only — release builds contain none of this code.
 
@@ -161,11 +161,11 @@ Same engine as the CLI, conversational front door. Each skill is a guided flow,
 | `cmp-test` | "Write tests for my app." *Observes* the running app's semantics tree — what's actually on screen, what's tappable, where navigation goes — and derives the regression suite from that. Tests come from rendered reality, not guesses. |
 | `cmp-qa-prep` | "Get my test environment up." Emulator + app install + E2E smoke run, with the gotchas handled. |
 
-Plus the **`cmp-inspector` MCP server** (26 tools) — the machine-readable window into a running
+Plus the **`cmp-inspector` MCP server** (15 tools — deliberately few; two production apps proved a lean surface gets used and a wide one gets ignored) — the machine-readable window into a running
 Compose UI that `cmp-inspect`, `cmp-test`, and the verified dev loop are built on. One tree
 contract, three sources: render a screen headlessly, connect to the live app, or read a device
 via UIAutomator. It also carries the runtime half of the agent's eyes (crashes, logs, DB state —
-`runtime_crashes`, `runtime_logs`, `db_schema`, `db_query`), the human-approval console
+`runtime_crashes`, `runtime_logs`, `db_query`), the human-approval console
 (`approval_status`, §8 below), the console's talk-back channel (`review_comments`,
 `resolve_comment`, §9 below), and the genesis walk's design-language workbench
 (`snapshot_variant`, §8 below).
@@ -313,7 +313,7 @@ scaffolded app carries the whole loop):
 `./gradlew :composeApp:renderScreens && node qa/preview-gallery.mjs`.
 
 **The verified dev loop (the flagship).** For any UI change: snapshot the live tree → make the
-edit → reload → `prove_change` compares before/after structure, token drift, and a11y, and returns
+edit → reload → `preview_diff` compares before/after structure, token drift, and a11y, and returns
 a verdict. The agent doesn't say "I centered the title" — it shows *"title bounds moved, tokens
 unchanged, no a11y regressions: proven clean."*
 
@@ -338,11 +338,13 @@ standalone gate. All of it works on any KMP project.
   generation and mechanical work to sub-agents with self-contained briefs, then **gates every
   hand-off through the verify lane** before accepting it. Nothing is reported done on prose —
   only on a receipt.
-- **The MCP tools** are how any agent *sees*: `inspect_tree`, `get_node`, `assert_token`,
-  `layout_gaps`, `diff_against_design_system`, `find_drift`, `snapshot_save`, `snapshot_diff`,
-  `audit_a11y`, `connect_live`, `navigate_and_inspect`, `render_tree`, `render_screen`,
-  `prove_change`. Structure in, structure out — never pixels in model context. The same eyes
-  extend to runtime behavior (`runtime_crashes`, `runtime_logs`, `db_schema`, `db_query`), to
+- **The MCP tools** are how any agent *sees*: `inspect_tree` (one tree contract — subtree by
+  `testTag`, wireframe rendering, layout-gap reporting as options), `connect_live`
+  (self-healing: device → forward → health → launch → transport reset), `navigate_and_inspect`,
+  `render_screen`, and the preview loop (`preview`, `preview_status`, `preview_diff`).
+  Structure in, structure out — never pixels in model context. Token drift, a11y, and golden
+  regressions are the verify lane's job, not interactive tools. The same eyes
+  extend to runtime behavior (`runtime_crashes`, `runtime_logs`, `db_query`), to
   the human side of the loop (`approval_status`, blocking on a console decision the same way
   `preview_status` blocks on a render), and to the console's talk-back channel
   (`review_comments`, `resolve_comment` — the agent observes feedback and closes the loop with a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Create production mobile apps (Android + iOS, one Kotlin codebase) with AI — the delivery harness for Compose Multiplatform, the current generation of cross-platform (Google-backed KMP, iOS stable since May 2025). A deterministic, non-interactive generator that scaffolds a green-building app in minutes, then holds AI-driven changes to a machine-enforced verify lane with a committed evidence receipt. Every app carries a device-free UI preview loop (real screens rendered headlessly on save; changed-screen attribution and compile-error surfacing for coding agents, a live gallery for humans) plus agent-first docs (CLAUDE.md + AGENTS.md). Installs the `create-cmp` command.",
   "type": "module",
   "bin": {

package/src/lib/package-name.mjs

@@ -0,0 +1,72 @@
+// Semantic validation for the `package` option, beyond what the JSON-schema
+// pattern in options.schema.json can express.
+//
+// The pattern already enforces the SHAPE of a reverse-DNS id (lowercase start,
+// at least two segments, no digit-leading segments). What it cannot encode is
+// that every segment also has to be a legal *Java identifier*: the value
+// becomes the Android namespace and the Kotlin package, and AGP rejects a
+// reserved word outright —
+//
+//   Namespace 'com.final.proof' is not a valid Java package name as 'final'
+//   is a Java keyword
+//
+// Observed for real: `--package com.final.proof` was accepted, stamped a full
+// project, and only failed at the first Gradle configure — late, and as a raw
+// Gradle stack rather than an input error. Refuse it at the door instead, and
+// name the offending segment.
+
+// Java SE reserved words (JLS §3.9), plus the three reserved literals and the
+// lone underscore (reserved since Java 9). `var`/`yield`/`record`/`sealed` and
+// friends are contextual, not reserved — they are legal package segments, so
+// they are deliberately absent.
+export const JAVA_KEYWORDS = new Set([
+  "abstract", "assert", "boolean", "break", "byte", "case", "catch", "char",
+  "class", "const", "continue", "default", "do", "double", "else", "enum",
+  "extends", "final", "finally", "float", "for", "goto", "if", "implements",
+  "import", "instanceof", "int", "interface", "long", "native", "new",
+  "package", "private", "protected", "public", "return", "short", "static",
+  "strictfp", "super", "switch", "synchronized", "this", "throw", "throws",
+  "transient", "try", "void", "volatile", "while",
+  // reserved literals
+  "true", "false", "null",
+  // reserved identifier (Java 9+)
+  "_",
+]);
+
+/**
+ * Segments of `pkg` that cannot be Java identifiers.
+ * @param {string} pkg
+ * @returns {string[]} offending segments, in source order (may repeat)
+ */
+export function reservedSegments(pkg) {
+  if (typeof pkg !== "string" || pkg.length === 0) return [];
+  return pkg.split(".").filter((seg) => JAVA_KEYWORDS.has(seg));
+}
+
+/**
+ * Validate the package id's segments. Same error shape as schema.mjs's
+ * validate(), so callers can merge the two lists and format them together.
+ * @param {string} pkg
+ * @param {string} [path] error path label
+ * @returns {{ valid: boolean, errors: Array<{path: string, message: string}> }}
+ */
+export function validatePackageName(pkg, path = "package") {
+  const bad = reservedSegments(pkg);
+  if (bad.length === 0) return { valid: true, errors: [] };
+  const uniq = [...new Set(bad)];
+  const which = uniq.map((s) => `'${s}'`).join(", ");
+  const lead = uniq.length > 1
+    ? `segments ${which} are Java keywords and cannot be package segments`
+    : `segment ${which} is a Java keyword and cannot be a package segment`;
+  return {
+    valid: false,
+    errors: [
+      {
+        path,
+        message:
+          `${lead} — Gradle will refuse the namespace. Rename it ` +
+          `(e.g. com.final.proof \u2192 com.finalproof).`,
+      },
+    ],
+  };
+}

package/src/scaffold.mjs

@@ -18,6 +18,7 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { validate, formatErrors } from "./lib/schema.mjs";
+import { validatePackageName } from "./lib/package-name.mjs";
 import { buildTokenMap, replaceTokens, replacePathTokens, isBinaryPath, slugifyAppName } from "./lib/tokens.mjs";
 import { renamePackageDirs } from "./lib/rename.mjs";
 import {
@@ -51,8 +52,12 @@ export function loadSchema(opts = {}) {
  */
 export function validateConfig(config, opts = {}) {
   const schema = loadSchema(opts);
-  const { valid, errors } = validate(config, schema);
-  if (!valid) {
+  const { errors } = validate(config, schema);
+  // The schema pattern proves the SHAPE of the package id; this proves its
+  // segments are legal Java identifiers. Merged into one list so a config with
+  // both problems reports both at once.
+  errors.push(...validatePackageName(config?.package).errors);
+  if (errors.length > 0) {
     const err = new Error(`Invalid config:\n${formatErrors(errors)}`);
     err.validationErrors = errors;
     throw err;

package/template/.claude/settings.json

@@ -1,5 +1,35 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"This app is governed by its delivery contract (CLAUDE.md): behavior starts in specs/, done is `node qa/verify.mjs` with a committed receipt, approvals gate signed artifacts. The cmp-inspector MCP tools (preview loop, live tier) are the expected eyes — if they are absent from this session, that is a fault to diagnose (plugin disabled, session predates plugin enablement, or stale plugin copy; see cmp-doctor), not a cue to fall back to screenshots or blind adb.\"}}'"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "grep -qE 'screencap|uiautomator dump' && printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"permissionDecisionReason\":\"Reminder: raw pixels/blind taps lose structure. If cmp-inspector is connected, inspect_tree reads the semantic tree and navigate_and_inspect gives verified taps; if its tools are missing, diagnose first (cmp-doctor, Inspector MCP section).\"}}' || true"
+          },
+          {
+            "type": "command",
+            "command": "grep -qE 'connected[A-Za-z]*AndroidTest|maestro test|adb (-s [^ ]+ )?(install|uninstall)' && printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"permissionDecisionReason\":\"Reminder: device evidence is lane-owned and batched. node qa/verify.mjs sequences the device steps once, last, under a machine-global per-serial lease (qa/lib/device-lease.mjs) — the one device is scarce, slow, and fragile, so device proof is a checkpoint, never an inner loop. Driving it by hand mid-task risks colliding with a running lane (wedged adbd, device offline, false reds, crossed app state). Ad-hoc debugging stays allowed; batch the evidence into the lane.\"}}' || true"
+          },
+          {
+            "type": "command",
+            "command": "in=$(cat); printf '%s' \"$in\" | grep -qE 'node qa/verify\\.mjs' && ! printf '%s' \"$in\" | grep -q -- '--fast' && printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"permissionDecisionReason\":\"Reminder: for inner-loop iteration, node qa/verify.mjs --fast skips the device/release tier (releaseBuild, tokenDrift, e2eSmoke, androidChecks, releaseSmoke) and is much quicker. Run the full lane once, deliberately, before reporting work done — never speculatively, and never to re-confirm a result you already have. A --fast receipt never satisfies the done-gate.\"}}' || true"
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "matcher": "",

package/template/CLAUDE.md

@@ -15,7 +15,10 @@ tests, and gates the whole tree to produce the receipt, so it is slow by design;
 after every edit wastes the minutes it takes. Iterate on the fast tier, and run the lane
 once — when you believe the change is done.
 
-- **Inner loop — run continuously (seconds):** the preview loop (below) for UI, and
+- **Inner loop — run continuously (seconds):** the preview loop (below) for UI;
+  `node qa/watch.mjs` for verification — a resident watcher that re-runs the fast tier
+  (`node qa/verify.mjs --fast`) on every save and re-prints the step table, so the
+  did-I-break-anything signal is free the way an IDE's errors-on-save are free; and
   `./gradlew :composeApp:desktopTest` for the unit tests your change touches. This is where
   you catch your own mistakes.
 - **Checkpoint — run once, at done:** `node qa/verify.mjs`. It writes the receipt; commit
@@ -85,9 +88,25 @@ the tree. The governed `architecture` artifact (below) hashes the document along
 - Never delete, weaken, or `@Ignore` a failing test to reach green. Fix the behavior — or,
   if the test itself is wrong, say so in your summary and justify the change.
 
+**Platform behavior tests live in `composeApp/src/androidInstrumentedTest`** — when a
+feature touches alarms, notifications, lock-screen intents, or audio routing, its behavior
+test goes there, because no desktop tier can see those OS facts. Assertion helpers:
+`NotificationAsserts`, `AlarmAsserts`, `SystemState`. **Runtime state control** — put the
+device into the state your claim is about, instead of waiting for it: `TimeWarp` (clock,
+timezone), `DozeControl` (forced idle), `PermissionControl`, `ProcessControl`,
+`NetworkControl`, `ConfigControl` (dark mode, font scale, per-app locale). They compose —
+the exemplar proves an `allowWhileIdle` alarm delivers from inside forced deep idle by
+nesting a clock warp in a Doze bracket. Exemplars: `PlatformBehaviorSeamTest`,
+`RuntimeStateSeamTest`. Each organ's header states what it does NOT reproduce; read it
+before claiming more than it proves. The lane's `androidChecks` step runs them when a
+device is attached; see `docs/TESTING.md`.
+
 ## Evidence
 
 `node qa/verify.mjs` writes `qa/evidence/latest.json` (schema: `qa/evidence/schema.json`).
+Each PASS receipt names its **evidence rung** (L0 scaffold / L1 desktop / L2 device /
+L3 release), derived from which steps actually ran and passed — never declared, and a
+SKIPped step never upgrades it (see `docs/TESTING.md` §"The evidence ladder").
 Commit it with your change; git history is the audit ledger. Binary artifacts under
 `qa-artifacts/` are hashed into the receipt, never committed. The studio console's Evidence
 page reconstructs the full audit trail from the git log of `latest.json` — every commit is
@@ -305,16 +324,35 @@ and tells you what your edit changed.
 3. `preview_diff { screen }` proves the change in one call: `proven-clean` /
    `changed-with-regressions` / `no-change`. No snapshot bookkeeping.
 
-**Without the plugin:** `./gradlew :composeApp:renderScreens` renders every screen to
-`composeApp/build/previews/<id>/{screen.png, tree.json}` (`-Pscreen=<id>` for one);
-`node qa/preview-gallery.mjs` builds a self-contained gallery page from the output.
+**If the tools are missing:** capability absence is a fault to diagnose and report — never
+a silent fallback. If ToolSearch finds no `cmp-inspector` tools, STOP and tell the human
+which it is: the plugin is disabled (`enabledPlugins` in `~/.claude/settings.json` or the
+project settings); the session predates the plugin's enablement (MCP servers attach at
+session start — restart the session; no in-session retry will surface them); or the plugin
+copy is stale/broken (run cmp-doctor's inspector-MCP check group). Report before degrading.
+
+**Degraded path** — for environments where the plugin is genuinely unavailable (CI, other
+agents), and only after the fault is reported: `./gradlew :composeApp:renderScreens` renders
+every screen to `composeApp/build/previews/<id>/{screen.png, tree.json}` (`-Pscreen=<id>`
+for one); `node qa/preview-gallery.mjs` builds a self-contained gallery page from the
+output. What this loses: on-save re-render, changed-screen attribution, compile errors
+in-band, and the `preview_diff` change proof — structured feedback replaced by pixels.
 
 **Live tier — the human's live device view (standing step).** Whenever `connect_live`
 succeeds, OFFER the `remoteUrl` it returns (`http://127.0.0.1:9500/inspect/remote`) to the
 human — every time, not as a maybe. It is a self-contained browser page that mirrors the
 running app (~700ms refresh) with click-to-tap driving the real device: they watch and drive
-the actual app while you assert on the tree (`navigate_and_inspect` / `prove_change` /
-`db_query`). It is also the right way for a human to *watch* an e2e run.
+the actual app while you assert on the tree (`navigate_and_inspect` — its before/after delta
+is the change proof live — and `inspect_tree`). It is also the right way for a human to
+*watch* an e2e run.
+
+Asserting persisted state: `db_query` reads bounded rows from the running app's database;
+use it when a flow's proof is a row existing (or not) after an action, instead of shelling
+into sqlite or trusting the UI.
+
+When the app crashes or misbehaves on device: `runtime_crashes` returns persisted crashes
+with cause attribution and `runtime_logs` bounded structured logcat for the app's pid; use
+these before hand-grepping `adb logcat`.
 
 Screens come from `inspector/PreviewRegistry.kt` (desktopMain). The `add-feature` and
 `add-screen` stampers auto-register stamped screens at the `// cmp:anchor preview-registry`
@@ -342,8 +380,12 @@ conventions) · [`CONTRIBUTING.md`](./CONTRIBUTING.md) (workflow, Conventional C
 | Command | What |
 |---|---|
 | `node qa/verify.mjs` | The verify lane (profile `local`) — the done checkpoint, run once |
+| `node qa/verify.mjs --fast` | **Inner loop — NOT the done-gate**: skips the device/release tier (`releaseBuild`, `tokenDrift`, `e2eSmoke`, `androidChecks`, `releaseSmoke`), reuses unchanged pure-Node step results (`CACHED`, content-hashed inputs), and scopes unit tests to the working-tree change (broad-impact changes — build files, DI, theme, shared components, `qa/` — run the full suite). Its receipt records `"mode": "fast"`, earns no evidence rung, and the Stop hook refuses it — run the full lane once at done |
+| `node qa/watch.mjs` | **Resident inner loop — never a gate**: watches `composeApp/src`, `specs/`, `qa/` and re-runs `node qa/verify.mjs --fast` on save (debounced — a save storm is one run; defers while a verify lane or a preview render holds the project). `--once` for a single pass, `--json` for line-per-run output. The done-gate stays one deliberate full `node qa/verify.mjs` run |
 | `./gradlew :composeApp:desktopTest` | Unit tests only (fast inner loop) |
 | `node qa/setup-hooks.mjs` | Enable the pre-push receipt gate (one-time, after `git init`) |
 | `./gradlew :composeApp:assembleDebug` | Android debug build |
 | `./gradlew :composeApp:assembleRelease` | Android release build — R8 + `lintVital`, the variant the lane's `releaseBuild` step proves. Produces an **unsigned** APK; signing needs a keystore, which is yours to create and keep out of the repo. |
 | `./gradlew :composeApp:hotRunDesktop --auto` | Desktop dev-client with hot reload |
+| `./gradlew :composeApp:connectedDebugAndroidTest` | Instrumented behavior tests on the attached device (the lane's `androidChecks` step) |
+| `node qa/verify.mjs --profile release` | Ship-time lane: everything `ci` proves plus the release-APK Maestro smoke (`releaseSmoke`) |

package/template/composeApp/build.gradle.kts

@@ -161,6 +161,24 @@ kotlin {
                 implementation(compose.desktop.currentOs)
             }
         }
+
+        // Android INSTRUMENTATION tier (composeApp/src/androidInstrumentedTest) — the one
+        // evidence tier that crosses the process boundary. Everything else in this build is
+        // JVM-side: desktopTest is a JVM, golden trees are structure, the conformance suite
+        // is static analysis, and the Maestro smoke taps UI without asserting anything about
+        // notifications or alarms. Alarms, notification channels, full-screen intents,
+        // PendingIntent identity, and audio routing are OS facts that only exist on a device
+        // — a fully green desktop lane is compatible with an alerting feature that never
+        // alerts. This source set runs via `:composeApp:connectedDebugAndroidTest` (the
+        // lane's `androidChecks` step; SKIPs honestly when no device is attached).
+        //
+        // Its dependencies are declared through AGP's androidTestImplementation
+        // configuration (the dependencies block at the bottom of this file), not here: the
+        // KMP source-set DSL compiles these sources but does not put the androidx.test
+        // artifacts on their classpath.
+        //
+        // No kotlin-test here: instrumented tests run under JUnit4 (AndroidJUnit4), so they
+        // assert with org.junit.Assert — a second assertion vocabulary buys nothing.
     }
 }
 
@@ -174,6 +192,9 @@ android {
         targetSdk = 35
         versionCode = 1
         versionName = "1.0.0"
+        // Instrumentation entry point for the on-device behavior tier
+        // (composeApp/src/androidInstrumentedTest — see the source-set note above).
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
     }
 
     packaging {
@@ -182,6 +203,20 @@ android {
         }
     }
 
+    // AGP resolves BUILD-TYPE source sets at src/<buildType>/, while the Kotlin
+    // Multiplatform plugin only remaps the `main` one to src/androidMain/. Without this
+    // wiring, src/androidDebug/'s manifest and resources are silently never merged —
+    // dead files that look live: the debug network-security config never applied, and a
+    // permission declared there never reached the APK. Point the debug build type at them
+    // explicitly. Caught when an instrumented test asserted canScheduleExactAlarms() and
+    // found the grant it had declared was absent on the device.
+    sourceSets {
+        getByName("debug") {
+            manifest.srcFile("src/androidDebug/AndroidManifest.xml")
+            res.srcDirs("src/androidDebug/res")
+        }
+    }
+
     buildFeatures {
         buildConfig = true
     }
@@ -269,6 +304,15 @@ dependencies {
     add("kspDesktop", libs.room.compiler)
     // <<< cmp:feature room
     add("coreLibraryDesugaring", libs.android.desugar.jdk)
+    // The instrumentation tier's runner, JUnit4 harness, and device helpers. Declared
+    // through AGP's own configuration rather than the KMP androidInstrumentedTest
+    // source-set block — the latter compiles the sources but does not put these
+    // artifacts on their classpath.
+    add("androidTestImplementation", libs.androidx.test.runner)
+    add("androidTestImplementation", libs.androidx.test.core)
+    add("androidTestImplementation", libs.androidx.test.ext.junit)
+    add("androidTestImplementation", libs.androidx.uiautomator)
+    add("androidTestImplementation", libs.junit4)
 }
 
 // Pin the generated resources accessor package so `__PACKAGE__.generated.resources.Res`

package/template/composeApp/src/androidDebug/AndroidManifest.xml

@@ -7,6 +7,15 @@
     <uses-permission android:name="android.permission.INTERNET" />
     <!-- <<< cmp:feature inspector -->
 
+    <!-- The instrumented-tier exact-alarm proof (PlatformBehaviorSeamTest, TimeWarp) needs
+         setExactAndAllowWhileIdle to actually schedule. API 31/32 gate it behind
+         SCHEDULE_EXACT_ALARM, which the system grants by default there; API 33+ gates it
+         behind USE_EXACT_ALARM, granted at install. Neither belongs in the shipped
+         manifest — a real app that wants exact alarms declares that choice itself; this is
+         the test harness's own permission, debug-only. -->
+    <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
+    <uses-permission android:name="android.permission.USE_EXACT_ALARM" />
+
     <application
         android:networkSecurityConfig="@xml/debug_network_security_config"
         android:usesCleartextTraffic="true" />