@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.9 → 0.10.1-dev.0

package/cli/src/ports.mjs

@@ -0,0 +1,193 @@
+// Port contract helpers for plugin back ends.
+import { spawnSync } from "node:child_process";
+import { usesHostNetwork } from "./zenohDev.mjs";
+
+export const PLUGIN_PORT_MIN = 28600;
+export const PLUGIN_PORT_MAX = 28999;
+export const MEDIA_PORTS = [8554, 8889, 8189]; // MediaMTX: RTSP publish, WebRTC, WebRTC media
+export const INTERNAL_DEV_PORTS = new Set([10000, ...MEDIA_PORTS]);
+
+export function mediaPortFlags() {
+  return [
+    "-p", "127.0.0.1:8554:8554", "-p", "127.0.0.1:8889:8889",
+    "-p", "127.0.0.1:8189:8189/udp", "-p", "127.0.0.1:8189:8189/tcp",
+  ];
+}
+export const RESERVED_BACKEND_PORTS = new Map([
+  [502, "Modbus TCP"],
+  [4840, "OPC-UA"],
+  [10000, "Muscat plugin gateway"],
+  [2222, "EtherNet/IP Implicit"],
+  [30004, "RTDE"],
+  [34964, "ProfiNET"],
+  [44818, "EtherNet/IP Explicit"],
+  [50051, "gRPC"],
+]);
+export const RESERVED_BACKEND_PORT_RANGES = [
+  { from: 5170, to: 5179, name: "UI 517x servers" },
+  { from: 8000, to: 8999, name: "Muscat/internal 8000 range" },
+  { from: 50000, to: 50005, name: "robot TCP/UDP ASCII and REST interfaces" },
+];
+
+function reservedPortReason(port) {
+  if (RESERVED_BACKEND_PORTS.has(port)) return RESERVED_BACKEND_PORTS.get(port);
+  const range = RESERVED_BACKEND_PORT_RANGES.find((item) => port >= item.from && port <= item.to);
+  if (!range) return null;
+  return `${range.name} (${range.from}-${range.to})`;
+}
+
+// function isPluginManagedPort(port) {
+//   return reservedPortReason(port) || (port >= PLUGIN_PORT_MIN && port <= PLUGIN_PORT_MAX);
+// }
+
+function isInt(value) {
+  return Number.isInteger(value);
+}
+
+function validatePort(port, field, errors) {
+  if (!isInt(port)) {
+    errors.push(`${field}: must be a port number`);
+    return;
+  }
+  if (port < 1 || port > 65535) {
+    errors.push(`${field}: port must be between 1 and 65535`);
+    return;
+  }
+  const reserved = reservedPortReason(port);
+  if (reserved) {
+    errors.push(`${field}: ${port} is reserved for ${reserved}`);
+    return;
+  }
+  if (port < PLUGIN_PORT_MIN || port > PLUGIN_PORT_MAX) {
+    errors.push(
+      `${field}: external plugin backend ports must be within ${PLUGIN_PORT_MIN}-${PLUGIN_PORT_MAX}`,
+    );
+  }
+}
+
+export function normalizePorts(ports, errors = []) {
+  if (ports === undefined || ports === null) return [];
+  if (!Array.isArray(ports)) {
+    errors.push(`"ports" must be an array`);
+    return [];
+  }
+  if (ports.length === 0) {
+    errors.push(`"ports" must not be empty when provided`);
+    return [];
+  }
+
+  const normalized = [];
+  const seen = new Set();
+  ports.forEach((port, i) => {
+    validatePort(port, `ports[${i}]`, errors);
+    if (!isInt(port)) return;
+    if (seen.has(port)) {
+      errors.push(`"ports" entries must be unique (duplicate: ${port})`);
+      return;
+    }
+    seen.add(port);
+    normalized.push(port);
+  });
+
+  return normalized;
+}
+
+export function validatePorts(ports, errors) {
+  normalizePorts(ports, errors);
+}
+
+export function manifestPortRanges(manifest) {
+  return normalizePorts(manifest?.ports, []);
+}
+
+export function formatPortRange(range) {
+  return String(range);
+}
+
+export function formatPortRanges(ranges) {
+  return ranges.map(formatPortRange).join(", ");
+}
+
+export function portInRanges(port, ranges) {
+  return ranges.includes(port);
+}
+
+export function portEnvFlags(ranges) {
+  if (ranges.length === 0) return [];
+  return ["-e", `RB_PLUGIN_PORTS=${ranges.map(formatPortRange).join(",")}`];
+}
+
+/**
+ * `docker run -p` flags for the plugin's declared ports, TCP and UDP on every host interface like
+ * on the robot, so LAN devices (e.g. a Meta Quest streaming UDP) reach the backend. Native Linux
+ * without a local Muscat uses --network host instead. Only valid on the container that owns the netns.
+ */
+export function publishPortFlags(ranges = []) {
+  return ranges.flatMap((port) => ["-p", `${port}:${port}`, "-p", `${port}:${port}/udp`]);
+}
+
+// Skips OS-assigned loopback listeners (127.0.0.1:0, e.g. the SDK's Zenoh session).
+function listeningTcpPorts(container) {
+  const script = `
+read -r eph_lo eph_hi < /proc/sys/net/ipv4/ip_local_port_range 2>/dev/null || { eph_lo=32768; eph_hi=60999; }
+for f in /proc/net/tcp /proc/net/tcp6; do
+  [ -r "$f" ] || continue
+  tail -n +2 "$f" | while read -r sl local_address rem_address st rest; do
+    [ "$st" = "0A" ] || continue
+    hex_ip="\${local_address%%:*}"
+    port=$((0x\${local_address##*:}))
+    case "$hex_ip" in
+      0100007F|00000000000000000000000001000000)
+        [ "$port" -ge "$eph_lo" ] && [ "$port" -le "$eph_hi" ] && continue ;;
+    esac
+    echo "$port"
+  done
+done | sort -n -u
+`;
+  const r = spawnSync("docker", ["exec", container, "bash", "-lc", script], {
+    encoding: "utf8",
+  });
+  if (r.status !== 0) return [];
+  return String(r.stdout || "")
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((v) => Number(v))
+    .filter((v) => Number.isInteger(v));
+}
+
+export function startPortContractMonitor({ container, ranges, log, intervalMs = 1000, allow = [] }) {
+  // Under --network host (or a local Muscat container's netns) /proc/net/tcp shows every
+  // host/robot service port, not just the plugin's — the contract can't be enforced.
+  if (usesHostNetwork() || process.env.MUSCAT_PK_MUSCAT_CONTAINER) return () => false;
+  const declared = ranges ?? [];
+  // muscat-pk's own dev plumbing shares this netns — not the plugin's doing.
+  const ignored = new Set([...INTERNAL_DEV_PORTS, ...allow.map(Number).filter(Number.isInteger)]);
+  let reported = false;
+  const timer = setInterval(() => {
+    // Every listening port that isn't declared is a violation — a port outside
+    // 28600-28999 can't be declared at all, so it must not be opened either.
+    // Otherwise it silently escapes both this check and rby2's install-time
+    // conflict check, and only collides once it's on a robot.
+    const unexpected = listeningTcpPorts(container)
+      .filter((port) => !ignored.has(port))
+      .filter((port) => !portInRanges(port, declared));
+    if (unexpected.length === 0) return;
+
+    clearInterval(timer);
+    reported = true;
+    const declaredText = declared.length > 0 ? formatPortRanges(declared) : "(none)";
+    log.error(
+      `backend opened undeclared TCP port(s): ${unexpected.join(", ")}. ` +
+      `Every listening port must be in manifest.json "ports" within ${PLUGIN_PORT_MIN}-${PLUGIN_PORT_MAX}. ` +
+      `Declared: ${declaredText}`,
+    );
+    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
+    process.exit(1);
+  }, intervalMs);
+  timer.unref?.();
+
+  return () => {
+    clearInterval(timer);
+    return reported;
+  };
+}

package/cli/src/projectCheck.mjs

@@ -0,0 +1,102 @@
+// What a project must change for the plugin-ui it has installed: known old APIs (ai-rules.mjs) plus
+// `tsc --noEmit`. Shared by `muscat-pk update` and the MCP tool check_project, so a user and an
+// agent see the same list.
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { LEGACY_COMPONENTS, LEGACY_SUBPATHS } from "./ai-rules.mjs";
+
+const isBinaryMode = typeof Bun !== "undefined";
+
+// The clause can't hold quotes or `;`, so a match can't start at an earlier import statement.
+const PLUGIN_UI_IMPORT = /import\s+([^;'"]*?)\s+from\s+["']@rainbow-robotics\/plugin-ui\/([\w-]+)["']/g;
+
+function listUiFiles(dir) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+    e.isDirectory() ? listUiFiles(join(dir, e.name)) : /\.[jt]sx?$/.test(e.name) ? [join(dir, e.name)] : [],
+  );
+}
+
+// rb.toast takes one { message, type } object now; flag a string or multi-argument call.
+const TOAST_CALL = /\.toast\(([^()]*)\)/g;
+
+/** Uses of the pre-1.x plugin-ui API in the project (ui/ and vite.config), as { file, line, text }. */
+function findLegacyUiUsage(root) {
+  const uiDir = resolve(root, "ui");
+  if (!existsSync(uiDir)) return [];
+  const found = [];
+  // The old hand-written config builds entries without their exports (connect() rendered as a side
+  // effect), so `export default App` is dropped from dist. The muscat() preset keeps it.
+  const viteConfig = ["vite.config.ts", "vite.config.mts", "vite.config.js", "vite.config.mjs"].find((f) => existsSync(resolve(root, f)));
+  if (viteConfig && !readFileSync(resolve(root, viteConfig), "utf8").includes("@rainbow-robotics/muscat-plugin-kit/vite")) {
+    found.push({
+      file: viteConfig,
+      line: 1,
+      text: 'not using the muscat() preset — the build drops the entry\'s default export. Use: import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite"; defineConfig({ plugins: [muscat()] })',
+    });
+  }
+  for (const file of listUiFiles(uiDir)) {
+    const src = readFileSync(file, "utf8");
+    const rel = relative(root, file);
+    const lineOf = (index) => src.slice(0, index).split("\n").length;
+    for (const m of src.matchAll(PLUGIN_UI_IMPORT)) {
+      const [, clause, subpath] = m;
+      if (LEGACY_SUBPATHS[subpath]) {
+        found.push({ file: rel, line: lineOf(m.index), text: `@rainbow-robotics/plugin-ui/${subpath} ${LEGACY_SUBPATHS[subpath]}` });
+      } else if (subpath === "react") {
+        const named = clause.match(/\{([\s\S]*)\}/)?.[1] ?? "";
+        for (const spec of named.split(",")) {
+          const name = spec.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0];
+          if (LEGACY_COMPONENTS[name]) {
+            found.push({ file: rel, line: lineOf(m.index), text: `${name} → ${LEGACY_COMPONENTS[name]}` });
+          }
+        }
+      }
+    }
+    for (const m of src.matchAll(TOAST_CALL)) {
+      const arg = m[1].trim();
+      if (!arg.startsWith("{") && (/^["'`]/.test(arg) || arg.includes(","))) {
+        found.push({ file: rel, line: lineOf(m.index), text: "rb.toast(message, type) → rb.toast({ message, type })" });
+      }
+    }
+    // Top-level ui/ files are the entries; the host mounts their default export.
+    if (relative(uiDir, file).split(/[\\/]/).length === 1 && !/export\s+default\b/.test(src)) {
+      found.push({ file: rel, line: 1, text: "no default export — the host renders the entry's default export" });
+    }
+  }
+  return found;
+}
+
+// The known-API list above only knows past changes. Type-checking against the plugin-ui that was
+// just installed catches whatever a later release removes or reshapes, with no list to keep up.
+function typeScriptErrors(root) {
+  const tsc = resolve(root, "node_modules/typescript/bin/tsc");
+  if (!existsSync(tsc) || !existsSync(resolve(root, "tsconfig.json"))) return [];
+  const runtime = isBinaryMode ? "node" : process.execPath;
+  const r = spawnSync(runtime, [tsc, "--noEmit", "-p", root, "--pretty", "false"], { cwd: root, encoding: "utf8" });
+  return `${r.stdout ?? ""}`
+    .split("\n")
+    .map((l) => /^(.+?)\((\d+),\d+\): error (TS\d+): (.*)$/.exec(l))
+    .filter(Boolean)
+    .map(([, file, line, code, text]) => ({ file: relative(root, resolve(root, file)), line: Number(line), text: `${code} ${text}` }));
+}
+
+/** Everything the project must change, as { file, line, text, source: "known" | "tsc" }. */
+export function checkProject(root) {
+  return [
+    ...findLegacyUiUsage(root).map((f) => ({ ...f, source: "known" })),
+    ...typeScriptErrors(root).map((e) => ({ ...e, source: "tsc" })),
+  ];
+}
+
+/** Plain-text lines for a checkProject() result (empty when there is nothing to fix). */
+export function formatProjectCheck(items) {
+  if (!items.length) return [];
+  const line = (i) => `  ${i.file}:${i.line}  ${i.text}`;
+  const tsc = items.filter((i) => i.source === "tsc");
+  return [
+    ...items.filter((i) => i.source !== "tsc").map(line),
+    ...(tsc.length ? ["  TypeScript (tsc --noEmit):", ...tsc.map(line)] : []),
+    "  For working examples, generate a fresh project and read its ui/content.tsx:  muscat-pk new <dir>",
+  ];
+}

package/cli/src/python.mjs

@@ -0,0 +1,112 @@
+// 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, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { canSkipImageBuild, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile, buildCacheFlags } 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");
+  const key = imageKey(dockerfile);
+  if (canSkipImageBuild(image, key)) {
+    return;
+  }
+  log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
+  const platformFlags = platform ? ["--platform", platform] : [];
+  const r = spawnSync(
+    "docker",
+    ["build", ...buildCacheFlags(), ...platformFlags, ...imageKeyLabel(key), "-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_35_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_35_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();
+
+  // A pinned pre-release (e.g. rainbow-rb-sdk==0.1.4.dev1) pins its sibling rainbow-rb-*
+  // pre-releases too; uv rejects those transitive pre-releases unless allowed.
+  const reqText = readFileSync(resolve(pluginRoot, "requirements.txt"), "utf8");
+  const prerelease = /==\s*\S*\d(a|b|rc|\.dev)\d*\s*$/im.test(reqText) ? " --prerelease=allow" : "";
+  log.step(`generating lock (uv pip compile${prerelease})…`);
+  const lockResult = spawnSync(
+    "docker",
+    [
+      "run", "--rm",
+      ...dockerUserFlags(),
+      "-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" + prerelease,
+    ],
+    { stdio: "inherit" },
+  );
+  if (lockResult.status !== 0) throw new Error("lock generation failed (uv pip compile)");
+  log.ok("dist/requirements.lock ready");
+
+  for (const arch of archs) {
+    const pipPlatforms = PIP_PLATFORM[arch];
+    if (!pipPlatforms) throw new Error(`unknown arch '${arch}'`);
+    log.step(`vendoring wheels for ${arch}…`);
+    const r = spawnSync(
+      "docker",
+      [
+        "run", "--rm",
+        ...dockerUserFlags(),
+        "-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" },
+    );
+    // A ZIP missing wheels fails to import on the robot — stop instead.
+    if (r.status !== 0) throw new Error(`wheel download failed for ${arch} (see pip output above)`);
+    log.ok(`dist/wheels/ ready (${arch})`);
+  }
+}

package/cli/src/ros2.mjs

@@ -3,14 +3,11 @@
 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 { canSkipImageBuild, cppSdkVersion, pluginRootOrNull, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile, buildCacheFlags } from "./util.mjs";
+import { syncCppIde } from "./cppIde.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 +22,38 @@ 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, 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 = cppSdkVersion(root);
+  const key = imageKey(dockerfile, sdkVer ?? "");
+  if (canSkipImageBuild(image, key)) {
+    return;
+  }
+  log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
+  const platformFlags = platform ? ["--platform", platform] : [];
+  const buildArgs = [...(sdkVer ? ["--build-arg", `RB_SDK_VERSION=${sdkVer}`] : []), ...imageKeyLabel(key)];
   const r = spawnSync(
     "docker",
-    ["build", "-t", image, "-f", DOCKERFILE, dirname(DOCKERFILE)],
+    ["build", ...buildCacheFlags(), ...platformFlags, ...buildArgs, "-t", image, "-f", dockerfile, dirname(dockerfile)],
     { stdio: "inherit" },
   );
   if (r.status !== 0) throw new Error("docker build failed.");
+  pruneMuskatImages();
 }
 
 /**
@@ -46,20 +61,49 @@ 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 buildBase = symlink ? "build" : arch ? `build-${arch}` : "build-dist";
   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(),
+    // Export builds use their own build cache: sharing build/ with dev's --symlink-install
+    // (or another arch) breaks the next colcon build.
+    // rclcpp export: ship librb_sdk.so in <pkg>/lib/ (robot has no SDK) when the node links it.
+    `colcon build ${flag} --build-base ${buildBase} --install-base ${installBase}`.replace("  ", " ") +
+      (arch ? ` --cmake-args '-DCMAKE_INSTALL_RPATH=$ORIGIN/..'` : ""),
+    ...(arch ? [`for d in ${installBase}/*/lib; do if readelf -d $(find "$d" -mindepth 2 -type f -executable) 2>/dev/null | grep -q librb_sdk; then cp -a $(dpkg -L rainbow-rb-sdk | grep -E '/librb_sdk[.]so[.][0-9]') "$d"/; fi; done`] : []),
   ].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],
+    // python/cpp 와 같이 호스트 uid 로 돌린다 — root 소유 산출물이 남으면 사용자가 지우지 못한다.
+    ["run", "--rm", ...platformFlags, ...dockerUserFlags(), "-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,27 +1,78 @@
-// muscat-pk sdk <list|update [version]> — manage the python rainbow-rb-sdk.
-import { spawnSync } from "node:child_process";
+// 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 { findPluginRoot, log } from "./util.mjs";
+import { cppSdkFiles, cppSdkPin, ensureIdeVenv, findPluginRoot, log, setCppSdkPin, venvPython } from "./util.mjs";
+import { readManifest } from "./manifest.mjs";
 
 const PKG = "rainbow-rb-sdk";
 
-async function fetchVersions() {
+async function fetchPypi() {
   try {
     const res = await fetch(`https://pypi.org/pypi/${PKG}/json`);
+    return res.ok ? await res.json() : null;
+  } catch {
+    return null;
+  }
+}
+
+async function fetchVersions() {
+  const data = await fetchPypi();
+  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 data = await res.json();
-    return Object.keys(data.releases || {}).sort((a, b) =>
-      b.localeCompare(a, undefined, { numeric: true }),
-    );
+    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") {
@@ -37,28 +88,27 @@ export async function runSdk(args = []) {
   if (sub === "update") {
     let version = args[1];
     if (!version) {
-      const versions = await fetchVersions();
-      version = versions[0] || "latest";
+      // info.version = latest stable
+      version = (await fetchPypi())?.info?.version;
+      if (!version) throw new Error("could not fetch the latest version (offline?). Pass one: muscat-pk sdk update <version>");
     }
+    // rainbow-rb-* pin each other exactly — bump them together.
     let content = existsSync(reqs) ? readFileSync(reqs, "utf8") : "";
-    const line = `${PKG}==${version}`;
-    if (new RegExp(`^${PKG}==`, "m").test(content)) {
-      content = content.replace(new RegExp(`^${PKG}==.*$`, "m"), line);
-    } else {
-      content = (content ? content.trimEnd() + "\n" : "") + line + "\n";
+    const pinned = /^(rainbow-rb-[\w-]+)\s*==.*$/gim;
+    const bumped = [...content.matchAll(pinned)].map((m) => m[1]);
+    content = content.replace(pinned, (_m, name) => `${name}==${version}`);
+    if (!bumped.some((n) => n.toLowerCase() === PKG)) {
+      content = (content ? content.trimEnd() + "\n" : "") + `${PKG}==${version}\n`;
+      bumped.push(PKG);
     }
     writeFileSync(reqs, content);
-    log.ok(`requirements.txt → ${line}`);
+    log.ok(`requirements.txt → ${bumped.map((n) => `${n}==${version}`).join(", ")}`);
 
-    const py = resolve(root, ".venv", "bin", "python");
-    if (existsSync(py)) {
-      log.step("pip install -r requirements.txt…");
-      spawnSync(py, ["-m", "pip", "install", "-q", "-r", reqs], {
-        cwd: root,
-        stdio: "inherit",
-      });
+    if (existsSync(venvPython(resolve(root, ".venv")))) {
+      log.step("refreshing .venv (for your editor)…");
+      if (!ensureIdeVenv(root)) log.warn(".venv refresh failed — the Docker dev container is unaffected.");
     } 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;
   }