@rainbow-robotics/muscat-plugin-kit 1.10.1-dev.1 → 1.10.1

package/cli/src/build.mjs

@@ -1,447 +1,447 @@
-// muscat-pk build — bundle ui/content.tsx into dist/content.js, stage
-// manifest.json and assets/ for distribution, and zip dist/ into a
-// distributable ZIP (skip with --no-zip).
-//
-// sandbox.html is generated by the CLI — plugin authors never manage it.
-// The import map always reflects the current plugin-ui entry set, so users
-// don't have to update it when the runtime adds new entries.
-//
-// The plugin author's `@rainbow-robotics/plugin-ui` and React imports are left external.
-// Muscat/robot and preview-host provide those modules through a sandbox import
-// map, so plugin ZIPs do not carry the UI runtime.
-import { chmodSync, cpSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import { basename, dirname, resolve } from "node:path";
-import { createInterface } from "node:readline/promises";
-import { execSync, spawnSync } from "node:child_process";
-import { ensureDocker, findPluginRoot, hasBin, humanSize, log, parseArgs, prompt } from "./util.mjs";
-import { assertManifest, manifestRuntime } from "./manifest.mjs";
-
-// Find a usable JS runtime for running vite as a subprocess.
-// In binary (Bun) mode, try `bun` first (it can run vite directly), then node.
-// In node mode, use the current process.
-function findJsRuntime() {
-  if (typeof Bun === "undefined") return { bin: process.execPath, isBun: false };
-  for (const c of ["bun", "node", "nodejs"]) {
-    if (hasBin(c)) return { bin: c, isBun: c === "bun" };
-  }
-  return null;
-}
-
-// Resolve vite bin path from the plugin root, hoisting-aware.
-function findViteBin(pluginRoot) {
-  try {
-    const req = createRequire(resolve(pluginRoot, "package.json"));
-    const vitePkg = req.resolve("vite/package.json");
-    return resolve(dirname(vitePkg), "bin", "vite.js");
-  } catch {
-    return null;
-  }
-}
-
-// Run vite build in the plugin project. Without a JS runtime (binary CLI, no Node.js) it asks
-// whether to build the plugin without its UI and returns false on yes; throws on no or if vite is missing.
-async function runViteBuild(pluginRoot, { mode = "production" } = {}) {
-  const runtime = findJsRuntime();
-  if (!runtime) {
-    log.warn("Node.js 20+ (or Bun) not found — the UI cannot be built and will not be in the plugin.");
-    const answer = await prompt("  Build the plugin without its UI? [y/N]: ", "n");
-    if (answer.toLowerCase() !== "y")
-      throw new Error("build cancelled. Install Node.js 20+ (https://nodejs.org), run `npm install` in the plugin, then build again.");
-    return false;
-  }
-  const viteBin = findViteBin(pluginRoot);
-  if (!viteBin || !existsSync(viteBin)) {
-    throw new Error(
-      "vite not found in this plugin's node_modules.\n" +
-      `  Run: npm install  (inside ${pluginRoot})`,
-    );
-  }
-
-  log.step(`vite build (mode: ${mode})`);
-  // bun can run vite directly; node needs the explicit bin path
-  const args = runtime.isBun ? ["run", viteBin, "build", "--mode", mode]
-                              : [viteBin, "build", "--mode", mode];
-  const r = spawnSync(runtime.bin, args, { cwd: pluginRoot, stdio: "inherit" });
-  if (r.status !== 0) throw new Error("vite build failed");
-  return true;
-}
-
-// function isMainBranch() {
-//   const r = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
-//   const branch = r.stdout?.trim();
-//   return branch === "main" || branch === "master";
-// }
-
-// For ros2 plugins, compile the colcon workspace inside the Jazzy + Python 3.12 container.
-// rclpy: arch-agnostic (pure Python) → dist/ros2_ws/install/ (built once)
-// rclcpp: arch-specific C++ binaries → dist/ros2_ws/install-{arch}/ per arch
-// Cross-arch C++ builds run inside an emulated container. Docker Desktop ships the
-// emulation; native Linux needs binfmt/QEMU — check up front so the error says so.
-function assertCanBuildArch(arch, dockerPlatform) {
-  const info = spawnSync("docker", ["info", "--format", "{{.Architecture}}"], { encoding: "utf8" });
-  const host = { x86_64: "amd64", aarch64: "arm64", arm64: "arm64" }[(info.stdout || "").trim()] ?? "";
-  if (arch === host) return;
-  const r = spawnSync("docker", ["run", "--rm", "--platform", dockerPlatform, "ubuntu:24.04", "true"], { stdio: "ignore" });
-  if (r.status === 0) return;
-  throw new Error(
-    `can't build ${arch} on this ${host || "machine"}: Docker has no ${arch} emulation.\n` +
-    `  enable it once:  docker run --privileged --rm tonistiigi/binfmt --install ${arch}\n` +
-    `  or build only this machine's arch:  muscat-pk build --arch ${host || "<arch>"}`,
-  );
-}
-
-export async function exportRos2Build(root, archs = ["amd64", "arm64"]) {
-  if (manifestRuntime(root) !== "ros2") return;
-  const { assertDockerReady, ensureImage, colconBuild, ROS2_DEV_IMAGE, ARCH_DOCKER_PLATFORM } = await import("./ros2.mjs");
-  assertDockerReady();
-
-  const manifest = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8"));
-  if (manifest.runtime?.rosClient === "rclcpp") {
-    // C++ ROS2: compile per arch so each robot picks the right install-{arch}/
-    for (const arch of archs) {
-      const dockerPlatform = ARCH_DOCKER_PLATFORM[arch];
-      if (!dockerPlatform) throw new Error(`unknown arch '${arch}'`);
-      assertCanBuildArch(arch, dockerPlatform);
-      await ensureImage(`${ROS2_DEV_IMAGE}-${arch}`, { platform: dockerPlatform });
-      colconBuild(root, { symlink: false, arch });
-      log.ok(`dist/ros2_ws/install-${arch}/ ready`);
-    }
-  } else {
-    // rclpy / pure Python: arch-agnostic, build once
-    await ensureImage();
-    colconBuild(root, { symlink: false });
-    log.ok("dist/ros2_ws/install/ ready");
-  }
-}
-
-// For cpp plugins, compile cpp/ inside the Ubuntu container (Release) per arch
-// and copy each binary into dist/{arch}/{entry} so the ZIP carries relocatable
-// robot-compatible executables.
-export async function exportCppBuild(root, distDir, archs = ["amd64", "arm64"]) {
-  if (manifestRuntime(root) !== "cpp") return;
-  const { assertDockerReady, ensureImage, cmakeBuild, CPP_DEV_IMAGE, ARCH_DOCKER_PLATFORM } = await import("./cpp.mjs");
-  assertDockerReady();
-
-  const entry = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime?.entry;
-  if (!entry) throw new Error("manifest.json runtime.entry is required for cpp (the built executable name)");
-
-  for (const arch of archs) {
-    const dockerPlatform = ARCH_DOCKER_PLATFORM[arch];
-    if (!dockerPlatform) throw new Error(`unknown arch '${arch}'`);
-    assertCanBuildArch(arch, dockerPlatform);
-    await ensureImage(`${CPP_DEV_IMAGE}-${arch}`, { platform: dockerPlatform });
-    cmakeBuild(root, { buildType: "Release", arch });
-    const built = resolve(root, `cpp/build-${arch}`, entry);
-    if (!existsSync(built)) {
-      throw new Error(`cpp/build-${arch}/${entry} not found — the CMake target name must equal runtime.entry`);
-    }
-    const archDir = resolve(distDir, arch);
-    mkdirSync(archDir, { recursive: true });
-    const dest = resolve(archDir, entry);
-    copyFileSync(built, dest);
-    chmodSync(dest, 0o755);
-    const libDir = resolve(root, `cpp/build-${arch}`, "lib");
-    if (existsSync(libDir)) cpSync(libDir, resolve(archDir, "lib"), { recursive: true, verbatimSymlinks: true });
-    log.ok(`cpp binary → dist/${arch}/${entry}${existsSync(libDir) ? " (+ lib/)" : ""}`);
-  }
-}
-
-const PRERELEASE_RE = /\.(dev|a|b|rc|alpha|beta)\d*/i;
-
-function isPrerelease(version) {
-  return PRERELEASE_RE.test(version);
-}
-
-// Resolve the latest version of a PyPI package.
-// stableOnly=true → skips pre-release (dev/a/b/rc) versions.
-async function latestPypiVersion(pkg, { stableOnly = false } = {}) {
-  const res = await fetch(`https://pypi.org/pypi/${pkg}/json`, {
-    signal: new AbortController().signal.timeout(5000),
-  });
-  if (!res.ok) throw new Error(`pypi ${pkg}: ${res.status}`);
-  const data = await res.json();
-
-  if (!stableOnly) return data.info.version;
-
-  // data.info.version is latest stable when stable releases exist.
-  // If it's still a pre-release, scan all releases for the newest stable.
-  if (!isPrerelease(data.info.version)) return data.info.version;
-
-  const stable = Object.keys(data.releases)
-    .filter((v) => !isPrerelease(v))
-    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
-    .at(-1);
-
-  if (stable) return stable;
-
-  // No stable release exists — fall back with a warning.
-  log.warn(`  ${pkg}: no stable release found, using ${data.info.version}`);
-  return data.info.version;
-}
-
-// Pin unpinned (no version specifier) entries in requirements.txt to the
-// latest PyPI release. Runs on explicit `build` only — keeps the shipped
-// plugin reproducible without churning the source file on every dev rebuild.
-// stableOnly=true is used on main-branch builds to avoid shipping dev versions.
-export async function pinRequirements(root, { stableOnly = false } = {}) {
-  const reqPath = resolve(root, "requirements.txt");
-  if (!existsSync(reqPath)) return;
-
-  const lines = readFileSync(reqPath, "utf8").split("\n");
-  const out = [];
-  let pinned = 0;
-  for (const line of lines) {
-    const name = line.trim();
-    // skip blanks, comments, and already-specified versions
-    if (!name || name.startsWith("#") || /[=<>~!]/.test(name)) {
-      out.push(line);
-      continue;
-    }
-    try {
-      const v = await latestPypiVersion(name, { stableOnly });
-      out.push(`${name}==${v}`);
-      pinned++;
-      log.info(`  pinned ${name}==${v}`);
-    } catch {
-      out.push(line);
-      log.warn(`  could not resolve ${name} (offline?) — left unpinned`);
-    }
-  }
-  if (pinned > 0) writeFileSync(reqPath, out.join("\n"));
-}
-
-export async function buildPlugin({ root, minify = false } = {}) {
-  const pluginRoot = root ?? findPluginRoot();
-  assertManifest(pluginRoot);
-  const distDir = resolve(pluginRoot, "dist");
-  try {
-    rmSync(distDir, { recursive: true, force: true });
-  } catch (err) {
-    if (err?.code !== "EACCES" && err?.code !== "EPERM") throw err;
-    // 이전 버전이 컨테이너를 root로 돌려 남긴 dist/ — 한 번만 정리하면 된다
-    throw new Error(
-      `Permission denied when deleting dist/ (${err.path ?? distDir}).\n` +
-      `The previous build left files owned by root. Please clean it up once:\n` +
-      `  sudo rm -rf ${distDir}`,
-    );
-  }
-  mkdirSync(distDir, { recursive: true });
-
-  const manifest = JSON.parse(readFileSync(resolve(pluginRoot, "manifest.json"), "utf8"));
-  const uiDir = resolve(pluginRoot, "ui");
-  const declaredUiEntries = [...new Set(
-    (manifest.contributes ?? []).map((c) => c.ui).filter(Boolean)
-  )];
-  // Validate each declared UI entry has a matching source file
-  for (const entry of declaredUiEntries) {
-    const exists = [".tsx", ".ts", ".jsx", ".js"].some(
-      (ext) => existsSync(resolve(uiDir, entry + ext))
-    );
-    if (!exists)
-      throw new Error(
-        `contributes declares ui "${entry}" but ui/${entry}.tsx (or .ts/.jsx/.js) does not exist.`
-      );
-  }
-  const hasUiFiles = existsSync(uiDir) && readdirSync(uiDir).some((f) => /\.[tj]sx?$/.test(f));
-  // A backend-only plugin (no contributes) ships no UI, so leftover ui/ files are not built either.
-  let uiBuilt = true;
-  if (declaredUiEntries.length > 0 || (hasUiFiles && manifest.contributes?.length > 0)) {
-    uiBuilt = await runViteBuild(pluginRoot, { mode: minify ? "production" : "development" });
-  }
-
-  // Stage distribution files.
-  const manifestSrc = resolve(pluginRoot, "manifest.json");
-  if (existsSync(manifestSrc)) copyFileSync(manifestSrc, resolve(distDir, "manifest.json"));
-  // Built without the UI: ship it as a backend-only plugin so the host lists no screen it cannot load.
-  if (!uiBuilt) {
-    const { contributes, ...backendOnly } = manifest;
-    writeFileSync(resolve(distDir, "manifest.json"), JSON.stringify(backendOnly, null, 2) + "\n");
-    log.warn(`packaged without UI: dropped ${contributes.length} screen area(s) from dist/manifest.json`);
-  }
-
-  // No sandbox.html: the host dynamically imports dist/{ui}.js directly as a
-  // plain ESM module (see @rainbow-robotics/plugin-ui/host) — no iframe.
-
-  const assetsSrc = resolve(pluginRoot, "assets");
-  if (existsSync(assetsSrc)) {
-    cpSync(assetsSrc, resolve(distDir, "assets"), { recursive: true });
-  }
-
-  // README.md, README.[lang].md, CHANGELOG.md → dist/
-  for (const f of readdirSync(pluginRoot)) {
-    if (/^README(\.[a-z]{2}(-[A-Z]{2})?)?\.md$/i.test(f) || /^CHANGELOG\.md$/i.test(f)) {
-      copyFileSync(resolve(pluginRoot, f), resolve(distDir, f));
-    }
-  }
-
-  // Backend runtime files — copy entire py/ into dist/, then requirements.txt from root.
-  const pySrc = resolve(pluginRoot, "py");
-  if (existsSync(pySrc)) {
-    cpSync(pySrc, distDir, { recursive: true });
-  }
-  const rootReqs = resolve(pluginRoot, "requirements.txt");
-  if (existsSync(rootReqs)) {
-    copyFileSync(rootReqs, resolve(distDir, "requirements.txt"));
-  }
-
-  log.ok(`built → ${distDir}`);
-  return { pluginRoot, distDir, uiBuilt };
-}
-
-function dirSize(dir, skip = []) {
-  if (!existsSync(dir)) return 0;
-  let total = 0;
-  for (const entry of readdirSync(dir)) {
-    if (skip.includes(entry)) continue;
-    const full = resolve(dir, entry);
-    const st = statSync(full);
-    total += st.isDirectory() ? dirSize(full) : st.size;
-  }
-  return total;
-}
-
-// Read the uncompressed byte total of a .whl (zip) file by parsing its central
-// directory — no external library needed, no actual extraction.
-
-// installedSize = "이 플러그인 하나를 지우면 되찾는 용량"
-//   = dist/(wheels/ 제외)
-// ros2_ws/install* 은 이제 dist/ 안에 있으므로 별도 합산 불필요.
-// 휠은 로봇 공유 스토어(store/py/)에 언팩되므로 포함하지 않는다.
-function calcInstalledSize(pluginRoot) {
-  const distDir = resolve(pluginRoot, "dist");
-
-  const installedSize = dirSize(distDir, ["wheels"]);
-
-  // Write to root manifest.json
-  const rootManifestPath = resolve(pluginRoot, "manifest.json");
-  if (existsSync(rootManifestPath)) {
-    const m = JSON.parse(readFileSync(rootManifestPath, "utf8"));
-    m.installedSize = installedSize;
-    writeFileSync(rootManifestPath, JSON.stringify(m, null, 2) + "\n");
-  }
-
-  // Re-stage dist/manifest.json so the ZIP carries the updated value
-  const distManifestPath = resolve(distDir, "manifest.json");
-  if (existsSync(distManifestPath)) {
-    const m = JSON.parse(readFileSync(distManifestPath, "utf8"));
-    m.installedSize = installedSize;
-    writeFileSync(distManifestPath, JSON.stringify(m, null, 2) + "\n");
-  }
-
-  log.ok(`installedSize → ${humanSize(installedSize)}`);
-}
-
-// Zip dist/ into a distributable ZIP with a size report.
-// ros2_ws/install* is now inside dist/, so only "dist" is needed.
-function packZip(pluginRoot) {
-  const manifest = JSON.parse(readFileSync(resolve(pluginRoot, "manifest.json"), "utf8"));
-  const zipName = `${basename(pluginRoot)}-${manifest.version || "0.0.0"}.zip`;
-  const zipPath = resolve(pluginRoot, zipName);
-  rmSync(zipPath, { force: true });
-
-  const entries = ["dist"];
-
-  log.step(`packing ${entries.join(", ")} → ${zipName}`);
-  try {
-    execSync(`zip -r -q "${zipPath}" ${entries.map((e) => `"${e}"`).join(" ")}`, {
-      cwd: pluginRoot,
-      stdio: "inherit",
-    });
-  } catch {
-    throw new Error("`zip` not found. Install zip or pack manually.");
-  }
-
-  const zipBytes = statSync(zipPath).size;
-  log.ok(`${zipName}   ${humanSize(zipBytes)}`);
-  for (const e of entries) {
-    const full = resolve(pluginRoot, e);
-    const size = statSync(full).isDirectory() ? dirSize(full) : statSync(full).size;
-    log.info(`  ├─ ${e}   ${humanSize(size)}`);
-  }
-}
-
-/**
- * Ask which target arch(es) to build for.
- * Non-TTY (CI): both, same as the prompt default.
- * @returns {Promise<string[]>} e.g. ['amd64'] | ['arm64'] | ['amd64','arm64']
- */
-async function promptArch(args = []) {
-  const archFlag = parseArgs(args).arch ?? null;
-  if (archFlag) {
-    if (archFlag === "both") return ["amd64", "arm64"];
-    if (archFlag === "amd64" || archFlag === "x86_64") return ["amd64"];
-    if (archFlag === "arm64" || archFlag === "aarch64") return ["arm64"];
-    throw new Error(`unknown --arch value '${archFlag}' (valid: amd64, arm64, both)`);
-  }
-  // Same default as the prompt: the target is the robot, not this machine
-  // (node's os.arch() is x64 under Rosetta on an arm64 Mac anyway).
-  if (!process.stdin.isTTY) {
-    log.info("arch auto-selected (non-TTY): both");
-    return ["amd64", "arm64"];
-  }
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  process.stdout.write(
-    "\n  Target arch:\n" +
-    "    1) amd64\n" +
-    "    2) arm64\n" +
-    "    3) Both (fat ZIP)\n",
-  );
-  const answer = (await rl.question("  Select [1/2/3, default: 3]: ")).trim() || "3";
-  rl.close();
-  if (answer === "1") return ["amd64"];
-  if (answer === "2") return ["arm64"];
-  return ["amd64", "arm64"];
-}
-
-async function promptVersion(root) {
-  if (!process.stdin.isTTY) return;
-  const manifestPath = resolve(root, "manifest.json");
-  if (!existsSync(manifestPath)) return;
-  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
-  const current = manifest.version ?? "1.0.0";
-
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const input = (await rl.question(`  Version (current: ${current}, leave blank to keep): `)).trim();
-  rl.close();
-
-  if (!input) return;
-  manifest.version = input;
-  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
-  log.ok(`manifest.json version → ${input}`);
-}
-
-export async function runBuild(args) {
-  const noZip = args.includes("--no-zip");
-  const noLock = args.includes("--no-lock");
-  const root = findPluginRoot();
-  const rt = manifestRuntime(root);
-
-  // All runtimes except "none" need Docker
-  if (rt !== "none") ensureDocker();
-
-  await promptVersion(root);
-  const archs = await promptArch(args);
-  // Drop a previous ZIP of this version so a failed build can't leave a stale one to upload.
-  const version = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).version || "0.0.0";
-  rmSync(resolve(root, `${basename(root)}-${version}.zip`), { force: true });
-
-  const { pluginRoot, distDir } = await buildPlugin({ root, minify: true });
-
-  // python / rclpy: lock + wheel vendor in Ubuntu 24.04 container
-  if (!noLock) {
-    const manifest = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime ?? {};
-    const needsLock =
-      manifest.type === "python" ||
-      (manifest.type === "ros2" && manifest.rosClient === "rclpy");
-    if (needsLock) {
-      const { lockAndVendor } = await import("./python.mjs");
-      await lockAndVendor(pluginRoot, archs);
-    }
-  }
-
-  await exportRos2Build(root, archs);
-  await exportCppBuild(root, distDir, archs);
-  calcInstalledSize(pluginRoot);
-  if (!noZip) packZip(pluginRoot);
-}
+// muscat-pk build — bundle ui/content.tsx into dist/content.js, stage
+// manifest.json and assets/ for distribution, and zip dist/ into a
+// distributable ZIP (skip with --no-zip).
+//
+// sandbox.html is generated by the CLI — plugin authors never manage it.
+// The import map always reflects the current plugin-ui entry set, so users
+// don't have to update it when the runtime adds new entries.
+//
+// The plugin author's `@rainbow-robotics/plugin-ui` and React imports are left external.
+// Muscat/robot and preview-host provide those modules through a sandbox import
+// map, so plugin ZIPs do not carry the UI runtime.
+import { chmodSync, cpSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { execSync, spawnSync } from "node:child_process";
+import { ensureDocker, findPluginRoot, hasBin, humanSize, log, parseArgs, prompt } from "./util.mjs";
+import { assertManifest, manifestRuntime } from "./manifest.mjs";
+
+// Find a usable JS runtime for running vite as a subprocess.
+// In binary (Bun) mode, try `bun` first (it can run vite directly), then node.
+// In node mode, use the current process.
+function findJsRuntime() {
+  if (typeof Bun === "undefined") return { bin: process.execPath, isBun: false };
+  for (const c of ["bun", "node", "nodejs"]) {
+    if (hasBin(c)) return { bin: c, isBun: c === "bun" };
+  }
+  return null;
+}
+
+// Resolve vite bin path from the plugin root, hoisting-aware.
+function findViteBin(pluginRoot) {
+  try {
+    const req = createRequire(resolve(pluginRoot, "package.json"));
+    const vitePkg = req.resolve("vite/package.json");
+    return resolve(dirname(vitePkg), "bin", "vite.js");
+  } catch {
+    return null;
+  }
+}
+
+// Run vite build in the plugin project. Without a JS runtime (binary CLI, no Node.js) it asks
+// whether to build the plugin without its UI and returns false on yes; throws on no or if vite is missing.
+async function runViteBuild(pluginRoot, { mode = "production" } = {}) {
+  const runtime = findJsRuntime();
+  if (!runtime) {
+    log.warn("Node.js 20+ (or Bun) not found — the UI cannot be built and will not be in the plugin.");
+    const answer = await prompt("  Build the plugin without its UI? [y/N]: ", "n");
+    if (answer.toLowerCase() !== "y")
+      throw new Error("build cancelled. Install Node.js 20+ (https://nodejs.org), run `npm install` in the plugin, then build again.");
+    return false;
+  }
+  const viteBin = findViteBin(pluginRoot);
+  if (!viteBin || !existsSync(viteBin)) {
+    throw new Error(
+      "vite not found in this plugin's node_modules.\n" +
+      `  Run: npm install  (inside ${pluginRoot})`,
+    );
+  }
+
+  log.step(`vite build (mode: ${mode})`);
+  // bun can run vite directly; node needs the explicit bin path
+  const args = runtime.isBun ? ["run", viteBin, "build", "--mode", mode]
+                              : [viteBin, "build", "--mode", mode];
+  const r = spawnSync(runtime.bin, args, { cwd: pluginRoot, stdio: "inherit" });
+  if (r.status !== 0) throw new Error("vite build failed");
+  return true;
+}
+
+// function isMainBranch() {
+//   const r = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
+//   const branch = r.stdout?.trim();
+//   return branch === "main" || branch === "master";
+// }
+
+// For ros2 plugins, compile the colcon workspace inside the Jazzy + Python 3.12 container.
+// rclpy: arch-agnostic (pure Python) → dist/ros2_ws/install/ (built once)
+// rclcpp: arch-specific C++ binaries → dist/ros2_ws/install-{arch}/ per arch
+// Cross-arch C++ builds run inside an emulated container. Docker Desktop ships the
+// emulation; native Linux needs binfmt/QEMU — check up front so the error says so.
+function assertCanBuildArch(arch, dockerPlatform) {
+  const info = spawnSync("docker", ["info", "--format", "{{.Architecture}}"], { encoding: "utf8" });
+  const host = { x86_64: "amd64", aarch64: "arm64", arm64: "arm64" }[(info.stdout || "").trim()] ?? "";
+  if (arch === host) return;
+  const r = spawnSync("docker", ["run", "--rm", "--platform", dockerPlatform, "ubuntu:24.04", "true"], { stdio: "ignore" });
+  if (r.status === 0) return;
+  throw new Error(
+    `can't build ${arch} on this ${host || "machine"}: Docker has no ${arch} emulation.\n` +
+    `  enable it once:  docker run --privileged --rm tonistiigi/binfmt --install ${arch}\n` +
+    `  or build only this machine's arch:  muscat-pk build --arch ${host || "<arch>"}`,
+  );
+}
+
+export async function exportRos2Build(root, archs = ["amd64", "arm64"]) {
+  if (manifestRuntime(root) !== "ros2") return;
+  const { assertDockerReady, ensureImage, colconBuild, ROS2_DEV_IMAGE, ARCH_DOCKER_PLATFORM } = await import("./ros2.mjs");
+  assertDockerReady();
+
+  const manifest = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8"));
+  if (manifest.runtime?.rosClient === "rclcpp") {
+    // C++ ROS2: compile per arch so each robot picks the right install-{arch}/
+    for (const arch of archs) {
+      const dockerPlatform = ARCH_DOCKER_PLATFORM[arch];
+      if (!dockerPlatform) throw new Error(`unknown arch '${arch}'`);
+      assertCanBuildArch(arch, dockerPlatform);
+      await ensureImage(`${ROS2_DEV_IMAGE}-${arch}`, { platform: dockerPlatform });
+      colconBuild(root, { symlink: false, arch });
+      log.ok(`dist/ros2_ws/install-${arch}/ ready`);
+    }
+  } else {
+    // rclpy / pure Python: arch-agnostic, build once
+    await ensureImage();
+    colconBuild(root, { symlink: false });
+    log.ok("dist/ros2_ws/install/ ready");
+  }
+}
+
+// For cpp plugins, compile cpp/ inside the Ubuntu container (Release) per arch
+// and copy each binary into dist/{arch}/{entry} so the ZIP carries relocatable
+// robot-compatible executables.
+export async function exportCppBuild(root, distDir, archs = ["amd64", "arm64"]) {
+  if (manifestRuntime(root) !== "cpp") return;
+  const { assertDockerReady, ensureImage, cmakeBuild, CPP_DEV_IMAGE, ARCH_DOCKER_PLATFORM } = await import("./cpp.mjs");
+  assertDockerReady();
+
+  const entry = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime?.entry;
+  if (!entry) throw new Error("manifest.json runtime.entry is required for cpp (the built executable name)");
+
+  for (const arch of archs) {
+    const dockerPlatform = ARCH_DOCKER_PLATFORM[arch];
+    if (!dockerPlatform) throw new Error(`unknown arch '${arch}'`);
+    assertCanBuildArch(arch, dockerPlatform);
+    await ensureImage(`${CPP_DEV_IMAGE}-${arch}`, { platform: dockerPlatform });
+    cmakeBuild(root, { buildType: "Release", arch });
+    const built = resolve(root, `cpp/build-${arch}`, entry);
+    if (!existsSync(built)) {
+      throw new Error(`cpp/build-${arch}/${entry} not found — the CMake target name must equal runtime.entry`);
+    }
+    const archDir = resolve(distDir, arch);
+    mkdirSync(archDir, { recursive: true });
+    const dest = resolve(archDir, entry);
+    copyFileSync(built, dest);
+    chmodSync(dest, 0o755);
+    const libDir = resolve(root, `cpp/build-${arch}`, "lib");
+    if (existsSync(libDir)) cpSync(libDir, resolve(archDir, "lib"), { recursive: true, verbatimSymlinks: true });
+    log.ok(`cpp binary → dist/${arch}/${entry}${existsSync(libDir) ? " (+ lib/)" : ""}`);
+  }
+}
+
+const PRERELEASE_RE = /\.(dev|a|b|rc|alpha|beta)\d*/i;
+
+function isPrerelease(version) {
+  return PRERELEASE_RE.test(version);
+}
+
+// Resolve the latest version of a PyPI package.
+// stableOnly=true → skips pre-release (dev/a/b/rc) versions.
+async function latestPypiVersion(pkg, { stableOnly = false } = {}) {
+  const res = await fetch(`https://pypi.org/pypi/${pkg}/json`, {
+    signal: new AbortController().signal.timeout(5000),
+  });
+  if (!res.ok) throw new Error(`pypi ${pkg}: ${res.status}`);
+  const data = await res.json();
+
+  if (!stableOnly) return data.info.version;
+
+  // data.info.version is latest stable when stable releases exist.
+  // If it's still a pre-release, scan all releases for the newest stable.
+  if (!isPrerelease(data.info.version)) return data.info.version;
+
+  const stable = Object.keys(data.releases)
+    .filter((v) => !isPrerelease(v))
+    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+    .at(-1);
+
+  if (stable) return stable;
+
+  // No stable release exists — fall back with a warning.
+  log.warn(`  ${pkg}: no stable release found, using ${data.info.version}`);
+  return data.info.version;
+}
+
+// Pin unpinned (no version specifier) entries in requirements.txt to the
+// latest PyPI release. Runs on explicit `build` only — keeps the shipped
+// plugin reproducible without churning the source file on every dev rebuild.
+// stableOnly=true is used on main-branch builds to avoid shipping dev versions.
+export async function pinRequirements(root, { stableOnly = false } = {}) {
+  const reqPath = resolve(root, "requirements.txt");
+  if (!existsSync(reqPath)) return;
+
+  const lines = readFileSync(reqPath, "utf8").split("\n");
+  const out = [];
+  let pinned = 0;
+  for (const line of lines) {
+    const name = line.trim();
+    // skip blanks, comments, and already-specified versions
+    if (!name || name.startsWith("#") || /[=<>~!]/.test(name)) {
+      out.push(line);
+      continue;
+    }
+    try {
+      const v = await latestPypiVersion(name, { stableOnly });
+      out.push(`${name}==${v}`);
+      pinned++;
+      log.info(`  pinned ${name}==${v}`);
+    } catch {
+      out.push(line);
+      log.warn(`  could not resolve ${name} (offline?) — left unpinned`);
+    }
+  }
+  if (pinned > 0) writeFileSync(reqPath, out.join("\n"));
+}
+
+export async function buildPlugin({ root, minify = false } = {}) {
+  const pluginRoot = root ?? findPluginRoot();
+  assertManifest(pluginRoot);
+  const distDir = resolve(pluginRoot, "dist");
+  try {
+    rmSync(distDir, { recursive: true, force: true });
+  } catch (err) {
+    if (err?.code !== "EACCES" && err?.code !== "EPERM") throw err;
+    // 이전 버전이 컨테이너를 root로 돌려 남긴 dist/ — 한 번만 정리하면 된다
+    throw new Error(
+      `Permission denied when deleting dist/ (${err.path ?? distDir}).\n` +
+      `The previous build left files owned by root. Please clean it up once:\n` +
+      `  sudo rm -rf ${distDir}`,
+    );
+  }
+  mkdirSync(distDir, { recursive: true });
+
+  const manifest = JSON.parse(readFileSync(resolve(pluginRoot, "manifest.json"), "utf8"));
+  const uiDir = resolve(pluginRoot, "ui");
+  const declaredUiEntries = [...new Set(
+    (manifest.contributes ?? []).map((c) => c.ui).filter(Boolean)
+  )];
+  // Validate each declared UI entry has a matching source file
+  for (const entry of declaredUiEntries) {
+    const exists = [".tsx", ".ts", ".jsx", ".js"].some(
+      (ext) => existsSync(resolve(uiDir, entry + ext))
+    );
+    if (!exists)
+      throw new Error(
+        `contributes declares ui "${entry}" but ui/${entry}.tsx (or .ts/.jsx/.js) does not exist.`
+      );
+  }
+  const hasUiFiles = existsSync(uiDir) && readdirSync(uiDir).some((f) => /\.[tj]sx?$/.test(f));
+  // A backend-only plugin (no contributes) ships no UI, so leftover ui/ files are not built either.
+  let uiBuilt = true;
+  if (declaredUiEntries.length > 0 || (hasUiFiles && manifest.contributes?.length > 0)) {
+    uiBuilt = await runViteBuild(pluginRoot, { mode: minify ? "production" : "development" });
+  }
+
+  // Stage distribution files.
+  const manifestSrc = resolve(pluginRoot, "manifest.json");
+  if (existsSync(manifestSrc)) copyFileSync(manifestSrc, resolve(distDir, "manifest.json"));
+  // Built without the UI: ship it as a backend-only plugin so the host lists no screen it cannot load.
+  if (!uiBuilt) {
+    const { contributes, ...backendOnly } = manifest;
+    writeFileSync(resolve(distDir, "manifest.json"), JSON.stringify(backendOnly, null, 2) + "\n");
+    log.warn(`packaged without UI: dropped ${contributes.length} screen area(s) from dist/manifest.json`);
+  }
+
+  // No sandbox.html: the host dynamically imports dist/{ui}.js directly as a
+  // plain ESM module (see @rainbow-robotics/plugin-ui/host) — no iframe.
+
+  const assetsSrc = resolve(pluginRoot, "assets");
+  if (existsSync(assetsSrc)) {
+    cpSync(assetsSrc, resolve(distDir, "assets"), { recursive: true });
+  }
+
+  // README.md, README.[lang].md, CHANGELOG.md → dist/
+  for (const f of readdirSync(pluginRoot)) {
+    if (/^README(\.[a-z]{2}(-[A-Z]{2})?)?\.md$/i.test(f) || /^CHANGELOG\.md$/i.test(f)) {
+      copyFileSync(resolve(pluginRoot, f), resolve(distDir, f));
+    }
+  }
+
+  // Backend runtime files — copy entire py/ into dist/, then requirements.txt from root.
+  const pySrc = resolve(pluginRoot, "py");
+  if (existsSync(pySrc)) {
+    cpSync(pySrc, distDir, { recursive: true });
+  }
+  const rootReqs = resolve(pluginRoot, "requirements.txt");
+  if (existsSync(rootReqs)) {
+    copyFileSync(rootReqs, resolve(distDir, "requirements.txt"));
+  }
+
+  log.ok(`built → ${distDir}`);
+  return { pluginRoot, distDir, uiBuilt };
+}
+
+function dirSize(dir, skip = []) {
+  if (!existsSync(dir)) return 0;
+  let total = 0;
+  for (const entry of readdirSync(dir)) {
+    if (skip.includes(entry)) continue;
+    const full = resolve(dir, entry);
+    const st = statSync(full);
+    total += st.isDirectory() ? dirSize(full) : st.size;
+  }
+  return total;
+}
+
+// Read the uncompressed byte total of a .whl (zip) file by parsing its central
+// directory — no external library needed, no actual extraction.
+
+// installedSize = "이 플러그인 하나를 지우면 되찾는 용량"
+//   = dist/(wheels/ 제외)
+// ros2_ws/install* 은 이제 dist/ 안에 있으므로 별도 합산 불필요.
+// 휠은 로봇 공유 스토어(store/py/)에 언팩되므로 포함하지 않는다.
+function calcInstalledSize(pluginRoot) {
+  const distDir = resolve(pluginRoot, "dist");
+
+  const installedSize = dirSize(distDir, ["wheels"]);
+
+  // Write to root manifest.json
+  const rootManifestPath = resolve(pluginRoot, "manifest.json");
+  if (existsSync(rootManifestPath)) {
+    const m = JSON.parse(readFileSync(rootManifestPath, "utf8"));
+    m.installedSize = installedSize;
+    writeFileSync(rootManifestPath, JSON.stringify(m, null, 2) + "\n");
+  }
+
+  // Re-stage dist/manifest.json so the ZIP carries the updated value
+  const distManifestPath = resolve(distDir, "manifest.json");
+  if (existsSync(distManifestPath)) {
+    const m = JSON.parse(readFileSync(distManifestPath, "utf8"));
+    m.installedSize = installedSize;
+    writeFileSync(distManifestPath, JSON.stringify(m, null, 2) + "\n");
+  }
+
+  log.ok(`installedSize → ${humanSize(installedSize)}`);
+}
+
+// Zip dist/ into a distributable ZIP with a size report.
+// ros2_ws/install* is now inside dist/, so only "dist" is needed.
+function packZip(pluginRoot) {
+  const manifest = JSON.parse(readFileSync(resolve(pluginRoot, "manifest.json"), "utf8"));
+  const zipName = `${basename(pluginRoot)}-${manifest.version || "0.0.0"}.zip`;
+  const zipPath = resolve(pluginRoot, zipName);
+  rmSync(zipPath, { force: true });
+
+  const entries = ["dist"];
+
+  log.step(`packing ${entries.join(", ")} → ${zipName}`);
+  try {
+    execSync(`zip -r -q "${zipPath}" ${entries.map((e) => `"${e}"`).join(" ")}`, {
+      cwd: pluginRoot,
+      stdio: "inherit",
+    });
+  } catch {
+    throw new Error("`zip` not found. Install zip or pack manually.");
+  }
+
+  const zipBytes = statSync(zipPath).size;
+  log.ok(`${zipName}   ${humanSize(zipBytes)}`);
+  for (const e of entries) {
+    const full = resolve(pluginRoot, e);
+    const size = statSync(full).isDirectory() ? dirSize(full) : statSync(full).size;
+    log.info(`  ├─ ${e}   ${humanSize(size)}`);
+  }
+}
+
+/**
+ * Ask which target arch(es) to build for.
+ * Non-TTY (CI): both, same as the prompt default.
+ * @returns {Promise<string[]>} e.g. ['amd64'] | ['arm64'] | ['amd64','arm64']
+ */
+async function promptArch(args = []) {
+  const archFlag = parseArgs(args).arch ?? null;
+  if (archFlag) {
+    if (archFlag === "both") return ["amd64", "arm64"];
+    if (archFlag === "amd64" || archFlag === "x86_64") return ["amd64"];
+    if (archFlag === "arm64" || archFlag === "aarch64") return ["arm64"];
+    throw new Error(`unknown --arch value '${archFlag}' (valid: amd64, arm64, both)`);
+  }
+  // Same default as the prompt: the target is the robot, not this machine
+  // (node's os.arch() is x64 under Rosetta on an arm64 Mac anyway).
+  if (!process.stdin.isTTY) {
+    log.info("arch auto-selected (non-TTY): both");
+    return ["amd64", "arm64"];
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  process.stdout.write(
+    "\n  Target arch:\n" +
+    "    1) amd64\n" +
+    "    2) arm64\n" +
+    "    3) Both (fat ZIP)\n",
+  );
+  const answer = (await rl.question("  Select [1/2/3, default: 3]: ")).trim() || "3";
+  rl.close();
+  if (answer === "1") return ["amd64"];
+  if (answer === "2") return ["arm64"];
+  return ["amd64", "arm64"];
+}
+
+async function promptVersion(root) {
+  if (!process.stdin.isTTY) return;
+  const manifestPath = resolve(root, "manifest.json");
+  if (!existsSync(manifestPath)) return;
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const current = manifest.version ?? "1.0.0";
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const input = (await rl.question(`  Version (current: ${current}, leave blank to keep): `)).trim();
+  rl.close();
+
+  if (!input) return;
+  manifest.version = input;
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+  log.ok(`manifest.json version → ${input}`);
+}
+
+export async function runBuild(args) {
+  const noZip = args.includes("--no-zip");
+  const noLock = args.includes("--no-lock");
+  const root = findPluginRoot();
+  const rt = manifestRuntime(root);
+
+  // All runtimes except "none" need Docker
+  if (rt !== "none") ensureDocker();
+
+  await promptVersion(root);
+  const archs = await promptArch(args);
+  // Drop a previous ZIP of this version so a failed build can't leave a stale one to upload.
+  const version = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).version || "0.0.0";
+  rmSync(resolve(root, `${basename(root)}-${version}.zip`), { force: true });
+
+  const { pluginRoot, distDir } = await buildPlugin({ root, minify: true });
+
+  // python / rclpy: lock + wheel vendor in Ubuntu 24.04 container
+  if (!noLock) {
+    const manifest = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime ?? {};
+    const needsLock =
+      manifest.type === "python" ||
+      (manifest.type === "ros2" && manifest.rosClient === "rclpy");
+    if (needsLock) {
+      const { lockAndVendor } = await import("./python.mjs");
+      await lockAndVendor(pluginRoot, archs);
+    }
+  }
+
+  await exportRos2Build(root, archs);
+  await exportCppBuild(root, distDir, archs);
+  calcInstalledSize(pluginRoot);
+  if (!noZip) packZip(pluginRoot);
+}