@multiplatform.one/cli 7.11.0 → 7.16.0

package/lib/commands/merge.mjs

@@ -0,0 +1,359 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import spawn from "nano-spawn";
+import { tmpdir } from "node:os";
+
+//#region src/commands/merge.ts
+/**
+* The three-way merge behind `mpo update` and `mpo add-app`:
+*
+*   base   = the scaffold the project started from (recorded in .mpo.json)
+*   ours   = the project's HEAD (every commit the project made)
+*   theirs = the scaffold it is moving to
+*
+* `git merge-tree --write-tree --merge-base=<base>` merges the scaffold's
+* evolution with the project's history; the result lands in the index and
+* worktree, never in a commit, so the project commits when it is happy.
+* `.updateignore` entries (exact files or directory prefixes, not globs) and
+* pnpm-lock.yaml stay pinned to HEAD.
+*/
+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();
+}
+async function projectRootOf(command) {
+	return gitOut(process.cwd(), ["rev-parse", "--show-toplevel"]).catch(() => {
+		throw new Error(`${command} must run inside a git repository`);
+	});
+}
+/** The merge lands in the worktree, so nothing else may be in flight there. */
+async function requireCleanTree(projectDir, command) {
+	await git(projectDir, ["rev-parse", "HEAD"]).catch(() => {
+		throw new Error(`${command} requires at least one commit`);
+	});
+	await git(projectDir, ["diff", "--quiet"]).catch(() => {
+		throw new Error(`${command} requires a clean working tree (unstaged changes present)`);
+	});
+	await git(projectDir, [
+		"diff",
+		"--cached",
+		"--quiet"
+	]).catch(() => {
+		throw new Error(`${command} requires a clean working tree (staged changes present)`);
+	});
+}
+/** Import a directory tree into the project's object database as a
+*  commit (temp index; the worktree is never touched). The directory's own
+*  .gitignore applies, so a generated .env never enters the tree. */
+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",
+		"--",
+		"."
+	], 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;
+}
+async function emptyCommit(projectDir, message) {
+	const indexFile = join(mkdtempSync(join(tmpdir(), "mpo-index-")), "index");
+	const env = { GIT_INDEX_FILE: indexFile };
+	await git(projectDir, ["read-tree", "--empty"], env);
+	const tree = await gitOut(projectDir, ["write-tree"], env);
+	rmSync(indexFile, { force: true });
+	return gitOut(projectDir, [
+		"commit-tree",
+		tree,
+		"-m",
+		message
+	]);
+}
+/** A tree derived from `tree` where every path under `pins` is replaced by
+*  its content in `headCommit` (removed when absent there). */
+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;
+}
+/**
+* Pins: pnpm-lock.yaml plus every .updateignore entry. Entries are exact
+* files or directory prefixes (`git ls-tree -- <path>` semantics); the one
+* natural glob spelling (`dir/**`, `dir/*`) normalizes to its directory and
+* any other glob shape is refused, because a silently dead ignore rule is
+* the worst failure mode.
+*/
+function readPins(projectDir) {
+	const pins = ["pnpm-lock.yaml"];
+	const updateignore = join(projectDir, ".updateignore");
+	if (!existsSync(updateignore)) return pins;
+	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(/\/+$/, ""));
+	}
+	return pins;
+}
+const UNRESOLVED = Symbol("unresolved");
+const ABSENT = Symbol("absent");
+const DEP_MAP_KEYS = new Set([
+	"dependencies",
+	"devDependencies",
+	"peerDependencies",
+	"optionalDependencies",
+	"overrides",
+	"resolutions"
+]);
+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, or undefined when a
+*  divergence cannot be auto-resolved (the textual markers then stay). */
+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;
+}
+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
+		});
+	}
+}
+/** Compute the merged tree. Pure object-database work; nothing is written to the worktree. */
+async function mergeScaffolds(request) {
+	const { projectDir } = request;
+	const head = await gitOut(projectDir, ["rev-parse", "HEAD"]);
+	const baseCommit = request.baseDir ? await commitTreeFromDir(projectDir, request.baseDir, request.baseLabel) : await emptyCommit(projectDir, request.baseLabel);
+	const nextCommit = await commitTreeFromDir(projectDir, request.theirsDir, request.theirsLabel, 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);
+	}
+	const pins = readPins(projectDir);
+	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);
+	const headTree = await gitOut(projectDir, ["rev-parse", `${head}^{tree}`]);
+	return {
+		mergedTree: autoResolved.tree,
+		changed: autoResolved.tree !== headTree,
+		conflicts: autoResolved.conflicts,
+		resolved: autoResolved.resolved
+	};
+}
+/** Land a tree in the index and worktree. The tree was clean before, so
+*  every difference is the merge; nothing is committed. */
+async function landTree(projectDir, tree) {
+	await git(projectDir, [
+		"read-tree",
+		"-u",
+		"--reset",
+		tree
+	]);
+}
+/** Print the outcome and the commit line; run pnpm install on a clean merge. */
+async function finishMerge(projectDir, outcome, commitMessage, options = {}) {
+	for (const file of outcome.resolved) console.log(`   auto-resolved: ${file} (dependency ranges)`);
+	if (outcome.conflicts.length) {
+		console.log("\n⚠️  merge conflicts — resolve the markers, then commit:");
+		for (const file of outcome.conflicts) console.log(`   ${file}`);
+	} else console.log("\n✅ merged cleanly into the index and worktree (nothing committed)");
+	if (outcome.conflicts.length) {
+		if (!options.skipInstall) console.log("\nSkipping pnpm install until the conflicts are resolved (then run: pnpm install).");
+	} else if (!options.skipInstall) {
+		console.log("\nInstalling dependencies...");
+		await spawn("pnpm", ["install"], {
+			cwd: projectDir,
+			stdio: "inherit"
+		});
+	}
+	console.log(`\nReview with git status / git diff, then:\n   git add -A && git commit -m "${commitMessage}"`);
+}
+
+//#endregion
+export { finishMerge, git, gitOut, landTree, mergeScaffolds, projectRootOf, readPins, requireCleanTree, threeWayMergePackageJson };

package/lib/commands/pieces.mjs

@@ -0,0 +1,236 @@
+import { cliRoot } from "./provenance.mjs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { extname, join } from "node:path";
+
+//#region src/commands/pieces.ts
+/**
+* Pieces: additive fragment trees under templates/pieces/<piece>/ that an
+* ADOPTED project (`mpo adopt`) hand-copied and wants `mpo update` to keep
+* reconciling. A project from `mpo init` never needs them: apps/one already
+* ships gnome/, tauri/, vscode/ and webext/, and frappe / keycloak are
+* `--service` selections of the real apps. Keep sorted: pieces are recorded
+* sorted in provenance and overlaid in this order.
+*/
+const INIT_APP_PIECES = [
+	"frappe",
+	"frappe-bench",
+	"gnome",
+	"keycloak",
+	"tauri",
+	"vscode",
+	"webext"
+];
+const PIECE_DESCRIPTIONS = {
+	frappe: "Frappe client wiring (env keys, provider)",
+	"frappe-bench": "Frappe dev bench (docker compose: bench, MariaDB, Redis)",
+	gnome: "GNOME desktop target (GTK4/GJS via react-gnome — native widgets, no webview)",
+	keycloak: "Keycloak auth wiring (env keys, provider, docker compose + realm)",
+	tauri: "Tauri desktop target (src-tauri skeleton — webview shell, Rust toolchain)",
+	vscode: "VS Code extension target (extension host + Tamagui webview)",
+	webext: "Browser extension target (MV3 popup + background)"
+};
+function piecesRoot() {
+	return join(cliRoot(), "templates/pieces");
+}
+function toPascalCase(name) {
+	return name.split(/[-_\s]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+/**
+* Fragment source dirs for a piece: shared/ plus universal/ (the layout
+* adopted repos follow: apps/<name>/...). A piece is available when at least
+* one of the two exists.
+*/
+function pieceFragmentDirs(piece, root) {
+	return [join(root, piece, "shared"), join(root, piece, "universal")].filter((dir) => existsSync(dir));
+}
+/**
+* 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",
+	"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);
+}
+/** Assets copied byte-for-byte; the utf-8 render pass would corrupt them. */
+const BINARY_EXTENSIONS = new Set([
+	".woff2",
+	".woff",
+	".ttf",
+	".otf",
+	".png",
+	".jpg",
+	".ico",
+	".icns"
+]);
+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), 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;
+}
+const SORTED_DEPENDENCY_FIELDS = [
+	"dependencies",
+	"devDependencies",
+	"peerDependencies",
+	"optionalDependencies"
+];
+/** Dependency maps stay sorted after fragment merges so overlay order never changes the bytes. */
+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)
+*   - 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: regular files render and overwrite,
+* `<target>.partial` files merge into (or create) their target.
+*/
+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: unknown names throw, duplicates
+* collapse, order is always sorted, and every piece must ship a fragment.
+*/
+function normalizePieces(pieces, root = piecesRoot()) {
+	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, root).length === 0) throw new Error(`Piece "${piece}" ships no fragments under ${root}`);
+	}
+	return normalized;
+}
+/**
+* The frappe piece carried the dev bench until the bench became its own piece
+* (MPO-241). An adoption recorded against pieces that still bundle it keeps
+* the bench, now as frappe-bench, so an update does not delete it.
+*/
+function withSplitPieces(pieces, recordedRoot) {
+	if (!recordedRoot || !pieces.includes("frappe") || pieces.includes("frappe-bench")) return pieces;
+	if (!existsSync(join(recordedRoot, "frappe/universal/docker/compose.frappe.yaml"))) return pieces;
+	return [...pieces, "frappe-bench"].sort();
+}
+function availablePieces(root = piecesRoot()) {
+	return INIT_APP_PIECES.filter((piece) => pieceFragmentDirs(piece, root).length > 0);
+}
+function pieceDescription(piece) {
+	return PIECE_DESCRIPTIONS[piece];
+}
+/**
+* apps/<name>/src/app.ts for the selected backend pieces: each provider
+* adds one createApp key. Only written when a provider piece is selected.
+*/
+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", " * this project adopted — 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 client: FrappeProvider mounts when FRAPPE_ENABLED=1 (a", "  // packages/config public env key, loaded from .env — see", "  // .env.example). FRAPPE_URL names the Frappe server (default:", "  // BASE_URL, then http://localhost:8000).");
+		if (pieces.includes("frappe-bench")) lines.push("  // docker/compose.frappe.yaml runs a dev bench.");
+		lines.push("  frappe: { baseURL: config.get(\"FRAPPE_URL\") },");
+	}
+	if (keycloak) lines.push("  // Keycloak auth: 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");
+}
+/**
+* The tool-owned surface of an adopted project: the selected piece
+* fragments overlaid, in sorted order, on an EMPTY tree. `mpo update`
+* builds both merge baselines of an adopted project with this.
+*/
+function scaffoldPieces(targetDir, request) {
+	const root = request.root ?? piecesRoot();
+	const pieces = normalizePieces(request.pieces, root);
+	if (!pieces.length) throw new Error(`A pieces scaffold needs at least one piece (${INIT_APP_PIECES.map((piece) => `--${piece}`).join(", ")})`);
+	const vars = {
+		NAME: request.name,
+		NAME_PASCAL: toPascalCase(request.name),
+		NAME_APPID: request.name.replaceAll("-", ""),
+		MPO_VERSION: request.mpoVersion,
+		YEAR: String((/* @__PURE__ */ new Date()).getFullYear())
+	};
+	mkdirSync(targetDir, { recursive: true });
+	for (const piece of pieces) for (const fragmentDir of pieceFragmentDirs(piece, root)) overlayTree(fragmentDir, targetDir, vars);
+	if (pieces.includes("frappe") || pieces.includes("keycloak")) {
+		mkdirSync(join(targetDir, "apps", request.name, "src"), { recursive: true });
+		writeFileSync(join(targetDir, "apps", request.name, "src/app.ts"), composeAppTs(pieces));
+	}
+}
+
+//#endregion
+export { INIT_APP_PIECES, availablePieces, composeAppTs, mergeJsonValues, normalizePieces, pieceDescription, piecesRoot, scaffoldPieces, withSplitPieces };