@rainbow-robotics/muscat-plugin-kit 1.10.2-dev.5 → 1.10.2-dev.7

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/cppIde.mjs

@@ -5,7 +5,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { cppSdkFiles, log } from "./util.mjs";
+import { cppSdkFiles, ensureDevDir, log } from "./util.mjs";
 
 const SYSROOT = ".muscat-dev/sysroot";
 const CONFIG_NAME = "Muscat";
@@ -25,6 +25,7 @@ export function syncCppIde(root, image) {
   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();

package/cli/src/dev.mjs

@@ -7,7 +7,8 @@ import { fileURLToPath } from "node:url";
 import { runDevUi } from "./devUi.mjs";
 import { stopDevBackContainers } from "./devBack.mjs";
 import { ensureLocalMuscat, GATEWAY_PORT, isPortInUse, robotHasMuscat } from "./muscatLocal.mjs";
-import { assertManifestPorts, assertManifestVariables } from "./manifest.mjs";
+import { assertManifestPorts, assertManifestVariables, readManifest } from "./manifest.mjs";
+import { devPluginId } from "./devId.mjs";
 import {
   ensureDocker,
   ensureIdeVenv,
@@ -119,6 +120,8 @@ export async function runDev(args = []) {
   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 });
   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

package/cli/src/devBack.mjs

@@ -8,12 +8,13 @@
 //   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, mkdirSync, readFileSync, watch, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, watch, writeFileSync } from "node:fs";
 import { isIP } from "node:net";
-import { dirname, resolve } from "node:path";
-import { dockerUserFlags, ensureDocker, ensureIdeVenv, findPluginRoot, log, promptRobotConnection, realtimeFlags } from "./util.mjs";
+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 { 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";
 import {
   portEnvFlags,
@@ -110,8 +111,8 @@ async function serveRosPeers(root, pluginId, restart) {
     if (!Array.isArray(peers) || !peers.every((p) => typeof p === "string" && isIP(p))) {
       return { ok: false, error: "peers must be a list of IP addresses" };
     }
+    ensureDevDir(root);
     const file = resolve(root, ROS_PEERS_FILE);
-    mkdirSync(dirname(file), { recursive: true });
     writeFileSync(file, JSON.stringify(peers) + "\n");
     log.step(`ROS_STATIC_PEERS → ${peers.join(";") || "(none)"} — restarting node`);
     restart();
@@ -147,7 +148,7 @@ async function runPython(root, portRanges, robotGateway) {
   await pyEnsureImage();
 
   const manifest = readManifest(root);
-  const pluginId = manifest.id ?? "";
+  const pluginId = process.env.MUSCAT_PK_DEV_PLUGIN_ID || (manifest.id ?? "");
   const container = `${PYTHON_DEV_IMAGE}-run`;
   const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
   const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
@@ -527,7 +528,7 @@ async function runRos2(root, portRanges, robotGateway) {
 
   await ensureImage();
 
-  const pluginId = manifest.id ?? "";
+  const pluginId = process.env.MUSCAT_PK_DEV_PLUGIN_ID || (manifest.id ?? "");
   const container = `${ROS2_DEV_IMAGE}-run`;
   const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
   const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
@@ -622,7 +623,7 @@ async function runCpp(root, portRanges, robotGateway) {
 
   await cppEnsureImage();
 
-  const pluginId = manifest.id ?? "";
+  const pluginId = process.env.MUSCAT_PK_DEV_PLUGIN_ID || (manifest.id ?? "");
   const container = `${CPP_DEV_IMAGE}-run`;
   const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
   const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
@@ -705,6 +706,8 @@ export async function runDevBack(args = []) {
   const { robotIp, robotToken } = await promptRobotConnection(args);
   if (robotIp)    process.env.MUSCAT_ROBOT_HOST  = robotIp;
   if (robotToken) process.env.MUSCAT_ROBOT_TOKEN = robotToken;
+  // Under `dev` this returns the id `dev` chose (environment); standalone it decides it the same way.
+  devPluginId(readManifest(root).id, { robotIp, args });
   // Standalone `dev:back` against a remote robot needs the Zenoh reverse-path
   // advertise host/port too (idempotent — `muscat-pk dev` already set these).
   // Byte-proxy mode (a host-side host_agent set MUSCAT_PROXY_ENDPOINT) makes

package/cli/src/devId.mjs

@@ -0,0 +1,54 @@
+// The plugin id a dev session runs under.
+//
+// Machines developing the same plugin against one robot register the same topics on its gateway, and
+// requests (rb.action, external routes) then reach whichever backend registered last — with no error,
+// so one developer's button runs the other's code. Against a remote robot each machine therefore runs
+// as <manifest id>.dev-<user>-<random>. The random part is kept in ~/.muscat-pk/dev-id: the id stays the
+// same across runs (stable external URLs) and differs between machines even when host or user names match.
+// --keep-id runs under the manifest id (program execute, external clients that use the real id); then only
+// one machine may be connected to that robot.
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { dirname, resolve } from "node:path";
+import { PLUGIN_ID_RE } from "./manifest.mjs";
+import { log } from "./util.mjs";
+import { isRemoteRobot } from "./zenohDev.mjs";
+
+const DEV_ID_FILE = resolve(homedir(), ".muscat-pk", "dev-id");
+const ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+// `dev` decides once; its dev:back child gets no CLI args and reads the id from here.
+const ENV = "MUSCAT_PK_DEV_PLUGIN_ID";
+
+function machineToken() {
+  const saved = existsSync(DEV_ID_FILE) ? readFileSync(DEV_ID_FILE, "utf8").trim() : "";
+  if (/^[a-z0-9]{6}$/.test(saved)) return saved;
+  const token = [...randomBytes(6)].map((b) => ALPHABET[b % ALPHABET.length]).join("");
+  mkdirSync(dirname(DEV_ID_FILE), { recursive: true });
+  writeFileSync(DEV_ID_FILE, `${token}\n`);
+  return token;
+}
+
+function userName() {
+  try {
+    return userInfo().username.toLowerCase().replace(/[^a-z0-9]/g, "").slice(0, 12);
+  } catch {
+    return "";
+  }
+}
+
+/** The id for this dev session (UI, backend, ROS namespace and external routes all use it). */
+export function devPluginId(manifestId, { robotIp, args = [] }) {
+  if (process.env[ENV]) return process.env[ENV];
+  let id = manifestId;
+  if (manifestId && isRemoteRobot(robotIp) && !args.includes("--keep-id")) {
+    const candidate = `${manifestId}.${["dev", userName(), machineToken()].filter(Boolean).join("-")}`;
+    if (PLUGIN_ID_RE.test(candidate)) id = candidate;
+  }
+  if (id !== manifestId) {
+    log.step(`dev plugin id ${id} — this machine's own on the shared robot (--keep-id runs as ${manifestId})`);
+    log.step(`external routes: http://${robotIp}:3000/common/plugin/${id}/<path>`);
+  }
+  if (id) process.env[ENV] = id;
+  return id;
+}

package/cli/src/devUi.mjs

@@ -2,12 +2,14 @@
 import { spawn, spawnSync } from "node:child_process";
 import { createServer as createNetServer } from "node:net";
 import { createRequire } from "node:module";
-import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, watch } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, watch, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { checkKitUpdate, findPluginRoot, hasBin, kitRoot, log, parseArgs, prompt } from "./util.mjs";
-import { ensureLocalMuscat, GATEWAY_PORT, robotHasMuscat } from "./muscatLocal.mjs";
+import { checkKitUpdate, ensureDevDir, findPluginRoot, hasBin, kitRoot, log, openBrowser, parseArgs, prompt } from "./util.mjs";
+import { devPluginId } from "./devId.mjs";
+import { readManifest } from "./manifest.mjs";
+import { ensureLocalMuscat, GATEWAY_PORT, localFullMuscat, robotHasMuscat } from "./muscatLocal.mjs";
 import { isRemoteRobot } from "./zenohDev.mjs";
 
 
@@ -32,7 +34,6 @@ const CACHE_DIR = resolve(homedir(), ".muscat-pk");
 const CACHE_ROOT = resolve(CACHE_DIR, "node_modules", "@rainbow-robotics", "preview-host");
 
 
-const DEV_OUT = ".muscat-dev";
 
 function findNodeBin() {
   if (typeof Bun === "undefined") return process.execPath;
@@ -81,11 +82,15 @@ function syncAssets(pluginRoot, outDir) {
 }
 
 
-function stageDevAssets(pluginRoot) {
-  const outDir = resolve(pluginRoot, DEV_OUT);
-  mkdirSync(outDir, { recursive: true });
+// 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);
   const manifestSrc = resolve(pluginRoot, "manifest.json");
-  if (existsSync(manifestSrc)) copyFileSync(manifestSrc, resolve(outDir, "manifest.json"));
+  if (existsSync(manifestSrc)) {
+    const manifest = JSON.parse(readFileSync(manifestSrc, "utf8"));
+    if (pluginId) manifest.id = pluginId;
+    writeFileSync(resolve(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+  }
   syncAssets(pluginRoot, outDir);
   return outDir;
 }
@@ -162,7 +167,7 @@ export async function runDevUi(args = []) {
 
   await checkKitUpdate();
   const pluginRoot = findPluginRoot();
-  const outDir = stageDevAssets(pluginRoot);
+  const outDir = stageDevAssets(pluginRoot, devPluginId(readManifest(pluginRoot).id, { robotIp, args }));
   const port = await getFreePort(requestedPort);
 
   // No robot: the bundle talks to localhost:3000, so put a Muscat there (`dev` already did).
@@ -194,6 +199,9 @@ export async function runDevUi(args = []) {
     });
   }
 
+  const localDevMuscat = await localFullMuscat(robotIp);
+  const uiHost = isRemoteRobot(robotIp) ? robotIp : localDevMuscat ? "localhost" : "";
+
   const previewRoot = findPreviewHostRoot();
   const serveEntry = resolve(previewRoot, "serve.mjs");
   if (!existsSync(resolve(previewRoot, "dist", "index.html"))) {
@@ -214,11 +222,11 @@ export async function runDevUi(args = []) {
       "--plugin", outDir,
       "--port", String(port),
       "--dev-server-url", `http://localhost:${devPort}`,
-      // A remote robot turns the bundle into that robot's Muscat UI; localhost stays the mock preview.
-      ...(isRemoteRobot(robotIp) ? ["--robot-host", robotIp] : []),
-      // The dev plugin's socket goes to the robot's gateway when the robot runs Muscat (the UI is
-      // that robot's Muscat then); otherwise to the local runtime.
-      ...((await robotHasMuscat(robotIp)) ? ["--socket-url", `ws://${robotIp}:${GATEWAY_PORT}`] : []),
+      // A remote robot (or a local muscat-dev) turns the bundle into that Muscat's UI; otherwise
+      // it stays the mock preview.
+      ...(uiHost ? ["--robot-host", uiHost] : []),
+      // The dev plugin's socket goes to that Muscat's gateway; otherwise to the local runtime.
+      ...((await robotHasMuscat(robotIp)) || localDevMuscat ? ["--socket-url", `ws://${uiHost}:${GATEWAY_PORT}`] : []),
     ],
     // preview-host only prints its address and paths; the "UI →" line below says what matters.
     { stdio: ["inherit", "ignore", "inherit"] },
@@ -227,6 +235,8 @@ export async function runDevUi(args = []) {
   for (let i = 0; i < 50 && !(await fetch(`http://localhost:${port}/`).then(() => true, () => false)); i++)
     await new Promise((r) => setTimeout(r, 200));
   log.ok(`UI → http://localhost:${port}`);
+  // Only for a person at a terminal — not CI, scripts or `--no-open`.
+  if (process.stdout.isTTY && !process.env.CI && !parsed["no-open"]) openBrowser(`http://localhost:${port}`);
 
   let cleaned = false;
   const cleanup = () => {

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

@@ -128,8 +128,7 @@ async function waitForApi(timeoutMs = 180_000) {
 
 // Does the robot at `ip` run Muscat (common answers /is-muscat)? Then the dev UI and backend use its
 // gateway and no local Muscat is started. Local addresses and unreachable hosts → false.
-export async function robotHasMuscat(ip) {
-  if (!ip || LOCAL_HOSTS.has(ip)) return false;
+async function isMuscat(ip) {
   try {
     const res = await fetch(`http://${ip}:${API_PORT}/common/is-muscat`, { signal: AbortSignal.timeout(3000) });
     return res.ok && (await res.json())?.result === true;
@@ -138,6 +137,20 @@ export async function robotHasMuscat(ip) {
   }
 }
 
+export async function robotHasMuscat(ip) {
+  if (!ip || LOCAL_HOSTS.has(ip)) return false;
+  return isMuscat(ip);
+}
+
+// rby2's full Muscat dev stack on this machine — unlike muscat-pk's own minimal runtime it has the
+// whole UI backend, so `dev` without a robot IP shows its real Muscat UI, like a robot's.
+const LOCAL_FULL_MUSCAT = "muscat-dev";
+export async function localFullMuscat(ip) {
+  if (!LOCAL_HOSTS.has(ip ?? "") || !hasBin("docker")) return false;
+  const r = spawnSync("docker", ["ps", "--filter", `name=^${LOCAL_FULL_MUSCAT}$`, "--format", "{{.Names}}"], { encoding: "utf8" });
+  return !!(r.stdout || "").trim() && isMuscat("127.0.0.1");
+}
+
 // Is a host TCP port already bound?
 export function isPortInUse(port) {
   return new Promise((res) => {

package/cli/src/storybook.mjs

@@ -14,10 +14,10 @@ import {
   rmSync,
   statSync,
 } from "node:fs";
-import { execSync, spawn } from "node:child_process";
+import { execSync } from "node:child_process";
 import { copyFileSync } from "node:fs";
 import { extname, join, resolve } from "node:path";
-import { kitRoot, log, parseArgs } from "./util.mjs";
+import { kitRoot, log, openBrowser, parseArgs } from "./util.mjs";
 
 // Shipped location (under cli/ → included in the npm "files" list).
 const SHIPPED_DIST = resolve(kitRoot, "cli/storybook-dist");
@@ -93,24 +93,6 @@ export function buildStorybook() {
   log.ok(`storybook → ${SHIPPED_DIST}`);
 }
 
-function openBrowser(url) {
-  const cmd =
-    process.platform === "darwin"
-      ? "open"
-      : process.platform === "win32"
-        ? "start"
-        : "xdg-open";
-  try {
-    spawn(cmd, [url], {
-      stdio: "ignore",
-      detached: true,
-      shell: process.platform === "win32",
-    }).unref();
-  } catch {
-    /* headless / no browser — the URL is printed anyway */
-  }
-}
-
 function serve(distDir, port) {
   const server = createServer((req, res) => {
     const url = decodeURIComponent((req.url || "/").split("?")[0]);