@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.8 → 1.0.0

package/cli/src/python.mjs

@@ -0,0 +1,109 @@
+// Shared Python Docker helpers (Ubuntu 24.04 + Python 3.12 — matches the robot).
+// Used by dev:back (hot-reload) and build (lock + wheel vendor).
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+
+export const PYTHON_DEV_IMAGE = "muscat-pk-python-dev";
+
+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).");
+  }
+}
+
+/** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
+export async function ensureImage(image = PYTHON_DEV_IMAGE, { platform = null } = {}) {
+  const dockerfile = await resolveDockerfile("Dockerfile.python");
+  log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
+  const platformFlags = platform ? ["--platform", platform] : [];
+  const r = spawnSync(
+    "docker",
+    ["build", ...platformFlags, "-t", image, "-f", dockerfile, dirname(dockerfile)],
+    { stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error("docker build failed.");
+  pruneMuskatImages();
+}
+
+// pip --platform does NOT auto-expand manylinux tags (unlike sys_tags()) — exact match only.
+// Specifying all common glibc milestones ensures packages built for any Ubuntu era are found.
+const PIP_PLATFORM = {
+  amd64: [
+    "manylinux_2_5_x86_64",
+    "manylinux_2_17_x86_64",
+    "manylinux_2_27_x86_64",
+    "manylinux_2_28_x86_64",
+    "manylinux_2_34_x86_64",
+    "manylinux_2_39_x86_64",
+    "linux_x86_64",
+  ],
+  arm64: [
+    "manylinux_2_17_aarch64",
+    "manylinux_2_27_aarch64",
+    "manylinux_2_28_aarch64",
+    "manylinux_2_34_aarch64",
+    "manylinux_2_39_aarch64",
+    "linux_aarch64",
+  ],
+};
+
+export async function lockAndVendor(pluginRoot, archs = ["amd64", "arm64"]) {
+  // ponytail: pip --platform used intentionally (not QEMU) — downloads wheels without running target arch code.
+  const reqTxt = resolve(pluginRoot, "requirements.txt");
+  if (!existsSync(reqTxt)) {
+    log.warn("requirements.txt not found — lock/vendor skipped");
+    return;
+  }
+
+  await ensureImage();
+
+  log.step("generating lock (uv pip compile)…");
+  const lockResult = spawnSync(
+    "docker",
+    [
+      "run", "--rm",
+      "-v", `${pluginRoot}:/plugin`,
+      PYTHON_DEV_IMAGE,
+      "bash", "-c",
+      "set -e && cd /plugin && mkdir -p dist && uv pip compile requirements.txt --python-version 3.12 -o dist/requirements.lock",
+    ],
+    { stdio: "inherit" },
+  );
+  if (lockResult.status !== 0) throw new Error("lock generation failed (uv pip compile)");
+  log.ok("dist/requirements.lock ready");
+
+  const failed = [];
+  for (const arch of archs) {
+    const pipPlatforms = PIP_PLATFORM[arch];
+    if (!pipPlatforms) { log.warn(`unknown arch '${arch}' — skipped`); continue; }
+    log.step(`vendoring wheels for ${arch}…`);
+    const r = spawnSync(
+      "docker",
+      [
+        "run", "--rm",
+        "-e", "PIP_ROOT_USER_ACTION=ignore",
+        "-v", `${pluginRoot}:/plugin`,
+        "-w", "/plugin",
+        PYTHON_DEV_IMAGE,
+        "bash", "-c",
+        "mkdir -p dist/wheels && pip3 download -r dist/requirements.lock --no-deps --only-binary=:all: -d dist/wheels -q " +
+          "--python-version 312 --implementation cp --abi cp312 " +
+          pipPlatforms.map((p) => `--platform ${p}`).join(" "),
+      ],
+      { stdio: "inherit" },
+    );
+    if (r.status !== 0) {
+      log.warn(`wheel vendoring failed for ${arch}`);
+      failed.push(arch);
+    } else {
+      log.ok(`dist/wheels/ ready (${arch})`);
+    }
+  }
+
+  if (failed.length === archs.length) {
+    throw new Error(`wheel vendoring failed for all archs: ${failed.join(", ")}`);
+  }
+  return failed;
+}

package/cli/src/ros2.mjs

@@ -3,14 +3,10 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { hasBin, kitRoot, log } from "./util.mjs";
+import { hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
 
 export const ROS2_DEV_IMAGE = "muscat-pk-ros2-dev";
 
-// Dockerfile lives inside the kit — plugin authors never see or edit it.
-// It has no COPY/ADD, so the build context is irrelevant (its own dir is used).
-const DOCKERFILE = resolve(kitRoot, "cli/docker/Dockerfile.dev");
-
 /** First package directory under ros2_ws/src (the colcon package name). */
 export function ros2PackageName(root) {
   const srcDir = resolve(root, "ros2_ws/src");
@@ -25,20 +21,25 @@ export function assertDockerReady() {
   if (!hasBin("docker")) {
     throw new Error("Docker not found. ROS2 needs Docker (Jazzy + Python 3.12 container).");
   }
-  if (!existsSync(DOCKERFILE)) {
-    throw new Error(`kit Dockerfile missing at ${DOCKERFILE} (reinstall muscat-plugin-kit).`);
-  }
 }
 
+export const ARCH_DOCKER_PLATFORM = {
+  amd64: "linux/amd64",
+  arm64: "linux/arm64",
+};
+
 /** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
-export function ensureImage(image = ROS2_DEV_IMAGE) {
-  log.step(`docker build -t ${image} (first run is slow, then cached)…`);
+export async function ensureImage(image = ROS2_DEV_IMAGE, { platform = null } = {}) {
+  const dockerfile = await resolveDockerfile("Dockerfile.dev");
+  log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
+  const platformFlags = platform ? ["--platform", platform] : [];
   const r = spawnSync(
     "docker",
-    ["build", "-t", image, "-f", DOCKERFILE, dirname(DOCKERFILE)],
+    ["build", ...platformFlags, "-t", image, "-f", dockerfile, dirname(dockerfile)],
     { stdio: "inherit" },
   );
   if (r.status !== 0) throw new Error("docker build failed.");
+  pruneMuskatImages();
 }
 
 /**
@@ -46,20 +47,44 @@ export function ensureImage(image = ROS2_DEV_IMAGE) {
  * (the workspace is mounted). symlink=true for dev (fast, edit-in-place);
  * symlink=false for export builds that ship in the ZIP (real copies, relocatable).
  */
-export function colconBuild(root, { image = ROS2_DEV_IMAGE, symlink = false } = {}) {
+/**
+ * arch=null → dev mode, builds to ros2_ws/install/ (native)
+ * arch="amd64"|"arm64" → export mode, builds to ros2_ws/install-{arch}/ using arch-specific image
+ */
+/**
+ * symlink=true (dev): ros2_ws/install/ — local dev workspace, not for ZIP
+ * symlink=false, arch=null (rclpy export): dist/ros2_ws/install/
+ * symlink=false, arch="amd64"|"arm64" (rclcpp export): dist/ros2_ws/install-{arch}/
+ */
+export function colconBuild(root, { image = ROS2_DEV_IMAGE, symlink = false, arch = null } = {}) {
+  // paths are relative to ros2_ws/ inside the container
+  let installBase;
+  if (symlink) {
+    installBase = "install";
+  } else if (arch) {
+    installBase = `../dist/ros2_ws/install-${arch}`;
+  } else {
+    installBase = "../dist/ros2_ws/install";
+  }
   const flag = symlink ? "--symlink-install" : "";
   const script = [
-    // --ignore-installed: don't try to uninstall debian-managed packages
-    // (e.g. psutil), which fails with "RECORD file not found".
     "pip install -r requirements.txt --break-system-packages --ignore-installed -q || true",
     "cd ros2_ws",
-    `colcon build ${flag}`.trim(),
+    // ponytail: rm only on cross-arch; same-arch dev rebuilds keep the cache
+    ...(arch ? ["rm -rf build"] : []),
+    `colcon build ${flag} --install-base ${installBase}`.trim(),
   ].join(" && ");
-  log.step(`colcon build${symlink ? " --symlink-install" : ""} (in container)…`);
+  const label = arch
+    ? `colcon build (${arch}) → dist/ros2_ws/install-${arch}/…`
+    : `colcon build${symlink ? " --symlink-install" : ""} (in container)…`;
+  log.step(label);
+  const actualImage = arch ? `${ROS2_DEV_IMAGE}-${arch}` : image;
+  const dockerPlatform = arch ? ARCH_DOCKER_PLATFORM[arch] : null;
+  const platformFlags = dockerPlatform ? ["--platform", dockerPlatform] : [];
   const r = spawnSync(
     "docker",
-    ["run", "--rm", "-v", `${root}:/plugin`, "-w", "/plugin", image, "bash", "-lc", script],
+    ["run", "--rm", ...platformFlags, "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", actualImage, "bash", "-lc", script],
     { cwd: root, stdio: "inherit" },
   );
-  if (r.status !== 0) throw new Error("colcon build failed.");
+  if (r.status !== 0) throw new Error(`colcon build failed${arch ? ` (${arch})` : ""}.`);
 }

package/cli/src/sdk.mjs

@@ -1,8 +1,13 @@
 // muscat-pk sdk <list|update [version]> — manage the python rainbow-rb-sdk.
-import { spawnSync } from "node:child_process";
+//
+// Pins requirements.txt — the real install happens in the `dev`/`dev:back`
+// Docker container. If a local .venv exists (see devBack.mjs's syncIdeVenv,
+// for editor/linter support), also update it in place so pylint/pyright see
+// the new version immediately; this is best-effort only.
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { findPluginRoot, log } from "./util.mjs";
+import { spawnSync } from "node:child_process";
+import { findPluginRoot, log, venvPython } from "./util.mjs";
 
 const PKG = "rainbow-rb-sdk";
 
@@ -50,15 +55,12 @@ export async function runSdk(args = []) {
     writeFileSync(reqs, content);
     log.ok(`requirements.txt → ${line}`);
 
-    const py = resolve(root, ".venv", "bin", "python");
+    const py = venvPython(resolve(root, ".venv"));
     if (existsSync(py)) {
-      log.step("pip install -r requirements.txt…");
-      spawnSync(py, ["-m", "pip", "install", "-q", "-r", reqs], {
-        cwd: root,
-        stdio: "inherit",
-      });
+      log.step("pip install -r requirements.txt (.venv, for your editor)…");
+      spawnSync(py, ["-m", "pip", "install", "-q", "-r", reqs], { cwd: root, stdio: "inherit" });
     } else {
-      log.warn(".venv not found; run `muscat-pk dev:back` to install.");
+      log.info("Installed automatically on the next `muscat-pk dev` / `dev:back` (Docker container).");
     }
     return;
   }

package/cli/src/socketBridge.mjs

@@ -0,0 +1,133 @@
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { Server } from "socket.io";
+
+// 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;
+
+export function startSocketBridge({ port = 10000, host = "0.0.0.0" } = {}) {
+  const httpServer = createServer();
+  const io = new Server(httpServer, { cors: { origin: "*" } });
+
+  // topic → socketId (serve_register로 등록된 queryable)
+  const queryables = new Map();
+  // call_id → { timer, resolve } (action → serve_call → serve_reply 대기)
+  const pending = new Map();
+
+  function cleanupSocket(socket) {
+    for (const [topic, sid] of queryables) {
+      if (sid === socket.id) queryables.delete(topic);
+    }
+    for (const [id, p] of pending) {
+      if (p.sid !== socket.id) continue;
+      clearTimeout(p.timer);
+      p.resolve(undefined);
+      pending.delete(id);
+    }
+  }
+
+  io.on("connection", (socket) => {
+    socket.on("sub", async (data = {}) => {
+      if (!data.topic) return;
+      await socket.join(`t:${data.topic}`);
+    });
+
+    socket.on("unsub", async (data = {}) => {
+      if (!data.topic) return;
+      await socket.leave(`t:${data.topic}`);
+    });
+
+    socket.on("pub", (data = {}) => {
+      const { topic, payload } = data;
+      if (!topic) return;
+      io.to(`t:${topic}`).emit("msg", { topic, payload });
+    });
+
+    socket.on("serve_register", (data = {}) => {
+      if (!data.topic) return;
+      queryables.set(data.topic, socket.id);
+      log.step(`serve registered: ${data.topic}`);
+    });
+
+    socket.on("serve_unregister", (data = {}) => {
+      if (queryables.get(data.topic) === socket.id) queryables.delete(data.topic);
+      if (data.topic) log.step(`serve unregistered: ${data.topic}`);
+    });
+
+    socket.on("serve_reply", (data = {}) => {
+      const p = pending.get(data.id);
+      if (!p) return;
+      clearTimeout(p.timer);
+      p.resolve(data.payload);
+      pending.delete(data.id);
+    });
+
+    socket.on("action", (data = {}, ack) => {
+      const { topic, payload } = data;
+      const targetSid = queryables.get(topic);
+      const target = targetSid && io.sockets.sockets.get(targetSid);
+      if (!target) {
+        log.warn(`action has no handler: ${topic}`);
+        if (typeof ack === "function") ack({ error: `No handler registered for ${topic}` });
+        return;
+      }
+      log.step(`action: ${topic}`);
+      const id = randomUUID();
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        if (typeof ack === "function") ack(undefined);
+      }, DEFAULT_ACTION_TIMEOUT_MS);
+      pending.set(id, {
+        sid: targetSid,
+        timer,
+        resolve: (v) => { if (typeof ack === "function") ack(v); },
+      });
+      target.emit("serve_call", { id, topic, payload });
+    });
+
+    socket.on("disconnect", () => cleanupSocket(socket));
+  });
+
+  return new Promise((resolve) => {
+    httpServer.once("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        log.warn(`Socket.IO bridge already running on :${port} — skipping`);
+        io.close();
+        httpServer.close();
+        resolve({ close: () => {} });
+      } else {
+        throw err;
+      }
+    });
+
+    httpServer.listen(port, host, () => {
+      log.step(`Socket.IO bridge listening on ws://127.0.0.1:${port}`);
+
+      const close = () => {
+        for (const p of pending.values()) {
+          clearTimeout(p.timer);
+          p.resolve(undefined);
+        }
+        pending.clear();
+        queryables.clear();
+        io.close();
+        httpServer.close();
+      };
+
+      resolve({ close });
+    });
+  });
+}
+
+// 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/storybook.mjs

@@ -0,0 +1,168 @@
+// muscat-pk storybook — serve the bundled Storybook (foundations + muscat) so
+// plugin authors can browse the real rb-components UI while developing.
+//
+// The static build is produced from apps/storybook (MUSCAT_STORYBOOK=true → only
+// the 1.foundations + 4.muscat sections, ordering-number prefixes stripped) and
+// staged into cli/storybook-dist so it ships inside the published muscat-pk.
+// In the monorepo it's built on demand if missing (or with --rebuild).
+import { createServer } from "node:http";
+import {
+  cpSync,
+  createReadStream,
+  existsSync,
+  mkdirSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { execSync, spawn } from "node:child_process";
+import { copyFileSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+import { kitRoot, log, parseArgs } from "./util.mjs";
+
+// Shipped location (under cli/ → included in the npm "files" list).
+const SHIPPED_DIST = resolve(kitRoot, "cli/storybook-dist");
+// Raw .stories.tsx sources, staged alongside the compiled build — the `mcp`
+// command's get_component_example tool reads these directly (real usage
+// code, not just prop types) without needing a Storybook runtime.
+export const SHIPPED_STORIES_SRC = resolve(SHIPPED_DIST, "_stories-src");
+// Monorepo source (absent in an external install).
+const REPO_ROOT = resolve(kitRoot, "../..");
+const REPO_STORYBOOK = resolve(REPO_ROOT, "apps/storybook");
+const REPO_BUILD_OUT = resolve(REPO_STORYBOOK, "storybook-static-muscat");
+const REPO_MUSCAT_STORIES = resolve(REPO_STORYBOOK, "stories/4.muscat");
+const REPO_DESIGN_TOKENS = resolve(
+  REPO_ROOT,
+  "packages/rb-styles/css/output/rb-token.css",
+);
+// Generated Tailwind v4 token file (@theme colors + @utility typo-*), staged so
+// the `mcp` command's *_design_tokens tools work in an external install too.
+export const SHIPPED_DESIGN_TOKENS = resolve(SHIPPED_DIST, "_design-tokens.css");
+
+const CONTENT_TYPE = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".wasm": "application/wasm",
+};
+
+// Build apps/storybook (muscat subset) and stage it into cli/storybook-dist.
+// Monorepo only. Outside the monorepo (e.g. re-packing an already-published
+// copy) it's a no-op — the shipped cli/storybook-dist is already in place.
+export function buildStorybook() {
+  if (!existsSync(REPO_STORYBOOK)) {
+    log.info("apps/storybook not found — using the pre-staged storybook-dist.");
+    return;
+  }
+  log.step("building Storybook (foundations + muscat)…");
+  execSync("yarn workspace storybook storybook:build:muscat", {
+    cwd: REPO_ROOT,
+    stdio: "inherit",
+    env: { ...process.env, MUSCAT_STORYBOOK: "true" },
+  });
+  rmSync(SHIPPED_DIST, { recursive: true, force: true });
+  mkdirSync(SHIPPED_DIST, { recursive: true });
+  cpSync(REPO_BUILD_OUT, SHIPPED_DIST, { recursive: true });
+
+  // Stage raw .stories.tsx sources (not just the compiled JS bundle) for the
+  // `mcp` command's get_component_example tool.
+  if (existsSync(REPO_MUSCAT_STORIES)) {
+    cpSync(REPO_MUSCAT_STORIES, SHIPPED_STORIES_SRC, {
+      recursive: true,
+      filter: (src) => statSync(src).isDirectory() || src.endsWith(".stories.tsx"),
+    });
+  }
+
+  // Stage the design-token CSS for the `mcp` command's *_design_tokens tools.
+  if (existsSync(REPO_DESIGN_TOKENS)) {
+    copyFileSync(REPO_DESIGN_TOKENS, SHIPPED_DESIGN_TOKENS);
+  }
+
+  log.ok(`storybook → ${SHIPPED_DIST}`);
+}
+
+function openBrowser(url) {
+  const cmd =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "start"
+        : "xdg-open";
+  try {
+    spawn(cmd, [url], {
+      stdio: "ignore",
+      detached: true,
+      shell: process.platform === "win32",
+    }).unref();
+  } catch {
+    /* headless / no browser — the URL is printed anyway */
+  }
+}
+
+function serve(distDir, port) {
+  const server = createServer((req, res) => {
+    const url = decodeURIComponent((req.url || "/").split("?")[0]);
+    const rel = url === "/" ? "/index.html" : url;
+    const filePath = resolve(distDir, `.${rel}`);
+
+    // Serve the file if it's inside distDir and exists; otherwise fall back to
+    // index.html (Storybook is a single-page app).
+    if (
+      filePath.startsWith(distDir) &&
+      existsSync(filePath) &&
+      statSync(filePath).isFile()
+    ) {
+      const type = CONTENT_TYPE[extname(filePath)];
+      if (type) res.setHeader("Content-Type", type);
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      createReadStream(filePath).pipe(res);
+      return;
+    }
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    createReadStream(join(distDir, "index.html")).pipe(res);
+  });
+
+  server.on("error", (err) => {
+    if (err.code === "EADDRINUSE") {
+      log.error(`port ${port} is in use — pass a free one with --port <n>.`);
+      process.exit(1);
+    }
+    throw err;
+  });
+
+  server.listen(port, () => {
+    const url = `http://localhost:${port}`;
+    log.ok(`Storybook → ${url}`);
+    openBrowser(url);
+  });
+}
+
+export async function runStorybook(args = []) {
+  const { port = "6007", rebuild } = parseArgs(args, { booleans: ["rebuild"] });
+
+  const staged = existsSync(join(SHIPPED_DIST, "index.html"));
+  if (rebuild || !staged) {
+    if (existsSync(REPO_STORYBOOK)) {
+      buildStorybook();
+    } else if (!staged) {
+      throw new Error(
+        `Storybook build not found at ${SHIPPED_DIST}.\n` +
+          "  This build of muscat-pk was published without the bundled Storybook.",
+      );
+    }
+  }
+
+  serve(SHIPPED_DIST, Number(port));
+}

package/cli/src/type.mjs

@@ -1,21 +1,20 @@
 // 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 { findPluginRoot, log, prompt } from "./util.mjs";
+import {
+  TYPE_CHOICES,
+  applyTokens,
+  deriveNames,
+  overlayCpp,
+  overlayRos2,
+  runtimeForChoice,
+} from "./new.mjs";
 
-const TYPES = ["python", "ros2"];
-
-async function prompt(question, fallback) {
-  if (!process.stdin.isTTY) return fallback;
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const answer = (await rl.question(question)).trim();
-  rl.close();
-  return answer || fallback;
-}
+const TYPES = Object.keys(TYPE_CHOICES);
 
 function readManifest(root) {
   const path = resolve(root, "manifest.json");
@@ -23,44 +22,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})`);
+      await overlayRos2(root, slug, runtimeChoice.rosClient);
       applyTokens(root, {
         __PLUGIN_ID__: pluginId,
         __PLUGIN_NAME__: pluginName,
@@ -69,14 +78,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");
+      await 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}`);
 }