@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.4 → 0.1.2-dev.40

package/cli/src/build.mjs

@@ -1,5 +1,6 @@
-// muscat-pk build — bundle src/content.tsx into dist/content.js and stage
-// manifest.json and assets/ for distribution.
+// 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
@@ -8,12 +9,209 @@
 // 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 { cpSync, copyFileSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { buildWithFallback } from "./esbuild.mjs";
-import { findPluginRoot, log } from "./util.mjs";
+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 } from "./util.mjs";
+import { assertManifest, manifestRuntime } from "./manifest.mjs";
 
-const SANDBOX_HTML = `<!doctype html>
+// 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", "node20", "node18"]) {
+    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. Throws if runtime or vite not found.
+function runViteBuild(pluginRoot, { mode = "production" } = {}) {
+  const runtime = findJsRuntime();
+  if (!runtime) {
+    throw new Error(
+      "Node.js 20+ (or Bun) is required to build the plugin UI.\n" +
+      "  Install Node.js: https://nodejs.org\n" +
+      "  Then run: npm install  (inside the plugin directory)",
+    );
+  }
+  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");
+}
+
+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
+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");
+  try {
+    assertDockerReady();
+  } catch (e) {
+    log.warn(`ros2 build skipped: ${e.message}`);
+    return;
+  }
+
+  const manifest = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8"));
+  const rosClient = manifest.runtime?.rosClient;
+
+  if (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) { log.warn(`unknown arch '${arch}' — skipped`); continue; }
+      const archImage = `${ROS2_DEV_IMAGE}-${arch}`;
+      await ensureImage(archImage, { 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. rb-runtime prefers dist/{arch}/ and falls back
+// to dist/{entry} (legacy). Skipped (with a warning) if Docker is unavailable.
+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");
+  try {
+    assertDockerReady();
+  } catch (e) {
+    log.warn(`cpp build skipped: ${e.message}`);
+    return;
+  }
+
+  const entry = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime?.entry;
+  if (!entry) {
+    log.warn("manifest.json runtime.entry not set — cpp build skipped");
+    return;
+  }
+
+  for (const arch of archs) {
+    // python과 동일하게 arch별 이미지를 빌드해야 --platform 불일치를 피할 수 있다.
+    const dockerPlatform = ARCH_DOCKER_PLATFORM[arch];
+    if (!dockerPlatform) { log.warn(`unknown arch '${arch}' — skipped`); continue; }
+    const archImage = `${CPP_DEV_IMAGE}-${arch}`;
+    await ensureImage(archImage, { platform: dockerPlatform });
+    cmakeBuild(root, { buildType: "Release", arch });
+    const buildDir = `cpp/build-${arch}`;
+    const built = resolve(root, buildDir, entry);
+    if (existsSync(built)) {
+      const archDir = resolve(distDir, arch);
+      mkdirSync(archDir, { recursive: true });
+      const dest = resolve(archDir, entry);
+      copyFileSync(built, dest);
+      chmodSync(dest, 0o755);
+      log.ok(`cpp binary → dist/${arch}/${entry}`);
+    } else {
+      log.warn(`cpp binary not found at ${buildDir}/${entry} — skipped for ${arch}`);
+    }
+  }
+}
+
+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: AbortSignal.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 const SANDBOX_HTML = `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
@@ -39,39 +237,20 @@ const SANDBOX_HTML = `<!doctype html>
 </html>
 `;
 
-const HOST_PROVIDED_EXTERNALS = [
-  "@rainbow-robotics/plugin-ui",
-  "@rainbow-robotics/plugin-ui/*",
-  "react",
-  "react/jsx-runtime",
-  "react/jsx-dev-runtime",
-  "react-dom",
-  "react-dom/*",
-];
-
 export async function buildPlugin({ root, minify = false } = {}) {
   const pluginRoot = root ?? findPluginRoot();
-  const entry = resolve(pluginRoot, "src/content.tsx");
-  if (!existsSync(entry)) {
-    throw new Error(`missing entry: ${entry}`);
-  }
+  assertManifest(pluginRoot);
   const distDir = resolve(pluginRoot, "dist");
   rmSync(distDir, { recursive: true, force: true });
   mkdirSync(distDir, { recursive: true });
 
-  log.step("bundling src/content.tsx → dist/content.js");
-  await buildWithFallback({
-    entryPoints: [entry],
-    outfile: resolve(distDir, "content.js"),
-    bundle: true,
-    format: "esm",
-    jsx: "automatic",
-    minify,
-    loader: { ".tsx": "tsx", ".ts": "ts", ".svg": "dataurl" },
-    define: { "process.env.NODE_ENV": JSON.stringify(minify ? "production" : "development") },
-    external: HOST_PROVIDED_EXTERNALS,
-    logLevel: "warning",
-  });
+  const manifest = JSON.parse(readFileSync(resolve(pluginRoot, "manifest.json"), "utf8"));
+  const contributesUi = (manifest.contributes ?? []).some((c) => c.ui);
+  const uiDir = resolve(pluginRoot, "ui");
+  const hasUiFiles = existsSync(uiDir) && readdirSync(uiDir).some((f) => /\.[tj]sx?$/.test(f));
+  if (contributesUi || hasUiFiles) {
+    runViteBuild(pluginRoot, { mode: minify ? "production" : "development" });
+  }
 
   // Stage distribution files.
   const manifestSrc = resolve(pluginRoot, "manifest.json");
@@ -80,16 +259,187 @@ export async function buildPlugin({ root, minify = false } = {}) {
   // Generate sandbox.html — plugin authors don't manage this file.
   writeFileSync(resolve(distDir, "sandbox.html"), SANDBOX_HTML, "utf8");
   log.step("generated dist/sandbox.html");
+
   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 };
 }
 
+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): auto-selects current machine arch.
+ * @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)`);
+  }
+  if (!process.stdin.isTTY) {
+    const { arch } = await import("node:os");
+    const machine = arch() === "arm64" ? "arm64" : "amd64";
+    log.info(`arch auto-selected (non-TTY): ${machine}`);
+    return [machine];
+  }
+  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 minify = args.includes("--minify");
-  await buildPlugin({ minify });
+  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);
+
+  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");
+      try {
+        await lockAndVendor(pluginRoot, archs);
+      } catch (e) {
+        log.warn(`python lock/vendor skipped: ${e.message}`);
+      }
+    }
+  }
+
+  await exportRos2Build(root, archs);
+  await exportCppBuild(root, distDir, archs);
+  calcInstalledSize(pluginRoot);
+  if (!noZip) packZip(pluginRoot);
 }

package/cli/src/check-package.mjs

@@ -1,28 +1,13 @@
-import { execFileSync } from "node:child_process";
-import { readdirSync, statSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
-const roots = [resolve(root, "cli"), resolve(root, "preview-host")];
-
-function* mjsFiles(dir) {
-  for (const entry of readdirSync(dir)) {
-    const full = resolve(dir, entry);
-    const stat = statSync(full);
-    if (stat.isDirectory()) {
-      if (entry === "dist" || entry === "runtime" || entry === "templates") {
-        continue;
-      }
-      yield* mjsFiles(full);
-    } else if (entry.endsWith(".mjs")) {
-      yield full;
-    }
-  }
-}
-
-for (const dir of roots) {
-  for (const file of mjsFiles(dir)) {
-    execFileSync(process.execPath, ["--check", file], { stdio: "inherit" });
-  }
+for (const dir of ["cli", "preview-host"]) {
+  if (!existsSync(resolve(root, dir))) continue;
+  execSync(
+    `find ${dir} -name '*.mjs' ! -path '*/dist/*' ! -path '*/runtime/*' ! -path '*/templates/*' -exec node --check {} +`,
+    { cwd: root, stdio: "inherit" },
+  );
 }

package/cli/src/cpp.mjs

@@ -0,0 +1,61 @@
+// Shared C++ Docker helpers (Ubuntu 24.04 + build-essential + cmake).
+// Matches the robot OS so the compiled binary is relocatable to the robot.
+// Used by dev:back (interactive dev loop) and build (export the binary into the ZIP).
+import { spawnSync } from "node:child_process";
+import { dirname } from "node:path";
+import { hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+
+export const CPP_DEV_IMAGE = "muscat-pk-cpp-dev";
+
+export function assertDockerReady() {
+  if (!hasBin("docker")) {
+    throw new Error("Docker not found. C++ builds need Docker (Ubuntu 24.04 + cmake container).");
+  }
+}
+
+/** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
+export async function ensureImage(image = CPP_DEV_IMAGE, { platform = null } = {}) {
+  const dockerfile = await resolveDockerfile("Dockerfile.cpp");
+  log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
+  const platformFlags = platform ? ["--platform", platform] : [];
+  const r = spawnSync(
+    "docker",
+    ["build", ...platformFlags, "-t", image, "-f", dockerfile, dirname(dockerfile)],
+    { stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error("docker build failed.");
+  pruneMuskatImages();
+}
+
+// Docker platform token for each target arch
+export const ARCH_DOCKER_PLATFORM = {
+  amd64: "linux/amd64",
+  arm64: "linux/arm64",
+};
+
+/**
+ * Configure + build cpp/ inside the container, producing cpp/build-{arch}/<entry>
+ * on the host (the workspace is mounted).
+ * - arch null → native (dev mode, uses cpp/build/)
+ * - arch "x86_64" / "aarch64" → cross via --platform (Release builds for ZIP)
+ * buildType "Debug" for dev, "Release" for export builds that ship in the ZIP.
+ */
+export function cmakeBuild(root, { image = CPP_DEV_IMAGE, buildType = "Debug", arch = null } = {}) {
+  const buildDir = arch ? `cpp/build-${arch}` : "cpp/build";
+  const dockerPlatform = arch ? ARCH_DOCKER_PLATFORM[arch] : null;
+  const platformFlags = dockerPlatform ? ["--platform", dockerPlatform] : [];
+  // arch 빌드 시 arch별 이미지 사용 (로컬 이미지와 platform 불일치 방지)
+  const actualImage = arch ? `${CPP_DEV_IMAGE}-${arch}` : image;
+  const script = [
+    `cmake -S cpp -B ${buildDir} -DCMAKE_BUILD_TYPE=${buildType}`,
+    `cmake --build ${buildDir} -j`,
+  ].join(" && ");
+  const label = arch ? `cmake build (${buildType}, ${arch}, in container)…` : `cmake build (${buildType}, in container)…`;
+  log.step(label);
+  const r = spawnSync(
+    "docker",
+    ["run", "--rm", ...platformFlags, "-v", `${root}:/plugin`, "-w", "/plugin", actualImage, "bash", "-lc", script],
+    { cwd: root, stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error(`cmake build failed${arch ? ` (${arch})` : ""}.`);
+}

package/cli/src/dev.mjs

@@ -1,10 +1,23 @@
-// muscat-pk dev — run dev:ui and dev:back together.
+// muscat-pk dev — run the Socket.IO bridge (Docker), dev:ui, and dev:back together.
 import { runDevUi } from "./devUi.mjs";
 import { runDevBack } from "./devBack.mjs";
-import { log } from "./util.mjs";
+import { startBridge, stopBridge, BRIDGE_CONTAINER } from "./bridge.mjs";
+import { ensureDocker, log } from "./util.mjs";
 
 export async function runDev(args = []) {
-  log.step("starting dev:ui + dev:back");
+  ensureDocker();
+  log.step("starting Socket.IO bridge (Docker) + dev:ui + dev:back");
+  await startBridge();
+
+  // Tell dev:back which bridge container to share a netns with, so the backend
+  // reaches the bridge at localhost:10000 (no host.docker.internal).
+  process.env.MUSCAT_PK_BRIDGE_CONTAINER = BRIDGE_CONTAINER;
+
+  const cleanup = () => stopBridge();
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
+  process.once("exit", cleanup);
+
   // dev:back runs to completion / detaches on its own; dev:ui owns the process.
   runDevBack().catch((e) => log.warn(`dev:back: ${e.message}`));
   await runDevUi(args);