@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.23 → 0.1.2-dev.25

package/cli/README.md

@@ -1,6 +1,6 @@
 # @rainbow-robotics/muscat-plugin-kit (`muscat-pk`)
 
-CLI to scaffold, build, preview and pack Muscat plugins.
+CLI to scaffold, build, and preview Muscat plugins.
 
 Install/use it the same way an external plugin author will:
 
@@ -10,11 +10,10 @@ muscat-pk new my-plugin
 ```
 
 ```bash
-muscat-pk new my-plugin [--type sdk|ros2|ui] [--pm npm|yarn|pnpm|bun] [--yes]
-muscat-pk build       # src/content.tsx -> dist/content.js (+ manifest, sandbox, assets)
-muscat-pk pack        # build (minified) + distributable ZIP with a size report
+muscat-pk new my-plugin [--type python|cpp|ros2|ros2-cpp] [--pm npm|yarn|pnpm|bun] [--yes]
+muscat-pk build       # ui/content.tsx -> dist/ (minified) + distributable ZIP (--no-zip to skip)
 muscat-pk dev:ui      # preview the plugin in a mini-Muscat (preview-host)
-muscat-pk dev:back    # run the back end (.venv + python main.py)
+muscat-pk dev:back    # run the back end in a Docker container (python / cpp / ros2)
 muscat-pk dev         # dev:ui + dev:back
 muscat-pk update      # update @rainbow-robotics/muscat-plugin-kit and @rainbow-robotics/plugin-ui
 muscat-pk sdk list | sdk update [version]   # manage rainbow-rb-sdk (python)

package/cli/bin/create-muscat-plugin.mjs

@@ -3,6 +3,6 @@
 import { runNew } from "../src/new.mjs";
 
 runNew(process.argv.slice(2)).catch((err) => {
-  console.error(`\n✖ ${err?.message || err}`);
+  console.error(`\n ✖ ${err?.message || err}`);
   process.exit(1);
 });

package/cli/bin/muscat-pk.mjs

@@ -1,10 +1,9 @@
 #!/usr/bin/env node
 // muscat-pk — Muscat plugin developer CLI.
-// Subcommands: new, build, pack, dev, dev:ui, dev:back, update, sdk.
+// Subcommands: new, build, dev, dev:ui, dev:back, update, sdk.
 import { log } from "../src/util.mjs";
 import { runNew } from "../src/new.mjs";
 import { runBuild } from "../src/build.mjs";
-import { runPack } from "../src/pack.mjs";
 import { runDevUi } from "../src/devUi.mjs";
 import { runDevBack } from "../src/devBack.mjs";
 import { runDev } from "../src/dev.mjs";
@@ -20,10 +19,9 @@ const HELP = `muscat-pk — Muscat plugin kit
 Usage: muscat-pk <command> [options]
 
 Commands:
-  new [dir]        Scaffold a new plugin project
-  type change      Switch backend type (python <-> ros2)
-  build            Build src/content.tsx -> dist/content.js (+ manifest, assets)
-  pack             Build then create a distributable ZIP (with size report)
+  new [dir]        Scaffold a new plugin project (prompts: author, email, description, type, pm)
+  type change      Switch backend type (python | cpp | ros2 | ros2-cpp)
+  build            Build ui/content.tsx -> dist/ and zip into a distributable ZIP (--no-zip to skip)
   dev              Run Socket.IO bridge, dev:ui, and dev:back together
   dev:ui           Preview the plugin in a mini-Muscat (preview-host)
   dev:back         Run the plugin back end (python: watchfiles reload / ros2: Docker)
@@ -42,8 +40,6 @@ async function main() {
         return await runType(args);
       case "build":
         return await runBuild(args);
-      case "pack":
-        return await runPack(args);
       case "dev":
         return await runDev(args);
       case "dev:ui":

package/cli/docker/Dockerfile.bridge

@@ -0,0 +1,16 @@
+# Socket.IO bridge container — the frontend (preview-host) and the backend
+# container rendezvous here during `muscat-pk dev`.
+#   - frontend (host)  → published port localhost:10000
+#   - backend container → shares this container's netns (--network container:),
+#                         so it reaches the bridge at localhost:10000 too
+# Build context is the `cli/` dir so it can copy src/socketBridge.mjs.
+FROM node:20-slim
+
+WORKDIR /bridge
+COPY docker/bridge-package.json package.json
+RUN npm install --omit=dev --no-audit --no-fund
+
+COPY src/socketBridge.mjs ./socketBridge.mjs
+
+EXPOSE 10000
+CMD ["node", "socketBridge.mjs"]

package/cli/docker/Dockerfile.cpp

@@ -0,0 +1,21 @@
+# Dev/build container for the pure C++ plugin back end.
+# Matches the Muscat robot backend OS (Ubuntu 24.04) so the compiled binary
+# is ABI-compatible with the robot. Used by `muscat-pk dev:back` and `build`
+# — NOT shipped in the plugin ZIP.
+FROM ubuntu:24.04
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      build-essential \
+      cmake \
+    && rm -rf /var/lib/apt/lists/*
+
+# TODO(cpp-sdk): install the rainbow cpp SDK (dev package) here, pinned to the
+# robot's version, so plugins build/link against the same SDK as production.
+# Plan: apt package + dynamic link (the robot provides the .so at runtime;
+# we do NOT bundle it into the plugin binary). e.g.:
+#   RUN apt-get update && apt-get install -y rainbow-cpp-sdk-dev=<robot-version> \
+#       && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /plugin
+
+CMD ["bash"]

package/cli/docker/Dockerfile.python

@@ -0,0 +1,18 @@
+# Dev container for the Python plugin back end.
+# Matches the Muscat robot backend: Ubuntu 24.04 + Python 3.12.
+# Used by `muscat-pk dev:back` — NOT shipped in the plugin ZIP (the robot
+# pip-installs requirements itself at load time).
+FROM ubuntu:24.04
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      python3 \
+      python3-pip \
+    && rm -rf /var/lib/apt/lists/*
+
+# TODO(cpp-sdk): the Python SDK is a pybind wrapper over the cpp SDK, so the
+# cpp SDK shared lib must be present for the python module to load. Install the
+# rainbow cpp SDK (apt, pinned to the robot's version) here once it exists.
+
+WORKDIR /plugin
+
+CMD ["bash"]

package/cli/docker/bridge-package.json

@@ -0,0 +1,8 @@
+{
+  "name": "muscat-pk-bridge",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "socket.io": "^4.8.1"
+  }
+}

package/cli/src/bridge.mjs

@@ -0,0 +1,91 @@
+// Socket.IO bridge container lifecycle for `muscat-pk dev`.
+// The bridge runs in Docker and publishes port 10000 to the host:
+//   - frontend (preview-host, on the host) connects to localhost:10000
+//   - the backend container joins via `--network container:<bridge>` and reaches
+//     it at localhost:10000 too — no host.docker.internal needed (robust cross-OS).
+import { spawnSync } from "node:child_process";
+import { createServer, connect } from "node:net";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { hasBin, kitRoot, log } from "./util.mjs";
+
+export const BRIDGE_IMAGE = "muscat-pk-bridge";
+export const BRIDGE_CONTAINER = "muscat-pk-bridge-run";
+export const BRIDGE_PORT = 10000;
+
+const DOCKERFILE = resolve(kitRoot, "cli/docker/Dockerfile.bridge");
+const BUILD_CONTEXT = resolve(kitRoot, "cli");
+
+function assertDockerReady() {
+  if (!hasBin("docker")) {
+    throw new Error("Docker not found. `muscat-pk dev` runs the Socket.IO bridge in a container.");
+  }
+  if (!existsSync(DOCKERFILE)) {
+    throw new Error(`kit Dockerfile missing at ${DOCKERFILE} (reinstall muscat-plugin-kit).`);
+  }
+}
+
+// Is a host TCP port already bound? (Catches another bridge or a stray process.)
+function isPortInUse(port) {
+  return new Promise((res) => {
+    const srv = createServer();
+    srv.once("error", (err) => res(err.code === "EADDRINUSE"));
+    srv.once("listening", () => srv.close(() => res(false)));
+    srv.listen(port, "0.0.0.0");
+  });
+}
+
+// Wait until the published port accepts a TCP connection (bridge is ready).
+function waitForPort(port, timeoutMs = 15_000) {
+  const start = Date.now();
+  return new Promise((res, rej) => {
+    const tryOnce = () => {
+      const sock = connect(port, "127.0.0.1");
+      sock.once("connect", () => { sock.destroy(); res(); });
+      sock.once("error", () => {
+        sock.destroy();
+        if (Date.now() - start > timeoutMs) rej(new Error("bridge container did not become ready in time"));
+        else setTimeout(tryOnce, 300);
+      });
+    };
+    tryOnce();
+  });
+}
+
+function ensureImage() {
+  log.step(`docker build -t ${BRIDGE_IMAGE} (first run is slow, then cached)…`);
+  const r = spawnSync("docker", ["build", "-t", BRIDGE_IMAGE, "-f", DOCKERFILE, BUILD_CONTEXT], { stdio: "inherit" });
+  if (r.status !== 0) throw new Error("docker build failed (bridge image).");
+}
+
+/** Build the image, preflight the port, and start the bridge container. */
+export async function startBridge() {
+  assertDockerReady();
+
+  // remove our own stale container first, then check the host port is free
+  spawnSync("docker", ["rm", "-f", BRIDGE_CONTAINER], { stdio: "ignore" });
+  if (await isPortInUse(BRIDGE_PORT)) {
+    throw new Error(
+      `port ${BRIDGE_PORT} is already in use.\n` +
+      `  Another 'muscat-pk dev' may be running, or a process is holding the port.\n` +
+      `  Stop it, or free the port, then retry.`,
+    );
+  }
+
+  ensureImage();
+
+  log.step("starting Socket.IO bridge container…");
+  const up = spawnSync(
+    "docker",
+    ["run", "-d", "--name", BRIDGE_CONTAINER, "-p", `${BRIDGE_PORT}:${BRIDGE_PORT}`, BRIDGE_IMAGE],
+    { stdio: "inherit" },
+  );
+  if (up.status !== 0) throw new Error("failed to start bridge container.");
+
+  await waitForPort(BRIDGE_PORT);
+  log.step(`Socket.IO bridge listening on ws://127.0.0.1:${BRIDGE_PORT}`);
+}
+
+export function stopBridge() {
+  spawnSync("docker", ["rm", "-f", BRIDGE_CONTAINER], { stdio: "ignore" });
+}

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,11 +9,11 @@
 // 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, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, cpSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, resolve } from "node:path";
-import { spawnSync } from "node:child_process";
-import { findPluginRoot, hasBin, log } from "./util.mjs";
+import { basename, dirname, resolve } from "node:path";
+import { execSync, spawnSync } from "node:child_process";
+import { ensureDocker, findPluginRoot, hasBin, humanSize, log } from "./util.mjs";
 import { assertManifest } from "./manifest.mjs";
 
 // Find a usable node binary (for running vite as subprocess).
@@ -83,6 +84,33 @@ export async function exportRos2Build(root) {
   log.ok("ros2_ws/install ready (will be included in the ZIP)");
 }
 
+// For cpp plugins, compile cpp/ inside the Ubuntu container (Release) and copy
+// the binary into dist/ so the ZIP carries a robot-compatible executable.
+// Skipped (with a warning) if Docker is unavailable.
+export async function exportCppBuild(root, distDir) {
+  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();
+  cmakeBuild(root, { buildType: "Release" });
+
+  const entry = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime?.entry;
+  const built = resolve(root, "cpp/build", entry ?? "");
+  if (entry && existsSync(built)) {
+    const dest = resolve(distDir, entry);
+    copyFileSync(built, dest);
+    chmodSync(dest, 0o755);
+    log.ok(`cpp binary → dist/${entry} (will be included in the ZIP)`);
+  } else {
+    log.warn(`cpp binary not found at cpp/build/${entry} — skipped`);
+  }
+}
+
 const PRERELEASE_RE = /\.(dev|a|b|rc|alpha|beta)\d*/i;
 
 function isPrerelease(version) {
@@ -117,7 +145,7 @@ async function latestPypiVersion(pkg, { stableOnly = false } = {}) {
 }
 
 // Pin unpinned (no version specifier) entries in requirements.txt to the
-// latest PyPI release. Runs on explicit `build`/`pack` only — keeps the shipped
+// 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 } = {}) {
@@ -198,9 +226,9 @@ export async function buildPlugin({ root, minify = false } = {}) {
     cpSync(assetsSrc, resolve(distDir, "assets"), { recursive: true });
   }
 
-  // README.md and README.[lang].md → dist/
+  // 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)) {
+    if (/^README(\.[a-z]{2}(-[A-Z]{2})?)?\.md$/i.test(f) || /^CHANGELOG\.md$/i.test(f)) {
       copyFileSync(resolve(pluginRoot, f), resolve(distDir, f));
     }
   }
@@ -219,14 +247,59 @@ export async function buildPlugin({ root, minify = false } = {}) {
   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;
+}
+
+// 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).");
+}
+
 export async function runBuild(args) {
-  const minify = args.includes("--minify");
+  const noZip = args.includes("--no-zip");
   const root = findPluginRoot();
+  // cpp / ros2 compile inside Docker — require it up front (python/none don't).
+  const rt = manifestRuntime(root);
+  if (rt === "cpp" || rt === "ros2") ensureDocker();
   if (!args.includes("--no-pin")) {
     const stableOnly = isMainBranch();
     log.step(`pinning requirements.txt to latest ${stableOnly ? "stable " : ""}PyPI versions`);
     await pinRequirements(root, { stableOnly });
   }
-  await buildPlugin({ root, minify });
+  const { pluginRoot, distDir } = await buildPlugin({ root, minify: true });
   await exportRos2Build(root);
+  await exportCppBuild(root, distDir);
+  if (!noZip) packZip(pluginRoot);
 }

package/cli/src/cpp.mjs

@@ -0,0 +1,51 @@
+// 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 } 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.");
+}
+
+/**
+ * Configure + build cpp/ inside the container, producing cpp/build/<entry> on
+ * the host (the workspace is mounted). buildType "Debug" for dev, "Release" for
+ * export builds that ship in the ZIP.
+ */
+export function cmakeBuild(root, { image = CPP_DEV_IMAGE, buildType = "Debug" } = {}) {
+  const script = [
+    `cmake -S cpp -B cpp/build -DCMAKE_BUILD_TYPE=${buildType}`,
+    "cmake --build cpp/build -j",
+  ].join(" && ");
+  log.step(`cmake build (${buildType}, in container)…`);
+  const r = spawnSync(
+    "docker",
+    ["run", "--rm", "-v", `${root}:/plugin`, "-w", "/plugin", image, "bash", "-lc", script],
+    { cwd: root, stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error("cmake build failed.");
+}

package/cli/src/dev.mjs

@@ -1,13 +1,19 @@
-// muscat-pk dev — run Socket.IO bridge, 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 { startSocketBridge } from "./socketBridge.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 Socket.IO bridge + dev:ui + dev:back");
-  const bridge = await startSocketBridge();
-  const cleanup = () => bridge.close();
+  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);