@rainbow-robotics/muscat-plugin-kit 1.3.8-dev.2 → 1.10.1-dev.0

package/cli/src/pluginDevServer.mjs

@@ -1,112 +1,111 @@
-
-import { createRequire } from "node:module";
-import { writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-
-const pluginRoot = resolve(process.argv[2]);
-const port = Number(process.argv[3] || "4181");
-const readyFile = process.argv[4] ? resolve(process.argv[4]) : "";
-
-
-process.chdir(pluginRoot);
-
-const require = createRequire(resolve(pluginRoot, "package.json"));
-
-const viteMod = await import(pathToFileURL(require.resolve("vite")));
-const createServer = viteMod.createServer ?? viteMod.default?.createServer;
-
-const BOOTSTRAP_PREFIX = "\0rb-bootstrap:";
-const PREAMBLE_ID = "\0rb-preamble";
-const bootstrapPlugin = {
-  name: "rb-plugin-bootstrap",
-  resolveId(id) {
-    if (id.startsWith("rb-bootstrap:")) return "\0" + id;
-    if (id === "rb-preamble") return PREAMBLE_ID;
-  },
-  load(id) {
-    if (id === PREAMBLE_ID) {
-      return `
-import RefreshRuntime from "/@react-refresh";
-RefreshRuntime.injectIntoGlobalHook(window);
-window.$RefreshReg$ = () => {};
-window.$RefreshSig$ = () => (type) => type;
-window.__vite_plugin_react_preamble_installed__ = true;
-`;
-    }
-    if (!id.startsWith(BOOTSTRAP_PREFIX)) return;
-    const ui = id.slice(BOOTSTRAP_PREFIX.length) || "content";
-    const entry = JSON.stringify(`muscat-ui-entry:${ui}`);
-    return `
-import "rb-preamble";
-import { createElement } from "react";
-import { createRoot } from "react-dom/client";
-import { RbContext } from "@rainbow-robotics/plugin-ui/sdk";
-import { setHostServices } from "@rainbow-robotics/plugin-ui/host-ui";
-import { RbWs, createLazyRbSdk } from "@rainbow-robotics/plugin-ui/ws";
-import App from ${entry};
-
-// HMR passes the new module to the accept callback but doesn't rebind the
-// static \`App\` import, so we track the latest at module scope. Without this,
-// navigating away and back (a fresh mount() on this cached module) renders the
-// stale App from first import. \`activeRender\` points at the mounted root so
-// live edits re-render in place.
-let latestApp = App;
-let activeRender = null;
-if (import.meta.hot) {
-  import.meta.hot.accept(${entry}, (m) => {
-    if (!m || !m.default) return;
-    latestApp = m.default;
-    activeRender?.(latestApp);
-  });
-}
-
-export function mount(container, { socketUrl, pluginId, hostServices, data, onSave }) {
-  container.setAttribute("data-muscat-plugin-root", "");
-  container.setAttribute("data-muscat-plugin-id", pluginId);
-  setHostServices(hostServices);
-  // Lazy connect: don't block the first render on the WebSocket handshake
-  // (there may be no backend at all in dev, e.g. no robot reachable) — each rb
-  // method awaits this promise internally instead.
-  const wsPromise = RbWs.connect(socketUrl, pluginId);
-  const rb = createLazyRbSdk(wsPromise, hostServices, { data, onSave });
-  const root = createRoot(container);
-  let mounted = true;
-  const render = (Component) => {
-    if (!mounted) return;
-    root.render(createElement(RbContext.Provider, { value: rb }, createElement(Component)));
-  };
-  const boundRender = (Component) => queueMicrotask(() => render(Component));
-  activeRender = boundRender;
-  render(latestApp);
-  return () => {
-    mounted = false;
-    // Don't clobber a newer mount's render (host defers unmount a microtask).
-    if (activeRender === boundRender) activeRender = null;
-    root.unmount();
-  };
-}
-`;
-  },
-};
-
-const server = await createServer({
-  root: pluginRoot,
-  configFile: resolve(pluginRoot, "vite.config.ts"),
-  mode: "development",
-  plugins: [bootstrapPlugin],
-  server: {
-    port,
-    strictPort: false,
-    cors: true,
-    hmr: { host: "localhost", protocol: "ws" },
-  },
-});
-
-await server.listen();
-const address = server.httpServer?.address();
-const actualPort = typeof address === "object" && address ? address.port : port;
-if (readyFile) {
-  writeFileSync(readyFile, JSON.stringify({ port: actualPort }), "utf8");
-}
-console.log(`[plugin-dev] vite dev server → http://localhost:${actualPort}`);
+
+import { createRequire } from "node:module";
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const pluginRoot = resolve(process.argv[2]);
+const port = Number(process.argv[3] || "4181");
+const readyFile = process.argv[4] ? resolve(process.argv[4]) : "";
+
+
+process.chdir(pluginRoot);
+
+const require = createRequire(resolve(pluginRoot, "package.json"));
+
+const viteMod = await import(pathToFileURL(require.resolve("vite")));
+const createServer = viteMod.createServer ?? viteMod.default?.createServer;
+
+const BOOTSTRAP_PREFIX = "\0rb-bootstrap:";
+const PREAMBLE_ID = "\0rb-preamble";
+const bootstrapPlugin = {
+  name: "rb-plugin-bootstrap",
+  resolveId(id) {
+    if (id.startsWith("rb-bootstrap:")) return "\0" + id;
+    if (id === "rb-preamble") return PREAMBLE_ID;
+  },
+  load(id) {
+    if (id === PREAMBLE_ID) {
+      return `
+import RefreshRuntime from "/@react-refresh";
+RefreshRuntime.injectIntoGlobalHook(window);
+window.$RefreshReg$ = () => {};
+window.$RefreshSig$ = () => (type) => type;
+window.__vite_plugin_react_preamble_installed__ = true;
+`;
+    }
+    if (!id.startsWith(BOOTSTRAP_PREFIX)) return;
+    const ui = id.slice(BOOTSTRAP_PREFIX.length) || "content";
+    const entry = JSON.stringify(`muscat-ui-entry:${ui}`);
+    return `
+import "rb-preamble";
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { RbContext } from "@rainbow-robotics/plugin-ui/sdk";
+import { setHostServices } from "@rainbow-robotics/plugin-ui/host-ui";
+import { RbWs, createLazyRbSdk } from "@rainbow-robotics/plugin-ui/ws";
+import App from ${entry};
+
+// HMR passes the new module to the accept callback but doesn't rebind the
+// static \`App\` import, so we track the latest at module scope. Without this,
+// navigating away and back (a fresh mount() on this cached module) renders the
+// stale App from first import. \`activeRender\` points at the mounted root so
+// live edits re-render in place.
+let latestApp = App;
+let activeRender = null;
+if (import.meta.hot) {
+  import.meta.hot.accept(${entry}, (m) => {
+    if (!m || !m.default) return;
+    latestApp = m.default;
+    activeRender?.(latestApp);
+  });
+}
+
+export function mount(container, { socketUrl, pluginId, hostServices, data, onSave }) {
+  container.setAttribute("data-muscat-plugin-root", "");
+  container.setAttribute("data-muscat-plugin-id", pluginId);
+  setHostServices(hostServices);
+  // Lazy connect: don't block the first render on the WebSocket handshake
+  // (there may be no backend at all in dev, e.g. no robot reachable) — each rb
+  // method awaits this promise internally instead.
+  const wsPromise = RbWs.connect(socketUrl, pluginId);
+  const rb = createLazyRbSdk(wsPromise, hostServices, { data, onSave });
+  const root = createRoot(container);
+  let mounted = true;
+  const render = (Component) => {
+    if (!mounted) return;
+    root.render(createElement(RbContext.Provider, { value: rb }, createElement(Component)));
+  };
+  const boundRender = (Component) => queueMicrotask(() => render(Component));
+  activeRender = boundRender;
+  render(latestApp);
+  return () => {
+    mounted = false;
+    // Don't clobber a newer mount's render (host defers unmount a microtask).
+    if (activeRender === boundRender) activeRender = null;
+    root.unmount();
+  };
+}
+`;
+  },
+};
+
+const server = await createServer({
+  root: pluginRoot,
+  configFile: resolve(pluginRoot, "vite.config.ts"),
+  mode: "development",
+  plugins: [bootstrapPlugin],
+  server: {
+    port,
+    strictPort: false,
+    cors: true,
+    hmr: { host: "localhost", protocol: "ws" },
+  },
+});
+
+await server.listen();
+const address = server.httpServer?.address();
+const actualPort = typeof address === "object" && address ? address.port : port;
+if (readyFile) {
+  writeFileSync(readyFile, JSON.stringify({ port: actualPort }), "utf8");
+}

package/cli/src/ports.mjs

@@ -1,193 +1,193 @@
-// Port contract helpers for plugin back ends.
-import { spawnSync } from "node:child_process";
-import { usesHostNetwork } from "./zenohDev.mjs";
-
-export const PLUGIN_PORT_MIN = 28600;
-export const PLUGIN_PORT_MAX = 28999;
-export const MEDIA_PORTS = [8554, 8889, 8189]; // MediaMTX: RTSP publish, WebRTC, WebRTC media
-export const INTERNAL_DEV_PORTS = new Set([10000, ...MEDIA_PORTS]);
-
-export function mediaPortFlags() {
-  return [
-    "-p", "127.0.0.1:8554:8554", "-p", "127.0.0.1:8889:8889",
-    "-p", "127.0.0.1:8189:8189/udp", "-p", "127.0.0.1:8189:8189/tcp",
-  ];
-}
-export const RESERVED_BACKEND_PORTS = new Map([
-  [502, "Modbus TCP"],
-  [4840, "OPC-UA"],
-  [10000, "Muscat plugin gateway"],
-  [2222, "EtherNet/IP Implicit"],
-  [30004, "RTDE"],
-  [34964, "ProfiNET"],
-  [44818, "EtherNet/IP Explicit"],
-  [50051, "gRPC"],
-]);
-export const RESERVED_BACKEND_PORT_RANGES = [
-  { from: 5170, to: 5179, name: "UI 517x servers" },
-  { from: 8000, to: 8999, name: "Muscat/internal 8000 range" },
-  { from: 50000, to: 50005, name: "robot TCP/UDP ASCII and REST interfaces" },
-];
-
-function reservedPortReason(port) {
-  if (RESERVED_BACKEND_PORTS.has(port)) return RESERVED_BACKEND_PORTS.get(port);
-  const range = RESERVED_BACKEND_PORT_RANGES.find((item) => port >= item.from && port <= item.to);
-  if (!range) return null;
-  return `${range.name} (${range.from}-${range.to})`;
-}
-
-// function isPluginManagedPort(port) {
-//   return reservedPortReason(port) || (port >= PLUGIN_PORT_MIN && port <= PLUGIN_PORT_MAX);
-// }
-
-function isInt(value) {
-  return Number.isInteger(value);
-}
-
-function validatePort(port, field, errors) {
-  if (!isInt(port)) {
-    errors.push(`${field}: must be a port number`);
-    return;
-  }
-  if (port < 1 || port > 65535) {
-    errors.push(`${field}: port must be between 1 and 65535`);
-    return;
-  }
-  const reserved = reservedPortReason(port);
-  if (reserved) {
-    errors.push(`${field}: ${port} is reserved for ${reserved}`);
-    return;
-  }
-  if (port < PLUGIN_PORT_MIN || port > PLUGIN_PORT_MAX) {
-    errors.push(
-      `${field}: external plugin backend ports must be within ${PLUGIN_PORT_MIN}-${PLUGIN_PORT_MAX}`,
-    );
-  }
-}
-
-export function normalizePorts(ports, errors = []) {
-  if (ports === undefined || ports === null) return [];
-  if (!Array.isArray(ports)) {
-    errors.push(`"ports" must be an array`);
-    return [];
-  }
-  if (ports.length === 0) {
-    errors.push(`"ports" must not be empty when provided`);
-    return [];
-  }
-
-  const normalized = [];
-  const seen = new Set();
-  ports.forEach((port, i) => {
-    validatePort(port, `ports[${i}]`, errors);
-    if (!isInt(port)) return;
-    if (seen.has(port)) {
-      errors.push(`"ports" entries must be unique (duplicate: ${port})`);
-      return;
-    }
-    seen.add(port);
-    normalized.push(port);
-  });
-
-  return normalized;
-}
-
-export function validatePorts(ports, errors) {
-  normalizePorts(ports, errors);
-}
-
-export function manifestPortRanges(manifest) {
-  return normalizePorts(manifest?.ports, []);
-}
-
-export function formatPortRange(range) {
-  return String(range);
-}
-
-export function formatPortRanges(ranges) {
-  return ranges.map(formatPortRange).join(", ");
-}
-
-export function portInRanges(port, ranges) {
-  return ranges.includes(port);
-}
-
-export function portEnvFlags(ranges) {
-  if (ranges.length === 0) return [];
-  return ["-e", `RB_PLUGIN_PORTS=${ranges.map(formatPortRange).join(",")}`];
-}
-
-/**
- * `docker run -p` flags for the plugin's declared ports, so macOS/Windows can
- * reach the backend's listeners (native Linux uses --network host and already
- * has them). Only valid on the container that owns the netns.
- */
-export function publishPortFlags(ranges = []) {
-  return ranges.flatMap((port) => ["-p", `127.0.0.1:${port}:${port}`]);
-}
-
-// Skips OS-assigned loopback listeners (127.0.0.1:0, e.g. the SDK's Zenoh session).
-function listeningTcpPorts(container) {
-  const script = `
-read -r eph_lo eph_hi < /proc/sys/net/ipv4/ip_local_port_range 2>/dev/null || { eph_lo=32768; eph_hi=60999; }
-for f in /proc/net/tcp /proc/net/tcp6; do
-  [ -r "$f" ] || continue
-  tail -n +2 "$f" | while read -r sl local_address rem_address st rest; do
-    [ "$st" = "0A" ] || continue
-    hex_ip="\${local_address%%:*}"
-    port=$((0x\${local_address##*:}))
-    case "$hex_ip" in
-      0100007F|00000000000000000000000001000000)
-        [ "$port" -ge "$eph_lo" ] && [ "$port" -le "$eph_hi" ] && continue ;;
-    esac
-    echo "$port"
-  done
-done | sort -n -u
-`;
-  const r = spawnSync("docker", ["exec", container, "bash", "-lc", script], {
-    encoding: "utf8",
-  });
-  if (r.status !== 0) return [];
-  return String(r.stdout || "")
-    .split(/\s+/)
-    .filter(Boolean)
-    .map((v) => Number(v))
-    .filter((v) => Number.isInteger(v));
-}
-
-export function startPortContractMonitor({ container, ranges, log, intervalMs = 1000, allow = [] }) {
-  // Under --network host (or a local Muscat container's netns) /proc/net/tcp shows every
-  // host/robot service port, not just the plugin's — the contract can't be enforced.
-  if (usesHostNetwork() || process.env.MUSCAT_PK_MUSCAT_CONTAINER) return () => false;
-  const declared = ranges ?? [];
-  // muscat-pk's own dev plumbing shares this netns — not the plugin's doing.
-  const ignored = new Set([...INTERNAL_DEV_PORTS, ...allow.map(Number).filter(Number.isInteger)]);
-  let reported = false;
-  const timer = setInterval(() => {
-    // Every listening port that isn't declared is a violation — a port outside
-    // 28600-28999 can't be declared at all, so it must not be opened either.
-    // Otherwise it silently escapes both this check and rby2's install-time
-    // conflict check, and only collides once it's on a robot.
-    const unexpected = listeningTcpPorts(container)
-      .filter((port) => !ignored.has(port))
-      .filter((port) => !portInRanges(port, declared));
-    if (unexpected.length === 0) return;
-
-    clearInterval(timer);
-    reported = true;
-    const declaredText = declared.length > 0 ? formatPortRanges(declared) : "(none)";
-    log.error(
-      `backend opened undeclared TCP port(s): ${unexpected.join(", ")}. ` +
-      `Every listening port must be in manifest.json "ports" within ${PLUGIN_PORT_MIN}-${PLUGIN_PORT_MAX}. ` +
-      `Declared: ${declaredText}`,
-    );
-    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
-    process.exit(1);
-  }, intervalMs);
-  timer.unref?.();
-
-  return () => {
-    clearInterval(timer);
-    return reported;
-  };
-}
+// Port contract helpers for plugin back ends.
+import { spawnSync } from "node:child_process";
+import { usesHostNetwork } from "./zenohDev.mjs";
+
+export const PLUGIN_PORT_MIN = 28600;
+export const PLUGIN_PORT_MAX = 28999;
+export const MEDIA_PORTS = [8554, 8889, 8189]; // MediaMTX: RTSP publish, WebRTC, WebRTC media
+export const INTERNAL_DEV_PORTS = new Set([10000, ...MEDIA_PORTS]);
+
+export function mediaPortFlags() {
+  return [
+    "-p", "127.0.0.1:8554:8554", "-p", "127.0.0.1:8889:8889",
+    "-p", "127.0.0.1:8189:8189/udp", "-p", "127.0.0.1:8189:8189/tcp",
+  ];
+}
+export const RESERVED_BACKEND_PORTS = new Map([
+  [502, "Modbus TCP"],
+  [4840, "OPC-UA"],
+  [10000, "Muscat plugin gateway"],
+  [2222, "EtherNet/IP Implicit"],
+  [30004, "RTDE"],
+  [34964, "ProfiNET"],
+  [44818, "EtherNet/IP Explicit"],
+  [50051, "gRPC"],
+]);
+export const RESERVED_BACKEND_PORT_RANGES = [
+  { from: 5170, to: 5179, name: "UI 517x servers" },
+  { from: 8000, to: 8999, name: "Muscat/internal 8000 range" },
+  { from: 50000, to: 50005, name: "robot TCP/UDP ASCII and REST interfaces" },
+];
+
+function reservedPortReason(port) {
+  if (RESERVED_BACKEND_PORTS.has(port)) return RESERVED_BACKEND_PORTS.get(port);
+  const range = RESERVED_BACKEND_PORT_RANGES.find((item) => port >= item.from && port <= item.to);
+  if (!range) return null;
+  return `${range.name} (${range.from}-${range.to})`;
+}
+
+// function isPluginManagedPort(port) {
+//   return reservedPortReason(port) || (port >= PLUGIN_PORT_MIN && port <= PLUGIN_PORT_MAX);
+// }
+
+function isInt(value) {
+  return Number.isInteger(value);
+}
+
+function validatePort(port, field, errors) {
+  if (!isInt(port)) {
+    errors.push(`${field}: must be a port number`);
+    return;
+  }
+  if (port < 1 || port > 65535) {
+    errors.push(`${field}: port must be between 1 and 65535`);
+    return;
+  }
+  const reserved = reservedPortReason(port);
+  if (reserved) {
+    errors.push(`${field}: ${port} is reserved for ${reserved}`);
+    return;
+  }
+  if (port < PLUGIN_PORT_MIN || port > PLUGIN_PORT_MAX) {
+    errors.push(
+      `${field}: external plugin backend ports must be within ${PLUGIN_PORT_MIN}-${PLUGIN_PORT_MAX}`,
+    );
+  }
+}
+
+export function normalizePorts(ports, errors = []) {
+  if (ports === undefined || ports === null) return [];
+  if (!Array.isArray(ports)) {
+    errors.push(`"ports" must be an array`);
+    return [];
+  }
+  if (ports.length === 0) {
+    errors.push(`"ports" must not be empty when provided`);
+    return [];
+  }
+
+  const normalized = [];
+  const seen = new Set();
+  ports.forEach((port, i) => {
+    validatePort(port, `ports[${i}]`, errors);
+    if (!isInt(port)) return;
+    if (seen.has(port)) {
+      errors.push(`"ports" entries must be unique (duplicate: ${port})`);
+      return;
+    }
+    seen.add(port);
+    normalized.push(port);
+  });
+
+  return normalized;
+}
+
+export function validatePorts(ports, errors) {
+  normalizePorts(ports, errors);
+}
+
+export function manifestPortRanges(manifest) {
+  return normalizePorts(manifest?.ports, []);
+}
+
+export function formatPortRange(range) {
+  return String(range);
+}
+
+export function formatPortRanges(ranges) {
+  return ranges.map(formatPortRange).join(", ");
+}
+
+export function portInRanges(port, ranges) {
+  return ranges.includes(port);
+}
+
+export function portEnvFlags(ranges) {
+  if (ranges.length === 0) return [];
+  return ["-e", `RB_PLUGIN_PORTS=${ranges.map(formatPortRange).join(",")}`];
+}
+
+/**
+ * `docker run -p` flags for the plugin's declared ports, so macOS/Windows can
+ * reach the backend's listeners (native Linux uses --network host and already
+ * has them). Only valid on the container that owns the netns.
+ */
+export function publishPortFlags(ranges = []) {
+  return ranges.flatMap((port) => ["-p", `127.0.0.1:${port}:${port}`]);
+}
+
+// Skips OS-assigned loopback listeners (127.0.0.1:0, e.g. the SDK's Zenoh session).
+function listeningTcpPorts(container) {
+  const script = `
+read -r eph_lo eph_hi < /proc/sys/net/ipv4/ip_local_port_range 2>/dev/null || { eph_lo=32768; eph_hi=60999; }
+for f in /proc/net/tcp /proc/net/tcp6; do
+  [ -r "$f" ] || continue
+  tail -n +2 "$f" | while read -r sl local_address rem_address st rest; do
+    [ "$st" = "0A" ] || continue
+    hex_ip="\${local_address%%:*}"
+    port=$((0x\${local_address##*:}))
+    case "$hex_ip" in
+      0100007F|00000000000000000000000001000000)
+        [ "$port" -ge "$eph_lo" ] && [ "$port" -le "$eph_hi" ] && continue ;;
+    esac
+    echo "$port"
+  done
+done | sort -n -u
+`;
+  const r = spawnSync("docker", ["exec", container, "bash", "-lc", script], {
+    encoding: "utf8",
+  });
+  if (r.status !== 0) return [];
+  return String(r.stdout || "")
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((v) => Number(v))
+    .filter((v) => Number.isInteger(v));
+}
+
+export function startPortContractMonitor({ container, ranges, log, intervalMs = 1000, allow = [] }) {
+  // Under --network host (or a local Muscat container's netns) /proc/net/tcp shows every
+  // host/robot service port, not just the plugin's — the contract can't be enforced.
+  if (usesHostNetwork() || process.env.MUSCAT_PK_MUSCAT_CONTAINER) return () => false;
+  const declared = ranges ?? [];
+  // muscat-pk's own dev plumbing shares this netns — not the plugin's doing.
+  const ignored = new Set([...INTERNAL_DEV_PORTS, ...allow.map(Number).filter(Number.isInteger)]);
+  let reported = false;
+  const timer = setInterval(() => {
+    // Every listening port that isn't declared is a violation — a port outside
+    // 28600-28999 can't be declared at all, so it must not be opened either.
+    // Otherwise it silently escapes both this check and rby2's install-time
+    // conflict check, and only collides once it's on a robot.
+    const unexpected = listeningTcpPorts(container)
+      .filter((port) => !ignored.has(port))
+      .filter((port) => !portInRanges(port, declared));
+    if (unexpected.length === 0) return;
+
+    clearInterval(timer);
+    reported = true;
+    const declaredText = declared.length > 0 ? formatPortRanges(declared) : "(none)";
+    log.error(
+      `backend opened undeclared TCP port(s): ${unexpected.join(", ")}. ` +
+      `Every listening port must be in manifest.json "ports" within ${PLUGIN_PORT_MIN}-${PLUGIN_PORT_MAX}. ` +
+      `Declared: ${declaredText}`,
+    );
+    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
+    process.exit(1);
+  }, intervalMs);
+  timer.unref?.();
+
+  return () => {
+    clearInterval(timer);
+    return reported;
+  };
+}