@rainbow-robotics/muscat-plugin-kit 1.3.6 → 1.3.8-dev.0

package/README.md

@@ -115,7 +115,7 @@ muscat-pk build                # build dist/ and produce a distributable ZIP (sk
 | `muscat-pk storybook` | Browse the bundled rb-components Storybook |
 | `muscat-pk mcp` | Run an MCP server for AI coding agents (exposes rb-components/design-token/SDK docs) |
 | `muscat-pk update` | Update the kit + plugin-ui to the latest version |
-| `muscat-pk sdk <list\|update>` | Manage the Python `rainbow-rb-sdk` version |
+| `muscat-pk sdk <list\|update>` | Manage the `rainbow-rb-sdk` version — python: `requirements.txt`, C++ (cpp / ros2-cpp): `find_package(rb_sdk <ver> EXACT REQUIRED)` in `CMakeLists.txt` |
 | `muscat-pk version` | Print the installed CLI version (`-v` / `--version` also work) |
 | `muscat-pk completion [shell]` | Print a shell completion script (`bash` / `zsh` / `fish` / `powershell`; defaults to `$SHELL`) |
 

package/cli/README.md

@@ -226,7 +226,13 @@ inside plugins.
 - **`build`** bundles plugin code into ESM while externalizing
   `@rainbow-robotics/plugin-ui`, React, and ReactDOM.
 - **`dev:ui`** builds the plugin then serves it inside the bundled preview host
-  at `/plugin-dev` — a real mini-Muscat shell with no robot/back end.
+  at `/plugin-dev` — a real mini-Muscat shell. Without a robot IP it needs a Muscat
+  on `localhost:3000` for program preview: `dev` / `dev:ui` reuse any container that
+  already publishes `:10000` (`muscat`, `muscat-dev`, …) and otherwise start
+  `muscat-pk-muscat` — the S3 runtime image (`muscat/main/muscat.zip`) running only the
+  `common` service from `muscat/main/version.json`, cached under `~/.muscat-pk/muscat/`.
+  It keeps running between runs (`docker rm -f muscat-pk-muscat` to stop);
+  `MUSCAT_PK_NO_LOCAL_MUSCAT=1` disables it.
 
 `create-muscat-plugin <dir>` is the bin alias for `muscat-pk new`.
 

package/cli/docker/Dockerfile.cpp

@@ -10,14 +10,15 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       cmake \
     && rm -rf /var/lib/apt/lists/*
 
-# Rainbow Robotics C++ SDK for find_package(rb_sdk).
+# Rainbow Robotics C++ SDK for find_package(rb_sdk). Pin the runtime package too: apt would
+# otherwise pick the newest rainbow-rb-sdk, which -dev (= same version) rejects.
 # Override with MUSCAT_PK_RB_SDK_VERSION=<ver> (+ MUSCAT_PK_REBUILD_IMAGE=1).
-ARG RB_SDK_VERSION=0.1.7
+ARG RB_SDK_VERSION=0.10.2
 RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl \
     && install -d /etc/apt/keyrings \
     && curl -fsSL https://rainbowrobotics.github.io/rb-sdk/rb-sdk-apt-repo.gpg.key -o /etc/apt/keyrings/rb-sdk.asc \
     && printf 'deb [signed-by=/etc/apt/keyrings/rb-sdk.asc] https://rainbowrobotics.github.io/rb-sdk %s main\n' stable dev > /etc/apt/sources.list.d/rb-sdk.list \
-    && apt-get update && apt-get install -y --no-install-recommends "rainbow-rb-sdk-dev=${RB_SDK_VERSION}" \
+    && apt-get update && apt-get install -y --no-install-recommends "rainbow-rb-sdk=${RB_SDK_VERSION}" "rainbow-rb-sdk-dev=${RB_SDK_VERSION}" \
     && rm -rf /var/lib/apt/lists/*
 
 # MediaMTX — same version/ports as the Muscat runtime (rby2 scripts/backend/runtime/mediamtx.yml),

package/cli/docker/Dockerfile.dev

@@ -11,12 +11,12 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 
 # Rainbow Robotics C++ SDK for find_package(rb_sdk).
 # Override with MUSCAT_PK_RB_SDK_VERSION=<ver> (+ MUSCAT_PK_REBUILD_IMAGE=1).
-ARG RB_SDK_VERSION=0.1.7
+ARG RB_SDK_VERSION=0.10.2
 RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl \
     && install -d /etc/apt/keyrings \
     && curl -fsSL https://rainbowrobotics.github.io/rb-sdk/rb-sdk-apt-repo.gpg.key -o /etc/apt/keyrings/rb-sdk.asc \
     && printf 'deb [signed-by=/etc/apt/keyrings/rb-sdk.asc] https://rainbowrobotics.github.io/rb-sdk %s main\n' stable dev > /etc/apt/sources.list.d/rb-sdk.list \
-    && apt-get update && apt-get install -y --no-install-recommends "rainbow-rb-sdk-dev=${RB_SDK_VERSION}" \
+    && apt-get update && apt-get install -y --no-install-recommends "rainbow-rb-sdk=${RB_SDK_VERSION}" "rainbow-rb-sdk-dev=${RB_SDK_VERSION}" \
     && rm -rf /var/lib/apt/lists/*
 
 # MediaMTX — same version/ports as the Muscat runtime (rby2 scripts/backend/runtime/mediamtx.yml),

package/cli/src/bridge.mjs

@@ -43,7 +43,7 @@ function assertDockerReady() {
 }
 
 // Is a host TCP port already bound? (Catches another bridge or a stray process.)
-function isPortInUse(port) {
+export function isPortInUse(port) {
   return new Promise((res) => {
     const srv = createServer();
     srv.once("error", (err) => res(err.code === "EADDRINUSE"));

package/cli/src/build.mjs

@@ -353,7 +353,7 @@ function packZip(pluginRoot) {
 
 /**
  * Ask which target arch(es) to build for.
- * Non-TTY (CI): auto-selects current machine arch.
+ * Non-TTY (CI): both, same as the prompt default.
  * @returns {Promise<string[]>} e.g. ['amd64'] | ['arm64'] | ['amd64','arm64']
  */
 async function promptArch(args = []) {
@@ -364,11 +364,11 @@ async function promptArch(args = []) {
     if (archFlag === "arm64" || archFlag === "aarch64") return ["arm64"];
     throw new Error(`unknown --arch value '${archFlag}' (valid: amd64, arm64, both)`);
   }
+  // Same default as the prompt: the target is the robot, not this machine
+  // (node's os.arch() is x64 under Rosetta on an arm64 Mac anyway).
   if (!process.stdin.isTTY) {
-    const { arch } = await import("node:os");
-    const machine = arch() === "arm64" ? "arm64" : "amd64";
-    log.info(`arch auto-selected (non-TTY): ${machine}`);
-    return [machine];
+    log.info("arch auto-selected (non-TTY): both");
+    return ["amd64", "arm64"];
   }
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   process.stdout.write(

package/cli/src/completion.mjs

@@ -19,7 +19,7 @@ const COMMANDS = [
   ["mcp", "Start an MCP server (stdio)"],
   ["update", "Update muscat-pk and plugin-ui"],
   ["uninstall", "Remove the installed muscat-pk CLI"],
-  ["sdk", "Manage the python rainbow-rb-sdk version"],
+  ["sdk", "Manage the rainbow-rb-sdk version (python: requirements.txt, C++: CMakeLists.txt)"],
   ["version", "Print the installed muscat-pk version"],
   ["completion", "Print a shell completion script"],
   ["help", "Show help"],

package/cli/src/cpp.mjs

@@ -3,7 +3,8 @@
 // Used by dev:back (interactive dev loop) and build (export the binary into the ZIP).
 import { spawnSync } from "node:child_process";
 import { dirname } from "node:path";
-import { canSkipImageBuild, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+import { canSkipImageBuild, cppSdkVersion, pluginRootOrNull, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+import { syncCppIde } from "./cppIde.mjs";
 
 export const CPP_DEV_IMAGE = "muscat-pk-cpp-dev";
 
@@ -14,9 +15,16 @@ export function assertDockerReady() {
 }
 
 /** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
-export async function ensureImage(image = CPP_DEV_IMAGE, { platform = null } = {}) {
+export async function ensureImage(image = CPP_DEV_IMAGE, { platform = null, root = pluginRootOrNull() } = {}) {
+  await buildImage(image, platform, root);
+  // Dev images feed the editor's SDK headers: the native one (dev) or the host-arch one (build).
+  const hostArch = process.arch === "arm64" ? "arm64" : "amd64";
+  if (root && (image === CPP_DEV_IMAGE || image === `${CPP_DEV_IMAGE}-${hostArch}`)) syncCppIde(root, image);
+}
+
+async function buildImage(image, platform, root) {
   const dockerfile = await resolveDockerfile("Dockerfile.cpp");
-  const sdkVer = process.env.MUSCAT_PK_RB_SDK_VERSION;
+  const sdkVer = cppSdkVersion(root);
   const key = imageKey(dockerfile, sdkVer ?? "");
   if (canSkipImageBuild(image, key)) {
     log.step(`${image} already built — skipping docker build`);

package/cli/src/cppIde.mjs

@@ -0,0 +1,75 @@
+// Editor (IntelliSense) support for C++ backends. The rb_sdk headers only exist inside the dev image,
+// so a host editor flags every SDK name. Copy them to .muscat-dev/sysroot and point
+// .vscode/c_cpp_properties.json at them, using the include dirs / defines rb_sdk's CMake target exports.
+// The build never reads these copies — it runs in the image.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { cppSdkFiles, log } from "./util.mjs";
+
+const SYSROOT = ".muscat-dev/sysroot";
+const CONFIG_NAME = "Muscat";
+const COPY = ["/usr/include/rainbow", "/usr/include/eigen3", "/usr/lib/cmake/rb_sdk/rb_sdkTargets.cmake"];
+
+function imageId(image) {
+  const r = spawnSync("docker", ["image", "inspect", "-f", "{{.Id}}", image], { encoding: "utf8" });
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+/** Copy the SDK headers out of `image` (once per image build) and write the VS Code C/C++ config. */
+export function syncCppIde(root, image) {
+  if (!cppSdkFiles(root).length) return;
+  const id = imageId(image);
+  if (!id) return;
+  const sysroot = resolve(root, SYSROOT);
+  const stamp = resolve(sysroot, ".image-id");
+  if (!existsSync(stamp) || readFileSync(stamp, "utf8") !== id) {
+    rmSync(sysroot, { recursive: true, force: true });
+    const create = spawnSync("docker", ["create", image], { encoding: "utf8" });
+    if (create.status !== 0) return log.warn("could not copy SDK headers for the editor (docker create failed).");
+    const container = create.stdout.trim();
+    try {
+      for (const src of COPY) {
+        const dest = resolve(sysroot, src.slice(1));
+        mkdirSync(resolve(dest, ".."), { recursive: true });
+        spawnSync("docker", ["cp", `${container}:${src}`, dest], { stdio: "ignore" });
+      }
+    } finally {
+      spawnSync("docker", ["rm", container], { stdio: "ignore" });
+    }
+    writeFileSync(stamp, id);
+    log.step(`SDK headers for the editor → ${SYSROOT}`);
+  }
+  writeCppProperties(root, readTarget(sysroot));
+}
+
+// INTERFACE_INCLUDE_DIRECTORIES / INTERFACE_COMPILE_DEFINITIONS of rb_sdk::rb_sdk, mapped into the sysroot.
+function readTarget(sysroot) {
+  const file = resolve(sysroot, "usr/lib/cmake/rb_sdk/rb_sdkTargets.cmake");
+  const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const list = (key) => (text.match(new RegExp(`${key} "([^"]*)"`))?.[1] ?? "").split(";").filter(Boolean);
+  const prefix = `\${workspaceFolder}/${SYSROOT}/usr`;
+  const includes = list("INTERFACE_INCLUDE_DIRECTORIES").map((d) => d.replace("${_IMPORT_PREFIX}", prefix));
+  return {
+    includePath: [...(includes.length ? includes : [`${prefix}/include`]), `${prefix}/include/eigen3`],
+    defines: list("INTERFACE_COMPILE_DEFINITIONS"),
+  };
+}
+
+// Keeps other configurations; ours is replaced in place or put first so VS Code picks it by default.
+function writeCppProperties(root, { includePath, defines }) {
+  const file = resolve(root, ".vscode", "c_cpp_properties.json");
+  let props = { configurations: [], version: 4 };
+  if (existsSync(file)) {
+    try {
+      props = JSON.parse(readFileSync(file, "utf8"));
+    } catch {
+      return log.warn(".vscode/c_cpp_properties.json is not plain JSON — add the SDK include paths yourself.");
+    }
+  }
+  const config = { name: CONFIG_NAME, includePath: ["${workspaceFolder}/**", ...includePath], defines, cppStandard: "c++20" };
+  const configs = (props.configurations ?? []).filter((c) => c.name !== CONFIG_NAME);
+  props.configurations = [config, ...configs];
+  mkdirSync(resolve(root, ".vscode"), { recursive: true });
+  writeFileSync(file, JSON.stringify(props, null, 2) + "\n");
+}

package/cli/src/dev.mjs

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 import { runDevUi } from "./devUi.mjs";
 import { runDevBack, stopDevBackContainers } from "./devBack.mjs";
 import { localMuscatContainer, startBridge, stopBridge, BRIDGE_CONTAINER, BRIDGE_PORT } from "./bridge.mjs";
+import { ensureLocalMuscat } from "./muscatLocal.mjs";
 import { assertManifestPorts, assertManifestVariables } from "./manifest.mjs";
 import { formatPortRanges } from "./ports.mjs";
 import {
@@ -123,6 +124,11 @@ export async function runDev(args = []) {
   if (robotToken) process.env.MUSCAT_ROBOT_TOKEN = robotToken;
 
   const remoteRobot = isRemoteRobot(robotIp);
+  // No robot: a local Muscat (common) owns :10000, so the bridge below is skipped and
+  // dev:back joins the Muscat netns instead — same as against a `muscat-dev` container.
+  const localMuscat = remoteRobot
+    ? null
+    : await ensureLocalMuscat().catch((e) => { log.warn(`local Muscat: ${e.message}`); return null; });
   const hostAgent = await maybeStartHostAgent(root, { robotIp, robotToken });
   const proxyEndpoint = process.env.MUSCAT_PROXY_ENDPOINT || "";
   // No proxy (Linux, disabled, ...): fall back to the container reverse-dialing
@@ -130,7 +136,8 @@ export async function runDev(args = []) {
   if (!proxyEndpoint) await ensureRemoteZenohEnv(robotIp, { log });
 
   log.step("starting Socket.IO bridge (Docker) + dev:ui + dev:back");
-  const bridgeStarted = await startBridge({
+  // A local Muscat already serves :10000 (gateway) and MediaMTX — no bridge needed.
+  const bridgeStarted = localMuscat ? false : await startBridge({
     zenohPort: remoteRobot && !proxyEndpoint && !usesHostNetwork()
       ? Number(process.env.MUSCAT_ZENOH_PORT)
       : null,
@@ -138,7 +145,7 @@ export async function runDev(args = []) {
     pluginPorts: usesHostNetwork() ? [] : portRanges,
   });
 
-  const muscat = bridgeStarted ? null : localMuscatContainer();
+  const muscat = bridgeStarted ? null : (localMuscat ?? localMuscatContainer());
   if (muscat) {
     log.step(`local Muscat container '${muscat}' owns :${BRIDGE_PORT} — backend joins its network (gateway, MediaMTX)`);
     process.env.MUSCAT_PK_MUSCAT_CONTAINER = muscat;

package/cli/src/devBack.mjs

@@ -12,7 +12,8 @@ import { existsSync, mkdirSync, readFileSync, watch, writeFileSync } from "node:
 import { isIP } from "node:net";
 import { dirname, resolve } from "node:path";
 import { dockerUserFlags, ensureDocker, ensureIdeVenv, findPluginRoot, log, promptRobotConnection, realtimeFlags } from "./util.mjs";
-import { ensureRemoteZenohEnv, usesHostNetwork } from "./zenohDev.mjs";
+import { ensureRemoteZenohEnv, isRemoteRobot, usesHostNetwork } from "./zenohDev.mjs";
+import { localMuscatContainer } from "./bridge.mjs";
 import { PLUGIN_ID_RE, assertManifestPorts, assertManifestVariables, manifestRuntime, readManifest, rosNamespace, validateManifest } from "./manifest.mjs";
 import {
   formatPortRanges,
@@ -56,9 +57,18 @@ export function stopDevBackContainers() {
 // Where the backend's 127.0.0.1 points. A local Muscat container (muscat-dev): join its
 // netns so the gateway and MediaMTX resolve like on the robot. Under `dev`: the bridge's
 // netns. Standalone dev:back: its own netns, gateway via the host.
+// IS_DEV Muscat (muscat-dev): common is a zenoh-router client and opens no 7447 listener,
+// so the plugin must join the router too or `execute` queries never reach it.
+function muscatZenohEnv(container) {
+  const r = spawnSync("docker", ["inspect", "-f", "{{range .Config.Env}}{{println .}}{{end}}", container], { encoding: "utf8" });
+  return /^IS_DEV=(true|1)$/im.test(r.stdout || "")
+    ? ["-e", "ZENOH_PEER_CONNECT_ENDPOINTS=tcp/zenoh-router:7447"]
+    : [];
+}
+
 function backendNetwork(portRanges) {
   const muscat = process.env.MUSCAT_PK_MUSCAT_CONTAINER;
-  if (muscat) return { run: ["--network", `container:${muscat}`], env: [], shared: true };
+  if (muscat) return { run: ["--network", `container:${muscat}`], env: muscatZenohEnv(muscat), shared: true };
   if (usesHostNetwork()) return { run: ["--network", "host"], env: [], shared: true };
   const bridge = process.env.MUSCAT_PK_BRIDGE_CONTAINER;
   if (bridge) return { run: ["--network", `container:${bridge}`], env: [], shared: true };
@@ -656,6 +666,15 @@ export async function runDevBack(args = []) {
   // Byte-proxy mode (a host-side host_agent set MUSCAT_PROXY_ENDPOINT) makes
   // the container speak the proxy protocol instead, so it needs no reverse-dial.
   if (!process.env.MUSCAT_PROXY_ENDPOINT) await ensureRemoteZenohEnv(robotIp, { log });
+  // Standalone against a local Muscat (muscat-dev, …): join its netns like `dev` does,
+  // otherwise zenoh reaches nothing and `execute` never arrives.
+  if (!process.env.MUSCAT_PK_MUSCAT_CONTAINER && !isRemoteRobot(robotIp)) {
+    const muscat = localMuscatContainer();
+    if (muscat) {
+      log.step(`local Muscat container '${muscat}' found — backend joins its network`);
+      process.env.MUSCAT_PK_MUSCAT_CONTAINER = muscat;
+    }
+  }
   const type = manifestRuntime(root);
   if (type === "ros2") return await runRos2(root, portRanges);
   if (type === "cpp") return await runCpp(root, portRanges);

package/cli/src/devUi.mjs

@@ -7,6 +7,8 @@ import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { checkKitUpdate, findPluginRoot, hasBin, kitRoot, log, parseArgs, prompt } from "./util.mjs";
+import { ensureLocalMuscat } from "./muscatLocal.mjs";
+import { isRemoteRobot } from "./zenohDev.mjs";
 
 
 const DEV_PLUGIN_PORT = 4181;
@@ -44,7 +46,9 @@ function findPreviewHostRoot() {
   try {
     const req = createRequire(import.meta.url);
     return dirname(req.resolve(`${PREVIEW_PKG}/package.json`));
-  } catch {}
+  } catch {
+    console.log("Try the sibling and cached package locations below.")
+  }
 
   const sibling = resolve(kitRoot, "../preview-host");
   if (existsSync(resolve(sibling, "package.json"))) return sibling;
@@ -137,6 +141,7 @@ function waitForPluginDevPort(readyFile, proc, timeoutMs = 15_000) {
           const { port } = JSON.parse(readFileSync(readyFile, "utf8"));
           if (Number.isInteger(port)) return res(port);
         } catch {
+          console.log("Keep polling until the ready file contains valid JSON.")
         }
       }
       if (Date.now() - start > timeoutMs)
@@ -160,6 +165,10 @@ export async function runDevUi(args = []) {
     log.warn(`preview-host port ${requestedPort} is in use — using ${port} instead.`);
 
   if (robotIp) log.info(`MUSCAT_API_ORIGIN → http://${robotIp}:*`);
+  // No robot: the bundle talks to localhost:3000, so put a Muscat there (`dev` already did).
+  if (!isRemoteRobot(robotIp) && process.env.MUSCAT_PK_MANAGED_DEV !== "1") {
+    await ensureLocalMuscat().catch((e) => log.warn(`local Muscat: ${e.message}`));
+  }
 
   watchAssets(pluginRoot, outDir);
 

package/cli/src/muscatLocal.mjs

@@ -0,0 +1,160 @@
+// Local Muscat back end for `dev` / `dev:ui` without a robot.
+// preview-host hits http://localhost:3000/common/* (baked into the nexus bundle), so a
+// Muscat on :3000 makes program preview work with no front-end change. We reuse any
+// Muscat already publishing :10000 (e.g. a `muscat` / `muscat-dev` container) and only
+// otherwise start our own: the S3 runtime image with just the `common` service.
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { isPortInUse, localMuscatContainer } from "./bridge.mjs";
+import { mediaPortFlags, MEDIA_PORTS } from "./ports.mjs";
+import { canSkipImageBuild, hasBin, log } from "./util.mjs";
+
+export const MUSCAT_CONTAINER = "muscat-pk-muscat";
+const IMAGE = "muscat-pk-runtime";
+const S3 = process.env.MUSCAT_PK_MUSCAT_S3 ?? "https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat/main";
+const CACHE = resolve(homedir(), ".muscat-pk", "muscat");
+const API_PORT = 3000;
+const GATEWAY_PORT = 10000;
+// The bin runs inside Docker, so follow the Docker engine's arch, not this Node's
+// (Rosetta/x64 Node on an Apple Silicon host would otherwise pick amd64).
+const dockerArch = () => {
+  const r = spawnSync("docker", ["version", "--format", "{{.Server.Arch}}"], { encoding: "utf8" });
+  const a = (r.stdout || "").trim();
+  return a === "arm64" || a === "amd64" ? a : process.arch === "arm64" ? "arm64" : "amd64";
+};
+
+async function fetchBuffer(url) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${url}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+// macOS/Windows `tar` reads zip; GNU tar does not, Linux has `unzip`.
+function extractZip(zip, dir, members = []) {
+  mkdirSync(dir, { recursive: true });
+  const tries = [
+    ["unzip", ["-o", "-q", zip, ...members, "-d", dir]],
+    ["tar", ["-xf", zip, "-C", dir, ...members]],
+  ];
+  for (const [bin, args] of tries) {
+    if (hasBin(bin) && spawnSync(bin, args, { stdio: "ignore" }).status === 0) return;
+  }
+  throw new Error(`could not extract ${zip} (needs unzip or tar)`);
+}
+
+async function resolveVersions() {
+  const file = resolve(CACHE, "version.json");
+  try {
+    const data = await fetchBuffer(`${S3}/version.json`);
+    mkdirSync(CACHE, { recursive: true });
+    writeFileSync(file, data);
+    return JSON.parse(data.toString());
+  } catch (e) {
+    if (!existsSync(file)) throw e;
+    log.warn(`version.json unreachable (${e.message}) — using cached Muscat version`);
+    return JSON.parse(readFileSync(file, "utf8"));
+  }
+}
+
+async function ensureRuntimeImage(total) {
+  const image = `${IMAGE}:${total}`;
+  if (canSkipImageBuild(image)) return image;
+  const dir = resolve(CACHE, "runtime", total);
+  if (!existsSync(resolve(dir, "Dockerfile.runtime"))) {
+    log.step(`downloading Muscat runtime scripts (muscat.zip ${total})…`);
+    const zip = resolve(CACHE, "muscat.zip");
+    writeFileSync(zip, await fetchBuffer(`${S3}/muscat.zip`));
+    extractZip(zip, dir);
+    rmSync(zip, { force: true });
+  }
+  log.step(`docker build -t ${image} (first run downloads MongoDB/InfluxDB/ROS base — slow, then cached)…`);
+  const r = spawnSync(
+    "docker",
+    ["build", "-t", image, "-f", resolve(dir, "Dockerfile.runtime"), "--label", "com.rainbow-robotics.muscat-pk=true", dir],
+    { stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error("docker build failed (Muscat runtime image).");
+  return image;
+}
+
+async function ensureCommonBinary(version) {
+  const ARCH = dockerArch();
+  const dir = resolve(CACHE, "services", "common");
+  const stamp = resolve(dir, ".version");
+  if (existsSync(stamp) && readFileSync(stamp, "utf8").trim() === version && existsSync(resolve(dir, `common.${ARCH}.bin`))) return dir;
+  log.step(`downloading Muscat common service ${version} (${ARCH})…`);
+  const zip = resolve(CACHE, `common-${version}.zip`);
+  writeFileSync(zip, await fetchBuffer(`${S3}/common/${version}.zip`));
+  extractZip(zip, dir, ["config.env", `common.${ARCH}.bin`]);
+  rmSync(zip, { force: true });
+  chmodSync(resolve(dir, `common.${ARCH}.bin`), 0o755);
+  writeFileSync(stamp, `${version}\n`);
+  return dir;
+}
+
+async function waitForApi(timeoutMs = 180_000) {
+  const start = Date.now();
+  for (;;) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${API_PORT}/common/docs`);
+      if (res.ok) return;
+    } catch { /* not listening yet */ }
+    if (Date.now() - start > timeoutMs) throw new Error(`Muscat did not answer on :${API_PORT} in time — see \`docker logs ${MUSCAT_CONTAINER}\``);
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+}
+
+/**
+ * Make sure a Muscat answers on localhost:3000 / :10000. Returns the container name,
+ * or null when one can't be started (no Docker, foreign process on the ports).
+ * The container is left running across runs — stop it with `docker rm -f muscat-pk-muscat`.
+ */
+export async function ensureLocalMuscat() {
+  if (process.env.MUSCAT_PK_NO_LOCAL_MUSCAT === "1") return null;
+  const existing = hasBin("docker") ? localMuscatContainer() : null;
+  if (existing) {
+    log.step(`local Muscat '${existing}' already on :${GATEWAY_PORT} — reusing it`);
+    return existing;
+  }
+  if (!hasBin("docker")) {
+    log.warn("Docker not found — no local Muscat; program preview will have no back end.");
+    return null;
+  }
+  for (const port of [API_PORT, GATEWAY_PORT]) {
+    if (await isPortInUse(port)) {
+      log.warn(`port ${port} is in use by something that is not a Muscat container — not starting local Muscat.`);
+      return null;
+    }
+  }
+
+  const versions = await resolveVersions();
+  const total = versions.total;
+  const commonVersion = versions.services?.common?.version;
+  if (!total || !commonVersion) throw new Error("version.json has no total / services.common.version");
+
+  const image = await ensureRuntimeImage(total);
+  const commonDir = await ensureCommonBinary(commonVersion);
+
+  let media = true;
+  for (const port of MEDIA_PORTS) if (await isPortInUse(port)) media = false;
+
+  spawnSync("docker", ["rm", "-f", MUSCAT_CONTAINER], { stdio: "ignore" });
+  log.step(`starting local Muscat (common ${commonVersion}) → http://localhost:${API_PORT}/common/docs`);
+  const r = spawnSync("docker", [
+    "run", "-d", "--name", MUSCAT_CONTAINER, "--label", "com.rainbow-robotics.muscat-pk=true",
+    "-e", "RB_ENABLED_SERVICES=common",
+    "-e", "RB_RUNTIME_ENABLE_ZENOH_BRIDGE=0",
+    "-v", `${commonDir}:/app/services/common`,
+    "-v", `${resolve(CACHE, "data")}:/app/data`,
+    "-p", `127.0.0.1:${API_PORT}:${API_PORT}`,
+    "-p", `127.0.0.1:${GATEWAY_PORT}:${GATEWAY_PORT}`,
+    ...(media ? mediaPortFlags() : []),
+    image,
+  ], { stdio: ["ignore", "ignore", "inherit"] });
+  if (r.status !== 0) throw new Error("failed to start the local Muscat container.");
+  await waitForApi();
+  log.step(`local Muscat ready — keeps running between runs; stop with: docker rm -f ${MUSCAT_CONTAINER}`);
+  return MUSCAT_CONTAINER;
+}

package/cli/src/new.mjs

@@ -70,6 +70,20 @@ function printNewSuccess({ targetName, type, pm }) {
   log.info("");
 }
 
+// C++ backends: the editor needs the SDK headers, which only exist in the dev image. Building the image
+// now (dev/build reuse it) lets VS Code resolve rb_sdk right away. Best-effort, like the .venv.
+export async function prepareCppIde(root, choice) {
+  const later = "they come with the first `muscat-pk dev` / `build`";
+  if (!hasBin("docker")) return log.warn(`Docker not found — SDK headers for the editor: ${later}.`);
+  try {
+    log.step("preparing the C++ dev image + SDK headers for your editor (first run is slow)…");
+    const { ensureImage } = await import(choice.type === "cpp" ? "./cpp.mjs" : "./ros2.mjs");
+    await ensureImage(undefined, { root });
+  } catch (err) {
+    log.warn(`Could not prepare SDK headers for the editor (${err.message}) — ${later}.`);
+  }
+}
+
 // Build the manifest runtime object for a given type choice + plugin slug.
 export function runtimeForChoice(choice, slug) {
   switch (choice.type) {
@@ -285,6 +299,7 @@ export async function runNew(args) {
         log.warn("Could not create .venv (no local Python/uv?) — skipping, Docker dev still works.");
       }
     }
+    if (runtimeChoice.type === "cpp" || runtimeChoice.rosClient === "rclcpp") await prepareCppIde(target, runtimeChoice);
   }
 
   // git init (best-effort). Always runs, even nested inside another repo —

package/cli/src/ros2.mjs

@@ -3,7 +3,8 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { canSkipImageBuild, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+import { canSkipImageBuild, cppSdkVersion, pluginRootOrNull, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+import { syncCppIde } from "./cppIde.mjs";
 
 export const ROS2_DEV_IMAGE = "muscat-pk-ros2-dev";
 
@@ -29,9 +30,16 @@ export const ARCH_DOCKER_PLATFORM = {
 };
 
 /** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
-export async function ensureImage(image = ROS2_DEV_IMAGE, { platform = null } = {}) {
+export async function ensureImage(image = ROS2_DEV_IMAGE, { platform = null, root = pluginRootOrNull() } = {}) {
+  await buildImage(image, platform, root);
+  // Dev images feed the editor's SDK headers: the native one (dev) or the host-arch one (build).
+  const hostArch = process.arch === "arm64" ? "arm64" : "amd64";
+  if (root && (image === ROS2_DEV_IMAGE || image === `${ROS2_DEV_IMAGE}-${hostArch}`)) syncCppIde(root, image);
+}
+
+async function buildImage(image, platform, root) {
   const dockerfile = await resolveDockerfile("Dockerfile.dev");
-  const sdkVer = process.env.MUSCAT_PK_RB_SDK_VERSION;
+  const sdkVer = cppSdkVersion(root);
   const key = imageKey(dockerfile, sdkVer ?? "");
   if (canSkipImageBuild(image, key)) {
     log.step(`${image} already built — skipping docker build`);

package/cli/src/sdk.mjs

@@ -1,12 +1,17 @@
-// muscat-pk sdk <list|update [version]> — manage the python rainbow-rb-sdk.
+// muscat-pk sdk <list|update [version]> — manage the rainbow-rb-sdk version.
 //
+// C++ backends (cpp, ros2 rclcpp) pin it in CMakeLists.txt (find_package(rb_sdk <ver> EXACT)); the
+// versions come from the rb-sdk apt repository and the dev image installs the pinned one.
+//
+// Python backends:
 // 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 { ensureIdeVenv, findPluginRoot, log, venvPython } from "./util.mjs";
+import { cppSdkFiles, cppSdkPin, ensureIdeVenv, findPluginRoot, log, setCppSdkPin, venvPython } from "./util.mjs";
+import { readManifest } from "./manifest.mjs";
 
 const PKG = "rainbow-rb-sdk";
 
@@ -24,9 +29,50 @@ async function fetchVersions() {
   return Object.keys(data?.releases || {}).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
 }
 
+// Stable releases of rainbow-rb-sdk-dev, newest first. Pre-releases (0.1.4~dev1) are skipped: CMake
+// versions are numeric only.
+const APT_PACKAGES = "https://rainbowrobotics.github.io/rb-sdk/dists/stable/main/binary-amd64/Packages";
+
+export async function fetchAptVersions() {
+  try {
+    const res = await fetch(APT_PACKAGES);
+    if (!res.ok) return [];
+    const text = await res.text();
+    const versions = [...text.matchAll(/^Package: rainbow-rb-sdk-dev\n(?:.*\n)*?Version: (\S+)/gm)].map((m) => m[1]);
+    return [...new Set(versions)].filter((v) => /^[0-9]+(\.[0-9]+)*$/.test(v)).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+  } catch {
+    return [];
+  }
+}
+
+async function runCppSdk(sub, version, root) {
+  if (sub === "list") {
+    const versions = await fetchAptVersions();
+    if (!versions.length) return log.warn("could not fetch versions (offline?).");
+    log.info(`rainbow-rb-sdk-dev versions:\n  ${versions.slice(0, 12).join("\n  ")}`);
+    return;
+  }
+  if (sub === "update") {
+    if (!cppSdkFiles(root).length) throw new Error("no find_package(rb_sdk ...) in cpp/CMakeLists.txt or ros2_ws/src/*/CMakeLists.txt");
+    if (!version) {
+      version = (await fetchAptVersions())[0];
+      if (!version) throw new Error("could not fetch the latest version (offline?). Pass one: muscat-pk sdk update <version>");
+    }
+    if (!/^[0-9]+(\.[0-9]+)*$/.test(version)) throw new Error(`"${version}" is not a CMake version (digits and dots only)`);
+    const before = cppSdkPin(root);
+    const files = setCppSdkPin(root, version);
+    log.ok(`rb_sdk ${before ?? "(unpinned)"} → ${version} in ${files.map((f) => f.slice(root.length + 1)).join(", ")}`);
+    log.info("The dev image is rebuilt with this SDK on the next `muscat-pk build` / `dev:back`.");
+    return;
+  }
+  log.info("Usage: muscat-pk sdk <list|update [version]>");
+}
+
 export async function runSdk(args = []) {
   const sub = args[0];
   const root = findPluginRoot();
+  const runtime = readManifest(root)?.runtime ?? {};
+  if (runtime.type === "cpp" || (runtime.type === "ros2" && runtime.rosClient === "rclcpp")) return runCppSdk(sub, args[1], root);
   const reqs = resolve(root, "requirements.txt");
 
   if (sub === "list") {

package/cli/src/type.mjs

@@ -13,6 +13,7 @@ import {
   deriveNames,
   overlayCpp,
   overlayRos2,
+  prepareCppIde,
   runtimeForChoice,
 } from "./new.mjs";
 
@@ -126,6 +127,7 @@ export async function runType(args) {
   json.runtime = runtimeForChoice(runtimeChoice, slug);
   writeFileSync(path, JSON.stringify(json, null, 2) + "\n");
   log.ok(`${basename(root)} type: ${current} → ${to}`);
+  if (isCpp(to)) await prepareCppIde(root, runtimeChoice);
 
   if (isCpp(current) !== isCpp(to)) {
     await offerReadme(root, isCpp(to), args.includes("--readme"), {