@multiplatform.one/cli 6.7.0 → 7.0.0

package/README.md

@@ -52,23 +52,98 @@ the interactive prompt; they are recorded in `.mpo.json` and reproduced by
 | `--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.
+`--gnome` is the desktop piece. It renders your Tamagui components as native
+GTK widgets laid out by Yoga — not the web build in a frame — so the app looks
+and behaves like part of the desktop. Linux-first.
+
+## Update a project
+
+`mpo update` upgrades a project to the current templates with a three-way
+merge driven by `.mpo.json` (written at init time): base = the original
+scaffold regenerated at the recorded CLI version, ours = your HEAD, theirs =
+a fresh scaffold from the current CLI. `.updateignore` entries (exact files or directory prefixes — not globs) (and
+`pnpm-lock.yaml`) stay pinned to your version; `package.json` dependency-range
+drift auto-resolves to the newer minimum.
+
+**Idempotency contract:** re-running `mpo update` immediately after a
+successful update makes zero changes (clean `git status`). Run it, see no
+changes, know you're current.
+
+### Adopt an existing project
+
+A project that was never scaffolded — it hand-copied a delivery target
+(webext, gnome, …) and uses `@multiplatform.one/*` from npm — has no
+provenance. Bring it under `mpo update` management:
+
+```bash
+mpo adopt --webext --name my-app   # requires a clean git tree; ≥ 1 piece
+```
+
+Adoption writes `.mpo.json` (template `"none"` + pieces) and seeds
+`.updateignore`; **it changes no project files**. The FIRST `mpo update`
+afterwards reconciles the piece files from an empty merge base, so diffs and
+conflicts on hand-copied files are expected — resolve and commit. Later
+updates are ordinary three-way merges (baselines come from
+`mpo init --pieces-only` at the recorded version).
+
+### Bootstrap missing provenance
+
+Scaffolded before `.mpo.json` existed (CLI ≤ 6.3.0)? Assert the version it
+was scaffolded with instead of hand-writing the file:
+
+```bash
+mpo update --assume-version 6.3.0 [--template universal|app]
+```
+
+## Update a project
+
+`mpo update` upgrades a project to the current templates with a three-way
+merge driven by `.mpo.json` (written at init time): base = the original
+scaffold regenerated at the recorded CLI version, ours = your HEAD, theirs =
+a fresh scaffold from the current CLI. `.updateignore` entries (exact files or directory prefixes — not globs) (and
+`pnpm-lock.yaml`) stay pinned to your version; `package.json` dependency-range
+drift auto-resolves to the newer minimum.
+
+**Idempotency contract:** re-running `mpo update` immediately after a
+successful update makes zero changes (clean `git status`). Run it, see no
+changes, know you're current.
+
+### Adopt an existing project
+
+A project that was never scaffolded — it hand-copied a delivery target
+(webext, tauri, …) and uses `@multiplatform.one/*` from npm — has no
+provenance. Bring it under `mpo update` management:
+
+```bash
+mpo adopt --webext --name my-app   # requires a clean git tree; ≥ 1 piece
+```
+
+Adoption writes `.mpo.json` (template `"none"` + pieces) and seeds
+`.updateignore`; **it changes no project files**. The FIRST `mpo update`
+afterwards reconciles the piece files from an empty merge base, so diffs and
+conflicts on hand-copied files are expected — resolve and commit. Later
+updates are ordinary three-way merges (baselines come from
+`mpo init --pieces-only` at the recorded version).
+
+### Bootstrap missing provenance
+
+Scaffolded before `.mpo.json` existed (CLI ≤ 6.3.0)? Assert the version it
+was scaffolded with instead of hand-writing the file:
+
+```bash
+mpo update --assume-version 6.3.0 [--template universal|app]
+```
 
 ## Other commands
 
 | Command                      | Purpose                                                              |
 | ---------------------------- | -------------------------------------------------------------------- |
 | `mpo init --monorepo [name]` | DEPRECATED: clone/modify the full monorepo (framework dev forks)     |
-| `mpo update`                 | Merge upstream and re-apply workspace config                         |
+| `mpo adopt`                  | Write provenance into an existing, never-scaffolded project          |
+| `mpo update`                 | Three-way template update via `.mpo.json` (legacy merge for forks)   |
 | `mpo wait`                   | Wait for a service (frappe, postgres, mariadb, keycloak) to be ready |
 | `mpo frappe bootstrap`       | Bootstrap the Frappe development environment                         |
 | `mpo frappe dev`             | Start the Frappe development server                                  |

package/lib/bin/multiplatformOne.mjs

@@ -1,7 +1,8 @@
 import { generateVscodeConfig } from "../generateVscode.mjs";
+import { INIT_APP_PIECES, initApp, readProvenance } from "../commands/initApp.mjs";
+import { adoptApp } from "../commands/adoptApp.mjs";
 import { discoverE2EApp, runE2ESession } from "../commands/e2e.mjs";
 import { init, runModifyStep } from "../commands/init.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 +472,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("--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) => {
+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 Tauri desktop target piece (src-tauri webview shell — Rust; combines with --gnome)").option("--vscode", "add the VS Code extension target piece").option("--webext", "add the browser extension target piece (MV3 popup + background)").option("--pieces-only", "scaffold ONLY the selected piece fragments onto an empty tree (no base template) — used by `mpo update` to rebuild adopted-project merge baselines").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,26 +486,39 @@ 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");
+	if (options.piecesOnly && (webOnly || options.universal)) throw new Error("--pieces-only scaffolds no base template — drop --web/--universal");
 	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,
+		template: options.piecesOnly ? "none" : webOnly ? "app" : options.universal ? "universal" : void 0,
 		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) => {
+program.command("adopt").option("--frappe", "the project adopted the Frappe backend piece").option("--keycloak", "the project adopted the Keycloak auth piece").option("--gnome", "the project adopted the GNOME desktop target piece").option("--tauri", "the project adopted the Tauri desktop target piece").option("--vscode", "the project adopted the VS Code extension target piece").option("--webext", "the project adopted the browser extension target piece").option("--name <name>", "project name recorded in provenance (default: package.json name, scope stripped) — it renders piece paths (apps/<name>/…), so match your app directory").option("-y, --yes", "non-interactive: never prompt (pieces must come from flags)").description("bring an existing, never-scaffolded project under `mpo update` management: writes .mpo.json provenance (and seeds .updateignore) without changing any project file — the FIRST `mpo update` afterwards reconciles piece files (real diffs expected)").action(async (options) => {
+	const pieces = INIT_APP_PIECES.filter((piece) => Boolean(options[piece]));
+	await adoptApp({
+		pieces: pieces.length ? pieces : void 0,
+		name: options.name,
+		yes: Boolean(options.yes)
+	});
+});
+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>)").option("--assume-version <cliVersion>", "bootstrap missing .mpo.json: assume the project was scaffolded by this exact CLI version, record provenance, then update").option("--template <template>", "template recorded by --assume-version (universal|app, default universal)").description("update a scaffolded or adopted 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)) {
+	if (options.template && !options.assumeVersion) throw new Error("--template only applies to the --assume-version bootstrap");
+	if (options.template && options.template !== "universal" && options.template !== "app") throw new Error(`--template must be universal or app, got "${options.template}"`);
+	if (readProvenance(projectRoot) || options.assumeVersion) {
 		await updateApp({
 			skipInstall: options.skipInstall,
-			version: options.mpoVersion
+			version: options.mpoVersion,
+			assumeVersion: options.assumeVersion,
+			assumeTemplate: options.template
 		});
 		return;
 	}
-	if (!await fs.stat(path.resolve(projectRoot, "features/package.json")).then((stat) => stat.isFile(), () => false)) 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`.");
+	if (!await fs.stat(path.resolve(projectRoot, "features/package.json")).then((stat) => stat.isFile(), () => false)) throw new Error(".mpo.json not found — this project predates scaffold provenance.\n  - scaffolded by an old CLI (pre-6.3)? bootstrap it:\n      mpo update --assume-version <cliVersion> [--template universal|app]\n  - never scaffolded (hand-adopted pieces)? bring it under management:\n      mpo adopt --<piece> [...]");
 	if (await spawn("git", [
 		"diff",
 		"--cached",

package/lib/commands/adoptApp.mjs

@@ -0,0 +1,127 @@
+import { INIT_APP_PIECES, PROVENANCE_FILE, availablePieces, cliVersion, normalizePieces, packageJsonName, pieceDescription, validateName, writeProvenance } from "./initApp.mjs";
+import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import spawn from "nano-spawn";
+import inquirer from "inquirer";
+
+//#region src/commands/adoptApp.ts
+/**
+* `mpo adopt` — bring an EXISTING, never-scaffolded project under `mpo
+* update` management. Projects like this hand-copied one or more delivery
+* targets (webext, gnome, …) from the mpo templates and consume
+* @multiplatform.one/* from npm, but have no .mpo.json provenance, so
+* `mpo update` refuses to run.
+*
+* Adoption writes provenance ONLY (template "none" + the chosen pieces +
+* the current CLI version) and seeds .updateignore — it never rewrites a
+* project file. The FIRST `mpo update` afterwards reconciles the piece
+* files against the piece templates from an empty merge base, so real
+* diffs (and conflicts) against hand-copied files are expected there;
+* every later update is an ordinary three-way merge.
+*/
+const UPDATEIGNORE_FILE = ".updateignore";
+const UPDATEIGNORE_SEED = `# .updateignore — \`mpo update\` never rewrites paths listed here.
+# One git pathspec per line; matching paths stay pinned to YOUR version
+# during template updates. Lines starting with "#" are comments.
+`;
+async function git(projectDir, args) {
+	return spawn("git", args, { cwd: projectDir });
+}
+/**
+* The multiplatform.one monorepo (and its forks) is the home of the
+* templates themselves — adopting it into consumer-project update
+* management would be circular. It is identified by the CLI package
+* living at public/cli.
+*/
+function isMpoMonorepo(projectDir) {
+	try {
+		return JSON.parse(readFileSync(join(projectDir, "public/cli/package.json"), "utf-8")).name === "@multiplatform.one/cli";
+	} catch {
+		return false;
+	}
+}
+async function resolveAdoptPieces(options) {
+	if (options.pieces?.length) return normalizePieces(options.pieces, "none");
+	if (!options.yes && process.stdout.isTTY) return normalizePieces((await inquirer.prompt([{
+		message: "Which pieces did this project adopt? (space to toggle, enter to confirm)",
+		name: "pieces",
+		type: "checkbox",
+		choices: availablePieces("none").map((piece) => ({
+			name: `${piece} — ${pieceDescription(piece)}`,
+			value: piece,
+			checked: false
+		})),
+		validate: (selection) => selection.length > 0 || "Select at least one piece — adopting nothing is meaningless"
+	}])).pieces, "none");
+	throw new Error(`mpo adopt needs at least one piece (${INIT_APP_PIECES.map((piece) => `--${piece}`).join(", ")}) — adopting nothing is meaningless`);
+}
+async function adoptApp(options = {}) {
+	const projectDir = await spawn("git", ["rev-parse", "--show-toplevel"], { cwd: process.cwd() }).then((result) => result.stdout.trim(), () => {
+		throw new Error("mpo adopt must run inside a git repository");
+	});
+	if (isMpoMonorepo(projectDir)) throw new Error("mpo adopt cannot run inside the multiplatform.one monorepo (or a fork of it) — it is for consumer projects that use @multiplatform.one/* from npm");
+	if (existsSync(join(projectDir, ".mpo.json"))) throw new Error(`${PROVENANCE_FILE} already exists — this project already has scaffold provenance. Run \`mpo update\` directly.`);
+	await git(projectDir, ["rev-parse", "HEAD"]).catch(() => {
+		throw new Error("mpo adopt requires at least one commit — commit your project first");
+	});
+	await git(projectDir, ["diff", "--quiet"]).catch(() => {
+		throw new Error("mpo adopt requires a clean working tree (unstaged changes present)");
+	});
+	await git(projectDir, [
+		"diff",
+		"--cached",
+		"--quiet"
+	]).catch(() => {
+		throw new Error("mpo adopt requires a clean working tree (staged changes present)");
+	});
+	const rawName = options.name ?? packageJsonName(projectDir);
+	if (!rawName) throw new Error("Could not derive a project name from package.json — pass one with --name <name>");
+	let name;
+	try {
+		name = validateName(rawName);
+	} catch (err) {
+		throw new Error(`${err.message} The name renders piece file paths (apps/<name>/…), so pick the one matching your app directory: --name <name>.`);
+	}
+	const pieces = await resolveAdoptPieces(options);
+	const currentVersion = cliVersion() ?? "0.0.0";
+	writeProvenance(projectDir, {
+		template: "none",
+		cliVersion: currentVersion,
+		name,
+		mpoVersion: `^${currentVersion}`,
+		pieces,
+		reconciled: false
+	});
+	const files = [PROVENANCE_FILE];
+	if (!existsSync(join(projectDir, UPDATEIGNORE_FILE))) {
+		writeFileSync(join(projectDir, UPDATEIGNORE_FILE), UPDATEIGNORE_SEED);
+		files.push(UPDATEIGNORE_FILE);
+	}
+	await git(projectDir, [
+		"add",
+		"--",
+		...files
+	]);
+	const committed = await git(projectDir, [
+		"commit",
+		"--quiet",
+		"-m",
+		"chore: adopt multiplatform.one tooling (mpo adopt)"
+	]).then(() => true, () => {
+		console.warn("⚠️  git commit failed (missing git identity?) — provenance left staged.");
+		return false;
+	});
+	console.log(`\n✅ adopted ${name} (pieces: ${pieces.join(", ")}, cli ${currentVersion})`);
+	console.log(`   ${files.join(" + ")} ${committed ? "committed" : "written"} — NO project files`);
+	console.log("   were changed by adoption itself.\n");
+	console.log("Next: run `mpo update` to reconcile the piece files.");
+	console.log("   THE FIRST UPDATE SURFACES REAL DIFFS: your hand-copied piece files");
+	console.log("   are merged against the piece templates from scratch, so conflicts");
+	console.log("   there are expected — resolve the markers and commit. Later updates");
+	console.log("   are ordinary three-way merges, and re-running `mpo update` right");
+	console.log("   after a successful update makes zero changes.");
+	console.log(`Pin anything the updater must never touch in ${UPDATEIGNORE_FILE}.`);
+}
+
+//#endregion
+export { adoptApp };

package/lib/commands/init.mjs

@@ -1,7 +1,7 @@
 import { join, resolve } from "node:path";
 import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
-import { execSync } from "node:child_process";
 import inquirer from "inquirer";
+import { execSync } from "node:child_process";
 
 //#region src/commands/init.ts
 const repoUrl = "https://gitlab.com/bitspur/frappe/multiplatform.one.git";

package/lib/commands/initApp.mjs

@@ -23,7 +23,7 @@ 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)",
+	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)"
 };
@@ -36,6 +36,15 @@ function validateName(name) {
 	if (!/^[a-z][a-z0-9-]*$/.test(trimmed)) throw new Error(`Invalid project name "${trimmed}". Use lowercase letters, numbers, and hyphens (e.g. my-app).`);
 	return trimmed;
 }
+/** Root package.json name with any @scope/ prefix stripped (adopt +
+*  update-bootstrap provenance name derivation). */
+function packageJsonName(projectDir) {
+	try {
+		return JSON.parse(readFileSync(join(projectDir, "package.json"), "utf-8")).name?.replace(/^@[^/]+\//u, "");
+	} catch {
+		return;
+	}
+}
 function resolveMpoVersion(explicit) {
 	if (explicit) return explicit.startsWith("^") || explicit.startsWith("~") || explicit === "*" ? explicit : `^${explicit}`;
 	const version = cliVersion();
@@ -67,7 +76,8 @@ function readProvenance(projectDir) {
 			cliVersion: raw.cliVersion,
 			name: raw.name,
 			mpoVersion: raw.mpoVersion ?? `^${raw.cliVersion}`,
-			pieces: Array.isArray(raw.pieces) ? [...raw.pieces].sort() : []
+			pieces: Array.isArray(raw.pieces) ? [...raw.pieces].sort() : [],
+			...raw.reconciled === false ? { reconciled: false } : {}
 		};
 	} catch {
 		return;
@@ -82,10 +92,13 @@ function piecesRoot(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.
+* at least one of the two exists. Adopted projects (template "none") use the
+* universal fragment set — pieces ship universal-layout fragments
+* (apps/<name>/…), which is the layout adopted repos follow.
 */
 function pieceFragmentDirs(piece, template) {
-	return [join(piecesRoot(piece), "shared"), join(piecesRoot(piece), template)].filter((dir) => existsSync(dir));
+	const effective = template === "none" ? "universal" : template;
+	return [join(piecesRoot(piece), "shared"), join(piecesRoot(piece), effective)].filter((dir) => existsSync(dir));
 }
 /**
 * npm always strips .gitignore / .npmrc (and newer npms .env*) from published
@@ -246,6 +259,10 @@ function normalizePieces(pieces, template) {
 function availablePieces(template) {
 	return INIT_APP_PIECES.filter((piece) => pieceFragmentDirs(piece, template).length > 0);
 }
+/** Human-readable piece summaries (adopt + init prompts). */
+function pieceDescription(piece) {
+	return PIECE_DESCRIPTIONS[piece];
+}
 async function resolvePieces(options, template) {
 	if (options.pieces) return normalizePieces(options.pieces, template);
 	if (options.yes || !process.stdout.isTTY) return [];
@@ -315,6 +332,7 @@ async function initApp(nameArg, options = {}) {
 	const name = validateName(projectName);
 	const template = await resolveTemplate(options);
 	const pieces = await resolvePieces(options, template);
+	if (template === "none" && pieces.length === 0) throw new Error(`A pieces-only scaffold needs at least one piece (${INIT_APP_PIECES.map((piece) => `--${piece}`).join(", ")})`);
 	const targetDir = resolve(name);
 	if (existsSync(targetDir)) {
 		if (readdirSync(targetDir).length > 0) throw new Error(`Directory "${targetDir}" already exists and is not empty`);
@@ -326,19 +344,25 @@ async function initApp(nameArg, options = {}) {
 		MPO_VERSION: resolveMpoVersion(options.version),
 		YEAR: String((/* @__PURE__ */ new Date()).getFullYear())
 	};
-	console.log(`\nScaffolding ${template === "universal" ? "universal (web + iOS + Android)" : "web-only"} project at ${targetDir}`);
-	console.log(`  apps/${name}`);
-	console.log(`  features/${name}`);
-	console.log(`  packages/config`);
+	console.log(`\nScaffolding ${template === "universal" ? "universal (web + iOS + Android)" : template === "app" ? "web-only" : "pieces-only (adopted-project baseline)"} project at ${targetDir}`);
+	if (template !== "none") {
+		console.log(`  apps/${name}`);
+		console.log(`  features/${name}`);
+		console.log(`  packages/config`);
+	}
 	if (template === "universal") {
 		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);
+	if (template === "none") mkdirSync(targetDir, { recursive: true });
+	else 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));
+	if (pieces.includes("frappe") || pieces.includes("keycloak")) {
+		mkdirSync(join(targetDir, "apps", name, "src"), { recursive: true });
+		writeFileSync(join(targetDir, "apps", name, "src/app.ts"), composeAppTs(pieces));
+	}
 	writeProvenance(targetDir, {
 		template,
 		cliVersion: cliVersion() ?? "0.0.0",
@@ -349,7 +373,7 @@ async function initApp(nameArg, options = {}) {
 	let scaffoldCommitted = false;
 	if (!options.skipGit) {
 		if (!await spawn("git", ["rev-parse", "--is-inside-work-tree"], { cwd: targetDir }).then(() => true, () => false)) {
-			const label = template === "universal" ? "universal" : "web-only";
+			const label = template === "universal" ? "universal" : template === "app" ? "web-only" : "pieces-only";
 			await spawn("git", ["init", "--quiet"], { cwd: targetDir });
 			await spawn("git", ["add", "-A"], { cwd: targetDir });
 			scaffoldCommitted = await spawn("git", [
@@ -363,7 +387,7 @@ async function initApp(nameArg, options = {}) {
 			});
 		}
 	}
-	if (!options.skipInstall) {
+	if (!options.skipInstall && template !== "none") {
 		console.log("Installing dependencies...");
 		await spawn("pnpm", ["install"], {
 			cwd: targetDir,
@@ -379,8 +403,12 @@ async function initApp(nameArg, options = {}) {
 			"--no-edit",
 			"--quiet"
 		], { cwd: targetDir })).catch(() => {});
-	} else console.log("Skipped pnpm install (--skip-install).");
+	} else if (options.skipInstall) console.log("Skipped pnpm install (--skip-install).");
 	console.log(`\n✅ Project created at ${targetDir}`);
+	if (template === "none") {
+		console.log("\nPieces-only tree (adopted-project baseline) — not a runnable project.");
+		return;
+	}
 	console.log("\nNext steps:");
 	console.log(`  cd ${name}`);
 	if (options.skipInstall) console.log("  pnpm install");
@@ -392,7 +420,7 @@ async function initApp(nameArg, options = {}) {
 	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("tauri")) console.log("  pnpm tauri:dev   # Tauri 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.");
@@ -400,4 +428,4 @@ async function initApp(nameArg, options = {}) {
 }
 
 //#endregion
-export { INIT_APP_PIECES, PROVENANCE_FILE, availablePieces, cliVersion, composeAppTs, initApp, mergeJsonValues, normalizePieces, readProvenance, writeProvenance };
+export { INIT_APP_PIECES, PROVENANCE_FILE, availablePieces, cliVersion, composeAppTs, initApp, mergeJsonValues, normalizePieces, packageJsonName, pieceDescription, readProvenance, validateName, writeProvenance };

package/lib/commands/updateApp.mjs

@@ -1,5 +1,5 @@
 import { generateVscodeConfig } from "../generateVscode.mjs";
-import { cliVersion, initApp, readProvenance, writeProvenance } from "./initApp.mjs";
+import { PROVENANCE_FILE, cliVersion, initApp, packageJsonName, readProvenance, validateName, writeProvenance } from "./initApp.mjs";
 import { basename, join } from "node:path";
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import spawn from "nano-spawn";
@@ -19,8 +19,9 @@ import { tmpdir } from "node:os";
 *
 * `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.
+* 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.
 */
 async function git(projectDir, args, env) {
 	return spawn("git", args, {
@@ -76,14 +77,15 @@ async function scaffoldBaseline(version, name, template, mpoVersion, pieces) {
 		force: true
 	});
 	const current = cliVersion();
-	const templateFlag = template === "app" ? ["--web"] : ["--universal"];
+	const templateFlag = template === "none" ? ["--pieces-only"] : template === "app" ? ["--web"] : ["--universal"];
 	const [major = 0, minor = 0] = version.split(".").map(Number);
-	const scaffoldCapable = major > 6 || major === 6 && minor >= 3;
+	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) 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) {
+	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",
@@ -103,7 +105,7 @@ async function scaffoldBaseline(version, name, template, mpoVersion, pieces) {
 				stdio: "inherit"
 			});
 			const dir = join(parent, name);
-			if (existsSync(join(dir, "package.json"))) return {
+			if (existsSync(join(dir, template === "none" ? ".mpo.json" : "package.json"))) return {
 				dir,
 				cleanup
 			};
@@ -319,6 +321,42 @@ async function autoResolveDependencyConflicts(projectDir, mergedTree, conflicts,
 		});
 	}
 }
+/**
+* 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");
@@ -333,16 +371,44 @@ async function updateApp(options = {}) {
 	]).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`.");
+	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> [...]`);
 	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}`);
+	console.log(`  template: ${provenance.template}${adopted ? " (adopted)" : ""}`);
 	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, provenance.pieces);
+	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 });
@@ -380,7 +446,10 @@ async function updateApp(options = {}) {
 		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);
+			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}/`)));
@@ -390,7 +459,7 @@ async function updateApp(options = {}) {
 		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) {
+			if (provenance.cliVersion !== finalProvenance.cliVersion || provenance.mpoVersion !== finalProvenance.mpoVersion || provenance.reconciled === false) {
 				writeProvenance(projectDir, finalProvenance);
 				await git(projectDir, [
 					"add",