@multiplatform.one/cli 7.10.0 → 7.15.0

package/scripts/stamp-source.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// Writes lib/source.json: the monorepo commit this build of the CLI came
+// from, so a published `mpo init` clones the exact tree its templates and
+// packages were cut from. Runs as the last step of `pnpm build`, and again
+// from `package-train.mjs pack`, because a release builds before its version
+// commit exists. A commit whose package.json carries another version is never
+// stamped: scaffold.sh reads the @multiplatform.one range from that file at the
+// stamped commit (MPO-346).
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+const url = process.env.MPO_SOURCE_URL || pkg.repository.url.replace(/^git\+/, "");
+
+function git(args) {
+  return execFileSync("git", args, {
+    cwd: root,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  }).trim();
+}
+
+function committedVersion(rev) {
+  try {
+    return JSON.parse(git(["show", `${rev}:./package.json`])).version;
+  } catch {
+    return undefined;
+  }
+}
+
+let sha = process.env.MPO_SOURCE_SHA;
+let skipped = "";
+if (!sha) {
+  let head;
+  try {
+    head = git(["rev-parse", "HEAD"]);
+  } catch {
+    head = undefined;
+  }
+  const version = head && committedVersion(head);
+  if (version === pkg.version) sha = head;
+  else if (head)
+    skipped = ` (HEAD ${head.slice(0, 12)} carries ${version ?? "no"} cli version, not ${pkg.version})`;
+}
+const stamp = { cliVersion: pkg.version, url, ...(sha ? { sha } : {}) };
+mkdirSync(join(root, "lib"), { recursive: true });
+writeFileSync(join(root, "lib/source.json"), `${JSON.stringify(stamp, null, 2)}\n`);
+process.stdout.write(`source: ${sha ?? "(no git sha)"}${skipped} ${url}\n`);

package/scripts/stamp-source.spec.ts

@@ -0,0 +1,86 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const script = join(dirname(fileURLToPath(import.meta.url)), "stamp-source.mjs");
+
+interface Stamp {
+  cliVersion: string;
+  sha?: string;
+  url: string;
+}
+
+describe("stamp-source", () => {
+  let repo: string;
+  let cli: string;
+
+  const git = (...args: string[]) =>
+    execFileSync("git", args, {
+      cwd: repo,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  const setVersion = (version: string) =>
+    writeFileSync(
+      join(cli, "package.json"),
+      `${JSON.stringify({ name: "@multiplatform.one/cli", version, repository: { url: "git+https://git.example.invalid/mpo.git" } })}\n`,
+    );
+  const commit = (message: string) => {
+    git("add", "-A");
+    git(
+      "-c",
+      "user.name=fixture",
+      "-c",
+      "user.email=fixture@example.invalid",
+      "commit",
+      "-qm",
+      message,
+    );
+  };
+  const stamp = (): Stamp => {
+    execFileSync(process.execPath, [join(cli, "scripts/stamp-source.mjs")], {
+      env: { PATH: process.env.PATH },
+      stdio: "ignore",
+    });
+    return JSON.parse(readFileSync(join(cli, "lib/source.json"), "utf8")) as Stamp;
+  };
+  const cliVersionAt = (sha: string) =>
+    (JSON.parse(git("show", `${sha}:public/cli/package.json`)) as { version: string }).version;
+
+  beforeEach(() => {
+    repo = mkdtempSync(join(tmpdir(), "mpo-stamp-"));
+    cli = join(repo, "public/cli");
+    mkdirSync(join(cli, "scripts"), { recursive: true });
+    writeFileSync(join(cli, "scripts/stamp-source.mjs"), readFileSync(script));
+    writeFileSync(join(repo, ".gitignore"), "lib/\n");
+    setVersion("7.14.1");
+    git("init", "-q");
+    commit("7.14.1");
+  });
+
+  afterEach(() => {
+    rmSync(repo, { recursive: true, force: true });
+  });
+
+  it("never names a commit whose CLI carries another version than the one it stamps", () => {
+    setVersion("7.14.2");
+    const written = stamp();
+    expect(written.cliVersion).toBe("7.14.2");
+    expect(written.sha && cliVersionAt(written.sha)).toBeUndefined();
+  });
+
+  it("names the version commit once it exists", () => {
+    setVersion("8.0.0");
+    commit("chore(release): version packages");
+    const written = stamp();
+    expect(written).toEqual({
+      cliVersion: "8.0.0",
+      url: "https://git.example.invalid/mpo.git",
+      sha: git("rev-parse", "HEAD"),
+    });
+    expect(cliVersionAt(written.sha!)).toBe("8.0.0");
+  });
+});

package/src/bin/multiplatformOne.ts

@@ -2,7 +2,6 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { generateVscodeConfig } from "../generateVscode.js";
 import {
   formatServiceList,
   lookupProjectRoot,
@@ -17,10 +16,12 @@ import dotenv from "dotenv";
 import spawn from "nano-spawn";
 import YAML from "yaml";
 import yoctoSpinner from "yocto-spinner";
+import { addApp } from "../commands/addApp";
 import { adoptApp } from "../commands/adoptApp";
+import { generateDoctypeTypes, typesDrift } from "../commands/doctypeTypes";
 import { discoverE2EApp, runE2ESession } from "../commands/e2e";
-import { init, runModifyStep } from "../commands/init";
-import { INIT_APP_PIECES, initApp, readProvenance } from "../commands/initApp";
+import { SINGLETON_APPS, init } from "../commands/init";
+import { INIT_APP_PIECES } from "../commands/pieces";
 import { updateApp } from "../commands/updateApp";
 
 const projectRoot = lookupProjectRoot();
@@ -217,100 +218,82 @@ program.version(
   )?.version,
 );
 
+const collect = (value: string, previous: string[]) => [...previous, value];
+
 program
   .command("init")
-  .option("--universal", "scaffold the universal template (web + iOS + Android; default)")
-  .option("--web", "scaffold the web-only template (Vite + React)")
-  .option("--app", "alias of --web (back-compat)")
-  .option("--frappe", "add the Frappe backend piece (env keys, provider, docker compose bench)")
-  .option("--keycloak", "add the Keycloak auth piece (env keys, provider, docker compose + realm)")
+  .argument("[name]", "the project (and product app) name; with --into, the directory")
+  .option("--app <name>", "one more product app derived from apps/one (repeatable)", collect, [])
   .option(
-    "--gnome",
-    "add the GNOME desktop target piece (GTK4/GJS via react-gnome — native widgets, no webview)",
+    "--service <name>",
+    `singleton app to keep (repeatable): ${SINGLETON_APPS.join(", ")}`,
+    collect,
+    [],
   )
+  .option("--frappe", "same as --service frappe")
+  .option("--keycloak", "same as --service keycloak")
   .option(
-    "--tauri",
-    "add the Tauri desktop target piece (src-tauri webview shell — Rust; combines with --gnome)",
+    "--into",
+    "scaffold into an existing directory (the argument, default .); paths already there are kept and pinned in .updateignore",
   )
-  .option("--vscode", "add the VS Code extension target piece")
-  .option("--webext", "add the browser extension target piece (MV3 popup + background)")
   .option(
-    "--pieces-only",
-    "scaffold ONLY the selected piece fragments onto an empty tree (no base template) — used by `mpo update` to rebuild adopted-project merge baselines",
+    "--source <path|url>",
+    "monorepo to scaffold from (default: the commit this CLI was built from)",
   )
-  .option("--skip-install", "skip pnpm install after scaffolding")
-  .option("--skip-git", "skip git init + scaffold commit")
+  .option("-c, --checkout <ref>", "commit, tag or branch at the source")
   .option(
     "--mpo-version <range>",
-    "semver range for @multiplatform.one/* (default: ^<cli version>)",
+    "semver range for @multiplatform.one/* (default: ^<cli version at the source>)",
   )
-  .option("-y, --yes", "non-interactive: accept defaults instead of prompting")
-  .option(
-    "--monorepo",
-    "DEPRECATED: clone/modify the full multiplatform.one monorepo instead of scaffolding a consumer project",
-  )
-  .option("-c, --checkout <branch>", "branch, tag or commit to checkout (--monorepo only)", "main")
-  .option("-a, --apps <apps>", "comma-separated apps to include (--monorepo only)")
-  .option("-s, --services <services>", "comma-separated services to include (--monorepo only)")
-  .argument("[name]", "the name of the project")
+  .option("--skip-install", "skip pnpm install after scaffolding")
+  .option("--skip-git", "skip git init + scaffold commit")
+  .option("-y, --yes", "non-interactive: no prompts, no services unless passed")
+  .option("--verbose", "show what the scaffold removes and skips")
   .description(
-    "scaffold a new multiplatform project (universal web + native by default; --web for web-only; semver @multiplatform.one/* deps)",
+    "scaffold a project: the multiplatform.one monorepo at one commit, pruned (no public/, only the services asked for, apps/one renamed to the product app, @multiplatform.one/* at semver ranges)",
   )
   .action(async (name: string | undefined, options) => {
-    if (options.monorepo) {
-      console.warn(
-        "⚠️  `mpo init --monorepo` clones the whole multiplatform.one monorepo (legacy). " +
-          "New projects should use the default consumer scaffold instead.",
-      );
-      if (
-        await spawn("git", ["rev-parse", "--is-inside-work-tree"]).then(
-          () => true,
-          () => false,
-        )
-      ) {
-        throw new Error("mpo cannot be initialized inside a git repository");
-      }
-      const cloneScript = path.resolve(
-        path.dirname(fileURLToPath(import.meta.url)),
-        "../../scripts/clone.sh",
-      );
-      await init(name, { ...options, cloneScript });
-      return;
-    }
-    if (options.apps || options.services) {
-      throw new Error(
-        "--apps/--services select monorepo pieces and require --monorepo (legacy clone mode)",
-      );
-    }
-    const webOnly = Boolean(options.web || options.app);
-    if (webOnly && options.universal) {
-      throw new Error("Pass either --web/--app or --universal, not both");
-    }
-    if (options.piecesOnly && (webOnly || options.universal)) {
-      throw new Error("--pieces-only scaffolds no base template — drop --web/--universal");
-    }
-    // Piece flags are multi-select; passing any of them skips the interactive
-    // pieces prompt. No flags + --yes (or non-TTY) → no pieces.
-    const pieces = INIT_APP_PIECES.filter((piece) => Boolean(options[piece]));
-    await initApp(name, {
+    const services: string[] = [...options.service];
+    if (options.frappe) services.push("frappe");
+    if (options.keycloak) services.push("keycloak");
+    await init(name, {
+      apps: options.app,
+      services: services.length || options.yes || !process.stdout.isTTY ? services : undefined,
+      source: options.source,
+      checkout: options.checkout,
+      mpoVersion: options.mpoVersion,
       skipInstall: Boolean(options.skipInstall),
       skipGit: Boolean(options.skipGit),
-      version: options.mpoVersion,
-      template: options.piecesOnly
-        ? "none"
-        : webOnly
-          ? "app"
-          : options.universal
-            ? "universal"
-            : undefined,
       yes: Boolean(options.yes),
-      pieces: pieces.length ? pieces : undefined,
+      into: Boolean(options.into),
+      verbose: Boolean(options.verbose),
+    });
+  });
+
+program
+  .command("add-app")
+  .argument("<name>", "the new product app (apps/<name> + features/<name>)")
+  .option(
+    "--source <path|url>",
+    "monorepo holding the recorded source commit (default: the recorded url)",
+  )
+  .option("--skip-install", "skip pnpm install after the merge")
+  .option("--verbose", "show the scaffold's progress")
+  .description(
+    "add another product app from apps/one at the project's recorded source commit; the result is left uncommitted like mpo update",
+  )
+  .action(async (name: string, options) => {
+    await addApp(name, {
+      source: options.source,
+      skipInstall: Boolean(options.skipInstall),
+      verbose: Boolean(options.verbose),
     });
   });
 
 program
   .command("adopt")
-  .option("--frappe", "the project adopted the Frappe backend piece")
+  .option("--frappe", "the project adopted the Frappe client piece (env keys, provider)")
+  .option("--frappe-bench", "the project adopted the Frappe dev bench piece (docker compose)")
   .option("--keycloak", "the project adopted the Keycloak auth piece")
   .option("--gnome", "the project adopted the GNOME desktop target piece")
   .option("--tauri", "the project adopted the Tauri desktop target piece")
@@ -322,10 +305,12 @@ program
   )
   .option("-y, --yes", "non-interactive: never prompt (pieces must come from flags)")
   .description(
-    "bring an existing, never-scaffolded project under `mpo update` management: writes .mpo.json provenance (and seeds .updateignore) without changing any project file — the FIRST `mpo update` afterwards reconciles piece files (real diffs expected)",
+    "bring an existing, never-scaffolded project that hand-copied piece files under `mpo update` management: writes .mpo.json provenance (and seeds .updateignore) without changing any project file — the FIRST `mpo update` afterwards reconciles piece files (real diffs expected). For the whole monorepo scaffold use `mpo init --into`",
   )
   .action(async (options) => {
-    const pieces = INIT_APP_PIECES.filter((piece) => Boolean(options[piece]));
+    const pieces = INIT_APP_PIECES.filter((piece) =>
+      Boolean(options[piece.replace(/-(\w)/gu, (_, letter: string) => letter.toUpperCase())]),
+    );
     await adoptApp({
       pieces: pieces.length ? pieces : undefined,
       name: options.name,
@@ -333,164 +318,31 @@ program
     });
   });
 
-const defaultUpdateRemote = "https://gitlab.com/bitspur/frappe/multiplatform.one.git";
-
 program
   .command("update")
   .option(
-    "-c, --checkout <branch>",
-    "branch, tag or commit to merge from upstream (monorepo forks)",
-    "main",
+    "--source <path|url>",
+    "monorepo to update from (default: the commit this CLI was built from)",
   )
-  .option("-r, --remote <url>", "upstream remote URL (monorepo forks)", defaultUpdateRemote)
-  .option("--skip-install", "skip pnpm install after the update")
+  .option("-c, --checkout <ref>", "commit, tag or branch at the source")
+  .option("--skip-install", "skip pnpm install after the merge")
   .option(
     "--mpo-version <range>",
-    "semver range for @multiplatform.one/* (default: ^<cli version>)",
-  )
-  .option(
-    "--assume-version <cliVersion>",
-    "bootstrap missing .mpo.json: assume the project was scaffolded by this exact CLI version, record provenance, then update",
-  )
-  .option(
-    "--template <template>",
-    "template recorded by --assume-version (universal|app, default universal)",
+    "semver range for @multiplatform.one/* (default: ^<cli version at the source>)",
   )
+  .option("--verbose", "show the scaffold's progress")
   .description(
-    "update a scaffolded or adopted project to the current template (three-way merge via .mpo.json provenance); monorepo forks fall back to the upstream merge flow",
+    "three-way merge the monorepo's changes into this project (base = the scaffold at the recorded source commit, ours = HEAD, theirs = the scaffold at the current commit); lands in the index and worktree, never commits; refuses a dirty tree",
   )
-  .action(
-    async (options: {
-      checkout: string;
-      remote: string;
-      skipInstall?: boolean;
-      mpoVersion?: string;
-      assumeVersion?: string;
-      template?: string;
-    }) => {
-      // Update prechecks: must be in a git repo
-      if (
-        await spawn("git", ["rev-parse", "--is-inside-work-tree"]).then(
-          () => false,
-          () => true,
-        )
-      ) {
-        throw new Error("mpo cannot be updated outside of a git repository");
-      }
-      if (options.template && !options.assumeVersion) {
-        throw new Error("--template only applies to the --assume-version bootstrap");
-      }
-      if (options.template && options.template !== "universal" && options.template !== "app") {
-        throw new Error(`--template must be universal or app, got "${options.template}"`);
-      }
-      // Scaffolded consumer projects carry .mpo.json provenance — use the
-      // copier-style three-way template update (--assume-version bootstraps
-      // the provenance for pre-6.3 scaffolds first). Monorepo forks
-      // (identified by the legacy features/package.json marker) fall through
-      // to the upstream-merge flow below; anything else gets the provenance
-      // guidance instead of the fork flow's unrelated errors.
-      if (readProvenance(projectRoot) || options.assumeVersion) {
-        await updateApp({
-          skipInstall: options.skipInstall,
-          version: options.mpoVersion,
-          assumeVersion: options.assumeVersion,
-          assumeTemplate: options.template as "universal" | "app" | undefined,
-        });
-        return;
-      }
-      const legacyFork = await fs.stat(path.resolve(projectRoot, "features/package.json")).then(
-        (stat) => stat.isFile(),
-        () => false,
-      );
-      if (!legacyFork) {
-        throw new Error(
-          ".mpo.json not found — this project predates scaffold provenance.\n" +
-            "  - scaffolded by an old CLI (pre-6.3)? bootstrap it:\n" +
-            "      mpo update --assume-version <cliVersion> [--template universal|app]\n" +
-            "  - never scaffolded (hand-adopted pieces)? bring it under management:\n" +
-            "      mpo adopt --<piece> [...]",
-        );
-      }
-      // Require clean working tree (no staged or unstaged changes)
-      if (
-        await spawn("git", ["diff", "--cached", "--quiet"]).then(
-          () => false,
-          () => true,
-        )
-      ) {
-        throw new Error("mpo cannot be updated with uncommitted changes (staged changes present)");
-      }
-      if (
-        await spawn("git", ["diff", "--quiet"]).then(
-          () => false,
-          () => true,
-        )
-      ) {
-        throw new Error(
-          "multiplatform.one cannot be updated with uncommitted changes (unstaged changes present)",
-        );
-      }
-      // Validate multiplatform.one project with clear errors per failure
-      const rootPkgPath = path.resolve(projectRoot, "package.json");
-      const featuresPkgPath = path.resolve(projectRoot, "features/package.json");
-      try {
-        const stat = await fs.stat(rootPkgPath);
-        if (!stat.isFile()) {
-          throw new Error("mpo update requires a valid project: root package.json not found");
-        }
-      } catch (err) {
-        if (err instanceof Error && err.message.includes("valid project")) {
-          throw err;
-        }
-        throw new Error("mpo update requires a valid project: root package.json not found");
-      }
-      try {
-        const stat = await fs.stat(featuresPkgPath);
-        if (!stat.isFile()) {
-          throw new Error("mpo update requires a valid project: features/package.json not found");
-        }
-      } catch (err) {
-        if (err instanceof Error && err.message.includes("valid project")) {
-          throw err;
-        }
-        throw new Error("mpo update requires a valid project: features/package.json not found");
-      }
-      const featuresPkg = JSON.parse(await fs.readFile(featuresPkgPath, "utf8")) as {
-        dependencies?: Record<string, string>;
-      };
-      if (
-        !featuresPkg?.dependencies?.["multiplatform.one"] ||
-        !String(featuresPkg.dependencies["multiplatform.one"]).length
-      ) {
-        throw new Error(
-          "mpo update requires a valid project: features must depend on multiplatform.one",
-        );
-      }
-
-      // Merge from upstream (update.sh: add remote, fetch, merge, remove remote, restore .updateignore list, pnpm lint)
-      const updateScript = path.resolve(
-        path.dirname(fileURLToPath(import.meta.url)),
-        "../../scripts/update.sh",
-      );
-      await spawn("sh", [updateScript, options.remote, options.checkout], {
-        cwd: projectRoot,
-        stdio: "inherit",
-        shell: true,
-      });
-
-      // Re-apply modify step with auto-detected apps and services
-      const presentServices = await getPresentServices(projectRoot);
-      const presentApps = await getPresentApps(projectRoot);
-      runModifyStep(projectRoot, presentServices, presentApps);
-
-      // Post-update refresh: .vscode from current workspace
-      try {
-        await generateVscodeConfig(projectRoot);
-      } catch {
-        // may fail in older projects without apps/ layout
-      }
-    },
-  );
+  .action(async (options) => {
+    await updateApp({
+      source: options.source,
+      checkout: options.checkout,
+      skipInstall: Boolean(options.skipInstall),
+      version: options.mpoVersion,
+      verbose: Boolean(options.verbose),
+    });
+  });
 
 program
   .command("wait")
@@ -598,6 +450,44 @@ frappe
     );
   });
 
+frappe
+  .command("types")
+  .description(
+    "generate TypeScript types for doctypes from getdoctype (auth: $FRAPPE_API_KEY, $FRAPPE_API_SECRET)",
+  )
+  .argument("<doctypes...>", "doctype names; child tables come along")
+  .option("-o, --out <file>", "write the module here instead of stdout")
+  .option("--check", "exit 1 and print the diff when --out differs from the server")
+  .option("--url <url>", "frappe base URL (default $FRAPPE_URL or http://localhost:8000)")
+  .action(async (doctypes: string[], options) => {
+    const parentOptions = frappe.opts();
+    dotenv.config({ path: parentOptions.dotenv || defaultDotenvPath, quiet: true });
+    if (options.check && !options.out) {
+      console.error("--check needs --out <file>");
+      process.exit(2);
+    }
+    const generated = await generateDoctypeTypes(doctypes, {
+      baseURL: options.url || process.env.FRAPPE_URL || "http://localhost:8000",
+      apiKey: process.env.FRAPPE_API_KEY,
+      apiSecret: process.env.FRAPPE_API_SECRET,
+    });
+    if (!options.out) {
+      process.stdout.write(generated);
+      return;
+    }
+    const out = path.resolve(process.cwd(), options.out);
+    if (options.check) {
+      const committed = fsSync.existsSync(out) ? await fs.readFile(out, "utf8") : "";
+      const drift = typesDrift(committed, generated);
+      if (drift.length > 0) {
+        console.error(`${options.out} drifted from the server:\n${drift.join("\n")}`);
+        process.exit(1);
+      }
+      return;
+    }
+    await fs.writeFile(out, generated);
+  });
+
 program
   .command("build")
   .argument(

package/src/commands/addApp.ts

@@ -0,0 +1,102 @@
+/**
+ * `mpo add-app <name>`: one more product app from apps/one, merged in at the
+ * commit the project was scaffolded from.
+ *
+ *   base   = scaffold(recorded sha, recorded apps)
+ *   theirs = scaffold(recorded sha, recorded apps + name)
+ *   ours   = HEAD
+ *
+ * Same commit on both sides, so the diff is exactly the new app and the
+ * root wiring that names it; the project's own changes are untouched. The
+ * result stays uncommitted like `mpo update`.
+ */
+
+import { rmSync } from "node:fs";
+import { basename, join } from "node:path";
+import { finishMerge, landTree, mergeScaffolds, projectRootOf, requireCleanTree } from "./merge";
+import {
+  PROVENANCE_FILE,
+  cliVersion,
+  packageJsonName,
+  readProvenance,
+  validateName,
+  writeProvenance,
+} from "./provenance";
+import { scaffoldToTemp } from "./scaffold";
+
+export interface AddAppOptions {
+  /** Path or url holding the recorded source commit (default: the recorded url). */
+  source?: string;
+  skipInstall?: boolean;
+  verbose?: boolean;
+}
+
+export async function addApp(nameArg: string, options: AddAppOptions = {}): Promise<void> {
+  const name = validateName(nameArg);
+  const projectDir = await projectRootOf("mpo add-app");
+  await requireCleanTree(projectDir, "mpo add-app");
+
+  const provenance = readProvenance(projectDir);
+  if (!provenance) {
+    throw new Error(`${PROVENANCE_FILE} not found — mpo add-app needs a project from mpo init`);
+  }
+  if (!provenance.source) {
+    throw new Error(
+      "mpo add-app needs a project scaffolded from the monorepo (a source commit in " +
+        `${PROVENANCE_FILE}); adopted and template-era projects run mpo update first`,
+    );
+  }
+  if (provenance.apps.includes(name)) {
+    throw new Error(`apps/${name} is already a product app of this project`);
+  }
+  const source = options.source ?? provenance.source.url;
+  if (!source) {
+    throw new Error(`${PROVENANCE_FILE} records no source url — pass --source <path or url>`);
+  }
+  const { sha } = provenance.source;
+  const common = {
+    source,
+    ref: sha,
+    services: provenance.services,
+    mpoVersion: `^${provenance.cliVersion}`,
+    name: packageJsonName(projectDir) ?? basename(projectDir),
+    verbose: options.verbose,
+  };
+
+  console.log(
+    `\nmpo add-app ${name}: ${provenance.apps.join(", ")} + ${name} @ ${sha.slice(0, 12)}`,
+  );
+  const base = await scaffoldToTemp({ ...common, apps: provenance.apps });
+  const theirs = await scaffoldToTemp({ ...common, apps: [...provenance.apps, name] }).catch(
+    (err: unknown) => {
+      base.cleanup();
+      throw err;
+    },
+  );
+  try {
+    for (const dir of [base.dir, theirs.dir]) {
+      rmSync(join(dir, PROVENANCE_FILE), { force: true });
+    }
+    const outcome = await mergeScaffolds({
+      projectDir,
+      baseDir: base.dir,
+      theirsDir: theirs.dir,
+      baseLabel: `mpo scaffold ${sha} (${provenance.apps.join(",")})`,
+      theirsLabel: `mpo scaffold ${sha} (${[...provenance.apps, name].join(",")})`,
+    });
+    if (!outcome.changed && !outcome.conflicts.length) {
+      console.log("\n✅ nothing to add (the project already carries this app)");
+      return;
+    }
+    await landTree(projectDir, outcome.mergedTree);
+    writeProvenance(projectDir, {
+      ...provenance,
+      cliVersion: cliVersion() ?? provenance.cliVersion,
+      apps: [...provenance.apps, name],
+    });
+    await finishMerge(projectDir, outcome, `feat: add app ${name} (mpo add-app)`, options);
+  } finally {
+    base.cleanup();
+    theirs.cleanup();
+  }
+}