@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.5 → 0.1.2-dev.51

package/cli/src/cpp.mjs

@@ -0,0 +1,61 @@
+// Shared C++ Docker helpers (Ubuntu 24.04 + build-essential + cmake).
+// Matches the robot OS so the compiled binary is relocatable to the robot.
+// 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 { hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+
+export const CPP_DEV_IMAGE = "muscat-pk-cpp-dev";
+
+export function assertDockerReady() {
+  if (!hasBin("docker")) {
+    throw new Error("Docker not found. C++ builds need Docker (Ubuntu 24.04 + cmake container).");
+  }
+}
+
+/** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
+export async function ensureImage(image = CPP_DEV_IMAGE, { platform = null } = {}) {
+  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 r = spawnSync(
+    "docker",
+    ["build", ...platformFlags, "-t", image, "-f", dockerfile, dirname(dockerfile)],
+    { stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error("docker build failed.");
+  pruneMuskatImages();
+}
+
+// Docker platform token for each target arch
+export const ARCH_DOCKER_PLATFORM = {
+  amd64: "linux/amd64",
+  arm64: "linux/arm64",
+};
+
+/**
+ * Configure + build cpp/ inside the container, producing cpp/build-{arch}/<entry>
+ * on the host (the workspace is mounted).
+ * - arch null → native (dev mode, uses cpp/build/)
+ * - arch "x86_64" / "aarch64" → cross via --platform (Release builds for ZIP)
+ * buildType "Debug" for dev, "Release" for export builds that ship in the ZIP.
+ */
+export function cmakeBuild(root, { image = CPP_DEV_IMAGE, buildType = "Debug", arch = null } = {}) {
+  const buildDir = arch ? `cpp/build-${arch}` : "cpp/build";
+  const dockerPlatform = arch ? ARCH_DOCKER_PLATFORM[arch] : null;
+  const platformFlags = dockerPlatform ? ["--platform", dockerPlatform] : [];
+  // arch 빌드 시 arch별 이미지 사용 (로컬 이미지와 platform 불일치 방지)
+  const actualImage = arch ? `${CPP_DEV_IMAGE}-${arch}` : image;
+  const script = [
+    `cmake -S cpp -B ${buildDir} -DCMAKE_BUILD_TYPE=${buildType}`,
+    `cmake --build ${buildDir} -j`,
+  ].join(" && ");
+  const label = arch ? `cmake build (${buildType}, ${arch}, in container)…` : `cmake build (${buildType}, in container)…`;
+  log.step(label);
+  const r = spawnSync(
+    "docker",
+    ["run", "--rm", ...platformFlags, "-v", `${root}:/plugin`, "-w", "/plugin", actualImage, "bash", "-lc", script],
+    { cwd: root, stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error(`cmake build failed${arch ? ` (${arch})` : ""}.`);
+}

package/cli/src/dev.mjs

@@ -1,10 +1,55 @@
-// muscat-pk dev — run dev:ui and dev:back together.
+// muscat-pk dev — run the Socket.IO bridge (Docker), dev:ui, and dev:back together.
 import { runDevUi } from "./devUi.mjs";
-import { runDevBack } from "./devBack.mjs";
-import { log } from "./util.mjs";
+import { runDevBack, stopDevBackContainers } from "./devBack.mjs";
+import { startBridge, stopBridge, BRIDGE_CONTAINER, BRIDGE_PORT } from "./bridge.mjs";
+import { assertManifestPorts } from "./manifest.mjs";
+import { formatPortRanges } from "./ports.mjs";
+import { ensureDocker, findPluginRoot, log, prompt, promptRobotConnection } from "./util.mjs";
+import { ensureRemoteZenohEnv, isRemoteRobot } from "./zenohDev.mjs";
 
 export async function runDev(args = []) {
-  log.step("starting dev:ui + dev:back");
+  const root = findPluginRoot();
+  const portRanges = assertManifestPorts(root);
+  if (portRanges.length > 0) {
+    log.step(`plugin backend ports declared: ${formatPortRanges(portRanges)}`);
+    process.env.MUSCAT_PK_PORTS_PRECHECKED = "1";
+  }
+  ensureDocker();
+  const { robotIp, robotToken } = await promptRobotConnection(args);
+  process.env.MUSCAT_ROBOT_HOST  = robotIp;
+  if (robotToken) process.env.MUSCAT_ROBOT_TOKEN = robotToken;
+
+  const remoteRobot = isRemoteRobot(robotIp);
+  // Compute the Zenoh advertise host/port up front — startBridge() needs the
+  // port to publish it on the bridge container so the robot can reach back.
+  await ensureRemoteZenohEnv(robotIp, { log });
+
+  log.step("starting Socket.IO bridge (Docker) + dev:ui + dev:back");
+  const bridgeStarted = await startBridge({
+    zenohPort: remoteRobot ? Number(process.env.MUSCAT_ZENOH_PORT) : null,
+  });
+
+  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 {
+    // 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;
+  }
+
+  process.env.MUSCAT_PK_MANAGED_DEV = "1";
+
+  const cleanup = () => {
+    stopDevBackContainers();
+    if (bridgeStarted) stopBridge();
+  };
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
+  process.once("exit", cleanup);
+
   // dev:back runs to completion / detaches on its own; dev:ui owns the process.
   runDevBack().catch((e) => log.warn(`dev:back: ${e.message}`));
   await runDevUi(args);

package/cli/src/devBack.mjs

@@ -1,71 +1,235 @@
 // muscat-pk dev:back — run the plugin back end during development.
-//   python : create/refresh .venv, then run main.py with watchfiles hot-reload
-//            (uvicorn's reloader). Watches ALL .py files, not just main.py.
-//   ros2   : keep a Jazzy + Python 3.12 container warm, colcon build once with
-//            --symlink-install, run the node, and restart on source changes —
-//            i.e. develop as if inside the container.
+// 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).
+//   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
+//            on source changes (rclcpp rebuilds on change).
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, readFileSync, watch } from "node:fs";
+import { existsSync, watch } from "node:fs";
 import { resolve } from "node:path";
-import { detectPythonCmd, findPluginRoot, log, venvPython } from "./util.mjs";
+import { ensureDocker, ensureIdeVenv, findPluginRoot, log, promptRobotConnection } from "./util.mjs";
+import { ensureRemoteZenohEnv } from "./zenohDev.mjs";
+import { assertManifestPorts, manifestRuntime, readManifest, validateManifest } from "./manifest.mjs";
+import {
+  formatPortRanges,
+  portEnvFlags,
+  startPortContractMonitor,
+} from "./ports.mjs";
+import {
+  PYTHON_DEV_IMAGE,
+  assertDockerReady as pyAssertDockerReady,
+  ensureImage as pyEnsureImage,
+} from "./python.mjs";
 import {
   ROS2_DEV_IMAGE,
   assertDockerReady,
   ensureImage,
   ros2PackageName,
 } from "./ros2.mjs";
+import {
+  CPP_DEV_IMAGE,
+  assertDockerReady as cppAssertDockerReady,
+  ensureImage as cppEnsureImage,
+} from "./cpp.mjs";
+
+const MANAGED_DEV_ENV = "MUSCAT_PK_MANAGED_DEV";
+
+function exitAfterCleanup(code = 0) {
+  if (process.env[MANAGED_DEV_ENV] !== "1") process.exit(code ?? 0);
+}
 
-function manifestRuntime(root) {
-  try {
-    const m = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8"));
-    return m.runtime?.type ?? "python";
-  } catch {
-    return "python";
+export function stopDevBackContainers() {
+  for (const container of [
+    `${PYTHON_DEV_IMAGE}-run`,
+    `${ROS2_DEV_IMAGE}-run`,
+    `${CPP_DEV_IMAGE}-run`,
+  ]) {
+    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
   }
 }
 
+// ── 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.
+// Docker remains the actual execution environment — this never affects it.
+// Runs in the background so it never delays `dev:back` starting, and any
+// failure here (no local Python toolchain, offline, ...) is silent.
+function syncIdeVenv(root) {
+  setImmediate(() => {
+    try {
+      if (ensureIdeVenv(root)) {
+        log.info("IDE venv ready → .venv (point your editor's Python interpreter there for pylint/pyright)");
+      }
+    } catch {
+      /* best-effort only */
+    }
+  });
+}
+
 // ── python ────────────────────────────────────────────────────────────────────
-function runPython(root) {
-  const venv = resolve(root, ".venv");
-  const py = venvPython(venv);
-
-  if (!existsSync(py)) {
-    const { cmd, is312 } = detectPythonCmd();
-    if (!is312) log.warn("python3.12 not found; using fallback (robot targets 3.12).");
-    log.step("creating .venv…");
-    spawnSync(cmd[0], [...cmd.slice(1), "-m", "venv", venv], { cwd: root, stdio: "inherit" });
-  }
+// 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.
+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.
+  syncIdeVenv(root);
+  pyAssertDockerReady();
+  await pyEnsureImage();
 
-  const reqs = resolve(root, "requirements.txt");
-  if (existsSync(reqs)) {
-    log.step("pip install -r requirements.txt…");
-    spawnSync(py, ["-m", "pip", "install", "-q", "-r", reqs], { cwd: root, stdio: "inherit" });
-  }
+  const manifest = readManifest(root);
+  const pluginId = manifest.id ?? "";
+  const container = `${PYTHON_DEV_IMAGE}-run`;
+  const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
+  const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
+  const zenohAdvertiseHost = process.env.MUSCAT_ZENOH_ADVERTISE_HOST ?? "";
+  const zenohPort = process.env.MUSCAT_ZENOH_PORT ?? "";
+  // Share the bridge container's network namespace so localhost:10000 is the
+  // bridge (set by `muscat-pk dev`). Standalone dev:back has no bridge to join.
+  const bridgeContainer = process.env.MUSCAT_PK_BRIDGE_CONTAINER;
+  const netFlags = bridgeContainer ? ["--network", `container:${bridgeContainer}`] : [];
+  const standaloneZenohPortFlags = !bridgeContainer && zenohPort ? ["-p", `${zenohPort}:${zenohPort}`] : [];
+  const hostGatewayFlags = bridgeContainer
+    ? []
+    : ["--add-host", "host.docker.internal:host-gateway"];
+  // Without the bridge's netns, this container is isolated — its own
+  // 127.0.0.1 (rainbow.rb_sdk's gateway default) is itself, not the host, so
+  // it can never see a gateway already running on the host (e.g. the user's
+  // own robot stack occupying port 10000, the reason the bridge start above
+  // was skipped in the first place). host.docker.internal reaches the host.
+  const gatewayFlags = bridgeContainer
+    ? []
+    : ["-e", "RB_PLUGIN_GATEWAY_URL=http://host.docker.internal:10000"];
+  const envFlags = [
+    // docker exec below has no -t (no pseudo-TTY), so Python defaults to
+    // block-buffered stdout — print() output wouldn't show up until the
+    // buffer fills or the process exits. Force unbuffered.
+    "-e", "PYTHONUNBUFFERED=1",
+    ...gatewayFlags,
+    ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
+    ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
+    ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
+    ...(zenohAdvertiseHost ? ["-e", `MUSCAT_ZENOH_ADVERTISE_HOST=${zenohAdvertiseHost}`] : []),
+    ...(zenohPort ? ["-e", `MUSCAT_ZENOH_PORT=${zenohPort}`] : []),
+    ...portEnvFlags(portRanges),
+  ];
+  const docker = (args, opts = {}) =>
+    spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
 
-  // watchfiles = uvicorn's reloader. --filter python watches every *.py in the
-  // project (and ignores .venv/__pycache__/node_modules), so interdependent
-  // modules trigger reloads — not just main.py.
-  log.step("pip install -q watchfiles (dev reloader)…");
-  spawnSync(py, ["-m", "pip", "install", "-q", "watchfiles"], { cwd: root, stdio: "inherit" });
+  // start a warm, long-lived container with the plugin mounted
+  docker(["rm", "-f", container], { stdio: "ignore" });
+  log.step("starting Python dev container…");
+  const up = docker(
+    ["run", "-d", "--name", container, ...netFlags, ...standaloneZenohPortFlags,
+      // host.docker.internal is automatic on Docker Desktop (macOS/Windows);
+      // this makes it resolve on Linux too, for the no-bridge gateway fallback above.
+      ...hostGatewayFlags,
+      "-e", "PIP_ROOT_USER_ACTION=ignore",
+      "-v", `${root}:/plugin`, "-w", "/plugin", PYTHON_DEV_IMAGE, "sleep", "infinity"],
+    { stdio: "inherit" },
+  );
+  if (up.status !== 0) throw new Error("failed to start dev container.");
+  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log });
 
-  log.step("watchfiles → python main.py (reload on any .py change)");
+  log.step("pip install requirements + watchfiles (in container)…");
+  docker(["exec", container, "bash", "-lc",
+    "pip install --break-system-packages --ignore-installed -q watchfiles" +
+    " && { [ -f requirements.txt ] && pip install --break-system-packages --ignore-installed -q -r requirements.txt || true; }"]);
+
+  docker(["exec", container, "bash", "-lc", `cat > /tmp/muscat-pk-python-dev-entry.py <<'PY'
+import os
+import runpy
+
+try:
+    from rainbow.rb_sdk.base import RBBaseSDK
+
+    advertise_host = os.getenv("MUSCAT_ZENOH_ADVERTISE_HOST")
+    zenoh_port = os.getenv("MUSCAT_ZENOH_PORT")
+
+    if advertise_host:
+        RBBaseSDK._detect_local_ip = staticmethod(lambda host: advertise_host)
+
+    if zenoh_port:
+        _orig_connect = RBBaseSDK.connect
+
+        async def _connect_with_dev_port(self, *args, **kwargs):
+            kwargs.setdefault("zenoh_port", int(zenoh_port))
+            return await _orig_connect(self, *args, **kwargs)
+
+        RBBaseSDK.connect = _connect_with_dev_port
+except Exception as exc:
+    print(f"[muscat-pk] SDK dev network patch skipped: {exc}", flush=True)
+
+runpy.run_path("/plugin/py/main.py", run_name="__main__")
+PY`]);
+
+  if (pluginId) log.step(`RB_PLUGIN_ID=${pluginId}`);
+  if (zenohAdvertiseHost && zenohPort) log.step(`Zenoh advertise → ${zenohAdvertiseHost}:${zenohPort}`);
+  log.step("watchfiles → py/main.py (reload on any .py change in py/)");
   const child = spawn(
-    py,
-    ["-m", "watchfiles", "--filter", "python", "--target-type", "command", "python main.py", "."],
-    { cwd: root, stdio: "inherit" },
+    "docker",
+    ["exec", ...envFlags, container, "bash", "-lc",
+      "python3 -m watchfiles --filter python --target-type command 'python3 /tmp/muscat-pk-python-dev-entry.py' py"],
+    { cwd: root, stdio: ["inherit", "inherit", "pipe"] },
   );
-  child.on("exit", (code) => process.exit(code ?? 0));
+  // watchfiles prints a KeyboardInterrupt traceback on SIGTERM — suppress it
+  child.stderr.on("data", (buf) => {
+    const text = buf.toString();
+    if (!text.includes("KeyboardInterrupt") && !text.includes("raise_keyboard_interrupt")) {
+      process.stderr.write(buf);
+    }
+  });
+
+  let cleaned = false;
+  const cleanupResources = () => {
+    if (cleaned) return;
+    cleaned = true;
+    stopPortMonitor();
+    if (!child.killed && child.exitCode === null) child.kill();
+    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
+  };
+  const cleanup = () => {
+    cleanupResources();
+    exitAfterCleanup(0);
+  };
+  child.on("exit", (code) => {
+    cleanupResources();
+    exitAfterCleanup(code ?? 0);
+  });
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
 }
 
 // ── ros2 ───────────────────────────────────────────────────────────────────────
-function runRos2(root) {
+async function runRos2(root, portRanges) {
+  const manifest = readManifest(root);
+  const isRclcpp = manifest.runtime?.rosClient === "rclcpp";
+  // Independent of Docker readiness — must still happen if Docker isn't
+  // installed/running, since that's exactly when local IDE tooling matters most.
+  if (!isRclcpp) syncIdeVenv(root); // rclpy is plain Python — rclcpp is C++, no venv needed
+
   assertDockerReady();
   const pkg = ros2PackageName(root);
   if (!pkg) throw new Error("no ROS2 package found under ros2_ws/src.");
 
-  ensureImage();
+  await ensureImage();
 
+  const pluginId = manifest.id ?? "";
   const container = `${ROS2_DEV_IMAGE}-run`;
+  const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
+  const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
+  const envFlags = [
+    // Same rationale as runPython(): no -t on docker exec below means
+    // rclpy's Python process stdout is block-buffered, not line-buffered.
+    "-e", "PYTHONUNBUFFERED=1",
+    ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
+    ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
+    ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
+    ...portEnvFlags(portRanges),
+  ];
   const docker = (args, opts = {}) =>
     spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
 
@@ -73,10 +237,11 @@ function runRos2(root) {
   docker(["rm", "-f", container], { stdio: "ignore" });
   log.step("starting ROS2 dev container…");
   const up = docker(
-    ["run", "-d", "--name", container, "-v", `${root}:/plugin`, "-w", "/plugin", ROS2_DEV_IMAGE, "sleep", "infinity"],
+    ["run", "-d", "--name", container, "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", ROS2_DEV_IMAGE, "sleep", "infinity"],
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
+  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log });
 
   // one-time deps + symlink build (edits to .py reflect without rebuilding)
   log.step("pip install + colcon build --symlink-install (once)…");
@@ -89,21 +254,22 @@ function runRos2(root) {
     log.step(`ros2 run ${pkg} ${pkg}_node`);
     child = spawn(
       "docker",
-      ["exec", container, "bash", "-lc",
+      ["exec", ...envFlags, container, "bash", "-lc",
         `cd ros2_ws && source install/setup.bash && ros2 run ${pkg} ${pkg}_node`],
       { cwd: root, stdio: "inherit" },
     );
   };
   startNode();
 
-  // restart node on source change; rebuild only when package metadata changes
+  // restart node on source change. rclpy reflects .py edits live (symlink-install);
+  // rclcpp (C++) and package-metadata changes require a colcon rebuild.
   let timer = null;
   const onChange = (_event, filename) => {
     clearTimeout(timer);
     timer = setTimeout(() => {
       const structural = filename && /(setup\.py|package\.xml|CMakeLists\.txt)$/.test(String(filename));
-      if (structural) {
-        log.info("package metadata changed — colcon rebuild…");
+      if (structural || isRclcpp) {
+        log.info(structural ? "package metadata changed — colcon rebuild…" : "source changed — colcon rebuild…");
         docker(["exec", container, "bash", "-lc", "cd ros2_ws && colcon build --symlink-install"]);
       } else {
         log.info("source changed — restarting node…");
@@ -117,17 +283,113 @@ function runRos2(root) {
   }
 
   const cleanup = () => {
+    stopPortMonitor();
     if (child) child.kill();
     spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
-    process.exit(0);
+    exitAfterCleanup(0);
   };
   process.on("SIGINT", cleanup);
   process.on("SIGTERM", cleanup);
 }
 
-export async function runDevBack() {
+// ── cpp ──────────────────────────────────────────────────────────────────────
+async function runCpp(root, portRanges) {
+  cppAssertDockerReady();
+  const manifest = readManifest(root);
+  const entry = manifest.runtime?.entry;
+  if (!entry) throw new Error("runtime.entry (the built executable name) is required for cpp.");
+
+  await cppEnsureImage();
+
+  const pluginId = manifest.id ?? "";
+  const container = `${CPP_DEV_IMAGE}-run`;
+  const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
+  const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
+  const envFlags = [
+    ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
+    ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
+    ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
+    ...portEnvFlags(portRanges),
+  ];
+  const docker = (args, opts = {}) =>
+    spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
+
+  // start a warm, long-lived container with the plugin mounted
+  docker(["rm", "-f", container], { stdio: "ignore" });
+  log.step("starting C++ dev container…");
+  const up = docker(
+    ["run", "-d", "--name", container, "-v", `${root}:/plugin`, "-w", "/plugin", CPP_DEV_IMAGE, "sleep", "infinity"],
+    { stdio: "inherit" },
+  );
+  if (up.status !== 0) throw new Error("failed to start dev container.");
+  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log });
+
+  const build = () => {
+    log.step("cmake build…");
+    return docker(["exec", container, "bash", "-lc",
+      "cmake -S cpp -B cpp/build -DCMAKE_BUILD_TYPE=Debug && cmake --build cpp/build -j"]);
+  };
+  build();
+
+  let child = null;
+  const startBin = () => {
+    if (child) child.kill();
+    log.step(`run cpp/build/${entry}`);
+    child = spawn(
+      "docker",
+      ["exec", ...envFlags, container, "bash", "-lc", `./cpp/build/${entry}`],
+      { cwd: root, stdio: "inherit" },
+    );
+  };
+  startBin();
+
+  // rebuild + restart on C++ source changes; ignore the build/ output dir.
+  let timer = null;
+  const onChange = (_event, filename) => {
+    if (filename && String(filename).startsWith("build")) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      log.info("source changed — rebuilding…");
+      const r = build();
+      if (r.status === 0) startBin();
+      else log.warn("build failed — keeping previous binary");
+    }, 300);
+  };
+  const cppDir = resolve(root, "cpp");
+  if (existsSync(cppDir)) watch(cppDir, { recursive: true }, onChange);
+
+  const cleanup = () => {
+    stopPortMonitor();
+    if (child) child.kill();
+    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
+    exitAfterCleanup(0);
+  };
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+}
+
+function warnManifest(root) {
+  const manifest = readManifest(root);
+  if (!manifest || Object.keys(manifest).length === 0) return;
+  const errors = validateManifest(manifest);
+  for (const e of errors) log.warn(`manifest.json: ${e}`);
+}
+
+export async function runDevBack(args = []) {
   const root = findPluginRoot();
+  warnManifest(root);
+  const portRanges = assertManifestPorts(root);
+  if (portRanges.length > 0 && process.env.MUSCAT_PK_PORTS_PRECHECKED !== "1")
+    log.step(`plugin backend ports declared: ${formatPortRanges(portRanges)}`);
+  ensureDocker();
+  const { robotIp, robotToken } = await promptRobotConnection(args);
+  if (robotIp)    process.env.MUSCAT_ROBOT_HOST  = robotIp;
+  if (robotToken) process.env.MUSCAT_ROBOT_TOKEN = robotToken;
+  // Standalone `dev:back` against a remote robot needs the Zenoh reverse-path
+  // advertise host/port too (idempotent — `muscat-pk dev` already set these).
+  await ensureRemoteZenohEnv(robotIp, { log });
   const type = manifestRuntime(root);
-  if (type === "ros2") return runRos2(root);
-  return runPython(root);
+  if (type === "ros2") return await runRos2(root, portRanges);
+  if (type === "cpp") return await runCpp(root, portRanges);
+  return await runPython(root, portRanges);
 }