@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.24 → 0.1.2-dev.26

package/cli/README.md

@@ -10,10 +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 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

@@ -19,8 +19,8 @@ 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)
+  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)

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

@@ -9,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, statSync, writeFileSync } from "node:fs";
+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 { execSync, spawnSync } from "node:child_process";
-import { findPluginRoot, hasBin, humanSize, log } from "./util.mjs";
+import { ensureDocker, findPluginRoot, hasBin, humanSize, log } from "./util.mjs";
 import { assertManifest } from "./manifest.mjs";
 
 // Find a usable node binary (for running vite as subprocess).
@@ -84,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) {
@@ -199,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));
     }
   }
@@ -263,12 +290,16 @@ function packZip(pluginRoot) {
 export async function runBuild(args) {
   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 });
   }
-  const { pluginRoot } = await buildPlugin({ root, minify: true });
+  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);

package/cli/src/devBack.mjs

@@ -1,20 +1,33 @@
 // muscat-pk dev:back — run the plugin back end during development.
-//   python : create/refresh .venv, then run main.py with watchfiles hot-reload
-//            (uvicorn's reloader). Watches ALL .py files, not just main.py.
-//   ros2   : keep a Jazzy + Python 3.12 container warm, colcon build once with
-//            --symlink-install, run the node, and restart on source changes —
-//            i.e. develop as if inside the container.
+// 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, watch } from "node:fs";
 import { resolve } from "node:path";
-import { detectPythonCmd, hasBin, findPluginRoot, log, venvPython } 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 readManifest(root) {
   try {
@@ -29,50 +42,64 @@ function manifestRuntime(root) {
 }
 
 // ── 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) {
-  const venv = resolve(root, ".venv");
-  const py = venvPython(venv);
-  const pyDir = resolve(root, "py");
-
-  if (!existsSync(py)) {
-    log.step("creating .venv…");
-    if (hasBin("uv")) {
-      spawnSync("uv", ["venv", venv, "--python", "3.12", "--seed"], { cwd: root, stdio: "inherit" });
-    } else if (hasBin("conda")) {
-      spawnSync("conda", ["create", "-p", venv, "python=3.12", "-y", "--quiet"], { cwd: root, stdio: "inherit" });
-    } else if (hasBin("python3.12")) {
-      spawnSync("python3.12", ["-m", "venv", venv], { cwd: root, stdio: "inherit" });
-    } else {
-      throw new Error(
-        "Python 3.12 not found.\n" +
-        "  The rainbow SDK requires Python >=3.12,<3.13.\n" +
-        "  Install Python 3.12: https://www.python.org/downloads/release/python-3120/\n" +
-        "  Or use uv (recommended): https://docs.astral.sh/uv/getting-started/installation/"
-      );
-    }
-  }
+  pyAssertDockerReady();
+  pyEnsureImage();
 
-  const reqs = resolve(root, "requirements.txt");
-  if (existsSync(reqs)) {
-    log.step("pip install -r requirements.txt…");
-    spawnSync(py, ["-m", "pip", "install", "-q", "--no-cache-dir", "-r", reqs], { cwd: root, stdio: "inherit" });
-  }
+  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 });
 
-  log.step("pip install -q watchfiles (dev reloader)…");
-  spawnSync(py, ["-m", "pip", "install", "-q", "watchfiles"], { cwd: root, stdio: "inherit" });
+  // 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.");
 
-  const pluginId = readManifest(root).id ?? "";
-  const backEnv = { ...process.env, ...(pluginId ? { RB_PLUGIN_ID: pluginId } : {}) };
-  if (pluginId) log.step(`RB_PLUGIN_ID=${pluginId}`);
+  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(
-    py,
-    ["-m", "watchfiles", "--filter", "python", "--target-type", "command", `${py} py/main.py`, "py"],
-    { cwd: root, stdio: "inherit", env: backEnv },
+    "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"] },
   );
-  const cleanup = () => { if (!child.killed) child.kill(); };
-  child.on("exit", (code) => process.exit(code ?? 0));
+  // 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);
+    }
+  });
+
+  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);
 }
@@ -85,7 +112,9 @@ function runRos2(root) {
 
   ensureImage();
 
-  const pluginId = readManifest(root).id ?? "";
+  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 = {}) =>
@@ -118,14 +147,15 @@ function runRos2(root) {
   };
   startNode();
 
-  // restart node on source change; rebuild only when package metadata changes
+  // 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) {
-        log.info("package metadata changed — colcon rebuild…");
+      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…");
@@ -147,6 +177,73 @@ function runRos2(root) {
   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;
@@ -155,9 +252,11 @@ function warnManifest(root) {
 }
 
 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/manifest.mjs

@@ -4,7 +4,7 @@ import { resolve } from "node:path";
 
 export const CONTRIBUTION_POINTS = ["program.command", "toolbar", "move.rnb"];
 const ICON_SIZES = ["16", "48", "128"];
-const RUNTIME_TYPES = ["none", "python", "ros2"];
+const RUNTIME_TYPES = ["none", "python", "cpp", "ros2"];
 const ROS_CLIENTS = ["rclpy", "rclcpp"];
 const I18N_LANGS = ["ko", "en", "ja", "zh", "vi", "th", "es"];
 const TARGET_CATEGORIES = ["manipulate", "amr", "rby1", "vision"];
@@ -66,6 +66,8 @@ function validateRuntime(runtime, errors) {
     errors.push(`runtime.type must be one of ${RUNTIME_TYPES.map((t) => `"${t}"`).join(" | ")}`);
   if (runtime.type === "python" && !runtime.entry)
     errors.push("runtime.entry is required for python runtime");
+  if (runtime.type === "cpp" && !runtime.entry)
+    errors.push("runtime.entry is required for cpp runtime (the built executable name)");
   if (runtime.type === "ros2") {
     if (!runtime.package) errors.push("runtime.package is required for ros2 runtime");
     if (!runtime.launch) errors.push("runtime.launch is required for ros2 runtime");
@@ -136,6 +138,10 @@ export function validateManifest(manifest) {
   }
   if (typeof manifest.author !== "string" || manifest.author.length === 0)
     errors.push(`"author" is required`);
+  if (typeof manifest.email !== "string" || manifest.email.length === 0)
+    errors.push(`"email" is required`);
+  if (manifest.company !== undefined && manifest.company !== null && typeof manifest.company !== "string")
+    errors.push(`"company" must be a string`);
 
   const hasModels = manifest.targetModels !== undefined && manifest.targetModels !== null;
   const hasCategorys = manifest.targetCategorys !== undefined && manifest.targetCategorys !== null;