@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.3 → 0.1.2-dev.31

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,185 @@
 // 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 } from "./util.mjs";
+import { assertManifest } from "./manifest.mjs";
 
-const SANDBOX_HTML = `<!doctype html>
+// Find a usable node binary (for running vite as subprocess).
+function findNodeBin() {
+  if (typeof Bun === "undefined") return process.execPath; // already node
+  for (const c of ["node", "node20", "node18"]) {
+    if (hasBin(c)) return c;
+  }
+  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.
+// Returns true on success, false if vite/node not available.
+function runViteBuild(pluginRoot, { mode = "production" } = {}) {
+  const node = findNodeBin();
+  if (!node) return false;
+  const viteBin = findViteBin(pluginRoot);
+  if (!viteBin || !existsSync(viteBin)) return false;
+
+  log.step(`vite build (mode: ${mode})`);
+  const r = spawnSync(node, [viteBin, "build", "--mode", mode], {
+    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";
+}
+
+function manifestRuntime(root) {
+  try {
+    return JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime?.type ?? "python";
+  } catch {
+    return "python";
+  }
+}
+
+// For ros2 plugins, compile the colcon workspace inside the Jazzy + Python 3.12
+// container so the shipped ZIP carries ros2_ws/install. Real (non-symlink) build
+// → relocatable on the robot. Skipped (with a warning) if Docker is unavailable.
+export async function exportRos2Build(root) {
+  if (manifestRuntime(root) !== "ros2") return;
+  const { assertDockerReady, ensureImage, colconBuild } = await import("./ros2.mjs");
+  try {
+    assertDockerReady();
+  } catch (e) {
+    log.warn(`ros2 build skipped: ${e.message}`);
+    return;
+  }
+  ensureImage();
+  colconBuild(root, { symlink: false });
+  log.ok("ros2_ws/install ready (will be included in the ZIP)");
+}
+
+// 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 = ["x86_64", "aarch64"]) {
+  if (manifestRuntime(root) !== "cpp") return;
+  const { assertDockerReady, ensureImage, cmakeBuild } = await import("./cpp.mjs");
+  try {
+    assertDockerReady();
+  } catch (e) {
+    log.warn(`cpp build skipped: ${e.message}`);
+    return;
+  }
+  ensureImage();
+
+  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) {
+    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 +213,17 @@ 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 viteOk = runViteBuild(pluginRoot, { mode: minify ? "production" : "development" });
+  if (!viteOk) {
+    log.warn("vite not found — UI bundle skipped. Install Node.js and run: npm install");
+  }
 
   // Stage distribution files.
   const manifestSrc = resolve(pluginRoot, "manifest.json");
@@ -80,16 +232,234 @@ 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) {
+  let total = 0;
+  for (const entry of readdirSync(dir)) {
+    const full = resolve(dir, entry);
+    const st = statSync(full);
+    total += st.isDirectory() ? dirSize(full) : st.size;
+  }
+  return total;
+}
+
+// Recursively sum directory size, skipping subdirs in `skip` list (by name).
+function dirSizeExcluding(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.
+function unpackedWheelSize(whlPath) {
+  const buf = readFileSync(whlPath);
+  // Find EOCD signature (0x06054b50) scanning from end
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 65558); i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) { eocd = i; break; }
+  }
+  if (eocd === -1) return 0;
+  const cdOffset = buf.readUInt32LE(eocd + 16);
+  const cdSize   = buf.readUInt32LE(eocd + 12);
+  let pos = cdOffset;
+  let total = 0;
+  while (pos < cdOffset + cdSize) {
+    if (buf.readUInt32LE(pos) !== 0x02014b50) break; // central dir signature
+    total += buf.readUInt32LE(pos + 24); // uncompressed size
+    const fnLen      = buf.readUInt16LE(pos + 28);
+    const extraLen   = buf.readUInt16LE(pos + 30);
+    const commentLen = buf.readUInt16LE(pos + 32);
+    pos += 46 + fnLen + extraLen + commentLen;
+  }
+  return total;
+}
+
+// Calculate max(arch installedSize) across requested archs and stamp it into
+// both manifest.json (root) and dist/manifest.json.
+// installedSize(arch) = dist/(excl. wheels/) + ros2_ws/install/ + uncompressed arch+none-any wheels
+function calcInstalledSize(pluginRoot, archs) {
+  const distDir     = resolve(pluginRoot, "dist");
+  const wheelsDir   = resolve(distDir, "wheels");
+  const ros2Install = resolve(pluginRoot, "ros2_ws/install");
+
+  const baseSize = dirSizeExcluding(distDir, ["wheels"]);
+  const ros2Size = existsSync(ros2Install) ? dirSize(ros2Install) : 0;
+
+  // Collect all wheel files once
+  const wheels = existsSync(wheelsDir)
+    ? readdirSync(wheelsDir).filter((f) => f.endsWith(".whl")).map((f) => resolve(wheelsDir, f))
+    : [];
+
+  const perArchSize = archs.map((arch) => {
+    const archWheels = wheels.filter((w) => {
+      const name = w.split("/").pop();
+      // none-any wheels count for every arch
+      if (name.endsWith("none-any.whl")) return true;
+      return name.includes(arch);
+    });
+    const wheelSize = archWheels.reduce((sum, w) => sum + unpackedWheelSize(w), 0);
+    return baseSize + ros2Size + wheelSize;
+  });
+
+  const installedSize = Math.max(0, ...perArchSize);
+
+  // 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)} (${archs.join(", ")} max, uncompressed)`);
+}
+
+// Zip dist/ (+ ros2_ws/install) into a distributable ZIP with a size report.
+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"];
+  if (existsSync(resolve(pluginRoot, "ros2_ws/install"))) entries.push("ros2_ws/install");
+
+  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)}`);
+  }
+  log.warn("robot install checks free space via GET /plugin/capacity (507 if low).");
+}
+
+/**
+ * Ask which target arch(es) to build for.
+ * Non-TTY (CI): auto-selects current machine arch.
+ * @returns {Promise<string[]>} e.g. ['x86_64'] | ['aarch64'] | ['x86_64','aarch64']
+ */
+async function promptArch() {
+  if (!process.stdin.isTTY) {
+    const { arch } = await import("node:os");
+    const machine = arch() === "arm64" ? "aarch64" : "x86_64";
+    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 (x86_64)\n" +
+    "    2) arm64 (aarch64)\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 ["x86_64"];
+  if (answer === "2") return ["aarch64"];
+  return ["x86_64", "aarch64"];
+}
+
+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();
+
+  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 {
+        lockAndVendor(pluginRoot, archs);
+      } catch (e) {
+        log.warn(`python lock/vendor skipped: ${e.message}`);
+      }
+    }
+  }
+
+  await exportRos2Build(root);
+  await exportCppBuild(root, distDir, archs);
+  calcInstalledSize(pluginRoot, archs);
+  if (!noZip) packZip(pluginRoot);
 }

package/cli/src/check-package.mjs

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import { readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -22,6 +22,7 @@ function* mjsFiles(dir) {
 }
 
 for (const dir of roots) {
+  if (!existsSync(dir)) continue;
   for (const file of mjsFiles(dir)) {
     execFileSync(process.execPath, ["--check", file], { stdio: "inherit" });
   }

package/cli/src/cpp.mjs

@@ -0,0 +1,65 @@
+// 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 { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { hasBin, kitRoot, log, pruneMuskatImages } from "./util.mjs";
+
+export const CPP_DEV_IMAGE = "muscat-pk-cpp-dev";
+
+// Dockerfile lives inside the kit — plugin authors never see or edit it.
+const DOCKERFILE = resolve(kitRoot, "cli/docker/Dockerfile.cpp");
+
+export function assertDockerReady() {
+  if (!hasBin("docker")) {
+    throw new Error("Docker not found. C++ builds need Docker (Ubuntu 24.04 + cmake container).");
+  }
+  if (!existsSync(DOCKERFILE)) {
+    throw new Error(`kit Dockerfile missing at ${DOCKERFILE} (reinstall muscat-plugin-kit).`);
+  }
+}
+
+/** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
+export function ensureImage(image = CPP_DEV_IMAGE) {
+  log.step(`docker build -t ${image} (first run is slow, then cached)…`);
+  const r = spawnSync(
+    "docker",
+    ["build", "-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
+const ARCH_DOCKER_PLATFORM = {
+  x86_64: "linux/amd64",
+  aarch64: "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 platformFlags = arch && ARCH_DOCKER_PLATFORM[arch]
+    ? ["--platform", ARCH_DOCKER_PLATFORM[arch]]
+    : [];
+  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", image, "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);