@multiplatform.one/cli 5.0.27 → 6.0.1

package/src/bin/multiplatformOne.ts

@@ -1,72 +1,214 @@
-/*
- * File: /src/bin/multiplatformOne.ts
- * Project: @multiplatform.one/cli
- * File Created: 10-01-2025 21:02:36
- * Author: Clay Risser
- * -----
- * BitSpur (c) Copyright 2021 - 2025
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { generateVscodeConfig } from "../generateVscode.js";
 import {
   formatServiceList,
   lookupProjectRoot,
-  waitForApi,
   waitForFrappe,
   waitForKeycloak,
   waitForPostgres,
   waitServices,
 } from "@multiplatform.one/utils/dev";
-import { program } from "commander";
+import { Command } from "commander";
 import dotenv from "dotenv";
-import { execa } from "execa";
-import inquirer from "inquirer";
-import ora from "ora";
-import type { CookieCutterConfig } from "../types";
+
+import spawn from "nano-spawn";
+import YAML from "yaml";
+import yoctoSpinner from "yocto-spinner";
+import { discoverE2EApp, runE2ESession } from "../commands/e2e";
+import { init, runModifyStep } from "../commands/init";
 
 const projectRoot = lookupProjectRoot();
 const availableServices = ["api", "frappe", "solana", "ethereum", "sui"];
+
+/** Map a service name to its relative directory from the project root. */
+function serviceDir(name: string): string {
+  return `apps/${name}`;
+}
 const defaultDotenvPath = path.resolve(projectRoot, ".env");
-const availablePlatforms = [
-  "electron",
-  "expo",
-  "keycloak",
-  "one",
-  "storybook",
-  "storybook-expo",
-  "vocs",
-  "vscode",
-  "webext",
-];
-
-process.env.COOKIECUTTER = `sh ${path.resolve(
-  path.dirname(fileURLToPath(import.meta.url)),
-  "../../scripts/cookiecutter.sh",
-)}`;
-program.name("multiplatform.one");
+
+/** Apps that exist under apps/ and have package.json (discovered from filesystem). */
+async function getPresentApps(root: string): Promise<string[]> {
+  const appsDir = path.join(root, "apps");
+  try {
+    const entries = await fs.readdir(appsDir, { withFileTypes: true });
+    const names: string[] = [];
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const pkgPath = path.join(appsDir, e.name, "package.json");
+      try {
+        await fs.access(pkgPath);
+        names.push(e.name);
+      } catch {
+        // no package.json
+      }
+    }
+    return names;
+  } catch {
+    return [];
+  }
+}
+
+/** Root-level services that exist and have package.json (discovered from filesystem). */
+async function getPresentServices(root: string): Promise<string[]> {
+  const names: string[] = [];
+  for (const name of availableServices) {
+    const dir = path.join(root, serviceDir(name));
+    const pkgPath = path.join(dir, "package.json");
+    try {
+      const stat = await fs.stat(dir);
+      if (!stat.isDirectory()) continue;
+      await fs.access(pkgPath);
+      names.push(name);
+    } catch {
+      // dir or package.json missing
+    }
+  }
+  return names;
+}
+
+/** Turbo --filter args to exclude root-level workspaces that are not present (so turbo only runs where they exist).
+ *  Only generates exclude filters for directories that exist on disk (turbo errors on non-existent filter paths). */
+async function getTurboExcludeFiltersForMissing(root: string): Promise<string[]> {
+  const present = await getPresentServices(root);
+  const filters: string[] = [];
+  for (const s of availableServices) {
+    if (present.includes(s)) continue;
+    const dir = serviceDir(s);
+    try {
+      const stat = await fs.stat(path.join(root, dir));
+      if (stat.isDirectory()) filters.push(`!./${dir}`);
+    } catch {
+      // directory doesn't exist; turbo won't find it, no filter needed
+    }
+  }
+  return filters;
+}
+
+/** Workspaces that have Storybook and can run visual regression (discovered from filesystem + package.json). */
+export type StorybookVisualWorkspace = {
+  dirName: string;
+  absolutePath: string;
+  /** How to run visual test: run `make test/visual` in absolutePath, or run pnpm script by name. */
+  runVisual: "make" | "pnpm";
+  pnpmScript?: string;
+  /** If true, run `pnpm run build` then `pnpm exec lost-pixel` in workspace (no named script). */
+  runLostPixelAfterBuild?: boolean;
+};
+
+async function getStorybookVisualWorkspaces(root: string): Promise<StorybookVisualWorkspace[]> {
+  const out: StorybookVisualWorkspace[] = [];
+  const searchDirs = [
+    { base: path.join(root, "apps"), prefix: "apps/" },
+    { base: path.join(root, "packages"), prefix: "packages/" },
+  ];
+  for (const { base, prefix: _prefix } of searchDirs) {
+    let entries: { name: string }[];
+    try {
+      entries = (await fs.readdir(base, { withFileTypes: true }))
+        .filter((e) => e.isDirectory())
+        .map((e) => ({ name: e.name }));
+    } catch {
+      continue;
+    }
+    for (const { name } of entries) {
+      const dirPath = path.join(base, name);
+      const storybookDir = path.join(dirPath, ".storybook");
+      try {
+        const stat = await fs.stat(storybookDir);
+        if (!stat.isDirectory()) continue;
+      } catch {
+        continue;
+      }
+      const pkgPath = path.join(dirPath, "package.json");
+      let pkg: {
+        scripts?: Record<string, string>;
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+      } | null = null;
+      try {
+        pkg = JSON.parse(await fs.readFile(pkgPath, "utf8"));
+      } catch {
+        // no package.json or invalid
+      }
+      const hasLostPixel =
+        pkg && (pkg.dependencies?.["lost-pixel"] || pkg.devDependencies?.["lost-pixel"]);
+      const scripts = pkg?.scripts ?? {};
+      const testVisualScript =
+        scripts["test:visual"] ?? scripts["test/visual"] ?? scripts["test:visual:ci"];
+      const makefilePath = path.join(dirPath, "Makefile");
+      let makefileHasTestVisual = false;
+      try {
+        const makefile = await fs.readFile(makefilePath, "utf8");
+        makefileHasTestVisual = /test\/visual[\s:]/.test(makefile);
+      } catch {
+        // no Makefile
+      }
+      if (makefileHasTestVisual) {
+        out.push({ dirName: name, absolutePath: dirPath, runVisual: "make" });
+      } else if (testVisualScript) {
+        const scriptName = scripts["test:visual"]
+          ? "test:visual"
+          : scripts["test/visual"]
+            ? "test/visual"
+            : "test:visual:ci";
+        out.push({
+          dirName: name,
+          absolutePath: dirPath,
+          runVisual: "pnpm",
+          pnpmScript: scriptName,
+        });
+      } else if (hasLostPixel) {
+        out.push({
+          dirName: name,
+          absolutePath: dirPath,
+          runVisual: "pnpm",
+          pnpmScript: undefined,
+          runLostPixelAfterBuild: true,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+/** Discover frappe apps from frappe.yaml that have local source paths.
+ *  Supports both string entries (`- ./apps/core`) and object entries (`- name: core\n  source: ./apps/core`). */
+async function getFrappeApps(root: string): Promise<{ name: string; absolutePath: string }[]> {
+  const frappeDir = path.join(root, "apps", "frappe");
+  const frappeYamlPath = path.join(frappeDir, "frappe.yaml");
+  if (!fsSync.existsSync(frappeYamlPath)) return [];
+  const raw = await fs.readFile(frappeYamlPath, "utf8");
+  const config = YAML.parse(raw) as { apps?: (string | { name?: string; source?: string })[] };
+  const out: { name: string; absolutePath: string }[] = [];
+  for (const app of config?.apps ?? []) {
+    let src: string;
+    let name: string;
+    if (typeof app === "string") {
+      src = app;
+      name = path.basename(app);
+    } else {
+      if (!app.source || !app.name) continue;
+      src = app.source;
+      name = app.name;
+    }
+    src = src.startsWith("file://") ? src.slice(7) : src;
+    if (!src.startsWith("./") && !src.startsWith("../") && !src.startsWith("/")) continue;
+    const absPath = path.isAbsolute(src) ? src : path.resolve(frappeDir, src);
+    if (!fsSync.existsSync(absPath)) continue;
+    out.push({ name, absolutePath: absPath });
+  }
+  return out;
+}
+
+const program = new Command();
+program.name("mpo");
 program.version(
   JSON.parse(
     fsSync.readFileSync(
-      path.resolve(
-        path.dirname(fileURLToPath(import.meta.url)),
-        "../../package.json",
-      ),
+      path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json"),
       "utf8",
     ),
   )?.version,
@@ -74,260 +216,123 @@ program.version(
 
 program
   .command("init")
-  .option(
-    "-r, --remote <remote>",
-    "the remote to use",
-    "https://gitlab.com/bitspur/multiplatform.one/cookiecutter",
-  )
-  .option(
-    "-c, --checkout <branch>",
-    "branch, tag or commit to checkout",
-    "main",
-  )
-  .option("-p, --platforms <platforms>", "platforms to use")
-  .option("-s, --services <services>", "services to use")
-  .argument("[name]", "the name of the project", "")
-  .description("init multiplatform.one")
-  .action(async (name, options) => {
-    let { services, platforms } = options;
+  .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: string | undefined, options) => {
     if (
-      (
-        await execa("git", ["rev-parse", "--is-inside-work-tree"], {
-          reject: false,
-        })
-      ).exitCode === 0
+      await spawn("git", ["rev-parse", "--is-inside-work-tree"]).then(
+        () => true,
+        () => false,
+      )
     ) {
-      throw new Error(
-        "multiplatform.one cannot be initialized inside a git repository",
-      );
-    }
-    if (!name) {
-      name = (
-        await inquirer.prompt([
-          {
-            message: "What is the project name?",
-            name: "name",
-            type: "input",
-          },
-        ])
-      ).name;
-    }
-    if (!services) {
-      const servicesResult = (
-        await inquirer.prompt([
-          {
-            message: "What services are you using?",
-            name: "services",
-            type: "checkbox",
-            choices: availableServices.map((name) => ({ name })),
-          },
-        ])
-      ).services;
-      services = servicesResult.join(",");
+      throw new Error("mpo cannot be initialized inside a git repository");
     }
-    if (!platforms) {
-      const platformsResult = (
-        await inquirer.prompt([
-          {
-            message: "What platforms are you using?",
-            name: "platforms",
-            type: "checkbox",
-            choices: availablePlatforms.map((name) => ({ name })),
-          },
-        ])
-      ).platforms;
-      platforms = platformsResult.join(",");
-    }
-    const cookieCutterConfig: CookieCutterConfig = {
-      default_context: { name, platforms, services },
-    };
-    const cookieCutterConfigFile = path.join(
-      await fs.mkdtemp(path.join(os.tmpdir(), "multiplatform-")),
-      "config.json",
+    const cloneScript = path.resolve(
+      path.dirname(fileURLToPath(import.meta.url)),
+      "../../scripts/clone.sh",
     );
-    try {
-      await fs.writeFile(
-        cookieCutterConfigFile,
-        JSON.stringify(cookieCutterConfig, null, 2),
-      );
-      await execa(
-        "sh",
-        [
-          path.resolve(
-            path.dirname(fileURLToPath(import.meta.url)),
-            "../../scripts/init.sh",
-          ),
-          "--no-input",
-          "-f",
-          "--config-file",
-          cookieCutterConfigFile,
-          "--checkout",
-          options.checkout,
-          options.remote,
-        ],
-        {
-          stdio: "inherit",
-        },
-      );
-    } finally {
-      await fs.rm(cookieCutterConfigFile, { recursive: true, force: true });
-    }
+    await init(name, { ...options, cloneScript });
   });
 
+const defaultUpdateRemote = "https://gitlab.com/bitspur/multiplatform.one/multiplatform.one.git";
+
 program
   .command("update")
-  .option(
-    "-r, --remote <remote>",
-    "the remote to use",
-    "https://gitlab.com/bitspur/multiplatform.one/cookiecutter",
-  )
-  .option(
-    "-c, --checkout <branch>",
-    "branch, tag or commit to checkout",
-    "main",
-  )
-  .option("-p, --platforms <platforms>", "platforms to keep")
-  .option("-s, --services <services>", "services to keep")
-  .option("--no-prompt", "do not prompt for services and platforms")
-  .description("update multiplatform.one")
-  .action(
-    async (options: {
-      checkout: string;
-      noPrompt?: boolean;
-      platforms?: string;
-      remote: string;
-      services?: string;
-    }) => {
-      let platforms: string[] = [];
-      let services: string[] = [];
-      if (!options.platforms) {
-        platforms = (
-          await fs.readdir(path.join(projectRoot, "platforms"), {
-            withFileTypes: true,
-          })
-        )
-          .filter((d) => d.isDirectory())
-          .map((d) => d.name)
-          .filter((name) => availablePlatforms.includes(name));
-      }
-      if (!options.services) {
-        services = (await fs.readdir(projectRoot, { withFileTypes: true }))
-          .filter((d) => d.isDirectory())
-          .map((d) => d.name)
-          .filter((name) => availableServices.includes(name));
-      }
-      if (!options.noPrompt) {
-        const servicesResult = await inquirer.prompt([
-          {
-            message: "What services are you using?",
-            name: "services",
-            type: "checkbox",
-            choices: availableServices.map((name) => ({
-              name,
-              checked: services.includes(name),
-            })),
-          },
-        ]);
-        services = servicesResult.services;
-        const platformsResult = await inquirer.prompt([
-          {
-            message: "What platforms are you using?",
-            name: "platforms",
-            type: "checkbox",
-            choices: availablePlatforms.map((name) => ({
-              name,
-              checked: platforms.includes(name),
-            })),
-          },
-        ]);
-        platforms = platformsResult.platforms;
-      }
-      if (
-        (
-          await execa("git", ["rev-parse", "--is-inside-work-tree"], {
-            reject: false,
-          })
-        ).exitCode !== 0
-      ) {
-        throw new Error(
-          "multiplatform.one cannot be updated outside of a git repository",
-        );
+  .option("-c, --checkout <branch>", "branch, tag or commit to merge from upstream", "main")
+  .option("-r, --remote <url>", "upstream remote URL", defaultUpdateRemote)
+  .description("merge upstream and re-apply workspace config")
+  .action(async (options: { checkout: string; remote: string }) => {
+    // Update prechecks: must be in a git repo
+    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");
+    }
+    // Require clean working tree (no staged or unstaged changes)
+    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)",
+      );
+    }
+    // Validate multiplatform.one project with clear errors per failure
+    const rootPkgPath = path.resolve(projectRoot, "package.json");
+    const featuresPkgPath = path.resolve(projectRoot, "features/package.json");
+    try {
+      const stat = await fs.stat(rootPkgPath);
+      if (!stat.isFile()) {
+        throw new Error("mpo update requires a valid project: root package.json not found");
       }
-      if (
-        (
-          await execa("git", ["diff", "--cached", "--quiet"], {
-            reject: false,
-          })
-        ).exitCode !== 0
-      ) {
-        throw new Error(
-          "multiplatform.one cannot be updated with uncommitted changes",
-        );
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("valid project")) {
+        throw err;
       }
-      let cookieCutterConfig: CookieCutterConfig | undefined;
-      if (
-        (await fs.stat(path.resolve(projectRoot, "package.json"))).isFile() &&
-        (
-          await fs.stat(path.resolve(projectRoot, "app/package.json"))
-        ).isFile() &&
-        JSON.parse(
-          await fs.readFile(
-            path.resolve(projectRoot, "app/package.json"),
-            "utf8",
-          ),
-        )?.dependencies?.["multiplatform.one"]?.length
-      ) {
-        const name = JSON.parse(
-          await fs.readFile(path.resolve(projectRoot, "package.json"), "utf8"),
-        )?.name;
-        if (name) {
-          cookieCutterConfig = {
-            default_context: {
-              name,
-              platforms: platforms.join(","),
-              services: services.join(","),
-            },
-          };
-        }
+      throw new Error("mpo update requires a valid project: root package.json not found");
+    }
+    try {
+      const stat = await fs.stat(featuresPkgPath);
+      if (!stat.isFile()) {
+        throw new Error("mpo update requires a valid project: features/package.json not found");
       }
-      if (!cookieCutterConfig) {
-        throw new Error("not a multiplatform.one project");
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("valid project")) {
+        throw err;
       }
-      const cookieCutterConfigFile = path.join(
-        await fs.mkdtemp(path.join(os.tmpdir(), "multiplatform-")),
-        "config.json",
+      throw new Error("mpo update requires a valid project: features/package.json not found");
+    }
+    const featuresPkg = JSON.parse(await fs.readFile(featuresPkgPath, "utf8")) as {
+      dependencies?: Record<string, string>;
+    };
+    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",
       );
-      try {
-        await fs.writeFile(
-          cookieCutterConfigFile,
-          JSON.stringify(cookieCutterConfig, null, 2),
-        );
-        await execa(
-          "sh",
-          [
-            path.resolve(
-              path.dirname(fileURLToPath(import.meta.url)),
-              "../../scripts/update.sh",
-            ),
-            "--no-input",
-            "-f",
-            "--config-file",
-            cookieCutterConfigFile,
-            "--checkout",
-            options.checkout,
-            options.remote,
-          ],
-          {
-            cwd: projectRoot,
-            stdio: "inherit",
-            shell: true,
-          },
-        );
-      } finally {
-        await fs.rm(cookieCutterConfigFile, { recursive: true, force: true });
-      }
-    },
-  );
+    }
+
+    // Merge from upstream (update.sh: add remote, fetch, merge, remove remote, restore .updateignore list, pnpm lint)
+    const updateScript = path.resolve(
+      path.dirname(fileURLToPath(import.meta.url)),
+      "../../scripts/update.sh",
+    );
+    await spawn("sh", [updateScript, options.remote, options.checkout], {
+      cwd: projectRoot,
+      stdio: "inherit",
+      shell: true,
+    });
+
+    // Re-apply modify step with auto-detected apps and services
+    const presentServices = await getPresentServices(projectRoot);
+    const presentApps = await getPresentApps(projectRoot);
+    runModifyStep(projectRoot, presentServices, presentApps);
+
+    // Post-update refresh: .vscode from current workspace
+    try {
+      await generateVscodeConfig(projectRoot);
+    } catch {
+      // may fail in older projects without apps/ layout
+    }
+  });
 
 program
   .command("wait")
@@ -335,10 +340,7 @@ program
   .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(", ")})`,
-  )
+  .argument("<services>", `the services to wait for (${waitServices.join(", ")})`)
   .action(async (servicesString, options) => {
     dotenv.config({ path: options.dotenv || defaultDotenvPath });
     const interval = Number.parseInt(options.interval);
@@ -346,63 +348,94 @@ program
     const services: string[] = servicesString.split(",");
     try {
       await waitWithSpinner(services, { interval, timeout });
-    } catch (err) {
+    } catch {
       process.exit(1);
     }
   });
 
-program
-  .command("mesh")
-  .description("start the mesh server")
-  .option("-a, --api", "use api", false)
-  .option("-e, --dotenv <dotenv>", "dotenv file path", ".env")
-  .option("-f, --frappe", "use frappe", false)
-  .option("-i, --interval <interval>", "interval to wait for", "1000")
-  .option("-p, --port <port>", "port to run mesh on", "5002")
-  .option("-t, --timeout <timeout>", "timeout to wait for", "600000")
+const frappe = program
+  .command("frappe")
+  .description("manage frappe development environment")
+  .option("-e, --dotenv <dotenv>", "dotenv file path", ".env");
+
+frappe
+  .command("bootstrap")
+  .description("bootstrap frappe development environment")
+  .option("-u, --update", "update dependencies")
   .action(async (options) => {
-    dotenv.config({ path: options.dotenv || defaultDotenvPath });
-    process.env.UWS_HTTP_MAX_HEADERS_SIZE = "16384";
-    if (options.frappe || options.api) {
-      process.env.MESH_API = options.api ? "1" : "0";
-      process.env.MESH_FRAPPE = options.frappe ? "1" : "0";
-    }
-    if (
-      !(await fs
-        .stat(path.resolve(projectRoot, "app/main.ts"))
-        .catch(() => false))
-    ) {
-      process.env.MESH_APP = "0";
-    }
-    if (
-      !(await fs
-        .stat(path.resolve(projectRoot, "frappe/package.json"))
-        .catch(() => false))
-    ) {
-      process.env.MESH_FRAPPE = "0";
-    }
-    const services = [
-      ...(process.env.MESH_API === "1" ? ["api"] : []),
-      ...(process.env.MESH_FRAPPE === "1" ? ["frappe"] : []),
-    ];
-    if (services.length > 0) {
-      const interval = Number.parseInt(options.interval);
-      const timeout = Number.parseInt(options.timeout);
-      try {
-        await waitWithSpinner(services, { interval, timeout });
-      } catch (err) {
-        process.exit(1);
-      }
-    }
-    await execa(
-      "mesh",
+    const parentOptions = frappe.opts();
+    dotenv.config({ path: parentOptions.dotenv || defaultDotenvPath });
+    await spawn(
+      "sh",
       [
+        path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../scripts/frappe.sh"),
+        "bootstrap",
+        ...(options.update ? ["--update"] : []),
+      ],
+      {
+        stdio: "inherit",
+        shell: true,
+        cwd: projectRoot,
+      },
+    );
+  });
+
+frappe
+  .command("clean")
+  .description("clean frappe bench artifacts")
+  .option("--cache", "also remove frappe cache")
+  .action(async (options) => {
+    await spawn(
+      "sh",
+      [
+        path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../scripts/frappe.sh"),
+        "clean",
+        ...(options.cache ? ["--cache"] : []),
+      ],
+      {
+        stdio: "inherit",
+        shell: true,
+        cwd: projectRoot,
+      },
+    );
+  });
+
+frappe
+  .command("dev")
+  .description("start frappe development server")
+  .action(async () => {
+    const parentOptions = frappe.opts();
+    dotenv.config({ path: parentOptions.dotenv || defaultDotenvPath });
+    await spawn(
+      "sh",
+      [
+        path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../scripts/frappe.sh"),
         "dev",
-        "--port",
-        Number(options.port || process.env.MESH_PORT || 5002).toString(),
       ],
       {
         stdio: "inherit",
+        shell: true,
+        cwd: projectRoot,
+      },
+    );
+  });
+
+frappe
+  .command("bench")
+  .description("run bench command")
+  .action(async () => {
+    const parentOptions = frappe.opts();
+    dotenv.config({ path: parentOptions.dotenv || defaultDotenvPath });
+    await spawn(
+      "sh",
+      [
+        path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../scripts/frappe.sh"),
+        "bench",
+      ],
+      {
+        stdio: "inherit",
+        shell: true,
+        cwd: projectRoot,
       },
     );
   });
@@ -415,26 +448,21 @@ program
   )
   .description("run build command")
   .action(async (args: string[]) => {
-    args = args.flatMap((arg) => arg.split(","));
-    const packages = args.includes("packages");
-    const projects = args.filter((arg) => arg !== "packages");
+    const parsed = args.flatMap((arg) => arg.split(","));
+    const packages = parsed.includes("packages");
+    const projects = parsed.filter((arg) => arg !== "packages");
+    const presentApps = await getPresentApps(projectRoot);
+    const presentServices = await getPresentServices(projectRoot);
     if ((!projects.length && !packages) || packages) {
-      await execa(
+      await spawn(
         "pnpm",
         [
           "turbo",
           "run",
           "build",
           "--filter",
-          "'!./platforms/*'",
-          "--filter",
-          "'!./api'",
-          "--filter",
-          "'!./solana'",
-          "--filter",
-          "'!./ethereum'",
-          "--filter",
-          "'!./sui'",
+          "'!./apps/*'",
+          ...presentServices.flatMap((s) => ["--filter", `'!./${serviceDir(s)}'`]),
         ],
         {
           stdio: "inherit",
@@ -443,223 +471,259 @@ program
         },
       );
     }
-    for (const platform of await fs.readdir("platforms")) {
-      if (
-        ((!projects.length && !packages) || projects.includes(platform)) &&
-        (await fs
-          .access(path.join(projectRoot, "platforms", platform, "package.json"))
+    for (const platform of presentApps) {
+      if ((!projects.length && !packages) || projects.includes(platform)) {
+        const hasBuild = await fs
+          .access(path.join(projectRoot, "apps", platform, "package.json"))
           .then(
             () =>
               JSON.parse(
                 fsSync.readFileSync(
-                  path.join(projectRoot, "platforms", platform, "package.json"),
+                  path.join(projectRoot, "apps", platform, "package.json"),
                   "utf8",
                 ),
               ).scripts?.build,
           )
-          .catch(() => false))
-      ) {
-        await execa("./mkpm", [`${platform}/build`], {
-          stdio: "inherit",
-          shell: true,
-          cwd: projectRoot,
-        });
+          .catch(() => false);
+        if (hasBuild) {
+          await spawn("pnpm", ["turbo", "run", "build", `--filter=./apps/${platform}`], {
+            stdio: "inherit",
+            shell: true,
+            cwd: projectRoot,
+          });
+        }
       }
     }
-    for (const service of availableServices) {
-      if (
-        ((!projects.length && !packages) || projects.includes(service)) &&
-        (await fs
-          .access(path.join(projectRoot, service, "package.json"))
+    for (const service of presentServices) {
+      if ((!projects.length && !packages) || projects.includes(service)) {
+        const dir = serviceDir(service);
+        const hasBuild = await fs
+          .access(path.join(projectRoot, dir, "package.json"))
           .then(
             () =>
-              JSON.parse(
-                fsSync.readFileSync(
-                  path.join(projectRoot, service, "package.json"),
-                  "utf8",
-                ),
-              ).scripts?.build,
+              JSON.parse(fsSync.readFileSync(path.join(projectRoot, dir, "package.json"), "utf8"))
+                .scripts?.build,
           )
-          .catch(() => false))
-      ) {
-        await execa("./mkpm", [`${service}/build`], {
-          stdio: "inherit",
-          shell: true,
-          cwd: projectRoot,
-        });
+          .catch(() => false);
+        if (hasBuild) {
+          await spawn("pnpm", ["turbo", "run", "build", `--filter=./${dir}`], {
+            stdio: "inherit",
+            shell: true,
+            cwd: projectRoot,
+          });
+        }
       }
     }
   });
 
 program
   .command("test")
-  .argument(
-    "[args...]",
-    `test to run: ${[...availableServices, "packages"].join(", ")} (default: all)`,
-  )
+  .argument("[args...]", "test to run: unit, integration, e2e, visual (default: unit)")
+  .option("--up-only", "start E2E environment and exit (for agent/manual testing)")
+  .option("--down", "tear down E2E test environment")
+  .option("--port-offset <number>", "port offset from defaults", "1000")
+  .option("--project <name>", "Docker project name for E2E")
+  .option("--no-build", "skip image builds for E2E")
+  .option("--filter <pattern>", "run specific Playwright test files")
   .description("run test command")
-  .action(async (args: string[]) => {
-    args = args.flatMap((arg) => arg.split(","));
-    const packages = args.includes("packages");
-    const projects = args.filter((arg) => arg !== "packages");
-    if ((!projects.length && !packages) || packages) {
-      await execa(
-        "pnpm",
-        [
-          "turbo",
-          "run",
-          "test",
-          "--filter",
-          "'!./platforms/*'",
-          "--filter",
-          "'!./api'",
-          "--filter",
-          "'!./solana'",
-          "--filter",
-          "'!./ethereum'",
-          "--filter",
-          "'!./sui'",
-        ],
-        {
-          stdio: "inherit",
-          shell: true,
-          cwd: projectRoot,
-        },
-      );
-    }
-    for (const platform of await fs.readdir("platforms")) {
-      if (
-        ((!projects.length && !packages) || projects.includes(platform)) &&
-        (await fs
-          .access(path.join(projectRoot, "platforms", platform, "package.json"))
-          .then(
-            () =>
-              JSON.parse(
-                fsSync.readFileSync(
-                  path.join(projectRoot, "platforms", platform, "package.json"),
-                  "utf8",
-                ),
-              ).scripts?.test,
-          )
-          .catch(() => false))
-      ) {
-        await execa("./mkpm", [`${platform}/test`], {
-          stdio: "inherit",
-          shell: true,
-          cwd: projectRoot,
-        });
-      }
-    }
-    for (const service of availableServices) {
-      if (
-        ((!projects.length && !packages) || projects.includes(service)) &&
-        (await fs
-          .access(path.join(projectRoot, service, "package.json"))
-          .then(
-            () =>
-              JSON.parse(
-                fsSync.readFileSync(
-                  path.join(projectRoot, service, "package.json"),
-                  "utf8",
-                ),
-              ).scripts?.test,
-          )
-          .catch(() => false))
-      ) {
-        await execa("./mkpm", [`${service}/test`], {
-          stdio: "inherit",
-          shell: true,
-          cwd: projectRoot,
-        });
+  .action(async (args: string[], options) => {
+    const parsed = args.flatMap((arg) => arg.split(","));
+
+    // Handle unit tests (turbo test with dynamic excludes: missing services + E2E app, plus frappe app unit tests)
+    if (parsed.includes("unit")) {
+      const excludeFilters = await getTurboExcludeFiltersForMissing(projectRoot);
+      const e2eApp = await discoverE2EApp(projectRoot);
+      const filters = [
+        ...excludeFilters.flatMap((f) => ["--filter", f]),
+        ...(e2eApp ? ["--filter", `'!./apps/${e2eApp}'`] : []),
+      ];
+      await spawn("pnpm", ["turbo", "run", "test", ...filters], {
+        stdio: "inherit",
+        shell: true,
+        cwd: projectRoot,
+      });
+
+      // Run frappe app unit tests (exclude integration-marked tests)
+      const frappeApps = await getFrappeApps(projectRoot);
+      for (const app of frappeApps) {
+        const hasPytest = await fs
+          .access(path.join(app.absolutePath, "pyproject.toml"))
+          .then(() => true)
+          .catch(() => false);
+        if (hasPytest) {
+          try {
+            await spawn("bench", ["run-tests", "--app", app.name, "--", "-m", "not integration"], {
+              stdio: "inherit",
+              cwd: path.join(projectRoot, "apps", "frappe"),
+            });
+          } catch {
+            console.warn(`frappe app ${app.name} unit tests failed (bench may not be available)`);
+          }
+        }
       }
+
+      if (parsed.length === 1) return;
     }
-  });
 
-program
-  .command("check")
-  .argument("[args...]", "checks to run: spelling, types, lint (default: all)")
-  .description("run check command")
-  .action(async (args: string[]) => {
-    args = args.flatMap((arg) => arg.split(","));
-    const spelling = !args.length || args.includes("spelling");
-    const types = !args.length || args.includes("types");
-    const lint = !args.length || args.includes("lint");
-    let exitCode = 0;
-    if (spelling) {
-      try {
-        await execa(
-          "pnpm",
-          [
-            "cspell",
-            "--unique",
-            "`(git ls-files && (git lfs ls-files | cut -d' ' -f3))`",
-          ],
-          {
-            stdio: "inherit",
-            shell: true,
-            cwd: projectRoot,
-          },
-        );
-      } catch (err) {
-        if (err instanceof Error && "exitCode" in err) {
-          exitCode = (err as { exitCode: number }).exitCode;
-        } else {
-          exitCode = 1;
+    // Handle integration tests (turbo test + frappe app integration tests)
+    if (parsed.includes("integration")) {
+      const excludeFilters = await getTurboExcludeFiltersForMissing(projectRoot);
+      const e2eApp = await discoverE2EApp(projectRoot);
+      const filters = [
+        ...excludeFilters.flatMap((f) => ["--filter", f]),
+        ...(e2eApp ? ["--filter", `'!./apps/${e2eApp}'`] : []),
+      ];
+      await spawn("pnpm", ["turbo", "run", "test", ...filters], {
+        stdio: "inherit",
+        shell: true,
+        cwd: projectRoot,
+      });
+
+      // Run frappe app integration tests (only integration-marked tests)
+      const frappeApps = await getFrappeApps(projectRoot);
+      for (const app of frappeApps) {
+        const hasPytest = await fs
+          .access(path.join(app.absolutePath, "pyproject.toml"))
+          .then(() => true)
+          .catch(() => false);
+        if (hasPytest) {
+          try {
+            await spawn("bench", ["run-tests", "--app", app.name, "--", "-m", "integration"], {
+              stdio: "inherit",
+              cwd: path.join(projectRoot, "apps", "frappe"),
+            });
+          } catch {
+            console.warn(
+              `frappe app ${app.name} integration tests failed (bench may not be available)`,
+            );
+          }
         }
       }
+
+      if (parsed.length === 1) return;
     }
-    if (types) {
-      try {
-        await execa("turbo", ["run", "typecheck"], {
-          stdio: "inherit",
-          shell: true,
-          cwd: projectRoot,
-        });
-      } catch (err) {
-        if (err instanceof Error && "exitCode" in err) {
-          exitCode = (err as { exitCode: number }).exitCode;
-        } else {
-          exitCode = 1;
-        }
+
+    // Handle E2E test sessions
+    if (parsed.includes("e2e")) {
+      const teardownHandler = () => {
+        runE2ESession(projectRoot, { down: true }).then(() => process.exit(130));
+      };
+      if (!options.down) {
+        process.on("SIGINT", teardownHandler);
+        process.on("SIGTERM", teardownHandler);
       }
+      await runE2ESession(projectRoot, {
+        upOnly: options.upOnly,
+        down: options.down,
+        portOffset: Number.parseInt(options.portOffset),
+        project: options.project,
+        noBuild: options.build === false,
+        filter: options.filter,
+      });
+      return;
     }
-    if (lint) {
-      try {
-        await execa(
-          "pnpm",
-          [
-            "biome",
-            "check",
-            "--fix",
-            "--unsafe",
-            "`(git ls-files && (git lfs ls-files | cut -d' ' -f3)) | sort | uniq -u | grep -E '(html)|(s?css)|(md)|(json)|(yaml)|([jt]sx?)$'`",
-          ],
-          {
+
+    // Handle visual regression tests (discovered dynamically from storybook + lost-pixel)
+    if (parsed.includes("visual")) {
+      const workspaces = await getStorybookVisualWorkspaces(projectRoot);
+      if (!workspaces.length) {
+        console.warn(
+          "No visual regression workspaces found (.storybook + Makefile test/visual, test:visual script, or lost-pixel).",
+        );
+        return;
+      }
+      for (const w of workspaces) {
+        if (w.runVisual === "make") {
+          await spawn("make", ["-C", w.absolutePath, "test/visual"], {
             stdio: "inherit",
-            shell: true,
             cwd: projectRoot,
-          },
-        );
-      } catch (err) {
-        if (err instanceof Error && "exitCode" in err) {
-          exitCode = (err as { exitCode: number }).exitCode;
-        } else {
-          exitCode = 1;
+          });
+        } else if (w.runLostPixelAfterBuild) {
+          await spawn("pnpm", ["run", "build"], {
+            stdio: "inherit",
+            cwd: w.absolutePath,
+          });
+          await spawn("pnpm", ["exec", "lost-pixel"], {
+            stdio: "inherit",
+            cwd: w.absolutePath,
+          });
+        } else if (w.pnpmScript) {
+          await spawn("pnpm", ["run", w.pnpmScript], {
+            stdio: "inherit",
+            cwd: w.absolutePath,
+          });
         }
       }
+      return;
     }
-    process.exit(exitCode);
+  });
+
+/**
+ * Run ruff format or check on the Frappe Python apps (if present).
+ * Returns true if the ruff step failed.
+ */
+async function ruffStep(mode: "format" | "check"): Promise<boolean> {
+  const frappeApps = path.join(projectRoot, "apps", "frappe", "apps");
+  if (!fsSync.existsSync(frappeApps)) return false;
+  const label = mode === "format" ? "ruff format" : "ruff check";
+  console.log(`\n── ${label} (Python) ──`);
+  try {
+    await spawn("ruff", [mode, frappeApps], {
+      stdio: "inherit",
+      cwd: projectRoot,
+    });
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+program
+  .command("format")
+  .description("format all supported files (TS, Python, etc.) via turbo")
+  .action(async () => {
+    await spawn("turbo", ["run", "format", "--filter=//"], {
+      stdio: "inherit",
+      cwd: projectRoot,
+    });
+    await ruffStep("format");
+  });
+
+program
+  .command("lint")
+  .description("lint and typecheck all supported files (TS, Python, etc.) via turbo")
+  .action(async () => {
+    const excludeFilters = await getTurboExcludeFiltersForMissing(projectRoot);
+    let turboFailed = false;
+    try {
+      await spawn(
+        "turbo",
+        [
+          "run",
+          "lint",
+          "typecheck",
+          "--filter=//",
+          "--continue",
+          "--filter",
+          "!@package/features",
+          ...excludeFilters.flatMap((f) => ["--filter", f]),
+        ],
+        { stdio: "inherit", cwd: projectRoot },
+      );
+    } catch {
+      turboFailed = true;
+    }
+    const ruffFailed = await ruffStep("check");
+    if (turboFailed || ruffFailed) process.exit(1);
   });
 
 program
   .command("count")
   .description("count lines of code")
   .action(async () => {
-    await execa(
+    await spawn(
       "cloc",
-      [
-        "`(git ls-files && (git lfs ls-files | cut -d' ' -f3)) | sort | uniq -u | grep -E '(html)|(s?css)|(md)|(json)|(yaml)|([jt]sx?)$'`",
-      ],
+      ["`git ls-files | grep -E '(html)|(s?css)|(md)|(json)|(yaml)|([jt]sx?)$'`"],
       {
         stdio: "inherit",
         shell: true,
@@ -672,7 +736,7 @@ program
   .command("generate")
   .description("run generate command")
   .action(async () => {
-    await execa("pnpm", ["turbo", "run", "generate"], {
+    await spawn("pnpm", ["turbo", "run", "generate"], {
       stdio: "inherit",
       shell: true,
       cwd: projectRoot,
@@ -687,18 +751,17 @@ async function waitWithSpinner(
 ) {
   const { interval = 1000, timeout = 600000 } = options;
   const waitFunctions = {
-    api: waitForApi,
     frappe: waitForFrappe,
     postgres: waitForPostgres,
     keycloak: waitForKeycloak,
   };
   const unreadyServices = [...services];
-  const spinner = ora(
-    `waiting for ${formatServiceList(unreadyServices)}`,
-  ).start();
+  const spinner = yoctoSpinner({
+    text: `waiting for ${formatServiceList(unreadyServices)}`,
+  }).start();
   function updateSpinner(readyService: string) {
     unreadyServices.splice(unreadyServices.indexOf(readyService), 1);
-    spinner.succeed(`${readyService} is ready`);
+    spinner.success(`${readyService} is ready`);
     if (unreadyServices.length) {
       spinner.start(`waiting for ${formatServiceList(unreadyServices)}`);
     }
@@ -721,11 +784,9 @@ async function waitWithSpinner(
   } catch (err) {
     const error = err as Error;
     if (error.message === "Timeout") {
-      spinner.fail(
-        `${formatServiceList(unreadyServices)} timed out after ${timeout}ms`,
-      );
+      spinner.error(`${formatServiceList(unreadyServices)} timed out after ${timeout}ms`);
     } else {
-      spinner.fail(error.message);
+      spinner.error(error.message);
     }
     throw error;
   } finally {