@multiplatform.one/cli 7.11.0 → 7.16.0

package/lib/commands/updateApp.mjs

@@ -1,573 +1,256 @@
-import { generateVscodeConfig } from "../generateVscode.mjs";
-import { PROVENANCE_FILE, cliVersion, initApp, packageJsonName, readProvenance, validateName, writeProvenance } from "./initApp.mjs";
-import { basename, join } from "node:path";
+import { PROVENANCE_FILE, cliVersion, mpoRange, packageJsonName, readProvenance, writeProvenance } from "./provenance.mjs";
+import { isGitUrl, monorepoCheckout, monorepoUrl, resolveSource } from "../source.mjs";
+import { finishMerge, git, gitOut, landTree, mergeScaffolds, projectRootOf, requireCleanTree } from "./merge.mjs";
+import { archiveSubtree, scaffoldToTemp } from "./scaffold.mjs";
+import { scaffoldPieces, withSplitPieces } from "./pieces.mjs";
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import spawn from "nano-spawn";
+import { basename, join } from "node:path";
 import { tmpdir } from "node:os";
 
 //#region src/commands/updateApp.ts
 /**
-* `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.
 */
-async function git(projectDir, args, env) {
-	return spawn("git", args, {
-		cwd: projectDir,
-		env: env ? {
-			...process.env,
-			...env
-		} : void 0
-	});
+function isSha(ref) {
+	return /^[0-9a-f]{40}$/.test(ref);
 }
-async function gitOut(projectDir, args, env) {
-	return (await git(projectDir, args, env)).stdout.trim();
+/** The commit a source spec names, when it can be known without scaffolding. */
+async function resolveSha(spec) {
+	if (isSha(spec.ref)) return spec.ref;
+	if (isGitUrl(spec.source)) return void 0;
+	return gitOut(spec.source, [
+		"rev-parse",
+		"--verify",
+		`${spec.ref}^{commit}`
+	]).catch(() => void 0);
 }
-/** 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, dir, message, parent) {
-	const indexFile = join(mkdtempSync(join(tmpdir(), "mpo-index-")), "index");
-	const env = {
-		GIT_INDEX_FILE: indexFile,
-		GIT_WORK_TREE: dir
-	};
+async function dropStalePnpmfileChecksum(projectDir) {
+	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",
-		"-A",
-		"--force",
 		"--",
-		"."
-	], env);
-	const tree = await gitOut(projectDir, ["write-tree"], env);
-	const commit = await gitOut(projectDir, parent ? [
-		"commit-tree",
-		tree,
-		"-p",
-		parent,
-		"-m",
-		message
-	] : [
-		"commit-tree",
-		tree,
-		"-m",
-		message
+		"pnpm-lock.yaml"
 	]);
-	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, name, template, mpoVersion, pieces) {
-	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"];
-	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;
-	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) {
-		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) {
-		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);
-			if (existsSync(join(dir, template === "none" ? ".mpo.json" : "package.json"))) 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);
-	}
+function tempDir() {
+	const dir = mkdtempSync(join(tmpdir(), "mpo-update-"));
 	return {
-		dir: join(parent, name),
-		cleanup
+		dir,
+		cleanup: () => rmSync(dir, {
+			recursive: true,
+			force: true
+		})
 	};
 }
-/** 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, tree, headCommit, pins) {
-	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) {
-		const inTree = await gitOut(projectDir, [
-			"ls-tree",
-			"-r",
-			"--name-only",
-			tree,
-			"--",
-			pin
-		], env).then((out) => out.split("\n").filter(Boolean)).catch(() => []);
-		for (const path of inTree) await git(projectDir, [
-			"update-index",
-			"--force-remove",
-			"--",
-			path
-		], env).catch(() => {});
-		const headEntries = await gitOut(projectDir, [
-			"ls-tree",
-			"-r",
-			headCommit,
-			"--",
-			pin
-		], env).catch(() => "");
-		for (const line of headEntries.split("\n").filter(Boolean)) {
-			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;
-}
-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) {
-	if (typeof range !== "string") return void 0;
-	const match = range.match(/^[\^~]?(\d+)\.(\d+)\.(\d+)(?:-[\w.]+)?$/);
-	if (!match) return void 0;
-	return [
-		Number(match[1]),
-		Number(match[2]),
-		Number(match[3])
-	];
-}
-function isPlainObject(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function jsonEqual(a, b) {
-	return JSON.stringify(a) === JSON.stringify(b);
-}
-function mergeNode(base, ours, theirs, inDepMap) {
-	if (jsonEqual(ours, theirs)) return ours === void 0 ? ABSENT : ours;
-	if (jsonEqual(theirs, base)) return ours === void 0 ? ABSENT : ours;
-	if (jsonEqual(ours, base)) return theirs === void 0 ? ABSENT : theirs;
-	if (isPlainObject(ours) && isPlainObject(theirs)) {
-		const baseObject = isPlainObject(base) ? base : {};
-		const merged = {};
-		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;
-		}
-	}
-	return UNRESOLVED;
-}
-/** 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). */
-function threeWayMergePackageJson(base, ours, theirs) {
-	let baseJson;
-	let oursJson;
-	let theirsJson;
-	try {
-		baseJson = base === void 0 ? {} : JSON.parse(base);
-		oursJson = JSON.parse(ours);
-		theirsJson = JSON.parse(theirs);
-	} catch {
-		return;
-	}
-	if (!isPlainObject(oursJson) || !isPlainObject(theirsJson)) return void 0;
-	const merged = mergeNode(baseJson, oursJson, theirsJson, false);
-	if (merged === UNRESOLVED || merged === ABSENT || !isPlainObject(merged)) return void 0;
-	return merged;
-}
-/** Replace auto-resolvable conflicted package.json files in `mergedTree`
-*  with their structural merge. Pure index plumbing, worktree untouched. */
-async function autoResolveDependencyConflicts(projectDir, mergedTree, conflicts, baseCommit, headCommit, nextCommit) {
-	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 = [];
+/**
+* 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 piecesRootAt(version, options) {
+	if (version === cliVersion()) return { cleanup: () => {} };
+	const scratch = tempDir();
+	const source = options.source ?? monorepoCheckout() ?? "https://git.corp.bitspur.com/multiplatform.one/mpo.git";
 	try {
-		for (const file of candidates) {
-			const show = (commit) => gitOut(projectDir, ["show", `${commit}:${file}`]).catch(() => void 0);
-			const [base, ours, theirs] = await Promise.all([
-				show(baseCommit),
-				show(headCommit),
-				show(nextCommit)
-			]);
-			if (ours === void 0 || theirs === void 0) 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 env = { GIT_INDEX_FILE: join(scratch, "index") };
-		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));
+		await archiveSubtree(source, `v${version}`, "public/cli/templates/pieces", scratch.dir);
 		return {
-			tree,
-			conflicts: conflicts.filter((file) => !resolvedPaths.has(file)),
-			resolved: [...resolvedPaths]
+			root: join(scratch.dir, "public/cli/templates/pieces"),
+			cleanup: scratch.cleanup
 		};
-	} finally {
-		rmSync(scratch, {
-			recursive: true,
-			force: true
-		});
+	} 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: () => {} };
 	}
 }
-/**
-* 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.
-*/
-async function bootstrapProvenance(projectDir, options) {
-	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`);
-	const provenance = {
-		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;
-}
-async function updateApp(options = {}) {
-	const projectDir = await gitOut(process.cwd(), ["rev-parse", "--show-toplevel"]).catch(() => {
-		throw new Error("mpo update must run inside a git repository");
-	});
-	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:
-      mpo update --assume-version <cliVersion> [--template universal|app]
-  - never scaffolded (hand-adopted pieces)? bring it under management:
-      mpo adopt --<piece> [...]`);
+async function updateAdopted(projectDir, provenance, options) {
 	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");
 		console.log("   hand-copied piece files are EXPECTED — resolve the markers and");
 		console.log("   commit. Later updates merge three-way and stay quiet.\n");
 	}
-	let base;
-	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);
-	}
-	console.log(`Scaffolding update target (cli@${currentVersion})...`);
-	const next = await scaffoldBaseline(currentVersion, provenance.name, provenance.template, targetMpoRange, provenance.pieces);
-	rmSync(join(base.dir, ".mpo.json"), { force: true });
-	rmSync(join(next.dir, ".mpo.json"), { force: true });
+	const base = tempDir();
+	const theirs = tempDir();
+	let oldPieces = { cleanup: () => {} };
+	let pieces = provenance.pieces;
 	try {
-		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;
-		let conflicts = [];
-		try {
-			mergedTree = (await gitOut(projectDir, [
-				"merge-tree",
-				"--write-tree",
-				"--name-only",
-				`--merge-base=${baseCommit}`,
-				head,
-				nextCommit
-			])).split("\n")[0].trim();
-		} catch (err) {
-			const lines = (err.stdout ?? "").split("\n");
-			if (!lines[0]?.trim()) throw err;
-			mergedTree = lines[0].trim();
-			const blank = lines.indexOf("", 1);
-			conflicts = lines.slice(1, blank === -1 ? void 0 : blank).map((line) => line.trim()).filter(Boolean);
+		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");
 		}
-		const finalProvenance = {
-			template: provenance.template,
+		scaffoldPieces(theirs.dir, {
+			name,
+			mpoVersion: targetRange,
+			pieces
+		});
+		const outcome = await mergeScaffolds({
+			projectDir,
+			baseDir: firstReconcile ? void 0 : base.dir,
+			theirsDir: theirs.dir,
+			baseLabel: `mpo pieces ${provenance.cliVersion}`,
+			theirsLabel: `mpo pieces ${currentVersion}`
+		});
+		const next = {
+			...provenance,
 			cliVersion: currentVersion,
-			name: provenance.name,
-			mpoVersion: targetMpoRange,
-			pieces: provenance.pieces
+			mpoVersion: targetRange,
+			pieces,
+			reconciled: void 0
 		};
-		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(/\/+$/, ""));
-		}
-		mergedTree = await pinPathsToHead(projectDir, mergedTree, head, pins);
-		conflicts = conflicts.filter((file) => !pins.some((pin) => file === pin || file.startsWith(`${pin}/`)));
-		const autoResolved = await autoResolveDependencyConflicts(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)`);
-		const headTree = await gitOut(projectDir, ["rev-parse", `${head}^{tree}`]);
-		if (!conflicts.length && mergedTree === headTree) {
-			if (provenance.cliVersion !== finalProvenance.cliVersion || provenance.mpoVersion !== finalProvenance.mpoVersion || provenance.reconciled === false) {
-				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)");
+		if (!outcome.changed && !outcome.conflicts.length) {
+			if (provenance.cliVersion !== currentVersion || provenance.mpoVersion !== targetRange || pieces !== provenance.pieces || firstReconcile) {
+				writeProvenance(projectDir, next);
+				console.log(`\n✅ already up to date; ${PROVENANCE_FILE} refreshed — commit it`);
 			} else console.log("\n✅ already up to date");
 			return;
 		}
-		let cleanMergeMessage;
-		if (!conflicts.length) {
-			const message = `chore: mpo update ${provenance.cliVersion} → ${currentVersion}`;
-			await git(projectDir, [
-				"update-ref",
-				"HEAD",
-				await gitOut(projectDir, [
-					"commit-tree",
-					mergedTree,
-					"-p",
-					head,
-					"-p",
-					nextCommit,
-					"-m",
-					message
-				])
-			]);
-			await git(projectDir, [
-				"reset",
-				"--hard",
-				"HEAD"
-			]);
-			writeProvenance(projectDir, finalProvenance);
-			try {
-				await generateVscodeConfig(projectDir);
-			} catch {}
-			await git(projectDir, [
-				"add",
-				"--",
-				".mpo.json",
-				".vscode"
-			]);
-			await git(projectDir, [
-				"commit",
-				"--amend",
-				"--no-edit",
-				"--quiet"
-			]);
-			cleanMergeMessage = message;
-		} else {
-			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}"`);
+		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();
+	}
+}
+async function updateClone(projectDir, provenance, options) {
+	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`);
+	const nextSpec = resolveSource({
+		source: options.source,
+		checkout: options.checkout
+	});
+	if (nextSpec.warning) console.warn(`⚠️  ${nextSpec.warning}`);
+	const baseSource = options.source ?? recorded?.url ?? nextSpec.source;
+	const targetRange = options.version ? mpoRange(options.version) : void 0;
+	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) {
+		if (await resolveSha(nextSpec) === recorded.sha) {
+			console.log("\n✅ already up to date");
+			return;
 		}
-		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"
-			});
-			if (!conflicts.length) {
-				if (await git(projectDir, [
-					"diff",
-					"--quiet",
-					"--",
-					"pnpm-lock.yaml"
-				]).then(() => false, () => true)) {
-					await git(projectDir, [
-						"add",
-						"--",
-						"pnpm-lock.yaml"
-					]);
-					await git(projectDir, [
-						"commit",
-						"--amend",
-						"--no-edit",
-						"--quiet"
-					]);
-				}
-			}
+	}
+	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;
+	try {
+		const nextSha = theirs.provenance.source.sha;
+		if (recorded && nextSha === recorded.sha && !options.version) {
+			console.log("\n✅ already up to date");
+			return;
 		}
-		if (cleanMergeMessage) {
-			const finalHash = await gitOut(projectDir, [
-				"rev-parse",
-				"--short",
-				"HEAD"
-			]);
-			console.log(`\n✅ merged cleanly → ${finalHash} ("${cleanMergeMessage}")`);
+		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 = {
+			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();
+	}
+}
+async function updateApp(options = {}) {
+	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:
+      mpo adopt --<piece> [...]
+  - scaffolded from the monorepo before provenance existed? write .mpo.json:
+      { "cliVersion": "<cli>", "source": { "sha": "<commit>", "url": "<repo>" },
+        "apps": ["<name>"], "services": [], "pieces": [] }`);
+	if (provenance.template === "none") {
+		await updateAdopted(projectDir, provenance, options);
+		return;
 	}
+	await updateClone(projectDir, provenance, options);
 }
 
 //#endregion
-export { threeWayMergePackageJson, updateApp };
+export { updateApp };