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

package/README.md

@@ -159,7 +159,7 @@ Move images to a machine with no internet:
 
 ```bash
 # on a machine with network
-docker save muscat-pk-python-dev muscat-pk-bridge | gzip > muscat-pk-images.tar.gz
+docker save muscat-pk-python-dev muscat-pk-runtime | gzip > muscat-pk-images.tar.gz
 
 # on the offline machine
 gunzip -c muscat-pk-images.tar.gz | docker load
@@ -198,12 +198,12 @@ The runtime monitor is strict on purpose: an undeclared port outside the plugin
 range is invisible to both the monitor and the robot's conflict check, so it
 would only surface as a collision after deployment.
 
-`muscat-pk`'s own dev plumbing (the Socket.IO bridge on `10000`, the Zenoh dev
+`muscat-pk`'s own dev plumbing (the plugin gateway on `10000`, the Zenoh dev
 peer port) is excluded from the check — it isn't the plugin's traffic.
 
-Declared ports are published to `127.0.0.1` on macOS and Windows so you can
-reach the backend from the host; native Linux uses host networking, where they
-already are.
+Under `muscat-pk dev` declared ports are published to `127.0.0.1` from the local
+Muscat container (the backend shares its network), so you can reach the backend
+from the host.
 
 ## Variables (pyfm)
 

package/cli/README.md

@@ -42,12 +42,12 @@ the backend**, whatever its number. Since a port outside `28600-28999` cannot be
 declared, it cannot be opened either — otherwise it would slip past both this
 check and the robot's install-time conflict check.
 
-The kit's own dev ports (Socket.IO bridge `10000`, the Zenoh dev peer port) are
+The kit's own dev ports (plugin gateway `10000`, the Zenoh dev peer port) are
 excluded from that check.
 
-Declared ports are published to `127.0.0.1` so the host can reach the backend on
-macOS/Windows; native Linux dev containers use host networking and already have
-them. A declared port that is already busy on the host is skipped with a warning.
+Under `muscat-pk dev` the backend shares the local Muscat container's network, so
+declared ports are published to `127.0.0.1` from that container. A declared port
+that is already busy on the host is skipped with a warning.
 
 Known robot/industrial/internal ports such as `502`, `4840`, `5170-5179`,
 `8000-8999`, `10000`, `2222`, `30004`, `34964`, `44818`, `50000-50005`,

package/cli/bin/muscat-pk.mjs

@@ -81,7 +81,7 @@ function formatHelp() {
     commandRow("new [dir]", `Scaffold a new plugin project ${color.dim("(prompts: author, email, description, type, front-package-manager)")}`),
     commandRow("type change", `Switch backend type ${color.dim("(python | cpp | ros2-python | ros2-cpp)")}`),
     commandRow("build", `Build + lock deps + vendor wheels + zip ${color.dim(`(${option("--no-zip")}: skip zip, ${option("--no-lock")}: skip python lock/vendor, ${option("--arch")} amd64|arm64|both)`)}`),
-    commandRow("dev", "Run Socket.IO bridge, dev:ui, and dev:back together"),
+    commandRow("dev", "Run a local Muscat runtime, dev:ui, and dev:back together"),
     commandRow("dev:ui", `Preview the plugin in a mini-Muscat ${color.dim("(preview-host)")}`),
     commandRow("dev:back", `Run the plugin back end ${color.dim("(python: watchfiles reload / ros2: Docker)")}`),
     commandRow("storybook", `Browse the bundled rb-components Storybook ${color.dim(`(${option("--port")} <n>, ${option("--rebuild")})`)}`),

package/cli/bundle-templates.mjs

@@ -19,8 +19,6 @@ 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"));
 

package/cli/docker/Dockerfile.cpp

@@ -10,35 +10,18 @@ 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). 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.10.2
+# Rainbow Robotics C++ SDK for find_package(rb_sdk). muscat-pk passes the version pinned in the
+# project's CMakeLists.txt (find_package(rb_sdk <ver> EXACT)); without a pin (ROS 2 rclpy, `muscat-pk mcp`
+# outside a project) the newest SDK is installed. Runtime and -dev are installed together at one version.
+ARG RB_SDK_VERSION=
 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=${RB_SDK_VERSION}" "rainbow-rb-sdk-dev=${RB_SDK_VERSION}" \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends "rainbow-rb-sdk${RB_SDK_VERSION:+=$RB_SDK_VERSION}" "rainbow-rb-sdk-dev${RB_SDK_VERSION:+=$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,34 +9,18 @@ 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.10.2
+# Rainbow Robotics C++ SDK for find_package(rb_sdk). muscat-pk passes the version pinned in the
+# project's CMakeLists.txt (find_package(rb_sdk <ver> EXACT)); without a pin (ROS 2 rclpy, `muscat-pk mcp`
+# outside a project) the newest SDK is installed. Runtime and -dev are installed together at one version.
+ARG RB_SDK_VERSION=
 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=${RB_SDK_VERSION}" "rainbow-rb-sdk-dev=${RB_SDK_VERSION}" \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends "rainbow-rb-sdk${RB_SDK_VERSION:+=$RB_SDK_VERSION}" "rainbow-rb-sdk-dev${RB_SDK_VERSION:+=$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

package/cli/docker/Dockerfile.python

@@ -15,24 +15,6 @@ 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
 

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, cppSdkVersion, pluginRootOrNull, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } 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 CPP_DEV_IMAGE = "muscat-pk-cpp-dev";
@@ -35,7 +35,7 @@ async function buildImage(image, platform, root) {
   const buildArgs = [...(sdkVer ? ["--build-arg", `RB_SDK_VERSION=${sdkVer}`] : []), ...imageKeyLabel(key)];
   const r = spawnSync(
     "docker",
-    ["build", ...platformFlags, ...buildArgs, "-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.");

package/cli/src/dev.mjs

@@ -1,4 +1,4 @@
-// muscat-pk dev — run the Socket.IO bridge (Docker), dev:ui, and dev:back together.
+// muscat-pk dev — run the local Muscat runtime (gateway, MediaMTX, common), dev:ui, and dev:back together.
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { connect as netConnect } from "node:net";
@@ -6,8 +6,7 @@ import { resolve } from "node:path";
 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 { ensureLocalMuscat, GATEWAY_PORT, isPortInUse } from "./muscatLocal.mjs";
 import { assertManifestPorts, assertManifestVariables } from "./manifest.mjs";
 import { formatPortRanges } from "./ports.mjs";
 import {
@@ -19,7 +18,7 @@ import {
   promptRobotConnection,
   venvPython,
 } from "./util.mjs";
-import { ensureRemoteZenohEnv, isRemoteRobot, isWsl, usesHostNetwork } from "./zenohDev.mjs";
+import { ensureRemoteZenohEnv, isRemoteRobot, isWsl } from "./zenohDev.mjs";
 
 const HOST_AGENT_PATH = fileURLToPath(new URL("./host_agent.py", import.meta.url));
 const canAutoStartHostAgent = () => process.platform === "darwin" || isWsl();
@@ -100,7 +99,7 @@ async function maybeStartHostAgent(root, { robotIp, robotToken }) {
   }
 
   // advertiseHost (not host.docker.internal): a Docker Desktop container run
-  // under `dev` may share the bridge container's netns (--network container:),
+  // under `dev` shares the local Muscat container's netns (--network container:),
   // which has no host-gateway alias configured — the host's real LAN IP
   // always resolves regardless of netns mode.
   const proxyEndpoint = `${advertiseHost}:${proxyPort}`;
@@ -124,41 +123,29 @@ 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
-  // the robot itself — startBridge() then publishes the zenoh port for it.
+  // the robot itself — the local Muscat then publishes the zenoh port for it.
   if (!proxyEndpoint) await ensureRemoteZenohEnv(robotIp, { log });
 
-  log.step("starting Socket.IO bridge (Docker) + dev:ui + dev:back");
-  // 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,
-    // Linux uses --network host, so the ports are already on the host.
-    pluginPorts: usesHostNetwork() ? [] : portRanges,
-  });
-
-  const muscat = bridgeStarted ? null : (localMuscat ?? localMuscatContainer());
+  // Robot or not, the local Muscat runtime is the gateway (:10000), MediaMTX and common; the
+  // backend joins its netns, so the plugin's declared ports are published from it too.
+  log.step("starting local Muscat (Docker) + dev:ui + dev:back");
+  const muscat = await ensureLocalMuscat({
+    pluginPorts: portRanges,
+    zenohPort: remoteRobot && !proxyEndpoint ? Number(process.env.MUSCAT_ZENOH_PORT) || null : null,
+  }).catch((e) => { log.warn(`local Muscat: ${e.message}`); return null; });
   if (muscat) {
-    log.step(`local Muscat container '${muscat}' owns :${BRIDGE_PORT} — backend joins its network (gateway, MediaMTX)`);
+    log.step(`local Muscat container '${muscat}' owns :${GATEWAY_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;
-    log.info("proceeding without bridge — backend will skip network sharing.");
+  } else if (await isPortInUse(GATEWAY_PORT)) {
+    // e.g. developing on the robot PC: its Muscat already serves the gateway; the backend reaches it via the host.
+    log.step(`:${GATEWAY_PORT} is already served (Muscat on this machine) — using it`);
   } else {
-    // 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";
+    log.warn(`no local Muscat on :${GATEWAY_PORT} — the plugin UI cannot reach the backend.`);
+    const answer = await prompt("  Proceed anyway? [y/N]: ");
+    if (answer.toLowerCase() !== "y") return;
   }
 
   process.env.MUSCAT_PK_MANAGED_DEV = "1";
@@ -166,7 +153,6 @@ export async function runDev(args = []) {
   const cleanup = () => {
     if (hostAgent && hostAgent.exitCode === null) hostAgent.kill();
     stopDevBackContainers();
-    if (bridgeStarted) stopBridge();
   };
   process.once("SIGINT", cleanup);
   process.once("SIGTERM", cleanup);

package/cli/src/devBack.mjs

@@ -2,7 +2,7 @@
 // Every backend runs in a warm Docker container that matches the robot
 // (Ubuntu 24.04), so dev behaves like production.
 //   python : Python 3.12 container, pip install, run main.py with watchfiles
-//            hot-reload. Shares the bridge container's netns (localhost:10000).
+//            hot-reload. Shares the local Muscat container's netns (localhost:10000).
 //   cpp    : Ubuntu + cmake container, build cpp/, run the binary, rebuild +
 //            restart on source changes.
 //   ros2   : Jazzy + Python 3.12 container, colcon build, run the node, restart
@@ -13,7 +13,7 @@ import { isIP } from "node:net";
 import { dirname, resolve } from "node:path";
 import { dockerUserFlags, ensureDocker, ensureIdeVenv, findPluginRoot, log, promptRobotConnection, realtimeFlags } from "./util.mjs";
 import { ensureRemoteZenohEnv, isRemoteRobot, usesHostNetwork } from "./zenohDev.mjs";
-import { localMuscatContainer } from "./bridge.mjs";
+import { localMuscatContainer } from "./muscatLocal.mjs";
 import { PLUGIN_ID_RE, assertManifestPorts, assertManifestVariables, manifestRuntime, readManifest, rosNamespace, validateManifest } from "./manifest.mjs";
 import {
   formatPortRanges,
@@ -54,9 +54,9 @@ 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.
+// Where the backend's 127.0.0.1 points. A local Muscat container (muscat-pk-muscat, muscat-dev):
+// join its netns so the gateway and MediaMTX resolve like on the robot. Otherwise 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) {
@@ -70,8 +70,6 @@ function backendNetwork(portRanges) {
   const muscat = process.env.MUSCAT_PK_MUSCAT_CONTAINER;
   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 };
   return {
     // host.docker.internal is automatic on Docker Desktop; this makes it resolve on Linux too.
     run: [...publishPortFlags(portRanges), "--add-host", "host.docker.internal:host-gateway"],
@@ -117,13 +115,6 @@ async function serveRosPeers(root, pluginId, restart) {
   });
 }
 
-// Our own MediaMTX, only when `dev` found its ports free (a local Muscat brings its own).
-function startMediaServer(container) {
-  if (process.env.MUSCAT_PK_MEDIA !== "1") return;
-  spawnSync("docker", ["exec", "-d", container, "mediamtx", "/etc/mediamtx/mediamtx.yml"], { stdio: "ignore" });
-  log.step("MediaMTX: publish rtsp://127.0.0.1:8554/<path> · play http://localhost:8889/<path>");
-}
-
 // ── IDE tooling venv (best-effort, non-blocking) ────────────────────────────
 // `muscat-pk new` already creates this up front (see new.mjs); this just
 // refreshes it on every `dev`/`dev:back` in case requirements.txt changed.
@@ -144,8 +135,8 @@ function syncIdeVenv(root) {
 
 // ── python ────────────────────────────────────────────────────────────────────
 // Runs in a warm Ubuntu 24.04 + Python 3.12 container (matches the robot).
-// Under `muscat-pk dev`, it shares the bridge container's netns, so the SDK
-// reaches the Socket.IO bridge at the default localhost:10000.
+// Under `muscat-pk dev`, it shares the local Muscat container's netns, so the SDK
+// reaches the plugin gateway at the default localhost:10000.
 async function runPython(root, portRanges) {
   // Independent of Docker readiness — must still happen if Docker isn't
   // installed/running, since that's exactly when local IDE tooling matters most.
@@ -164,7 +155,7 @@ async function runPython(root, portRanges) {
   // Zenoh mesh, so it speaks a byte protocol to the host-side proxy instead.
   const proxyEndpoint = process.env.MUSCAT_PROXY_ENDPOINT ?? "";
   // Native Linux (not WSL, not Docker Desktop) has real host networking: the
-  // container shares the host's network stack, so it reaches the bridge at
+  // container shares the host's network stack, so it reaches the gateway at
   // localhost:10000 and the robot's Zenoh router / reverse-dial path directly
   // — no netns sharing, port publishing, host.docker.internal, or byte-proxy.
   const net = backendNetwork(portRanges);
@@ -205,7 +196,6 @@ async function runPython(root, portRanges) {
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
-  startMediaServer(container);
   const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [zenohPort] });
 
   log.step("pip install requirements + watchfiles (in container)…");
@@ -423,7 +413,7 @@ runpy.run_path("/plugin/py/main.py", run_name="__main__")
 PY`]);
 
   if (pluginId) log.step(`RB_PLUGIN_ID=${pluginId}`);
-  if (usesHostNetwork()) log.step("network: host (native Linux — direct robot/bridge access)");
+  if (usesHostNetwork()) log.step("network: host (native Linux — direct robot/gateway access)");
   if (proxyEndpoint) log.step(`Zenoh via host byte-proxy → ${proxyEndpoint}`);
   else if (zenohAdvertiseHost && zenohPort) log.step(`Zenoh advertise → ${zenohAdvertiseHost}:${zenohPort}`);
   log.step("watchfiles → py/main.py (reload on any .py change in py/)");
@@ -503,7 +493,6 @@ async function runRos2(root, portRanges) {
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
-  startMediaServer(container);
   const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [process.env.MUSCAT_ZENOH_PORT] });
 
   // one-time deps + symlink build (edits to .py reflect without rebuilding)
@@ -596,7 +585,6 @@ async function runCpp(root, portRanges) {
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
-  startMediaServer(container);
   const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [process.env.MUSCAT_ZENOH_PORT] });
 
   const build = () => {

package/cli/src/muscatLocal.mjs

@@ -1,22 +1,25 @@
-// 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.
+// Local Muscat runtime for `dev` / `dev:ui`, with or without a robot. It is the plugin gateway
+// (:10000, plugin-socketio — same Socket.IO protocol as on the robot), MediaMTX, and `common`:
+// preview-host hits http://localhost:3000/common/* (baked into the nexus bundle), so program
+// preview works with no front-end change. The backend container joins its netns. 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 { createServer } from "node:net";
 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";
+import { mediaPortFlags, MEDIA_PORTS, publishPortFlags } from "./ports.mjs";
+import { canSkipImageBuild, hasBin, log, buildCacheFlags } from "./util.mjs";
 
 export const MUSCAT_CONTAINER = "muscat-pk-muscat";
+// Ports published for the backend (it shares this container's netns); a different set recreates it.
+const PORTS_LABEL = "com.rainbow-robotics.muscat-pk.ports";
 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;
+export 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 = () => {
@@ -72,7 +75,7 @@ async function ensureRuntimeImage(total) {
   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],
+    ["build", ...buildCacheFlags(), "-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).");
@@ -106,16 +109,41 @@ async function waitForApi(timeoutMs = 180_000) {
   }
 }
 
+// Is a host TCP port already bound?
+export function isPortInUse(port) {
+  return new Promise((res) => {
+    const srv = createServer();
+    srv.once("error", (err) => res(err.code === "EADDRINUSE"));
+    srv.once("listening", () => srv.close(() => res(false)));
+    srv.listen(port, "0.0.0.0");
+  });
+}
+
+/** A running Muscat container (ours or e.g. muscat-dev) that owns host port 10000, or null. */
+export function localMuscatContainer() {
+  const r = spawnSync("docker", ["ps", "--filter", `publish=${GATEWAY_PORT}`, "--format", "{{.Names}}"], { encoding: "utf8" });
+  return (r.stdout || "").split("\n").map((n) => n.trim()).find(Boolean) ?? null;
+}
+
+const containerLabel = (name, label) =>
+  spawnSync("docker", ["inspect", "-f", `{{index .Config.Labels "${label}"}}`, name], { encoding: "utf8" }).stdout?.trim() ?? "";
+
 /**
  * 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() {
+export async function ensureLocalMuscat({ pluginPorts = [], zenohPort = null } = {}) {
   if (process.env.MUSCAT_PK_NO_LOCAL_MUSCAT === "1") return null;
+  const portsKey = [...pluginPorts, ...(zenohPort ? [`zenoh:${zenohPort}`] : [])].join(",");
   const existing = hasBin("docker") ? localMuscatContainer() : null;
-  if (existing) {
+  if (existing === MUSCAT_CONTAINER && containerLabel(existing, PORTS_LABEL) !== portsKey) {
+    log.step(`recreating local Muscat to publish ${portsKey || "no extra"} port(s)`);
+    spawnSync("docker", ["rm", "-f", MUSCAT_CONTAINER], { stdio: "ignore" });
+  } else if (existing) {
     log.step(`local Muscat '${existing}' already on :${GATEWAY_PORT} — reusing it`);
+    if (existing !== MUSCAT_CONTAINER && portsKey)
+      log.warn(`'${existing}' is not managed by muscat-pk — port(s) ${portsKey} are not published from it.`);
     return existing;
   }
   if (!hasBin("docker")) {
@@ -139,11 +167,16 @@ export async function ensureLocalMuscat() {
 
   let media = true;
   for (const port of MEDIA_PORTS) if (await isPortInUse(port)) media = false;
+  // A busy plugin port would make `docker run` fail with a raw daemon error — skip it and say so.
+  const busy = [];
+  for (const port of pluginPorts) if (await isPortInUse(port)) busy.push(port);
+  if (busy.length) log.warn(`plugin port(s) already in use on the host: ${busy.join(", ")} — not published (the backend still listens inside).`);
+  const published = pluginPorts.filter((port) => !busy.includes(port));
 
   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",
+    "run", "-d", "--name", MUSCAT_CONTAINER, "--label", "com.rainbow-robotics.muscat-pk=true", "--label", `${PORTS_LABEL}=${portsKey}`,
     "-e", "RB_ENABLED_SERVICES=common",
     "-e", "RB_RUNTIME_ENABLE_ZENOH_BRIDGE=0",
     "-v", `${commonDir}:/app/services/common`,
@@ -151,10 +184,15 @@ export async function ensureLocalMuscat() {
     "-p", `127.0.0.1:${API_PORT}:${API_PORT}`,
     "-p", `127.0.0.1:${GATEWAY_PORT}:${GATEWAY_PORT}`,
     ...(media ? mediaPortFlags() : []),
+    ...publishPortFlags(published),
+    // The robot reverse-dials the backend's Zenoh session from the LAN, so not loopback-only.
+    ...(zenohPort ? ["-p", `${zenohPort}:${zenohPort}`] : []),
     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}`);
+  if (published.length) log.step(`plugin backend ports published on 127.0.0.1: ${published.join(", ")}`);
+  if (zenohPort) log.step(`Zenoh dev peer port published on :${zenohPort}`);
   return MUSCAT_CONTAINER;
 }

package/cli/src/ports.mjs

@@ -16,7 +16,7 @@ export function mediaPortFlags() {
 export const RESERVED_BACKEND_PORTS = new Map([
   [502, "Modbus TCP"],
   [4840, "OPC-UA"],
-  [10000, "muscat-pk Socket.IO bridge"],
+  [10000, "Muscat plugin gateway"],
   [2222, "EtherNet/IP Implicit"],
   [30004, "RTDE"],
   [34964, "ProfiNET"],

package/cli/src/python.mjs

@@ -3,7 +3,7 @@
 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 } from "./util.mjs";
+import { canSkipImageBuild, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile, buildCacheFlags } from "./util.mjs";
 
 export const PYTHON_DEV_IMAGE = "muscat-pk-python-dev";
 
@@ -25,7 +25,7 @@ export async function ensureImage(image = PYTHON_DEV_IMAGE, { platform = null }
   const platformFlags = platform ? ["--platform", platform] : [];
   const r = spawnSync(
     "docker",
-    ["build", ...platformFlags, ...imageKeyLabel(key), "-t", image, "-f", dockerfile, dirname(dockerfile)],
+    ["build", ...buildCacheFlags(), ...platformFlags, ...imageKeyLabel(key), "-t", image, "-f", dockerfile, dirname(dockerfile)],
     { stdio: "inherit" },
   );
   if (r.status !== 0) throw new Error("docker build failed.");

package/cli/src/ros2.mjs

@@ -3,7 +3,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { canSkipImageBuild, cppSdkVersion, pluginRootOrNull, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } 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";
@@ -50,7 +50,7 @@ async function buildImage(image, platform, root) {
   const buildArgs = [...(sdkVer ? ["--build-arg", `RB_SDK_VERSION=${sdkVer}`] : []), ...imageKeyLabel(key)];
   const r = spawnSync(
     "docker",
-    ["build", ...platformFlags, ...buildArgs, "-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.");

package/cli/src/util.mjs

@@ -269,12 +269,12 @@ export const log = {
   error: (...m) => console.error(color.red("✖"), ...m.map(s => color.red(s))),
 };
 
-// dev / dev:back / build run the plugin back end, the dev bridge, and cpp/ros2
+// dev / dev:back / build run the plugin back end, the local Muscat runtime, and cpp/ros2
 // compilation in Docker. Show a clear install hint when Docker is missing.
 export function ensureDocker() {
   if (hasBin("docker")) return;
   log.warn("Docker not found.");
-  log.warn("  muscat-pk runs the plugin back end, the dev bridge, and cpp/ros2 builds in Docker.");
+  log.warn("  muscat-pk runs the plugin back end, the local Muscat runtime, and cpp/ros2 builds in Docker.");
   log.warn("  Install Docker, then retry: https://docs.docker.com/get-docker/");
   throw new Error("Docker is required for dev / dev:back / build.");
 }
@@ -323,6 +323,10 @@ export function imageKey(dockerfile, extra = "") {
   return createHash("sha256").update(readFileSync(dockerfile)).update(extra).digest("hex").slice(0, 16);
 }
 
+// MUSCAT_PK_NO_BUILD_CACHE=1 (CI): build images without Docker's layer cache, so an apt/PyPI/GitHub
+// change that breaks a fresh build fails the test too instead of hiding behind a cached layer.
+export const buildCacheFlags = () => (process.env.MUSCAT_PK_NO_BUILD_CACHE === "1" ? ["--no-cache"] : []);
+
 export function imageKeyLabel(key) {
   return ["--label", `${IMAGE_KEY_LABEL}=${key}`];
 }

package/cli/storybook-dist/project.json

@@ -1 +1 @@
-{"generatedAt":1792585817698,"userSince":1750932757926,"hasCustomBabel":false,"hasCustomWebpack":false,"hasStaticDirs":false,"hasStorybookEslint":true,"refCount":0,"testPackages":{"@vitest/browser":"3.2.4","@vitest/coverage-v8":"3.2.4","playwright":"1.59.1","vitest":"3.2.4"},"hasRouterPackage":false,"monorepo":"Turborepo","packageManager":{"type":"yarn","version":"berry","agent":"yarn@berry"},"preview":{"usesGlobals":false},"framework":{"name":"@storybook/react-vite","options":{}},"builder":"@storybook/builder-vite","renderer":"@storybook/react","portableStoriesFileCount":0,"applicationFileCount":0,"storybookVersion":"8.6.18","storybookVersionSpecifier":"^8.6.4","language":"typescript","storybookPackages":{"@chromatic-com/storybook":{"version":"3.2.7"},"@storybook/addon-essentials":{"version":"8.6.18"},"@storybook/addon-links":{"version":"8.6.18"},"@storybook/addon-onboarding":{"version":"8.6.18"},"@storybook/addon-themes":{"version":"8.6.18"},"@storybook/blocks":{"version":"8.6.18"},"@storybook/experimental-addon-test":{"version":"8.6.18"},"@storybook/react":{"version":"8.6.18"},"@storybook/react-vite":{"version":"8.6.18"},"@storybook/test":{"version":"8.6.18"},"@storybook/theming":{"version":"8.6.18"},"eslint-plugin-storybook":{"version":"0.11.6"},"storybook":{"version":"8.6.18"},"storybook-addon-react-docgen":{"version":"1.2.44"}},"addons":{"$SNIP/node_modules/@storybook/addon-links":{"version":null},"$SNIP/node_modules/@storybook/addon-essentials":{"version":null},"$SNIP/node_modules/@chromatic-com/storybook":{"version":null},"$SNIP/node_modules/@storybook/addon-themes":{"version":null},"$SNIP/node_modules/@storybook/experimental-addon-test":{"version":null}}}
+{"generatedAt":1792588886374,"userSince":1750932757926,"hasCustomBabel":false,"hasCustomWebpack":false,"hasStaticDirs":false,"hasStorybookEslint":true,"refCount":0,"testPackages":{"@vitest/browser":"3.2.4","@vitest/coverage-v8":"3.2.4","playwright":"1.59.1","vitest":"3.2.4"},"hasRouterPackage":false,"monorepo":"Turborepo","packageManager":{"type":"yarn","version":"berry","agent":"yarn@berry"},"preview":{"usesGlobals":false},"framework":{"name":"@storybook/react-vite","options":{}},"builder":"@storybook/builder-vite","renderer":"@storybook/react","portableStoriesFileCount":0,"applicationFileCount":0,"storybookVersion":"8.6.18","storybookVersionSpecifier":"^8.6.4","language":"typescript","storybookPackages":{"@chromatic-com/storybook":{"version":"3.2.7"},"@storybook/addon-essentials":{"version":"8.6.18"},"@storybook/addon-links":{"version":"8.6.18"},"@storybook/addon-onboarding":{"version":"8.6.18"},"@storybook/addon-themes":{"version":"8.6.18"},"@storybook/blocks":{"version":"8.6.18"},"@storybook/experimental-addon-test":{"version":"8.6.18"},"@storybook/react":{"version":"8.6.18"},"@storybook/react-vite":{"version":"8.6.18"},"@storybook/test":{"version":"8.6.18"},"@storybook/theming":{"version":"8.6.18"},"eslint-plugin-storybook":{"version":"0.11.6"},"storybook":{"version":"8.6.18"},"storybook-addon-react-docgen":{"version":"1.2.44"}},"addons":{"$SNIP/node_modules/@storybook/addon-links":{"version":null},"$SNIP/node_modules/@storybook/addon-essentials":{"version":null},"$SNIP/node_modules/@chromatic-com/storybook":{"version":null},"$SNIP/node_modules/@storybook/addon-themes":{"version":null},"$SNIP/node_modules/@storybook/experimental-addon-test":{"version":null}}}

package/cli/templates/common/README.md

@@ -307,21 +307,10 @@ export default function App() {
 
 ## Developing directly on the robot PC
 
-If you're running `muscat-pk dev` **on the robot PC itself**, Muscat is likely already
-running its own Socket.IO bridge on port 10000. In that case the CLI detects the port
-conflict and asks:
-
-```
-⚠ port 10000 is already in use — can't start Socket.IO bridge.
-  Proceed without Socket.IO bridge? [y/N]:
-```
-
-Answer **y**. Your plugin backend will connect to the Muscat bridge that's already
-running instead of starting a new one — exactly what you want when developing on the
-robot.
-
-> If you answer **n** (or just press Enter), the CLI exits so you can free the port
-> manually and retry.
+If you're running `muscat-pk dev` **on the robot PC itself**, Muscat already serves the
+plugin gateway on port 10000. The CLI sees that, does not start its own local Muscat, and
+your plugin backend connects to the robot's gateway — exactly what you want when
+developing on the robot.
 
 ---
 
@@ -329,8 +318,7 @@ robot.
 
 `manifest.json` chooses one backend runtime. `muscat-pk dev` runs backend code in
 a Docker container matching the robot environment. Backend code should contain
-plugin logic only; it should not start the Muscat bridge or its own copy of the
-plugin gateway.
+plugin logic only; it should not start its own copy of the plugin gateway.
 
 ### Which backend pattern? (depends on the contribution point)
 
@@ -488,10 +476,10 @@ Known limits:
 - The MQTT broker echoes to the sender: a plugin that `emit`s and `subscribe`s the same topic receives its own push over `mqtt`. Drop `mqtt` from `explicit_events` or use separate topics. (TCP is filtered by `sender_id`.)
 - `on` and `subscribe` may share a name — they live in separate tables.
 
-During `muscat-pk dev` / `dev:back` the local bridge (port `10000`) accepts the
-`router.*` registrations, but **external calls need a running `common`** — it is
-`common` that routes `common/plugin/...` to the gateway. Use a robot (or a local
-`common`) to exercise the external addresses. After restarting the plugin process,
+During `muscat-pk dev` the local Muscat runtime takes the `router.*` registrations
+on its gateway (port `10000`), and its `common` (port `3000`) routes
+`common/plugin/...` to them like on the robot — try
+`curl http://localhost:3000/common/plugin/<plugin-id>/<path>`. After restarting the plugin process,
 external calls may return 504 for up to about a minute (until the gateway notices
 the old socket is gone), then 404 — that is expected.
 
@@ -773,7 +761,7 @@ sudo apt update && sudo apt install rainbow-rb-sdk-dev
 - CMake: `find_package(rb_sdk REQUIRED)` + `target_link_libraries(<target> rb_sdk::rb_sdk)` (C++20). pkg-config: `rb_sdk`.
 - Headers: `<rainbow/rb_sdk/manipulate/rb_manipulate_sdk.hpp>` (`RBManipulateSDK`),
   `<rainbow/rb_sdk/program/plugin_program_context.hpp>` (`rb_plugin::PluginProgramContext`, for `program.panel` commands — the header's top comment has a full `main()` example).
-- The binary is linked **dynamically**; `muscat-pk build` copies the matching `librb_sdk.so` into `dist/<arch>/lib/` (the robot has no SDK installed), so each plugin keeps the SDK version it was built with. Change the version with `MUSCAT_PK_RB_SDK_VERSION=<version> MUSCAT_PK_REBUILD_IMAGE=1 muscat-pk dev`.
+- The binary is linked **dynamically**; `muscat-pk build` copies the matching `librb_sdk.so` into `dist/<arch>/lib/` (the robot has no SDK installed), so each plugin keeps the SDK version it was built with. The version is the one pinned in `CMakeLists.txt` (`find_package(rb_sdk <version> EXACT REQUIRED)`); change it with `muscat-pk sdk update <version>`.
 - UI ↔ backend messaging works from C++ too: `rb_plugin::RBPluginCall` in `<rainbow/rb_sdk/plugin/rb_plugin.hpp>` (see the scaffolded `cpp/main.cpp`).
 
 ### ROS2 (rclpy)

package/cli/templates/cpp/cpp/CMakeLists.txt

@@ -7,7 +7,7 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON)
 # Rainbow Robotics C++ SDK — provided by the apt package rainbow-rb-sdk-dev
 # (pre-installed in the muscat-pk dev container). The version here is the one the
 # dev container installs; change it with `muscat-pk sdk update <version>`.
-find_package(rb_sdk 0.1.6 EXACT REQUIRED)
+find_package(rb_sdk 0.10.2 EXACT REQUIRED)
 
 # The executable name must match runtime.entry in manifest.json.
 add_executable(__PLUGIN_SLUG__ main.cpp)

package/cli/templates/readme-cpp/README.md

@@ -307,21 +307,10 @@ export default function App() {
 
 ## Developing directly on the robot PC
 
-If you're running `muscat-pk dev` **on the robot PC itself**, Muscat is likely already
-running its own Socket.IO bridge on port 10000. In that case the CLI detects the port
-conflict and asks:
-
-```
-⚠ port 10000 is already in use — can't start Socket.IO bridge.
-  Proceed without Socket.IO bridge? [y/N]:
-```
-
-Answer **y**. Your plugin backend will connect to the Muscat bridge that's already
-running instead of starting a new one — exactly what you want when developing on the
-robot.
-
-> If you answer **n** (or just press Enter), the CLI exits so you can free the port
-> manually and retry.
+If you're running `muscat-pk dev` **on the robot PC itself**, Muscat already serves the
+plugin gateway on port 10000. The CLI sees that, does not start its own local Muscat, and
+your plugin backend connects to the robot's gateway — exactly what you want when
+developing on the robot.
 
 ---
 
@@ -329,8 +318,7 @@ robot.
 
 `manifest.json` chooses one backend runtime. `muscat-pk dev` runs backend code in
 a Docker container matching the robot environment. Backend code should contain
-plugin logic only; it should not start the Muscat bridge or its own copy of the
-plugin gateway.
+plugin logic only; it should not start its own copy of the plugin gateway.
 
 ### Which backend pattern? (depends on the contribution point)
 
@@ -367,7 +355,7 @@ don't install anything locally.
 
 ```cmake
 # cpp/CMakeLists.txt — the version is the SDK the dev container installs (muscat-pk sdk update <version>)
-find_package(rb_sdk 0.1.6 EXACT REQUIRED)
+find_package(rb_sdk 0.10.2 EXACT REQUIRED)
 add_executable(__PLUGIN_SLUG__ main.cpp)           # name must equal runtime.entry
 target_link_libraries(__PLUGIN_SLUG__ PRIVATE rb_sdk::rb_sdk)
 ```
@@ -476,8 +464,9 @@ curl -s -X POST http://<robot>/common/plugin/<plugin_id>/hello \
 | Plugin did not answer within 10 s | 504 |
 | `common` ↔ gateway not connected | 503 |
 
-During `muscat-pk dev` the local bridge accepts `router()` registrations, but
-**external calls need a running `common`** (a robot or a local `common`). After
+During `muscat-pk dev` the local Muscat runtime takes `router()` registrations on its
+gateway and its `common` routes external calls to them like on the robot
+(`curl http://localhost:3000/common/plugin/<plugin-id>/<path>`). After
 restarting the plugin, external calls may return 504 for about a minute, then 404.
 
 #### Program command backend (`program.panel`)
@@ -831,10 +820,10 @@ falling back to `README.md` if none matches.
 ## C++ SDK & dependencies
 
 The dev container has the C++ SDK (`rainbow-rb-sdk-dev`) pre-installed — no local
-install needed. Pick a different SDK version with:
+install needed. The SDK version is the one pinned in `CMakeLists.txt` (`find_package(rb_sdk <version> EXACT REQUIRED)`). Pick a different one with:
 
 ```bash
-MUSCAT_PK_RB_SDK_VERSION=<version> MUSCAT_PK_REBUILD_IMAGE=1 muscat-pk dev
+muscat-pk sdk update <version>
 ```
 
 `muscat-pk build` copies the matching `librb_sdk.so` next to your binary

package/cli/templates/ros2-cpp/ros2_ws/src/__PLUGIN_SLUG__/CMakeLists.txt

@@ -10,7 +10,7 @@ find_package(rclcpp REQUIRED)
 # Rainbow Robotics C++ SDK (apt: rainbow-rb-sdk-dev, pre-installed in the dev
 # container). The version here is the one the dev container installs; change it
 # with `muscat-pk sdk update <version>`.
-find_package(rb_sdk 0.1.6 EXACT REQUIRED)
+find_package(rb_sdk 0.10.2 EXACT REQUIRED)
 
 add_executable(__PLUGIN_SLUG___node src/node.cpp)
 ament_target_dependencies(__PLUGIN_SLUG___node rclcpp)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainbow-robotics/muscat-plugin-kit",
-  "version": "1.3.8-dev.0",
+  "version": "1.3.8-dev.2",
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -53,10 +53,9 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@rainbow-robotics/plugin-ui": "1.3.8-dev.0",
-    "@rainbow-robotics/preview-host": "1.3.8-dev.0",
+    "@rainbow-robotics/plugin-ui": "1.3.8-dev.2",
+    "@rainbow-robotics/preview-host": "1.3.8-dev.2",
     "postcss": "^8.5.8",
-    "socket.io": "^4.8.1",
     "typescript": "^5.8.0",
     "vite-plugin-css-injected-by-js": "^3.5.2",
     "zod": "^3.25.0"

package/cli/docker/Dockerfile.bridge

@@ -1,17 +0,0 @@
-# Socket.IO bridge container — the frontend (preview-host) and the backend
-# container rendezvous here during `muscat-pk dev`.
-#   - frontend (host)  → published port localhost:10000
-#   - backend container → shares this container's netns (--network container:),
-#                         so it reaches the bridge at localhost:10000 too
-# Build context is the `cli/` dir so it can copy src/socketBridge.mjs.
-FROM node:20-slim
-LABEL com.rainbow-robotics.muscat-pk="true"
-
-WORKDIR /bridge
-COPY docker/bridge-package.json package.json
-RUN npm install --omit=dev --no-audit --no-fund
-
-COPY src/socketBridge.mjs ./socketBridge.mjs
-
-EXPOSE 10000
-CMD ["node", "socketBridge.mjs"]

package/cli/docker/bridge-package.json

@@ -1,8 +0,0 @@
-{
-  "name": "muscat-pk-bridge",
-  "private": true,
-  "type": "module",
-  "dependencies": {
-    "socket.io": "^4.8.1"
-  }
-}

package/cli/src/bridge.mjs

@@ -1,152 +0,0 @@
-// Socket.IO bridge container lifecycle for `muscat-pk dev`.
-// The bridge runs in Docker and publishes port 10000 to the host:
-//   - frontend (preview-host, on the host) connects to localhost:10000
-//   - the backend container joins via `--network container:<bridge>` and reaches
-//     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, 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;
-
-// 컴파일된 바이너리에는 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.");
-  }
-}
-
-// Is a host TCP port already bound? (Catches another bridge or a stray process.)
-export function isPortInUse(port) {
-  return new Promise((res) => {
-    const srv = createServer();
-    srv.once("error", (err) => res(err.code === "EADDRINUSE"));
-    srv.once("listening", () => srv.close(() => res(false)));
-    srv.listen(port, "0.0.0.0");
-  });
-}
-
-// Wait until the published port accepts a TCP connection (bridge is ready).
-function waitForPort(port, timeoutMs = 15_000) {
-  const start = Date.now();
-  return new Promise((res, rej) => {
-    const tryOnce = () => {
-      const sock = connect(port, "127.0.0.1");
-      sock.once("connect", () => { sock.destroy(); res(); });
-      sock.once("error", () => {
-        sock.destroy();
-        if (Date.now() - start > timeoutMs) rej(new Error("bridge container did not become ready in time"));
-        else setTimeout(tryOnce, 300);
-      });
-    };
-    tryOnce();
-  });
-}
-
-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, 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 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();
-
-  // remove our own stale container first, then check the host port is free
-  spawnSync("docker", ["rm", "-f", BRIDGE_CONTAINER], { stdio: "ignore" });
-  if (await isPortInUse(BRIDGE_PORT)) return false;
-
-  // Publishing a busy port makes `docker run` fail with a raw daemon error —
-  // say which port and keep the bridge up instead.
-  const busy = [];
-  for (const port of pluginPorts) {
-    if (await isPortInUse(port)) busy.push(port);
-  }
-  if (busy.length > 0) {
-    log.warn(
-      `declared plugin port(s) already in use on the host: ${busy.join(", ")} — ` +
-      `not published (the backend still listens inside the container).`,
-    );
-  }
-  const publishable = pluginPorts.filter((port) => !busy.includes(port));
-
-  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
-  // netns can only publish ports when its owner starts — so the plugin's
-  // declared ports have to be published here, not on the backend container.
-  const portFlags = [
-    "-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",
-    ["run", "-d", "--name", BRIDGE_CONTAINER, ...portFlags, BRIDGE_IMAGE],
-    { stdio: "inherit" },
-  );
-  if (up.status !== 0) throw new Error("failed to start bridge container.");
-
-  await waitForPort(BRIDGE_PORT);
-  log.step(`Socket.IO bridge listening on ws://127.0.0.1:${BRIDGE_PORT}`);
-  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 { media };
-}
-
-export function stopBridge() {
-  spawnSync("docker", ["rm", "-f", BRIDGE_CONTAINER], { stdio: "ignore" });
-}

package/cli/src/socketBridge.mjs

@@ -1,133 +0,0 @@
-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 });
-}