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

package/cli/src/devBack.mjs

@@ -1,65 +1,262 @@
-// muscat-pk dev:back — run the plugin back end.
-//   sdk  : create/refresh .venv then `python main.py`
-//   ros2 : requires Docker (Jazzy container) — guidance only here
-//   none : nothing to run
+// muscat-pk dev:back — run the plugin back end during development.
+// Every backend runs in a warm Docker container that matches the robot
+// (Ubuntu 24.04), so dev behaves like production.
+//   python : Python 3.12 container, pip install, run main.py with watchfiles
+//            hot-reload. Shares the bridge container's netns (localhost:10000).
+//   cpp    : Ubuntu + cmake container, build cpp/, run the binary, rebuild +
+//            restart on source changes.
+//   ros2   : Jazzy + Python 3.12 container, colcon build, run the node, restart
+//            on source changes (rclcpp rebuilds on change).
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, watch } from "node:fs";
 import { resolve } from "node:path";
-import { findPluginRoot, log } from "./util.mjs";
+import { ensureDocker, findPluginRoot, log } from "./util.mjs";
+import { readManifest as readManifestSchema, validateManifest } from "./manifest.mjs";
+import {
+  PYTHON_DEV_IMAGE,
+  assertDockerReady as pyAssertDockerReady,
+  ensureImage as pyEnsureImage,
+} from "./python.mjs";
+import {
+  ROS2_DEV_IMAGE,
+  assertDockerReady,
+  ensureImage,
+  ros2PackageName,
+} from "./ros2.mjs";
+import {
+  CPP_DEV_IMAGE,
+  assertDockerReady as cppAssertDockerReady,
+  ensureImage as cppEnsureImage,
+} from "./cpp.mjs";
 
-function manifestRuntime(root) {
+function readManifest(root) {
   try {
-    const m = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8"));
-    return m.runtime?.type ?? "none";
+    return JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8"));
   } catch {
-    return "none";
+    return {};
   }
 }
 
-export async function runDevBack() {
-  const root = findPluginRoot();
-  const type = manifestRuntime(root);
+function manifestRuntime(root) {
+  return readManifest(root).runtime?.type ?? "python";
+}
 
-  if (type === "none") {
-    log.info("runtime: none — no back end to run.");
-    return;
-  }
+// ── python ────────────────────────────────────────────────────────────────────
+// Runs in a warm Ubuntu 24.04 + Python 3.12 container (matches the robot).
+// Under `muscat-pk dev`, it shares the bridge container's netns, so the SDK
+// reaches the Socket.IO bridge at the default localhost:10000.
+function runPython(root) {
+  pyAssertDockerReady();
+  pyEnsureImage();
 
-  if (type === "ros2") {
-    log.warn(
-      "ROS2 back end runs in a Jazzy + Python 3.12 Docker container.\n" +
-        "  Ensure Docker is running, then: muscat-pk dev:back (container support TBD).",
-    );
-    return;
-  }
+  const manifest = readManifest(root);
+  const pluginId = manifest.id ?? "";
+  const container = `${PYTHON_DEV_IMAGE}-run`;
+  const envFlags = pluginId ? ["-e", `RB_PLUGIN_ID=${pluginId}`] : [];
+  // Share the bridge container's network namespace so localhost:10000 is the
+  // bridge (set by `muscat-pk dev`). Standalone dev:back has no bridge to join.
+  const bridgeContainer = process.env.MUSCAT_PK_BRIDGE_CONTAINER;
+  const netFlags = bridgeContainer ? ["--network", `container:${bridgeContainer}`] : [];
+  const docker = (args, opts = {}) =>
+    spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
+
+  // start a warm, long-lived container with the plugin mounted
+  docker(["rm", "-f", container], { stdio: "ignore" });
+  log.step("starting Python dev container…");
+  const up = docker(
+    ["run", "-d", "--name", container, ...netFlags,
+      "-v", `${root}:/plugin`, "-w", "/plugin", PYTHON_DEV_IMAGE, "sleep", "infinity"],
+    { stdio: "inherit" },
+  );
+  if (up.status !== 0) throw new Error("failed to start dev container.");
 
-  // python / rb_sdk
-  const venv = resolve(root, ".venv");
-  const py = process.platform === "win32"
-    ? resolve(venv, "Scripts", "python.exe")
-    : resolve(venv, "bin", "python");
-
-  if (!existsSync(py)) {
-    log.step("creating .venv (python3.12 preferred)…");
-    const python = spawnSync("python3.12", ["--version"]).status === 0
-      ? "python3.12"
-      : "python3";
-    if (python !== "python3.12") {
-      log.warn("python3.12 not found; using python3 (robot targets 3.12).");
+  log.step("pip install requirements + watchfiles (in container)…");
+  docker(["exec", container, "bash", "-lc",
+    "pip install --break-system-packages --ignore-installed -q watchfiles" +
+    " && { [ -f requirements.txt ] && pip install --break-system-packages --ignore-installed -q -r requirements.txt || true; }"]);
+
+  if (pluginId) log.step(`RB_PLUGIN_ID=${pluginId}`);
+  log.step("watchfiles → py/main.py (reload on any .py change in py/)");
+  const child = spawn(
+    "docker",
+    ["exec", ...envFlags, container, "bash", "-lc",
+      "python3 -m watchfiles --filter python --target-type command 'python3 py/main.py' py"],
+    { cwd: root, stdio: ["inherit", "inherit", "pipe"] },
+  );
+  // watchfiles prints a KeyboardInterrupt traceback on SIGTERM — suppress it
+  child.stderr.on("data", (buf) => {
+    const text = buf.toString();
+    if (!text.includes("KeyboardInterrupt") && !text.includes("raise_keyboard_interrupt")) {
+      process.stderr.write(buf);
     }
-    spawnSync(python, ["-m", "venv", venv], { cwd: root, stdio: "inherit" });
-  }
+  });
+
+  const cleanup = () => {
+    if (!child.killed) child.kill();
+    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
+    process.exit(0);
+  };
+  child.on("exit", (code) => {
+    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
+    process.exit(code ?? 0);
+  });
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
+}
+
+// ── ros2 ───────────────────────────────────────────────────────────────────────
+function runRos2(root) {
+  assertDockerReady();
+  const pkg = ros2PackageName(root);
+  if (!pkg) throw new Error("no ROS2 package found under ros2_ws/src.");
+
+  ensureImage();
+
+  const manifest = readManifest(root);
+  const pluginId = manifest.id ?? "";
+  const isRclcpp = manifest.runtime?.rosClient === "rclcpp";
+  const container = `${ROS2_DEV_IMAGE}-run`;
+  const envFlags = pluginId ? ["-e", `RB_PLUGIN_ID=${pluginId}`] : [];
+  const docker = (args, opts = {}) =>
+    spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
+
+  // start a warm, long-lived container with the workspace mounted
+  docker(["rm", "-f", container], { stdio: "ignore" });
+  log.step("starting ROS2 dev container…");
+  const up = docker(
+    ["run", "-d", "--name", container, "-v", `${root}:/plugin`, "-w", "/plugin", ROS2_DEV_IMAGE, "sleep", "infinity"],
+    { stdio: "inherit" },
+  );
+  if (up.status !== 0) throw new Error("failed to start dev container.");
+
+  // one-time deps + symlink build (edits to .py reflect without rebuilding)
+  log.step("pip install + colcon build --symlink-install (once)…");
+  docker(["exec", container, "bash", "-lc",
+    "pip install -r requirements.txt --break-system-packages --ignore-installed -q || true; cd ros2_ws && colcon build --symlink-install"]);
 
-  const reqs = resolve(root, "requirements.txt");
-  if (existsSync(reqs)) {
-    log.step("pip install -r requirements.txt…");
-    spawnSync(py, ["-m", "pip", "install", "-q", "-r", reqs], {
-      cwd: root,
-      stdio: "inherit",
-    });
+  let child = null;
+  const startNode = () => {
+    if (child) child.kill();
+    log.step(`ros2 run ${pkg} ${pkg}_node`);
+    child = spawn(
+      "docker",
+      ["exec", ...envFlags, container, "bash", "-lc",
+        `cd ros2_ws && source install/setup.bash && ros2 run ${pkg} ${pkg}_node`],
+      { cwd: root, stdio: "inherit" },
+    );
+  };
+  startNode();
+
+  // restart node on source change. rclpy reflects .py edits live (symlink-install);
+  // rclcpp (C++) and package-metadata changes require a colcon rebuild.
+  let timer = null;
+  const onChange = (_event, filename) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      const structural = filename && /(setup\.py|package\.xml|CMakeLists\.txt)$/.test(String(filename));
+      if (structural || isRclcpp) {
+        log.info(structural ? "package metadata changed — colcon rebuild…" : "source changed — colcon rebuild…");
+        docker(["exec", container, "bash", "-lc", "cd ros2_ws && colcon build --symlink-install"]);
+      } else {
+        log.info("source changed — restarting node…");
+      }
+      startNode();
+    }, 300);
+  };
+  for (const target of ["ros2_ws/src", "main.py"]) {
+    const full = resolve(root, target);
+    if (existsSync(full)) watch(full, { recursive: true }, onChange);
   }
 
-  log.step("python main.py");
-  const child = spawn(py, ["main.py"], { cwd: root, stdio: "inherit" });
-  child.on("exit", (code) => process.exit(code ?? 0));
+  const cleanup = () => {
+    if (child) child.kill();
+    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
+    process.exit(0);
+  };
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+}
+
+// ── cpp ──────────────────────────────────────────────────────────────────────
+function runCpp(root) {
+  cppAssertDockerReady();
+  const manifest = readManifest(root);
+  const entry = manifest.runtime?.entry;
+  if (!entry) throw new Error("runtime.entry (the built executable name) is required for cpp.");
+
+  cppEnsureImage();
+
+  const pluginId = manifest.id ?? "";
+  const container = `${CPP_DEV_IMAGE}-run`;
+  const envFlags = pluginId ? ["-e", `RB_PLUGIN_ID=${pluginId}`] : [];
+  const docker = (args, opts = {}) =>
+    spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
+
+  // start a warm, long-lived container with the plugin mounted
+  docker(["rm", "-f", container], { stdio: "ignore" });
+  log.step("starting C++ dev container…");
+  const up = docker(
+    ["run", "-d", "--name", container, "-v", `${root}:/plugin`, "-w", "/plugin", CPP_DEV_IMAGE, "sleep", "infinity"],
+    { stdio: "inherit" },
+  );
+  if (up.status !== 0) throw new Error("failed to start dev container.");
+
+  const build = () => {
+    log.step("cmake build…");
+    return docker(["exec", container, "bash", "-lc",
+      "cmake -S cpp -B cpp/build -DCMAKE_BUILD_TYPE=Debug && cmake --build cpp/build -j"]);
+  };
+  build();
+
+  let child = null;
+  const startBin = () => {
+    if (child) child.kill();
+    log.step(`run cpp/build/${entry}`);
+    child = spawn(
+      "docker",
+      ["exec", ...envFlags, container, "bash", "-lc", `./cpp/build/${entry}`],
+      { cwd: root, stdio: "inherit" },
+    );
+  };
+  startBin();
+
+  // rebuild + restart on C++ source changes; ignore the build/ output dir.
+  let timer = null;
+  const onChange = (_event, filename) => {
+    if (filename && String(filename).startsWith("build")) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      log.info("source changed — rebuilding…");
+      const r = build();
+      if (r.status === 0) startBin();
+      else log.warn("build failed — keeping previous binary");
+    }, 300);
+  };
+  const cppDir = resolve(root, "cpp");
+  if (existsSync(cppDir)) watch(cppDir, { recursive: true }, onChange);
+
+  const cleanup = () => {
+    if (child) child.kill();
+    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
+    process.exit(0);
+  };
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+}
+
+function warnManifest(root) {
+  const manifest = readManifestSchema(root);
+  if (!manifest || Object.keys(manifest).length === 0) return;
+  const errors = validateManifest(manifest);
+  for (const e of errors) log.warn(`manifest.json: ${e}`);
+}
+
+export async function runDevBack() {
+  ensureDocker();
+  const root = findPluginRoot();
+  warnManifest(root);
+  const type = manifestRuntime(root);
+  if (type === "ros2") return runRos2(root);
+  if (type === "cpp") return runCpp(root);
+  return runPython(root);
 }

package/cli/src/devUi.mjs

@@ -1,37 +1,133 @@
 // muscat-pk dev:ui — preview the plugin inside a mini-Muscat (preview-host).
-import { spawn } from "node:child_process";
+// UI bundling: vite build --watch (uses plugin project's own node_modules/vite).
+// Falls back gracefully if Node.js or vite is not available.
+import { spawn, spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
-import { existsSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
-import { buildPlugin } from "./build.mjs";
-import { checkKitUpdate, findPluginRoot, kitRoot, log } from "./util.mjs";
+import { SANDBOX_HTML } from "./build.mjs";
+import { checkKitUpdate, findPluginRoot, hasBin, kitRoot, log } from "./util.mjs";
+
+const PREVIEW_PKG = "@rainbow-robotics/preview-host";
+const CACHE_DIR = resolve(homedir(), ".muscat-pk");
+const CACHE_ROOT = resolve(CACHE_DIR, "node_modules", "@rainbow-robotics", "preview-host");
+
+// Dev builds go to a throwaway dir, not dist/ — dist/ is reserved for
+// build/pack output (the shippable artifact).
+const DEV_OUT = ".muscat-dev";
+
+function findNodeBin() {
+  if (typeof Bun === "undefined") return process.execPath;
+  for (const c of ["node", "node20", "node18"]) {
+    if (hasBin(c)) return c;
+  }
+  return null;
+}
 
-/** Resolve @rainbow-robotics/preview-host package root.
- *  Works in monorepo (yarn workspace hoisting) and when both packages are
- *  installed as deps of the plugin project. */
 function findPreviewHostRoot() {
   try {
     const req = createRequire(import.meta.url);
-    return dirname(req.resolve("@rainbow-robotics/preview-host/package.json"));
+    return dirname(req.resolve(`${PREVIEW_PKG}/package.json`));
+  } catch {}
+
+  const sibling = resolve(kitRoot, "../preview-host");
+  if (existsSync(resolve(sibling, "package.json"))) return sibling;
+
+  if (existsSync(resolve(CACHE_ROOT, "package.json"))) return CACHE_ROOT;
+
+  if (!hasBin("npm")) {
+    throw new Error(
+      `preview-host를 찾을 수 없습니다.\n` +
+      `Node.js 20+ 를 설치하면 자동으로 준비됩니다: https://nodejs.org`,
+    );
+  }
+  log.step(`preview-host 설치 중 (~/.muscat-pk) — 첫 실행 시 한 번만 수행됩니다…`);
+  mkdirSync(CACHE_DIR, { recursive: true });
+  const r = spawnSync(
+    "npm",
+    ["install", "--prefix", CACHE_DIR, "--save", PREVIEW_PKG],
+    { stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error("preview-host 설치 실패.");
+  if (!existsSync(resolve(CACHE_ROOT, "package.json"))) {
+    throw new Error("preview-host 설치 후에도 패키지를 찾을 수 없습니다.");
+  }
+  return CACHE_ROOT;
+}
+
+// Write sandbox.html + copy manifest into the dev out dir (vite doesn't generate these).
+function stageDevAssets(pluginRoot) {
+  const outDir = resolve(pluginRoot, DEV_OUT);
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(resolve(outDir, "sandbox.html"), SANDBOX_HTML, "utf8");
+  const manifestSrc = resolve(pluginRoot, "manifest.json");
+  if (existsSync(manifestSrc)) copyFileSync(manifestSrc, resolve(outDir, "manifest.json"));
+  return outDir;
+}
+
+// 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 {
-    // fallback: sibling package in muscat-plugin-kit/ workspace
-    return resolve(kitRoot, "../preview-host");
+    return null;
   }
 }
 
+// Spawn vite build --watch as a background process.
+// Returns the child process, or null if vite/node not available.
+function spawnViteWatch(pluginRoot, node) {
+  const viteBin = findViteBin(pluginRoot);
+  if (!node || !viteBin || !existsSync(viteBin)) return null;
+
+  log.step(`vite build --watch (ui/content.tsx → ${DEV_OUT}/content.js)`);
+  return spawn(node, [viteBin, "build", "--watch", "--mode", "development", "--outDir", DEV_OUT], {
+    cwd: pluginRoot,
+    stdio: "inherit",
+  });
+}
+
+// Wait until dist/content.js exists (vite initial build completes).
+function waitForInitialBuild(distDir, timeoutMs = 30_000) {
+  return new Promise((res, rej) => {
+    const contentJs = resolve(distDir, "content.js");
+    const start = Date.now();
+    const check = () => {
+      if (existsSync(contentJs)) return res();
+      if (Date.now() - start > timeoutMs) return rej(new Error("vite initial build timed out"));
+      setTimeout(check, 300);
+    };
+    check();
+  });
+}
+
 export async function runDevUi(args = []) {
   const portIdx = args.indexOf("--port");
   const port = portIdx !== -1 ? args[portIdx + 1] : "4180";
 
   await checkKitUpdate();
-  const { distDir } = await buildPlugin();
+  const pluginRoot = findPluginRoot();
+  const outDir = stageDevAssets(pluginRoot);
+
+  const node = findNodeBin();
+  const viteProc = spawnViteWatch(pluginRoot, node);
+
+  if (viteProc) {
+    log.step("waiting for initial vite build…");
+    await waitForInitialBuild(outDir);
+  } else {
+    log.warn("vite not found — UI will not be bundled. Run `npm install` in the plugin project.");
+  }
 
   const previewRoot = findPreviewHostRoot();
   const serveEntry = resolve(previewRoot, "serve.mjs");
   if (!existsSync(resolve(previewRoot, "dist", "index.html"))) {
     log.step("building preview-host bundle (first run)…");
     await new Promise((res, rej) => {
-      const p = spawn("node", [resolve(previewRoot, "build.mjs")], {
+      const p = spawn(node ?? process.execPath, [resolve(previewRoot, "build.mjs")], {
         stdio: "inherit",
       });
       p.on("exit", (c) => (c === 0 ? res() : rej(new Error("preview-host build failed"))));
@@ -40,11 +136,18 @@ export async function runDevUi(args = []) {
 
   log.step(`starting preview-host on :${port}`);
   const child = spawn(
-    "node",
-    [serveEntry, "--plugin", distDir, "--port", String(port)],
+    node ?? process.execPath,
+    [serveEntry, "--plugin", outDir, "--port", String(port)],
     { stdio: "inherit" },
   );
+
+  const cleanup = () => {
+    if (viteProc && !viteProc.killed) viteProc.kill();
+    if (!child.killed) child.kill();
+  };
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
   child.on("exit", (code) => process.exit(code ?? 0));
 }
 
-export { findPluginRoot };
+export { findPluginRoot, findPreviewHostRoot };

package/cli/src/esbuild.mjs

@@ -1,15 +1,56 @@
+// When compiled with `bun --compile`, esbuild's native subprocess binary is
+// not bundled. Use Bun's built-in bundler instead.
+async function buildWithBun(options) {
+  const { entryPoints, outfile, format, minify, loader, define, external } = options;
+  const { dirname } = await import("node:path");
+  const result = await Bun.build({
+    entrypoints: entryPoints,
+    outdir: dirname(outfile),
+    format: format ?? "esm",
+    minify: minify ?? false,
+    loader,
+    define,
+    external,
+    target: "node",
+    throw: false,
+  });
+  if (!result.success) {
+    for (const log of result.logs) console.error(log.message);
+    throw new Error("Bun.build() failed");
+  }
+}
+
+async function buildWithWasm(options) {
+  const wasm = await import("esbuild-wasm");
+  return wasm.build(options);
+}
+
+function isNativeMissing(err) {
+  const msg = String(err?.message || err?.code || err || "");
+  return (
+    msg.includes("another platform") ||
+    msg.includes("Cannot find module") ||
+    msg.includes("Cannot find package") ||
+    msg.includes("not found") ||
+    msg.includes("No such file") ||
+    msg.includes("ENOENT") ||
+    msg.includes("MODULE_NOT_FOUND")
+  );
+}
+
 export async function buildWithFallback(options) {
-  const native = await import("esbuild");
+  if (typeof Bun !== "undefined") return buildWithBun(options);
+
+  // Try native esbuild (faster, no extra setup). Falls back to wasm when:
+  // - esbuild was not installed (removed from hard dependencies to avoid
+  //   postinstall script blocking npm i -g on Windows)
+  // - binary was built for a different platform
   try {
+    const native = await import("esbuild");
     return await native.build(options);
-  } catch (error) {
-    const message = String(error?.message || error);
-    if (!message.includes("another platform")) {
-      throw error;
-    }
-
-    const wasm = await import("esbuild-wasm");
-    console.warn("[muscat-pk] native esbuild binary mismatch; falling back to esbuild-wasm");
-    return wasm.build(options);
+  } catch (err) {
+    if (!isNativeMissing(err)) throw err;
   }
+
+  return buildWithWasm(options);
 }