@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.11 → 0.1.2-dev.13

package/cli/bin/muscat-pk.mjs

@@ -23,7 +23,7 @@ Commands:
   type change      Switch backend type (python <-> ros2)
   build            Build src/content.tsx -> dist/content.js (+ manifest, assets)
   pack             Build then create a distributable ZIP (with size report)
-  dev              Run dev:ui and dev:back together
+  dev              Run Socket.IO bridge, dev:ui, and dev:back together
   dev:ui           Preview the plugin in a mini-Muscat (preview-host)
   dev:back         Run the plugin back end (python: watchfiles reload / ros2: Docker)
   preview          Preview against a real Muscat server (prompts for robot IP)

package/cli/src/check-package.mjs

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import { readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -22,6 +22,7 @@ function* mjsFiles(dir) {
 }
 
 for (const dir of roots) {
+  if (!existsSync(dir)) continue;
   for (const file of mjsFiles(dir)) {
     execFileSync(process.execPath, ["--check", file], { stdio: "inherit" });
   }

package/cli/src/dev.mjs

@@ -1,10 +1,17 @@
-// muscat-pk dev — run dev:ui and dev:back together.
+// muscat-pk dev — run Socket.IO bridge, dev:ui, and dev:back together.
 import { runDevUi } from "./devUi.mjs";
 import { runDevBack } from "./devBack.mjs";
+import { startSocketBridge } from "./socketBridge.mjs";
 import { log } from "./util.mjs";
 
 export async function runDev(args = []) {
-  log.step("starting dev:ui + dev:back");
+  log.step("starting Socket.IO bridge + dev:ui + dev:back");
+  const bridge = startSocketBridge();
+  const cleanup = () => bridge.close();
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
+  process.once("exit", cleanup);
+
   // dev:back runs to completion / detaches on its own; dev:ui owns the process.
   runDevBack().catch((e) => log.warn(`dev:back: ${e.message}`));
   await runDevUi(args);

package/cli/src/devBack.mjs

@@ -15,15 +15,18 @@ import {
   ros2PackageName,
 } from "./ros2.mjs";
 
-function manifestRuntime(root) {
+function readManifest(root) {
   try {
-    const m = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8"));
-    return m.runtime?.type ?? "python";
+    return JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8"));
   } catch {
-    return "python";
+    return {};
   }
 }
 
+function manifestRuntime(root) {
+  return readManifest(root).runtime?.type ?? "python";
+}
+
 // ── python ────────────────────────────────────────────────────────────────────
 function runPython(root) {
   const venv = resolve(root, ".venv");
@@ -56,13 +59,20 @@ function runPython(root) {
   log.step("pip install -q watchfiles (dev reloader)…");
   spawnSync(py, ["-m", "pip", "install", "-q", "watchfiles"], { cwd: root, stdio: "inherit" });
 
+  const pluginId = readManifest(root).id ?? "";
+  const backEnv = { ...process.env, ...(pluginId ? { RB_PLUGIN_ID: pluginId } : {}) };
+  if (pluginId) log.step(`RB_PLUGIN_ID=${pluginId}`);
+
   log.step("watchfiles → python main.py (reload on any .py change)");
   const child = spawn(
     py,
     ["-m", "watchfiles", "--filter", "python", "--target-type", "command", "python main.py", "."],
-    { cwd: root, stdio: "inherit" },
+    { cwd: root, stdio: "inherit", env: backEnv },
   );
+  const cleanup = () => { if (!child.killed) child.kill(); };
   child.on("exit", (code) => process.exit(code ?? 0));
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
 }
 
 // ── ros2 ───────────────────────────────────────────────────────────────────────
@@ -73,7 +83,9 @@ function runRos2(root) {
 
   ensureImage();
 
+  const pluginId = readManifest(root).id ?? "";
   const container = `${ROS2_DEV_IMAGE}-run`;
+  const envFlags = pluginId ? ["-e", `RB_PLUGIN_ID=${pluginId}`] : [];
   const docker = (args, opts = {}) =>
     spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
 
@@ -97,7 +109,7 @@ function runRos2(root) {
     log.step(`ros2 run ${pkg} ${pkg}_node`);
     child = spawn(
       "docker",
-      ["exec", container, "bash", "-lc",
+      ["exec", ...envFlags, container, "bash", "-lc",
         `cd ros2_ws && source install/setup.bash && ros2 run ${pkg} ${pkg}_node`],
       { cwd: root, stdio: "inherit" },
     );

package/cli/src/esbuild.mjs

@@ -20,20 +20,36 @@ async function buildWithBun(options) {
   }
 }
 
+async function buildWithWasm(options) {
+  const wasm = await import("esbuild-wasm");
+  return wasm.build(options);
+}
+
+function isNativeMissing(err) {
+  const msg = String(err?.message || err?.code || err || "");
+  return (
+    msg.includes("another platform") ||
+    msg.includes("Cannot find module") ||
+    msg.includes("not found") ||
+    msg.includes("No such file") ||
+    msg.includes("ENOENT") ||
+    msg.includes("MODULE_NOT_FOUND")
+  );
+}
+
 export async function buildWithFallback(options) {
   if (typeof Bun !== "undefined") return buildWithBun(options);
 
-  const native = await import("esbuild");
+  // Try native esbuild (faster, no extra setup). Falls back to wasm when:
+  // - esbuild was not installed (removed from hard dependencies to avoid
+  //   postinstall script blocking npm i -g on Windows)
+  // - binary was built for a different platform
   try {
+    const native = await import("esbuild");
     return await native.build(options);
-  } catch (error) {
-    const message = String(error?.message || error);
-    if (!message.includes("another platform")) {
-      throw error;
-    }
-
-    const wasm = await import("esbuild-wasm");
-    console.warn("[muscat-pk] native esbuild binary mismatch; falling back to esbuild-wasm");
-    return wasm.build(options);
+  } catch (err) {
+    if (!isNativeMissing(err)) throw err;
   }
+
+  return buildWithWasm(options);
 }

package/cli/src/socketBridge.mjs

@@ -0,0 +1,122 @@
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { Server } from "socket.io";
+import { log } from "./util.mjs";
+
+const DEFAULT_ACTION_TIMEOUT_MS = 10_000;
+
+export function startSocketBridge({ port = 10000, host = "0.0.0.0" } = {}) {
+  const httpServer = createServer();
+  const io = new Server(httpServer, {
+    cors: { origin: "*" },
+  });
+  const queryables = new Map();
+  const pendingReplies = new Map();
+
+  function cleanupSocket(socket) {
+    for (const [topic, sid] of queryables) {
+      if (sid === socket.id) queryables.delete(topic);
+    }
+
+    for (const [id, pending] of pendingReplies) {
+      if (pending.sid !== socket.id) continue;
+      clearTimeout(pending.timer);
+      pending.resolve(undefined);
+      pendingReplies.delete(id);
+    }
+  }
+
+  io.on("connection", (socket) => {
+    socket.on("sub", async (data = {}) => {
+      if (!data.topic) return;
+      await socket.join(`t:${data.topic}`);
+    });
+
+    socket.on("unsub", async (data = {}) => {
+      if (!data.topic) return;
+      await socket.leave(`t:${data.topic}`);
+    });
+
+    socket.on("pub", (data = {}) => {
+      const topic = data.topic;
+      if (!topic) return;
+      io.to(`t:${topic}`).emit("msg", {
+        topic,
+        payload: data.payload,
+      });
+    });
+
+    socket.on("serve_register", (data = {}) => {
+      if (!data.topic) return;
+      queryables.set(data.topic, socket.id);
+    });
+
+    socket.on("serve_unregister", (data = {}) => {
+      const topic = data.topic;
+      if (!topic) return;
+      if (queryables.get(topic) === socket.id) queryables.delete(topic);
+    });
+
+    socket.on("serve_reply", (data = {}) => {
+      const pending = pendingReplies.get(data.id);
+      if (!pending) return;
+      clearTimeout(pending.timer);
+      pending.resolve(data.payload);
+      pendingReplies.delete(data.id);
+    });
+
+    socket.on("action", (data = {}, ack) => {
+      const topic = data.topic;
+      const sid = topic ? queryables.get(topic) : undefined;
+      const target = sid ? io.sockets.sockets.get(sid) : undefined;
+
+      if (!target) {
+        if (typeof ack === "function") ack(undefined);
+        return;
+      }
+
+      const id = randomUUID();
+      const result = new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          pendingReplies.delete(id);
+          resolve(undefined);
+        }, DEFAULT_ACTION_TIMEOUT_MS);
+
+        pendingReplies.set(id, {
+          sid,
+          timer,
+          resolve,
+        });
+      });
+
+      target.emit("serve_call", {
+        id,
+        topic,
+        payload: data.payload,
+      });
+
+      result.then((payload) => {
+        if (typeof ack === "function") ack(payload);
+      });
+    });
+
+    socket.on("disconnect", () => cleanupSocket(socket));
+  });
+
+  httpServer.listen(port, host, () => {
+    log.step(`Socket.IO bridge listening on ws://127.0.0.1:${port}`);
+  });
+
+  const close = () => {
+    for (const pending of pendingReplies.values()) {
+      clearTimeout(pending.timer);
+      pending.resolve(undefined);
+    }
+    pendingReplies.clear();
+    queryables.clear();
+    io.close();
+    httpServer.close();
+  };
+
+  return { close };
+}

package/cli/templates/common/README.md

@@ -99,36 +99,50 @@ connect(App);
 
 ## Backend (`main.py`)
 
-The backend communicates with the frontend using `rainbow_rb_zenoh`.
-Set the `prefix` to `plugin/{manifest.id}` to match the frontend's auto-namespace.
+The backend communicates with the frontend using `rainbow.rb_sdk.RBPluginCall`.
+Relative topics and plugin context are handled by the SDK.
+`muscat-pk dev` starts the local Socket.IO bridge separately; `main.py`
+should contain plugin logic only and should not start its own server.
 
 ### Python plugin
 
 ```python
-import asyncio
-from rainbow_rb_zenoh import ZenohRouter, ZenohClient
+import time
+from rainbow.rb_sdk import RBAmrSDK, RBManipulateSDK, RBPluginCall
 
-router = ZenohRouter(prefix="plugin/__PLUGIN_ID__")
-client = ZenohClient()
+plugin = RBPluginCall()
 
 
-@router.subscribe("sensor/data")
-async def on_sensor(*, dict_payload, **_):
-    print("received:", dict_payload)
+plugin.publish("state", {"ready": True})
 
 
-@router.queryable("get-status")
-async def get_status(req=None, **_):
-    return {"ok": True}
+@plugin.subscribe("event")
+def on_ui_event(payload=None):
+    print(payload)
 
 
-async def main():
-    await router.startup()
-    await asyncio.Event().wait()  # keep alive
+@plugin.serve("tool/echo")
+def echo(payload=None):
+    return {"echo": payload}
+
+
+def call_frontend():
+    res = plugin.call("tool/ping", payload={"hello": "plugin"})
+    print(res)
+
+
+def move_j_example():
+    amr = RBAmrSDK()
+    manipulate = RBManipulateSDK()
+    return manipulate.move.call_move_j(
+        robot_model="C500920",
+        target={"tar_values": [0, 0, 0, 0, 0, 0], "tar_frame": 0, "tar_unit": 0},
+    )
 
 
 if __name__ == "__main__":
-    asyncio.run(main())
+    while True:
+        time.sleep(1)
 ```
 
 ### ROS2 plugin

package/cli/templates/common/main.py

@@ -1,114 +1,88 @@
 """
 Muscat plugin backend — __PLUGIN_NAME__
 
-플러그인 UI(브라우저)와 Socket.IO로 통신한다.
-`muscat-pk dev:back` 또는 `python main.py`로 실행.
+Run with:
+  muscat-pk dev:back
+  python main.py
 
-토픽 자동 네임스페이스:
-  "sensor/data"  →  plugin/__PLUGIN_ID__/sensor/data  (자동)
-  "/broadcast/x" →  broadcast/x                       (앞 / = 절대경로)
+This template uses the high-level Rainbow Python SDK instead of wiring the
+transport layer directly.
 """
 
-import asyncio
-import socketio
-from aiohttp import web
+import time
+from typing import Any
 
-sio = socketio.AsyncServer(async_mode="aiohttp", cors_allowed_origins="*")
-app = web.Application()
-sio.attach(app)
+from rainbow.rb_sdk import RBManipulateSDK, RBPluginCall
 
-PLUGIN_ID = "__PLUGIN_ID__"
-_PREFIX = f"plugin/{PLUGIN_ID}"
 
+PLUGIN_NAME = "__PLUGIN_NAME__"
 
-def _topic(relative: str) -> str:
-    """상대 토픽 → 전체 네임스페이스 토픽."""
-    return relative if relative.startswith("/") else f"{_PREFIX}/{relative}"
+plugin = RBPluginCall()
 
 
-# ── 구독·쿼리어블 핸들러 저장소 ────────────────────────────────────────────────
-_sub_handlers: dict[str, list] = {}
-_queryable_handlers: dict[str, object] = {}
-_serve_pending: dict[str, asyncio.Future] = {}
+@plugin.subscribe("event")
+def on_ui_event(payload: dict[str, Any] | None = None):
+    """Handle messages published from the plugin UI with rb.pub("event", ...)."""
+    print(f"[{PLUGIN_NAME}] event:", payload)
 
 
-# ── Socket.IO 이벤트 ───────────────────────────────────────────────────────────
+@plugin.serve("grip")
+def grip(payload: dict[str, Any] | None = None):
+    """Handle the default UI button: rb.action("grip", { width })."""
+    width = (payload or {}).get("width", 20)
+    print(f"[{PLUGIN_NAME}] grip requested: width={width}")
 
-@sio.event
-async def sub(sid, data):
-    """브라우저가 토픽을 구독."""
-    await sio.enter_room(sid, f"t:{data['topic']}")
+    plugin.publish("state", {"ready": True, "last_grip_width": width})
+    return {"ok": True, "width": width}
 
 
-@sio.event
-async def unsub(sid, data):
-    await sio.leave_room(sid, f"t:{data['topic']}")
+@plugin.serve("tool/echo")
+def echo(payload: dict[str, Any] | None = None):
+    """Small query example callable from the UI with rb.action("tool/echo", ...)."""
+    return {"echo": payload, "plugin": PLUGIN_NAME}
 
 
-@sio.event
-async def pub(sid, data):
-    """브라우저가 발행 → Python 구독 핸들러로 전달."""
-    topic = data.get("topic", "")
-    payload = data.get("payload")
-    for handler in _sub_handlers.get(topic, []):
-        asyncio.create_task(handler(payload))
+def ping_ui_example():
+    """
+    Example: call a queryable served by the UI.
 
+    In the frontend, register:
+      rb.serve("tool/ping", async (payload) => ({ pong: payload }))
+    """
+    res = plugin.call("tool/ping", payload={"hello": "plugin"})
+    print(f"[{PLUGIN_NAME}] ping response:", res)
+    return res
 
-@sio.event
-async def action(sid, data):
-    """브라우저 rb.action() 호출 → Python queryable 핸들러 → ack 반환."""
-    topic = data.get("topic", "")
-    handler = _queryable_handlers.get(topic)
-    if handler:
-        return await handler(data.get("payload"))
 
+def move_j_example():
+    """
+    Example: use other robot SDKs from the same backend.
 
-@sio.event
-async def serve_reply(sid, data):
-    """브라우저가 serve_call에 응답."""
-    fut = _serve_pending.pop(data.get("id", ""), None)
-    if fut and not fut.done():
-        fut.set_result(data.get("payload"))
+    This function is not called automatically. Add safety checks and call it
+    from your own handler when the robot is ready.
+    """
+    manipulate = RBManipulateSDK()
 
+    return manipulate.move.call_move_j(
+        robot_model="C500920",
+        target={
+            "tar_values": [0, 0, 0, 0, 0, 0],
+            "tar_frame": 0,
+            "tar_unit": 0,
+        },
+    )
 
-# ── 헬퍼 데코레이터 ────────────────────────────────────────────────────────────
 
-def subscribe(relative_topic: str):
-    """브라우저 → Python 메시지 구독 핸들러 등록."""
-    def decorator(fn):
-        _sub_handlers.setdefault(_topic(relative_topic), []).append(fn)
-        return fn
-    return decorator
+def main():
+    plugin.publish("state", {"ready": True, "plugin": PLUGIN_NAME})
+    print(f"[{PLUGIN_NAME}] backend ready")
 
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print(f"[{PLUGIN_NAME}] stopped")
 
-def queryable(relative_topic: str):
-    """브라우저 rb.action() 호출을 처리할 핸들러 등록."""
-    def decorator(fn):
-        _queryable_handlers[_topic(relative_topic)] = fn
-        return fn
-    return decorator
-
-
-async def publish(relative_topic: str, payload) -> None:
-    """Python → 브라우저 구독자에게 메시지 발행."""
-    full = _topic(relative_topic)
-    await sio.emit("msg", {"topic": full, "payload": payload}, room=f"t:{full}")
-
-
-# ── 플러그인 로직 ──────────────────────────────────────────────────────────────
-
-@subscribe("sensor/data")
-async def on_sensor_data(payload):
-    print(f"[__PLUGIN_NAME__] sensor/data: {payload}")
-
-
-@queryable("get-status")
-async def get_status(payload=None):
-    return {"ok": True, "plugin": "__PLUGIN_NAME__"}
-
-
-# ── 진입점 ─────────────────────────────────────────────────────────────────────
 
 if __name__ == "__main__":
-    print("[__PLUGIN_NAME__] Socket.IO server starting on :10000")
-    web.run_app(app, host="0.0.0.0", port=10000)
+    main()

package/cli/templates/ros2/ros2_ws/src/__PLUGIN_SLUG__/__PLUGIN_SLUG__/node.py

@@ -1,6 +1,6 @@
 import rclpy
 from rclpy.node import Node
-from rb_sdk import RBManipulateSDK  # PyPI: rainbow-rb-sdk (installed from requirements.txt)
+from rainbow.rb_sdk import RBManipulateSDK  # PyPI: rainbow-rb-sdk
 
 
 sdk = RBManipulateSDK()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainbow-robotics/muscat-plugin-kit",
-  "version": "0.1.2-dev.11",
+  "version": "0.1.2-dev.13",
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -31,8 +31,8 @@
     "@types/react-dom": "^19.0.4"
   },
   "dependencies": {
-    "@rainbow-robotics/preview-host": "0.1.2-dev.11",
-    "esbuild": "^0.25.0"
+    "@rainbow-robotics/preview-host": "0.1.2-dev.13",
+    "socket.io": "^4.8.1"
   },
   "optionalDependencies": {
     "esbuild-wasm": "^0.25.0"