@multiplatform.one/cli 6.7.0 → 7.0.0

package/src/commands/initApp.ts

@@ -20,6 +20,15 @@ import spawn from "nano-spawn";
  */
 export type InitAppTemplate = "universal" | "app";
 
+/**
+ * The provenance template domain: the scaffold templates plus "none" for
+ * ADOPTED projects (`mpo adopt`) — existing repos that were never scaffolded.
+ * A "none" scaffold is the selected piece fragments overlaid on an EMPTY
+ * tree (no universal/app base), which is exactly the tool-owned surface of
+ * an adopted project.
+ */
+export type ProvenanceTemplate = InitAppTemplate | "none";
+
 /**
  * Optional composable pieces overlaid onto the base template (additive
  * fragments under templates/pieces/<piece>/ — the inverse of the old
@@ -40,7 +49,7 @@ const PIECE_DESCRIPTIONS: Record<InitAppPiece, string> = {
   frappe: "Frappe backend wiring (env keys, provider, docker compose bench)",
   gnome: "GNOME desktop target (GTK4/GJS via react-gnome — native widgets, no webview)",
   keycloak: "Keycloak auth wiring (env keys, provider, docker compose + realm)",
-  tauri: "Desktop target (src-tauri skeleton, tauri scripts)",
+  tauri: "Tauri desktop target (src-tauri skeleton — webview shell, Rust toolchain)",
   vscode: "VS Code extension target (extension host + Tamagui webview)",
   webext: "Browser extension target (MV3 popup + background)",
 };
@@ -52,8 +61,13 @@ export interface InitAppOptions {
   skipGit?: boolean;
   /** Pin @multiplatform.one/* to this semver range. Default: ^<cli version>. */
   version?: string;
-  /** Project template. When omitted: prompt (interactive) or "universal". */
-  template?: InitAppTemplate;
+  /**
+   * Project template. When omitted: prompt (interactive) or "universal".
+   * "none" scaffolds ONLY the selected pieces onto an empty tree (the
+   * `--pieces-only` flag) — `mpo update` uses it to rebuild the merge
+   * baselines of adopted projects.
+   */
+  template?: ProvenanceTemplate;
   /** Accept defaults instead of prompting (non-interactive / CI). */
   yes?: boolean;
   /**
@@ -80,7 +94,7 @@ function toPascalCase(name: string): string {
     .join("");
 }
 
-function validateName(name: string): string {
+export function validateName(name: string): string {
   const trimmed = name.trim();
   if (!trimmed) {
     throw new Error("Project name is required");
@@ -93,6 +107,19 @@ function validateName(name: string): string {
   return trimmed;
 }
 
+/** Root package.json name with any @scope/ prefix stripped (adopt +
+ *  update-bootstrap provenance name derivation). */
+export function packageJsonName(projectDir: string): string | undefined {
+  try {
+    const pkg = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf-8")) as {
+      name?: string;
+    };
+    return pkg.name?.replace(/^@[^/]+\//u, "");
+  } catch {
+    return undefined;
+  }
+}
+
 function resolveMpoVersion(explicit?: string): string {
   if (explicit) {
     return explicit.startsWith("^") || explicit.startsWith("~") || explicit === "*"
@@ -120,12 +147,21 @@ export function cliVersion(): string | undefined {
  * three-way template update.
  */
 export interface MpoProvenance {
-  template: InitAppTemplate;
+  /** "none" = adopted project (`mpo adopt`): pieces only, no base template. */
+  template: ProvenanceTemplate;
   cliVersion: string;
   name: string;
   mpoVersion: string;
   /** Composable pieces overlaid at init time (sorted). */
   pieces: InitAppPiece[];
+  /**
+   * false = adopted but never reconciled: `mpo adopt` wrote provenance
+   * without touching any project file, so no tool-owned content exists yet.
+   * The first `mpo update` merges the piece baseline from an EMPTY base
+   * (surfacing real diffs against hand-copied files) and then clears the
+   * flag. Absent/true = the tree carries the recorded scaffold.
+   */
+  reconciled?: boolean;
 }
 
 export const PROVENANCE_FILE = ".mpo.json";
@@ -150,6 +186,8 @@ export function readProvenance(projectDir: string): MpoProvenance | undefined {
       mpoVersion: raw.mpoVersion ?? `^${raw.cliVersion}`,
       // Scaffolds from pre-piece CLIs (≤6.4.x) have no pieces field.
       pieces: Array.isArray(raw.pieces) ? [...(raw.pieces as InitAppPiece[])].sort() : [],
+      // Only adopted-but-unreconciled provenance carries the flag.
+      ...(raw.reconciled === false ? { reconciled: false } : {}),
     };
   } catch {
     return undefined;
@@ -167,10 +205,13 @@ function piecesRoot(piece: InitAppPiece): string {
 /**
  * Fragment source dirs for a piece + template: shared/ applies to every
  * template, <template>/ only to that one. A piece supports a template when
- * at least one of the two exists.
+ * at least one of the two exists. Adopted projects (template "none") use the
+ * universal fragment set — pieces ship universal-layout fragments
+ * (apps/<name>/…), which is the layout adopted repos follow.
  */
-function pieceFragmentDirs(piece: InitAppPiece, template: InitAppTemplate): string[] {
-  return [join(piecesRoot(piece), "shared"), join(piecesRoot(piece), template)].filter((dir) =>
+function pieceFragmentDirs(piece: InitAppPiece, template: ProvenanceTemplate): string[] {
+  const effective: InitAppTemplate = template === "none" ? "universal" : template;
+  return [join(piecesRoot(piece), "shared"), join(piecesRoot(piece), effective)].filter((dir) =>
     existsSync(dir),
   );
 }
@@ -357,7 +398,7 @@ function overlayTree(srcDir: string, destDir: string, vars: TemplateVars): void
  * order must be deterministic), and every piece must ship a fragment for the
  * chosen template.
  */
-export function normalizePieces(pieces: string[], template: InitAppTemplate): InitAppPiece[] {
+export function normalizePieces(pieces: string[], template: ProvenanceTemplate): InitAppPiece[] {
   const known = new Set<string>(INIT_APP_PIECES);
   const normalized = [...new Set(pieces)].sort() as InitAppPiece[];
   for (const piece of normalized) {
@@ -375,13 +416,18 @@ export function normalizePieces(pieces: string[], template: InitAppTemplate): In
 }
 
 /** Pieces that can be offered for a template (fragment exists for it). */
-export function availablePieces(template: InitAppTemplate): InitAppPiece[] {
+export function availablePieces(template: ProvenanceTemplate): InitAppPiece[] {
   return INIT_APP_PIECES.filter((piece) => pieceFragmentDirs(piece, template).length > 0);
 }
 
+/** Human-readable piece summaries (adopt + init prompts). */
+export function pieceDescription(piece: InitAppPiece): string {
+  return PIECE_DESCRIPTIONS[piece];
+}
+
 async function resolvePieces(
   options: InitAppOptions,
-  template: InitAppTemplate,
+  template: ProvenanceTemplate,
 ): Promise<InitAppPiece[]> {
   if (options.pieces) return normalizePieces(options.pieces, template);
   if (options.yes || !process.stdout.isTTY) return [];
@@ -454,7 +500,7 @@ export function composeAppTs(pieces: InitAppPiece[]): string {
   return lines.join("\n");
 }
 
-async function resolveTemplate(options: InitAppOptions): Promise<InitAppTemplate> {
+async function resolveTemplate(options: InitAppOptions): Promise<ProvenanceTemplate> {
   if (options.template) return options.template;
   if (options.yes || !process.stdout.isTTY) return "universal";
   const result = await inquirer.prompt([
@@ -501,6 +547,12 @@ export async function initApp(
   const name = validateName(projectName);
   const template = await resolveTemplate(options);
   const pieces = await resolvePieces(options, template);
+  if (template === "none" && pieces.length === 0) {
+    throw new Error(
+      "A pieces-only scaffold needs at least one piece " +
+        `(${INIT_APP_PIECES.map((piece) => `--${piece}`).join(", ")})`,
+    );
+  }
   const targetDir = resolve(name);
 
   if (existsSync(targetDir)) {
@@ -518,11 +570,18 @@ export async function initApp(
     YEAR: String(new Date().getFullYear()),
   };
 
-  const label = template === "universal" ? "universal (web + iOS + Android)" : "web-only";
+  const label =
+    template === "universal"
+      ? "universal (web + iOS + Android)"
+      : template === "app"
+        ? "web-only"
+        : "pieces-only (adopted-project baseline)";
   console.log(`\nScaffolding ${label} project at ${targetDir}`);
-  console.log(`  apps/${name}`);
-  console.log(`  features/${name}`);
-  console.log(`  packages/config`);
+  if (template !== "none") {
+    console.log(`  apps/${name}`);
+    console.log(`  features/${name}`);
+    console.log(`  packages/config`);
+  }
   if (template === "universal") {
     console.log(`  packages/i18n`);
     console.log(`  packages/themes`);
@@ -532,7 +591,13 @@ export async function initApp(
   }
   console.log(`  @multiplatform.one/* → ${vars.MPO_VERSION}\n`);
 
-  writeTree(templatesRoot(template), targetDir, vars);
+  // "none" (adopted-project baselines) overlays pieces on an EMPTY tree —
+  // there is no base template to write.
+  if (template === "none") {
+    mkdirSync(targetDir, { recursive: true });
+  } else {
+    writeTree(templatesRoot(template), targetDir, vars);
+  }
   // Pieces overlay AFTER the base template, in sorted order (normalizePieces)
   // so repeated scaffolds are byte-identical — mpo update regenerates these
   // exact trees as merge baselines.
@@ -544,6 +609,8 @@ export async function initApp(
   // Backend providers are wired by generating src/app.ts from the selection
   // (not by stacking file overwrites per combination).
   if (pieces.includes("frappe") || pieces.includes("keycloak")) {
+    // Pieces-only trees have no base template dirs — create the path.
+    mkdirSync(join(targetDir, "apps", name, "src"), { recursive: true });
     writeFileSync(join(targetDir, "apps", name, "src/app.ts"), composeAppTs(pieces));
   }
   writeProvenance(targetDir, {
@@ -566,7 +633,8 @@ export async function initApp(
       () => false,
     );
     if (!insideRepo) {
-      const label = template === "universal" ? "universal" : "web-only";
+      const label =
+        template === "universal" ? "universal" : template === "app" ? "web-only" : "pieces-only";
       await spawn("git", ["init", "--quiet"], { cwd: targetDir });
       await spawn("git", ["add", "-A"], { cwd: targetDir });
       scaffoldCommitted = await spawn(
@@ -583,7 +651,9 @@ export async function initApp(
     }
   }
 
-  if (!options.skipInstall) {
+  // Pieces-only trees are merge baselines, not runnable projects — never
+  // install into them.
+  if (!options.skipInstall && template !== "none") {
     console.log("Installing dependencies...");
     await spawn("pnpm", ["install"], {
       cwd: targetDir,
@@ -596,11 +666,15 @@ export async function initApp(
         .then(() => spawn("git", ["commit", "--amend", "--no-edit", "--quiet"], { cwd: targetDir }))
         .catch(() => {});
     }
-  } else {
+  } else if (options.skipInstall) {
     console.log("Skipped pnpm install (--skip-install).");
   }
 
   console.log(`\n✅ Project created at ${targetDir}`);
+  if (template === "none") {
+    console.log("\nPieces-only tree (adopted-project baseline) — not a runnable project.");
+    return;
+  }
   console.log("\nNext steps:");
   console.log(`  cd ${name}`);
   if (options.skipInstall) console.log("  pnpm install");
@@ -619,7 +693,7 @@ export async function initApp(
     console.log("  pnpm gnome       # GTK4 desktop app (requires gjs + gtk4 — see README)");
   }
   if (pieces.includes("tauri")) {
-    console.log("  pnpm tauri:dev   # desktop app (requires the Rust toolchain)");
+    console.log("  pnpm tauri:dev   # Tauri desktop app (requires the Rust toolchain)");
   }
   if (pieces.includes("vscode")) {
     console.log("  pnpm build:vscode  # stage the VS Code extension into apps dist-vscode/");

package/src/commands/updateApp.spec.ts

@@ -1,5 +1,11 @@
-import { describe, expect, it } from "vitest";
-import { threeWayMergePackageJson } from "./updateApp";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import spawn from "nano-spawn";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { adoptApp } from "./adoptApp";
+import { cliVersion, initApp, readProvenance } from "./initApp";
+import { threeWayMergePackageJson, updateApp } from "./updateApp";
 
 const json = (value: unknown) => JSON.stringify(value, null, 2);
 
@@ -79,3 +85,309 @@ describe("threeWayMergePackageJson", () => {
     });
   });
 });
+
+// ── integration: adopt → update, bootstrap, idempotency ───────────
+//
+// Everything below runs at the CURRENT cli version, so both merge
+// baselines come from the local generator (never pnpm dlx / network).
+
+const readJson = (path: string) => JSON.parse(readFileSync(path, "utf-8"));
+
+async function gitOut(cwd: string, args: string[]): Promise<string> {
+  const result = await spawn("git", args, { cwd });
+  return result.stdout.trim();
+}
+
+async function initRepo(dir: string): Promise<void> {
+  await spawn("git", ["init", "--quiet"], { cwd: dir });
+  await spawn("git", ["config", "user.email", "spec@example.com"], { cwd: dir });
+  await spawn("git", ["config", "user.name", "Spec"], { cwd: dir });
+  await spawn("git", ["add", "-A"], { cwd: dir });
+  await spawn("git", ["commit", "--quiet", "-m", "chore: fixture"], { cwd: dir });
+}
+
+function writeFiles(dir: string, files: Record<string, string>): void {
+  mkdirSync(dir, { recursive: true });
+  for (const [file, content] of Object.entries(files)) {
+    mkdirSync(dirname(join(dir, file)), { recursive: true });
+    writeFileSync(join(dir, file), content);
+  }
+}
+
+describe("updateApp (integration)", () => {
+  const currentVersion = cliVersion()!;
+  const currentRange = `^${currentVersion}`;
+  let sandbox: string;
+  let previousCwd: string;
+  let canonical: string;
+
+  /** Scaffold the canonical pieces-only tree (what adopted-update baselines
+   *  look like) once, to source hand-copied fixtures and compare against. */
+  beforeAll(async () => {
+    sandbox = mkdtempSync(join(tmpdir(), "mpo-updateapp-spec-"));
+    previousCwd = process.cwd();
+    const parent = join(sandbox, "canonical");
+    mkdirSync(parent, { recursive: true });
+    process.chdir(parent);
+    await initApp("fake-ext", {
+      template: "none",
+      pieces: ["webext"],
+      version: currentRange,
+      skipInstall: true,
+      skipGit: true,
+      yes: true,
+    });
+    process.chdir(previousCwd);
+    canonical = join(parent, "fake-ext");
+  });
+
+  afterEach(() => {
+    process.chdir(previousCwd);
+  });
+
+  afterAll(() => {
+    rmSync(sandbox, { recursive: true, force: true });
+  });
+
+  it("adopted project: first update reconciles from an empty base, second run is a no-op", async () => {
+    // A never-scaffolded project that hand-copied ONE webext piece file
+    // verbatim and has its own unrelated files.
+    const dir = join(sandbox, "adopted-clean", "fake-ext");
+    writeFiles(dir, {
+      "package.json": json({
+        name: "@fake/fake-ext",
+        private: true,
+        scripts: { custom: "echo custom" },
+      }),
+      "src/index.ts": "export const custom = true;\n",
+      "apps/fake-ext/webext/manifest.ts": readFileSync(
+        join(canonical, "apps/fake-ext/webext/manifest.ts"),
+        "utf-8",
+      ),
+    });
+    await initRepo(dir);
+    process.chdir(dir);
+
+    await adoptApp({ pieces: ["webext"], yes: true });
+    expect(readProvenance(dir)?.reconciled).toBe(false);
+
+    await updateApp({ skipInstall: true });
+
+    // Missing piece files landed…
+    for (const file of [
+      "apps/fake-ext/vite.config.webext.ts",
+      "apps/fake-ext/vite.config.webext-background.ts",
+      "apps/fake-ext/webext/background/main.ts",
+      "apps/fake-ext/webext/views/popup/main.tsx",
+      "apps/fake-ext/package.json",
+    ]) {
+      expect(existsSync(join(dir, file)), `missing ${file}`).toBe(true);
+    }
+    // …the identical hand-copied file stayed identical…
+    expect(readFileSync(join(dir, "apps/fake-ext/webext/manifest.ts"), "utf-8")).toBe(
+      readFileSync(join(canonical, "apps/fake-ext/webext/manifest.ts"), "utf-8"),
+    );
+    // …the project's own files survived…
+    expect(readFileSync(join(dir, "src/index.ts"), "utf-8")).toBe("export const custom = true;\n");
+    // …and package.json merged structurally (custom + piece scripts).
+    const rootPkg = readJson(join(dir, "package.json"));
+    expect(rootPkg.scripts.custom).toBe("echo custom");
+    expect(rootPkg.scripts["build:webext"]).toBe("pnpm --filter @app/fake-ext build:webext");
+
+    // Reconciliation committed cleanly and cleared the flag.
+    expect(await gitOut(dir, ["status", "--porcelain"])).toBe("");
+    expect(await gitOut(dir, ["log", "-1", "--format=%s"])).toContain("mpo update");
+    const provenance = readProvenance(dir);
+    expect(provenance?.reconciled).toBeUndefined();
+    expect(provenance?.cliVersion).toBe(currentVersion);
+
+    // Idempotency: an immediate second update changes NOTHING.
+    const headBefore = await gitOut(dir, ["rev-parse", "HEAD"]);
+    await updateApp({ skipInstall: true });
+    expect(await gitOut(dir, ["rev-parse", "HEAD"])).toBe(headBefore);
+    expect(await gitOut(dir, ["status", "--porcelain"])).toBe("");
+  });
+
+  it("adopted project: divergent hand-copied files surface conflict markers, then updates go quiet", async () => {
+    const dir = join(sandbox, "adopted-divergent", "fake-ext");
+    writeFiles(dir, {
+      "package.json": json({ name: "fake-ext", private: true }),
+      "apps/fake-ext/webext/manifest.ts": "// hand-rolled manifest, diverged\n",
+    });
+    await initRepo(dir);
+    process.chdir(dir);
+
+    await adoptApp({ pieces: ["webext"], yes: true });
+    await updateApp({ skipInstall: true });
+
+    // The divergent file carries conflict markers in the worktree — the
+    // documented (expected) first-update behavior for hand-adopted files.
+    const manifest = readFileSync(join(dir, "apps/fake-ext/webext/manifest.ts"), "utf-8");
+    expect(manifest).toContain("<<<<<<<");
+    expect(manifest).toContain(">>>>>>>");
+    expect(await gitOut(dir, ["status", "--porcelain"])).not.toBe("");
+    // Provenance was still rewritten (flag cleared) for the resolution commit.
+    expect(readProvenance(dir)?.reconciled).toBeUndefined();
+
+    // Resolve (keep the template side) and commit like the CLI instructs.
+    writeFileSync(
+      join(dir, "apps/fake-ext/webext/manifest.ts"),
+      readFileSync(join(canonical, "apps/fake-ext/webext/manifest.ts"), "utf-8"),
+    );
+    await spawn("git", ["add", "-A"], { cwd: dir });
+    await spawn("git", ["commit", "--quiet", "-m", "chore: mpo update (resolved)"], { cwd: dir });
+
+    // Idempotency after resolution.
+    const headBefore = await gitOut(dir, ["rev-parse", "HEAD"]);
+    await updateApp({ skipInstall: true });
+    expect(await gitOut(dir, ["rev-parse", "HEAD"])).toBe(headBefore);
+    expect(await gitOut(dir, ["status", "--porcelain"])).toBe("");
+  });
+
+  it(".updateignore: dir/** normalizes to a directory pin; HEAD wins including absence", async () => {
+    const dir = join(sandbox, "adopted-pinned", "fake-ext");
+    writeFiles(dir, {
+      "package.json": json({ name: "fake-ext", private: true }),
+      // Deliberately diverged piece file the pin must protect verbatim.
+      "apps/fake-ext/webext/manifest.ts": "// bespoke manifest — never reconcile\n",
+      // The natural (glob) spelling users reach for first.
+      ".updateignore": "# bespoke surface\napps/fake-ext/webext/**\n",
+    });
+    await initRepo(dir);
+    process.chdir(dir);
+
+    await adoptApp({ pieces: ["webext"], yes: true });
+    await updateApp({ skipInstall: true });
+
+    // Pinned file byte-identical, no conflict markers anywhere under the pin.
+    expect(readFileSync(join(dir, "apps/fake-ext/webext/manifest.ts"), "utf-8")).toBe(
+      "// bespoke manifest — never reconcile\n",
+    );
+    // Pinning means HEAD wins INCLUDING absence: template-only files under
+    // the pinned dir must not land…
+    expect(existsSync(join(dir, "apps/fake-ext/webext/views/popup/main.tsx"))).toBe(false);
+    // …while piece files OUTSIDE the pin still flow.
+    expect(existsSync(join(dir, "apps/fake-ext/vite.config.webext.ts"))).toBe(true);
+
+    // Idempotency with pins active.
+    const headBefore = await gitOut(dir, ["rev-parse", "HEAD"]);
+    await updateApp({ skipInstall: true });
+    expect(await gitOut(dir, ["rev-parse", "HEAD"])).toBe(headBefore);
+    expect(await gitOut(dir, ["status", "--porcelain"])).toBe("");
+  });
+
+  it(".updateignore: a genuinely glob-shaped entry is refused loudly, not silently dead", async () => {
+    const dir = join(sandbox, "adopted-badglob", "fake-ext");
+    writeFiles(dir, {
+      "package.json": json({ name: "fake-ext", private: true }),
+      ".updateignore": "apps/*.config.ts\n",
+    });
+    await initRepo(dir);
+    process.chdir(dir);
+
+    await adoptApp({ pieces: ["webext"], yes: true });
+    await expect(updateApp({ skipInstall: true })).rejects.toThrow(/looks like a glob/);
+  });
+
+  it("scaffolded project: immediate re-update is a no-op, customizations survive", async () => {
+    const parent = join(sandbox, "scaffolded");
+    mkdirSync(parent, { recursive: true });
+    process.chdir(parent);
+    await initApp("uni-idem", {
+      template: "universal",
+      pieces: ["webext"],
+      version: currentRange,
+      skipInstall: true,
+      skipGit: true,
+      yes: true,
+    });
+    const dir = join(parent, "uni-idem");
+    await initRepo(dir);
+    process.chdir(dir);
+
+    // Fresh scaffold at the current version: update must be a pure no-op.
+    const headBefore = await gitOut(dir, ["rev-parse", "HEAD"]);
+    await updateApp({ skipInstall: true });
+    expect(await gitOut(dir, ["rev-parse", "HEAD"])).toBe(headBefore);
+    expect(await gitOut(dir, ["status", "--porcelain"])).toBe("");
+
+    // User customizations don't destabilize it.
+    writeFileSync(join(dir, "custom.md"), "# mine\n");
+    await spawn("git", ["add", "-A"], { cwd: dir });
+    await spawn("git", ["commit", "--quiet", "-m", "feat: customize"], { cwd: dir });
+    const headCustom = await gitOut(dir, ["rev-parse", "HEAD"]);
+    await updateApp({ skipInstall: true });
+    expect(await gitOut(dir, ["rev-parse", "HEAD"])).toBe(headCustom);
+    expect(await gitOut(dir, ["status", "--porcelain"])).toBe("");
+    expect(readFileSync(join(dir, "custom.md"), "utf-8")).toBe("# mine\n");
+  });
+
+  it("bootstraps missing provenance with --assume-version and stays idempotent", async () => {
+    const parent = join(sandbox, "bootstrap");
+    mkdirSync(parent, { recursive: true });
+    process.chdir(parent);
+    await initApp("pre-prov", {
+      template: "universal",
+      version: currentRange,
+      skipInstall: true,
+      skipGit: true,
+      yes: true,
+    });
+    const dir = join(parent, "pre-prov");
+    // Simulate a pre-provenance scaffold: no .mpo.json ever existed.
+    rmSync(join(dir, ".mpo.json"));
+    await initRepo(dir);
+    process.chdir(dir);
+
+    // Without provenance the update refuses, pointing at both escape
+    // hatches (bootstrap + adopt).
+    await expect(updateApp({ skipInstall: true })).rejects.toThrow(/--assume-version/u);
+    await expect(updateApp({ skipInstall: true })).rejects.toThrow(/mpo adopt/u);
+    // Bad version strings are rejected before anything is written.
+    await expect(updateApp({ skipInstall: true, assumeVersion: "not-a-version" })).rejects.toThrow(
+      /exact CLI version/u,
+    );
+    expect(existsSync(join(dir, ".mpo.json"))).toBe(false);
+
+    await updateApp({ skipInstall: true, assumeVersion: currentVersion });
+    const provenance = readProvenance(dir);
+    expect(provenance?.template).toBe("universal");
+    expect(provenance?.cliVersion).toBe(currentVersion);
+    expect(provenance?.pieces).toEqual([]);
+    expect(await gitOut(dir, ["status", "--porcelain"])).toBe("");
+    // The bootstrap provenance is committed, not floating.
+    expect(await gitOut(dir, ["show", "HEAD:.mpo.json"])).toContain(currentVersion);
+
+    // Re-asserting a version over existing provenance is refused.
+    await expect(updateApp({ skipInstall: true, assumeVersion: currentVersion })).rejects.toThrow(
+      /already has provenance/u,
+    );
+
+    // Plain updates are now no-ops.
+    const headBefore = await gitOut(dir, ["rev-parse", "HEAD"]);
+    await updateApp({ skipInstall: true });
+    expect(await gitOut(dir, ["rev-parse", "HEAD"])).toBe(headBefore);
+    expect(await gitOut(dir, ["status", "--porcelain"])).toBe("");
+  });
+
+  it("bootstraps the app template when told to", async () => {
+    const parent = join(sandbox, "bootstrap-app");
+    mkdirSync(parent, { recursive: true });
+    process.chdir(parent);
+    await initApp("pre-prov-app", {
+      template: "app",
+      version: currentRange,
+      skipInstall: true,
+      skipGit: true,
+      yes: true,
+    });
+    const dir = join(parent, "pre-prov-app");
+    rmSync(join(dir, ".mpo.json"));
+    await initRepo(dir);
+    process.chdir(dir);
+
+    await updateApp({ skipInstall: true, assumeVersion: currentVersion, assumeTemplate: "app" });
+    expect(readProvenance(dir)?.template).toBe("app");
+    expect(await gitOut(dir, ["status", "--porcelain"])).toBe("");
+  });
+});