@rainbow-robotics/muscat-plugin-kit 1.10.2-dev.6 → 1.10.2-dev.8

package/cli/bin/muscat-pk.mjs

@@ -121,6 +121,9 @@ async function main() {
       case "storybook":
         return await runStorybook(args);
       case "mcp": {
+        // Relay by default so `muscat-pk update` reaches a running session; --serve is the server.
+        if (args[0] !== "--serve" && args[0] !== "--install" && args[0] !== "install")
+          return (await import("../src/mcpProxy.mjs")).runMcpProxy();
         const { runMcp, installMcp } = await import("../src/mcp.mjs");
         if (args[0] === "--install" || args[0] === "install")
           return installMcp(args[1]);

package/cli/src/build.mjs

@@ -13,9 +13,10 @@ import { chmodSync, cpSync, copyFileSync, existsSync, mkdirSync, readdirSync, re
 import { createRequire } from "node:module";
 import { basename, dirname, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
-import { execSync, spawnSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import { ensureDocker, findPluginRoot, hasBin, humanSize, log, parseArgs, prompt } from "./util.mjs";
 import { assertManifest, manifestRuntime } from "./manifest.mjs";
+import { writeZip } from "./zip.mjs";
 
 // Find a usable JS runtime for running vite as a subprocess.
 // In binary (Bun) mode, try `bun` first (it can run vite directly), then node.
@@ -343,14 +344,8 @@ function packZip(pluginRoot) {
   const entries = ["dist"];
 
   log.step(`packing ${entries.join(", ")} → ${zipName}`);
-  try {
-    execSync(`zip -r -q "${zipPath}" ${entries.map((e) => `"${e}"`).join(" ")}`, {
-      cwd: pluginRoot,
-      stdio: "inherit",
-    });
-  } catch {
-    throw new Error("`zip` not found. Install zip or pack manually.");
-  }
+  // In-process, not the `zip` CLI: Windows has none, and it keeps the robot's executable bits (zip.mjs).
+  writeZip(zipPath, entries, pluginRoot);
 
   const zipBytes = statSync(zipPath).size;
   log.ok(`${zipName}   ${humanSize(zipBytes)}`);

package/cli/src/dev.mjs

@@ -5,7 +5,7 @@ import { connect as netConnect } from "node:net";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runDevUi } from "./devUi.mjs";
-import { stopDevBackContainers } from "./devBack.mjs";
+import { claimDevSession, stopDevBackContainers } from "./devSession.mjs";
 import { ensureLocalMuscat, GATEWAY_PORT, isPortInUse, robotHasMuscat } from "./muscatLocal.mjs";
 import { assertManifestPorts, assertManifestVariables, readManifest } from "./manifest.mjs";
 import { devPluginId } from "./devId.mjs";
@@ -111,6 +111,7 @@ async function maybeStartHostAgent(root, { robotIp, robotToken }) {
 
 export async function runDev(args = []) {
   const root = findPluginRoot();
+  await claimDevSession(root, "dev");
   assertManifestVariables(root);
   const portRanges = assertManifestPorts(root);
   ensureDocker();

package/cli/src/devBack.mjs

@@ -13,6 +13,7 @@ import { isIP } from "node:net";
 import { resolve } from "node:path";
 import { dockerUserFlags, ensureDevDir, ensureDocker, ensureIdeVenv, findPluginRoot, log, promptRobotConnection, realtimeFlags } from "./util.mjs";
 import { ensureRemoteZenohEnv, getFreePort, isRemoteRobot, usesHostNetwork } from "./zenohDev.mjs";
+import { claimDevSession, DEV_CONTAINER, stopDevBackContainers } from "./devSession.mjs";
 import { GATEWAY_PORT, localMuscatContainer, robotHasMuscat } from "./muscatLocal.mjs";
 import { devPluginId } from "./devId.mjs";
 import { PLUGIN_ID_RE, assertManifestPorts, assertManifestVariables, manifestRuntime, readManifest, rosNamespace, validateManifest } from "./manifest.mjs";
@@ -44,15 +45,7 @@ function exitAfterCleanup(code = 0) {
   if (process.env[MANAGED_DEV_ENV] !== "1") process.exit(code ?? 0);
 }
 
-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" });
-  }
-}
+export { stopDevBackContainers };
 
 // 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
@@ -149,7 +142,7 @@ async function runPython(root, portRanges, robotGateway) {
 
   const manifest = readManifest(root);
   const pluginId = process.env.MUSCAT_PK_DEV_PLUGIN_ID || (manifest.id ?? "");
-  const container = `${PYTHON_DEV_IMAGE}-run`;
+  const container = DEV_CONTAINER;
   const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
   const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
   const zenohAdvertiseHost = process.env.MUSCAT_ZENOH_ADVERTISE_HOST ?? "";
@@ -529,7 +522,7 @@ async function runRos2(root, portRanges, robotGateway) {
   await ensureImage();
 
   const pluginId = process.env.MUSCAT_PK_DEV_PLUGIN_ID || (manifest.id ?? "");
-  const container = `${ROS2_DEV_IMAGE}-run`;
+  const container = DEV_CONTAINER;
   const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
   const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
   const net = backendNetwork(portRanges, robotGateway);
@@ -624,7 +617,7 @@ async function runCpp(root, portRanges, robotGateway) {
   await cppEnsureImage();
 
   const pluginId = process.env.MUSCAT_PK_DEV_PLUGIN_ID || (manifest.id ?? "");
-  const container = `${CPP_DEV_IMAGE}-run`;
+  const container = DEV_CONTAINER;
   const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
   const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
   const net = backendNetwork(portRanges, robotGateway);
@@ -699,6 +692,7 @@ function warnManifest(root) {
 
 export async function runDevBack(args = []) {
   const root = findPluginRoot();
+  await claimDevSession(root, "dev:back");
   assertManifestVariables(root);
   warnManifest(root);
   const portRanges = assertManifestPorts(root);

package/cli/src/devSession.mjs

@@ -0,0 +1,67 @@
+// One Muscat plugin dev environment per PC: the backend container, the local Muscat runtime (and
+// the plugin ports it publishes) and the host_agent relay port are shared. A new dev / dev:ui /
+// dev:back offers to stop the running one and take over.
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { log, prompt } from "./util.mjs";
+
+export const DEV_CONTAINER = "muscat-pk-dev-run";
+// Per-runtime names from older kits.
+const OLD_CONTAINERS = ["muscat-pk-python-dev-run", "muscat-pk-ros2-dev-run", "muscat-pk-cpp-dev-run"];
+const LOCK = resolve(homedir(), ".muscat-pk", "dev-session.json");
+
+export function stopDevBackContainers() {
+  for (const c of [DEV_CONTAINER, ...OLD_CONTAINERS]) spawnSync("docker", ["rm", "-f", c], { stdio: "ignore" });
+}
+
+const alive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+};
+
+function runningSession() {
+  try {
+    const s = JSON.parse(readFileSync(LOCK, "utf8"));
+    return s.pid !== process.pid && alive(s.pid) ? s : null;
+  } catch {
+    return null;
+  }
+}
+
+async function stopSession(pid) {
+  // SIGINT runs its own cleanup (UI, host_agent, containers). Windows has no signals — kill the tree.
+  if (process.platform === "win32") spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
+  else process.kill(pid, "SIGINT");
+  for (let i = 0; i < 60 && alive(pid); i++) await new Promise((r) => setTimeout(r, 500));
+  if (alive(pid)) process.kill(pid, "SIGKILL");
+}
+
+export async function claimDevSession(root, command) {
+  if (process.env.MUSCAT_PK_MANAGED_DEV === "1") return; // `dev` claimed it for its dev:ui / dev:back
+  const other = runningSession();
+  if (other?.pid === process.ppid) return; // `dev`'s own dev:back child
+  if (other) {
+    log.warn(`A Muscat plugin dev environment is already running: muscat-pk ${other.command} in ${other.root} (pid ${other.pid}).`);
+    log.warn("Only one can run per PC — they share the backend container, the local Muscat and its ports.");
+    const answer = (await prompt("  Stop it and start this one? [y/N]: ")).toLowerCase();
+    if (answer !== "y" && answer !== "yes") throw new Error("another plugin dev environment is running — stop it first.");
+    await stopSession(other.pid);
+    stopDevBackContainers(); // whatever it could not clean up
+    log.ok("stopped the other plugin dev environment");
+  }
+  mkdirSync(dirname(LOCK), { recursive: true });
+  writeFileSync(LOCK, JSON.stringify({ pid: process.pid, root, command }));
+  process.on("exit", () => {
+    try {
+      if (JSON.parse(readFileSync(LOCK, "utf8")).pid === process.pid) rmSync(LOCK, { force: true });
+    } catch {
+      /* already gone */
+    }
+  });
+}

package/cli/src/devUi.mjs

@@ -11,6 +11,7 @@ import { devPluginId } from "./devId.mjs";
 import { readManifest } from "./manifest.mjs";
 import { ensureLocalMuscat, GATEWAY_PORT, localFullMuscat, robotHasMuscat } from "./muscatLocal.mjs";
 import { isRemoteRobot } from "./zenohDev.mjs";
+import { claimDevSession } from "./devSession.mjs";
 
 
 const DEV_PLUGIN_PORT = 4181;
@@ -82,6 +83,14 @@ function syncAssets(pluginRoot, outDir) {
 }
 
 
+// "(dev)" after every name the plugin shows, so a dev session is never mistaken for an installed copy.
+const devLabel = (v) =>
+  typeof v === "string"
+    ? `${v} (dev)`
+    : v && typeof v === "object"
+      ? Object.fromEntries(Object.entries(v).map(([lang, s]) => [lang, `${s} (dev)`]))
+      : v;
+
 // preview-host takes the plugin id from this copy, so the UI talks under the session's dev id.
 function stageDevAssets(pluginRoot, pluginId) {
   const outDir = ensureDevDir(pluginRoot);
@@ -89,6 +98,11 @@ function stageDevAssets(pluginRoot, pluginId) {
   if (existsSync(manifestSrc)) {
     const manifest = JSON.parse(readFileSync(manifestSrc, "utf8"));
     if (pluginId) manifest.id = pluginId;
+    manifest.name = devLabel(manifest.name);
+    for (const c of manifest.contributes ?? []) {
+      c.label = devLabel(c.label);
+      if (c.commandInfo?.name) c.commandInfo.name = devLabel(c.commandInfo.name);
+    }
     writeFileSync(resolve(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
   }
   syncAssets(pluginRoot, outDir);
@@ -163,6 +177,7 @@ function waitForPluginDevPort(readyFile, proc, timeoutMs = 120_000) {
 export async function runDevUi(args = []) {
   const parsed = parseArgs(args);
   const requestedPort = Number(parsed.port ?? "4180");
+  await claimDevSession(findPluginRoot(), "dev:ui");
   const robotIp = parsed["robot-ip"] ?? process.env.MUSCAT_ROBOT_HOST ?? await prompt("  Robot IP (skip if no robot): ");
 
   await checkKitUpdate();

package/cli/src/mcp.mjs

@@ -31,6 +31,7 @@ import {
   readdirSync,
   readFileSync,
   renameSync,
+  rmSync,
   statSync,
   writeFileSync,
 } from "node:fs";
@@ -470,7 +471,12 @@ function introspectInDocker(probe) {
     /* not a python plugin — latest */
   }
   // ponytail: "latest" cache is never refreshed; delete ~/.cache/... rb-sdk-py/latest to update.
-  const cache = join(UI_INDEX_CACHE_DIR, "rb-sdk-py", ver || "latest");
+  const cacheRoot = join(UI_INDEX_CACHE_DIR, "rb-sdk-py");
+  const cache = join(cacheRoot, ver || "latest");
+  // Only the SDK version in use is kept (~165MB each) — other versions don't pile up.
+  for (const old of existsSync(cacheRoot) ? readdirSync(cacheRoot) : []) {
+    if (join(cacheRoot, old) !== cache) rmSync(join(cacheRoot, old), { recursive: true, force: true });
+  }
   mkdirSync(cache, { recursive: true });
   const pkg = ver ? `rainbow-rb-sdk==${ver}` : "rainbow-rb-sdk";
   const script =

package/cli/src/mcpProxy.mjs

@@ -0,0 +1,110 @@
+// `muscat-pk mcp` — AI clients keep one stdio MCP server per session, so a `muscat-pk update`
+// never reached a running one. This relays stdio to the real server (`mcp --serve`) and, when the
+// installed kit changes, swaps that child for the new one: it replays the client's initialize and
+// sends tools/list_changed, so the connection stays up and the next calls use the new tools.
+import { spawn } from "node:child_process";
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { kitRoot, resolveLocalCliBin } from "./util.mjs";
+
+const isBinaryMode = typeof Bun !== "undefined";
+const REINIT_ID = "__muscat_pk_reinit__";
+const POLL_MS = 3000;
+
+// Re-resolved on every (re)start: an update may install, bump or remove the project's local kit.
+function serverCommand() {
+  const local = resolveLocalCliBin(process.cwd());
+  if (local) {
+    return { cmd: isBinaryMode ? "node" : process.execPath, args: [local, "mcp", "--serve"], watch: resolve(local, "../../../package.json") };
+  }
+  if (isBinaryMode) return { cmd: process.execPath, args: ["mcp", "--serve"], watch: process.execPath };
+  return { cmd: process.execPath, args: [process.argv[1], "mcp", "--serve"], watch: resolve(kitRoot, "package.json") };
+}
+
+const stamp = (file) => {
+  try {
+    return `${file}:${statSync(file).mtimeMs}`;
+  } catch {
+    return file;
+  }
+};
+
+export function runMcpProxy() {
+  let child = null;
+  let initRequest = null;
+  const pending = new Set(); // client request ids the current child hasn't answered
+  const toClient = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
+
+  const failPending = () => {
+    for (const id of pending) {
+      toClient({ jsonrpc: "2.0", id, error: { code: -32603, message: "muscat-pk was updated during this call — retry it." } });
+    }
+    pending.clear();
+  };
+
+  const start = () => {
+    const { cmd, args } = serverCommand();
+    const c = spawn(cmd, args, { stdio: ["pipe", "pipe", "inherit"] });
+    createInterface({ input: c.stdout }).on("line", (line) => {
+      let msg = null;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        /* not JSON — pass through */
+      }
+      if (msg?.id === REINIT_ID) {
+        // Our replayed initialize: the client already has its answer from the first child.
+        c.stdin.write(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }) + "\n");
+        toClient({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
+        return;
+      }
+      if (msg && msg.id !== undefined && !msg.method) pending.delete(msg.id);
+      process.stdout.write(line + "\n");
+    });
+    c.on("exit", () => {
+      if (c !== child) return; // replaced on purpose
+      child = null;
+      failPending();
+    });
+    child = c;
+    if (initRequest) c.stdin.write(JSON.stringify({ ...initRequest, id: REINIT_ID }) + "\n");
+  };
+
+  const restart = () => {
+    const old = child;
+    child = null;
+    old?.kill();
+    failPending();
+    start();
+  };
+
+  start();
+  let last = stamp(serverCommand().watch);
+  setInterval(() => {
+    const now = stamp(serverCommand().watch);
+    if (now !== last) {
+      last = now;
+      process.stderr.write("[muscat-pk] kit updated — restarting the MCP server\n");
+      restart();
+    }
+  }, POLL_MS).unref();
+
+  createInterface({ input: process.stdin })
+    .on("line", (line) => {
+      let msg = null;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        /* forward as-is */
+      }
+      if (msg?.method === "initialize") initRequest = msg;
+      if (!child) start(); // the server crashed — bring it back (it replays initialize)
+      if (msg && msg.id !== undefined && msg.method) pending.add(msg.id);
+      child.stdin.write(line + "\n");
+    })
+    .on("close", () => {
+      child?.kill();
+      process.exit(0);
+    });
+}

package/cli/src/muscatLocal.mjs

@@ -6,7 +6,7 @@
 // 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 { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { mediaPortFlags, MEDIA_PORTS, publishPortFlags } from "./ports.mjs";
@@ -78,8 +78,22 @@ async function resolveVersions() {
   }
 }
 
+// A new Muscat version replaces the previous runtime image (~2.8GB) and its scripts. One still in
+// use by the running local Muscat stays until a later run (rmi refuses it).
+export function removeOldRuntimes(total) {
+  const tags = spawnSync("docker", ["images", IMAGE, "--format", "{{.Tag}}"], { encoding: "utf8" }).stdout ?? "";
+  for (const tag of tags.split("\n").map((t) => t.trim()).filter((t) => t && t !== total)) {
+    spawnSync("docker", ["rmi", `${IMAGE}:${tag}`], { stdio: "ignore" });
+  }
+  const dir = resolve(CACHE, "runtime");
+  for (const old of existsSync(dir) ? readdirSync(dir) : []) {
+    if (old !== total) rmSync(resolve(dir, old), { recursive: true, force: true });
+  }
+}
+
 async function ensureRuntimeImage(total) {
   const image = `${IMAGE}:${total}`;
+  removeOldRuntimes(total);
   if (canSkipImageBuild(image)) return image;
   const dir = resolve(CACHE, "runtime", total);
   if (!existsSync(resolve(dir, "Dockerfile.runtime"))) {