@multiplatform.one/cli 6.1.0 → 6.4.0

package/README.md

@@ -0,0 +1,72 @@
+# @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.
+
+## Install
+
+```bash
+pnpm add -g @multiplatform.one/cli
+# or run the scaffolder without installing:
+npx --package=@multiplatform.one/cli create-multiplatform-app my-app
+```
+
+Two binaries: **`mpo`** (full CLI) and **`create-multiplatform-app`**
+(scaffolder only).
+
+## Scaffold a project (recommended)
+
+```bash
+mpo init my-app        # universal: web (SSR) + iOS + Android via one
+cd my-app
+pnpm install
+pnpm dev               # web + native dev server
+pnpm ios               # build & run the iOS dev client (pnpm dev in another terminal)
+```
+
+`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:*`.
+
+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`,
+`--mpo-version <range>` (defaults to `^<cli version>`), `-y/--yes`.
+
+## 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 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`, …)          |
+
+## 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).
+
+## 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/*"`)
+
+## License
+
+Apache-2.0

package/bin/createMultiplatformApp.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+/**
+ * create-multiplatform-app — npm create / npx entry for consumer scaffolds.
+ * Delegates to the same generator as `mpo init`.
+ *
+ * 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
+ */
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+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];
+}
+
+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:*):
+
+  (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]
+`);
+    return;
+  }
+  if (argv[0] === "--version" || argv[0] === "-V") {
+    console.log(require("../package.json").version);
+    return;
+  }
+
+  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;
+  try {
+    ({ initApp } = await import(pathToFileURL(libPath).href));
+  } catch {
+    throw new Error(
+      "Could not load initApp. Build @multiplatform.one/cli first (pnpm --filter @multiplatform.one/cli build).",
+    );
+  }
+
+  await initApp(name, {
+    skipInstall,
+    version,
+    template: universal ? "universal" : "app",
+    yes,
+  });
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/lib/bin/multiplatformOne.mjs

@@ -1,16 +1,18 @@
 import { generateVscodeConfig } from "../generateVscode.mjs";
 import { discoverE2EApp, runE2ESession } from "../commands/e2e.mjs";
 import { init, runModifyStep } from "../commands/init.mjs";
+import { initApp, readProvenance } from "../commands/initApp.mjs";
+import { updateApp } from "../commands/updateApp.mjs";
 import { createRequire } from "node:module";
 import fs from "node:fs/promises";
 import path from "node:path";
-import spawn from "nano-spawn";
-import yoctoSpinner from "yocto-spinner";
-import YAML from "yaml";
 import fsSync from "node:fs";
 import { fileURLToPath } from "node:url";
 import { formatServiceList, lookupProjectRoot, waitForFrappe, waitForKeycloak, waitForPostgres, waitServices } from "@multiplatform.one/utils/dev";
 import { Command } from "commander";
+import spawn from "nano-spawn";
+import YAML from "yaml";
+import yoctoSpinner from "yocto-spinner";
 
 //#region \0rolldown/runtime.js
 var __create = Object.create;
@@ -469,16 +471,39 @@ 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("-c, --checkout <branch>", "branch, tag or commit to checkout", "main").option("-a, --apps <apps>", "comma-separated apps to include").option("-s, --services <services>", "comma-separated services to include").argument("[name]", "the name of the project").description("clone multiplatform.one and apply selected apps/services").action(async (name, options) => {
-	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
+program.command("init").option("--universal", "scaffold the universal template (web + iOS + Android; default)").option("--web", "scaffold the web-only template (Vite + React)").option("--app", "alias of --web (back-compat)").option("--skip-install", "skip pnpm install after scaffolding").option("--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");
+	await initApp(name, {
+		skipInstall: Boolean(options.skipInstall),
+		version: options.mpoVersion,
+		template: webOnly ? "app" : options.universal ? "universal" : void 0,
+		yes: Boolean(options.yes)
 	});
 });
-program.command("update").option("-c, --checkout <branch>", "branch, tag or commit to merge from upstream", "main").option("-r, --remote <url>", "upstream remote URL", "https://gitlab.com/bitspur/multiplatform.one/multiplatform.one.git").description("merge upstream and re-apply workspace config").action(async (options) => {
+program.command("update").option("-c, --checkout <branch>", "branch, tag or commit to merge from upstream (monorepo forks)", "main").option("-r, --remote <url>", "upstream remote URL (monorepo forks)", "https://gitlab.com/bitspur/multiplatform.one/multiplatform.one.git").option("--skip-install", "skip pnpm install after the update").option("--mpo-version <range>", "semver range for @multiplatform.one/* (default: ^<cli version>)").description("update a scaffolded project to the current template (three-way merge via .mpo.json provenance); monorepo forks fall back to the upstream merge flow").action(async (options) => {
 	if (await spawn("git", ["rev-parse", "--is-inside-work-tree"]).then(() => false, () => true)) throw new Error("mpo cannot be updated outside of a git repository");
+	if (readProvenance(projectRoot)) {
+		await updateApp({
+			skipInstall: options.skipInstall,
+			version: options.mpoVersion
+		});
+		try {
+			await generateVscodeConfig(projectRoot);
+		} catch {}
+		return;
+	}
 	if (await spawn("git", [
 		"diff",
 		"--cached",

package/lib/commands/e2e.mjs

@@ -1,10 +1,10 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import crypto from "node:crypto";
-import os from "node:os";
 import spawn from "nano-spawn";
-import yoctoSpinner from "yocto-spinner";
 import YAML from "yaml";
+import yoctoSpinner from "yocto-spinner";
+import crypto from "node:crypto";
+import os from "node:os";
 
 //#region src/commands/e2e.ts
 function sessionFileName(portOffset) {

package/lib/commands/init.mjs

@@ -1,6 +1,6 @@
 import { join, resolve } from "node:path";
-import { execSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
 import inquirer from "inquirer";
 
 //#region src/commands/init.ts
@@ -20,8 +20,6 @@ const apps = [
 	"keycloak",
 	"storybook",
 	"storybook-expo",
-	"vscode",
-	"webext",
 	"vocs"
 ];
 /** env variable prefixes to remove per service */
@@ -33,12 +31,14 @@ const serviceEnvPrefixes = {
 };
 /** env variable prefixes to remove per app */
 const appEnvPrefixes = {
-	one: ["ONE_"],
+	one: [
+		"ONE_",
+		"VSCODE_",
+		"WEBEXT_"
+	],
 	keycloak: ["KEYCLOAK_"],
 	storybook: ["STORYBOOK_", "VR_DIFFING_ENGINE="],
 	"storybook-expo": [],
-	vscode: ["VSCODE_"],
-	webext: ["WEBEXT_"],
 	vocs: ["VOCS_"]
 };
 /** env section headers (comments) to remove per app/service */
@@ -49,12 +49,14 @@ const serviceEnvSections = {
 	sui: []
 };
 const appEnvSections = {
-	one: ["# one"],
+	one: [
+		"# one",
+		"# vscode",
+		"# webext"
+	],
 	keycloak: ["# keycloak"],
 	storybook: ["# storybook"],
 	"storybook-expo": [],
-	vscode: ["# vscode"],
-	webext: ["# webext"],
 	vocs: ["# vocs"]
 };
 /** launch.json configuration names per service/app */
@@ -65,12 +67,14 @@ const serviceLaunchNames = {
 	sui: ["sui dev"]
 };
 const appLaunchNames = {
-	one: ["one dev"],
+	one: [
+		"one dev",
+		"vscode dev",
+		"webext dev"
+	],
 	keycloak: ["keycloak dev", "keycloak storybook"],
 	storybook: ["storybook dev"],
 	"storybook-expo": ["storybook-expo dev"],
-	vscode: ["vscode dev"],
-	webext: ["webext dev"],
 	vocs: ["vocs dev"]
 };
 /**

package/lib/commands/initApp.mjs

@@ -0,0 +1,175 @@
+import { dirname, extname, join, resolve } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import spawn from "nano-spawn";
+import inquirer from "inquirer";
+
+//#region src/commands/initApp.ts
+function toPascalCase(name) {
+	return name.split(/[-_\s]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function validateName(name) {
+	const trimmed = name.trim();
+	if (!trimmed) throw new Error("Project name is required");
+	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;
+}
+function resolveMpoVersion(explicit) {
+	if (explicit) return explicit.startsWith("^") || explicit.startsWith("~") || explicit === "*" ? explicit : `^${explicit}`;
+	const version = cliVersion();
+	return version ? `^${version}` : "^6.1.0";
+}
+function cliVersion() {
+	try {
+		const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), "../../package.json");
+		return JSON.parse(readFileSync(pkgPath, "utf-8")).version;
+	} catch {
+		return;
+	}
+}
+const PROVENANCE_FILE = ".mpo.json";
+function writeProvenance(targetDir, provenance) {
+	writeFileSync(join(targetDir, PROVENANCE_FILE), `${JSON.stringify(provenance, null, 2)}\n`);
+}
+function readProvenance(projectDir) {
+	const file = join(projectDir, PROVENANCE_FILE);
+	if (!existsSync(file)) return void 0;
+	try {
+		const raw = JSON.parse(readFileSync(file, "utf-8"));
+		if (!raw.template || !raw.cliVersion || !raw.name) return void 0;
+		return {
+			template: raw.template,
+			cliVersion: raw.cliVersion,
+			name: raw.name,
+			mpoVersion: raw.mpoVersion ?? `^${raw.cliVersion}`
+		};
+	} catch {
+		return;
+	}
+}
+function templatesRoot(template) {
+	return resolve(dirname(fileURLToPath(import.meta.url)), "../../templates", template);
+}
+/**
+* npm always strips .gitignore / .npmrc from published tarballs, so the
+* template stores them without the leading dot; restore it at scaffold time.
+*/
+const DOTFILE_NAMES = {
+	gitignore: ".gitignore",
+	npmrc: ".npmrc"
+};
+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 — running them through the utf-8 render pass
+* would corrupt them (fonts ship in the templates for LC-33 stable mount).
+*/
+const BINARY_EXTENSIONS = new Set([
+	".woff2",
+	".woff",
+	".ttf",
+	".otf",
+	".png",
+	".jpg",
+	".ico"
+]);
+function writeTree(srcDir, destDir, vars) {
+	if (!existsSync(srcDir)) throw new Error(`Project template missing at ${srcDir}`);
+	mkdirSync(destDir, { recursive: true });
+	for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+		const from = join(srcDir, entry.name);
+		const to = join(destDir, render(DOTFILE_NAMES[entry.name] ?? entry.name, vars));
+		if (entry.isDirectory()) {
+			writeTree(from, to, vars);
+			continue;
+		}
+		if (BINARY_EXTENSIONS.has(extname(entry.name).toLowerCase())) {
+			copyFileSync(from, to);
+			continue;
+		}
+		writeFileSync(to, render(readFileSync(from, "utf-8"), vars));
+	}
+}
+async function resolveTemplate(options) {
+	if (options.template) return options.template;
+	if (options.yes || !process.stdout.isTTY) return "universal";
+	return (await inquirer.prompt([{
+		message: "Which platforms should this project target?",
+		name: "template",
+		type: "list",
+		choices: [{
+			name: "Universal — web + iOS + Android (one)",
+			value: "universal"
+		}, {
+			name: "Web only — Vite + React",
+			value: "app"
+		}],
+		default: "universal"
+	}])).template;
+}
+/**
+* Scaffold a consumer project (universal by default, web-only with
+* template: "app") that depends on @multiplatform.one/* at semver ranges
+* (never workspace:*). This is NOT a monorepo fork.
+*/
+async function initApp(nameArg, options = {}) {
+	let projectName = nameArg;
+	if (!projectName) if (options.yes || !process.stdout.isTTY) projectName = "my-app";
+	else projectName = (await inquirer.prompt([{
+		message: "What is the app name?",
+		name: "name",
+		type: "input",
+		default: "my-app"
+	}])).name;
+	const name = validateName(projectName);
+	const template = await resolveTemplate(options);
+	const targetDir = resolve(name);
+	if (existsSync(targetDir)) {
+		if (readdirSync(targetDir).length > 0) throw new Error(`Directory "${targetDir}" already exists and is not empty`);
+	}
+	const vars = {
+		NAME: name,
+		NAME_PASCAL: toPascalCase(name),
+		NAME_APPID: name.replaceAll("-", ""),
+		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`);
+	if (template === "universal") {
+		console.log(`  packages/i18n`);
+		console.log(`  packages/themes`);
+	}
+	console.log(`  @multiplatform.one/* → ${vars.MPO_VERSION}\n`);
+	writeTree(templatesRoot(template), targetDir, vars);
+	writeProvenance(targetDir, {
+		template,
+		cliVersion: cliVersion() ?? "0.0.0",
+		name,
+		mpoVersion: vars.MPO_VERSION
+	});
+	if (!options.skipInstall) {
+		console.log("Installing dependencies...");
+		await spawn("pnpm", ["install"], {
+			cwd: targetDir,
+			stdio: "inherit"
+		});
+	} else console.log("Skipped pnpm install (--skip-install).");
+	console.log(`\n✅ Project created at ${targetDir}`);
+	console.log("\nNext steps:");
+	console.log(`  cd ${name}`);
+	if (options.skipInstall) console.log("  pnpm install");
+	console.log("  pnpm dev        # web dev server");
+	if (template === "universal") {
+		console.log("  pnpm ios        # iOS (requires pnpm dev in another terminal)");
+		console.log("  pnpm android    # Android");
+	}
+	console.log("\nThis project consumes published @multiplatform.one/* packages.");
+	console.log("It is not a fork of the multiplatform.one monorepo.");
+}
+
+//#endregion
+export { PROVENANCE_FILE, cliVersion, initApp, readProvenance, writeProvenance };