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

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;

package/cli/src/new.mjs

@@ -1,5 +1,5 @@
 // muscat-pk new — scaffold a new plugin project from templates.
-import { execFileSync, execSync } from "node:child_process";
+import { execSync } from "node:child_process";
 import {
   cpSync,
   existsSync,
@@ -12,11 +12,35 @@ import {
 } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { basename, resolve } from "node:path";
-import { detectPythonCmd, hasBin, kitVersion, parseArgs, templatesDir, log, venvPython } from "./util.mjs";
-
-const TYPES = ["python", "ros2"];
+import { rmSync } from "node:fs";
+import { hasBin, kitVersion, parseArgs, templatesDir, log } from "./util.mjs";
+
+// `--type` values map to a runtime descriptor. ros2 has a python (rclpy) and a
+// C++ (rclcpp) flavor; we expose them as distinct type choices for clarity.
+export const TYPE_CHOICES = {
+  python:    { type: "python" },
+  cpp:       { type: "cpp" },
+  ros2:      { type: "ros2", rosClient: "rclpy" },
+  "ros2-cpp":{ type: "ros2", rosClient: "rclcpp" },
+};
+const TYPES = Object.keys(TYPE_CHOICES);
 const PMS = ["npm", "yarn", "pnpm", "bun"];
 
+// Build the manifest runtime object for a given type choice + plugin slug.
+export function runtimeForChoice(choice, slug) {
+  switch (choice.type) {
+    case "cpp":
+      // entry = built executable name (matches add_executable in cpp/CMakeLists.txt)
+      return { type: "cpp", entry: slug };
+    case "ros2":
+      // package = colcon package name; launch = node executable run on the robot
+      return { type: "ros2", rosClient: choice.rosClient, package: slug, launch: `${slug}_node` };
+    case "python":
+    default:
+      return { type: "python", entry: "main.py" };
+  }
+}
+
 async function prompt(question, fallback) {
   if (!process.stdin.isTTY) return fallback;
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -74,16 +98,25 @@ function renameSlugPaths(dir, slug) {
 // Copy the ros2_ws/ overlay into a plugin and substitute the package slug into
 // every path segment. The dev Dockerfile is NOT scaffolded here — it lives in
 // the kit (cli/docker/) so authors can't edit it. Caller runs applyTokens after.
-export function overlayRos2(target, slug) {
-  cpSync(resolve(templatesDir, "ros2"), target, { recursive: true });
+//   rclpy  → templates/ros2      (ament_python)
+//   rclcpp → templates/ros2-cpp  (ament_cmake)
+export function overlayRos2(target, slug, rosClient = "rclpy") {
+  const tmpl = rosClient === "rclcpp" ? "ros2-cpp" : "ros2";
+  cpSync(resolve(templatesDir, tmpl), target, { recursive: true });
   renameSlugPaths(resolve(target, "ros2_ws"), slug);
 }
 
+// Copy the cpp/ overlay (CMake project) into a plugin. Caller runs applyTokens after.
+export function overlayCpp(target) {
+  cpSync(resolve(templatesDir, "cpp"), target, { recursive: true });
+}
+
 export async function runNew(args) {
   const opts = parseArgs(args, { booleans: ["yes", "no-install", "help"] });
   if (opts.help) {
     console.log(
-      "muscat-pk new [dir] [--type python|ros2] [--pm npm|yarn|pnpm|bun]\n" +
+      "muscat-pk new [dir] [--type python|cpp|ros2|ros2-cpp] [--pm npm|yarn|pnpm|bun]\n" +
+        "                 [--author <name>] [--email <email>] [--description <text>]\n" +
         "                 [--yes] [--no-install]",
     );
     return;
@@ -97,15 +130,28 @@ export async function runNew(args) {
     throw new Error(`directory not empty: ${target}`);
   }
 
+  let authorArg = opts.author;
+  let emailArg = opts.email;
+  let descriptionArg = opts.description;
+
+  if (!opts.yes) {
+    if (!authorArg) authorArg = await prompt("Author name: ", "");
+    if (!emailArg) emailArg = await prompt("Email (required): ", "");
+    if (!descriptionArg) descriptionArg = await prompt("Description (English): ", "");
+  }
+
   let type = opts.type;
   if (!type && !opts.yes) {
     console.log("\n플러그인 타입을 선택하세요:");
     console.log("  1) Python");
-    console.log("  2) ROS2(rclpy)");
-    const choice = await prompt("\n선택 [1/2, default: 1]: ", "1");
-    type = choice === "2" ? "ros2" : "python";
+    console.log("  2) C++");
+    console.log("  3) ROS2 (rclpy / Python)");
+    console.log("  4) ROS2 (rclcpp / C++)");
+    const choice = await prompt("\n선택 [1/2/3/4, default: 1]: ", "1");
+    type = { "2": "cpp", "3": "ros2", "4": "ros2-cpp" }[choice] ?? "python";
   }
   type = TYPES.includes(type) ? type : "python";
+  const runtimeChoice = TYPE_CHOICES[type];
 
   // Auto-detect yarn workspace: if .yarnrc.yml exists anywhere up the tree, default to yarn.
   function isInsideYarnWorkspace(dir) {
@@ -121,7 +167,7 @@ export async function runNew(args) {
   let pm = opts.pm;
   if (!pm && !opts.yes) {
     const defaultPm = isInsideYarnWorkspace(process.cwd()) ? "yarn" : "npm";
-    pm = await prompt(`Package manager (${PMS.join("/")}) [${defaultPm}]: `, defaultPm);
+    pm = await prompt(`Front-end package manager (${PMS.join("/")}) [${defaultPm}]: `, defaultPm);
   }
   pm = PMS.includes(pm) ? pm : "npm";
 
@@ -129,11 +175,18 @@ export async function runNew(args) {
 
   mkdirSync(target, { recursive: true });
 
-  // common(UI + main.py + requirements.txt + manifest/config)은 항상 포함.
-  // ros2면 ros2_ws/ 오버레이만 추가로 얹는다. python은 ros2_ws/가 없을 뿐 구조는 동일.
+  // common(UI + manifest/config)은 항상 포함. 백엔드 오버레이는 타입별로 얹는다.
+  //   python   → common의 py/ 사용
+  //   cpp      → cpp/ 오버레이, py/·requirements.txt 제거
+  //   ros2(*)  → ros2_ws/ 오버레이 (rclpy=ament_python, rclcpp=ament_cmake)
   log.step(`scaffolding ${type} plugin → ${target}`);
   cpSync(resolve(templatesDir, "common"), target, { recursive: true });
-  if (type === "ros2") overlayRos2(target, slug);
+  if (runtimeChoice.type === "ros2") overlayRos2(target, slug, runtimeChoice.rosClient);
+  if (runtimeChoice.type === "cpp") {
+    overlayCpp(target);
+    rmSync(resolve(target, "py"), { recursive: true, force: true });
+    rmSync(resolve(target, "requirements.txt"), { force: true });
+  }
 
   applyTokens(target, {
     __PLUGIN_ID__: pluginId,
@@ -141,15 +194,24 @@ export async function runNew(args) {
     __PLUGIN_DIR__: dir,
     __PLUGIN_SLUG__: slug,
     __PLUGIN_CLASS__: pluginClass,
+    __PLUGIN_AUTHOR__: authorArg || "",
+    __PLUGIN_EMAIL__: emailArg || "",
     __PM__: pm,
-    __RUNTIME_TYPE__: type,
+    __RUNTIME_TYPE__: runtimeChoice.type,
     __RB_VERSION__: kitVersion(),
   });
 
+  // Write the correct runtime block into manifest.json (per-type fields).
+  const manifestPath = resolve(target, "manifest.json");
+  const manifestJson = JSON.parse(readFileSync(manifestPath, "utf8"));
+  manifestJson.runtime = runtimeForChoice(runtimeChoice, slug);
+  if (descriptionArg) manifestJson.description = { en: descriptionArg };
+  writeFileSync(manifestPath, JSON.stringify(manifestJson, null, 2) + "\n");
+
   // gitignore (templates can't ship a literal .gitignore via npm reliably)
   writeFileSync(
     resolve(target, ".gitignore"),
-    ["node_modules", "dist", ".muscat-dev", ".venv", "*.zip", "ros2_ws/install", ""].join("\n"),
+    ["node_modules", "dist", ".muscat-dev", ".venv", "*.zip", "ros2_ws/install", "cpp/build", ""].join("\n"),
   );
 
   if (!opts["no-install"]) {
@@ -161,38 +223,10 @@ export async function runNew(args) {
     }
   }
 
-  let noPython = false;
-  let venvFailed = false;
-
-  if (!opts["no-install"]) {
-    // Python venv (robot targets 3.12) — cross-platform.
-    // uv is preferred: handles uv-managed Pythons that break standard ensurepip.
-    try {
-      const venv = resolve(target, ".venv");
-      log.step("creating .venv + installing requirements…");
-      if (hasBin("uv")) {
-        execFileSync("uv", ["venv", venv, "--python", "3.12", "--seed"], { cwd: target, stdio: "inherit" });
-      } else if (hasBin("conda")) {
-        execFileSync("conda", ["create", "-p", venv, "python=3.12", "-y", "--quiet"], { cwd: target, stdio: "inherit" });
-      } else if (hasBin("python3.12") || hasBin("python3") || hasBin("python")) {
-        const { cmd, is312 } = detectPythonCmd();
-        if (!is312) log.warn("python3.12 not found; venv uses fallback python (robot targets 3.12).");
-        execFileSync(cmd[0], [...cmd.slice(1), "-m", "venv", venv], { cwd: target, stdio: "inherit" });
-      } else {
-        noPython = true;
-      }
-      if (!noPython) {
-        const py = venvPython(venv);
-        if (existsSync(resolve(target, "requirements.txt"))) {
-          execFileSync(py, ["-m", "pip", "install", "-q", "-r", "requirements.txt"], { cwd: target, stdio: "inherit" });
-        }
-      }
-    } catch {
-      venvFailed = true;
-    }
-  } else {
-    noPython = !hasBin("uv") && !hasBin("conda") && !hasBin("python3.12") && !hasBin("python3") && !hasBin("python");
-  }
+  // The back end (python / cpp / ros2) runs in a Docker container that matches
+  // the robot — no local Python/toolchain setup needed. Only `none` skips it.
+  const needsDocker = runtimeChoice.type !== "none";
+  const noDocker = needsDocker && !hasBin("docker");
 
   log.ok(`created ${targetName} (type: ${type}, pm: ${pm})`);
   log.info(`\n  cd ${targetName}`);
@@ -201,19 +235,15 @@ export async function runNew(args) {
 
   // ── post-scaffold environment warnings ───────────────────────────────────
   const noNode = !hasBin("node");
-  if (noNode || noPython || venvFailed) {
+  if (noNode || noDocker) {
     log.info("");
     if (noNode) {
       log.warn("Node.js not found. Install Node.js 20+ to run JS deps and dev:ui.");
       log.warn("  https://nodejs.org");
     }
-    if (noPython) {
-      log.warn("Python not found. Install Python 3.12 to run the backend.");
-      log.warn("  https://www.python.org/downloads/  (or: brew install python@3.12 / uv / conda)");
-      log.warn(`  Then: cd ${targetName} && python3.12 -m venv .venv && pip install -r requirements.txt`);
-    } else if (venvFailed) {
-      log.warn("venv setup failed. Create it manually:");
-      log.warn(`  cd ${targetName} && python3.12 -m venv .venv && pip install -r requirements.txt`);
+    if (noDocker) {
+      log.warn("Docker not found. The plugin back end runs in a container (matches the robot env).");
+      log.warn("  https://docs.docker.com/get-docker/");
     }
     log.info("");
   }

package/cli/src/python.mjs

@@ -0,0 +1,31 @@
+// Shared Python Docker helpers (Ubuntu 24.04 + Python 3.12 — matches the robot).
+// Used by dev:back so the dev backend runs in the same environment as the robot.
+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 PYTHON_DEV_IMAGE = "muscat-pk-python-dev";
+
+// Dockerfile lives inside the kit — plugin authors never see or edit it.
+const DOCKERFILE = resolve(kitRoot, "cli/docker/Dockerfile.python");
+
+export function assertDockerReady() {
+  if (!hasBin("docker")) {
+    throw new Error("Docker not found. The Python backend runs in a container (Ubuntu 24.04 + Python 3.12).");
+  }
+  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 = PYTHON_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.");
+}

package/cli/src/socketBridge.mjs

@@ -1,7 +1,14 @@
 import { createServer } from "node:http";
 import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import { Server } from "socket.io";
-import { log } from "./util.mjs";
+
+// Self-contained logger — this module also runs standalone inside the bridge
+// Docker container, where ./util.mjs is not available.
+const log = {
+  step: (...m) => console.log("›", ...m),
+  warn: (...m) => console.warn("⚠", ...m),
+};
 
 const DEFAULT_ACTION_TIMEOUT_MS = 10_000;
 
@@ -114,3 +121,9 @@ export function startSocketBridge({ port = 10000, host = "0.0.0.0" } = {}) {
     });
   });
 }
+
+// When executed directly (inside the bridge Docker container), start the server.
+if (process.argv[1] && process.argv[1] === fileURLToPath(import.meta.url)) {
+  const port = Number(process.env.PORT) || 10000;
+  startSocketBridge({ port });
+}

package/cli/src/type.mjs

@@ -1,13 +1,21 @@
 // muscat-pk type change — switch an existing plugin's backend type.
-//   python ↔ ros2.  python→ros2 adds the ros2_ws/ overlay; ros2→python flips
-//   the manifest type and leaves ros2_ws/ in place (never deletes user code).
+//   python | cpp | ros2 (rclpy) | ros2-cpp (rclcpp).
+//   Adds the matching backend overlay; never deletes existing user code
+//   (e.g. ros2_ws/ or cpp/ are left in place when switching away).
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { basename, resolve } from "node:path";
 import { findPluginRoot, log } from "./util.mjs";
-import { applyTokens, deriveNames, overlayRos2 } from "./new.mjs";
+import {
+  TYPE_CHOICES,
+  applyTokens,
+  deriveNames,
+  overlayCpp,
+  overlayRos2,
+  runtimeForChoice,
+} from "./new.mjs";
 
-const TYPES = ["python", "ros2"];
+const TYPES = Object.keys(TYPE_CHOICES);
 
 async function prompt(question, fallback) {
   if (!process.stdin.isTTY) return fallback;
@@ -23,44 +31,54 @@ function readManifest(root) {
   return { path, json: JSON.parse(readFileSync(path, "utf8")) };
 }
 
+// Derive the current `--type`-style key from a manifest runtime block.
+function currentTypeKey(runtime) {
+  if (runtime?.type === "ros2") return runtime.rosClient === "rclcpp" ? "ros2-cpp" : "ros2";
+  return runtime?.type ?? "python";
+}
+
 export async function runType(args) {
-  // accept `type change`, `type`, `type --to ros2`
+  // accept `type change`, `type`, `type --to ros2-cpp`
   const sub = args[0];
   const toFlagIdx = args.indexOf("--to");
   let to = toFlagIdx >= 0 ? args[toFlagIdx + 1] : undefined;
 
   const root = findPluginRoot();
   const { path, json } = readManifest(root);
-  const current = json.runtime?.type ?? "python";
+  const current = currentTypeKey(json.runtime);
 
   if (sub && sub !== "change") {
-    log.warn(`unknown subcommand '${sub}'. Usage: muscat-pk type change [--to python|ros2]`);
+    log.warn(`unknown subcommand '${sub}'. Usage: muscat-pk type change [--to python|cpp|ros2|ros2-cpp]`);
   }
 
   if (!to) {
     console.log(`\n현재 타입: ${current}`);
     console.log("변경할 타입을 선택하세요:");
     console.log("  1) Python");
-    console.log("  2) ROS2(rclpy)");
-    const choice = await prompt("\n선택 [1/2]: ", "");
-    to = choice === "1" ? "python" : choice === "2" ? "ros2" : undefined;
+    console.log("  2) C++");
+    console.log("  3) ROS2 (rclpy / Python)");
+    console.log("  4) ROS2 (rclcpp / C++)");
+    const choice = await prompt("\n선택 [1/2/3/4]: ", "");
+    to = { "1": "python", "2": "cpp", "3": "ros2", "4": "ros2-cpp" }[choice];
   }
 
   if (!TYPES.includes(to)) {
-    throw new Error(`invalid type. choose python or ros2.`);
+    throw new Error(`invalid type. choose python | cpp | ros2 | ros2-cpp.`);
   }
   if (to === current) {
     log.info(`already '${current}' — nothing to change.`);
     return;
   }
 
-  if (to === "ros2") {
-    const { slug, pluginName, pluginClass, pluginId } = deriveNames(root);
+  const runtimeChoice = TYPE_CHOICES[to];
+  const { slug, pluginName, pluginClass, pluginId } = deriveNames(root);
+
+  if (runtimeChoice.type === "ros2") {
     if (existsSync(resolve(root, "ros2_ws"))) {
       log.warn("ros2_ws/ already exists — keeping it, only flipping manifest type.");
     } else {
-      log.step("adding ros2_ws/ overlay");
-      overlayRos2(root, slug);
+      log.step(`adding ros2_ws/ overlay (${runtimeChoice.rosClient})`);
+      overlayRos2(root, slug, runtimeChoice.rosClient);
       applyTokens(root, {
         __PLUGIN_ID__: pluginId,
         __PLUGIN_NAME__: pluginName,
@@ -69,14 +87,28 @@ export async function runType(args) {
         __RUNTIME_TYPE__: "ros2",
       });
     }
+  } else if (runtimeChoice.type === "cpp") {
+    if (existsSync(resolve(root, "cpp"))) {
+      log.warn("cpp/ already exists — keeping it, only flipping manifest type.");
+    } else {
+      log.step("adding cpp/ overlay");
+      overlayCpp(root);
+      applyTokens(root, {
+        __PLUGIN_ID__: pluginId,
+        __PLUGIN_NAME__: pluginName,
+        __PLUGIN_SLUG__: slug,
+        __PLUGIN_CLASS__: pluginClass,
+        __RUNTIME_TYPE__: "cpp",
+      });
+    }
   } else {
-    // ros2 → python
-    if (existsSync(resolve(root, "ros2_ws"))) {
-      log.warn("ros2_ws/ left in place (not deleted). Remove it manually if unused.");
+    // → python. Leave any ros2_ws/ or cpp/ in place (never delete user code).
+    if (existsSync(resolve(root, "ros2_ws")) || existsSync(resolve(root, "cpp"))) {
+      log.warn("existing backend dir left in place (not deleted). Remove it manually if unused.");
     }
   }
 
-  json.runtime = { ...json.runtime, type: to };
+  json.runtime = runtimeForChoice(runtimeChoice, slug);
   writeFileSync(path, JSON.stringify(json, null, 2) + "\n");
   log.ok(`${basename(root)} type: ${current} → ${to}`);
 }

package/cli/src/util.mjs

@@ -91,6 +91,16 @@ export const log = {
   error: (...m) => console.error(`${RED}✖${RESET}`, ...m.map(s => `${RED}${s}${RESET}`)),
 };
 
+// dev / dev:back / build run the plugin back end, the dev bridge, and cpp/ros2
+// compilation in Docker. Show a clear install hint when Docker is missing.
+export function ensureDocker() {
+  if (hasBin("docker")) return;
+  log.warn("Docker not found.");
+  log.warn("  muscat-pk runs the plugin back end, the dev bridge, and cpp/ros2 builds in Docker.");
+  log.warn("  Install Docker, then retry: https://docs.docker.com/get-docker/");
+  throw new Error("Docker is required for dev / dev:back / build.");
+}
+
 export function humanSize(bytes) {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;

package/cli/templates/common/README.md

@@ -102,8 +102,9 @@ connect(App);
 ## Backend (`py/main.py`)
 
 The backend communicates with the frontend using `rainbow.rb_sdk.RBPluginCall`.
-`muscat-pk dev` starts the local Socket.IO bridge; `py/main.py` should contain plugin
-logic only and must not start its own server.
+`muscat-pk dev` starts the Socket.IO bridge in Docker (published on port 10000) and
+runs the backend container sharing its network, so the SDK connects at localhost:10000.
+`py/main.py` should contain plugin logic only and must not start its own server.
 
 ### Python plugin
 
@@ -230,11 +231,26 @@ class __PLUGIN_CLASS__Node(Node):
     }
   ],
 
-  // "none" | "python" | "ros2"
+  // runtime — one of:
+  //   { "type": "none" }
+  //   { "type": "python", "entry": "main.py" }
+  //   { "type": "cpp", "entry": "<executable name>" }
+  //   { "type": "ros2", "rosClient": "rclpy" | "rclcpp", "package": "...", "launch": "..._node" }
   "runtime": { "type": "python", "entry": "main.py" }
 }
 ```
 
+**Backend types:**
+
+| type | source dir | build / run | entry |
+|---|---|---|---|
+| `python` | `py/` | pip + run in Docker | `main.py` |
+| `cpp` | `cpp/` | CMake in Docker | built executable name |
+| `ros2` (rclpy) | `ros2_ws/` | colcon (ament_python) in Docker | — |
+| `ros2` (rclcpp) | `ros2_ws/` | colcon (ament_cmake) in Docker | — |
+
+> Every back end runs in a Docker container matching the robot (Ubuntu 24.04 + Python 3.12), so dev behaves like production and compiled binaries are ABI-compatible. **Docker is required** for all backend types (only a frontend-only `none` plugin skips it). No local Python/toolchain setup is needed.
+
 **Contribution points:**
 
 | point | Where it appears | `commandInfo` required |
@@ -306,24 +322,23 @@ numpy==1.26.4
 opencv-python
 ```
 
-Run `muscat-pk dev` or `muscat-pk dev:back` — dependencies are installed automatically on every startup.
-
-- **Python plugin**: installed into `.venv` via `pip install -r requirements.txt`
-- **ROS2 plugin**: installed inside the Docker container via `pip install -r requirements.txt`
+Run `muscat-pk dev` or `muscat-pk dev:back` — dependencies are installed automatically inside the dev container (`pip install -r requirements.txt`) on every startup. No local Python or venv needed.
 
-> `muscat-pk build` only **pins** versions in `requirements.txt` — it does not run `pip install`.
+> `muscat-pk build` only **pins** versions in `requirements.txt` — it does not run `pip install` (the robot installs them at load time).
 
 ---
 
 ## Switching backend type
 
 ```bash
-muscat-pk type change             # interactive
-muscat-pk type change --to ros2   # python → ros2
-muscat-pk type change --to python # ros2 → python
+muscat-pk type change                 # interactive
+muscat-pk type change --to cpp        # → C++
+muscat-pk type change --to ros2       # → ROS2 (rclpy / Python)
+muscat-pk type change --to ros2-cpp   # → ROS2 (rclcpp / C++)
+muscat-pk type change --to python     # → Python
 ```
 
-> `ros2_ws/` is not deleted when switching back to python. Remove it manually if no longer needed.
+> Existing backend dirs (`ros2_ws/`, `cpp/`) are not deleted when switching away. Remove them manually if no longer needed.
 
 ---
 

package/cli/templates/common/manifest.json

@@ -3,7 +3,8 @@
   "name": "__PLUGIN_NAME__",
   "version": "1.0.0",
   "minMuscatVersion": "1.0.0",
-  "author": "",
+  "author": "__PLUGIN_AUTHOR__",
+  "email": "__PLUGIN_EMAIL__",
   "description": {
     "ko": "",
     "en": ""

package/cli/templates/cpp/cpp/CMakeLists.txt

@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 3.16)
+project(__PLUGIN_SLUG__ CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# The executable name must match runtime.entry in manifest.json.
+add_executable(__PLUGIN_SLUG__ main.cpp)
+
+# TODO(cpp-sdk): link the rainbow cpp SDK dynamically (the robot provides the
+# .so at runtime — do NOT bundle/static-link it). Once the SDK ships an apt
+# package with CMake config, enable:
+#   find_package(rainbow_cpp_sdk REQUIRED)
+#   target_link_libraries(__PLUGIN_SLUG__ PRIVATE rainbow::cpp_sdk)

package/cli/templates/cpp/cpp/main.cpp

@@ -0,0 +1,25 @@
+// __PLUGIN_NAME__ — C++ plugin back end.
+//
+// The C++ plugin SDK is not available yet, so this is a build/run skeleton.
+// Once the SDK lands, connect to the plugin gateway here (the host exposes it
+// at the RB_PLUGIN_GATEWAY / RB_PLUGIN_ID environment variables) and wire up
+// pub / sub / serve, mirroring the Python rainbow.rb_sdk.RBPluginCall API.
+
+#include <chrono>
+#include <cstdlib>
+#include <iostream>
+#include <thread>
+
+int main() {
+  const char* plugin_id = std::getenv("RB_PLUGIN_ID");
+  std::cout << "[__PLUGIN_NAME__] backend ready"
+            << (plugin_id ? std::string(" (id=") + plugin_id + ")" : "")
+            << std::endl;
+
+  // TODO: connect to the plugin gateway and register handlers once the
+  //       C++ SDK is available. For now, just keep the process alive.
+  while (true) {
+    std::this_thread::sleep_for(std::chrono::seconds(1));
+  }
+  return 0;
+}

package/cli/templates/ros2-cpp/ros2_ws/src/__PLUGIN_SLUG__/CMakeLists.txt

@@ -0,0 +1,17 @@
+cmake_minimum_required(VERSION 3.16)
+project(__PLUGIN_SLUG__)
+
+if(NOT CMAKE_CXX_STANDARD)
+  set(CMAKE_CXX_STANDARD 17)
+endif()
+
+find_package(ament_cmake REQUIRED)
+find_package(rclcpp REQUIRED)
+
+add_executable(__PLUGIN_SLUG___node src/node.cpp)
+ament_target_dependencies(__PLUGIN_SLUG___node rclcpp)
+
+install(TARGETS __PLUGIN_SLUG___node
+  DESTINATION lib/${PROJECT_NAME})
+
+ament_package()

package/cli/templates/ros2-cpp/ros2_ws/src/__PLUGIN_SLUG__/package.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0"?>
+<package format="3">
+  <name>__PLUGIN_SLUG__</name>
+  <version>0.0.1</version>
+  <description>__PLUGIN_NAME__ ROS2 node (rclcpp)</description>
+  <maintainer email="todo@example.com">maintainer</maintainer>
+  <license>Proprietary</license>
+  <buildtool_depend>ament_cmake</buildtool_depend>
+  <depend>rclcpp</depend>
+  <export><build_type>ament_cmake</build_type></export>
+</package>

package/cli/templates/ros2-cpp/ros2_ws/src/__PLUGIN_SLUG__/src/node.cpp

@@ -0,0 +1,22 @@
+// __PLUGIN_NAME__ — ROS2 node (rclcpp).
+//
+// The node is launched with `--ros-args -r __ns:=/{slug}` automatically by
+// dev:back. ROS2 topics are bridged to the plugin communication layer, so a
+// plain rclcpp node is all you need — relative topic names get the namespace
+// prefix applied automatically.
+#include "rclcpp/rclcpp.hpp"
+
+class __PLUGIN_CLASS__Node : public rclcpp::Node {
+public:
+  __PLUGIN_CLASS__Node() : Node("__PLUGIN_SLUG___node") {
+    RCLCPP_INFO(this->get_logger(), "__PLUGIN_NAME__ node started");
+    // create publishers / subscribers / services here
+  }
+};
+
+int main(int argc, char** argv) {
+  rclcpp::init(argc, argv);
+  rclcpp::spin(std::make_shared<__PLUGIN_CLASS__Node>());
+  rclcpp::shutdown();
+  return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainbow-robotics/muscat-plugin-kit",
-  "version": "0.1.2-dev.24",
+  "version": "0.1.2-dev.25",
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -31,7 +31,7 @@
     "@types/react-dom": "^19.0.4"
   },
   "dependencies": {
-    "@rainbow-robotics/preview-host": "0.1.2-dev.24",
+    "@rainbow-robotics/preview-host": "0.1.2-dev.25",
     "socket.io": "^4.8.1"
   },
   "optionalDependencies": {