@multiplatform.one/cli 7.11.0 → 7.15.0

package/README.md

@@ -1,8 +1,8 @@
 # @multiplatform.one/cli
 
-The multiplatform.one command line: scaffold new multiplatform projects
-(`mpo init` / `create-multiplatform-app`), manage the monorepo dev
-environment, and drive Frappe + E2E workflows.
+The multiplatform.one command line: scaffold a project from the monorepo
+(`mpo init` / `create-multiplatform-app`), merge the monorepo's changes back
+in (`mpo update`), and drive the dev environment, Frappe and E2E workflows.
 
 ## Install
 
@@ -13,156 +13,166 @@ npx --package=@multiplatform.one/cli create-multiplatform-app my-app
 ```
 
 Two binaries: **`mpo`** (full CLI) and **`create-multiplatform-app`**
-(scaffolder only).
+(`mpo init` only).
 
-## Scaffold a project (recommended)
+## Scaffold a project
 
 ```bash
-mpo init my-app        # universal: web (SSR) + iOS + Android via one
+mpo init my-app                          # prompts for the singleton apps to keep
+mpo init my-app --service frappe --yes   # non-interactive
+mpo init my-app --app admin              # two product apps: my-app and admin
 cd my-app
-pnpm install
-pnpm dev               # web + native dev server
-pnpm ios               # build & run the iOS dev client (pnpm dev in another terminal)
+pnpm dev
 ```
 
-`mpo init` creates a **consumer** project — not a monorepo fork. It prompts for
-anything omitted (name; platforms, defaulting to universal); pass `--yes` for
-CI. `@multiplatform.one/*` dependencies come from npm at semver ranges, never
-`workspace:*`.
+A project is the multiplatform.one monorepo at one commit, pruned:
+
+- `public/` is gone; `@multiplatform.one/*` come from npmjs, the default
+  registry, at `^<cli version>` (`--mpo-version` overrides the range).
+- The singleton apps are ethereum, frappe, keycloak, solana, storybook,
+  storybook-expo, sui, uxpin and vocs; only the ones asked for stay.
+  `--frappe` and `--keycloak` are shorthands for `--service`.
+- Without `--service frappe` the project keeps the Frappe client
+  (`createApp`'s wiring, the `# frappe client` keys in `.env.example`) and
+  drops the bench: `apps/frappe`, its `.env` keys, and the `docker/compose.yaml`
+  services in the `frappe` profile with the volumes only they used.
+- Without `--service keycloak` the keycloak compose service, `postgres` and
+  its `.env` keys, the `docker-bake.hcl` target and the `docker/Makefile`
+  cert block go. With neither service, `docker/compose.yaml` is
+  `services: {}` and there is no `pnpm backend`.
+- `apps/one`, the One platform app, becomes `apps/my-app` (package
+  `@app/my-app`, app.config slug and scheme, bundle id, tauri identifier, the
+  `Makefile` `my-app/%` rules, `.vscode`, `.gitignore`), with
+  `features/my-app` beside it. Every `--app` is another copy. The
+  delivery targets (`gnome/`, `tauri/`, `vscode/`, `webext/`, the Frappe SPA)
+  ride inside each product app; there is nothing to add for them.
+- `packages/themes` is the app's one theme config, and it carries a declared
+  theme subset (`subset.ts`, `subset.tamagui.config.ts`). A narrow surface
+  ships only the themes it can enter, because every theme is CSS in the served
+  document; `packages/themes/README.md` has the measurement and the switch.
+- `docs/`, `deploy/`, `.changeset`, `typedoc.json` and `.gitlab-ci.yml` are
+  monorepo concerns and go too. `AGENTS.md` is the consumer copy
+  (`templates/AGENTS.md`), which names only paths and scripts the project has.
+  `README.md` is the consumer copy too (`templates/README.md`): a block
+  between `<!-- service:<app> -->` and `<!-- /service:<app> -->` stays only
+  when that service was kept, a `no-service:<app>` block only when it was not.
+- `.mpo.json` records the source commit and the selection; `mpo update` and
+  `mpo add-app` read it.
+
+The commit comes from the CLI itself: a published build carries the monorepo
+commit it was cut from (`lib/source.json`); a CLI running inside a monorepo
+checkout uses that checkout's `HEAD`; a build without a stamp falls back to
+the `v<version>` tag, then `main`, and says so. `--source <path|url>` and
+`--checkout <ref>` override it.
+
+### Into an existing directory
 
-Universal layout: `apps/<name>` (routes + providers + vite/expo config),
-`features/<name>` (starter Home/About screens, forms demo, vitest),
-`packages/config`, `packages/i18n` (en/es), `packages/themes` (Tamagui theme).
-
-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`, `--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.
+```bash
+cd my-python-service
+mpo init --into                          # product app named after the directory
+mpo init --into --app dashboard .        # or name it
+```
 
-| 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 |
-| `--vscode`   | VS Code extension — extension host + Tamagui webview             | —                     |
-| `--webext`   | Browser extension — MV3 popup + background                       | —                     |
+Paths that already exist are kept byte for byte, listed, and pinned in
+`.updateignore` so no later update rewrites them. Nothing is committed; the
+directory is yours to commit. `mpo adopt` is not the way in for this: it only
+registers hand-copied piece files (see below).
 
-`--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.
+Options: `--app <name>` (repeatable), `--service <name>` (repeatable),
+`--frappe`, `--keycloak`, `--into`, `--source`, `--checkout`, `--mpo-version`,
+`--skip-install`, `--skip-git`, `--yes`, `--verbose`.
 
 ## 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
+mpo update            # requires a clean tree
+git status            # the merge sits in the index and worktree
+git add -A && git commit -m "chore: mpo update <old> → <new>"
 ```
 
-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).
+A three-way merge: **base** is the scaffold at the commit recorded in
+`.mpo.json` with the recorded apps and services, **ours** is your `HEAD`,
+**theirs** is the same scaffold at the commit this CLI was built from (or
+`--source`/`--checkout`). Your commits are preserved, the monorepo's changes
+land as the diff, every product app receives the One app's changes, and
+nothing is committed. Conflicts land with normal markers; `pnpm install` runs
+on a clean merge (`--skip-install` to skip it).
+
+`.updateignore` entries (exact files or directory prefixes, not globs) and
+`pnpm-lock.yaml` stay pinned to your version. Dependency-range drift in
+`package.json` files resolves to the newer minimum.
 
-### Bootstrap missing provenance
+**Idempotency:** update, commit, update again: zero changes.
 
-Scaffolded before `.mpo.json` existed (CLI ≤ 6.3.0)? Assert the version it
-was scaffolded with instead of hand-writing the file:
+## Add a product app
 
 ```bash
-mpo update --assume-version 6.3.0 [--template universal|app]
+mpo add-app kiosk
 ```
 
-## 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.
+Scaffolds `apps/kiosk` + `features/kiosk` from `apps/one` at the recorded
+commit and merges only that in, uncommitted like `mpo update`.
 
-**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 hand-copied pieces
 
-### 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:
+A project that was never scaffolded and hand-copied a delivery target from
+`templates/pieces` (webext, gnome, tauri, vscode, keycloak wiring, the Frappe
+client as `frappe` and its dev bench as `frappe-bench`) has no provenance:
 
 ```bash
-mpo adopt --webext --name my-app   # requires a clean git tree; ≥ 1 piece
+mpo adopt --webext --name my-app   # clean git tree; at least one 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).
+`.updateignore`; it changes no project file. The first `mpo update` reconciles
+the piece files from an empty base (diffs and conflicts are expected); later
+updates merge three-way against the pieces of the recorded CLI version. An
+adoption recorded while the `frappe` piece still carried the bench gains
+`frappe-bench` on its next update, so the bench stays.
+
+A project from the retired template scaffolder (`.mpo.json` with `template:
+"universal"` or `"app"`) has no reproducible base left: its next `mpo update`
+merges the monorepo's One app in from an empty base once, then it is
+clone-derived.
 
-### Bootstrap missing provenance
+## The scaffold script
 
-Scaffolded before `.mpo.json` existed (CLI ≤ 6.3.0)? Assert the version it
-was scaffolded with instead of hand-writing the file:
+`scripts/scaffold.sh` is POSIX sh and needs only git, node and a shell:
 
 ```bash
-mpo update --assume-version 6.3.0 [--template universal|app]
+sh scripts/scaffold.sh [--app <name>]... [--service <name>]... [--mpo-version <range>] [--into] \
+  <path-or-url> <ref> <target>
 ```
 
 ## Other commands
 
-| Command                      | Purpose                                                              |
-| ---------------------------- | -------------------------------------------------------------------- |
-| `mpo init --monorepo [name]` | DEPRECATED: clone/modify the full monorepo (framework dev forks)     |
-| `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                                  |
-| `mpo frappe bench -- <args>` | Run a bench command                                                  |
-| `mpo frappe clean`           | Clean Frappe bench artifacts                                         |
-| `mpo build`                  | Run the build command                                                |
-| `mpo test`                   | Run tests (E2E flags: `--up-only`, `--down`, `--filter`, …)          |
+| Command                       | Purpose                                                                           |
+| ----------------------------- | --------------------------------------------------------------------------------- |
+| `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                                               |
+| `mpo frappe bench -- <args>`  | Run a bench command                                                               |
+| `mpo frappe clean`            | Clean Frappe bench artifacts                                                      |
+| `mpo frappe types <doctype…>` | Emit doctype TypeScript types from getdoctype; `--check -o <file>` fails on drift |
+| `mpo build`                   | Run the build command                                                             |
+| `mpo test`                    | Run tests (E2E flags: `--up-only`, `--down`, `--filter`, …)                       |
 
 ## Development
 
-Templates live in `templates/universal/` and `templates/app/`. Generator unit
-specs: `pnpm --filter @multiplatform.one/cli test`
-(`src/commands/initApp.spec.ts` — tree + package.json shape for both templates).
+`pnpm --filter @multiplatform.one/cli test` runs the vitest specs: the
+provenance and merge units, and `updateApp.spec.ts`, which scaffolds from
+this checkout at `HEAD`, updates from a second clone that moved ahead, and
+adds an app. `make -C public/cli test/bats` runs `tests/*.bats` against
+`scripts/scaffold.sh` directly (needs `bats`). `pnpm build` stamps
+`lib/source.json` from `git rev-parse HEAD` (`MPO_SOURCE_SHA` /
+`MPO_SOURCE_URL` override it), unless `HEAD` carries another CLI version;
+the release pack stamps the version commit.
 
 ## What it must not do
 
-- The project templates never ship `workspace:*` dependencies on
-  `@multiplatform.one/*` or copies of the monorepo's `public/` packages —
-  consumers upgrade via npm (`pnpm update "@multiplatform.one/*"`)
+- A scaffolded project never carries `public/` or `workspace:*` ranges on
+  `@multiplatform.one/*`; consumers upgrade via the registry
+  (`pnpm update "@multiplatform.one/*"`) and `mpo update`.
 
 ## License
 

package/bin/createMultiplatformApp.mjs

@@ -1,17 +1,11 @@
 #!/usr/bin/env node
 
 /**
- * create-multiplatform-app — npm create / npx entry for consumer scaffolds.
- * Delegates to the same generator as `mpo init`.
+ * create-multiplatform-app: the npm create / npx entry. Same command as
+ * `mpo init` (the monorepo at one commit, pruned into a project).
  *
- * Defaults to the web-only app template (back-compat). Pass --universal for
- * the full web + iOS + Android project (same as `mpo init <name>`).
- *
- * Usage:
  *   npx --package=@multiplatform.one/cli create-multiplatform-app my-app
- *   npx --package=@multiplatform.one/cli create-multiplatform-app my-app --universal
- *   mpo init my-app            # universal
- *   mpo init --web my-app      # web-only
+ *   npx --package=@multiplatform.one/cli create-multiplatform-app my-app --service frappe
  */
 import { createRequire } from "node:module";
 import { dirname, resolve } from "node:path";
@@ -20,25 +14,23 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 const here = dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
 
-function flagValue(argv, name) {
-  const idx = argv.indexOf(name);
-  if (idx < 0) return undefined;
-  return argv[idx + 1];
+function flagValues(argv, name) {
+  const values = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === name && argv[i + 1] !== undefined) values.push(argv[++i]);
+  }
+  return values;
 }
 
 async function main() {
   const argv = process.argv.slice(2);
   if (argv[0] === "--help" || argv[0] === "-h") {
-    console.log(`create-multiplatform-app [name] [--universal] [--skip-install] [--mpo-version <range>] [--yes]
-
-Scaffold a consumer project with @multiplatform.one/* at semver ranges
-(not workspace:*):
+    console.log(`create-multiplatform-app [name] [--app <name>]... [--service <name>]... [--into]
+                        [--source <path|url>] [--checkout <ref>] [--mpo-version <range>]
+                        [--skip-install] [--skip-git] [--yes]
 
-  (default)     apps/<name> + features/<name> + packages/config (web-only)
-  --universal   one-based web + iOS + Android app
-                (adds packages/i18n + packages/themes)
-
-Same as: mpo init --web [name]  /  mpo init [name]
+Scaffold a project: the multiplatform.one monorepo at one commit, pruned.
+Same as: mpo init [name] ...
 `);
     return;
   }
@@ -46,27 +38,37 @@ Same as: mpo init --web [name]  /  mpo init [name]
     console.log(require("../package.json").version);
     return;
   }
+  const valued = new Set(["--app", "--service", "--source", "--checkout", "--mpo-version"]);
+  let name;
+  for (let i = 0; i < argv.length; i++) {
+    if (valued.has(argv[i])) {
+      i++;
+    } else if (!argv[i].startsWith("-")) {
+      name = argv[i];
+      break;
+    }
+  }
 
-  const skipInstall = argv.includes("--skip-install");
-  const yes = argv.includes("--yes") || argv.includes("-y");
-  const universal = argv.includes("--universal");
-  const version = flagValue(argv, "--mpo-version");
-  const name = argv.find((a) => !a.startsWith("-"));
-
-  const libPath = resolve(here, "../lib/commands/initApp.mjs");
-  let initApp;
+  const libPath = resolve(here, "../lib/commands/init.mjs");
+  let init;
   try {
-    ({ initApp } = await import(pathToFileURL(libPath).href));
+    ({ init } = await import(pathToFileURL(libPath).href));
   } catch {
     throw new Error(
-      "Could not load initApp. Build @multiplatform.one/cli first (pnpm --filter @multiplatform.one/cli build).",
+      "Could not load init. Build @multiplatform.one/cli first (pnpm --filter @multiplatform.one/cli build).",
     );
   }
-
-  await initApp(name, {
-    skipInstall,
-    version,
-    template: universal ? "universal" : "app",
+  const services = flagValues(argv, "--service");
+  const yes = argv.includes("--yes") || argv.includes("-y");
+  await init(name, {
+    apps: flagValues(argv, "--app"),
+    services: services.length || yes ? services : undefined,
+    source: flagValues(argv, "--source")[0],
+    checkout: flagValues(argv, "--checkout")[0],
+    mpoVersion: flagValues(argv, "--mpo-version")[0],
+    skipInstall: argv.includes("--skip-install"),
+    skipGit: argv.includes("--skip-git"),
+    into: argv.includes("--into"),
     yes,
   });
 }

package/lib/bin/multiplatformOne.mjs

@@ -1,14 +1,15 @@
-import { generateVscodeConfig } from "../generateVscode.mjs";
-import { INIT_APP_PIECES, initApp, readProvenance } from "../commands/initApp.mjs";
+import { addApp } from "../commands/addApp.mjs";
+import { INIT_APP_PIECES } from "../commands/pieces.mjs";
 import { adoptApp } from "../commands/adoptApp.mjs";
+import { generateDoctypeTypes, typesDrift } from "../commands/doctypeTypes.mjs";
 import { discoverE2EApp, runE2ESession } from "../commands/e2e.mjs";
-import { init, runModifyStep } from "../commands/init.mjs";
+import { SINGLETON_APPS, init } from "../commands/init.mjs";
 import { updateApp } from "../commands/updateApp.mjs";
 import { createRequire } from "node:module";
-import fs from "node:fs/promises";
-import path from "node:path";
 import fsSync from "node:fs";
+import path from "node:path";
 import { fileURLToPath } from "node:url";
+import fs from "node:fs/promises";
 import { formatServiceList, lookupProjectRoot, waitForFrappe, waitForKeycloak, waitForPostgres, waitServices } from "@multiplatform.one/utils/dev";
 import { Command } from "commander";
 import spawn from "nano-spawn";
@@ -472,88 +473,47 @@ 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 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");
-		const cloneScript = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../scripts/clone.sh");
-		await init(name, {
-			...options,
-			cloneScript
-		});
-		return;
-	}
-	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, {
+const collect = (value, previous) => [...previous, value];
+program.command("init").argument("[name]", "the project (and product app) name; with --into, the directory").option("--app <name>", "one more product app derived from apps/one (repeatable)", collect, []).option("--service <name>", `singleton app to keep (repeatable): ${SINGLETON_APPS.join(", ")}`, collect, []).option("--frappe", "same as --service frappe").option("--keycloak", "same as --service keycloak").option("--into", "scaffold into an existing directory (the argument, default .); paths already there are kept and pinned in .updateignore").option("--source <path|url>", "monorepo to scaffold from (default: the commit this CLI was built from)").option("-c, --checkout <ref>", "commit, tag or branch at the source").option("--mpo-version <range>", "semver range for @multiplatform.one/* (default: ^<cli version at the source>)").option("--skip-install", "skip pnpm install after scaffolding").option("--skip-git", "skip git init + scaffold commit").option("-y, --yes", "non-interactive: no prompts, no services unless passed").option("--verbose", "show what the scaffold removes and skips").description("scaffold a project: the multiplatform.one monorepo at one commit, pruned (no public/, only the services asked for, apps/one renamed to the product app, @multiplatform.one/* at semver ranges)").action(async (name, options) => {
+	const services = [...options.service];
+	if (options.frappe) services.push("frappe");
+	if (options.keycloak) services.push("keycloak");
+	await init(name, {
+		apps: options.app,
+		services: services.length || options.yes || !process.stdout.isTTY ? services : void 0,
+		source: options.source,
+		checkout: options.checkout,
+		mpoVersion: options.mpoVersion,
 		skipInstall: Boolean(options.skipInstall),
 		skipGit: Boolean(options.skipGit),
-		version: options.mpoVersion,
-		template: options.piecesOnly ? "none" : webOnly ? "app" : options.universal ? "universal" : void 0,
 		yes: Boolean(options.yes),
-		pieces: pieces.length ? pieces : void 0
+		into: Boolean(options.into),
+		verbose: Boolean(options.verbose)
+	});
+});
+program.command("add-app").argument("<name>", "the new product app (apps/<name> + features/<name>)").option("--source <path|url>", "monorepo holding the recorded source commit (default: the recorded url)").option("--skip-install", "skip pnpm install after the merge").option("--verbose", "show the scaffold's progress").description("add another product app from apps/one at the project's recorded source commit; the result is left uncommitted like mpo update").action(async (name, options) => {
+	await addApp(name, {
+		source: options.source,
+		skipInstall: Boolean(options.skipInstall),
+		verbose: Boolean(options.verbose)
 	});
 });
-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]));
+program.command("adopt").option("--frappe", "the project adopted the Frappe client piece (env keys, provider)").option("--frappe-bench", "the project adopted the Frappe dev bench piece (docker compose)").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 that hand-copied piece files 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). For the whole monorepo scaffold use `mpo init --into`").action(async (options) => {
+	const pieces = INIT_APP_PIECES.filter((piece) => Boolean(options[piece.replace(/-(\w)/gu, (_, letter) => letter.toUpperCase())]));
 	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 (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,
-			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.\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",
-		"--quiet"
-	]).then(() => false, () => true)) throw new Error("mpo cannot be updated with uncommitted changes (staged changes present)");
-	if (await spawn("git", ["diff", "--quiet"]).then(() => false, () => true)) throw new Error("multiplatform.one cannot be updated with uncommitted changes (unstaged changes present)");
-	const rootPkgPath = path.resolve(projectRoot, "package.json");
-	const featuresPkgPath = path.resolve(projectRoot, "features/package.json");
-	try {
-		if (!(await fs.stat(rootPkgPath)).isFile()) throw new Error("mpo update requires a valid project: root package.json not found");
-	} catch (err) {
-		if (err instanceof Error && err.message.includes("valid project")) throw err;
-		throw new Error("mpo update requires a valid project: root package.json not found");
-	}
-	try {
-		if (!(await fs.stat(featuresPkgPath)).isFile()) throw new Error("mpo update requires a valid project: features/package.json not found");
-	} catch (err) {
-		if (err instanceof Error && err.message.includes("valid project")) throw err;
-		throw new Error("mpo update requires a valid project: features/package.json not found");
-	}
-	const featuresPkg = JSON.parse(await fs.readFile(featuresPkgPath, "utf8"));
-	if (!featuresPkg?.dependencies?.["multiplatform.one"] || !String(featuresPkg.dependencies["multiplatform.one"]).length) throw new Error("mpo update requires a valid project: features must depend on multiplatform.one");
-	await spawn("sh", [
-		path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../scripts/update.sh"),
-		options.remote,
-		options.checkout
-	], {
-		cwd: projectRoot,
-		stdio: "inherit",
-		shell: true
+program.command("update").option("--source <path|url>", "monorepo to update from (default: the commit this CLI was built from)").option("-c, --checkout <ref>", "commit, tag or branch at the source").option("--skip-install", "skip pnpm install after the merge").option("--mpo-version <range>", "semver range for @multiplatform.one/* (default: ^<cli version at the source>)").option("--verbose", "show the scaffold's progress").description("three-way merge the monorepo's changes into this project (base = the scaffold at the recorded source commit, ours = HEAD, theirs = the scaffold at the current commit); lands in the index and worktree, never commits; refuses a dirty tree").action(async (options) => {
+	await updateApp({
+		source: options.source,
+		checkout: options.checkout,
+		skipInstall: Boolean(options.skipInstall),
+		version: options.mpoVersion,
+		verbose: Boolean(options.verbose)
 	});
-	runModifyStep(projectRoot, await getPresentServices(projectRoot), await getPresentApps(projectRoot));
-	try {
-		await generateVscodeConfig(projectRoot);
-	} catch {}
 });
 program.command("wait").description("wait for a service to be ready").option("-i, --interval <interval>", "interval to wait for", "1000").option("-t, --timeout <timeout>", "timeout to wait for", "600000").option("-e, --dotenv <dotenv>", "dotenv file path", ".env").argument("<services>", `the services to wait for (${waitServices.join(", ")})`).action(async (servicesString, options) => {
 	import_main.default.config({ path: options.dotenv || defaultDotenvPath });
@@ -612,6 +572,36 @@ frappe.command("bench").description("run bench command").action(async () => {
 		cwd: projectRoot
 	});
 });
+frappe.command("types").description("generate TypeScript types for doctypes from getdoctype (auth: $FRAPPE_API_KEY, $FRAPPE_API_SECRET)").argument("<doctypes...>", "doctype names; child tables come along").option("-o, --out <file>", "write the module here instead of stdout").option("--check", "exit 1 and print the diff when --out differs from the server").option("--url <url>", "frappe base URL (default $FRAPPE_URL or http://localhost:8000)").action(async (doctypes, options) => {
+	const parentOptions = frappe.opts();
+	import_main.default.config({
+		path: parentOptions.dotenv || defaultDotenvPath,
+		quiet: true
+	});
+	if (options.check && !options.out) {
+		console.error("--check needs --out <file>");
+		process.exit(2);
+	}
+	const generated = await generateDoctypeTypes(doctypes, {
+		baseURL: options.url || process.env.FRAPPE_URL || "http://localhost:8000",
+		apiKey: process.env.FRAPPE_API_KEY,
+		apiSecret: process.env.FRAPPE_API_SECRET
+	});
+	if (!options.out) {
+		process.stdout.write(generated);
+		return;
+	}
+	const out = path.resolve(process.cwd(), options.out);
+	if (options.check) {
+		const drift = typesDrift(fsSync.existsSync(out) ? await fs.readFile(out, "utf8") : "", generated);
+		if (drift.length > 0) {
+			console.error(`${options.out} drifted from the server:\n${drift.join("\n")}`);
+			process.exit(1);
+		}
+		return;
+	}
+	await fs.writeFile(out, generated);
+});
 program.command("build").argument("[args...]", `build to run: ${[...availableServices, "packages"].join(", ")} (default: all)`).description("run build command").action(async (args) => {
 	const parsed = args.flatMap((arg) => arg.split(","));
 	const packages = parsed.includes("packages");