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

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/devUi.mjs

@@ -13,6 +13,10 @@ const PREVIEW_PKG = "@rainbow-robotics/preview-host";
 const CACHE_DIR = resolve(homedir(), ".muscat-pk");
 const CACHE_ROOT = resolve(CACHE_DIR, "node_modules", "@rainbow-robotics", "preview-host");
 
+// Dev builds go to a throwaway dir, not dist/ — dist/ is reserved for
+// build/pack output (the shippable artifact).
+const DEV_OUT = ".muscat-dev";
+
 function findNodeBin() {
   if (typeof Bun === "undefined") return process.execPath;
   for (const c of ["node", "node20", "node18"]) {
@@ -52,14 +56,14 @@ function findPreviewHostRoot() {
   return CACHE_ROOT;
 }
 
-// Write sandbox.html + copy manifest into dist/ (vite doesn't generate these).
+// Write sandbox.html + copy manifest into the dev out dir (vite doesn't generate these).
 function stageDevAssets(pluginRoot) {
-  const distDir = resolve(pluginRoot, "dist");
-  mkdirSync(distDir, { recursive: true });
-  writeFileSync(resolve(distDir, "sandbox.html"), SANDBOX_HTML, "utf8");
+  const outDir = resolve(pluginRoot, DEV_OUT);
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(resolve(outDir, "sandbox.html"), SANDBOX_HTML, "utf8");
   const manifestSrc = resolve(pluginRoot, "manifest.json");
-  if (existsSync(manifestSrc)) copyFileSync(manifestSrc, resolve(distDir, "manifest.json"));
-  return distDir;
+  if (existsSync(manifestSrc)) copyFileSync(manifestSrc, resolve(outDir, "manifest.json"));
+  return outDir;
 }
 
 // Resolve vite bin path from the plugin root, hoisting-aware.
@@ -79,8 +83,8 @@ function spawnViteWatch(pluginRoot, node) {
   const viteBin = findViteBin(pluginRoot);
   if (!node || !viteBin || !existsSync(viteBin)) return null;
 
-  log.step("vite build --watch (ui/content.tsx → dist/content.js)");
-  return spawn(node, [viteBin, "build", "--watch", "--mode", "development"], {
+  log.step(`vite build --watch (ui/content.tsx → ${DEV_OUT}/content.js)`);
+  return spawn(node, [viteBin, "build", "--watch", "--mode", "development", "--outDir", DEV_OUT], {
     cwd: pluginRoot,
     stdio: "inherit",
   });
@@ -106,14 +110,14 @@ export async function runDevUi(args = []) {
 
   await checkKitUpdate();
   const pluginRoot = findPluginRoot();
-  const distDir = stageDevAssets(pluginRoot);
+  const outDir = stageDevAssets(pluginRoot);
 
   const node = findNodeBin();
   const viteProc = spawnViteWatch(pluginRoot, node);
 
   if (viteProc) {
     log.step("waiting for initial vite build…");
-    await waitForInitialBuild(distDir);
+    await waitForInitialBuild(outDir);
   } else {
     log.warn("vite not found — UI will not be bundled. Run `npm install` in the plugin project.");
   }
@@ -133,7 +137,7 @@ export async function runDevUi(args = []) {
   log.step(`starting preview-host on :${port}`);
   const child = spawn(
     node ?? process.execPath,
-    [serveEntry, "--plugin", distDir, "--port", String(port)],
+    [serveEntry, "--plugin", outDir, "--port", String(port)],
     { stdio: "inherit" },
   );
 

package/cli/src/manifest.mjs

@@ -4,9 +4,10 @@ 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"];
 
 function validateI18nLabel(value, field, errors) {
   if (value === undefined || value === null) {
@@ -15,7 +16,7 @@ function validateI18nLabel(value, field, errors) {
   }
   if (typeof value === "string") return;
   if (typeof value === "object") {
-    if (typeof value.en !== "string" || value.en.length === 0)
+    if (typeof value.en !== "string")
       errors.push(`${field}: "en" is required when using object form`);
     const unknown = Object.keys(value).filter((k) => !I18N_LANGS.includes(k));
     if (unknown.length > 0)
@@ -65,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");
@@ -133,8 +136,34 @@ export function validateManifest(manifest) {
     if (typeof manifest[key] !== "string" || manifest[key].length === 0)
       errors.push(`"${key}" is required`);
   }
-  if (typeof manifest.author !== "string")
-    errors.push(`"author" is required (empty string is allowed)`);
+  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;
+  if (!hasModels && !hasCategorys) {
+    errors.push(`"targetModels" or "targetCategorys" is required`);
+  } else {
+    if (hasModels) {
+      if (manifest.targetModels !== "all" && (!Array.isArray(manifest.targetModels) || manifest.targetModels.length === 0))
+        errors.push(`"targetModels" must be "all" or a non-empty array of model strings`);
+      else if (Array.isArray(manifest.targetModels) && manifest.targetModels.some((m) => typeof m !== "string"))
+        errors.push(`"targetModels": all entries must be strings`);
+    }
+    if (hasCategorys) {
+      if (manifest.targetCategorys !== "all" && (!Array.isArray(manifest.targetCategorys) || manifest.targetCategorys.length === 0))
+        errors.push(`"targetCategorys" must be "all" or a non-empty array`);
+      else if (Array.isArray(manifest.targetCategorys)) {
+        const invalid = manifest.targetCategorys.filter((c) => !TARGET_CATEGORIES.includes(c));
+        if (invalid.length > 0)
+          errors.push(`"targetCategorys": invalid value(s) ${invalid.map((c) => `"${c}"`).join(", ")} — allowed: ${TARGET_CATEGORIES.join(", ")}`);
+      }
+    }
+  }
   validateI18nLabel(manifest.description, "description", errors);
 
   validateIcons(manifest.icons, errors);

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", ".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,59 +223,27 @@ 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}`);
   log.info(`  muscat-pk dev      # preview in mini-Muscat + back end`);
-  log.info(`  muscat-pk pack     # build a distributable ZIP\n`);
+  log.info(`  muscat-pk build    # build + distributable ZIP\n`);
 
   // ── 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.");
+}