create-cmp-cli 0.4.0 → 0.5.0

package/README.md

@@ -25,7 +25,8 @@ npx create-cmp-cli@latest my-app --name Acme --package com.acme.app --yes --veri
 Deterministic (stamps a frozen, CI-verified template), fully non-interactive with flags, and
 exits non-zero on failure. Every generated project ships its own verify lane — `node qa/verify.mjs`,
 8 gates, evidence receipts — with nothing installed. Agent-readable: [llms.txt](./llms.txt) ·
-[options.schema.json](./options.schema.json).
+[options.schema.json](./options.schema.json). Also answers to `npm create compose-multiplatform`
+and `npm create kmp` — official aliases ([packages/aliases](packages/aliases)) that delegate here.
 
 ## What is this, in plain words
 

package/llms.txt

@@ -12,6 +12,8 @@ npx create-cmp-cli@latest my-app --name Acme --package com.acme.app --yes --veri
 
 Other flags: `--bundle-id`, `--region`, `--theme-prefix`, `--ios/--no-ios`, `--firebase/--no-firebase`, `--auth <email|phone|both|none>`, `--room/--no-room`, `--e2e/--no-e2e`, `--inspector/--no-inspector`, `--dev-client/--no-dev-client`, `--tabs Home:home,Profile:person`, `--target-dir`, `--force`. Subcommands `doctor`, `upgrade`, `clean`, and `verify` work on any KMP project.
 
+Official alias packages (same tool, same flags, same maintainer): `npm create compose-multiplatform@latest my-app` and `npm create kmp@latest my-app` both delegate to create-cmp-cli.
+
 create-cmp is also invokable as a Claude Code plugin (`/plugin marketplace add kvdm-co-pilot/create-cmp`, then `/plugin install create-cmp`) with eight skills and the `cmp-inspector` MCP server. Generated projects self-verify without the plugin installed: `node qa/verify.mjs` runs 8 gates (spec coverage, build, unit tests, conformance, golden trees, token drift, a11y, on-device E2E) and writes a content-hash-bound evidence receipt; a Stop hook and CI both refuse "done" without a fresh PASS receipt.
 
 ## Docs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The AI delivery harness for Kotlin/Compose Multiplatform — a deterministic, non-interactive project generator that scaffolds a green-building app (Android + iOS) in minutes, then holds AI-driven changes to a machine-enforced verify lane with a committed evidence receipt. Installs the `create-cmp` command.",
   "type": "module",
   "bin": {

package/src/bootstrap/checks.mjs

@@ -71,7 +71,11 @@ export const checks = [
   },
   {
     id: "jdk",
-    label: "JDK 17 (Temurin)",
+    // Label states the actual requirement (17+), and detect() reports the
+    // resolved major — previously the row read "JDK 17 (Temurin)" while
+    // happily accepting JDK 21, a label/evidence contradiction that erodes
+    // trust in every other row (field-report finding 2.6).
+    label: "JDK (17+ required)",
     platforms: ["darwin", "linux"],
     detect() {
       const r = probe("javac", ["-version"]);
@@ -80,7 +84,10 @@ export const checks = [
       const m = out.match(/(\d+)(\.\d+)?/);
       const major = m ? parseInt(m[1], 10) : 0;
       if (!out) return { present: false, detail: "not found" };
-      return { present: major >= 17, detail: out.split("\n")[0] };
+      return {
+        present: major >= 17,
+        detail: `resolved major ${major} — ${out.split("\n")[0]}`,
+      };
     },
     installCommand: () =>
       isMac ? "brew install --cask temurin@17" : "sdk install java 17.0.13-tem  # (sdkman)",

package/src/lib/verify.mjs

@@ -66,8 +66,15 @@ export async function runVerify({ projectDir, manifest, config, dryRun = false }
       results.push({ platform: item.platform, command: item.command, code: 0, ran: false });
       continue;
     }
+    const startedAt = Date.now();
     const { code } = await runCommand(item.command, projectDir);
-    results.push({ platform: item.platform, command: item.command, code, ran: true });
+    results.push({
+      platform: item.platform,
+      command: item.command,
+      code,
+      ran: true,
+      durationMs: Date.now() - startedAt,
+    });
     if (code !== 0) green = false;
   }
 
@@ -94,4 +101,20 @@ export function printVerifyVerdict(verdict) {
       ? `\n${colors.green("GREEN — build proven.")}\n`
       : `\n${colors.red("FAIL — build did not go green.")}\n`
   );
+
+  // Machine-readable verdict, one greppable line (field-report finding 2.3):
+  // a verify run can exceed 170k log lines, where "-Werror=" clang flags and
+  // Xcode phase names false-positive naive error greps. Agents anchor on this
+  // marker instead of parsing raw Gradle/xcodebuild output.
+  process.stdout.write(
+    `::create-cmp-verdict::${JSON.stringify({
+      green: verdict.green,
+      results: verdict.results.map((r) => ({
+        platform: r.platform,
+        green: r.code === 0,
+        ran: r.ran,
+        durationMs: r.durationMs ?? null,
+      })),
+    })}\n`
+  );
 }

package/src/scaffold.mjs

@@ -205,6 +205,46 @@ function applyAppNameSlug(projectDir, appName) {
   }
 }
 
+/**
+ * Persist the fully-resolved engine config as `create-cmp.json` in the project
+ * root — the durable spec-of-record (field-report finding 5.5-1 / D6). The
+ * conformance/consistency tooling compares code against whatever this file
+ * currently says, so a hand-edit is a visible spec change rather than drift.
+ * @param {string} projectDir
+ * @param {object} config validated engine config
+ */
+function writeSpecOfRecord(projectDir, config) {
+  let engineVersion = "unknown";
+  try {
+    engineVersion = JSON.parse(
+      fs.readFileSync(path.join(REPO_ROOT, "package.json"), "utf8")
+    ).version;
+  } catch {
+    /* best-effort — never fail the stamp over version metadata */
+  }
+  const record = {
+    schemaVersion: 1,
+    name: config.appName,
+    package: config.package,
+    bundleId: config.iosBundleId,
+    themePrefix: config.themePrefix,
+    region: config.region,
+    platforms: config.platforms,
+    firebase: config.firebase,
+    room: config.room,
+    e2e: config.e2e,
+    inspector: config.inspector,
+    devClient: config.devClient,
+    tabs: config.tabs,
+    engineVersion,
+    stampedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(
+    path.join(projectDir, "create-cmp.json"),
+    JSON.stringify(record, null, 2) + "\n"
+  );
+}
+
 /**
  * Run the full scaffold pipeline.
  * @param {object} config engine config object (CONTRACT)
@@ -231,10 +271,20 @@ export async function scaffold(config, opts = {}) {
 
   const projectDir = path.resolve(config.targetDir);
   if (fs.existsSync(projectDir)) {
+    // Harmless entries must not force `--force`: our own doctor/session
+    // droppings (.claude), VCS metadata, and OS/editor noise. The documented
+    // doctor→create flow used to poison its own target dir this way. Anything
+    // else is real user content and still refuses — naming the offenders so
+    // the caller can decide without an `ls` round-trip.
+    const HARMLESS = new Set([".git", ".claude", ".DS_Store", ".idea", ".vscode"]);
     const entries = fs.readdirSync(projectDir).filter((e) => e !== "." && e !== "..");
-    if (entries.length > 0 && !opts.force) {
+    const blocking = entries.filter((e) => !HARMLESS.has(e) && !e.endsWith(".swp"));
+    if (blocking.length > 0 && !opts.force) {
+      const ignored = entries.filter((e) => !blocking.includes(e));
       throw new Error(
-        `target directory ${projectDir} is not empty (pass force to overwrite)`
+        `target directory ${projectDir} is not empty (pass force to overwrite)\n` +
+          `  Blocking entries: ${blocking.join(", ")}` +
+          (ignored.length > 0 ? `\n  (ignored as harmless: ${ignored.join(", ")})` : "")
       );
     }
   }
@@ -322,6 +372,14 @@ export async function scaffold(config, opts = {}) {
     if (fs.existsSync(abs)) fs.rmSync(abs);
   }
 
+  // Persist the resolved config as the project's spec-of-record. Until now the
+  // config was validated, consumed, and discarded — the only pre-code spec in
+  // the system evaporated at stamp time, so nothing could later answer "was
+  // this app built to its spec?" (tabs ↔ AppTab ↔ smoke consistency, upgrade
+  // intent, re-stamp/resume all need it). Committed with the app; hand-edits
+  // are visible spec changes, not drift.
+  writeSpecOfRecord(projectDir, config);
+
   ok("Scaffold complete.");
 
   // (f) verify gate

package/template/composeApp/build.gradle.kts

@@ -250,7 +250,19 @@ compose.resources {
 
 // >>> cmp:feature room
 room {
-    schemaDirectory("$projectDir/schemas")
+    // Per-target schema directories, NOT one shared dir. With a single directory the
+    // copyRoomSchemas aggregation task requires every target's exported schema to be
+    // byte-identical — and the first entity edit after scaffold trips a cross-target
+    // checksum conflict against the stale intermediate of whichever target built last
+    // ("Inconsistency detected exporting Room schema files"). Per-target locations are
+    // exactly what that error's remediation asks for.
+    schemaDirectory("android", "$projectDir/schemas/android")
+    schemaDirectory("desktop", "$projectDir/schemas/desktop")
+    // >>> cmp:feature ios
+    schemaDirectory("iosSimulatorArm64", "$projectDir/schemas/iosSimulatorArm64")
+    schemaDirectory("iosX64", "$projectDir/schemas/iosX64")
+    schemaDirectory("iosArm64", "$projectDir/schemas/iosArm64")
+    // <<< cmp:feature ios
 }
 // <<< cmp:feature room
 

package/template/composeApp/src/commonMain/kotlin/com/example/app/core/format/Format.kt

@@ -0,0 +1,36 @@
+package __PACKAGE__.core.format
+
+/**
+ * KMP-safe formatting helpers.
+ *
+ * `String.format` / `"%02d".format(...)` are JVM-only — they compile in `androidMain` but do
+ * not exist in `commonMain`, and reaching for them is the single most common first-week
+ * porting mistake in a shared module. These cover the cases that actually come up; add here
+ * rather than sprinkling `padStart` call sites.
+ */
+
+/** Pad an Int to two digits: 7 -> "07". The `%02d` you were about to write. */
+fun pad2(n: Int): String = n.toString().padStart(2, '0')
+
+/** "HH:mm" from minutes-since-midnight: 555 -> "09:15". */
+fun clockLabel(minutesOfDay: Int): String {
+    val m = ((minutesOfDay % (24 * 60)) + 24 * 60) % (24 * 60) // wrap + never negative
+    return "${pad2(m / 60)}:${pad2(m % 60)}"
+}
+
+/**
+ * Fixed decimal places without java.text: 12.5 -> "12.5" (1 dp). Rounds half away from zero
+ * via floor(abs + 0.5) — deterministic on every backend (kotlin.math.round's tie behavior and
+ * `%.Nf` locale handling both vary). For layout-stable numeric UI text, not accounting math.
+ */
+fun fixed(value: Double, decimals: Int = 1): String {
+    require(decimals >= 0) { "decimals must be >= 0" }
+    var factor = 1L
+    repeat(decimals) { factor *= 10 }
+    val scaled = kotlin.math.floor(kotlin.math.abs(value) * factor + 0.5).toLong()
+    val sign = if (value < 0 && scaled != 0L) "-" else ""
+    if (decimals == 0) return "$sign$scaled"
+    val whole = scaled / factor
+    val frac = (scaled % factor).toString().padStart(decimals, '0')
+    return "$sign$whole.$frac"
+}

package/template/composeApp/src/commonTest/kotlin/com/example/app/core/format/FormatTest.kt

@@ -0,0 +1,36 @@
+package __PACKAGE__.core.format
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class FormatTest {
+
+    @Test
+    fun pad2_pads_single_digits() {
+        assertEquals("07", pad2(7))
+        assertEquals("00", pad2(0))
+        assertEquals("15", pad2(15))
+    }
+
+    @Test
+    fun clockLabel_formats_minutes_of_day() {
+        assertEquals("09:15", clockLabel(9 * 60 + 15))
+        assertEquals("00:00", clockLabel(0))
+        assertEquals("23:59", clockLabel(23 * 60 + 59))
+        // wraps past midnight and never goes negative
+        assertEquals("00:30", clockLabel(24 * 60 + 30))
+        assertEquals("23:30", clockLabel(-30))
+    }
+
+    @Test
+    fun fixed_renders_stable_decimals() {
+        // Binary-exact inputs only — 0.1-style values are not representable and would make
+        // these assertions depend on the platform's double formatting.
+        assertEquals("12.5", fixed(12.5, 1))
+        assertEquals("0.3", fixed(0.25, 1)) // half rounds away from zero
+        assertEquals("-0.8", fixed(-0.75, 1))
+        assertEquals("3.00", fixed(3.0, 2))
+        assertEquals("13", fixed(12.5, 0))
+        assertEquals("0.0", fixed(0.0, 1))
+    }
+}

package/template/composeApp/src/desktopTest/kotlin/com/example/app/conformance/ArchitectureConformanceTest.kt

@@ -27,22 +27,47 @@ class ArchitectureConformanceTest {
     private fun imports(file: File): List<String> =
         file.readLines().filter { it.trimStart().startsWith("import ") }.map { it.trim() }
 
+    /**
+     * Source lines with comment lines stripped. Layer-boundary rules scan these for BOTH
+     * `import x.y.` statements AND fully-qualified inline references (`x.y.Type(...)`) —
+     * import-only matching leaves a one-edit evasion open: delete the import, qualify the
+     * name inline, and the gate goes green while the violation remains.
+     */
+    private fun nonCommentLines(file: File): List<String> =
+        file.readLines().filterNot {
+            val t = it.trimStart()
+            t.startsWith("//") || t.startsWith("*") || t.startsWith("/*")
+        }
+
+    private fun bannedReference(file: File, banned: List<String>): Boolean =
+        nonCommentLines(file).any { line -> banned.any { line.contains(it) } }
+
     private fun under(file: File, segment: String): Boolean =
         file.path.replace(File.separatorChar, '/').contains("/$segment/")
 
+    /**
+     * True when the file sits in a feature subpackage (presentation/<feature>/…) rather than
+     * at the presentation root (App.kt) — the scope for the composable-file rules.
+     */
+    private fun inPresentationFeatureDir(file: File): Boolean {
+        val rel = file.path.replace(File.separatorChar, '/').substringAfter("/presentation/", "")
+        return rel.isNotEmpty() && rel.contains('/')
+    }
+
     private fun violation(clause: String, rule: String, offenders: List<String>, fix: String): String =
         "[$clause] $rule\n  Offending: ${offenders.joinToString("\n             ")}\n  Fix: $fix"
 
     // SPEC: ARCH-01
     @Test
-    fun `ARCH-01 presentation never imports the data layer`() {
+    fun `ARCH-01 presentation never references the data layer`() {
         val offenders = sources(commonMain)
             .filter { under(it, "presentation") }
-            .filter { file -> imports(file).any { it.startsWith("import __PACKAGE__.data.") } }
+            .filter { bannedReference(it, listOf("__PACKAGE__.data.")) }
             .map { it.path }
         if (offenders.isNotEmpty()) fail(
             violation(
-                "ARCH-01", "presentation depends on domain only — it never imports the data layer.",
+                "ARCH-01", "presentation depends on domain only — it never references the data layer " +
+                    "(neither imports nor fully-qualified inline names).",
                 offenders,
                 "depend on a domain interface (domain/repository) and let di/ wire the data implementation.",
             )
@@ -53,16 +78,17 @@ class ArchitectureConformanceTest {
     @Test
     fun `ARCH-02 domain is pure - no app layers, no frameworks`() {
         val banned = listOf(
-            "import __PACKAGE__.presentation.", "import __PACKAGE__.data.", "import __PACKAGE__.di.",
-            "import androidx.compose.", "import org.koin.",
+            "__PACKAGE__.presentation.", "__PACKAGE__.data.", "__PACKAGE__.di.",
+            "androidx.compose.", "org.koin.",
         )
         val offenders = sources(commonMain)
             .filter { under(it, "domain") }
-            .filter { file -> imports(file).any { imp -> banned.any { imp.startsWith(it) } } }
+            .filter { bannedReference(it, banned) }
             .map { it.path }
         if (offenders.isNotEmpty()) fail(
             violation(
-                "ARCH-02", "domain imports nothing app-internal and no UI/DI frameworks.",
+                "ARCH-02", "domain references nothing app-internal and no UI/DI frameworks " +
+                    "(neither imports nor fully-qualified inline names).",
                 offenders,
                 "move framework-touching code out to presentation/data; domain stays pure Kotlin.",
             )
@@ -88,17 +114,23 @@ class ArchitectureConformanceTest {
 
     // SPEC: ARCH-04
     @Test
-    fun `ARCH-04 every Screen composable declares a testTag`() {
+    fun `ARCH-04 every feature composable file declares a testTag`() {
+        // Scoped by CONTENT (contains @Composable), not by *Screen.kt filename: real apps
+        // split features into Screen.kt (often ViewModel-only) and Content.kt (the UI).
+        // Filename scoping produced both false negatives (untagged FooContent.kt slid
+        // through) and false positives (VM-only FooScreen.kt was flagged) in the field.
         val offenders = sources(commonMain)
-            .filter { it.name != "Screen.kt" && it.name.endsWith("Screen.kt") }
-            .filterNot { under(it, "components") || under(it, "navigation") }
+            .filter { inPresentationFeatureDir(it) }
+            .filterNot { under(it, "components") || under(it, "navigation") || under(it, "theme") }
+            .filter { it.readText().contains("@Composable") }
             .filterNot { it.readText().contains("testTag") }
             .map { it.path }
         if (offenders.isNotEmpty()) fail(
             violation(
-                "ARCH-04", "every screen is automation-reachable: *Screen files declare at least one testTag.",
+                "ARCH-04", "every feature UI file is automation-reachable: files containing a " +
+                    "@Composable declare at least one testTag.",
                 offenders,
-                "add Modifier.semantics { testTag = \"<feature>_<element>\" } to the screen's key nodes.",
+                "add Modifier.semantics { testTag = \"<feature>_<element>\" } to the file's key nodes.",
             )
         )
     }
@@ -120,6 +152,45 @@ class ArchitectureConformanceTest {
         )
     }
 
+    // SPEC: SHELL-05
+    @Test
+    fun `SHELL-05 every non-shell nav destination wraps its content in BaseScreen`() {
+        // SHELL-03 bans direct inset-API calls, but a destination that simply never handles
+        // insets at all (bare Column at the nav layer) passes that rule while rendering
+        // under the status bar. Tab screens are exempt — AppShell wraps them — so the rule
+        // targets exactly the destinations registered directly on the NavHost.
+        val navHost = sources(commonMain).firstOrNull { it.name == "AppNavHost.kt" } ?: return
+        val text = navHost.readText()
+        val screenCall = Regex("""([A-Z][A-Za-z0-9]*Screen)\s*\(""")
+        // A call with only a trailing lambda has no paren — `BaseScreen { … }` — so match both.
+        val baseScreenCall = Regex("""BaseScreen\s*[({]""")
+        val allSources = sources(commonMain)
+
+        val offenders = mutableListOf<String>()
+        val chunks = text.split("composable(").drop(1)
+        for (chunk in chunks) {
+            if (chunk.contains("AppShell(")) continue // shell destination: tabs inherit BaseScreen
+            for (m in screenCall.findAll(chunk)) {
+                val name = m.groupValues[1]
+                if (name == "BaseScreen") continue
+                val defining = allSources.firstOrNull { f ->
+                    Regex("""fun\s+$name\s*\(""").containsMatchIn(f.readText())
+                } ?: continue
+                if (!baseScreenCall.containsMatchIn(defining.readText())) {
+                    offenders.add("${defining.path} ($name is a NavHost destination without BaseScreen)")
+                }
+            }
+        }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "SHELL-05", "every screen registered directly on the NavHost composes inside " +
+                    "BaseScreen — otherwise it renders edge-to-edge with no inset handling.",
+                offenders.distinct(),
+                "wrap the destination's content in BaseScreen { … } (see DetailScreen).",
+            )
+        )
+    }
+
     // SPEC: SHELL-03
     @Test
     fun `SHELL-03 insets are owned by BaseScreen - screens never touch inset APIs`() {

package/template/specs/app-base.spec.md

@@ -5,15 +5,19 @@
 
 ## Architecture invariants
 
-- **ARCH-01** — Given any file in `presentation`, When its imports are inspected, Then none
-  resolve into the `data` layer (presentation depends on domain only).
-- **ARCH-02** — Given any file in `domain`, When its imports are inspected, Then none resolve
-  into `presentation`, `data`, or `di`, and none import Compose, Koin, or platform types
-  (domain is pure Kotlin).
+- **ARCH-01** — Given any file in `presentation`, When its imports **and fully-qualified
+  inline references** are inspected, Then none resolve into the `data` layer (presentation
+  depends on domain only; qualifying the name inline instead of importing is the same
+  violation).
+- **ARCH-02** — Given any file in `domain`, When its imports **and fully-qualified inline
+  references** are inspected, Then none resolve into `presentation`, `data`, or `di`, and
+  none reference Compose, Koin, or platform types (domain is pure Kotlin).
 - **ARCH-03** — Given any ViewModel class, When the test sources are inspected, Then a
   corresponding `*ViewModelTest` exists (no untested presentation state).
-- **ARCH-04** — Given any file containing a `*Screen` composable, When its source is
-  inspected, Then it declares at least one `testTag` (every screen is automation-reachable).
+- **ARCH-04** — Given any file in a `presentation` feature package that contains a
+  `@Composable` function, When its source is inspected, Then it declares at least one
+  `testTag` (scoped by content, not `*Screen.kt` filename — split `Content.kt` UI files are
+  covered, ViewModel-only files are exempt).
 - **ARCH-05** — Given any file outside `presentation/theme`, When its source is inspected,
   Then it constructs no literal `Color(0x…)` values (design colors come from the token
   catalog).
@@ -28,3 +32,7 @@
   the safe-area insets owned by `BaseScreen` (edge-to-edge without overlap).
 - **SHELL-04** — Given the app renders any screen, When interactive elements are present,
   Then each is perceivable by automation: it exposes a testTag, text, or content description.
+- **SHELL-05** — Given any screen registered directly on the NavHost (not a shell tab), When
+  it renders, Then its content is composed inside `BaseScreen` — a bare destination that
+  never touches inset APIs still renders under the status bar, which SHELL-03 alone cannot
+  catch.