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

package/cli/src/python.mjs

@@ -0,0 +1,112 @@
+// Shared Python Docker helpers (Ubuntu 24.04 + Python 3.12 — matches the robot).
+// Used by dev:back (hot-reload) and build (lock + wheel vendor).
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { canSkipImageBuild, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile, buildCacheFlags } from "./util.mjs";
+
+export const PYTHON_DEV_IMAGE = "muscat-pk-python-dev";
+
+export function assertDockerReady() {
+  if (!hasBin("docker")) {
+    throw new Error("Docker not found. The Python backend runs in a container (Ubuntu 24.04 + Python 3.12).");
+  }
+}
+
+/** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
+export async function ensureImage(image = PYTHON_DEV_IMAGE, { platform = null } = {}) {
+  const dockerfile = await resolveDockerfile("Dockerfile.python");
+  const key = imageKey(dockerfile);
+  if (canSkipImageBuild(image, key)) {
+    return;
+  }
+  log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
+  const platformFlags = platform ? ["--platform", platform] : [];
+  const r = spawnSync(
+    "docker",
+    ["build", ...buildCacheFlags(), ...platformFlags, ...imageKeyLabel(key), "-t", image, "-f", dockerfile, dirname(dockerfile)],
+    { stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error("docker build failed.");
+  pruneMuskatImages();
+}
+
+// pip --platform does NOT auto-expand manylinux tags (unlike sys_tags()) — exact match only.
+// Specifying all common glibc milestones ensures packages built for any Ubuntu era are found.
+const PIP_PLATFORM = {
+  amd64: [
+    "manylinux_2_5_x86_64",
+    "manylinux_2_17_x86_64",
+    "manylinux_2_27_x86_64",
+    "manylinux_2_28_x86_64",
+    "manylinux_2_34_x86_64",
+    "manylinux_2_35_x86_64",
+    "manylinux_2_39_x86_64",
+    "linux_x86_64",
+  ],
+  arm64: [
+    "manylinux_2_17_aarch64",
+    "manylinux_2_27_aarch64",
+    "manylinux_2_28_aarch64",
+    "manylinux_2_34_aarch64",
+    "manylinux_2_35_aarch64",
+    "manylinux_2_39_aarch64",
+    "linux_aarch64",
+  ],
+};
+
+export async function lockAndVendor(pluginRoot, archs = ["amd64", "arm64"]) {
+  // ponytail: pip --platform used intentionally (not QEMU) — downloads wheels without running target arch code.
+  const reqTxt = resolve(pluginRoot, "requirements.txt");
+  if (!existsSync(reqTxt)) {
+    log.warn("requirements.txt not found — lock/vendor skipped");
+    return;
+  }
+
+  await ensureImage();
+
+  // A pinned pre-release (e.g. rainbow-rb-sdk==0.1.4.dev1) pins its sibling rainbow-rb-*
+  // pre-releases too; uv rejects those transitive pre-releases unless allowed.
+  const reqText = readFileSync(resolve(pluginRoot, "requirements.txt"), "utf8");
+  const prerelease = /==\s*\S*\d(a|b|rc|\.dev)\d*\s*$/im.test(reqText) ? " --prerelease=allow" : "";
+  log.step(`generating lock (uv pip compile${prerelease})…`);
+  const lockResult = spawnSync(
+    "docker",
+    [
+      "run", "--rm",
+      ...dockerUserFlags(),
+      "-v", `${pluginRoot}:/plugin`,
+      PYTHON_DEV_IMAGE,
+      "bash", "-c",
+      "set -e && cd /plugin && mkdir -p dist && uv pip compile requirements.txt --python-version 3.12 -o dist/requirements.lock" + prerelease,
+    ],
+    { stdio: "inherit" },
+  );
+  if (lockResult.status !== 0) throw new Error("lock generation failed (uv pip compile)");
+  log.ok("dist/requirements.lock ready");
+
+  for (const arch of archs) {
+    const pipPlatforms = PIP_PLATFORM[arch];
+    if (!pipPlatforms) throw new Error(`unknown arch '${arch}'`);
+    log.step(`vendoring wheels for ${arch}…`);
+    const r = spawnSync(
+      "docker",
+      [
+        "run", "--rm",
+        ...dockerUserFlags(),
+        "-e", "PIP_ROOT_USER_ACTION=ignore",
+        "-v", `${pluginRoot}:/plugin`,
+        "-w", "/plugin",
+        PYTHON_DEV_IMAGE,
+        "bash", "-c",
+        "mkdir -p dist/wheels && pip3 download -r dist/requirements.lock --no-deps --only-binary=:all: -d dist/wheels -q " +
+          "--python-version 312 --implementation cp --abi cp312 " +
+          pipPlatforms.map((p) => `--platform ${p}`).join(" "),
+      ],
+      { stdio: "inherit" },
+    );
+    // A ZIP missing wheels fails to import on the robot — stop instead.
+    if (r.status !== 0) throw new Error(`wheel download failed for ${arch} (see pip output above)`);
+    log.ok(`dist/wheels/ ready (${arch})`);
+  }
+}

package/cli/src/ros2.mjs

@@ -3,14 +3,11 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { hasBin, kitRoot, log } from "./util.mjs";
+import { canSkipImageBuild, cppSdkVersion, pluginRootOrNull, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile, buildCacheFlags } from "./util.mjs";
+import { syncCppIde } from "./cppIde.mjs";
 
 export const ROS2_DEV_IMAGE = "muscat-pk-ros2-dev";
 
-// Dockerfile lives inside the kit — plugin authors never see or edit it.
-// It has no COPY/ADD, so the build context is irrelevant (its own dir is used).
-const DOCKERFILE = resolve(kitRoot, "cli/docker/Dockerfile.dev");
-
 /** First package directory under ros2_ws/src (the colcon package name). */
 export function ros2PackageName(root) {
   const srcDir = resolve(root, "ros2_ws/src");
@@ -25,20 +22,38 @@ export function assertDockerReady() {
   if (!hasBin("docker")) {
     throw new Error("Docker not found. ROS2 needs Docker (Jazzy + Python 3.12 container).");
   }
-  if (!existsSync(DOCKERFILE)) {
-    throw new Error(`kit Dockerfile missing at ${DOCKERFILE} (reinstall muscat-plugin-kit).`);
-  }
 }
 
+export const ARCH_DOCKER_PLATFORM = {
+  amd64: "linux/amd64",
+  arm64: "linux/arm64",
+};
+
 /** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
-export function ensureImage(image = ROS2_DEV_IMAGE) {
-  log.step(`docker build -t ${image} (first run is slow, then cached)…`);
+export async function ensureImage(image = ROS2_DEV_IMAGE, { platform = null, root = pluginRootOrNull() } = {}) {
+  await buildImage(image, platform, root);
+  // Dev images feed the editor's SDK headers: the native one (dev) or the host-arch one (build).
+  const hostArch = process.arch === "arm64" ? "arm64" : "amd64";
+  if (root && (image === ROS2_DEV_IMAGE || image === `${ROS2_DEV_IMAGE}-${hostArch}`)) syncCppIde(root, image);
+}
+
+async function buildImage(image, platform, root) {
+  const dockerfile = await resolveDockerfile("Dockerfile.dev");
+  const sdkVer = cppSdkVersion(root);
+  const key = imageKey(dockerfile, sdkVer ?? "");
+  if (canSkipImageBuild(image, key)) {
+    return;
+  }
+  log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
+  const platformFlags = platform ? ["--platform", platform] : [];
+  const buildArgs = [...(sdkVer ? ["--build-arg", `RB_SDK_VERSION=${sdkVer}`] : []), ...imageKeyLabel(key)];
   const r = spawnSync(
     "docker",
-    ["build", "-t", image, "-f", DOCKERFILE, dirname(DOCKERFILE)],
+    ["build", ...buildCacheFlags(), ...platformFlags, ...buildArgs, "-t", image, "-f", dockerfile, dirname(dockerfile)],
     { stdio: "inherit" },
   );
   if (r.status !== 0) throw new Error("docker build failed.");
+  pruneMuskatImages();
 }
 
 /**
@@ -46,20 +61,49 @@ export function ensureImage(image = ROS2_DEV_IMAGE) {
  * (the workspace is mounted). symlink=true for dev (fast, edit-in-place);
  * symlink=false for export builds that ship in the ZIP (real copies, relocatable).
  */
-export function colconBuild(root, { image = ROS2_DEV_IMAGE, symlink = false } = {}) {
+/**
+ * arch=null → dev mode, builds to ros2_ws/install/ (native)
+ * arch="amd64"|"arm64" → export mode, builds to ros2_ws/install-{arch}/ using arch-specific image
+ */
+/**
+ * symlink=true (dev): ros2_ws/install/ — local dev workspace, not for ZIP
+ * symlink=false, arch=null (rclpy export): dist/ros2_ws/install/
+ * symlink=false, arch="amd64"|"arm64" (rclcpp export): dist/ros2_ws/install-{arch}/
+ */
+export function colconBuild(root, { image = ROS2_DEV_IMAGE, symlink = false, arch = null } = {}) {
+  // paths are relative to ros2_ws/ inside the container
+  let installBase;
+  if (symlink) {
+    installBase = "install";
+  } else if (arch) {
+    installBase = `../dist/ros2_ws/install-${arch}`;
+  } else {
+    installBase = "../dist/ros2_ws/install";
+  }
   const flag = symlink ? "--symlink-install" : "";
+  const buildBase = symlink ? "build" : arch ? `build-${arch}` : "build-dist";
   const script = [
-    // --ignore-installed: don't try to uninstall debian-managed packages
-    // (e.g. psutil), which fails with "RECORD file not found".
     "pip install -r requirements.txt --break-system-packages --ignore-installed -q || true",
     "cd ros2_ws",
-    `colcon build ${flag}`.trim(),
+    // Export builds use their own build cache: sharing build/ with dev's --symlink-install
+    // (or another arch) breaks the next colcon build.
+    // rclcpp export: ship librb_sdk.so in <pkg>/lib/ (robot has no SDK) when the node links it.
+    `colcon build ${flag} --build-base ${buildBase} --install-base ${installBase}`.replace("  ", " ") +
+      (arch ? ` --cmake-args '-DCMAKE_INSTALL_RPATH=$ORIGIN/..'` : ""),
+    ...(arch ? [`for d in ${installBase}/*/lib; do if readelf -d $(find "$d" -mindepth 2 -type f -executable) 2>/dev/null | grep -q librb_sdk; then cp -a $(dpkg -L rainbow-rb-sdk | grep -E '/librb_sdk[.]so[.][0-9]') "$d"/; fi; done`] : []),
   ].join(" && ");
-  log.step(`colcon build${symlink ? " --symlink-install" : ""} (in container)…`);
+  const label = arch
+    ? `colcon build (${arch}) → dist/ros2_ws/install-${arch}/…`
+    : `colcon build${symlink ? " --symlink-install" : ""} (in container)…`;
+  log.step(label);
+  const actualImage = arch ? `${ROS2_DEV_IMAGE}-${arch}` : image;
+  const dockerPlatform = arch ? ARCH_DOCKER_PLATFORM[arch] : null;
+  const platformFlags = dockerPlatform ? ["--platform", dockerPlatform] : [];
   const r = spawnSync(
     "docker",
-    ["run", "--rm", "-v", `${root}:/plugin`, "-w", "/plugin", image, "bash", "-lc", script],
+    // python/cpp 와 같이 호스트 uid 로 돌린다 — root 소유 산출물이 남으면 사용자가 지우지 못한다.
+    ["run", "--rm", ...platformFlags, ...dockerUserFlags(), "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", actualImage, "bash", "-lc", script],
     { cwd: root, stdio: "inherit" },
   );
-  if (r.status !== 0) throw new Error("colcon build failed.");
+  if (r.status !== 0) throw new Error(`colcon build failed${arch ? ` (${arch})` : ""}.`);
 }

package/cli/src/sdk.mjs

@@ -1,27 +1,78 @@
-// muscat-pk sdk <list|update [version]> — manage the python rainbow-rb-sdk.
-import { spawnSync } from "node:child_process";
+// muscat-pk sdk <list|update [version]> — manage the rainbow-rb-sdk version.
+//
+// C++ backends (cpp, ros2 rclcpp) pin it in CMakeLists.txt (find_package(rb_sdk <ver> EXACT)); the
+// versions come from the rb-sdk apt repository and the dev image installs the pinned one.
+//
+// Python backends:
+// Pins requirements.txt — the real install happens in the `dev`/`dev:back`
+// Docker container. If a local .venv exists (see devBack.mjs's syncIdeVenv,
+// for editor/linter support), also update it in place so pylint/pyright see
+// the new version immediately; this is best-effort only.
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { findPluginRoot, log } from "./util.mjs";
+import { cppSdkFiles, cppSdkPin, ensureIdeVenv, findPluginRoot, log, setCppSdkPin, venvPython } from "./util.mjs";
+import { readManifest } from "./manifest.mjs";
 
 const PKG = "rainbow-rb-sdk";
 
-async function fetchVersions() {
+async function fetchPypi() {
   try {
     const res = await fetch(`https://pypi.org/pypi/${PKG}/json`);
+    return res.ok ? await res.json() : null;
+  } catch {
+    return null;
+  }
+}
+
+async function fetchVersions() {
+  const data = await fetchPypi();
+  return Object.keys(data?.releases || {}).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+}
+
+// Stable releases of rainbow-rb-sdk-dev, newest first. Pre-releases (0.1.4~dev1) are skipped: CMake
+// versions are numeric only.
+const APT_PACKAGES = "https://rainbowrobotics.github.io/rb-sdk/dists/stable/main/binary-amd64/Packages";
+
+export async function fetchAptVersions() {
+  try {
+    const res = await fetch(APT_PACKAGES);
     if (!res.ok) return [];
-    const data = await res.json();
-    return Object.keys(data.releases || {}).sort((a, b) =>
-      b.localeCompare(a, undefined, { numeric: true }),
-    );
+    const text = await res.text();
+    const versions = [...text.matchAll(/^Package: rainbow-rb-sdk-dev\n(?:.*\n)*?Version: (\S+)/gm)].map((m) => m[1]);
+    return [...new Set(versions)].filter((v) => /^[0-9]+(\.[0-9]+)*$/.test(v)).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
   } catch {
     return [];
   }
 }
 
+async function runCppSdk(sub, version, root) {
+  if (sub === "list") {
+    const versions = await fetchAptVersions();
+    if (!versions.length) return log.warn("could not fetch versions (offline?).");
+    log.info(`rainbow-rb-sdk-dev versions:\n  ${versions.slice(0, 12).join("\n  ")}`);
+    return;
+  }
+  if (sub === "update") {
+    if (!cppSdkFiles(root).length) throw new Error("no find_package(rb_sdk ...) in cpp/CMakeLists.txt or ros2_ws/src/*/CMakeLists.txt");
+    if (!version) {
+      version = (await fetchAptVersions())[0];
+      if (!version) throw new Error("could not fetch the latest version (offline?). Pass one: muscat-pk sdk update <version>");
+    }
+    if (!/^[0-9]+(\.[0-9]+)*$/.test(version)) throw new Error(`"${version}" is not a CMake version (digits and dots only)`);
+    const before = cppSdkPin(root);
+    const files = setCppSdkPin(root, version);
+    log.ok(`rb_sdk ${before ?? "(unpinned)"} → ${version} in ${files.map((f) => f.slice(root.length + 1)).join(", ")}`);
+    log.info("The dev image is rebuilt with this SDK on the next `muscat-pk build` / `dev:back`.");
+    return;
+  }
+  log.info("Usage: muscat-pk sdk <list|update [version]>");
+}
+
 export async function runSdk(args = []) {
   const sub = args[0];
   const root = findPluginRoot();
+  const runtime = readManifest(root)?.runtime ?? {};
+  if (runtime.type === "cpp" || (runtime.type === "ros2" && runtime.rosClient === "rclcpp")) return runCppSdk(sub, args[1], root);
   const reqs = resolve(root, "requirements.txt");
 
   if (sub === "list") {
@@ -37,28 +88,27 @@ export async function runSdk(args = []) {
   if (sub === "update") {
     let version = args[1];
     if (!version) {
-      const versions = await fetchVersions();
-      version = versions[0] || "latest";
+      // info.version = latest stable
+      version = (await fetchPypi())?.info?.version;
+      if (!version) throw new Error("could not fetch the latest version (offline?). Pass one: muscat-pk sdk update <version>");
     }
+    // rainbow-rb-* pin each other exactly — bump them together.
     let content = existsSync(reqs) ? readFileSync(reqs, "utf8") : "";
-    const line = `${PKG}==${version}`;
-    if (new RegExp(`^${PKG}==`, "m").test(content)) {
-      content = content.replace(new RegExp(`^${PKG}==.*$`, "m"), line);
-    } else {
-      content = (content ? content.trimEnd() + "\n" : "") + line + "\n";
+    const pinned = /^(rainbow-rb-[\w-]+)\s*==.*$/gim;
+    const bumped = [...content.matchAll(pinned)].map((m) => m[1]);
+    content = content.replace(pinned, (_m, name) => `${name}==${version}`);
+    if (!bumped.some((n) => n.toLowerCase() === PKG)) {
+      content = (content ? content.trimEnd() + "\n" : "") + `${PKG}==${version}\n`;
+      bumped.push(PKG);
     }
     writeFileSync(reqs, content);
-    log.ok(`requirements.txt → ${line}`);
+    log.ok(`requirements.txt → ${bumped.map((n) => `${n}==${version}`).join(", ")}`);
 
-    const py = resolve(root, ".venv", "bin", "python");
-    if (existsSync(py)) {
-      log.step("pip install -r requirements.txt…");
-      spawnSync(py, ["-m", "pip", "install", "-q", "-r", reqs], {
-        cwd: root,
-        stdio: "inherit",
-      });
+    if (existsSync(venvPython(resolve(root, ".venv")))) {
+      log.step("refreshing .venv (for your editor)…");
+      if (!ensureIdeVenv(root)) log.warn(".venv refresh failed — the Docker dev container is unaffected.");
     } else {
-      log.warn(".venv not found; run `muscat-pk dev:back` to install.");
+      log.info("Installed automatically on the next `muscat-pk dev` / `dev:back` (Docker container).");
     }
     return;
   }

package/cli/src/sim.mjs

@@ -0,0 +1,177 @@
+// `dev --sim <model>`: robot simulators next to the local Muscat, for developing without a robot.
+// Cobot: coreSW (rainbowroboticsofficial/cobot-sim) per component, joined to common's Zenoh.
+// RB-Y1: rby1-sim + Xvfb built locally (it needs a GLFW window; there is no headless mode yet).
+import { spawnSync } from "node:child_process";
+import { canSkipImageBuild, log } from "./util.mjs";
+import { MUSCAT_NETWORK } from "./muscatLocal.mjs";
+
+const COBOT_IMAGE = "rainbowroboticsofficial/cobot-sim";
+const RBY1_IMAGE = "rainbowroboticsofficial/rby1-sim";
+const RBY1_LOCAL = "muscat-pk-rby1-sim";
+const RBY1_CONTAINER = "muscat-pk-sim-rby1";
+const SIM_LABEL = "com.rainbow-robotics.muscat-pk.sim";
+
+// ponytail: model table in code; move to S3 version.json when sims are versioned with Muscat (amr: no sim yet)
+// sim name → coreSW RB_MODEL per component, and the Muscat robot model it registers as.
+const COBOT_MODELS = {
+  "500920": { robotModel: "C500920", models: ["500920"] },
+  RBY2: { robotModel: "RBY2", models: ["C500880", "C501880", "C502880"] },
+};
+const RBY1_TYPES = ["a", "m", "ub"];
+
+// rby1-sim renders MuJoCo with software GL every frame; one GL thread and a tiny screen cut it from
+// ~3.5 cores to ~1. The cap keeps a busy Mac usable; the image already skips RT-loop timeouts.
+const RBY1_DOCKERFILE = `ARG BASE=0.10.6-m_v1.3
+FROM ${RBY1_IMAGE}:\${BASE}
+RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends xvfb && rm -rf /var/lib/apt/lists/*
+ENV LP_NUM_THREADS=0 DISPLAY=:99
+CMD ["sh", "-c", "Xvfb :99 -screen 0 320x240x16 -nolisten tcp & sleep 1; exec ./app_main"]
+`;
+
+export const SIM_NAMES = [...Object.keys(COBOT_MODELS), ...RBY1_TYPES.map((t) => `rby1-${t}`)];
+
+/** `muscat-pk sim list`: "<name>\t<what runs>" per line, for scripts and the VS Code Dev picker. */
+export function runSimList() {
+  for (const [name, { robotModel, models }] of Object.entries(COBOT_MODELS))
+    console.log(`${name}\tcobot · ${robotModel}${models.length > 1 ? ` (${models.join(", ")})` : ""}`);
+  for (const t of RBY1_TYPES) console.log(`rby1-${t}\tRB-Y1 ${t.toUpperCase()}`);
+}
+
+/** "500920" | "RBY2" | "rby1-m" | "rby1-m_v1.2" → { services, env, ... } or null. */
+export function parseSim(name) {
+  if (COBOT_MODELS[name]) return { name, kind: "cobot", services: ["log", "manipulate"], env: {}, ...COBOT_MODELS[name] };
+  const m = /^rby1-(a|m|ub)(?:_(v[\d.]+))?$/.exec(name ?? "");
+  if (m) return { name, kind: "rby1", services: ["log", "rby1"], env: { RBY1_HOST: RBY1_CONTAINER }, robotModel: m[1], type: m[1], version: m[2] };
+  return null;
+}
+
+/** Only an explicit --sim <name> runs a simulator. */
+export function resolveSim(simArg, manifest) {
+  if (simArg === undefined) return null;
+  const sim = typeof simArg === "string" ? parseSim(simArg) : null;
+  if (!sim) throw new Error(`--sim takes one of: ${SIM_NAMES.join(", ")} (rby1 also takes rby1-m_v1.2)`);
+  const models = Array.isArray(manifest.targetModels) ? manifest.targetModels : null;
+  if (models && !models.includes(simArg)) log.warn(`--sim ${simArg} is not in manifest targetModels (${models.join(", ")})`);
+  return sim;
+}
+
+async function hubTags(repo) {
+  const res = await fetch(`https://hub.docker.com/v2/repositories/${repo}/tags?page_size=100&ordering=last_updated`, {
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (!res.ok) throw new Error(`Docker Hub ${repo}: HTTP ${res.status}`);
+  return (await res.json()).results.map((t) => t.name);
+}
+
+// "0.10.6-m_v1.3" → [0, 10, 6, 1, 3]
+const semver = (v) => v.split(/[._v-]/).map(Number).filter((n) => !Number.isNaN(n));
+const newer = (a, b) => {
+  const [x, y] = [semver(a), semver(b)];
+  for (let i = 0; i < Math.max(x.length, y.length); i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) - (y[i] ?? 0);
+  return 0;
+};
+
+// Latest published tag; offline falls back to whatever was pulled before.
+async function latestTag(repo, pattern) {
+  try {
+    const tags = (await hubTags(repo)).filter((t) => pattern.test(t));
+    if (tags.length) return tags.sort(newer).at(-1);
+  } catch (e) {
+    log.warn(`${e.message} — using a local image`);
+  }
+  const tags = localTags(repo).filter((t) => pattern.test(t));
+  if (!tags.length) throw new Error(`no ${repo} image matching ${pattern} (offline and nothing pulled yet)`);
+  return tags.sort(newer).at(-1);
+}
+
+function localTags(repo) {
+  const out = spawnSync("docker", ["images", repo, "--format", "{{.Tag}}"], { encoding: "utf8" }).stdout ?? "";
+  return out.split("\n").map((t) => t.trim()).filter(Boolean);
+}
+
+// A new sim release replaces the previous one (100–700MB each); other model types' tags stay.
+function removeOldTags(repo, pattern, keep) {
+  for (const tag of localTags(repo).filter((t) => t !== keep && pattern.test(t)))
+    spawnSync("docker", ["rmi", `${repo}:${tag}`], { stdio: "ignore" });
+}
+
+function pull(image) {
+  if (spawnSync("docker", ["image", "inspect", image], { stdio: "ignore" }).status === 0) return;
+  log.step(`docker pull ${image}…`);
+  if (spawnSync("docker", ["pull", image], { stdio: "inherit" }).status !== 0) throw new Error(`docker pull ${image} failed`);
+}
+
+function run(name, args) {
+  spawnSync("docker", ["rm", "-f", name], { stdio: "ignore" });
+  const r = spawnSync("docker", [
+    // --ipc host like the robot: the cobot coreSWs share one shm segment (RB_MESSAGE_SHM, a slot per model).
+    "run", "-d", "--name", name, "--network", MUSCAT_NETWORK, "--ipc", "host",
+    "--label", "com.rainbow-robotics.muscat-pk=true", "--label", `${SIM_LABEL}=true`,
+    ...args,
+  ], { stdio: ["ignore", "ignore", "inherit"] });
+  if (r.status !== 0) throw new Error(`failed to start ${name}`);
+}
+
+// The Muscat UI (robot info, components, connection state) follows the registered robot model.
+async function registerRobot(robotModel) {
+  const res = await fetch("http://127.0.0.1:3000/common/upsert-robot-info", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ robotModel }),
+  });
+  if (!res.ok) throw new Error(`upsert-robot-info ${robotModel}: HTTP ${res.status}`);
+  log.step(`robot model ${robotModel} registered in the local Muscat`);
+}
+
+/** Start the simulator containers and register the robot model; returns the container names. */
+export async function startSim(sim) {
+  const names = await startContainers(sim);
+  await registerRobot(sim.robotModel);
+  return names;
+}
+
+// Needs the local Muscat on MUSCAT_NETWORK.
+async function startContainers(sim) {
+  stopSims();
+  if (sim.kind === "cobot") {
+    const pattern = /^\d+\.\d+\.\d+$/;
+    const tag = await latestTag(COBOT_IMAGE, pattern);
+    const image = `${COBOT_IMAGE}:${tag}`;
+    pull(image);
+    removeOldTags(COBOT_IMAGE, pattern, tag);
+    const names = sim.models.map((model) => `muscat-pk-sim-${model}`);
+    sim.models.forEach((model, i) => run(names[i], [
+      "--cap-add", "SYS_NICE", "--ulimit", "rtprio=99",
+      "-e", `RB_MODEL=${model}`,
+      "-e", "RB_ZENOH_CONNECT=tcp/muscat-pk-muscat:7447",
+      image,
+    ]));
+    log.step(`cobot sim ${sim.name} (${image}) → ${sim.models.join(", ")}`);
+    return names;
+  }
+
+  const pattern = sim.version ? new RegExp(`^\\d+\\.\\d+\\.\\d+-${sim.type}_${sim.version.replace(/\./g, "\\.")}$`) : new RegExp(`^\\d+\\.\\d+\\.\\d+-${sim.type}_v[\\d.]+$`);
+  const base = await latestTag(RBY1_IMAGE, pattern);
+  const image = `${RBY1_LOCAL}:${base}`;
+  if (!canSkipImageBuild(image)) {
+    log.step(`building ${image} (rby1-sim + Xvfb, first run pulls ~150MB)…`);
+    const r = spawnSync("docker", ["build", "-t", image, "--build-arg", `BASE=${base}`, "--label", "com.rainbow-robotics.muscat-pk=true", "-"], {
+      input: RBY1_DOCKERFILE,
+      stdio: ["pipe", "inherit", "inherit"],
+    });
+    if (r.status !== 0) throw new Error(`docker build ${image} failed`);
+  }
+  removeOldTags(RBY1_LOCAL, pattern, base);
+  removeOldTags(RBY1_IMAGE, pattern, base);
+  run(RBY1_CONTAINER, ["--cpus", process.env.MUSCAT_PK_RBY1_CPUS || "1.5", image]);
+  log.step(`rby1 sim ${base} → ${RBY1_CONTAINER}:50051`);
+  return [RBY1_CONTAINER];
+}
+
+export function stopSims() {
+  const ids = (spawnSync("docker", ["ps", "-aq", "--filter", `label=${SIM_LABEL}=true`], { encoding: "utf8" }).stdout ?? "").split("\n").filter(Boolean);
+  if (!ids.length) return;
+  // The cobot coreSWs share these under --ipc host; drop them so the next run starts from a fresh segment.
+  spawnSync("docker", ["exec", ids[0], "sh", "-c", "rm -f /dev/shm/RB_COBOT_SHM /dev/shm/RB_MESSAGE_SHM"], { stdio: "ignore" });
+  spawnSync("docker", ["rm", "-f", ...ids], { stdio: "ignore" });
+}