@multiplatform.one/cli 6.4.2 → 6.6.0

package/src/commands/initApp.ts

@@ -20,6 +20,31 @@ import spawn from "nano-spawn";
  */
 export type InitAppTemplate = "universal" | "app";
 
+/**
+ * Optional composable pieces overlaid onto the base template (additive
+ * fragments under templates/pieces/<piece>/ — the inverse of the old
+ * cookiecutter KEEP_SERVICES/KEEP_PLATFORMS removal hook). Keep sorted:
+ * pieces are recorded sorted in provenance and overlaid in this order.
+ */
+export const INIT_APP_PIECES = [
+  "frappe",
+  "gnome",
+  "keycloak",
+  "tauri",
+  "vscode",
+  "webext",
+] as const;
+export type InitAppPiece = (typeof INIT_APP_PIECES)[number];
+
+const PIECE_DESCRIPTIONS: Record<InitAppPiece, string> = {
+  frappe: "Frappe backend wiring (env keys, provider, docker compose bench)",
+  gnome: "GNOME desktop target (GTK4/GJS via react-gnome — native widgets, no webview)",
+  keycloak: "Keycloak auth wiring (env keys, provider, docker compose + realm)",
+  tauri: "Desktop target (src-tauri skeleton, tauri scripts)",
+  vscode: "VS Code extension target (extension host + Tamagui webview)",
+  webext: "Browser extension target (MV3 popup + background)",
+};
+
 export interface InitAppOptions {
   /** Skip pnpm install (useful for CI / dry scaffolding). */
   skipInstall?: boolean;
@@ -31,6 +56,11 @@ export interface InitAppOptions {
   template?: InitAppTemplate;
   /** Accept defaults instead of prompting (non-interactive / CI). */
   yes?: boolean;
+  /**
+   * Composable pieces overlaid onto the base template. When omitted:
+   * checkbox prompt (interactive) or none (--yes / non-TTY).
+   */
+  pieces?: InitAppPiece[];
 }
 
 type TemplateVars = {
@@ -94,12 +124,17 @@ export interface MpoProvenance {
   cliVersion: string;
   name: string;
   mpoVersion: string;
+  /** Composable pieces overlaid at init time (sorted). */
+  pieces: InitAppPiece[];
 }
 
 export const PROVENANCE_FILE = ".mpo.json";
 
 export function writeProvenance(targetDir: string, provenance: MpoProvenance): void {
-  writeFileSync(join(targetDir, PROVENANCE_FILE), `${JSON.stringify(provenance, null, 2)}\n`);
+  writeFileSync(
+    join(targetDir, PROVENANCE_FILE),
+    `${JSON.stringify({ ...provenance, pieces: [...provenance.pieces].sort() }, null, 2)}\n`,
+  );
 }
 
 export function readProvenance(projectDir: string): MpoProvenance | undefined {
@@ -113,6 +148,8 @@ export function readProvenance(projectDir: string): MpoProvenance | undefined {
       cliVersion: raw.cliVersion,
       name: raw.name,
       mpoVersion: raw.mpoVersion ?? `^${raw.cliVersion}`,
+      // Scaffolds from pre-piece CLIs (≤6.4.x) have no pieces field.
+      pieces: Array.isArray(raw.pieces) ? [...(raw.pieces as InitAppPiece[])].sort() : [],
     };
   } catch {
     return undefined;
@@ -123,13 +160,30 @@ function templatesRoot(template: InitAppTemplate): string {
   return resolve(dirname(fileURLToPath(import.meta.url)), "../../templates", template);
 }
 
+function piecesRoot(piece: InitAppPiece): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "../../templates/pieces", piece);
+}
+
+/**
+ * Fragment source dirs for a piece + template: shared/ applies to every
+ * template, <template>/ only to that one. A piece supports a template when
+ * at least one of the two exists.
+ */
+function pieceFragmentDirs(piece: InitAppPiece, template: InitAppTemplate): string[] {
+  return [join(piecesRoot(piece), "shared"), join(piecesRoot(piece), template)].filter((dir) =>
+    existsSync(dir),
+  );
+}
+
 /**
- * npm always strips .gitignore / .npmrc from published tarballs, so the
- * template stores them without the leading dot; restore it at scaffold time.
+ * npm always strips .gitignore / .npmrc (and newer npms .env*) from published
+ * tarballs, so the template stores them without the leading dot; restore it
+ * at scaffold time.
  */
 const DOTFILE_NAMES: Record<string, string> = {
   gitignore: ".gitignore",
   npmrc: ".npmrc",
+  "env.example": ".env.example",
 };
 
 function render(content: string, vars: TemplateVars): string {
@@ -145,7 +199,16 @@ function render(content: string, vars: TemplateVars): string {
  * 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"]);
+const BINARY_EXTENSIONS = new Set([
+  ".woff2",
+  ".woff",
+  ".ttf",
+  ".otf",
+  ".png",
+  ".jpg",
+  ".ico",
+  ".icns",
+]);
 
 function writeTree(srcDir: string, destDir: string, vars: TemplateVars): void {
   if (!existsSync(srcDir)) {
@@ -170,6 +233,227 @@ function writeTree(srcDir: string, destDir: string, vars: TemplateVars): void {
   }
 }
 
+// ── piece fragment overlay ─────────────────────────────────────────
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+function isJsonObject(value: JsonValue | undefined): value is { [key: string]: JsonValue } {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Deep-merge for JSON partials: objects merge recursively (fragment keys
+ * append after base keys, so e.g. package.json script order stays stable),
+ * arrays union (base order first — config.json public keys accumulate
+ * across pieces), scalars/type-mismatches take the fragment value.
+ */
+export function mergeJsonValues(base: JsonValue, fragment: JsonValue): JsonValue {
+  if (Array.isArray(base) && Array.isArray(fragment)) {
+    const merged = [...base];
+    const seen = new Set(base.map((item) => JSON.stringify(item)));
+    for (const item of fragment) {
+      const key = JSON.stringify(item);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      merged.push(item);
+    }
+    return merged;
+  }
+  if (isJsonObject(base) && isJsonObject(fragment)) {
+    const merged: { [key: string]: JsonValue } = { ...base };
+    for (const [key, value] of Object.entries(fragment)) {
+      merged[key] = key in merged ? mergeJsonValues(merged[key]!, value) : value;
+    }
+    return merged;
+  }
+  return fragment;
+}
+
+/** Dependency maps stay alphabetically sorted after fragment merges (the
+ *  base templates are sorted; multiple pieces appending must not depend on
+ *  overlay order for the final byte content). */
+const SORTED_DEPENDENCY_FIELDS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+];
+
+function sortDependencyFields(value: JsonValue): JsonValue {
+  if (!isJsonObject(value)) return value;
+  const result = { ...value };
+  for (const field of SORTED_DEPENDENCY_FIELDS) {
+    const deps = result[field];
+    if (!isJsonObject(deps)) continue;
+    result[field] = Object.fromEntries(
+      Object.entries(deps).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+    );
+  }
+  return result;
+}
+
+/**
+ * Apply a rendered `<target>.partial` fragment onto the target file:
+ *   - `.json` targets deep-merge (see mergeJsonValues); package.json-style
+ *     dependency maps are re-sorted for deterministic output
+ *   - everything else appends as a text block separated by a blank line
+ * Missing targets are created from the fragment alone.
+ */
+function applyPartial(targetPath: string, renderedFragment: string): void {
+  if (targetPath.endsWith(".json")) {
+    const fragment = JSON.parse(renderedFragment) as JsonValue;
+    const base = existsSync(targetPath)
+      ? (JSON.parse(readFileSync(targetPath, "utf-8")) as JsonValue)
+      : undefined;
+    const merged = sortDependencyFields(
+      base === undefined ? fragment : mergeJsonValues(base, fragment),
+    );
+    writeFileSync(targetPath, `${JSON.stringify(merged, null, 2)}\n`);
+    return;
+  }
+  const block = `${renderedFragment.replace(/^\n+/u, "").replace(/\n+$/u, "")}\n`;
+  if (!existsSync(targetPath)) {
+    writeFileSync(targetPath, block);
+    return;
+  }
+  const existing = readFileSync(targetPath, "utf-8").replace(/\n+$/u, "");
+  writeFileSync(targetPath, `${existing}\n\n${block}`);
+}
+
+const PARTIAL_SUFFIX = ".partial";
+
+/**
+ * Overlay a piece fragment tree onto the scaffold: regular files render and
+ * overwrite, `<target>.partial` files merge into (or create) their target
+ * (deep-merge for .json, append for text — see applyPartial).
+ */
+function overlayTree(srcDir: string, destDir: string, vars: TemplateVars): void {
+  mkdirSync(destDir, { recursive: true });
+  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+    const from = join(srcDir, entry.name);
+    if (entry.isDirectory()) {
+      overlayTree(from, join(destDir, render(DOTFILE_NAMES[entry.name] ?? entry.name, vars)), vars);
+      continue;
+    }
+    if (entry.name.endsWith(PARTIAL_SUFFIX)) {
+      const targetName = entry.name.slice(0, -PARTIAL_SUFFIX.length);
+      const toName = render(DOTFILE_NAMES[targetName] ?? targetName, vars);
+      applyPartial(join(destDir, toName), render(readFileSync(from, "utf-8"), vars));
+      continue;
+    }
+    const toName = render(DOTFILE_NAMES[entry.name] ?? entry.name, vars);
+    const to = join(destDir, toName);
+    if (BINARY_EXTENSIONS.has(extname(entry.name).toLowerCase())) {
+      copyFileSync(from, to);
+      continue;
+    }
+    writeFileSync(to, render(readFileSync(from, "utf-8"), vars));
+  }
+}
+
+/**
+ * Validate + canonicalize a piece selection for a template: unknown names
+ * throw, duplicates collapse, order is always sorted (provenance and overlay
+ * order must be deterministic), and every piece must ship a fragment for the
+ * chosen template.
+ */
+export function normalizePieces(pieces: string[], template: InitAppTemplate): InitAppPiece[] {
+  const known = new Set<string>(INIT_APP_PIECES);
+  const normalized = [...new Set(pieces)].sort() as InitAppPiece[];
+  for (const piece of normalized) {
+    if (!known.has(piece)) {
+      throw new Error(`Unknown piece "${piece}". Available pieces: ${INIT_APP_PIECES.join(", ")}`);
+    }
+    if (pieceFragmentDirs(piece, template).length === 0) {
+      throw new Error(
+        `Piece "${piece}" is not available for the ${template} template ` +
+          "(pieces currently target the universal template)",
+      );
+    }
+  }
+  return normalized;
+}
+
+/** Pieces that can be offered for a template (fragment exists for it). */
+export function availablePieces(template: InitAppTemplate): InitAppPiece[] {
+  return INIT_APP_PIECES.filter((piece) => pieceFragmentDirs(piece, template).length > 0);
+}
+
+async function resolvePieces(
+  options: InitAppOptions,
+  template: InitAppTemplate,
+): Promise<InitAppPiece[]> {
+  if (options.pieces) return normalizePieces(options.pieces, template);
+  if (options.yes || !process.stdout.isTTY) return [];
+  const choices = availablePieces(template);
+  if (choices.length === 0) return [];
+  const result = await inquirer.prompt([
+    {
+      message: "Add optional pieces? (space to toggle, enter to confirm)",
+      name: "pieces",
+      type: "checkbox",
+      choices: choices.map((piece) => ({
+        name: `${piece} — ${PIECE_DESCRIPTIONS[piece]}`,
+        value: piece,
+        checked: false,
+      })),
+    },
+  ]);
+  return normalizePieces(result.pieces as string[], template);
+}
+
+// ── app.ts composition (frappe / keycloak provider wiring) ─────────
+
+/**
+ * Generate apps/<name>/src/app.ts for the selected backend pieces instead of
+ * storing 2^n template variants: each selected provider adds one createApp
+ * key (frappe/keycloak read their runtime settings from the packages/config
+ * public env keys their fragments register). Only called when at least one
+ * provider piece is selected — the base template file stays otherwise.
+ */
+export function composeAppTs(pieces: InitAppPiece[]): string {
+  const frappe = pieces.includes("frappe");
+  const keycloak = pieces.includes("keycloak");
+  const lines: string[] = ['import { createApp } from "@multiplatform.one/core";'];
+  if (frappe || keycloak) {
+    lines.push('import { config } from "@multiplatform.one/platform";');
+  }
+  lines.push('import { themeConfig } from "@package/themes";');
+  lines.push(
+    "",
+    "/**",
+    " * App-wide provider stack. Providers below were enabled by the pieces",
+    " * selected at `mpo init` time — see CreateAppConfig in",
+    " * @multiplatform.one/core for everything else that can be wired here",
+    " * (tanstack, web3, custom providers).",
+    " */",
+    "export const { AppProvider, useAppConfig, withApp } = createApp({",
+    "  theme: themeConfig,",
+  );
+  if (frappe) {
+    lines.push(
+      "  // Frappe backend (mpo init --frappe): FrappeProvider mounts when",
+      "  // FRAPPE_ENABLED=1 (a packages/config public env key, loaded from",
+      "  // .env — see .env.example). FRAPPE_URL overrides the bench URL",
+      "  // (default: BASE_URL, then http://localhost:8000);",
+      "  // docker/compose.frappe.yaml runs a dev bench.",
+      '  frappe: { baseURL: config.get("FRAPPE_URL") },',
+    );
+  }
+  if (keycloak) {
+    lines.push(
+      "  // Keycloak auth (mpo init --keycloak): KeycloakProvider mounts when",
+      "  // KEYCLOAK_ENABLED=1. Realm/client settings come from the KEYCLOAK_*",
+      "  // env keys (packages/config, .env.example);",
+      "  // docker/compose.keycloak.yaml runs a dev server with an imported",
+      "  // realm.",
+      '  keycloak: { baseUrl: config.get("KEYCLOAK_BASE_URL") },',
+    );
+  }
+  lines.push("});", "");
+  return lines.join("\n");
+}
+
 async function resolveTemplate(options: InitAppOptions): Promise<InitAppTemplate> {
   if (options.template) return options.template;
   if (options.yes || !process.stdout.isTTY) return "universal";
@@ -216,6 +500,7 @@ export async function initApp(
 
   const name = validateName(projectName);
   const template = await resolveTemplate(options);
+  const pieces = await resolvePieces(options, template);
   const targetDir = resolve(name);
 
   if (existsSync(targetDir)) {
@@ -242,14 +527,31 @@ export async function initApp(
     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);
+  // Pieces overlay AFTER the base template, in sorted order (normalizePieces)
+  // so repeated scaffolds are byte-identical — mpo update regenerates these
+  // exact trees as merge baselines.
+  for (const piece of pieces) {
+    for (const fragmentDir of pieceFragmentDirs(piece, template)) {
+      overlayTree(fragmentDir, targetDir, vars);
+    }
+  }
+  // Backend providers are wired by generating src/app.ts from the selection
+  // (not by stacking file overwrites per combination).
+  if (pieces.includes("frappe") || pieces.includes("keycloak")) {
+    writeFileSync(join(targetDir, "apps", name, "src/app.ts"), composeAppTs(pieces));
+  }
   writeProvenance(targetDir, {
     template,
     cliVersion: cliVersion() ?? "0.0.0",
     name,
     mpoVersion: vars.MPO_VERSION,
+    pieces,
   });
 
   // Initialize git with a scaffold commit (unless already inside a repo —
@@ -291,9 +593,7 @@ export async function initApp(
     // commit so a fresh init is immediately clean.
     if (scaffoldCommitted) {
       await spawn("git", ["add", "--", "pnpm-lock.yaml"], { cwd: targetDir })
-        .then(() =>
-          spawn("git", ["commit", "--amend", "--no-edit", "--quiet"], { cwd: targetDir }),
-        )
+        .then(() => spawn("git", ["commit", "--amend", "--no-edit", "--quiet"], { cwd: targetDir }))
         .catch(() => {});
     }
   } else {
@@ -309,6 +609,24 @@ export async function initApp(
     console.log("  pnpm ios        # iOS (requires pnpm dev in another terminal)");
     console.log("  pnpm android    # Android");
   }
+  if (pieces.includes("frappe")) {
+    console.log("  docker compose -f docker/compose.frappe.yaml up -d   # dev bench (see README)");
+  }
+  if (pieces.includes("keycloak")) {
+    console.log("  docker compose -f docker/compose.keycloak.yaml up -d # dev keycloak");
+  }
+  if (pieces.includes("gnome")) {
+    console.log("  pnpm gnome       # GTK4 desktop app (requires gjs + gtk4 — see README)");
+  }
+  if (pieces.includes("tauri")) {
+    console.log("  pnpm tauri:dev   # desktop app (requires the Rust toolchain)");
+  }
+  if (pieces.includes("vscode")) {
+    console.log("  pnpm build:vscode  # stage the VS Code extension into apps dist-vscode/");
+  }
+  if (pieces.includes("webext")) {
+    console.log("  pnpm build:webext  # stage the browser extension into apps dist-webext/");
+  }
   console.log("\nThis project consumes published @multiplatform.one/* packages.");
   console.log("It is not a fork of the multiplatform.one monorepo.");
 }

package/src/commands/updateApp.spec.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { threeWayMergePackageJson } from "./updateApp";
+
+const json = (value: unknown) => JSON.stringify(value, null, 2);
+
+describe("threeWayMergePackageJson", () => {
+  it("resolves dependency-range drift to the newer minimum", () => {
+    const base = json({ dependencies: { "@multiplatform.one/components": "^6.3.0" } });
+    const ours = json({ dependencies: { "@multiplatform.one/components": "^6.4.2" } });
+    const theirs = json({ dependencies: { "@multiplatform.one/components": "^6.4.3" } });
+    expect(threeWayMergePackageJson(base, ours, theirs)).toEqual({
+      dependencies: { "@multiplatform.one/components": "^6.4.3" },
+    });
+    // Symmetric: the project may be AHEAD of the template.
+    expect(threeWayMergePackageJson(base, theirs, ours)).toEqual({
+      dependencies: { "@multiplatform.one/components": "^6.4.3" },
+    });
+  });
+
+  it("prefers the template spelling on equal minimums", () => {
+    const base = json({ dependencies: { react: "^19.0.0" } });
+    const ours = json({ dependencies: { react: "19.2.0" } });
+    const theirs = json({ dependencies: { react: "~19.2.0" } });
+    expect(threeWayMergePackageJson(base, ours, theirs)).toEqual({
+      dependencies: { react: "~19.2.0" },
+    });
+  });
+
+  it("keeps project-added dependencies alongside template bumps", () => {
+    const base = json({ dependencies: { one: "^1.0.0" } });
+    const ours = json({ dependencies: { one: "^1.0.0", "@multiplatform.one/keycloak": "^6.4.2" } });
+    const theirs = json({ dependencies: { one: "^1.1.0" } });
+    expect(threeWayMergePackageJson(base, ours, theirs)).toEqual({
+      dependencies: { one: "^1.1.0", "@multiplatform.one/keycloak": "^6.4.2" },
+    });
+  });
+
+  it("applies template deletions the project did not touch", () => {
+    const base = json({ scripts: { postinstall: "patch-package", build: "vite build" } });
+    const ours = json({ scripts: { postinstall: "patch-package", build: "vite build" } });
+    const theirs = json({ scripts: { build: "vite build" } });
+    expect(threeWayMergePackageJson(base, ours, theirs)).toEqual({
+      scripts: { build: "vite build" },
+    });
+  });
+
+  it("resolves nested override maps", () => {
+    const base = json({ pnpm: { overrides: { "react-dom": "19.2.4" } } });
+    const ours = json({ pnpm: { overrides: { "react-dom": "19.2.5" } } });
+    const theirs = json({ pnpm: { overrides: { "react-dom": "19.2.6" } } });
+    expect(threeWayMergePackageJson(base, ours, theirs)).toEqual({
+      pnpm: { overrides: { "react-dom": "19.2.6" } },
+    });
+  });
+
+  it("returns undefined for genuine two-sided conflicts", () => {
+    const base = json({ scripts: { build: "vite build" } });
+    const ours = json({ scripts: { build: "vite build --mode ours" } });
+    const theirs = json({ scripts: { build: "vite build --mode theirs" } });
+    expect(threeWayMergePackageJson(base, ours, theirs)).toBeUndefined();
+  });
+
+  it("returns undefined for non-range dependency divergence", () => {
+    const base = json({ dependencies: { local: "^1.0.0" } });
+    const ours = json({ dependencies: { local: "workspace:*" } });
+    const theirs = json({ dependencies: { local: "^2.0.0" } });
+    expect(threeWayMergePackageJson(base, ours, theirs)).toBeUndefined();
+  });
+
+  it("returns undefined on unparseable input", () => {
+    expect(threeWayMergePackageJson("{}", "not json", "{}")).toBeUndefined();
+  });
+
+  it("treats a missing base as empty (add/add merges)", () => {
+    const ours = json({ dependencies: { a: "^1.0.0" } });
+    const theirs = json({ dependencies: { b: "^2.0.0" } });
+    expect(threeWayMergePackageJson(undefined, ours, theirs)).toEqual({
+      dependencies: { a: "^1.0.0", b: "^2.0.0" },
+    });
+  });
+});