@multiplatform.one/cli 7.11.0 → 7.16.0

package/src/commands/updateApp.ts

@@ -1,494 +1,126 @@
 /**
- * `mpo update` for scaffolded consumer projects — the modern successor of
- * the old cookiecutter flow (init a fresh project, swap your .git in, merge
- * your changes on top), rebuilt with a TRUE three-way merge:
+ * `mpo update`: bring the monorepo's changes into a project as a three-way
+ * merge that is NEVER committed.
  *
- *   base  = the ORIGINAL scaffold, regenerated from the CLI version recorded
- *           in .mpo.json at init time (published CLIs ship their templates,
- *           so `pnpm dlx @multiplatform.one/cli@<old> init` reproduces it)
- *   ours  = the project's HEAD (all your custom changes)
- *   theirs= a fresh scaffold from the CURRENT CLI version
+ *   base   = the scaffold the project started from: the monorepo at the
+ *            commit recorded in .mpo.json, pruned with the recorded apps
+ *            and services
+ *   ours   = the project's HEAD (every commit the project made)
+ *   theirs = the same scaffold at the commit the running CLI was built from
+ *            (or --source/--checkout)
  *
- * `git merge-tree --write-tree --merge-base=<base>` merges template
- * evolution with your customizations; conflicts land in the worktree with
- * normal conflict markers. An `.updateignore` file (one exact file or
- * directory prefix per line — not globs; `dir/**` is normalized, other
- * glob shapes are refused) pins matching paths to your HEAD version.
+ * Every product app is a renamed apps/one on both sides, so a change to
+ * the One app lands in each of them. The merged tree goes into the index
+ * and worktree; the commit line is printed; a dirty tree is refused up
+ * front. Adopted projects (`mpo adopt`) merge their piece fragments the
+ * same way; projects from the retired template scaffolder reconcile from an
+ * empty base once and are clone-derived afterwards.
  */
 
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
-import spawn from "nano-spawn";
-import { generateVscodeConfig } from "../generateVscode";
+import { isGitUrl, monorepoCheckout, monorepoUrl, resolveSource, type SourceSpec } from "../source";
+import {
+  finishMerge,
+  git,
+  gitOut,
+  landTree,
+  mergeScaffolds,
+  projectRootOf,
+  requireCleanTree,
+} from "./merge";
+import { scaffoldPieces, withSplitPieces } from "./pieces";
 import {
   PROVENANCE_FILE,
   cliVersion,
-  initApp,
+  mpoRange,
   packageJsonName,
   readProvenance,
-  validateName,
   writeProvenance,
-  type InitAppPiece,
-  type InitAppTemplate,
   type MpoProvenance,
-  type ProvenanceTemplate,
-} from "./initApp";
+} from "./provenance";
+import { archiveSubtree, scaffoldToTemp, type TempScaffold } from "./scaffold";
 
 export interface UpdateAppOptions {
-  /** Skip pnpm install after the merge. */
   skipInstall?: boolean;
   /** Override the semver range written for @multiplatform.one/* deps. */
   version?: string;
-  /**
-   * Pre-provenance bootstrap: when .mpo.json is missing, assume the project
-   * was scaffolded by this exact CLI version, write provenance first, then
-   * proceed with the normal update.
-   */
-  assumeVersion?: string;
-  /** Template recorded by the --assume-version bootstrap (default universal). */
-  assumeTemplate?: InitAppTemplate;
-}
-
-async function git(projectDir: string, args: string[], env?: Record<string, string>) {
-  return spawn("git", args, {
-    cwd: projectDir,
-    env: env ? { ...process.env, ...env } : undefined,
-  });
-}
-
-async function gitOut(projectDir: string, args: string[], env?: Record<string, string>) {
-  const result = await git(projectDir, args, env);
-  return result.stdout.trim();
-}
-
-/** Import a directory tree into the project's object database and return a
- *  root-less commit for it (temp index; the worktree is never touched). */
-async function commitTreeFromDir(
-  projectDir: string,
-  dir: string,
-  message: string,
-  parent?: string,
-): Promise<string> {
-  const indexFile = join(mkdtempSync(join(tmpdir(), "mpo-index-")), "index");
-  const env = { GIT_INDEX_FILE: indexFile, GIT_WORK_TREE: dir };
-  await git(projectDir, ["add", "-A", "--force", "--", "."], env);
-  const tree = await gitOut(projectDir, ["write-tree"], env);
-  const commitArgs = parent
-    ? ["commit-tree", tree, "-p", parent, "-m", message]
-    : ["commit-tree", tree, "-m", message];
-  const commit = await gitOut(projectDir, commitArgs);
-  rmSync(indexFile, { force: true });
-  return commit;
-}
-
-/** Scaffold a project with a specific published CLI version into tmp and
- *  return the generated project dir. Falls back to the local generator when
- *  the requested version matches the running CLI (or dlx fails). */
-async function scaffoldBaseline(
-  version: string,
-  name: string,
-  template: ProvenanceTemplate,
-  mpoVersion: string,
-  pieces: InitAppPiece[],
-): Promise<{ dir: string; cleanup: () => void }> {
-  const parent = mkdtempSync(join(tmpdir(), "mpo-update-"));
-  const cleanup = () => rmSync(parent, { recursive: true, force: true });
-  const current = cliVersion();
-  const templateFlag =
-    template === "none" ? ["--pieces-only"] : template === "app" ? ["--web"] : ["--universal"];
-  // The consumer scaffolder (initApp + templates) shipped in 6.3.0 —
-  // earlier CLIs only had the monorepo-clone init and cannot regenerate a
-  // scaffold baseline. Pieces-only scaffolds (`mpo init --pieces-only`, the
-  // baseline of ADOPTED projects) shipped in 6.6.0 alongside `mpo adopt`;
-  // adopted provenance is always written by ≥6.6 CLIs, so the gate only
-  // trips on hand-written .mpo.json files.
-  const [major = 0, minor = 0] = version.split(".").map(Number);
-  const scaffoldCapable =
-    template === "none"
-      ? major > 6 || (major === 6 && minor >= 6)
-      : major > 6 || (major === 6 && minor >= 3);
-  // Composable pieces (--frappe/--keycloak/--gnome/--vscode/--webext)
-  // shipped in 6.5.0 — older published CLIs reject the flags. A 6.3/6.4
-  // baseline is scaffolded WITHOUT pieces: piece files then appear as
-  // ours-only additions relative to that base, which three-way merge keeps
-  // cleanly (they can't have come from those CLIs in the first place).
-  const piecesCapable = major > 6 || (major === 6 && minor >= 5);
-  const pieceFlags = piecesCapable ? pieces.map((piece) => `--${piece}`) : [];
-  if (pieces.length && scaffoldCapable && !piecesCapable && version !== current) {
-    console.warn(
-      `⚠️  @multiplatform.one/cli@${version} predates composable pieces (6.5.0); ` +
-        "the merge base is scaffolded without them.",
-    );
-  }
-  if (!scaffoldCapable) {
-    // The local generator is exact for the running version — the capability
-    // gate only matters when an OLDER published CLI must be dlx'd.
-    if (version !== current) {
-      console.warn(
-        template === "none"
-          ? `⚠️  @multiplatform.one/cli@${version} predates pieces-only baselines (6.6.0); ` +
-              "using the current CLI's piece templates as the merge base " +
-              "(the merge degrades to two-way: template changes since that version won't land)."
-          : `⚠️  @multiplatform.one/cli@${version} predates the consumer scaffolder (6.3.0); ` +
-              "using the current CLI's template as the merge base.",
-      );
-    }
-  } else if (version !== current) {
-    // Older published CLIs reject flags they don't know (--skip-git), so
-    // only the stable flag set is passed; a scaffold-side git repo is
-    // harmless (index operations never descend into nested .git dirs).
-    for (let attempt = 1; attempt <= 2; attempt++) {
-      try {
-        await spawn(
-          "pnpm",
-          [
-            "--package",
-            `@multiplatform.one/cli@${version}`,
-            "dlx",
-            "mpo",
-            "init",
-            name,
-            "--yes",
-            "--skip-install",
-            "--mpo-version",
-            mpoVersion,
-            ...templateFlag,
-            ...pieceFlags,
-          ],
-          { cwd: parent, stdio: "inherit" },
-        );
-        const dir = join(parent, name);
-        // Pieces-only trees may not contain a root package.json (not every
-        // piece ships a root fragment) — provenance is their reliable marker.
-        const marker = template === "none" ? PROVENANCE_FILE : "package.json";
-        if (existsSync(join(dir, marker))) return { dir, cleanup };
-        console.warn(`⚠️  dlx scaffold for @multiplatform.one/cli@${version} produced no project`);
-        break;
-      } catch {
-        rmSync(join(parent, name), { recursive: true, force: true });
-        if (attempt === 2) {
-          console.warn(
-            `⚠️  could not scaffold baseline with @multiplatform.one/cli@${version} (network?);`,
-          );
-        }
-      }
-    }
-    console.warn("   falling back to the current CLI's template as the merge base.");
-  }
-  const previousCwd = process.cwd();
-  process.chdir(parent);
-  try {
-    await initApp(name, {
-      skipInstall: true,
-      skipGit: true,
-      yes: true,
-      template,
-      version: mpoVersion,
-      pieces,
-    });
-  } finally {
-    process.chdir(previousCwd);
-  }
-  return { dir: join(parent, name), cleanup };
-}
-
-/** Return a tree derived from `tree` where every path matching `pins` is
- *  replaced by its content in `headCommit` (removed when absent there).
- *  Pure index plumbing — the worktree is untouched. */
-async function pinPathsToHead(
-  projectDir: string,
-  tree: string,
-  headCommit: string,
-  pins: string[],
-): Promise<string> {
-  const indexFile = join(mkdtempSync(join(tmpdir(), "mpo-pin-")), "index");
-  const env = { GIT_INDEX_FILE: indexFile };
-  await git(projectDir, ["read-tree", tree], env);
-  for (const pin of pins) {
-    // Paths under the pin in the merged tree (to drop when HEAD lacks them).
-    const inTree = await gitOut(projectDir, ["ls-tree", "-r", "--name-only", tree, "--", pin], env)
-      .then((out) => out.split("\n").filter(Boolean))
-      .catch(() => [] as string[]);
-    for (const path of inTree) {
-      await git(projectDir, ["update-index", "--force-remove", "--", path], env).catch(() => {});
-    }
-    // HEAD's entries for the pin (restored verbatim).
-    const headEntries = await gitOut(
-      projectDir,
-      ["ls-tree", "-r", headCommit, "--", pin],
-      env,
-    ).catch(() => "");
-    for (const line of headEntries.split("\n").filter(Boolean)) {
-      // "<mode> blob <oid>\t<path>"
-      const match = line.match(/^(\d+) \S+ ([0-9a-f]+)\t(.+)$/);
-      if (!match) continue;
-      await git(
-        projectDir,
-        ["update-index", "--add", "--cacheinfo", `${match[1]},${match[2]},${match[3]}`],
-        env,
-      ).catch(() => {});
-    }
-  }
-  const pinned = await gitOut(projectDir, ["write-tree"], env);
-  rmSync(indexFile, { force: true });
-  return pinned;
-}
-
-// ── package.json conflict auto-resolution ─────────────────────────
-//
-// The dominant conflict class in real updates is dependency-range drift:
-// the project bumped a range between updates (ours ^6.4.2) while the new
-// template carries its own (theirs ^6.4.3). Both sides changed the same
-// JSON entry, so textual merge punts — but the resolution is mechanical:
-// take the newer minimum version. A structural three-way merge handles it.
-
-const UNRESOLVED = Symbol("unresolved");
-/** Deleted-on-one-side sentinel (distinct from a key that never existed). */
-const ABSENT = Symbol("absent");
-
-const DEP_MAP_KEYS = new Set([
-  "dependencies",
-  "devDependencies",
-  "peerDependencies",
-  "optionalDependencies",
-  "overrides",
-  "resolutions",
-]);
-
-/** Minimum concrete version of a simple range (`^x.y.z`, `~x.y.z`,
- *  `x.y.z`, optional prerelease). Anything fancier is not auto-resolved. */
-function rangeMinimum(range: unknown): [number, number, number] | undefined {
-  if (typeof range !== "string") return undefined;
-  const match = range.match(/^[\^~]?(\d+)\.(\d+)\.(\d+)(?:-[\w.]+)?$/);
-  if (!match) return undefined;
-  return [Number(match[1]), Number(match[2]), Number(match[3])];
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+  /** Path or url to update from (default: the CLI's recorded source). */
+  source?: string;
+  /** Commit, tag or branch at that source (default: the CLI's source commit). */
+  checkout?: string;
+  verbose?: boolean;
 }
 
-function jsonEqual(a: unknown, b: unknown): boolean {
-  return JSON.stringify(a) === JSON.stringify(b);
+function isSha(ref: string): boolean {
+  return /^[0-9a-f]{40}$/.test(ref);
 }
 
-function mergeNode(
-  base: unknown,
-  ours: unknown,
-  theirs: unknown,
-  inDepMap: boolean,
-): unknown | typeof UNRESOLVED | typeof ABSENT {
-  if (jsonEqual(ours, theirs)) return ours === undefined ? ABSENT : ours;
-  // Only one side diverged from base → that side wins (undefined = deletion).
-  if (jsonEqual(theirs, base)) return ours === undefined ? ABSENT : ours;
-  if (jsonEqual(ours, base)) return theirs === undefined ? ABSENT : theirs;
-  // Both diverged. Objects merge key-by-key; dep ranges take the newer
-  // minimum; everything else is a genuine conflict.
-  if (isPlainObject(ours) && isPlainObject(theirs)) {
-    const baseObject = isPlainObject(base) ? base : {};
-    const merged: Record<string, unknown> = {};
-    const keys = [...Object.keys(ours), ...Object.keys(theirs).filter((key) => !(key in ours))];
-    for (const key of keys) {
-      const child = mergeNode(
-        baseObject[key],
-        ours[key],
-        theirs[key],
-        inDepMap || DEP_MAP_KEYS.has(key),
-      );
-      if (child === UNRESOLVED) return UNRESOLVED;
-      if (child !== ABSENT) merged[key] = child;
-    }
-    return merged;
-  }
-  if (inDepMap) {
-    const oursMin = rangeMinimum(ours);
-    const theirsMin = rangeMinimum(theirs);
-    if (oursMin && theirsMin) {
-      for (let i = 0; i < 3; i++) {
-        if (oursMin[i]! > theirsMin[i]!) return ours;
-        if (oursMin[i]! < theirsMin[i]!) return theirs;
-      }
-      return theirs; // equal minimums, different spelling — template wins
-    }
-  }
-  return UNRESOLVED;
+/** The commit a source spec names, when it can be known without scaffolding. */
+async function resolveSha(spec: SourceSpec): Promise<string | undefined> {
+  if (isSha(spec.ref)) return spec.ref;
+  if (isGitUrl(spec.source)) return undefined;
+  return gitOut(spec.source, ["rev-parse", "--verify", `${spec.ref}^{commit}`]).catch(
+    () => undefined,
+  );
 }
 
-/** Structural three-way merge of package.json content. Returns the merged
- *  object, or undefined when a divergence can't be auto-resolved (the file
- *  then keeps its textual conflict markers for manual resolution). */
-export function threeWayMergePackageJson(
-  base: string | undefined,
-  ours: string,
-  theirs: string,
-): Record<string, unknown> | undefined {
-  let baseJson: unknown;
-  let oursJson: unknown;
-  let theirsJson: unknown;
-  try {
-    baseJson = base === undefined ? {} : JSON.parse(base);
-    oursJson = JSON.parse(ours);
-    theirsJson = JSON.parse(theirs);
-  } catch {
-    return undefined;
-  }
-  if (!isPlainObject(oursJson) || !isPlainObject(theirsJson)) return undefined;
-  const merged = mergeNode(baseJson, oursJson, theirsJson, false);
-  if (merged === UNRESOLVED || merged === ABSENT || !isPlainObject(merged)) return undefined;
-  return merged;
+// pnpm-lock.yaml stays pinned to HEAD through the merge, so a merge that
+// removes .pnpmfile.cjs leaves its checksum behind, and pnpm re-resolves every
+// dependency over the mismatch instead of keeping the lockfile's pins.
+async function dropStalePnpmfileChecksum(projectDir: string): Promise<void> {
+  const lockfile = join(projectDir, "pnpm-lock.yaml");
+  if (existsSync(join(projectDir, ".pnpmfile.cjs")) || !existsSync(lockfile)) return;
+  const lock = readFileSync(lockfile, "utf-8");
+  const stripped = lock.replace(/^pnpmfileChecksum: .*\n\n?/m, "");
+  if (stripped === lock) return;
+  writeFileSync(lockfile, stripped);
+  await git(projectDir, ["add", "--", "pnpm-lock.yaml"]);
 }
 
-/** Replace auto-resolvable conflicted package.json files in `mergedTree`
- *  with their structural merge. Pure index plumbing, worktree untouched. */
-async function autoResolveDependencyConflicts(
-  projectDir: string,
-  mergedTree: string,
-  conflicts: string[],
-  baseCommit: string,
-  headCommit: string,
-  nextCommit: string,
-): Promise<{ tree: string; conflicts: string[]; resolved: string[] }> {
-  const candidates = conflicts.filter((file) => basename(file) === "package.json");
-  if (!candidates.length) return { tree: mergedTree, conflicts, resolved: [] };
-
-  const scratch = mkdtempSync(join(tmpdir(), "mpo-resolve-"));
-  const resolved: { path: string; oid: string }[] = [];
-  try {
-    for (const file of candidates) {
-      const show = (commit: string) =>
-        gitOut(projectDir, ["show", `${commit}:${file}`]).catch(() => undefined);
-      const [base, ours, theirs] = await Promise.all([
-        show(baseCommit),
-        show(headCommit),
-        show(nextCommit),
-      ]);
-      // Add/delete conflicts stay manual — only both-sides-present merges.
-      if (ours === undefined || theirs === undefined) continue;
-      const merged = threeWayMergePackageJson(base, ours, theirs);
-      if (!merged) continue;
-      const blobFile = join(scratch, "blob.json");
-      writeFileSync(blobFile, `${JSON.stringify(merged, null, 2)}\n`);
-      const oid = await gitOut(projectDir, ["hash-object", "-w", "--", blobFile]);
-      resolved.push({ path: file, oid });
-    }
-    if (!resolved.length) return { tree: mergedTree, conflicts, resolved: [] };
-
-    const indexFile = join(scratch, "index");
-    const env = { GIT_INDEX_FILE: indexFile };
-    await git(projectDir, ["read-tree", mergedTree], env);
-    for (const entry of resolved) {
-      await git(
-        projectDir,
-        ["update-index", "--add", "--cacheinfo", `100644,${entry.oid},${entry.path}`],
-        env,
-      );
-    }
-    const tree = await gitOut(projectDir, ["write-tree"], env);
-    const resolvedPaths = new Set(resolved.map((entry) => entry.path));
-    return {
-      tree,
-      conflicts: conflicts.filter((file) => !resolvedPaths.has(file)),
-      resolved: [...resolvedPaths],
-    };
-  } finally {
-    rmSync(scratch, { recursive: true, force: true });
-  }
+function tempDir(): { dir: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), "mpo-update-"));
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
 }
 
 /**
- * Pre-provenance bootstrap (`mpo update --assume-version <cliVersion>`):
- * projects scaffolded by CLIs older than the provenance file (≤6.3.0) have
- * no .mpo.json. The user asserts which CLI version (and template) produced
- * the project; provenance is written and committed, then the normal update
- * proceeds against that baseline.
+ * templates/pieces as they were at another CLI version: the monorepo tag
+ * v<version>, from the CLI's source (or --source). Falls back to the
+ * current templates with a warning, which degrades that merge to two-way.
  */
-async function bootstrapProvenance(
-  projectDir: string,
+async function piecesRootAt(
+  version: string,
   options: UpdateAppOptions,
-): Promise<MpoProvenance> {
-  const version = options.assumeVersion!;
-  if (!/^\d+\.\d+\.\d+(?:-[\w.]+)?$/u.test(version)) {
-    throw new Error(`--assume-version must be an exact CLI version (e.g. 6.3.0), got "${version}"`);
-  }
-  const rawName = packageJsonName(projectDir);
-  if (!rawName) {
-    throw new Error(
-      `Could not derive the project name from package.json — create ${PROVENANCE_FILE} by hand ` +
-        "with { template, cliVersion, name } instead",
+): Promise<{ root?: string; cleanup: () => void }> {
+  if (version === cliVersion()) return { cleanup: () => {} };
+  const scratch = tempDir();
+  const source = options.source ?? monorepoCheckout() ?? monorepoUrl;
+  try {
+    await archiveSubtree(source, `v${version}`, "public/cli/templates/pieces", scratch.dir);
+    return { root: join(scratch.dir, "public/cli/templates/pieces"), cleanup: scratch.cleanup };
+  } catch {
+    scratch.cleanup();
+    console.warn(
+      `⚠️  could not read templates/pieces at v${version} from ${source}; ` +
+        "using the current pieces as the merge base (changes since that version won't land).",
     );
+    return { cleanup: () => {} };
   }
-  const provenance: MpoProvenance = {
-    template: options.assumeTemplate ?? "universal",
-    cliVersion: version,
-    name: validateName(rawName),
-    mpoVersion: `^${version}`,
-    pieces: [],
-  };
-  console.log(
-    `\nBootstrapping provenance: assuming this project was scaffolded by ` +
-      `cli@${version} (${provenance.template} template).`,
-  );
-  writeProvenance(projectDir, provenance);
-  await git(projectDir, ["add", "--", PROVENANCE_FILE]);
-  await git(projectDir, [
-    "commit",
-    "--quiet",
-    "-m",
-    `chore: record assumed mpo scaffold provenance (cli@${version})`,
-  ]).catch(() => {
-    console.warn("⚠️  git commit failed (missing git identity?) — provenance left staged.");
-  });
-  return provenance;
 }
 
-export async function updateApp(options: UpdateAppOptions = {}): Promise<void> {
-  const projectDir = await gitOut(process.cwd(), ["rev-parse", "--show-toplevel"]).catch(() => {
-    throw new Error("mpo update must run inside a git repository");
-  });
-
-  // Clean tree required — the merge lands in the worktree.
-  await git(projectDir, ["diff", "--quiet"]).catch(() => {
-    throw new Error("mpo update requires a clean working tree (unstaged changes present)");
-  });
-  await git(projectDir, ["diff", "--cached", "--quiet"]).catch(() => {
-    throw new Error("mpo update requires a clean working tree (staged changes present)");
-  });
-
-  let provenance = readProvenance(projectDir);
-  if (options.assumeVersion) {
-    if (provenance) {
-      throw new Error(
-        `--assume-version is for projects without ${PROVENANCE_FILE} — ` +
-          `this project already has provenance (cli@${provenance.cliVersion})`,
-      );
-    }
-    provenance = await bootstrapProvenance(projectDir, options);
-  }
-  if (!provenance) {
-    throw new Error(
-      `${PROVENANCE_FILE} 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> [...]",
-    );
-  }
-
+async function updateAdopted(
+  projectDir: string,
+  provenance: MpoProvenance,
+  options: UpdateAppOptions,
+): Promise<void> {
   const currentVersion = cliVersion() ?? "0.0.0";
-  const targetMpoRange = options.version
-    ? options.version.startsWith("^") || options.version.startsWith("~")
-      ? options.version
-      : `^${options.version}`
-    : `^${currentVersion}`;
-
-  const adopted = provenance.template === "none";
-  const firstReconcile = adopted && provenance.reconciled === false;
-
-  console.log(`\nmpo update: ${provenance.cliVersion} → ${currentVersion}`);
-  console.log(`  template: ${provenance.template}${adopted ? " (adopted)" : ""}`);
-  if (provenance.pieces.length) console.log(`  pieces:   ${provenance.pieces.join(", ")}`);
-  console.log(`  project:  ${provenance.name}\n`);
+  const targetRange = mpoRange(options.version, currentVersion);
+  const name = provenance.name!;
+  const firstReconcile = provenance.reconciled === false;
+  console.log(`\nmpo update (adopted): cli ${provenance.cliVersion} → ${currentVersion}`);
+  console.log(`  pieces  ${provenance.pieces.join(", ")}`);
+  console.log(`  project ${name}\n`);
   if (firstReconcile) {
     console.log("⚠️  FIRST UPDATE AFTER ADOPTION: piece files are reconciled against the");
     console.log("   piece templates from an empty merge base. Diffs and conflicts on");
@@ -496,238 +128,193 @@ export async function updateApp(options: UpdateAppOptions = {}): Promise<void> {
     console.log("   commit. Later updates merge three-way and stay quiet.\n");
   }
 
-  // 1. Regenerate the ORIGINAL scaffold (merge base). Pieces recorded in
-  // provenance are reproduced in BOTH baselines so piece files merge as
-  // template content, not as phantom diffs. An adopted project's first
-  // update has NO original scaffold — the tool never wrote a file there —
-  // so its honest merge base is the empty tree.
-  let base: { dir: string; cleanup: () => void };
-  if (firstReconcile) {
-    console.log("Using an empty merge base (first update after adoption)...");
-    const dir = mkdtempSync(join(tmpdir(), "mpo-update-"));
-    base = { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
-  } else {
-    console.log(`Scaffolding merge base (cli@${provenance.cliVersion})...`);
-    base = await scaffoldBaseline(
-      provenance.cliVersion,
-      provenance.name,
-      provenance.template,
-      provenance.mpoVersion,
-      provenance.pieces,
-    );
-  }
-
-  // 2. Generate the CURRENT scaffold (theirs).
-  console.log(`Scaffolding update target (cli@${currentVersion})...`);
-  const next = await scaffoldBaseline(
-    currentVersion,
-    provenance.name,
-    provenance.template,
-    targetMpoRange,
-    provenance.pieces,
-  );
-
-  // .mpo.json is TOOL-owned, never merged: pre-provenance CLIs (≤6.3.0)
-  // didn't write it, so leaving it in the scaffolds guarantees an add/add
-  // phantom conflict on every honest old-baseline update. It is stripped
-  // from both synthetic trees and written authoritatively after the merge.
-  rmSync(join(base.dir, ".mpo.json"), { force: true });
-  rmSync(join(next.dir, ".mpo.json"), { force: true });
-
+  const base = tempDir();
+  const theirs = tempDir();
+  let oldPieces: { root?: string; cleanup: () => void } = { cleanup: () => {} };
+  let pieces = provenance.pieces;
   try {
-    // 3. Three-way merge: base → HEAD (ours) vs base → next (theirs).
-    const head = await gitOut(projectDir, ["rev-parse", "HEAD"]);
-    const baseCommit = await commitTreeFromDir(
-      projectDir,
-      base.dir,
-      `mpo scaffold ${provenance.template}@${provenance.cliVersion}`,
-    );
-    const nextCommit = await commitTreeFromDir(
-      projectDir,
-      next.dir,
-      `mpo scaffold ${provenance.template}@${currentVersion}`,
-      baseCommit,
-    );
-
-    let mergedTree: string;
-    let conflicts: string[] = [];
-    try {
-      const out = await gitOut(projectDir, [
-        "merge-tree",
-        "--write-tree",
-        "--name-only",
-        `--merge-base=${baseCommit}`,
-        head,
-        nextCommit,
-      ]);
-      mergedTree = out.split("\n")[0]!.trim();
-    } catch (err) {
-      // Exit code 1 = conflicts. Output format: <tree>\n<conflicted file
-      // names, one per line>\n\n<informational messages> — only the names
-      // section (up to the blank line) lists conflicted paths.
-      const stdout = (err as { stdout?: string }).stdout ?? "";
-      const lines = stdout.split("\n");
-      if (!lines[0]?.trim()) throw err;
-      mergedTree = lines[0].trim();
-      const blank = lines.indexOf("", 1);
-      conflicts = lines
-        .slice(1, blank === -1 ? undefined : blank)
-        .map((line) => line.trim())
-        .filter(Boolean);
-    }
-
-    // The merged .mpo.json can interleave ours/theirs lines (add/add
-    // two-way merge) — the post-merge provenance is always written
-    // authoritatively below. `reconciled: false` is intentionally NOT
-    // carried over: a successful update reconciles the adopted project,
-    // so later updates scaffold their merge base from the recorded version.
-    const finalProvenance: MpoProvenance = {
-      template: provenance.template,
-      cliVersion: currentVersion,
-      name: provenance.name,
-      mpoVersion: targetMpoRange,
-      pieces: provenance.pieces,
-    };
-
-    // .updateignore entries (+ pnpm-lock.yaml) pin to the pre-update HEAD.
-    // Pins are applied to the MERGED TREE before committing, so a clean
-    // update never leaves the tree dirty.
-    //
-    // Entries are EXACT FILES or DIRECTORY PREFIXES — the pin machinery
-    // rides `git ls-tree -- <path>`, which does prefix matching, not
-    // fnmatch. A silently dead ignore rule is the worst failure mode, so
-    // the one natural glob spelling (`dir/**`, `dir/*`) is normalized to
-    // its directory and anything else glob-shaped is refused loudly.
-    const pins = ["pnpm-lock.yaml"];
-    const updateignore = join(projectDir, ".updateignore");
-    if (existsSync(updateignore)) {
-      for (const line of readFileSync(updateignore, "utf-8").split("\n")) {
-        const pattern = line.trim();
-        if (!pattern || pattern.startsWith("#")) continue;
-        const normalized = pattern.replace(/\/\*{1,2}$/, "");
-        if (/[*?[\]]/.test(normalized)) {
-          throw new Error(
-            `.updateignore: "${pattern}" looks like a glob, but entries are ` +
-              "exact files or directory prefixes (a glob here would silently " +
-              "pin nothing). List the file or directory instead.",
-          );
-        }
-        pins.push(normalized.replace(/\/+$/, ""));
+    if (!firstReconcile) {
+      oldPieces = await piecesRootAt(provenance.cliVersion, options);
+      scaffoldPieces(base.dir, {
+        name,
+        mpoVersion: provenance.mpoVersion ?? `^${provenance.cliVersion}`,
+        pieces: provenance.pieces,
+        root: oldPieces.root,
+      });
+      pieces = withSplitPieces(provenance.pieces, oldPieces.root);
+      if (pieces !== provenance.pieces) {
+        console.log("  frappe-bench added: the frappe piece no longer carries the dev bench\n");
       }
     }
-    mergedTree = await pinPathsToHead(projectDir, mergedTree, head, pins);
-    // Pinning resolves any conflict inside a pinned path (the pre-update
-    // HEAD content wins by definition).
-    conflicts = conflicts.filter(
-      (file) => !pins.some((pin) => file === pin || file.startsWith(`${pin}/`)),
-    );
+    scaffoldPieces(theirs.dir, { name, mpoVersion: targetRange, pieces });
 
-    // Dependency-range drift in package.json files resolves mechanically
-    // (newer minimum version wins) — don't punt those to the user.
-    const autoResolved = await autoResolveDependencyConflicts(
+    const outcome = await mergeScaffolds({
       projectDir,
-      mergedTree,
-      conflicts,
-      baseCommit,
-      head,
-      nextCommit,
-    );
-    mergedTree = autoResolved.tree;
-    conflicts = autoResolved.conflicts;
-    for (const file of autoResolved.resolved) {
-      console.log(`   auto-resolved: ${file} (dependency ranges)`);
-    }
-
-    // No-op detection: identical trees mean the project already carries the
-    // current template — don't stack empty merge commits.
-    const headTree = await gitOut(projectDir, ["rev-parse", `${head}^{tree}`]);
-    if (!conflicts.length && mergedTree === headTree) {
+      baseDir: firstReconcile ? undefined : base.dir,
+      theirsDir: theirs.dir,
+      baseLabel: `mpo pieces ${provenance.cliVersion}`,
+      theirsLabel: `mpo pieces ${currentVersion}`,
+    });
+    const next: MpoProvenance = {
+      ...provenance,
+      cliVersion: currentVersion,
+      mpoVersion: targetRange,
+      pieces,
+      reconciled: undefined,
+    };
+    if (!outcome.changed && !outcome.conflicts.length) {
       if (
-        provenance.cliVersion !== finalProvenance.cliVersion ||
-        provenance.mpoVersion !== finalProvenance.mpoVersion ||
-        provenance.reconciled === false
+        provenance.cliVersion !== currentVersion ||
+        provenance.mpoVersion !== targetRange ||
+        pieces !== provenance.pieces ||
+        firstReconcile
       ) {
-        writeProvenance(projectDir, finalProvenance);
-        await git(projectDir, ["add", "--", ".mpo.json"]);
-        await git(projectDir, [
-          "commit",
-          "--quiet",
-          "-m",
-          `chore: record mpo template provenance ${currentVersion}`,
-        ]);
-        console.log("\n✅ already up to date (provenance refreshed)");
+        writeProvenance(projectDir, next);
+        console.log(`\n✅ already up to date; ${PROVENANCE_FILE} refreshed — commit it`);
       } else {
         console.log("\n✅ already up to date");
       }
       return;
     }
+    await landTree(projectDir, outcome.mergedTree);
+    writeProvenance(projectDir, next);
+    await finishMerge(
+      projectDir,
+      outcome,
+      `chore: mpo update ${provenance.cliVersion} → ${currentVersion}`,
+      options,
+    );
+  } finally {
+    base.cleanup();
+    theirs.cleanup();
+    oldPieces.cleanup();
+  }
+}
 
-    let cleanMergeMessage: string | undefined;
-    if (!conflicts.length) {
-      const message = `chore: mpo update ${provenance.cliVersion} → ${currentVersion}`;
-      const mergeCommit = await gitOut(projectDir, [
-        "commit-tree",
-        mergedTree,
-        "-p",
-        head,
-        "-p",
-        nextCommit,
-        "-m",
-        message,
-      ]);
-      await git(projectDir, ["update-ref", "HEAD", mergeCommit]);
-      await git(projectDir, ["reset", "--hard", "HEAD"]);
-      // Tool-owned outputs belong to the update commit: provenance + the
-      // regenerated .vscode config.
-      writeProvenance(projectDir, finalProvenance);
-      try {
-        await generateVscodeConfig(projectDir);
-      } catch {
-        // best-effort (older layouts)
-      }
-      await git(projectDir, ["add", "--", ".mpo.json", ".vscode"]);
-      await git(projectDir, ["commit", "--amend", "--no-edit", "--quiet"]);
-      cleanMergeMessage = message;
-    } else {
-      // Land the merged tree (with conflict markers) in index + worktree for
-      // manual resolution; pins are already part of the tree.
-      await git(projectDir, ["read-tree", "-u", "--reset", mergedTree]);
-      writeProvenance(projectDir, finalProvenance);
-      console.log("\n⚠️  merge conflicts — resolve the markers, then commit:");
-      for (const file of conflicts) console.log(`   ${file}`);
-      console.log(
-        `\n   git add -A && git commit -m "chore: mpo update ${provenance.cliVersion} → ${currentVersion}"`,
-      );
-    }
+async function updateClone(
+  projectDir: string,
+  provenance: MpoProvenance,
+  options: UpdateAppOptions,
+): Promise<void> {
+  const currentVersion = cliVersion() ?? "0.0.0";
+  const recorded = provenance.source;
+  const templateEra = !recorded;
+  const apps = provenance.apps;
+  if (!apps.length) {
+    throw new Error(`${PROVENANCE_FILE} lists no product apps — nothing to update`);
+  }
 
-    if (conflicts.length && !options.skipInstall) {
-      console.log("\nSkipping pnpm install until conflicts are resolved (then run: pnpm install).");
-    } else if (!options.skipInstall) {
-      console.log("\nInstalling dependencies...");
-      await spawn("pnpm", ["install"], { cwd: projectDir, stdio: "inherit" });
-      // The merge changed dependency ranges, so the regenerated lockfile
-      // belongs with the update: amend it into the clean-merge commit
-      // (conflict resolutions commit manually and pick it up there).
-      if (!conflicts.length) {
-        const lockDirty = await git(projectDir, ["diff", "--quiet", "--", "pnpm-lock.yaml"]).then(
-          () => false,
-          () => true,
-        );
-        if (lockDirty) {
-          await git(projectDir, ["add", "--", "pnpm-lock.yaml"]);
-          await git(projectDir, ["commit", "--amend", "--no-edit", "--quiet"]);
-        }
-      }
+  // theirs: the CLI's source commit unless --source/--checkout say otherwise.
+  const nextSpec = resolveSource({ source: options.source, checkout: options.checkout });
+  if (nextSpec.warning) console.warn(`⚠️  ${nextSpec.warning}`);
+  // base: the recorded commit, read from --source when given (a mirror or a
+  // local clone must hold that commit too).
+  const baseSource = options.source ?? recorded?.url ?? nextSpec.source;
+  const targetRange = options.version ? mpoRange(options.version) : undefined;
+
+  console.log(
+    `\nmpo update: ${recorded ? recorded.sha.slice(0, 12) : "(template-era project)"} → ${nextSpec.source} @ ${nextSpec.ref}`,
+  );
+  console.log(`  apps      ${apps.join(", ")}`);
+  console.log(
+    `  services  ${provenance.services.length ? provenance.services.join(", ") : "(none)"}`,
+  );
+  if (templateEra) {
+    console.log("\n⚠️  This project came from the retired template scaffolder, so there is no");
+    console.log("   scaffold to use as a merge base. The monorepo's One app is merged in");
+    console.log("   from an empty base once: expect additions and conflicts on shared files.");
+    console.log("   Pin what is yours in .updateignore first if needed. After this update the");
+    console.log(`   project is clone-derived and later updates merge three-way.\n`);
+  }
+
+  if (recorded && !options.version) {
+    const nextSha = await resolveSha(nextSpec);
+    if (nextSha === recorded.sha) {
+      console.log("\n✅ already up to date");
+      return;
     }
+  }
 
-    // Reported last — the lockfile amend above rewrites the commit, so an
-    // earlier print would show a hash that no longer exists.
-    if (cleanMergeMessage) {
-      const finalHash = await gitOut(projectDir, ["rev-parse", "--short", "HEAD"]);
-      console.log(`\n✅ merged cleanly → ${finalHash} ("${cleanMergeMessage}")`);
+  // Both scaffolds carry the project's own root package name, so the name
+  // never reads as a change (an empty base would otherwise conflict on it).
+  const name = packageJsonName(projectDir) ?? basename(projectDir);
+  const theirs = await scaffoldToTemp({
+    source: nextSpec.source,
+    ref: nextSpec.ref,
+    apps,
+    services: provenance.services,
+    mpoVersion: targetRange,
+    name,
+    verbose: options.verbose,
+  });
+  let base: TempScaffold | undefined;
+  try {
+    const nextSha = theirs.provenance.source!.sha;
+    if (recorded && nextSha === recorded.sha && !options.version) {
+      console.log("\n✅ already up to date");
+      return;
+    }
+    if (recorded) {
+      base = await scaffoldToTemp({
+        source: baseSource,
+        ref: recorded.sha,
+        apps,
+        services: provenance.services,
+        mpoVersion: `^${provenance.cliVersion}`,
+        name,
+        verbose: options.verbose,
+      });
+    }
+    for (const dir of [theirs.dir, base?.dir]) {
+      if (dir) rmSync(join(dir, PROVENANCE_FILE), { force: true });
+    }
+    const outcome = await mergeScaffolds({
+      projectDir,
+      baseDir: base?.dir,
+      theirsDir: theirs.dir,
+      baseLabel: recorded ? `mpo scaffold ${recorded.sha}` : "mpo scaffold (empty base)",
+      theirsLabel: `mpo scaffold ${nextSha}`,
+    });
+    const next: MpoProvenance = {
+      cliVersion: theirs.provenance.cliVersion || currentVersion,
+      source: { sha: nextSha, url: options.source ?? recorded?.url ?? nextSpec.source },
+      apps,
+      services: provenance.services,
+      pieces: [],
+    };
+    const label = `${recorded ? recorded.sha.slice(0, 12) : "template"} → ${nextSha.slice(0, 12)}`;
+    if (!outcome.changed && !outcome.conflicts.length) {
+      writeProvenance(projectDir, next);
+      console.log(`\n✅ already up to date; ${PROVENANCE_FILE} refreshed — commit it`);
+      return;
     }
+    await landTree(projectDir, outcome.mergedTree);
+    await dropStalePnpmfileChecksum(projectDir);
+    writeProvenance(projectDir, next);
+    await finishMerge(projectDir, outcome, `chore: mpo update ${label}`, options);
   } finally {
-    base.cleanup();
-    next.cleanup();
+    theirs.cleanup();
+    base?.cleanup();
+  }
+}
+
+export async function updateApp(options: UpdateAppOptions = {}): Promise<void> {
+  const projectDir = await projectRootOf("mpo update");
+  await requireCleanTree(projectDir, "mpo update");
+  const provenance = readProvenance(projectDir);
+  if (!provenance) {
+    throw new Error(
+      `${PROVENANCE_FILE} not found — this project has no scaffold provenance.\n` +
+        "  - hand-copied piece files from the templates? bring it under management:\n" +
+        "      mpo adopt --<piece> [...]\n" +
+        "  - scaffolded from the monorepo before provenance existed? write .mpo.json:\n" +
+        '      { "cliVersion": "<cli>", "source": { "sha": "<commit>", "url": "<repo>" },\n' +
+        '        "apps": ["<name>"], "services": [], "pieces": [] }',
+    );
+  }
+  if (provenance.template === "none") {
+    await updateAdopted(projectDir, provenance, options);
+    return;
   }
+  await updateClone(projectDir, provenance, options);
 }