@multiplatform.one/cli 6.7.0 → 7.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/cli",
-  "version": "6.7.0",
+  "version": "7.0.0",
   "description": "multiplatform.one cli — mpo init / create-multiplatform-app",
   "keywords": [
     "create-multiplatform-app",
@@ -61,7 +61,7 @@
     "nano-spawn": "^2.1.0",
     "yaml": "^2.8.3",
     "yocto-spinner": "^1.1.0",
-    "@multiplatform.one/utils": "6.7.0"
+    "@multiplatform.one/utils": "7.0.0"
   },
   "devDependencies": {
     "@types/inquirer": "^9.0.9",

package/scripts/frappe-app-name.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Resolve a frappe app's python MODULE name from its source tree.
+
+sites/apps.txt entries, bench app directory names, and `bench --app`
+arguments must be importable python module names (frappe_mcp), while git
+repo basenames and pyproject/setup.py distribution names are often
+hyphenated (frappe-mcp, github.com/frappe/mcp). A hyphenated entry in
+sites/apps.txt breaks every bench boot, so the module name is derived
+from the most authoritative source available:
+
+1. the package directory containing hooks.py (classic frappe app layout)
+2. the package directory matching the normalized distribution name
+3. the sole package directory at the app root
+4. the package directory matching the normalized fallback name
+5. the normalized distribution name (pyproject [project].name, setup.py name=)
+6. the normalized fallback (repo/dir basename)
+
+Usage: frappe-app-name.py <app-path> [fallback]
+Prints the module name on stdout; exits non-zero if none can be derived.
+"""
+
+import ast
+import re
+import sys
+from pathlib import Path
+
+
+def normalize(name: str) -> str:
+    """Map a distribution/repo name to module-name form (PEP 503 runs of
+    `-_.` and whitespace become single underscores, lowercased)."""
+    return re.sub(r"[-_.\s]+", "_", name.strip().lower())
+
+
+def distribution_name(app_path: Path) -> str:
+    pyproject = app_path / "pyproject.toml"
+    if pyproject.is_file():
+        import tomllib
+
+        try:
+            with pyproject.open("rb") as f:
+                name = tomllib.load(f).get("project", {}).get("name", "")
+        except (tomllib.TOMLDecodeError, OSError):
+            name = ""
+        if isinstance(name, str) and name:
+            return name
+    setup_py = app_path / "setup.py"
+    if setup_py.is_file():
+        try:
+            tree = ast.parse(setup_py.read_text(encoding="utf-8"))
+        except (SyntaxError, OSError):
+            return ""
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call):
+                continue
+            for kw in node.keywords:
+                if (
+                    kw.arg == "name"
+                    and isinstance(kw.value, ast.Constant)
+                    and isinstance(kw.value.value, str)
+                ):
+                    return kw.value.value
+    return ""
+
+
+def package_dirs(app_path: Path) -> "list[Path]":
+    """Direct child directories importable as python packages."""
+    try:
+        children = sorted(app_path.iterdir())
+    except OSError:
+        return []
+    return [
+        child
+        for child in children
+        if child.is_dir()
+        and child.name.isidentifier()
+        and (child / "__init__.py").is_file()
+    ]
+
+
+def derive_module_name(app_path: Path, fallback: str = "") -> str:
+    dist = distribution_name(app_path)
+    packages = package_dirs(app_path)
+    hooks = [p for p in packages if (p / "hooks.py").is_file()]
+    if hooks:
+        if len(hooks) > 1:
+            for want in filter(None, (normalize(dist), normalize(fallback))):
+                for package in hooks:
+                    if package.name == want:
+                        return package.name
+        return hooks[0].name
+    if dist:
+        want = normalize(dist)
+        for package in packages:
+            if package.name == want:
+                return package.name
+    if len(packages) == 1:
+        return packages[0].name
+    if fallback:
+        want = normalize(fallback)
+        for package in packages:
+            if package.name == want:
+                return package.name
+    if dist:
+        return normalize(dist)
+    if fallback:
+        return normalize(fallback)
+    return ""
+
+
+def main(argv: "list[str]") -> int:
+    if len(argv) < 2 or not argv[1]:
+        print("usage: frappe-app-name.py <app-path> [fallback]", file=sys.stderr)
+        return 2
+    app_path = Path(argv[1])
+    fallback = argv[2] if len(argv) > 2 else ""
+    name = derive_module_name(app_path, fallback)
+    if not name:
+        print(f"could not determine app name from {app_path}", file=sys.stderr)
+        return 1
+    print(name)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/scripts/frappe-app-name.spec.ts

@@ -0,0 +1,191 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+// frappe-bootstrap.sh writes this script's output into sites/apps.txt and
+// uses it for apps/<name> dirs and bench --app args, so it must always be
+// the importable python module name (frappe_mcp), never the hyphenated
+// repo/distribution name (frappe-mcp).
+const SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "frappe-app-name.py");
+
+function derive(appPath: string, fallback?: string) {
+  const result = spawnSync(
+    "python3",
+    [SCRIPT, appPath, ...(fallback === undefined ? [] : [fallback])],
+    { encoding: "utf-8" },
+  );
+  return {
+    status: result.status,
+    stdout: result.stdout.trim(),
+    stderr: result.stderr.trim(),
+  };
+}
+
+interface Case {
+  name: string;
+  /** Relative file path -> contents. Paths ending in "/" create bare dirs. */
+  files: Record<string, string>;
+  fallback?: string;
+  expected: string;
+}
+
+const pyproject = (name: string) => `[project]\nname = "${name}"\n`;
+
+const cases: Case[] = [
+  {
+    name: "classic app: hyphenated distribution, underscored module with hooks",
+    files: {
+      "pyproject.toml": pyproject("frappe-mcp"),
+      "frappe_mcp/__init__.py": "",
+      "frappe_mcp/hooks.py": 'app_name = "frappe_mcp"\n',
+    },
+    fallback: "mcp",
+    expected: "frappe_mcp",
+  },
+  {
+    name: "matching distribution and module names (plus stray root __init__.py)",
+    files: {
+      "pyproject.toml": pyproject("core"),
+      "__init__.py": "",
+      "core/__init__.py": "",
+      "core/hooks.py": 'app_name = "core"\n',
+    },
+    fallback: "core",
+    expected: "core",
+  },
+  {
+    name: "hookless package with hyphenated distribution (frappe/mcp shape)",
+    files: {
+      "pyproject.toml": pyproject("frappe-mcp"),
+      "frappe_mcp/__init__.py": "",
+      "frappe_mcp/server/__init__.py": "",
+    },
+    fallback: "mcp",
+    expected: "frappe_mcp",
+  },
+  {
+    name: "layout only: hooks package without any metadata",
+    files: {
+      "my_app/__init__.py": "",
+      "my_app/hooks.py": "",
+    },
+    fallback: "my-app",
+    expected: "my_app",
+  },
+  {
+    name: "nested module dirs and decoy packages do not confuse the hooks rule",
+    files: {
+      "pyproject.toml": pyproject("myapp"),
+      "myapp/__init__.py": "",
+      "myapp/hooks.py": "",
+      "myapp/sub/__init__.py": "",
+      "myapp/sub/hooks.py": "",
+      "tests/__init__.py": "",
+    },
+    fallback: "myapp-repo",
+    expected: "myapp",
+  },
+  {
+    name: "multiple hookless packages: distribution name picks the module",
+    files: {
+      "pyproject.toml": pyproject("cool-app"),
+      "cool_app/__init__.py": "",
+      "tests/__init__.py": "",
+    },
+    fallback: "cool-app-repo",
+    expected: "cool_app",
+  },
+  {
+    name: "multiple hooks packages: distribution name breaks the tie",
+    files: {
+      "pyproject.toml": pyproject("b-app"),
+      "a_app/__init__.py": "",
+      "a_app/hooks.py": "",
+      "b_app/__init__.py": "",
+      "b_app/hooks.py": "",
+    },
+    expected: "b_app",
+  },
+  {
+    name: "setup.py name is normalized and matched against the layout",
+    files: {
+      "setup.py": 'from setuptools import setup\nsetup(name="legacy-app")\n',
+      "legacy_app/__init__.py": "",
+      "tests/__init__.py": "",
+    },
+    fallback: "legacy",
+    expected: "legacy_app",
+  },
+  {
+    name: "metadata only: distribution name is normalized (dots and hyphens)",
+    files: {
+      "pyproject.toml": pyproject("multiplatform.one-app"),
+    },
+    fallback: "repo",
+    expected: "multiplatform_one_app",
+  },
+  {
+    name: "fallback only: repo basename is normalized",
+    files: {},
+    fallback: "repo-name",
+    expected: "repo_name",
+  },
+];
+
+describe("frappe-app-name.py", () => {
+  let sandbox: string;
+
+  beforeAll(() => {
+    const python = spawnSync("python3", ["--version"], { encoding: "utf-8" });
+    if (python.status !== 0) {
+      throw new Error("python3 is required to run the frappe-app-name derivation specs");
+    }
+    sandbox = mkdtempSync(join(tmpdir(), "mpo-frappe-app-name-"));
+  });
+
+  afterAll(() => {
+    rmSync(sandbox, { recursive: true, force: true });
+  });
+
+  function makeApp(name: string, files: Record<string, string>): string {
+    const root = join(sandbox, name.replace(/[^a-z0-9]+/gi, "-"));
+    mkdirSync(root, { recursive: true });
+    for (const [relative, contents] of Object.entries(files)) {
+      const target = join(root, relative);
+      if (relative.endsWith("/")) {
+        mkdirSync(target, { recursive: true });
+        continue;
+      }
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, contents);
+    }
+    return root;
+  }
+
+  for (const [index, spec] of cases.entries()) {
+    it(spec.name, () => {
+      const root = makeApp(`case-${index}`, spec.files);
+      const result = derive(root, spec.fallback);
+      expect(result.stderr).toBe("");
+      expect(result.status).toBe(0);
+      expect(result.stdout).toBe(spec.expected);
+    });
+  }
+
+  it("fails loudly when nothing can be derived", () => {
+    const root = makeApp("case-underivable", {});
+    const result = derive(root);
+    expect(result.status).toBe(1);
+    expect(result.stdout).toBe("");
+    expect(result.stderr).toContain("could not determine app name");
+  });
+
+  it("rejects a missing app path argument", () => {
+    const result = derive("");
+    expect(result.status).toBe(2);
+    expect(result.stderr).toContain("usage:");
+  });
+});

package/scripts/frappe-bootstrap.sh

@@ -22,7 +22,8 @@ _sed() {
     fi
 }
 
-. "$(cd "$(dirname "$0")" && pwd)/frappe-helpers.sh"
+FRAPPE_SCRIPTS_DIR="$(cd "$(dirname "$0")" && pwd)"
+. "$FRAPPE_SCRIPTS_DIR/frappe-helpers.sh"
 
 _clean_bench_artifacts() {
     rm -rf "$BENCH_DIR/apps/frappe" 2>/dev/null || true
@@ -62,36 +63,13 @@ print(" ".join(f"{k}=={v}" if "=" not in v else f"{k}{v}" for k, v in d.items())
     fi
 }
 
+# Resolves the app's python MODULE name (frappe_mcp), never the repo or
+# pyproject distribution name (frappe-mcp): apps.txt entries, apps/ dir
+# names, and bench --app args must all be importable module names -- a
+# hyphenated apps.txt entry breaks every bench boot. Derivation lives in
+# frappe-app-name.py (layout-first, unit-tested).
 _get_app_name() {
-    _APP_PATH="$1"
-    _FALLBACK="$2"
-    _NAME=""
-    if [ -f "$_APP_PATH/pyproject.toml" ]; then
-        _NAME="$(python3 -c '
-import tomllib, sys
-with open(sys.argv[1], "rb") as f:
-    print(tomllib.load(f).get("project", {}).get("name", ""))
-' "$_APP_PATH/pyproject.toml")"
-    fi
-    if [ -z "$_NAME" ] && [ -f "$_APP_PATH/setup.py" ]; then
-        _NAME="$(python3 -c '
-import ast, sys
-tree = ast.parse(open(sys.argv[1]).read())
-for node in ast.walk(tree):
-    if isinstance(node, ast.Call) and any(
-        kw.arg == "name" and isinstance(kw.value, ast.Constant)
-        for kw in node.keywords
-    ):
-        print(next(kw.value.value for kw in node.keywords if kw.arg == "name"))
-        break
-' "$_APP_PATH/setup.py" 2>/dev/null || true)"
-    fi
-    _NAME="${_NAME:-$_FALLBACK}"
-    if [ -z "$_NAME" ]; then
-        echo "could not determine app name from $_APP_PATH" >&2
-        return 1
-    fi
-    echo "$_NAME"
+    python3 "$FRAPPE_SCRIPTS_DIR/frappe-app-name.py" "$1" "$2"
 }
 
 _register_app() {

package/src/bin/multiplatformOne.ts

@@ -17,6 +17,7 @@ import dotenv from "dotenv";
 import spawn from "nano-spawn";
 import YAML from "yaml";
 import yoctoSpinner from "yocto-spinner";
+import { adoptApp } from "../commands/adoptApp";
 import { discoverE2EApp, runE2ESession } from "../commands/e2e";
 import { init, runModifyStep } from "../commands/init";
 import { INIT_APP_PIECES, initApp, readProvenance } from "../commands/initApp";
@@ -227,9 +228,16 @@ program
     "--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(
+    "--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(
@@ -278,6 +286,9 @@ program
     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");
+    }
     // Piece flags are multi-select; passing any of them skips the interactive
     // pieces prompt. No flags + --yes (or non-TTY) → no pieces.
     const pieces = INIT_APP_PIECES.filter((piece) => Boolean(options[piece]));
@@ -285,12 +296,43 @@ program
       skipInstall: Boolean(options.skipInstall),
       skipGit: Boolean(options.skipGit),
       version: options.mpoVersion,
-      template: webOnly ? "app" : options.universal ? "universal" : undefined,
+      template: options.piecesOnly
+        ? "none"
+        : webOnly
+          ? "app"
+          : options.universal
+            ? "universal"
+            : undefined,
       yes: Boolean(options.yes),
       pieces: pieces.length ? pieces : undefined,
     });
   });
 
+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 : undefined,
+      name: options.name,
+      yes: Boolean(options.yes),
+    });
+  });
+
 const defaultUpdateRemote = "https://gitlab.com/bitspur/frappe/multiplatform.one.git";
 
 program
@@ -306,8 +348,16 @@ program
     "--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 project to the current template (three-way merge via .mpo.json provenance); monorepo forks fall back to the upstream merge flow",
+    "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: {
@@ -315,6 +365,8 @@ program
       remote: string;
       skipInstall?: boolean;
       mpoVersion?: string;
+      assumeVersion?: string;
+      template?: string;
     }) => {
       // Update prechecks: must be in a git repo
       if (
@@ -325,13 +377,25 @@ program
       ) {
         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}"`);
+      }
       // Scaffolded consumer projects carry .mpo.json provenance — use the
-      // copier-style three-way template update. Monorepo forks (identified by
-      // the legacy features/package.json marker) fall through to the upstream-
-      // merge flow below; anything else gets the provenance guidance instead
-      // of the fork flow's unrelated errors.
-      if (readProvenance(projectRoot)) {
-        await updateApp({ skipInstall: options.skipInstall, version: options.mpoVersion });
+      // copier-style three-way template update (--assume-version bootstraps
+      // the provenance for pre-6.3 scaffolds first). Monorepo forks
+      // (identified by the legacy features/package.json marker) fall through
+      // to the upstream-merge flow below; anything else gets the provenance
+      // guidance instead of the fork flow's unrelated errors.
+      if (readProvenance(projectRoot) || options.assumeVersion) {
+        await updateApp({
+          skipInstall: options.skipInstall,
+          version: options.mpoVersion,
+          assumeVersion: options.assumeVersion,
+          assumeTemplate: options.template as "universal" | "app" | undefined,
+        });
         return;
       }
       const legacyFork = await fs.stat(path.resolve(projectRoot, "features/package.json")).then(
@@ -340,10 +404,11 @@ program
       );
       if (!legacyFork) {
         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`.",
+          ".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> [...]",
         );
       }
       // Require clean working tree (no staged or unstaged changes)