create-cmp-cli 0.11.0 → 0.13.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/bin/create-cmp.mjs

@@ -71,6 +71,7 @@ function printHelp() {
       `  npx create-cmp create [target-dir]     same, explicit\n` +
       `  npx create-cmp doctor                  toolchain doctor + project diagnosis (any KMP project)\n` +
       `  npx create-cmp upgrade                 migrate to the next proven-green version set\n` +
+      `  npx create-cmp upgrade --harness       refresh engine-owned files of a stamped app (3-way merge)\n` +
       `  npx create-cmp clean                   ~/.konan + Gradle build-output hygiene (consent-gated)\n` +
       `  npx create-cmp verify                  run the green-build gate on an existing project\n\n` +
       `create (scaffold) flags:\n` +
@@ -83,6 +84,8 @@ function printHelp() {
       `  --target-dir  --verify/--no-verify  --yes  --force  --dry-run-verify\n\n` +
       `doctor flags:  --yes  --dry-run  --no-ios  --no-install  --target-dir <dir>  --fix\n` +
       `upgrade flags: --target-dir <dir>  --set <id>  --dry-run  --yes  --verify\n` +
+      `  --harness mode flags: --target-dir <dir>  --base-dir <extracted-template>  --dry-run  --yes\n` +
+      `  (--harness dry-runs by default; conflicts never clobber — they land as *.cmp-new sidecars)\n` +
       `clean flags:   --target-dir <dir>  --dry-run  --yes\n` +
       `verify flags:  --target-dir <dir>  --no-ios  --dry-run\n`
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.11.0",
+  "version": "0.13.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/commands/upgrade.mjs

@@ -17,15 +17,39 @@
 //     `<kotlin>-…`.
 //   - Works on ANY project with a libs.versions.toml — template markers only
 //     soften/strengthen messaging, never refuse.
+//
+// Second mode — `create-cmp upgrade --harness`:
+//
+//   create-cmp upgrade --harness [--target-dir .] [--base-dir <path>] [--dry-run] [--yes]
+//
+//   Refreshes the ENGINE-OWNED files of a stamped app via a three-way merge
+//   (base = old engine's stamp, new = current engine's stamp, theirs = the
+//   app's tree — both stamps use the app's own recorded config from
+//   create-cmp.json so every diff is pure engine change). Conflicts never
+//   clobber: the app's file stays put and a `.cmp-new` sidecar carries the
+//   new engine content. Decision logic lives in src/lib/harness-upgrade.mjs;
+//   this file does the filesystem/CLI orchestration (npm pack of the base
+//   version, temp-dir stamps, consent, backups, report, exit code).
 
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
 
 import { flagBool } from "../lib/args.mjs";
 import { colors, ok, warn, fail, step } from "../lib/log.mjs";
 import { consent } from "../bootstrap/exec.mjs";
 import { loadRegistry, latestSet, getSet } from "../lib/registry.mjs";
 import { planUpgrade, BACKUP_SUFFIX } from "../lib/upgrade.mjs";
+import {
+  planHarnessUpgrade,
+  applyHarnessPlan,
+  configFromSpecRecord,
+  SIDECAR_SUFFIX,
+} from "../lib/harness-upgrade.mjs";
+
+const REPO_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 
 function readIfExists(p) {
   try {
@@ -48,11 +72,274 @@ function printDiffTable(changes) {
   }
 }
 
+// --- harness mode helpers ----------------------------------------------------
+
+/** Current engine version, from this checkout's package.json. */
+function currentEngineVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(REPO_ROOT, "package.json"), "utf8")).version;
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Resolve a --base-dir argument to a template root (the dir holding
+ * manifest.json). Accepts the template root itself, a repo/package checkout
+ * containing `template/`, or an extracted npm tarball (`package/template/`).
+ * Throws (never exits) so the caller's temp-dir cleanup always runs.
+ * @param {string} p
+ * @returns {string} absolute template root
+ */
+function resolveBaseTemplateDir(p) {
+  const abs = path.resolve(p);
+  for (const candidate of [abs, path.join(abs, "template"), path.join(abs, "package", "template")]) {
+    if (fs.existsSync(path.join(candidate, "manifest.json"))) return candidate;
+  }
+  throw new Error(
+    `--base-dir ${abs} does not look like a create-cmp template (no manifest.json at ` +
+      `<dir>, <dir>/template, or <dir>/package/template).`
+  );
+}
+
+/**
+ * Fetch the OLD engine's template by version: `npm pack create-cmp-cli@<v>`
+ * into a temp dir, then extract `package/template/` from the tarball.
+ * Fails loudly (throws — never exits, so the caller's temp-dir cleanup always
+ * runs), naming the exact command that failed and the --base-dir escape hatch
+ * (offline / local checkout / testing).
+ * @param {string} engineVersion version recorded in create-cmp.json
+ * @param {string} tmpRoot session temp dir (cleaned up by the caller)
+ * @returns {string} absolute path of the extracted template root
+ */
+function fetchBaseTemplate(engineVersion, tmpRoot) {
+  if (!engineVersion || engineVersion === "unknown" || !/^[0-9A-Za-z.+-]+$/.test(engineVersion)) {
+    throw new Error(
+      `create-cmp.json does not record a usable engineVersion (got ${JSON.stringify(engineVersion)}). ` +
+        `Pass --base-dir <path> pointing at the template this app was stamped from.`
+    );
+  }
+  const packDir = path.join(tmpRoot, "pack");
+  fs.mkdirSync(packDir, { recursive: true });
+  const packCmd = `npm pack create-cmp-cli@${engineVersion}`;
+  const r = spawnSync("npm", ["pack", `create-cmp-cli@${engineVersion}`], {
+    cwd: packDir,
+    encoding: "utf8",
+    timeout: 120000,
+  });
+  if (r.error || r.status !== 0) {
+    throw new Error(
+      `Could not fetch the base engine template: \`${packCmd}\` failed` +
+        (r.stderr ? ` — ${r.stderr.trim().split("\n").pop()}` : "") +
+        `.\n  Offline or unpublished version? Pass --base-dir <path> to an already-extracted template.`
+    );
+  }
+  // npm pack prints the tarball filename as the last stdout line.
+  const tgz = (r.stdout || "").trim().split("\n").pop().trim();
+  const tgzPath = path.join(packDir, tgz);
+  const tarCmd = `tar -xzf ${tgzPath} -C ${packDir}`;
+  const rt = spawnSync("tar", ["-xzf", tgzPath, "-C", packDir], { timeout: 120000 });
+  if (rt.error || rt.status !== 0 || !fs.existsSync(path.join(packDir, "package", "template", "manifest.json"))) {
+    throw new Error(
+      `Could not extract the base engine template: \`${tarCmd}\` failed or the tarball ` +
+        `carries no package/template/. Pass --base-dir <path> to an already-extracted template.`
+    );
+  }
+  return path.join(packDir, "package", "template");
+}
+
+/** Print the grouped harness report; returns whether anything is actionable. */
+function printHarnessReport(plan) {
+  const c = plan.counts;
+  const list = (bucket) => plan.entries.filter((e) => e.bucket === bucket).map((e) => e.relPath);
+
+  process.stdout.write(
+    `\n${colors.bold("Engine-owned files")} — ` +
+      `${colors.dim(`unchanged ${c.unchanged} · already current ${c.current} · excluded state/secrets ${c.excluded}`)}\n`
+  );
+  const groups = [
+    ["applied", "applied (engine changed, app never touched — will take the new content)", ok],
+    ["merged", "merged (both changed different regions — both edits survive)", ok],
+    ["added", "added (new engine files absent from the app)", ok],
+    ["removed", "removed (engine deleted, app never touched — will be deleted)", warn],
+    ["orphaned", "orphaned (engine deleted these but the app modified them — left in place)", warn],
+    ["conflicted", `conflicted (NEVER clobbered — new engine content lands beside as *${SIDECAR_SUFFIX})`, fail],
+  ];
+  let actionable = 0;
+  for (const [bucket, label, log] of groups) {
+    const files = list(bucket);
+    if (files.length === 0) continue;
+    if (bucket !== "orphaned") actionable += files.length;
+    log(`${colors.bold(String(files.length))} ${label}`);
+    for (const f of files) process.stdout.write(`    ${f}\n`);
+  }
+  process.stdout.write(
+    colors.dim(
+      `\n  Not considered: ${c.excluded} excluded app-state/secret files ` +
+        `(evidence, approvals, goldens, keystores, Firebase configs), and any app-authored ` +
+        `files the engine never stamped.\n`
+    )
+  );
+  return actionable > 0;
+}
+
+/**
+ * `create-cmp upgrade --harness` — refresh engine-owned files of a stamped app.
+ * @param {Record<string,string|boolean>} flags
+ * @param {string|undefined} positional optional target dir positional
+ */
+async function runHarnessUpgrade(flags, positional) {
+  const targetDir =
+    (typeof flags["target-dir"] === "string" && flags["target-dir"]) || positional || ".";
+  const projectDir = path.resolve(targetDir);
+
+  const specPath = path.join(projectDir, "create-cmp.json");
+  const specRaw = readIfExists(specPath);
+  if (specRaw === null) {
+    process.stderr.write(
+      `Error: no create-cmp.json under ${projectDir}.\n` +
+        `\`create-cmp upgrade --harness\` refreshes the engine-owned files of a create-cmp-stamped ` +
+        `project, and needs the spec-of-record the stamp wrote. Run it from the project root or ` +
+        `pass --target-dir. (For a plain version-catalog upgrade, drop --harness.)\n`
+    );
+    process.exit(1);
+  }
+  let record;
+  try {
+    record = JSON.parse(specRaw);
+  } catch (e) {
+    process.stderr.write(`Error: ${specPath} is not valid JSON (${e.message}).\n`);
+    process.exit(1);
+  }
+
+  const baseVersion = record.engineVersion;
+  const currentVersion = currentEngineVersion();
+  process.stdout.write(
+    `\n${colors.bold("create-cmp upgrade --harness")} — refresh engine-owned files\n` +
+      `  project: ${colors.cyan(projectDir)}\n` +
+      `  stamped by engine ${colors.yellow(String(baseVersion))} ${colors.dim("→")} current engine ${colors.green(currentVersion)}\n\n`
+  );
+
+  // NOTE: `process.exit` skips `finally`, so the body below RETURNS an exit
+  // code and the temp trees are cleaned up before the process actually exits.
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "create-cmp-harness-"));
+  let code = 1;
+  try {
+    code = await harnessPlanAndApply({
+      flags,
+      record,
+      projectDir,
+      targetDir,
+      tmpRoot,
+      baseVersion,
+      currentVersion,
+    });
+  } catch (e) {
+    fail(e.message);
+    code = 1;
+  } finally {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  }
+  process.exit(code);
+}
+
+/**
+ * The harness mode's plan/report/apply body. Returns the process exit code
+ * (0 = clean apply or dry run, 1 = conflicts produced) and throws on
+ * environment failures — it never calls process.exit itself, so the caller's
+ * temp-dir cleanup always runs.
+ * @returns {Promise<number>}
+ */
+async function harnessPlanAndApply({ flags, record, projectDir, targetDir, tmpRoot, baseVersion, currentVersion }) {
+  // Base template: --base-dir wins (offline / local checkout / testing);
+  // same-version needs no fetch (the local template IS the base); otherwise
+  // npm pack the recorded version.
+  let baseTemplateDir;
+  if (typeof flags["base-dir"] === "string") {
+    baseTemplateDir = resolveBaseTemplateDir(flags["base-dir"]);
+    step(`Base template: ${colors.cyan(baseTemplateDir)} (--base-dir)`);
+  } else if (baseVersion === currentVersion) {
+    baseTemplateDir = path.join(REPO_ROOT, "template");
+    step(`App was stamped by THIS engine version — base is the local template.`);
+  } else {
+    step(`Fetching base engine ${baseVersion} via npm pack…`);
+    baseTemplateDir = fetchBaseTemplate(baseVersion, tmpRoot);
+  }
+
+  // Stamp both sides with the app's OWN recorded config, so tokens resolve
+  // identically and base→new diffs are pure engine change. `verify:false`
+  // keeps this filesystem-only — no Gradle, no device.
+  const { scaffold } = await import("../scaffold.mjs");
+  const newDir = path.join(tmpRoot, "new");
+  const baseDir = path.join(tmpRoot, "base");
+  step("Stamping the CURRENT engine with the app's recorded config…");
+  await scaffold(configFromSpecRecord(record, newDir), { verify: false });
+  step(`Stamping the BASE engine (${baseVersion}) with the same config…`);
+  await scaffold(configFromSpecRecord(record, baseDir), {
+    templateDir: baseTemplateDir,
+    verify: false,
+  });
+  const plan = planHarnessUpgrade({ baseDir, newDir, projectDir });
+
+  const anythingToDo = printHarnessReport(plan);
+  if (!anythingToDo) {
+    ok("Engine-owned files are fully up to date — nothing to apply.");
+    return 0;
+  }
+
+  if (flags["dry-run"] === true) {
+    process.stdout.write(`\n${colors.yellow("Dry run")} — nothing written. Re-run with --yes to apply.\n`);
+    return 0;
+  }
+  const approved = await consent(
+    `\nApply these changes (backups written as *${BACKUP_SUFFIX}; conflicts only get *${SIDECAR_SUFFIX} sidecars)?`,
+    { assumeYes: flags.yes === true }
+  );
+  if (!approved) {
+    process.stdout.write(`${colors.yellow("Not applied")} — dry run only. Re-run with --yes to apply.\n`);
+    return 0;
+  }
+
+  const actionable = plan.entries.filter(
+    (e) => e.write !== null || e.sidecar !== null || e.remove
+  );
+  const result = applyHarnessPlan(projectDir, actionable);
+  for (const f of result.written) ok(`wrote ${f} ${colors.dim(`(backup: ${f}${BACKUP_SUFFIX})`)}`);
+  for (const f of result.created) ok(`created ${f}`);
+  for (const f of result.deleted) ok(`deleted ${f} ${colors.dim(`(backup: ${f}${BACKUP_SUFFIX})`)}`);
+  for (const f of result.sidecars) warn(`conflict sidecar ${f} — resolve by hand, then delete it`);
+
+  if (result.backups.length > 0 || result.created.length > 0) {
+    process.stdout.write(`\n${colors.bold("To revert")}\n`);
+    for (const f of result.backups) {
+      process.stdout.write(`  mv "${path.join(projectDir, f)}${BACKUP_SUFFIX}" "${path.join(projectDir, f)}"\n`);
+    }
+    for (const f of result.created) {
+      process.stdout.write(`  rm "${path.join(projectDir, f)}"\n`);
+    }
+  }
+
+  if (result.sidecars.length > 0) {
+    fail(
+      `${result.sidecars.length} conflict(s) need a human: the app's files were left untouched; ` +
+        `each *${SIDECAR_SUFFIX} sidecar carries the new engine content.`
+    );
+    return 1;
+  }
+  process.stdout.write(
+    `\n${colors.green("Applied.")} Prove the build: ${colors.cyan(`create-cmp verify --target-dir ${targetDir}`)}\n`
+  );
+  return 0;
+}
+
 /**
  * @param {Record<string,string|boolean>} flags
  * @param {string|undefined} positional optional target dir positional
  */
 export async function runUpgrade(flags, positional) {
+  if (flags.harness === true) {
+    return runHarnessUpgrade(flags, positional);
+  }
   const targetDir =
     (typeof flags["target-dir"] === "string" && flags["target-dir"]) || positional || ".";
   const projectDir = path.resolve(targetDir);