@multiplatform.one/cli 6.3.0 → 6.4.0

package/lib/bin/multiplatformOne.mjs

@@ -1,7 +1,8 @@
 import { generateVscodeConfig } from "../generateVscode.mjs";
 import { discoverE2EApp, runE2ESession } from "../commands/e2e.mjs";
 import { init, runModifyStep } from "../commands/init.mjs";
-import { initApp } from "../commands/initApp.mjs";
+import { initApp, readProvenance } from "../commands/initApp.mjs";
+import { updateApp } from "../commands/updateApp.mjs";
 import { createRequire } from "node:module";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -491,8 +492,18 @@ program.command("init").option("--universal", "scaffold the universal template (
 		yes: Boolean(options.yes)
 	});
 });
-program.command("update").option("-c, --checkout <branch>", "branch, tag or commit to merge from upstream", "main").option("-r, --remote <url>", "upstream remote URL", "https://gitlab.com/bitspur/multiplatform.one/multiplatform.one.git").description("merge upstream and re-apply workspace config").action(async (options) => {
+program.command("update").option("-c, --checkout <branch>", "branch, tag or commit to merge from upstream (monorepo forks)", "main").option("-r, --remote <url>", "upstream remote URL (monorepo forks)", "https://gitlab.com/bitspur/multiplatform.one/multiplatform.one.git").option("--skip-install", "skip pnpm install after the update").option("--mpo-version <range>", "semver range for @multiplatform.one/* (default: ^<cli version>)").description("update a scaffolded project to the current template (three-way merge via .mpo.json provenance); monorepo forks fall back to the upstream merge flow").action(async (options) => {
 	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 (readProvenance(projectRoot)) {
+		await updateApp({
+			skipInstall: options.skipInstall,
+			version: options.mpoVersion
+		});
+		try {
+			await generateVscodeConfig(projectRoot);
+		} catch {}
+		return;
+	}
 	if (await spawn("git", [
 		"diff",
 		"--cached",

package/lib/commands/initApp.mjs

@@ -16,12 +16,36 @@ function validateName(name) {
 }
 function resolveMpoVersion(explicit) {
 	if (explicit) return explicit.startsWith("^") || explicit.startsWith("~") || explicit === "*" ? explicit : `^${explicit}`;
+	const version = cliVersion();
+	return version ? `^${version}` : "^6.1.0";
+}
+function cliVersion() {
 	try {
 		const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), "../../package.json");
-		const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-		if (pkg.version) return `^${pkg.version}`;
-	} catch {}
-	return "^6.1.0";
+		return JSON.parse(readFileSync(pkgPath, "utf-8")).version;
+	} catch {
+		return;
+	}
+}
+const PROVENANCE_FILE = ".mpo.json";
+function writeProvenance(targetDir, provenance) {
+	writeFileSync(join(targetDir, PROVENANCE_FILE), `${JSON.stringify(provenance, null, 2)}\n`);
+}
+function readProvenance(projectDir) {
+	const file = join(projectDir, PROVENANCE_FILE);
+	if (!existsSync(file)) return void 0;
+	try {
+		const raw = JSON.parse(readFileSync(file, "utf-8"));
+		if (!raw.template || !raw.cliVersion || !raw.name) return void 0;
+		return {
+			template: raw.template,
+			cliVersion: raw.cliVersion,
+			name: raw.name,
+			mpoVersion: raw.mpoVersion ?? `^${raw.cliVersion}`
+		};
+	} catch {
+		return;
+	}
 }
 function templatesRoot(template) {
 	return resolve(dirname(fileURLToPath(import.meta.url)), "../../templates", template);
@@ -121,6 +145,12 @@ async function initApp(nameArg, options = {}) {
 	}
 	console.log(`  @multiplatform.one/* → ${vars.MPO_VERSION}\n`);
 	writeTree(templatesRoot(template), targetDir, vars);
+	writeProvenance(targetDir, {
+		template,
+		cliVersion: cliVersion() ?? "0.0.0",
+		name,
+		mpoVersion: vars.MPO_VERSION
+	});
 	if (!options.skipInstall) {
 		console.log("Installing dependencies...");
 		await spawn("pnpm", ["install"], {
@@ -142,4 +172,4 @@ async function initApp(nameArg, options = {}) {
 }
 
 //#endregion
-export { initApp };
+export { PROVENANCE_FILE, cliVersion, initApp, readProvenance, writeProvenance };

package/lib/commands/updateApp.mjs

@@ -0,0 +1,260 @@
+import { cliVersion, initApp, readProvenance, writeProvenance } from "./initApp.mjs";
+import { join } from "node:path";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import spawn from "nano-spawn";
+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:
+*
+*   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
+*
+* `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 pathspec per line)
+* pins matching paths to your HEAD version, exactly like the old script.
+*/
+async function git(projectDir, args, env) {
+	return spawn("git", args, {
+		cwd: projectDir,
+		env: env ? {
+			...process.env,
+			...env
+		} : void 0
+	});
+}
+async function gitOut(projectDir, args, env) {
+	return (await git(projectDir, args, env)).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, dir, message, parent) {
+	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 commit = await gitOut(projectDir, parent ? [
+		"commit-tree",
+		tree,
+		"-p",
+		parent,
+		"-m",
+		message
+	] : [
+		"commit-tree",
+		tree,
+		"-m",
+		message
+	]);
+	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) {
+	const parent = mkdtempSync(join(tmpdir(), "mpo-update-"));
+	const cleanup = () => rmSync(parent, {
+		recursive: true,
+		force: true
+	});
+	const current = cliVersion();
+	const templateFlag = template === "app" ? ["--web"] : ["--universal"];
+	if (version !== current) {
+		try {
+			await spawn("pnpm", [
+				"--package",
+				`@multiplatform.one/cli@${version}`,
+				"dlx",
+				"mpo",
+				"init",
+				name,
+				"--yes",
+				"--skip-install",
+				"--mpo-version",
+				mpoVersion,
+				...templateFlag
+			], {
+				cwd: parent,
+				stdio: "inherit"
+			});
+			const dir = join(parent, name);
+			if (existsSync(join(dir, "package.json"))) return {
+				dir,
+				cleanup
+			};
+			console.warn(`⚠️  dlx scaffold for @multiplatform.one/cli@${version} produced no project;`);
+		} catch {
+			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,
+			yes: true,
+			template,
+			version: mpoVersion
+		});
+	} finally {
+		process.chdir(previousCwd);
+	}
+	return {
+		dir: join(parent, name),
+		cleanup
+	};
+}
+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)");
+	});
+	const provenance = readProvenance(projectDir);
+	if (!provenance) throw new Error(".mpo.json not found — this project predates scaffold provenance. Create it with { template, cliVersion, name } matching how the project was generated (cliVersion = the @multiplatform.one/cli that scaffolded it), then re-run `mpo update`.");
+	const currentVersion = cliVersion() ?? "0.0.0";
+	const targetMpoRange = options.version ? options.version.startsWith("^") || options.version.startsWith("~") ? options.version : `^${options.version}` : `^${currentVersion}`;
+	console.log(`\nmpo update: ${provenance.cliVersion} → ${currentVersion}`);
+	console.log(`  template: ${provenance.template}`);
+	console.log(`  project:  ${provenance.name}\n`);
+	console.log(`Scaffolding merge base (cli@${provenance.cliVersion})...`);
+	const base = await scaffoldBaseline(provenance.cliVersion, provenance.name, provenance.template, provenance.mpoVersion);
+	console.log(`Scaffolding update target (cli@${currentVersion})...`);
+	const next = await scaffoldBaseline(currentVersion, provenance.name, provenance.template, targetMpoRange);
+	writeProvenance(next.dir, {
+		template: provenance.template,
+		cliVersion: currentVersion,
+		name: provenance.name,
+		mpoVersion: targetMpoRange
+	});
+	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").filter(Boolean);
+			if (!lines.length) throw err;
+			mergedTree = lines[0].trim();
+			conflicts = lines.slice(1).map((line) => line.trim());
+		}
+		const finalProvenance = {
+			template: provenance.template,
+			cliVersion: currentVersion,
+			name: provenance.name,
+			mpoVersion: targetMpoRange
+		};
+		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);
+			await git(projectDir, [
+				"add",
+				"--",
+				".mpo.json"
+			]);
+			await git(projectDir, [
+				"commit",
+				"--amend",
+				"--no-edit",
+				"--quiet"
+			]);
+			const amended = await gitOut(projectDir, [
+				"rev-parse",
+				"--short",
+				"HEAD"
+			]);
+			console.log(`\n✅ merged cleanly → ${amended} ("${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}"`);
+		}
+		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("#")) pins.push(pattern);
+		}
+		for (const pin of pins) await git(projectDir, [
+			"checkout",
+			head,
+			"--",
+			pin
+		]).catch(() => {});
+		if (!options.skipInstall) {
+			console.log("\nInstalling dependencies...");
+			await spawn("pnpm", ["install"], {
+				cwd: projectDir,
+				stdio: "inherit"
+			});
+		}
+	} finally {
+		base.cleanup();
+		next.cleanup();
+	}
+}
+
+//#endregion
+export { updateApp };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/cli",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "description": "multiplatform.one cli — mpo init / create-multiplatform-app",
   "keywords": [
     "create-multiplatform-app",
@@ -61,7 +61,7 @@
     "nano-spawn": "^2.1.0",
     "yaml": "^2.8.3",
     "yocto-spinner": "^1.1.0",
-    "@multiplatform.one/utils": "6.3.0"
+    "@multiplatform.one/utils": "6.4.0"
   },
   "devDependencies": {
     "@types/inquirer": "^9.0.9",

package/src/bin/multiplatformOne.ts

@@ -19,7 +19,8 @@ import YAML from "yaml";
 import yoctoSpinner from "yocto-spinner";
 import { discoverE2EApp, runE2ESession } from "../commands/e2e";
 import { init, runModifyStep } from "../commands/init";
-import { initApp } from "../commands/initApp";
+import { initApp, readProvenance } from "../commands/initApp";
+import { updateApp } from "../commands/updateApp";
 
 const projectRoot = lookupProjectRoot();
 const availableServices = ["api", "frappe", "solana", "ethereum", "sui"];
@@ -279,10 +280,22 @@ const defaultUpdateRemote = "https://gitlab.com/bitspur/multiplatform.one/multip
 
 program
   .command("update")
-  .option("-c, --checkout <branch>", "branch, tag or commit to merge from upstream", "main")
-  .option("-r, --remote <url>", "upstream remote URL", defaultUpdateRemote)
-  .description("merge upstream and re-apply workspace config")
-  .action(async (options: { checkout: string; remote: string }) => {
+  .option("-c, --checkout <branch>", "branch, tag or commit to merge from upstream (monorepo forks)", "main")
+  .option("-r, --remote <url>", "upstream remote URL (monorepo forks)", defaultUpdateRemote)
+  .option("--skip-install", "skip pnpm install after the update")
+  .option(
+    "--mpo-version <range>",
+    "semver range for @multiplatform.one/* (default: ^<cli version>)",
+  )
+  .description(
+    "update a scaffolded project to the current template (three-way merge via .mpo.json provenance); monorepo forks fall back to the upstream merge flow",
+  )
+  .action(async (options: {
+    checkout: string;
+    remote: string;
+    skipInstall?: boolean;
+    mpoVersion?: string;
+  }) => {
     // Update prechecks: must be in a git repo
     if (
       await spawn("git", ["rev-parse", "--is-inside-work-tree"]).then(
@@ -292,6 +305,18 @@ program
     ) {
       throw new Error("mpo cannot be updated outside of a git repository");
     }
+    // Scaffolded consumer projects carry .mpo.json provenance — use the
+    // copier-style three-way template update. Monorepo forks fall through to
+    // the legacy upstream-merge flow below.
+    if (readProvenance(projectRoot)) {
+      await updateApp({ skipInstall: options.skipInstall, version: options.mpoVersion });
+      try {
+        await generateVscodeConfig(projectRoot);
+      } catch {
+        // best-effort
+      }
+      return;
+    }
     // Require clean working tree (no staged or unstaged changes)
     if (
       await spawn("git", ["diff", "--cached", "--quiet"]).then(

package/src/commands/initApp.ts

@@ -67,14 +67,54 @@ function resolveMpoVersion(explicit?: string): string {
       ? explicit
       : `^${explicit}`;
   }
+  const version = cliVersion();
+  return version ? `^${version}` : "^6.1.0";
+}
+
+export function cliVersion(): string | undefined {
   try {
     const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), "../../package.json");
     const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { version?: string };
-    if (pkg.version) return `^${pkg.version}`;
+    return pkg.version;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Scaffold provenance (the copier-answers equivalent): which template, which
+ * CLI version and which vars produced this project. `mpo update` regenerates
+ * the ORIGINAL scaffold from this record to use as the merge base for a
+ * three-way template update.
+ */
+export interface MpoProvenance {
+  template: InitAppTemplate;
+  cliVersion: string;
+  name: string;
+  mpoVersion: string;
+}
+
+export const PROVENANCE_FILE = ".mpo.json";
+
+export function writeProvenance(targetDir: string, provenance: MpoProvenance): void {
+  writeFileSync(join(targetDir, PROVENANCE_FILE), `${JSON.stringify(provenance, null, 2)}\n`);
+}
+
+export function readProvenance(projectDir: string): MpoProvenance | undefined {
+  const file = join(projectDir, PROVENANCE_FILE);
+  if (!existsSync(file)) return undefined;
+  try {
+    const raw = JSON.parse(readFileSync(file, "utf-8")) as Partial<MpoProvenance>;
+    if (!raw.template || !raw.cliVersion || !raw.name) return undefined;
+    return {
+      template: raw.template,
+      cliVersion: raw.cliVersion,
+      name: raw.name,
+      mpoVersion: raw.mpoVersion ?? `^${raw.cliVersion}`,
+    };
   } catch {
-    // fall through
+    return undefined;
   }
-  return "^6.1.0";
 }
 
 function templatesRoot(template: InitAppTemplate): string {
@@ -203,6 +243,12 @@ export async function initApp(
   console.log(`  @multiplatform.one/* → ${vars.MPO_VERSION}\n`);
 
   writeTree(templatesRoot(template), targetDir, vars);
+  writeProvenance(targetDir, {
+    template,
+    cliVersion: cliVersion() ?? "0.0.0",
+    name,
+    mpoVersion: vars.MPO_VERSION,
+  });
 
   if (!options.skipInstall) {
     console.log("Installing dependencies...");

package/src/commands/updateApp.ts

@@ -0,0 +1,277 @@
+/**
+ * `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:
+ *
+ *   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
+ *
+ * `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 pathspec per line)
+ * pins matching paths to your HEAD version, exactly like the old script.
+ */
+
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import spawn from "nano-spawn";
+import { cliVersion, initApp, readProvenance, writeProvenance } from "./initApp";
+
+export interface UpdateAppOptions {
+  /** Skip pnpm install after the merge. */
+  skipInstall?: boolean;
+  /** Override the semver range written for @multiplatform.one/* deps. */
+  version?: string;
+}
+
+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: "universal" | "app",
+  mpoVersion: string,
+): 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 === "app" ? ["--web"] : ["--universal"];
+  if (version !== current) {
+    try {
+      await spawn(
+        "pnpm",
+        [
+          "--package",
+          `@multiplatform.one/cli@${version}`,
+          "dlx",
+          "mpo",
+          "init",
+          name,
+          "--yes",
+          "--skip-install",
+          "--mpo-version",
+          mpoVersion,
+          ...templateFlag,
+        ],
+        { cwd: parent, stdio: "inherit" },
+      );
+      const dir = join(parent, name);
+      if (existsSync(join(dir, "package.json"))) return { dir, cleanup };
+      console.warn(`⚠️  dlx scaffold for @multiplatform.one/cli@${version} produced no project;`);
+    } catch {
+      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,
+      yes: true,
+      template,
+      version: mpoVersion,
+    });
+  } finally {
+    process.chdir(previousCwd);
+  }
+  return { dir: join(parent, name), cleanup };
+}
+
+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)");
+  });
+
+  const provenance = readProvenance(projectDir);
+  if (!provenance) {
+    throw new Error(
+      ".mpo.json not found — this project predates scaffold provenance. " +
+        "Create it with { template, cliVersion, name } matching how the project " +
+        "was generated (cliVersion = the @multiplatform.one/cli that scaffolded it), " +
+        "then re-run `mpo update`.",
+    );
+  }
+
+  const currentVersion = cliVersion() ?? "0.0.0";
+  const targetMpoRange = options.version
+    ? options.version.startsWith("^") || options.version.startsWith("~")
+      ? options.version
+      : `^${options.version}`
+    : `^${currentVersion}`;
+
+  console.log(`\nmpo update: ${provenance.cliVersion} → ${currentVersion}`);
+  console.log(`  template: ${provenance.template}`);
+  console.log(`  project:  ${provenance.name}\n`);
+
+  // 1. Regenerate the ORIGINAL scaffold (merge base).
+  console.log(`Scaffolding merge base (cli@${provenance.cliVersion})...`);
+  const base = await scaffoldBaseline(
+    provenance.cliVersion,
+    provenance.name,
+    provenance.template,
+    provenance.mpoVersion,
+  );
+
+  // 2. Generate the CURRENT scaffold (theirs).
+  console.log(`Scaffolding update target (cli@${currentVersion})...`);
+  const next = await scaffoldBaseline(
+    currentVersion,
+    provenance.name,
+    provenance.template,
+    targetMpoRange,
+  );
+  writeProvenance(next.dir, {
+    template: provenance.template,
+    cliVersion: currentVersion,
+    name: provenance.name,
+    mpoVersion: targetMpoRange,
+  });
+
+  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; stdout still carries tree + conflict names.
+      const stdout = (err as { stdout?: string }).stdout ?? "";
+      const lines = stdout.split("\n").filter(Boolean);
+      if (!lines.length) throw err;
+      mergedTree = lines[0]!.trim();
+      conflicts = lines.slice(1).map((line) => line.trim());
+    }
+
+    // The merged .mpo.json can interleave ours/theirs lines (add/add
+    // two-way merge) — the post-merge provenance is always written
+    // authoritatively below.
+    const finalProvenance = {
+      template: provenance.template,
+      cliVersion: currentVersion,
+      name: provenance.name,
+      mpoVersion: targetMpoRange,
+    };
+
+    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"]);
+      writeProvenance(projectDir, finalProvenance);
+      await git(projectDir, ["add", "--", ".mpo.json"]);
+      await git(projectDir, ["commit", "--amend", "--no-edit", "--quiet"]);
+      const amended = await gitOut(projectDir, ["rev-parse", "--short", "HEAD"]);
+      console.log(`\n✅ merged cleanly → ${amended} ("${message}")`);
+    } else {
+      // Land the merged tree (with conflict markers) in index + worktree for
+      // manual resolution.
+      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}"`,
+      );
+    }
+
+    // 4. .updateignore: pin matching paths to the pre-update HEAD (always
+    // includes pnpm-lock.yaml — the install below regenerates it).
+    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("#")) pins.push(pattern);
+      }
+    }
+    for (const pin of pins) {
+      await git(projectDir, ["checkout", head, "--", pin]).catch(() => {});
+    }
+
+    if (!options.skipInstall) {
+      console.log("\nInstalling dependencies...");
+      await spawn("pnpm", ["install"], { cwd: projectDir, stdio: "inherit" });
+    }
+  } finally {
+    base.cleanup();
+    next.cleanup();
+  }
+}

package/types/bin/multiplatformOne.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"multiplatformOne.d.ts","sourceRoot":"","sources":["../../src/bin/multiplatformOne.ts"],"names":[],"mappings":"AA0FA,gHAAgH;AAChH,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,kGAAkG;IAClG,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gGAAgG;IAChG,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC,CAAC"}
+{"version":3,"file":"multiplatformOne.d.ts","sourceRoot":"","sources":["../../src/bin/multiplatformOne.ts"],"names":[],"mappings":"AA2FA,gHAAgH;AAChH,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,kGAAkG;IAClG,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gGAAgG;IAChG,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC,CAAC"}

package/types/commands/initApp.d.ts

@@ -16,6 +16,22 @@ export interface InitAppOptions {
     /** Accept defaults instead of prompting (non-interactive / CI). */
     yes?: boolean;
 }
+export declare function cliVersion(): string | undefined;
+/**
+ * Scaffold provenance (the copier-answers equivalent): which template, which
+ * CLI version and which vars produced this project. `mpo update` regenerates
+ * the ORIGINAL scaffold from this record to use as the merge base for a
+ * three-way template update.
+ */
+export interface MpoProvenance {
+    template: InitAppTemplate;
+    cliVersion: string;
+    name: string;
+    mpoVersion: string;
+}
+export declare const PROVENANCE_FILE = ".mpo.json";
+export declare function writeProvenance(targetDir: string, provenance: MpoProvenance): void;
+export declare function readProvenance(projectDir: string): MpoProvenance | undefined;
 /**
  * Scaffold a consumer project (universal by default, web-only with
  * template: "app") that depends on @multiplatform.one/* at semver ranges

package/types/commands/initApp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initApp.d.ts","sourceRoot":"","sources":["../../src/commands/initApp.ts"],"names":[],"mappings":"AAaA;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,KAAK,CAAC;AAElD,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,mEAAmE;IACnE,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAqHD;;;;GAIG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAuEf"}
+{"version":3,"file":"initApp.d.ts","sourceRoot":"","sources":["../../src/commands/initApp.ts"],"names":[],"mappings":"AAaA;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,KAAK,CAAC;AAElD,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,mEAAmE;IACnE,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AA0CD,wBAAgB,UAAU,IAAI,MAAM,GAAG,SAAS,CAQ/C;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,eAAe,cAAc,CAAC;AAE3C,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,GAAG,IAAI,CAElF;AAED,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAe5E;AAuED;;;;GAIG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CA6Ef"}

package/types/commands/updateApp.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `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:
+ *
+ *   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
+ *
+ * `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 pathspec per line)
+ * pins matching paths to your HEAD version, exactly like the old script.
+ */
+export interface UpdateAppOptions {
+    /** Skip pnpm install after the merge. */
+    skipInstall?: boolean;
+    /** Override the semver range written for @multiplatform.one/* deps. */
+    version?: string;
+}
+export declare function updateApp(options?: UpdateAppOptions): Promise<void>;
+//# sourceMappingURL=updateApp.d.ts.map

package/types/commands/updateApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateApp.d.ts","sourceRoot":"","sources":["../../src/commands/updateApp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA2FD,wBAAsB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6J7E"}