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

package/cli/src/completion.mjs

@@ -0,0 +1,168 @@
+// muscat-pk completion — print a shell completion script for bash / zsh / fish.
+//
+//   muscat-pk completion zsh >> ~/.zshrc      (or source it from there)
+//   muscat-pk completion bash >> ~/.bashrc
+//   muscat-pk completion fish > ~/.config/fish/completions/muscat-pk.fish
+//   muscat-pk completion powershell >> $PROFILE
+//
+// Keep COMMANDS in sync with the switch in bin/muscat-pk.mjs.
+import { log } from "./util.mjs";
+
+const COMMANDS = [
+  ["new", "Scaffold a new plugin project"],
+  ["type", "Switch backend type"],
+  ["build", "Build + zip the plugin"],
+  ["dev", "Bridge + dev:ui + dev:back"],
+  ["dev:ui", "Preview the plugin in a mini-Muscat"],
+  ["dev:back", "Run the plugin back end"],
+  ["storybook", "Browse the bundled rb-components Storybook"],
+  ["mcp", "Start an MCP server (stdio)"],
+  ["update", "Update muscat-pk and plugin-ui"],
+  ["uninstall", "Remove the installed muscat-pk CLI"],
+  ["sdk", "Manage the rainbow-rb-sdk version (python: requirements.txt, C++: CMakeLists.txt)"],
+  ["sim", "List the robot simulators for dev --sim"],
+  ["version", "Print the installed muscat-pk version"],
+  ["completion", "Print a shell completion script"],
+  ["help", "Show help"],
+];
+
+const SUBCOMMANDS = {
+  type: ["change"],
+  sdk: ["list", "update"],
+  sim: ["list"],
+  completion: ["bash", "zsh", "fish", "powershell"],
+};
+
+const names = COMMANDS.map(([name]) => name);
+
+function bashScript() {
+  const subCases = Object.entries(SUBCOMMANDS)
+    .map(([cmd, subs]) => `    ${cmd}) COMPREPLY=( $(compgen -W "${subs.join(" ")}" -- "$cur") ); return ;;`)
+    .join("\n");
+
+  return `_muscat_pk() {
+  local cur prev
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  case "$prev" in
+${subCases}
+  esac
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${names.join(" ")}" -- "$cur") )
+    # bash treats ":" as a word break, so "dev:ui" would come back duplicated
+    if type __ltrim_colon_completions >/dev/null 2>&1; then
+      __ltrim_colon_completions "$cur"
+    fi
+  fi
+}
+complete -F _muscat_pk muscat-pk`;
+}
+
+function zshScript() {
+  // _describe splits on ":", so a command name containing one (dev:ui) must escape it
+  const cmds = COMMANDS.map(
+    ([name, desc]) => `    '${name.replace(/:/g, "\\:")}:${desc}'`,
+  ).join("\n");
+  const subCases = Object.entries(SUBCOMMANDS)
+    .map(([cmd, subs]) => `      ${cmd}) _values 'subcommand' ${subs.join(" ")} ;;`)
+    .join("\n");
+
+  // Sourced from ~/.zshrc, compdef only exists once compinit has run — a bare
+  // zsh (no oh-my-zsh, no compinit) would error on every shell start otherwise.
+  return `#compdef muscat-pk
+if ! whence compdef > /dev/null; then
+  autoload -Uz compinit && compinit
+fi
+_muscat_pk() {
+  local -a cmds
+  cmds=(
+${cmds}
+  )
+  if (( CURRENT == 2 )); then
+    _describe 'command' cmds
+  else
+    case \${words[2]} in
+${subCases}
+    esac
+  fi
+}
+if whence compdef > /dev/null; then
+  compdef _muscat_pk muscat-pk
+fi`;
+}
+
+function fishScript() {
+  const top = COMMANDS.map(
+    ([name, desc]) =>
+      `complete -c muscat-pk -f -n __fish_use_subcommand -a ${name} -d ${JSON.stringify(desc)}`,
+  );
+  const subs = Object.entries(SUBCOMMANDS).flatMap(([cmd, list]) =>
+    list.map(
+      (sub) =>
+        `complete -c muscat-pk -f -n "__fish_seen_subcommand_from ${cmd}" -a ${sub}`,
+    ),
+  );
+  return [...top, ...subs].join("\n");
+}
+
+function powershellScript() {
+  const subMap = Object.entries(SUBCOMMANDS)
+    .map(([cmd, subs]) => `    '${cmd}' = @(${subs.map((s) => `'${s}'`).join(", ")})`)
+    .join("\n");
+
+  return `Register-ArgumentCompleter -Native -CommandName muscat-pk -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $commands = @(${names.map((n) => `'${n}'`).join(", ")})
+  $subcommands = @{
+${subMap}
+  }
+  $elements = @($commandAst.CommandElements | ForEach-Object { $_.ToString() })
+  # element 0 is "muscat-pk"; a trailing partial word is also in the list
+  $typedCommand = if ($elements.Count -gt 1) { $elements[1] } else { '' }
+  $candidates =
+    if ($elements.Count -gt 2 -or ($elements.Count -eq 2 -and $wordToComplete -eq '')) {
+      if ($subcommands.ContainsKey($typedCommand)) { $subcommands[$typedCommand] } else { @() }
+    } else { $commands }
+  $candidates |
+    Where-Object { $_ -like "$wordToComplete*" } |
+    ForEach-Object {
+      [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+    }
+}`;
+}
+
+const GENERATORS = {
+  bash: bashScript,
+  zsh: zshScript,
+  fish: fishScript,
+  powershell: powershellScript,
+};
+
+const HINTS = {
+  bash: "muscat-pk completion bash >> ~/.bashrc  →  then: source ~/.bashrc",
+  zsh: "muscat-pk completion zsh >> ~/.zshrc  →  then: source ~/.zshrc",
+  fish: "muscat-pk completion fish > ~/.config/fish/completions/muscat-pk.fish",
+  powershell: "muscat-pk completion powershell >> $PROFILE  →  then: . $PROFILE",
+};
+
+/** Guess the user's shell from $SHELL; PowerShell on Windows, else bash. */
+function detectShell() {
+  const shell = (process.env.SHELL || "").split(/[/\\]/).pop();
+  if (shell in GENERATORS) return shell;
+  return process.platform === "win32" ? "powershell" : "bash";
+}
+
+export async function runCompletion(args = []) {
+  const shell = args[0] ?? detectShell();
+  const generate = GENERATORS[shell];
+
+  if (!generate) {
+    throw new Error(
+      `Unsupported shell "${shell}" (supported: ${Object.keys(GENERATORS).join(", ")})`,
+    );
+  }
+
+  // Only the script goes to stdout, so `>> ~/.zshrc` stays valid.
+  console.log(generate());
+  if (process.stdout.isTTY) log.info(`\nInstall: ${HINTS[shell]}`);
+}

package/cli/src/cpp.mjs

@@ -0,0 +1,78 @@
+// 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 { 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";
+
+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, root = pluginRootOrNull() } = {}) {
+  await buildImage(image, platform, root);
+  // Dev images feed the editor's SDK headers: the native one (dev) or the host-arch one (build).
+  const hostArch = process.arch === "arm64" ? "arm64" : "amd64";
+  if (root && (image === CPP_DEV_IMAGE || image === `${CPP_DEV_IMAGE}-${hostArch}`)) syncCppIde(root, image);
+}
+
+async function buildImage(image, platform, root) {
+  const dockerfile = await resolveDockerfile("Dockerfile.cpp");
+  const sdkVer = cppSdkVersion(root);
+  const key = imageKey(dockerfile, sdkVer ?? "");
+  if (canSkipImageBuild(image, key)) {
+    return;
+  }
+  log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
+  const platformFlags = platform ? ["--platform", platform] : [];
+  const buildArgs = [...(sdkVer ? ["--build-arg", `RB_SDK_VERSION=${sdkVer}`] : []), ...imageKeyLabel(key)];
+  const r = spawnSync(
+    "docker",
+    ["build", ...buildCacheFlags(), ...platformFlags, ...buildArgs, "-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;
+  // 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}` + (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);
+  const r = spawnSync(
+    "docker",
+    ["run", "--rm", ...dockerUserFlags(), ...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/cppIde.mjs

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

package/cli/src/dev.mjs

@@ -1,11 +1,200 @@
-// muscat-pk dev — run dev:ui and dev:back together.
+// muscat-pk dev — run the local Muscat runtime (gateway, MediaMTX, common), robot simulators (--sim),
+// dev:ui, and dev:back together.
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { connect as netConnect } from "node:net";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { runDevUi } from "./devUi.mjs";
-import { runDevBack } from "./devBack.mjs";
-import { log } from "./util.mjs";
+import { prebuildBackend } from "./devBack.mjs";
+import { claimDevSession, stopDevBackContainers } from "./devSession.mjs";
+import { ensureLocalMuscat, GATEWAY_PORT, isPortInUse, MUSCAT_CONTAINER, robotHasMuscat } from "./muscatLocal.mjs";
+import { resolveSim, startSim, stopSims } from "./sim.mjs";
+import { assertManifestPorts, assertManifestVariables, readManifest } from "./manifest.mjs";
+import { devPluginId } from "./devId.mjs";
+import {
+  ensureDocker,
+  ensureIdeVenv,
+  findPluginRoot,
+  log,
+  parseArgs,
+  prompt,
+  promptRobotConnection,
+  venvPython,
+} from "./util.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" || process.platform === "win32" || isWsl();
+
+function waitForHostAgent(port, { timeoutMs = 30_000 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve, reject) => {
+    const probe = () => {
+      const sock = netConnect(port, "127.0.0.1");
+      sock.once("connect", () => { sock.destroy(); resolve(true); });
+      sock.once("error", () => {
+        sock.destroy();
+        if (Date.now() >= deadline) {
+          reject(new Error(`host SDK agent did not open port ${port} in time`));
+          return;
+        }
+        setTimeout(probe, 300);
+      });
+    };
+    probe();
+  });
+}
+
+const DEFAULT_PROXY_PORT = 47100;
+
+// Start the host-side Zenoh byte-proxy (host_agent.py) for a remote robot —
+// see host_agent.py for why a Docker Desktop container can't join the
+// robot's Zenoh mesh itself. Sets MUSCAT_PROXY_ENDPOINT for dev:back.
+// Returns the child process, or null if not applicable / disabled.
+async function maybeStartHostAgent(root, { robotIp, robotToken }) {
+  if (process.env.MUSCAT_PROXY_ENDPOINT) {
+    log.step(`Zenoh via host byte-proxy → ${process.env.MUSCAT_PROXY_ENDPOINT}`);
+    return null;
+  }
+  if (process.env.MUSCAT_HOST_AGENT_DISABLE === "1") return null;
+  if (!canAutoStartHostAgent() || !isRemoteRobot(robotIp)) return null;
+
+  const agentPath = process.env.MUSCAT_HOST_AGENT_SCRIPT || HOST_AGENT_PATH;
+  if (!existsSync(agentPath)) return null;
+
+  if (!ensureIdeVenv(root)) {
+    log.warn("host Zenoh byte-proxy skipped: could not prepare .venv");
+    return null;
+  }
+
+  // advertiseHost/zenohPort = the host_agent's OWN robot-facing Zenoh session
+  // (host LAN IP + port the robot reverse-dials into). The container never
+  // sees or needs these — it only talks to the proxyPort below.
+  const zenoh = await ensureRemoteZenohEnv(robotIp, { log });
+  const advertiseHost = zenoh?.advertiseHost || process.env.MUSCAT_ZENOH_ADVERTISE_HOST;
+  const zenohPort = zenoh?.zenohPort || Number(process.env.MUSCAT_ZENOH_PORT);
+  if (!advertiseHost || !zenohPort) {
+    log.warn("host Zenoh byte-proxy skipped: could not determine host LAN IP / port");
+    return null;
+  }
+  const proxyPort = Number(process.env.MUSCAT_PROXY_PORT) || DEFAULT_PROXY_PORT;
+
+  log.step("starting host Zenoh byte-proxy (Docker Desktop query-routing workaround)...");
+  const py = venvPython(resolve(root, ".venv"));
+  const child = spawn(py, [agentPath], {
+    cwd: root,
+    stdio: ["ignore", "inherit", "inherit"],
+    env: {
+      ...process.env,
+      MUSCAT_ROBOT_HOST: robotIp,
+      MUSCAT_ROBOT_TOKEN: robotToken,
+      MUSCAT_ZENOH_ADVERTISE_HOST: advertiseHost,
+      MUSCAT_ZENOH_PORT: String(zenohPort),
+      MUSCAT_PROXY_PORT: String(proxyPort),
+    },
+  });
+
+  try {
+    await waitForHostAgent(proxyPort);
+  } catch (e) {
+    child.kill();
+    throw e;
+  }
+
+  // advertiseHost (not host.docker.internal): a Docker Desktop container run
+  // 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}`;
+  process.env.MUSCAT_PROXY_ENDPOINT = proxyEndpoint;
+  process.env.MUSCAT_PROXY_PORT = String(proxyPort);
+  log.step(`Zenoh via host byte-proxy → ${proxyEndpoint}`);
+  return child;
+}
 
 export async function runDev(args = []) {
-  log.step("starting dev:ui + dev:back");
-  // dev:back runs to completion / detaches on its own; dev:ui owns the process.
-  runDevBack().catch((e) => log.warn(`dev:back: ${e.message}`));
+  const root = findPluginRoot();
+  await claimDevSession(root, "dev");
+  assertManifestVariables(root);
+  const portRanges = assertManifestPorts(root);
+  ensureDocker();
+  const { robotIp, robotToken } = await promptRobotConnection(args);
+  process.env.MUSCAT_ROBOT_HOST  = robotIp;
+  // Even when empty: the dev:back child (stdin ignored) must not prompt for the token again.
+  process.env.MUSCAT_ROBOT_TOKEN = robotToken;
+
+  const remoteRobot = isRemoteRobot(robotIp);
+  // Before dev:back is spawned: it inherits the id through the environment.
+  devPluginId(readManifest(root).id, { robotIp, args });
+
+  // Registered before anything starts: stopped while the local Muscat or a sim is still coming up,
+  // they would otherwise keep running. muscat-pk-muscat and the sims are ours — a muscat-dev the
+  // user started is another container and stays up.
+  let hostAgent = null;
+  let backend = null;
+  let cleaned = false;
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    if (hostAgent && hostAgent.exitCode === null) hostAgent.kill();
+    if (backend && backend.exitCode === null) backend.kill();
+    stopDevBackContainers();
+    stopSims();
+    spawnSync("docker", ["rm", "-f", MUSCAT_CONTAINER], { stdio: "ignore" });
+  };
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) // SIGHUP: terminal closed (VS Code re-running Dev disposes it)
+    process.once(signal, () => {
+      cleanup();
+      // Once dev:ui is up its own handler stops the UI and exits.
+      if (!process.listenerCount(signal)) process.exit(130);
+    });
+  process.once("exit", cleanup);
+
+  await prebuildBackend(root);
+  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 — the local Muscat then publishes the zenoh port for it.
+  if (!proxyEndpoint) await ensureRemoteZenohEnv(robotIp, { log });
+
+  // No robot: a simulator stands in for it (--sim, else the manifest's target).
+  const sim = remoteRobot ? null : resolveSim(parseArgs(args).sim, readManifest(root));
+
+  // A robot running Muscat is the gateway (:10000) and common for both the UI and the backend.
+  // Otherwise the local Muscat runtime is; the backend joins its netns, so the plugin's declared
+  // ports are published from it too.
+  const muscat = (await robotHasMuscat(robotIp)) ? null : await ensureLocalMuscat({
+    pluginPorts: portRanges,
+    zenohPort: remoteRobot && !proxyEndpoint ? Number(process.env.MUSCAT_ZENOH_PORT) || null : null,
+    services: sim?.services,
+    env: sim?.env,
+  }).catch((e) => { log.warn(`local Muscat: ${e.message}`); return null; });
+  if (sim && muscat !== MUSCAT_CONTAINER) {
+    log.warn(`--sim needs muscat-pk's own Muscat${muscat ? ` ('${muscat}' is running — stop it to use the simulator)` : ""}; no simulator.`);
+  } else if (sim) {
+    // dev:ui then serves the real Muscat UI against the local Muscat, like with muscat-dev.
+    if (await startSim(sim).catch((e) => log.warn(`simulator: ${e.message}`))) process.env.MUSCAT_PK_SIM = sim.name;
+  }
+  if (muscat) {
+    process.env.MUSCAT_PK_MUSCAT_CONTAINER = muscat;
+  } else if (remoteRobot || (await isPortInUse(GATEWAY_PORT))) {
+    // e.g. developing on the robot PC: its Muscat already serves the gateway; the backend reaches it via the host.
+  } else {
+    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;
+  }
+
+  // dev:back in its own process: its docker build / pip install / cmake build are synchronous and would
+  // freeze dev:ui's server on this event loop until they finish (or Ctrl+C killed them).
+  // A Bun binary re-runs itself with just the command; under Node argv[1] is the script.
+  backend = spawn(process.execPath, [...(typeof Bun === "undefined" ? [process.argv[1]] : []), "dev:back"], {
+    stdio: ["ignore", "inherit", "inherit"],
+  });
+  backend.on("exit", (code) => code && log.warn(`dev:back exited (${code})`));
+
+  process.env.MUSCAT_PK_MANAGED_DEV = "1";
+
   await runDevUi(args);
 }