create-cmp-cli 0.14.0 → 0.15.0

package/packages/harness/src/lib/inputs-hash.mjs

@@ -5,7 +5,7 @@
 // there is exactly one definition of the surface and the algorithm.
 //
 // SINGLE SOURCE OF TRUTH: packages/receipts/src/inputs-hash.mjs in the
-// create-cmp repo (the `cmp-receipts` package). The copy in a generated
+// create-cmp repo (the `@create-cmp/receipts` package). The copy in a generated
 // project's qa/lib/ is vendored byte-identical at scaffold time and pinned by
 // test/receipts-parity.test.mjs — edit the package source, then run
 // `node scripts/sync-harness.mjs`.

package/packages/harness/src/lib/receipt-validate.mjs

@@ -6,7 +6,7 @@
 // tarball rather than the working tree.
 //
 // SINGLE SOURCE OF TRUTH: packages/receipts/src/receipt-validate.mjs in the
-// create-cmp repo (the `cmp-receipts` package). The copy in a generated
+// create-cmp repo (the `@create-cmp/receipts` package). The copy in a generated
 // project's qa/lib/ is vendored byte-identical at scaffold time and pinned by
 // test/receipts-parity.test.mjs — edit the package source, then run
 // `node scripts/sync-harness.mjs`.

package/packages/harness/src/receipt-check.mjs

@@ -39,7 +39,7 @@ function readStdinJson() {
 }
 
 // The predicate itself lives in qa/lib/receipt-validate.mjs (vendored from the
-// cmp-receipts package — one definition everywhere a receipt is judged); this
+// @create-cmp/receipts package — one definition everywhere a receipt is judged); this
 // CLI only reads the receipt and frames the exit codes.
 function evaluate() {
   const receipt = readReceipt(ROOT);

package/packages/harness/src/verify.mjs

@@ -93,6 +93,14 @@ Flags:
                                   with --profile ci (or release) it runs
                                   inside the lane and lands on the receipt.
                                   Never combinable with --fast
+  --no-journal                   skip the qa/flight-recorder.jsonl append.
+                                  qa/watch.mjs passes this on every
+                                  save-triggered run: journalling each save
+                                  would add hundreds of committed lines a day
+                                  and leave a permanently dirty tree inside
+                                  the loop the recorder exists to observe. The
+                                  gap is disclosed in the retrospective's own
+                                  output
   --json                         print the receipt as JSON instead of the
                                   human-readable step-by-step log
   --help, -h                     print this usage and exit 0 without
@@ -116,7 +124,13 @@ if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
   process.exit(0);
 }
 
-const RECOGNIZED_FLAGS = new Set(["--profile", "--json", "--fast", "--determinism"]);
+// Every flag this file CONSUMES must be listed here, or the strict check below
+// rejects it. `--no-journal` was consumed but unlisted in 0.13.0, which meant
+// qa/watch.mjs — whose spawn passes exactly these flags — exited 2 on every
+// save without ever running the lane. test/verify-flags.test.mjs now pins
+// consumed ⊆ recognized and watch's spawn ⊆ recognized so the class cannot
+// recur.
+const RECOGNIZED_FLAGS = new Set(["--profile", "--json", "--fast", "--determinism", "--no-journal"]);
 for (let i = 0; i < rawArgs.length; i += 1) {
   const arg = rawArgs[i];
   if (arg === "--profile") {

package/packages/receipts/package.json

@@ -1,7 +1,7 @@
 {
-  "name": "cmp-receipts",
+  "name": "@create-cmp/receipts",
   "version": "0.1.0",
-  "description": "Validate create-cmp evidence receipts: inputs-hash recompute, receipt-vs-tree binding, freshness, and execution-plausibility. Dependency-free ESM — the single source of truth vendored into every generated project's qa/lib/ and consumed by the hosted receipt check.",
+  "description": "Validate create-cmp evidence receipts: inputs-hash recompute, receipt-vs-tree binding, freshness, and execution-plausibility. Dependency-free ESM \u2014 the single source of truth vendored into every generated project's qa/lib/ and consumed by the hosted receipt check.",
   "type": "module",
   "main": "src/index.mjs",
   "exports": {
@@ -14,7 +14,8 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "prepublishOnly": "npm test"
   },
   "engines": {
     "node": ">=18"
@@ -32,5 +33,12 @@
     "type": "git",
     "url": "git+https://github.com/kvdm-co-pilot/create-cmp.git",
     "directory": "packages/receipts"
+  },
+  "homepage": "https://github.com/kvdm-co-pilot/create-cmp/tree/main/packages/receipts#readme",
+  "bugs": {
+    "url": "https://github.com/kvdm-co-pilot/create-cmp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/packages/receipts/src/index.mjs

@@ -1,4 +1,4 @@
-// cmp-receipts — validate create-cmp evidence receipts.
+// @create-cmp/receipts — validate create-cmp evidence receipts.
 // Single source of truth for the inputs-hash algorithm and the receipt
 // predicate; vendored byte-identical into every generated project's qa/lib/
 // and consumed by hosted validators. Dependency-free ESM.

package/packages/receipts/src/inputs-hash.mjs

@@ -5,7 +5,7 @@
 // there is exactly one definition of the surface and the algorithm.
 //
 // SINGLE SOURCE OF TRUTH: packages/receipts/src/inputs-hash.mjs in the
-// create-cmp repo (the `cmp-receipts` package). The copy in a generated
+// create-cmp repo (the `@create-cmp/receipts` package). The copy in a generated
 // project's qa/lib/ is vendored byte-identical at scaffold time and pinned by
 // test/receipts-parity.test.mjs — edit the package source, then run
 // `node scripts/sync-harness.mjs`.

package/packages/receipts/src/receipt-validate.mjs

@@ -6,7 +6,7 @@
 // tarball rather than the working tree.
 //
 // SINGLE SOURCE OF TRUTH: packages/receipts/src/receipt-validate.mjs in the
-// create-cmp repo (the `cmp-receipts` package). The copy in a generated
+// create-cmp repo (the `@create-cmp/receipts` package). The copy in a generated
 // project's qa/lib/ is vendored byte-identical at scaffold time and pinned by
 // test/receipts-parity.test.mjs — edit the package source, then run
 // `node scripts/sync-harness.mjs`.

package/src/commands/attach.mjs

@@ -0,0 +1,250 @@
+// `create-cmp attach` — M0a: the agent contract for an EXISTING Compose/KMP
+// repo that create-cmp never scaffolded (docs/features/attach-mode.md is the
+// design of record; LADDER §R5).
+//
+// The honesty constraint IS the design: a foreign repo carries none of the
+// stamped machinery our discovery surfaces normally point at, so attach
+// writes ONLY surfaces that are true in any Compose/KMP repo — the engine's
+// own doctor/upgrade at the toolchain walls, and an advisory SessionStart
+// context that says plainly what is and is not wired here. Previews, the
+// lane, and enforcement are named as NOT wired (M0b's staged scope), never
+// faked. Files are never clobbered: an existing differing file keeps its
+// bytes and our content lands beside it as `*.cmp-new` (the same sidecar
+// convention as `upgrade --harness` and `harden`).
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { colors, ok, warn, fail } from "../lib/log.mjs";
+import { consent } from "../bootstrap/exec.mjs";
+import { sessionStartCommand } from "../lib/hooks.mjs";
+import { SIDECAR_SUFFIX } from "../lib/harness-upgrade.mjs";
+
+const COMPOSE_SIGNALS = [
+  "org.jetbrains.compose",
+  'kotlin("multiplatform")',
+  "org.jetbrains.kotlin.multiplatform",
+  "org.jetbrains.kotlin.plugin.compose",
+];
+
+/** SessionStart context for an attached repo. No apostrophes (shell-quoted). */
+export const ATTACH_SESSION_CONTEXT =
+  "This Compose/KMP repo carries the create-cmp attach surfaces: AGENTS.md maps " +
+  "toolchain walls to zero-consent commands (doctor diagnoses machine AND project, " +
+  "upgrade diffs against a proven-green version set). No verify lane, previews, or " +
+  "inspector are wired here — do not assume create-cmp scaffold machinery exists in " +
+  "this repo. A new app scaffolded with npx create-cmp-cli would carry all of it.";
+
+/** The attach rendering of the symptom table — only rows true in ANY Compose/KMP repo. */
+export function attachAgentsMd() {
+  return `# Agent instructions
+
+This is an existing Compose/KMP repository with the create-cmp **attach surfaces**
+installed: discovery for the walls every KMP build eventually hits. It was NOT
+scaffolded by create-cmp — none of the generated-project machinery (verify lane,
+headless previews, live inspector, generators) is wired here.
+
+## Stuck? Symptom → command
+
+Both commands run from the repo root with nothing to install — \`npx\` fetches on demand.
+
+| Symptom | Run |
+|---|---|
+| Build broken, toolchain suspect | \`npx create-cmp-cli doctor --fix\` — diagnoses machine AND project (kotlin↔ksp lockstep, catalog drift); asks before any repair |
+| Dependency versions stale or mismatched | \`npx create-cmp-cli upgrade --dry-run\` — diff against the next proven-green set before touching anything |
+
+Famous build failures (kotlin↔KSP mismatch, the KSP2/iOS catch-22, \`SDK location not
+found\`, \`No space left on device\`): \`doctor\` diagnoses all of them offline; the worked
+write-ups live upstream at
+<https://github.com/kvdm-co-pilot/create-cmp/tree/main/docs/errors>.
+
+## What is NOT wired here
+
+A create-cmp-scaffolded app additionally carries device-free screen previews (structure
+for the agent, pixels for the human), a live on-device inspector, feature generators,
+and a verify lane with evidence receipts and a machine-checked definition of done. Those
+surfaces presuppose scaffold machinery this repo does not have; attach does not fake
+them. To see the full contract, scaffold with \`npx create-cmp-cli@latest\`.
+`;
+}
+
+function attachSettings() {
+  return (
+    JSON.stringify(
+      {
+        hooks: {
+          SessionStart: [
+            {
+              matcher: "",
+              hooks: [{ type: "command", command: sessionStartCommand(ATTACH_SESSION_CONTEXT) }],
+            },
+          ],
+        },
+      },
+      null,
+      2
+    ) + "\n"
+  );
+}
+
+/**
+ * Classify the target directory. Pure; returns {ok:true} or {ok:false, reason}.
+ */
+export function classifyTarget(projectDir) {
+  if (fs.existsSync(path.join(projectDir, "create-cmp.json"))) {
+    return {
+      ok: false,
+      reason:
+        "this is a create-cmp-stamped app (create-cmp.json present). Attach is for repos " +
+        "create-cmp never scaffolded — use `create-cmp harden` (minimal → full) or " +
+        "`create-cmp upgrade --harness` (refresh) here instead.",
+    };
+  }
+  const hasGradleSettings =
+    fs.existsSync(path.join(projectDir, "settings.gradle.kts")) ||
+    fs.existsSync(path.join(projectDir, "settings.gradle"));
+  if (!hasGradleSettings) {
+    return {
+      ok: false,
+      reason: "no settings.gradle(.kts) — attach targets an existing Gradle Compose/KMP project.",
+    };
+  }
+  // A Compose/KMP signal anywhere in the repo's build files (two levels deep
+  // covers the conventional module layout without a full tree walk).
+  const buildFiles = [];
+  const collect = (dir, depth) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name === "build" || e.name.startsWith(".")) continue;
+      const abs = path.join(dir, e.name);
+      if (e.isDirectory() && depth > 0) collect(abs, depth - 1);
+      else if (/^build\.gradle(\.kts)?$|^libs\.versions\.toml$/.test(e.name)) buildFiles.push(abs);
+    }
+  };
+  collect(projectDir, 2);
+  collect(path.join(projectDir, "gradle"), 1);
+  const signals = buildFiles.some((f) => {
+    try {
+      const src = fs.readFileSync(f, "utf8");
+      return COMPOSE_SIGNALS.some((s) => src.includes(s));
+    } catch {
+      return false;
+    }
+  });
+  if (!signals) {
+    return {
+      ok: false,
+      reason:
+        "no Compose/KMP signal found in the build files (looked for the Compose or Kotlin " +
+        "Multiplatform plugins). Attach only claims to help Compose/KMP repos.",
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Plan (and optionally write) the attach surfaces. Testable core: no exit, no
+ * prompt. Each unit lands as one of: current | written | sidecar.
+ * @param {object} params
+ * @param {string} params.projectDir
+ * @param {boolean} [params.apply=false]
+ * @returns {{units: Array<{relPath:string, action:string}>, notWired: string[]}}
+ */
+export function attachProject({ projectDir, apply = false }) {
+  const target = classifyTarget(projectDir);
+  if (!target.ok) throw new Error(target.reason);
+
+  const files = [
+    { relPath: "AGENTS.md", content: attachAgentsMd() },
+    { relPath: ".claude/settings.json", content: attachSettings() },
+  ];
+  const units = [];
+  for (const { relPath, content } of files) {
+    const abs = path.join(projectDir, relPath);
+    if (fs.existsSync(abs)) {
+      const current = fs.readFileSync(abs, "utf8");
+      if (current === content) {
+        units.push({ relPath, action: "current" });
+        continue;
+      }
+      if (apply) {
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs + SIDECAR_SUFFIX, content);
+      }
+      units.push({ relPath, action: "sidecar" });
+      continue;
+    }
+    if (apply) {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, content);
+    }
+    units.push({ relPath, action: "written" });
+  }
+
+  return {
+    units,
+    notWired: [
+      "headless screen previews (PreviewRegistry + renderScreens) — staged M0b, needs a per-repo Gradle wiring design",
+      "live on-device inspector — ships with scaffolded apps; not injectable into a foreign build yet",
+      "verify lane / evidence receipts / enforcement — the lane addresses the stamped layout by name",
+    ],
+  };
+}
+
+/**
+ * `create-cmp attach [dir] [--dry-run] [--yes]`
+ */
+export async function runAttach(flags, positional) {
+  const targetDir =
+    (typeof flags["target-dir"] === "string" && flags["target-dir"]) || positional || ".";
+  const projectDir = path.resolve(targetDir);
+
+  process.stdout.write(
+    `\n${colors.bold("create-cmp attach")} — agent contract for an existing Compose/KMP repo\n` +
+      `  project: ${colors.cyan(projectDir)}\n\n`
+  );
+
+  let plan;
+  try {
+    plan = attachProject({ projectDir, apply: false });
+  } catch (e) {
+    fail(e.message);
+    process.exit(1);
+  }
+
+  for (const u of plan.units) {
+    if (u.action === "current") ok(`${u.relPath} — already current`);
+    if (u.action === "written") process.stdout.write(`  will write ${u.relPath}\n`);
+    if (u.action === "sidecar")
+      warn(`${u.relPath} exists and differs — ours will land as ${u.relPath}${SIDECAR_SUFFIX}`);
+  }
+  process.stdout.write(`\n${colors.bold("Not wired")} (staged, never faked):\n`);
+  for (const n of plan.notWired) process.stdout.write(`  · ${n}\n`);
+
+  const actionable = plan.units.filter((u) => u.action !== "current");
+  if (actionable.length === 0) {
+    ok("\nNothing to do — attach surfaces are current.");
+    process.exit(0);
+  }
+  if (flags["dry-run"] === true) {
+    process.stdout.write(`\n${colors.yellow("Dry run")} — nothing written.\n`);
+    process.exit(0);
+  }
+  const approved = await consent("\nWrite the attach surfaces?", { assumeYes: flags.yes === true });
+  if (!approved) {
+    process.stdout.write(`${colors.yellow("Not applied")} — re-run with --yes to skip the prompt.\n`);
+    process.exit(0);
+  }
+
+  const applied = attachProject({ projectDir, apply: true });
+  for (const u of applied.units) {
+    if (u.action === "written") ok(`wrote ${u.relPath}`);
+    if (u.action === "sidecar") warn(`wrote ${u.relPath}${SIDECAR_SUFFIX} (yours untouched)`);
+  }
+  process.exit(0);
+}

package/src/commands/create.mjs

@@ -74,6 +74,10 @@ function buildConfigFromFlags(flags, positional) {
     region: typeof flags.region === "string" ? flags.region : "us-central1",
     themePrefix:
       typeof flags["theme-prefix"] === "string" ? flags["theme-prefix"] : pascalFromName(name),
+    // `--minimal` is the Act 1 door (LADDER §2): same app, tests, previews and
+    // advisory hooks, without the verify lane / receipts / governance.
+    // `create-cmp harden` installs the subtraction back.
+    harness: !flagBool(flags, "minimal", false),
     platforms: { android: true, ios },
     firebase: {
       enabled: firebase,
@@ -95,7 +99,7 @@ function buildConfigFromFlags(flags, positional) {
   };
 }
 
-async function interactiveConfig(positional) {
+async function interactiveConfig(positional, flags = {}) {
   let prompts;
   try {
     prompts = (await import("prompts")).default;
@@ -157,6 +161,12 @@ async function interactiveConfig(positional) {
 
   const extras = await prompts(
     [
+      {
+        type: "confirm",
+        name: "harness",
+        message: "Verification harness (verify lane, evidence receipts, machine-checked done)?",
+        initial: flags.minimal !== true, // --minimal pre-answers the interview question
+      },
       { type: "confirm", name: "room", message: "Room local cache?", initial: true },
       { type: "confirm", name: "e2e", message: "E2E test harness (Maestro)?", initial: true },
       {
@@ -193,6 +203,7 @@ async function interactiveConfig(positional) {
     iosBundleId: base.package,
     region: base.region,
     themePrefix: pascalFromName(base.appName),
+    harness: extras.harness,
     platforms: { android: true, ios: base.ios },
     firebase: { enabled: base.firebase, auth, firestore, storage, functions, fcm },
     room: extras.room,
@@ -222,7 +233,7 @@ export async function runCreate(flags, positional) {
 
   const config = nonInteractive
     ? buildConfigFromFlags(flags, positional)
-    : await interactiveConfig(positional);
+    : await interactiveConfig(positional, flags);
 
   const verify = flagBool(flags, "verify", true);