@multiplatform.one/cli 6.4.3 → 6.7.0

package/README.md

@@ -38,9 +38,31 @@ Want web-only? `mpo init --web my-app` scaffolds the Vite + React variant
 (`--app` is a back-compat alias; `create-multiplatform-app` without flags also
 produces it — pass `--universal` there for the full project).
 
-Options: `--universal`, `--web`/`--app`, `--skip-install`,
+Options: `--universal`, `--web`/`--app`, `--skip-install`, `--skip-git`,
 `--mpo-version <range>` (defaults to `^<cli version>`), `-y/--yes`.
 
+### Pieces
+
+Composable fragments overlaid onto the base template. Pass any of them to skip
+the interactive prompt; they are recorded in `.mpo.json` and reproduced by
+`mpo update`, so pick them at init time.
+
+| Flag         | Adds                                                             | Needs                 |
+| ------------ | ---------------------------------------------------------------- | --------------------- |
+| `--frappe`   | Frappe backend wiring — env keys, provider, dev bench compose    | Docker                |
+| `--keycloak` | Keycloak auth — env keys, provider, compose + realm import       | Docker                |
+| `--gnome`    | GNOME desktop: **real GTK4 widgets** via react-gnome, no webview | gjs, gtk4, libadwaita |
+| `--tauri`    | Desktop: the web build in a system webview                       | Rust toolchain        |
+| `--vscode`   | VS Code extension — extension host + Tamagui webview             | —                     |
+| `--webext`   | Browser extension — MV3 popup + background                       | —                     |
+
+The two desktop pieces are different things, not alternatives to benchmark
+against each other. `--tauri` wraps the same web output you already ship and
+gives you Linux, macOS and Windows bundles. `--gnome` renders your Tamagui
+components as native GTK widgets laid out by Yoga — a genuinely different
+runtime, Linux-first, and the one to pick when the app should look and feel
+like part of the desktop rather than like a web page in a frame.
+
 ## Other commands
 
 | Command                      | Purpose                                                              |

package/lib/bin/multiplatformOne.mjs

@@ -1,7 +1,7 @@
 import { generateVscodeConfig } from "../generateVscode.mjs";
 import { discoverE2EApp, runE2ESession } from "../commands/e2e.mjs";
 import { init, runModifyStep } from "../commands/init.mjs";
-import { initApp, readProvenance } from "../commands/initApp.mjs";
+import { INIT_APP_PIECES, initApp, readProvenance } from "../commands/initApp.mjs";
 import { updateApp } from "../commands/updateApp.mjs";
 import { createRequire } from "node:module";
 import fs from "node:fs/promises";
@@ -471,7 +471,7 @@ async function getFrappeApps(root) {
 const program = new Command();
 program.name("mpo");
 program.version(JSON.parse(fsSync.readFileSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json"), "utf8"))?.version);
-program.command("init").option("--universal", "scaffold the universal template (web + iOS + Android; default)").option("--web", "scaffold the web-only template (Vite + React)").option("--app", "alias of --web (back-compat)").option("--skip-install", "skip pnpm install after scaffolding").option("--skip-git", "skip git init + scaffold commit").option("--mpo-version <range>", "semver range for @multiplatform.one/* (default: ^<cli version>)").option("-y, --yes", "non-interactive: accept defaults instead of prompting").option("--monorepo", "DEPRECATED: clone/modify the full multiplatform.one monorepo instead of scaffolding a consumer project").option("-c, --checkout <branch>", "branch, tag or commit to checkout (--monorepo only)", "main").option("-a, --apps <apps>", "comma-separated apps to include (--monorepo only)").option("-s, --services <services>", "comma-separated services to include (--monorepo only)").argument("[name]", "the name of the project").description("scaffold a new multiplatform project (universal web + native by default; --web for web-only; semver @multiplatform.one/* deps)").action(async (name, options) => {
+program.command("init").option("--universal", "scaffold the universal template (web + iOS + Android; default)").option("--web", "scaffold the web-only template (Vite + React)").option("--app", "alias of --web (back-compat)").option("--frappe", "add the Frappe backend piece (env keys, provider, docker compose bench)").option("--keycloak", "add the Keycloak auth piece (env keys, provider, docker compose + realm)").option("--gnome", "add the GNOME desktop target piece (GTK4/GJS via react-gnome — native widgets, no webview)").option("--tauri", "add the desktop target piece (src-tauri skeleton, webview)").option("--vscode", "add the VS Code extension target piece").option("--webext", "add the browser extension target piece (MV3 popup + background)").option("--skip-install", "skip pnpm install after scaffolding").option("--skip-git", "skip git init + scaffold commit").option("--mpo-version <range>", "semver range for @multiplatform.one/* (default: ^<cli version>)").option("-y, --yes", "non-interactive: accept defaults instead of prompting").option("--monorepo", "DEPRECATED: clone/modify the full multiplatform.one monorepo instead of scaffolding a consumer project").option("-c, --checkout <branch>", "branch, tag or commit to checkout (--monorepo only)", "main").option("-a, --apps <apps>", "comma-separated apps to include (--monorepo only)").option("-s, --services <services>", "comma-separated services to include (--monorepo only)").argument("[name]", "the name of the project").description("scaffold a new multiplatform project (universal web + native by default; --web for web-only; semver @multiplatform.one/* deps)").action(async (name, options) => {
 	if (options.monorepo) {
 		console.warn("⚠️  `mpo init --monorepo` clones the whole multiplatform.one monorepo (legacy). New projects should use the default consumer scaffold instead.");
 		if (await spawn("git", ["rev-parse", "--is-inside-work-tree"]).then(() => true, () => false)) throw new Error("mpo cannot be initialized inside a git repository");
@@ -485,12 +485,14 @@ program.command("init").option("--universal", "scaffold the universal template (
 	if (options.apps || options.services) throw new Error("--apps/--services select monorepo pieces and require --monorepo (legacy clone mode)");
 	const webOnly = Boolean(options.web || options.app);
 	if (webOnly && options.universal) throw new Error("Pass either --web/--app or --universal, not both");
+	const pieces = INIT_APP_PIECES.filter((piece) => Boolean(options[piece]));
 	await initApp(name, {
 		skipInstall: Boolean(options.skipInstall),
 		skipGit: Boolean(options.skipGit),
 		version: options.mpoVersion,
 		template: webOnly ? "app" : options.universal ? "universal" : void 0,
-		yes: Boolean(options.yes)
+		yes: Boolean(options.yes),
+		pieces: pieces.length ? pieces : void 0
 	});
 });
 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/frappe/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) => {

package/lib/commands/initApp.mjs

@@ -5,6 +5,28 @@ import spawn from "nano-spawn";
 import inquirer from "inquirer";
 
 //#region src/commands/initApp.ts
+/**
+* Optional composable pieces overlaid onto the base template (additive
+* fragments under templates/pieces/<piece>/ — the inverse of the old
+* cookiecutter KEEP_SERVICES/KEEP_PLATFORMS removal hook). Keep sorted:
+* pieces are recorded sorted in provenance and overlaid in this order.
+*/
+const INIT_APP_PIECES = [
+	"frappe",
+	"gnome",
+	"keycloak",
+	"tauri",
+	"vscode",
+	"webext"
+];
+const PIECE_DESCRIPTIONS = {
+	frappe: "Frappe backend wiring (env keys, provider, docker compose bench)",
+	gnome: "GNOME desktop target (GTK4/GJS via react-gnome — native widgets, no webview)",
+	keycloak: "Keycloak auth wiring (env keys, provider, docker compose + realm)",
+	tauri: "Desktop target (src-tauri skeleton, tauri scripts)",
+	vscode: "VS Code extension target (extension host + Tamagui webview)",
+	webext: "Browser extension target (MV3 popup + background)"
+};
 function toPascalCase(name) {
 	return name.split(/[-_\s]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
 }
@@ -29,7 +51,10 @@ function cliVersion() {
 }
 const PROVENANCE_FILE = ".mpo.json";
 function writeProvenance(targetDir, provenance) {
-	writeFileSync(join(targetDir, PROVENANCE_FILE), `${JSON.stringify(provenance, null, 2)}\n`);
+	writeFileSync(join(targetDir, PROVENANCE_FILE), `${JSON.stringify({
+		...provenance,
+		pieces: [...provenance.pieces].sort()
+	}, null, 2)}\n`);
 }
 function readProvenance(projectDir) {
 	const file = join(projectDir, PROVENANCE_FILE);
@@ -41,7 +66,8 @@ function readProvenance(projectDir) {
 			template: raw.template,
 			cliVersion: raw.cliVersion,
 			name: raw.name,
-			mpoVersion: raw.mpoVersion ?? `^${raw.cliVersion}`
+			mpoVersion: raw.mpoVersion ?? `^${raw.cliVersion}`,
+			pieces: Array.isArray(raw.pieces) ? [...raw.pieces].sort() : []
 		};
 	} catch {
 		return;
@@ -50,13 +76,26 @@ function readProvenance(projectDir) {
 function templatesRoot(template) {
 	return resolve(dirname(fileURLToPath(import.meta.url)), "../../templates", template);
 }
+function piecesRoot(piece) {
+	return resolve(dirname(fileURLToPath(import.meta.url)), "../../templates/pieces", piece);
+}
+/**
+* Fragment source dirs for a piece + template: shared/ applies to every
+* template, <template>/ only to that one. A piece supports a template when
+* at least one of the two exists.
+*/
+function pieceFragmentDirs(piece, template) {
+	return [join(piecesRoot(piece), "shared"), join(piecesRoot(piece), template)].filter((dir) => existsSync(dir));
+}
 /**
-* npm always strips .gitignore / .npmrc from published tarballs, so the
-* template stores them without the leading dot; restore it at scaffold time.
+* npm always strips .gitignore / .npmrc (and newer npms .env*) from published
+* tarballs, so the template stores them without the leading dot; restore it
+* at scaffold time.
 */
 const DOTFILE_NAMES = {
 	gitignore: ".gitignore",
-	npmrc: ".npmrc"
+	npmrc: ".npmrc",
+	"env.example": ".env.example"
 };
 function render(content, vars) {
 	return content.replaceAll("__NAME_PASCAL__", vars.NAME_PASCAL).replaceAll("__NAME_APPID__", vars.NAME_APPID).replaceAll("__NAME__", vars.NAME).replaceAll("__MPO_VERSION__", vars.MPO_VERSION).replaceAll("__YEAR__", vars.YEAR);
@@ -72,7 +111,8 @@ const BINARY_EXTENSIONS = new Set([
 	".otf",
 	".png",
 	".jpg",
-	".ico"
+	".ico",
+	".icns"
 ]);
 function writeTree(srcDir, destDir, vars) {
 	if (!existsSync(srcDir)) throw new Error(`Project template missing at ${srcDir}`);
@@ -91,6 +131,156 @@ function writeTree(srcDir, destDir, vars) {
 		writeFileSync(to, render(readFileSync(from, "utf-8"), vars));
 	}
 }
+function isJsonObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Deep-merge for JSON partials: objects merge recursively (fragment keys
+* append after base keys, so e.g. package.json script order stays stable),
+* arrays union (base order first — config.json public keys accumulate
+* across pieces), scalars/type-mismatches take the fragment value.
+*/
+function mergeJsonValues(base, fragment) {
+	if (Array.isArray(base) && Array.isArray(fragment)) {
+		const merged = [...base];
+		const seen = new Set(base.map((item) => JSON.stringify(item)));
+		for (const item of fragment) {
+			const key = JSON.stringify(item);
+			if (seen.has(key)) continue;
+			seen.add(key);
+			merged.push(item);
+		}
+		return merged;
+	}
+	if (isJsonObject(base) && isJsonObject(fragment)) {
+		const merged = { ...base };
+		for (const [key, value] of Object.entries(fragment)) merged[key] = key in merged ? mergeJsonValues(merged[key], value) : value;
+		return merged;
+	}
+	return fragment;
+}
+/** Dependency maps stay alphabetically sorted after fragment merges (the
+*  base templates are sorted; multiple pieces appending must not depend on
+*  overlay order for the final byte content). */
+const SORTED_DEPENDENCY_FIELDS = [
+	"dependencies",
+	"devDependencies",
+	"peerDependencies",
+	"optionalDependencies"
+];
+function sortDependencyFields(value) {
+	if (!isJsonObject(value)) return value;
+	const result = { ...value };
+	for (const field of SORTED_DEPENDENCY_FIELDS) {
+		const deps = result[field];
+		if (!isJsonObject(deps)) continue;
+		result[field] = Object.fromEntries(Object.entries(deps).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+	}
+	return result;
+}
+/**
+* Apply a rendered `<target>.partial` fragment onto the target file:
+*   - `.json` targets deep-merge (see mergeJsonValues); package.json-style
+*     dependency maps are re-sorted for deterministic output
+*   - everything else appends as a text block separated by a blank line
+* Missing targets are created from the fragment alone.
+*/
+function applyPartial(targetPath, renderedFragment) {
+	if (targetPath.endsWith(".json")) {
+		const fragment = JSON.parse(renderedFragment);
+		const base = existsSync(targetPath) ? JSON.parse(readFileSync(targetPath, "utf-8")) : void 0;
+		const merged = sortDependencyFields(base === void 0 ? fragment : mergeJsonValues(base, fragment));
+		writeFileSync(targetPath, `${JSON.stringify(merged, null, 2)}\n`);
+		return;
+	}
+	const block = `${renderedFragment.replace(/^\n+/u, "").replace(/\n+$/u, "")}\n`;
+	if (!existsSync(targetPath)) {
+		writeFileSync(targetPath, block);
+		return;
+	}
+	writeFileSync(targetPath, `${readFileSync(targetPath, "utf-8").replace(/\n+$/u, "")}\n\n${block}`);
+}
+const PARTIAL_SUFFIX = ".partial";
+/**
+* Overlay a piece fragment tree onto the scaffold: regular files render and
+* overwrite, `<target>.partial` files merge into (or create) their target
+* (deep-merge for .json, append for text — see applyPartial).
+*/
+function overlayTree(srcDir, destDir, vars) {
+	mkdirSync(destDir, { recursive: true });
+	for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+		const from = join(srcDir, entry.name);
+		if (entry.isDirectory()) {
+			overlayTree(from, join(destDir, render(DOTFILE_NAMES[entry.name] ?? entry.name, vars)), vars);
+			continue;
+		}
+		if (entry.name.endsWith(PARTIAL_SUFFIX)) {
+			const targetName = entry.name.slice(0, -8);
+			applyPartial(join(destDir, render(DOTFILE_NAMES[targetName] ?? targetName, vars)), render(readFileSync(from, "utf-8"), vars));
+			continue;
+		}
+		const to = join(destDir, render(DOTFILE_NAMES[entry.name] ?? entry.name, vars));
+		if (BINARY_EXTENSIONS.has(extname(entry.name).toLowerCase())) {
+			copyFileSync(from, to);
+			continue;
+		}
+		writeFileSync(to, render(readFileSync(from, "utf-8"), vars));
+	}
+}
+/**
+* Validate + canonicalize a piece selection for a template: unknown names
+* throw, duplicates collapse, order is always sorted (provenance and overlay
+* order must be deterministic), and every piece must ship a fragment for the
+* chosen template.
+*/
+function normalizePieces(pieces, template) {
+	const known = new Set(INIT_APP_PIECES);
+	const normalized = [...new Set(pieces)].sort();
+	for (const piece of normalized) {
+		if (!known.has(piece)) throw new Error(`Unknown piece "${piece}". Available pieces: ${INIT_APP_PIECES.join(", ")}`);
+		if (pieceFragmentDirs(piece, template).length === 0) throw new Error(`Piece "${piece}" is not available for the ${template} template (pieces currently target the universal template)`);
+	}
+	return normalized;
+}
+/** Pieces that can be offered for a template (fragment exists for it). */
+function availablePieces(template) {
+	return INIT_APP_PIECES.filter((piece) => pieceFragmentDirs(piece, template).length > 0);
+}
+async function resolvePieces(options, template) {
+	if (options.pieces) return normalizePieces(options.pieces, template);
+	if (options.yes || !process.stdout.isTTY) return [];
+	const choices = availablePieces(template);
+	if (choices.length === 0) return [];
+	return normalizePieces((await inquirer.prompt([{
+		message: "Add optional pieces? (space to toggle, enter to confirm)",
+		name: "pieces",
+		type: "checkbox",
+		choices: choices.map((piece) => ({
+			name: `${piece} — ${PIECE_DESCRIPTIONS[piece]}`,
+			value: piece,
+			checked: false
+		}))
+	}])).pieces, template);
+}
+/**
+* Generate apps/<name>/src/app.ts for the selected backend pieces instead of
+* storing 2^n template variants: each selected provider adds one createApp
+* key (frappe/keycloak read their runtime settings from the packages/config
+* public env keys their fragments register). Only called when at least one
+* provider piece is selected — the base template file stays otherwise.
+*/
+function composeAppTs(pieces) {
+	const frappe = pieces.includes("frappe");
+	const keycloak = pieces.includes("keycloak");
+	const lines = ["import { createApp } from \"@multiplatform.one/core\";"];
+	if (frappe || keycloak) lines.push("import { config } from \"@multiplatform.one/platform\";");
+	lines.push("import { themeConfig } from \"@package/themes\";");
+	lines.push("", "/**", " * App-wide provider stack. Providers below were enabled by the pieces", " * selected at `mpo init` time — see CreateAppConfig in", " * @multiplatform.one/core for everything else that can be wired here", " * (tanstack, web3, custom providers).", " */", "export const { AppProvider, useAppConfig, withApp } = createApp({", "  theme: themeConfig,");
+	if (frappe) lines.push("  // Frappe backend (mpo init --frappe): FrappeProvider mounts when", "  // FRAPPE_ENABLED=1 (a packages/config public env key, loaded from", "  // .env — see .env.example). FRAPPE_URL overrides the bench URL", "  // (default: BASE_URL, then http://localhost:8000);", "  // docker/compose.frappe.yaml runs a dev bench.", "  frappe: { baseURL: config.get(\"FRAPPE_URL\") },");
+	if (keycloak) lines.push("  // Keycloak auth (mpo init --keycloak): KeycloakProvider mounts when", "  // KEYCLOAK_ENABLED=1. Realm/client settings come from the KEYCLOAK_*", "  // env keys (packages/config, .env.example);", "  // docker/compose.keycloak.yaml runs a dev server with an imported", "  // realm.", "  keycloak: { baseUrl: config.get(\"KEYCLOAK_BASE_URL\") },");
+	lines.push("});", "");
+	return lines.join("\n");
+}
 async function resolveTemplate(options) {
 	if (options.template) return options.template;
 	if (options.yes || !process.stdout.isTTY) return "universal";
@@ -124,6 +314,7 @@ async function initApp(nameArg, options = {}) {
 	}])).name;
 	const name = validateName(projectName);
 	const template = await resolveTemplate(options);
+	const pieces = await resolvePieces(options, template);
 	const targetDir = resolve(name);
 	if (existsSync(targetDir)) {
 		if (readdirSync(targetDir).length > 0) throw new Error(`Directory "${targetDir}" already exists and is not empty`);
@@ -143,13 +334,17 @@ async function initApp(nameArg, options = {}) {
 		console.log(`  packages/i18n`);
 		console.log(`  packages/themes`);
 	}
+	if (pieces.length) console.log(`  pieces: ${pieces.join(", ")}`);
 	console.log(`  @multiplatform.one/* → ${vars.MPO_VERSION}\n`);
 	writeTree(templatesRoot(template), targetDir, vars);
+	for (const piece of pieces) for (const fragmentDir of pieceFragmentDirs(piece, template)) overlayTree(fragmentDir, targetDir, vars);
+	if (pieces.includes("frappe") || pieces.includes("keycloak")) writeFileSync(join(targetDir, "apps", name, "src/app.ts"), composeAppTs(pieces));
 	writeProvenance(targetDir, {
 		template,
 		cliVersion: cliVersion() ?? "0.0.0",
 		name,
-		mpoVersion: vars.MPO_VERSION
+		mpoVersion: vars.MPO_VERSION,
+		pieces
 	});
 	let scaffoldCommitted = false;
 	if (!options.skipGit) {
@@ -194,9 +389,15 @@ async function initApp(nameArg, options = {}) {
 		console.log("  pnpm ios        # iOS (requires pnpm dev in another terminal)");
 		console.log("  pnpm android    # Android");
 	}
+	if (pieces.includes("frappe")) console.log("  docker compose -f docker/compose.frappe.yaml up -d   # dev bench (see README)");
+	if (pieces.includes("keycloak")) console.log("  docker compose -f docker/compose.keycloak.yaml up -d # dev keycloak");
+	if (pieces.includes("gnome")) console.log("  pnpm gnome       # GTK4 desktop app (requires gjs + gtk4 — see README)");
+	if (pieces.includes("tauri")) console.log("  pnpm tauri:dev   # desktop app (requires the Rust toolchain)");
+	if (pieces.includes("vscode")) console.log("  pnpm build:vscode  # stage the VS Code extension into apps dist-vscode/");
+	if (pieces.includes("webext")) console.log("  pnpm build:webext  # stage the browser extension into apps dist-webext/");
 	console.log("\nThis project consumes published @multiplatform.one/* packages.");
 	console.log("It is not a fork of the multiplatform.one monorepo.");
 }
 
 //#endregion
-export { PROVENANCE_FILE, cliVersion, initApp, readProvenance, writeProvenance };
+export { INIT_APP_PIECES, PROVENANCE_FILE, availablePieces, cliVersion, composeAppTs, initApp, mergeJsonValues, normalizePieces, readProvenance, writeProvenance };

package/lib/commands/updateApp.mjs

@@ -1,7 +1,7 @@
 import { generateVscodeConfig } from "../generateVscode.mjs";
 import { cliVersion, initApp, readProvenance, writeProvenance } from "./initApp.mjs";
-import { join } from "node:path";
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { basename, join } from "node:path";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import spawn from "nano-spawn";
 import { tmpdir } from "node:os";
 
@@ -69,7 +69,7 @@ async function commitTreeFromDir(projectDir, dir, message, parent) {
 /** 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) {
+async function scaffoldBaseline(version, name, template, mpoVersion, pieces) {
 	const parent = mkdtempSync(join(tmpdir(), "mpo-update-"));
 	const cleanup = () => rmSync(parent, {
 		recursive: true,
@@ -78,7 +78,11 @@ async function scaffoldBaseline(version, name, template, mpoVersion) {
 	const current = cliVersion();
 	const templateFlag = template === "app" ? ["--web"] : ["--universal"];
 	const [major = 0, minor = 0] = version.split(".").map(Number);
-	if (!(major > 6 || major === 6 && minor >= 3)) console.warn(`⚠️  @multiplatform.one/cli@${version} predates the consumer scaffolder (6.3.0); using the current CLI's template as the merge base.`);
+	const scaffoldCapable = 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) console.warn(`⚠️  @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", [
@@ -92,7 +96,8 @@ async function scaffoldBaseline(version, name, template, mpoVersion) {
 				"--skip-install",
 				"--mpo-version",
 				mpoVersion,
-				...templateFlag
+				...templateFlag,
+				...pieceFlags
 			], {
 				cwd: parent,
 				stdio: "inherit"
@@ -121,7 +126,8 @@ async function scaffoldBaseline(version, name, template, mpoVersion) {
 			skipGit: true,
 			yes: true,
 			template,
-			version: mpoVersion
+			version: mpoVersion,
+			pieces
 		});
 	} finally {
 		process.chdir(previousCwd);
@@ -175,6 +181,144 @@ async function pinPathsToHead(projectDir, tree, headCommit, pins) {
 	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 = [];
+	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));
+		return {
+			tree,
+			conflicts: conflicts.filter((file) => !resolvedPaths.has(file)),
+			resolved: [...resolvedPaths]
+		};
+	} finally {
+		rmSync(scratch, {
+			recursive: true,
+			force: true
+		});
+	}
+}
 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");
@@ -195,11 +339,12 @@ async function updateApp(options = {}) {
 	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}`);
+	if (provenance.pieces.length) console.log(`  pieces:   ${provenance.pieces.join(", ")}`);
 	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);
+	const 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);
+	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 });
 	try {
@@ -228,7 +373,8 @@ async function updateApp(options = {}) {
 			template: provenance.template,
 			cliVersion: currentVersion,
 			name: provenance.name,
-			mpoVersion: targetMpoRange
+			mpoVersion: targetMpoRange,
+			pieces: provenance.pieces
 		};
 		const pins = ["pnpm-lock.yaml"];
 		const updateignore = join(projectDir, ".updateignore");
@@ -238,6 +384,10 @@ async function updateApp(options = {}) {
 		}
 		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) {
@@ -257,6 +407,7 @@ async function updateApp(options = {}) {
 			} 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, [
@@ -294,12 +445,7 @@ async function updateApp(options = {}) {
 				"--no-edit",
 				"--quiet"
 			]);
-			const amended = await gitOut(projectDir, [
-				"rev-parse",
-				"--short",
-				"HEAD"
-			]);
-			console.log(`\n✅ merged cleanly → ${amended} ("${message}")`);
+			cleanMergeMessage = message;
 		} else {
 			await git(projectDir, [
 				"read-tree",
@@ -340,6 +486,14 @@ async function updateApp(options = {}) {
 				}
 			}
 		}
+		if (cleanMergeMessage) {
+			const finalHash = await gitOut(projectDir, [
+				"rev-parse",
+				"--short",
+				"HEAD"
+			]);
+			console.log(`\n✅ merged cleanly → ${finalHash} ("${cleanMergeMessage}")`);
+		}
 	} finally {
 		base.cleanup();
 		next.cleanup();
@@ -347,4 +501,4 @@ async function updateApp(options = {}) {
 }
 
 //#endregion
-export { updateApp };
+export { threeWayMergePackageJson, updateApp };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/cli",
-  "version": "6.4.3",
+  "version": "6.7.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.4.3"
+    "@multiplatform.one/utils": "6.7.0"
   },
   "devDependencies": {
     "@types/inquirer": "^9.0.9",
@@ -75,6 +75,6 @@
   "scripts": {
     "build": "rm -rf lib types 2>/dev/null && tsc -p tsconfig.build.json && tsdown",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsgo --noEmit"
   }
 }