@rainbow-robotics/muscat-plugin-kit 1.3.6-dev.8 → 1.3.7

package/cli/README.md

@@ -60,10 +60,10 @@ and `50051` are reserved and must not be used by external plugins.
 | runtime | source | notes |
 |---|---|---|
 | `{ "type": "none" }` | — | UI-only plugin; no backend container |
-| `{ "type": "python", "entry": "main.py" }` | `py/` | Uses `rainbow.rb_sdk.RBPluginCall` for UI/backend messaging |
-| `{ "type": "cpp", "entry": "<executable name>" }` | `cpp/` | Built with CMake in Docker; current template is a run skeleton |
+| `{ "type": "python", "entry": "main.py" }` | `py/` | Uses `rainbow.rb_sdk.RBPluginCall` for UI/backend messaging; `plugin.router` exposes external endpoints (`common/plugin/{id}/{path}`, needs sdk ≥ 0.0.9.dev5 on the robot; the dev bridge only registers routes — external calls need a running `common`) |
+| `{ "type": "cpp", "entry": "<executable name>" }` | `cpp/` | Built with CMake in Docker against the C++ SDK (apt `rainbow-rb-sdk-dev`, `find_package(rb_sdk)`, dynamic link) |
 | `{ "type": "ros2", "rosClient": "rclpy", ... }` | `ros2_ws/` | ROS2 Python node; may use Python SDK alongside ROS2 APIs |
-| `{ "type": "ros2", "rosClient": "rclcpp", ... }` | `ros2_ws/` | ROS2 C++ node built with colcon/CMake |
+| `{ "type": "ros2", "rosClient": "rclcpp", ... }` | `ros2_ws/` | ROS2 C++ node built with colcon/CMake, links the C++ SDK like `cpp` |
 
 All non-`none` runtimes run in Docker during `muscat-pk dev:back`, `muscat-pk
 dev`, and build/export flows so development matches the robot environment.
@@ -257,6 +257,11 @@ would break `dev` offline. Pre-seed an air-gapped machine with
 `docker save … | gzip` + `docker load`, or force a rebuild with
 `MUSCAT_PK_REBUILD_IMAGE=1`.
 
+The C++ images (`Dockerfile.cpp`, `Dockerfile.dev`) install `rainbow-rb-sdk-dev`
+from `https://rainbowrobotics.github.io/rb-sdk` (suite `dev`), pinned by the
+`RB_SDK_VERSION` build arg. Set `MUSCAT_PK_RB_SDK_VERSION=<version>` (with
+`MUSCAT_PK_REBUILD_IMAGE=1`) to match a robot running a different SDK version.
+
 On Linux the dev containers run as the invoking user (`--user`), so build output
 under `dist/` and `cpp/build-*` is not left root-owned.
 

package/cli/bin/muscat-pk.mjs

@@ -35,6 +35,11 @@ function readVersion(binPath) {
 
 const isBinaryMode = typeof Bun !== "undefined";
 
+// 바이너리에는 package.json 이 없다 — 컴파일 시 임베드한 버전을 쓴다.
+if (isBinaryMode && !process.env.MUSCAT_PK_VERSION) {
+  process.env.MUSCAT_PK_VERSION = (await import("../src/templates-embedded.mjs")).KIT_VERSION;
+}
+
 (function delegateToLocalInstall() {
   try {
     const localBin = resolveLocalCliBin();

package/cli/bundle-templates.mjs

@@ -2,7 +2,7 @@
 // Pre-build step: serialise cli/templates/** into cli/src/templates-embedded.mjs
 // so that `bun build --compile` can embed them without needing the filesystem.
 import { readdirSync, readFileSync, writeFileSync, statSync } from "node:fs";
-import { resolve, relative } from "node:path";
+import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const root = resolve(fileURLToPath(import.meta.url), "..");
@@ -19,10 +19,15 @@ function walk(baseDir, prefix) {
 }
 walk(resolve(root, "templates") + "/", "");
 walk(resolve(root, "docker") + "/", "docker/");
+// Dockerfile.bridge 의 COPY 대상
+files["src/socketBridge.mjs"] = readFileSync(resolve(root, "src/socketBridge.mjs"), "base64");
+
+const { version } = JSON.parse(readFileSync(resolve(root, "../package.json"), "utf8"));
 
 writeFileSync(out,
   `// AUTO-GENERATED by cli/bundle-templates.mjs — do not edit.\n` +
   `// ponytail: generated at publish time; not tracked in git.\n` +
+  `export const KIT_VERSION = ${JSON.stringify(version)};\n` +
   `export const TEMPLATES = ${JSON.stringify(files)};\n`
 );
 console.log(`bundled ${Object.keys(files).length} template files → src/templates-embedded.mjs`);

package/cli/docker/Dockerfile.cpp

@@ -10,12 +10,34 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       cmake \
     && rm -rf /var/lib/apt/lists/*
 
-# TODO(cpp-sdk): install the rainbow cpp SDK (dev package) here, pinned to the
-# robot's version, so plugins build/link against the same SDK as production.
-# Plan: apt package + dynamic link (the robot provides the .so at runtime;
-# we do NOT bundle it into the plugin binary). e.g.:
-#   RUN apt-get update && apt-get install -y rainbow-cpp-sdk-dev=<robot-version> \
-#       && rm -rf /var/lib/apt/lists/*
+# 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
+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}" \
+    && rm -rf /var/lib/apt/lists/*
+
+# MediaMTX — same version/ports as the Muscat runtime (rby2 scripts/backend/runtime/mediamtx.yml),
+# plus webrtcAdditionalHosts so a browser on the dev host reaches the WebRTC media port.
+ARG MEDIAMTX_VERSION=1.12.3
+RUN set -eux; \
+    apt-get update; apt-get install -y --no-install-recommends ca-certificates curl; rm -rf /var/lib/apt/lists/*; \
+    case "$(uname -m)" in x86_64) a=amd64 ;; aarch64|arm64) a=arm64 ;; *) exit 1 ;; esac; \
+    curl -fsSL "https://github.com/bluenviron/mediamtx/releases/download/v${MEDIAMTX_VERSION}/mediamtx_v${MEDIAMTX_VERSION}_linux_${a}.tar.gz" \
+      | tar -xz -C /usr/local/bin mediamtx; \
+    mkdir -p /etc/mediamtx; \
+    printf '%s\n' \
+      'logLevel: warn' \
+      'rtsp: yes' 'rtspAddress: :8554' \
+      'webrtc: yes' 'webrtcAddress: :8889' \
+      'webrtcLocalUDPAddress: :8189' 'webrtcLocalTCPAddress: :8189' \
+      'webrtcAdditionalHosts: [127.0.0.1]' 'webrtcAllowOrigin: "*"' \
+      'hls: no' 'rtmp: no' 'srt: no' 'api: no' \
+      'paths:' '  all_others:' '    source: publisher' \
+      > /etc/mediamtx/mediamtx.yml
 
 WORKDIR /plugin
 

package/cli/docker/Dockerfile.dev

@@ -9,6 +9,38 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       python3-colcon-common-extensions \
     && rm -rf /var/lib/apt/lists/*
 
+# 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
+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}" \
+    && rm -rf /var/lib/apt/lists/*
+
+# MediaMTX — same version/ports as the Muscat runtime (rby2 scripts/backend/runtime/mediamtx.yml),
+# plus webrtcAdditionalHosts so a browser on the dev host reaches the WebRTC media port.
+ARG MEDIAMTX_VERSION=1.12.3
+RUN set -eux; \
+    apt-get update; apt-get install -y --no-install-recommends ca-certificates curl; rm -rf /var/lib/apt/lists/*; \
+    case "$(uname -m)" in x86_64) a=amd64 ;; aarch64|arm64) a=arm64 ;; *) exit 1 ;; esac; \
+    curl -fsSL "https://github.com/bluenviron/mediamtx/releases/download/v${MEDIAMTX_VERSION}/mediamtx_v${MEDIAMTX_VERSION}_linux_${a}.tar.gz" \
+      | tar -xz -C /usr/local/bin mediamtx; \
+    mkdir -p /etc/mediamtx; \
+    printf '%s\n' \
+      'logLevel: warn' \
+      'rtsp: yes' 'rtspAddress: :8554' \
+      'webrtc: yes' 'webrtcAddress: :8889' \
+      'webrtcLocalUDPAddress: :8189' 'webrtcLocalTCPAddress: :8189' \
+      'webrtcAdditionalHosts: [127.0.0.1]' 'webrtcAllowOrigin: "*"' \
+      'hls: no' 'rtmp: no' 'srt: no' 'api: no' \
+      'paths:' '  all_others:' '    source: publisher' \
+      > /etc/mediamtx/mediamtx.yml
+
+# `docker exec` skips /ros_entrypoint.sh — source ROS for the login shells dev:back runs.
+RUN echo ". /opt/ros/${ROS_DISTRO}/setup.sh" > /etc/profile.d/ros.sh
+
 WORKDIR /plugin
 
 CMD ["bash"]

package/cli/docker/Dockerfile.python

@@ -15,6 +15,25 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 # cpp SDK shared lib must be present for the python module to load. Install the
 # rainbow cpp SDK (apt, pinned to the robot's version) here once it exists.
 
+# MediaMTX — same version/ports as the Muscat runtime (rby2 scripts/backend/runtime/mediamtx.yml),
+# plus webrtcAdditionalHosts so a browser on the dev host reaches the WebRTC media port.
+ARG MEDIAMTX_VERSION=1.12.3
+RUN set -eux; \
+    apt-get update; apt-get install -y --no-install-recommends ca-certificates curl; rm -rf /var/lib/apt/lists/*; \
+    case "$(uname -m)" in x86_64) a=amd64 ;; aarch64|arm64) a=arm64 ;; *) exit 1 ;; esac; \
+    curl -fsSL "https://github.com/bluenviron/mediamtx/releases/download/v${MEDIAMTX_VERSION}/mediamtx_v${MEDIAMTX_VERSION}_linux_${a}.tar.gz" \
+      | tar -xz -C /usr/local/bin mediamtx; \
+    mkdir -p /etc/mediamtx; \
+    printf '%s\n' \
+      'logLevel: warn' \
+      'rtsp: yes' 'rtspAddress: :8554' \
+      'webrtc: yes' 'webrtcAddress: :8889' \
+      'webrtcLocalUDPAddress: :8189' 'webrtcLocalTCPAddress: :8189' \
+      'webrtcAdditionalHosts: [127.0.0.1]' 'webrtcAllowOrigin: "*"' \
+      'hls: no' 'rtmp: no' 'srt: no' 'api: no' \
+      'paths:' '  all_others:' '    source: publisher' \
+      > /etc/mediamtx/mediamtx.yml
+
 WORKDIR /plugin
 
 CMD ["bash"]

package/cli/src/bridge.mjs

@@ -5,24 +5,41 @@
 //     it at localhost:10000 too — no host.docker.internal needed (robust cross-OS).
 import { spawnSync } from "node:child_process";
 import { createServer, connect } from "node:net";
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, resolve } from "node:path";
 import { canSkipImageBuild, hasBin, kitRoot, log, pruneMuskatImages } from "./util.mjs";
+import { MEDIA_PORTS, mediaPortFlags } from "./ports.mjs";
+import { usesHostNetwork } from "./zenohDev.mjs";
 
 export const BRIDGE_IMAGE = "muscat-pk-bridge";
 export const BRIDGE_CONTAINER = "muscat-pk-bridge-run";
 export const BRIDGE_PORT = 10000;
 
-const DOCKERFILE = resolve(kitRoot, "cli/docker/Dockerfile.bridge");
-const BUILD_CONTEXT = resolve(kitRoot, "cli");
+// 컴파일된 바이너리에는 cli/ 트리가 없어 임베드 스냅샷에서 build context 를 tmp 에 복원한다.
+const BRIDGE_CONTEXT_FILES = ["docker/Dockerfile.bridge", "docker/bridge-package.json", "src/socketBridge.mjs"];
+
+async function resolveBridgeContext() {
+  const context = resolve(kitRoot, "cli");
+  const dockerfile = resolve(context, "docker/Dockerfile.bridge");
+  if (existsSync(dockerfile)) return { dockerfile, context };
+
+  const { TEMPLATES } = await import("./templates-embedded.mjs");
+  const dir = resolve(tmpdir(), "muscat-pk-bridge-context");
+  for (const key of BRIDGE_CONTEXT_FILES) {
+    const b64 = TEMPLATES[key];
+    if (!b64) throw new Error(`Embedded file missing: ${key}. Reinstall muscat-plugin-kit.`);
+    const file = resolve(dir, key);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, Buffer.from(b64, "base64"));
+  }
+  return { dockerfile: resolve(dir, "docker/Dockerfile.bridge"), context: dir };
+}
 
 function assertDockerReady() {
   if (!hasBin("docker")) {
     throw new Error("Docker not found. `muscat-pk dev` runs the Socket.IO bridge in a container.");
   }
-  if (!existsSync(DOCKERFILE)) {
-    throw new Error(`kit Dockerfile missing at ${DOCKERFILE} (reinstall muscat-plugin-kit).`);
-  }
 }
 
 // Is a host TCP port already bound? (Catches another bridge or a stray process.)
@@ -52,20 +69,28 @@ function waitForPort(port, timeoutMs = 15_000) {
   });
 }
 
-function ensureImage() {
+async function ensureImage() {
   if (canSkipImageBuild(BRIDGE_IMAGE)) {
     log.step(`${BRIDGE_IMAGE} already built — skipping docker build`);
     return;
   }
+  const { dockerfile, context } = await resolveBridgeContext();
   log.step(`docker build -t ${BRIDGE_IMAGE} (first run is slow, then cached)…`);
-  const r = spawnSync("docker", ["build", "-t", BRIDGE_IMAGE, "-f", DOCKERFILE, BUILD_CONTEXT], { stdio: "inherit" });
+  const r = spawnSync("docker", ["build", "-t", BRIDGE_IMAGE, "-f", dockerfile, context], { stdio: "inherit" });
   if (r.status !== 0) throw new Error("docker build failed (bridge image).");
   pruneMuskatImages();
 }
 
+/** A running Muscat container (e.g. muscat-dev) that owns host port 10000, or null. */
+export function localMuscatContainer() {
+  const r = spawnSync("docker", ["ps", "--filter", `publish=${BRIDGE_PORT}`, "--format", "{{.Names}}"], { encoding: "utf8" });
+  return (r.stdout || "").split("\n").map((n) => n.trim()).find((n) => n && n !== BRIDGE_CONTAINER) ?? null;
+}
+
 /**
  * Build the image, preflight the port, and start the bridge container.
- * Returns true if bridge started, false if port was already in use (caller decides).
+ * Returns false if port 10000 was already in use (caller decides), else { media }:
+ * whether the MediaMTX ports are free for the backend's own MediaMTX.
  */
 export async function startBridge({ zenohPort = null, pluginPorts = [] } = {}) {
   assertDockerReady();
@@ -88,7 +113,14 @@ export async function startBridge({ zenohPort = null, pluginPorts = [] } = {}) {
   }
   const publishable = pluginPorts.filter((port) => !busy.includes(port));
 
-  ensureImage();
+  const mediaBusy = [];
+  for (const port of MEDIA_PORTS) {
+    if (await isPortInUse(port)) mediaBusy.push(port);
+  }
+  const media = mediaBusy.length === 0;
+  if (!media) log.warn(`MediaMTX port(s) already in use: ${mediaBusy.join(", ")} — video streaming disabled in dev.`);
+
+  await ensureImage();
 
   log.step("starting Socket.IO bridge container…");
   // The backend joins THIS container's netns (--network container:), and a
@@ -98,6 +130,7 @@ export async function startBridge({ zenohPort = null, pluginPorts = [] } = {}) {
     "-p", `127.0.0.1:${BRIDGE_PORT}:${BRIDGE_PORT}`,
     ...(zenohPort ? ["-p", `${zenohPort}:${zenohPort}`] : []),
     ...publishable.flatMap((port) => ["-p", `127.0.0.1:${port}:${port}`]),
+    ...(media && !usesHostNetwork() ? mediaPortFlags() : []),
   ];
   const up = spawnSync(
     "docker",
@@ -111,7 +144,7 @@ export async function startBridge({ zenohPort = null, pluginPorts = [] } = {}) {
   if (zenohPort) log.step(`Zenoh dev peer port published on :${zenohPort}`);
   if (publishable.length > 0)
     log.step(`plugin backend ports published on 127.0.0.1: ${publishable.join(", ")}`);
-  return true;
+  return { media };
 }
 
 export function stopBridge() {

package/cli/src/build.mjs

@@ -74,34 +74,36 @@ function runViteBuild(pluginRoot, { mode = "production" } = {}) {
 // For ros2 plugins, compile the colcon workspace inside the Jazzy + Python 3.12 container.
 // rclpy: arch-agnostic (pure Python) → dist/ros2_ws/install/ (built once)
 // rclcpp: arch-specific C++ binaries → dist/ros2_ws/install-{arch}/ per arch
+// Cross-arch C++ builds run inside an emulated container. Docker Desktop ships the
+// emulation; native Linux needs binfmt/QEMU — check up front so the error says so.
+function assertCanBuildArch(arch, dockerPlatform) {
+  const info = spawnSync("docker", ["info", "--format", "{{.Architecture}}"], { encoding: "utf8" });
+  const host = { x86_64: "amd64", aarch64: "arm64", arm64: "arm64" }[(info.stdout || "").trim()] ?? "";
+  if (arch === host) return;
+  const r = spawnSync("docker", ["run", "--rm", "--platform", dockerPlatform, "ubuntu:24.04", "true"], { stdio: "ignore" });
+  if (r.status === 0) return;
+  throw new Error(
+    `can't build ${arch} on this ${host || "machine"}: Docker has no ${arch} emulation.\n` +
+    `  enable it once:  docker run --privileged --rm tonistiigi/binfmt --install ${arch}\n` +
+    `  or build only this machine's arch:  muscat-pk build --arch ${host || "<arch>"}`,
+  );
+}
+
 export async function exportRos2Build(root, archs = ["amd64", "arm64"]) {
-  if (manifestRuntime(root) !== "ros2") return [];
+  if (manifestRuntime(root) !== "ros2") return;
   const { assertDockerReady, ensureImage, colconBuild, ROS2_DEV_IMAGE, ARCH_DOCKER_PLATFORM } = await import("./ros2.mjs");
-  try {
-    assertDockerReady();
-  } catch (e) {
-    log.warn(`ros2 build skipped: ${e.message}`);
-    return [];
-  }
+  assertDockerReady();
 
   const manifest = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8"));
-  const rosClient = manifest.runtime?.rosClient;
-
-  const skipped = [];
-  if (rosClient === "rclcpp") {
+  if (manifest.runtime?.rosClient === "rclcpp") {
     // C++ ROS2: compile per arch so each robot picks the right install-{arch}/
     for (const arch of archs) {
       const dockerPlatform = ARCH_DOCKER_PLATFORM[arch];
-      if (!dockerPlatform) { log.warn(`unknown arch '${arch}' — skipped`); skipped.push(arch); continue; }
-      const archImage = `${ROS2_DEV_IMAGE}-${arch}`;
-      try {
-        await ensureImage(archImage, { platform: dockerPlatform });
-        colconBuild(root, { symlink: false, arch });
-        log.ok(`dist/ros2_ws/install-${arch}/ ready`);
-      } catch {
-        log.warn(`${arch} ros2 build skipped — QEMU not available`);
-        skipped.push(arch);
-      }
+      if (!dockerPlatform) throw new Error(`unknown arch '${arch}'`);
+      assertCanBuildArch(arch, dockerPlatform);
+      await ensureImage(`${ROS2_DEV_IMAGE}-${arch}`, { platform: dockerPlatform });
+      colconBuild(root, { symlink: false, arch });
+      log.ok(`dist/ros2_ws/install-${arch}/ ready`);
     }
   } else {
     // rclpy / pure Python: arch-agnostic, build once
@@ -109,54 +111,38 @@ export async function exportRos2Build(root, archs = ["amd64", "arm64"]) {
     colconBuild(root, { symlink: false });
     log.ok("dist/ros2_ws/install/ ready");
   }
-  return skipped;
 }
 
 // For cpp plugins, compile cpp/ inside the Ubuntu container (Release) per arch
 // and copy each binary into dist/{arch}/{entry} so the ZIP carries relocatable
-// robot-compatible executables. rb-runtime prefers dist/{arch}/ and falls back
-// to dist/{entry} (legacy). Skipped (with a warning) if Docker is unavailable.
+// robot-compatible executables.
 export async function exportCppBuild(root, distDir, archs = ["amd64", "arm64"]) {
-  if (manifestRuntime(root) !== "cpp") return [];
+  if (manifestRuntime(root) !== "cpp") return;
   const { assertDockerReady, ensureImage, cmakeBuild, CPP_DEV_IMAGE, ARCH_DOCKER_PLATFORM } = await import("./cpp.mjs");
-  try {
-    assertDockerReady();
-  } catch (e) {
-    log.warn(`cpp build skipped: ${e.message}`);
-    return [];
-  }
+  assertDockerReady();
 
   const entry = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime?.entry;
-  if (!entry) {
-    log.warn("manifest.json runtime.entry not set — cpp build skipped");
-    return;
-  }
+  if (!entry) throw new Error("manifest.json runtime.entry is required for cpp (the built executable name)");
 
-  const skipped = [];
   for (const arch of archs) {
     const dockerPlatform = ARCH_DOCKER_PLATFORM[arch];
-    if (!dockerPlatform) { log.warn(`unknown arch '${arch}' — skipped`); skipped.push(arch); continue; }
-    const archImage = `${CPP_DEV_IMAGE}-${arch}`;
-    try {
-      await ensureImage(archImage, { platform: dockerPlatform });
-      cmakeBuild(root, { buildType: "Release", arch });
-      const built = resolve(root, `cpp/build-${arch}`, entry);
-      if (existsSync(built)) {
-        const archDir = resolve(distDir, arch);
-        mkdirSync(archDir, { recursive: true });
-        const dest = resolve(archDir, entry);
-        copyFileSync(built, dest);
-        chmodSync(dest, 0o755);
-        log.ok(`cpp binary → dist/${arch}/${entry}`);
-      } else {
-        log.warn(`cpp binary not found at cpp/build-${arch}/${entry}`);
-      }
-    } catch {
-      log.warn(`${arch} cpp build skipped — QEMU not available`);
-      skipped.push(arch);
+    if (!dockerPlatform) throw new Error(`unknown arch '${arch}'`);
+    assertCanBuildArch(arch, dockerPlatform);
+    await ensureImage(`${CPP_DEV_IMAGE}-${arch}`, { platform: dockerPlatform });
+    cmakeBuild(root, { buildType: "Release", arch });
+    const built = resolve(root, `cpp/build-${arch}`, entry);
+    if (!existsSync(built)) {
+      throw new Error(`cpp/build-${arch}/${entry} not found — the CMake target name must equal runtime.entry`);
     }
+    const archDir = resolve(distDir, arch);
+    mkdirSync(archDir, { recursive: true });
+    const dest = resolve(archDir, entry);
+    copyFileSync(built, dest);
+    chmodSync(dest, 0o755);
+    const libDir = resolve(root, `cpp/build-${arch}`, "lib");
+    if (existsSync(libDir)) cpSync(libDir, resolve(archDir, "lib"), { recursive: true, verbatimSymlinks: true });
+    log.ok(`cpp binary → dist/${arch}/${entry}${existsSync(libDir) ? " (+ lib/)" : ""}`);
   }
-  return skipped;
 }
 
 const PRERELEASE_RE = /\.(dev|a|b|rc|alpha|beta)\d*/i;
@@ -426,11 +412,12 @@ export async function runBuild(args) {
 
   await promptVersion(root);
   const archs = await promptArch(args);
+  // Drop a previous ZIP of this version so a failed build can't leave a stale one to upload.
+  const version = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).version || "0.0.0";
+  rmSync(resolve(root, `${basename(root)}-${version}.zip`), { force: true });
 
   const { pluginRoot, distDir } = await buildPlugin({ root, minify: true });
 
-  const skippedArches = { wheels: [], ros2: [], cpp: [] };
-
   // python / rclpy: lock + wheel vendor in Ubuntu 24.04 container
   if (!noLock) {
     const manifest = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime ?? {};
@@ -439,30 +426,12 @@ export async function runBuild(args) {
       (manifest.type === "ros2" && manifest.rosClient === "rclpy");
     if (needsLock) {
       const { lockAndVendor } = await import("./python.mjs");
-      try {
-        skippedArches.wheels = await lockAndVendor(pluginRoot, archs);
-      } catch (e) {
-        log.warn(`python lock/vendor skipped: ${e.message}`);
-        skippedArches.wheels = archs;
-      }
+      await lockAndVendor(pluginRoot, archs);
     }
   }
 
-  skippedArches.ros2 = await exportRos2Build(root, archs) ?? [];
-  skippedArches.cpp  = await exportCppBuild(root, distDir, archs) ?? [];
+  await exportRos2Build(root, archs);
+  await exportCppBuild(root, distDir, archs);
   calcInstalledSize(pluginRoot);
   if (!noZip) packZip(pluginRoot);
-
-  // Build summary
-  const allSkipped = [...new Set([...skippedArches.wheels, ...skippedArches.ros2, ...skippedArches.cpp])];
-  if (allSkipped.length > 0) {
-    const line = "─".repeat(58);
-    console.log(`\n${line}`);
-    log.warn(`Cross-arch builds skipped (QEMU not available): ${allSkipped.join(", ")}`);
-    if (skippedArches.wheels.length) log.warn(`  wheels:  ${skippedArches.wheels.join(", ")}`);
-    if (skippedArches.ros2.length)   log.warn(`  ros2:    ${skippedArches.ros2.join(", ")}`);
-    if (skippedArches.cpp.length)    log.warn(`  cpp:     ${skippedArches.cpp.join(", ")}`);
-    log.warn(`  Enable: docker run --privileged --rm tonistiigi/binfmt --install all`);
-    console.log(line);
-  }
 }

package/cli/src/cpp.mjs

@@ -3,7 +3,7 @@
 // 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, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+import { canSkipImageBuild, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
 
 export const CPP_DEV_IMAGE = "muscat-pk-cpp-dev";
 
@@ -15,16 +15,19 @@ 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 } = {}) {
-  if (canSkipImageBuild(image)) {
+  const dockerfile = await resolveDockerfile("Dockerfile.cpp");
+  const sdkVer = process.env.MUSCAT_PK_RB_SDK_VERSION;
+  const key = imageKey(dockerfile, sdkVer ?? "");
+  if (canSkipImageBuild(image, key)) {
     log.step(`${image} already built — skipping docker build`);
     return;
   }
-  const dockerfile = await resolveDockerfile("Dockerfile.cpp");
   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", ...platformFlags, "-t", image, "-f", dockerfile, dirname(dockerfile)],
+    ["build", ...platformFlags, ...buildArgs, "-t", image, "-f", dockerfile, dirname(dockerfile)],
     { stdio: "inherit" },
   );
   if (r.status !== 0) throw new Error("docker build failed.");
@@ -50,9 +53,12 @@ export function cmakeBuild(root, { image = CPP_DEV_IMAGE, buildType = "Debug", a
   const platformFlags = dockerPlatform ? ["--platform", dockerPlatform] : [];
   // arch 빌드 시 arch별 이미지 사용 (로컬 이미지와 platform 불일치 방지)
   const actualImage = arch ? `${CPP_DEV_IMAGE}-${arch}` : image;
+  // Export builds ship lib/ next to the binary: librb_sdk.so (robot has no SDK) + any .so the
+  // plugin copied there itself. Found via RPATH $ORIGIN/lib.
   const script = [
-    `cmake -S cpp -B ${buildDir} -DCMAKE_BUILD_TYPE=${buildType}`,
+    `cmake -S cpp -B ${buildDir} -DCMAKE_BUILD_TYPE=${buildType}` + (arch ? ` -DCMAKE_BUILD_RPATH='$ORIGIN/lib'` : ""),
     `cmake --build ${buildDir} -j`,
+    ...(arch ? [`rm -f ${buildDir}/lib/librb_sdk.so.* && if readelf -d $(find ${buildDir} -maxdepth 1 -type f -executable) 2>/dev/null | grep -q librb_sdk; then mkdir -p ${buildDir}/lib && cp -a $(dpkg -L rainbow-rb-sdk | grep -E '/librb_sdk[.]so[.][0-9]') ${buildDir}/lib/; fi`] : []),
   ].join(" && ");
   const label = arch ? `cmake build (${buildType}, ${arch}, in container)…` : `cmake build (${buildType}, in container)…`;
   log.step(label);

package/cli/src/dev.mjs

@@ -6,7 +6,7 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runDevUi } from "./devUi.mjs";
 import { runDevBack, stopDevBackContainers } from "./devBack.mjs";
-import { startBridge, stopBridge, BRIDGE_CONTAINER, BRIDGE_PORT } from "./bridge.mjs";
+import { localMuscatContainer, startBridge, stopBridge, BRIDGE_CONTAINER, BRIDGE_PORT } from "./bridge.mjs";
 import { assertManifestPorts, assertManifestVariables } from "./manifest.mjs";
 import { formatPortRanges } from "./ports.mjs";
 import {
@@ -138,7 +138,11 @@ export async function runDev(args = []) {
     pluginPorts: usesHostNetwork() ? [] : portRanges,
   });
 
-  if (!bridgeStarted) {
+  const muscat = bridgeStarted ? null : 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;
+  } else if (!bridgeStarted) {
     log.warn(`port ${BRIDGE_PORT} is already in use — can't start Socket.IO bridge.`);
     const answer = await prompt("  Proceed without Socket.IO bridge? [y/N]: ");
     if (answer.toLowerCase() !== "y") return;
@@ -147,6 +151,7 @@ export async function runDev(args = []) {
     // Tell dev:back which bridge container to share a netns with, so the backend
     // reaches the bridge at localhost:10000 (no host.docker.internal).
     process.env.MUSCAT_PK_BRIDGE_CONTAINER = BRIDGE_CONTAINER;
+    if (bridgeStarted.media) process.env.MUSCAT_PK_MEDIA = "1";
   }
 
   process.env.MUSCAT_PK_MANAGED_DEV = "1";