@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.42 → 0.1.2-dev.44

package/cli/bin/muscat-pk.mjs

@@ -11,7 +11,6 @@ import { runUpdate } from "../src/update.mjs";
 import { runUninstall } from "../src/uninstall.mjs";
 import { runSdk } from "../src/sdk.mjs";
 import { runType } from "../src/type.mjs";
-import { runPreview } from "../src/preview.mjs";
 
 const [, , cmd, ...args] = process.argv;
 
@@ -26,7 +25,6 @@ Commands:
   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)
   update           Update @rainbow-robotics/muscat-plugin-kit and @rainbow-robotics/plugin-ui
   uninstall        Remove the installed muscat-pk CLI (npm global or S3 binary)
   sdk <list|update [version]>   Manage the python rainbow-rb-sdk version
@@ -48,8 +46,6 @@ async function main() {
         return await runDevUi(args);
       case "dev:back":
         return await runDevBack(args);
-      case "preview":
-        return await runPreview(args);
       case "update":
         return await runUpdate(args);
       case "uninstall":

package/cli/src/bridge.mjs

@@ -59,19 +59,16 @@ function ensureImage() {
   pruneMuskatImages();
 }
 
-/** Build the image, preflight the port, and start the bridge container. */
+/**
+ * Build the image, preflight the port, and start the bridge container.
+ * Returns true if bridge started, false if port was already in use (caller decides).
+ */
 export async function startBridge() {
   assertDockerReady();
 
   // remove our own stale container first, then check the host port is free
   spawnSync("docker", ["rm", "-f", BRIDGE_CONTAINER], { stdio: "ignore" });
-  if (await isPortInUse(BRIDGE_PORT)) {
-    throw new Error(
-      `port ${BRIDGE_PORT} is already in use.\n` +
-      `  Another 'muscat-pk dev' may be running, or a process is holding the port.\n` +
-      `  Stop it, or free the port, then retry.`,
-    );
-  }
+  if (await isPortInUse(BRIDGE_PORT)) return false;
 
   ensureImage();
 
@@ -85,6 +82,7 @@ export async function startBridge() {
 
   await waitForPort(BRIDGE_PORT);
   log.step(`Socket.IO bridge listening on ws://127.0.0.1:${BRIDGE_PORT}`);
+  return true;
 }
 
 export function stopBridge() {

package/cli/src/dev.mjs

@@ -1,19 +1,29 @@
 // muscat-pk dev — run the Socket.IO bridge (Docker), dev:ui, and dev:back together.
 import { runDevUi } from "./devUi.mjs";
 import { runDevBack } from "./devBack.mjs";
-import { startBridge, stopBridge, BRIDGE_CONTAINER } from "./bridge.mjs";
-import { ensureDocker, log } from "./util.mjs";
+import { startBridge, stopBridge, BRIDGE_CONTAINER, BRIDGE_PORT } from "./bridge.mjs";
+import { ensureDocker, log, prompt, promptRobotConnection } from "./util.mjs";
 
 export async function runDev(args = []) {
   ensureDocker();
+  const { robotIp, robotToken } = await promptRobotConnection(args);
+  if (robotIp)    process.env.MUSCAT_ROBOT_HOST  = robotIp;
+  if (robotToken) process.env.MUSCAT_ROBOT_TOKEN = robotToken;
   log.step("starting Socket.IO bridge (Docker) + dev:ui + dev:back");
-  await startBridge();
+  const bridgeStarted = await startBridge();
 
-  // Tell dev:back which bridge container to share a netns with, so the backend
-  // reaches the bridge at localhost:10000 (no host.docker.internal).
-  process.env.MUSCAT_PK_BRIDGE_CONTAINER = BRIDGE_CONTAINER;
+  if (!bridgeStarted) {
+    log.warn(`port ${BRIDGE_PORT} is already in use — can't start Socket.IO bridge.`);
+    const answer = await prompt("  Proceed without Socket.IO bridge? [y/N]: ");
+    if (answer.toLowerCase() !== "y") return;
+    log.info("proceeding without bridge — backend will skip network sharing.");
+  } else {
+    // Tell dev:back which bridge container to share a netns with, so the backend
+    // reaches the bridge at localhost:10000 (no host.docker.internal).
+    process.env.MUSCAT_PK_BRIDGE_CONTAINER = BRIDGE_CONTAINER;
+  }
 
-  const cleanup = () => stopBridge();
+  const cleanup = () => { if (bridgeStarted) stopBridge(); };
   process.once("SIGINT", cleanup);
   process.once("SIGTERM", cleanup);
   process.once("exit", cleanup);

package/cli/src/devBack.mjs

@@ -10,7 +10,7 @@
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync, watch } from "node:fs";
 import { resolve } from "node:path";
-import { ensureDocker, findPluginRoot, log } from "./util.mjs";
+import { ensureDocker, findPluginRoot, log, promptRobotConnection } from "./util.mjs";
 import { manifestRuntime, readManifest, validateManifest } from "./manifest.mjs";
 import {
   PYTHON_DEV_IMAGE,
@@ -40,7 +40,13 @@ async function runPython(root) {
   const manifest = readManifest(root);
   const pluginId = manifest.id ?? "";
   const container = `${PYTHON_DEV_IMAGE}-run`;
-  const envFlags = pluginId ? ["-e", `RB_PLUGIN_ID=${pluginId}`] : [];
+  const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
+  const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
+  const envFlags = [
+    ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
+    ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
+    ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
+  ];
   // Share the bridge container's network namespace so localhost:10000 is the
   // bridge (set by `muscat-pk dev`). Standalone dev:back has no bridge to join.
   const bridgeContainer = process.env.MUSCAT_PK_BRIDGE_CONTAINER;
@@ -105,7 +111,13 @@ async function runRos2(root) {
   const pluginId = manifest.id ?? "";
   const isRclcpp = manifest.runtime?.rosClient === "rclcpp";
   const container = `${ROS2_DEV_IMAGE}-run`;
-  const envFlags = pluginId ? ["-e", `RB_PLUGIN_ID=${pluginId}`] : [];
+  const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
+  const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
+  const envFlags = [
+    ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
+    ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
+    ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
+  ];
   const docker = (args, opts = {}) =>
     spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
 
@@ -177,7 +189,13 @@ async function runCpp(root) {
 
   const pluginId = manifest.id ?? "";
   const container = `${CPP_DEV_IMAGE}-run`;
-  const envFlags = pluginId ? ["-e", `RB_PLUGIN_ID=${pluginId}`] : [];
+  const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
+  const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
+  const envFlags = [
+    ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
+    ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
+    ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
+  ];
   const docker = (args, opts = {}) =>
     spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
 
@@ -240,10 +258,13 @@ function warnManifest(root) {
   for (const e of errors) log.warn(`manifest.json: ${e}`);
 }
 
-export async function runDevBack() {
+export async function runDevBack(args = []) {
   ensureDocker();
   const root = findPluginRoot();
   warnManifest(root);
+  const { robotIp, robotToken } = await promptRobotConnection(args);
+  if (robotIp)    process.env.MUSCAT_ROBOT_HOST  = robotIp;
+  if (robotToken) process.env.MUSCAT_ROBOT_TOKEN = robotToken;
   const type = manifestRuntime(root);
   if (type === "ros2") return await runRos2(root);
   if (type === "cpp") return await runCpp(root);

package/cli/src/devUi.mjs

@@ -87,7 +87,7 @@ function spawnViteWatch(pluginRoot, node, { robotIp = "" } = {}) {
   return spawn(node, [viteBin, "build", "--watch", "--mode", "development", "--outDir", DEV_OUT], {
     cwd: pluginRoot,
     stdio: "inherit",
-    env: { ...process.env, ...(robotIp ? { VITE_RRS_PY_HOST: robotIp } : {}) },
+    env: { ...process.env, VITE_PLUGIN_PREVIEW: "true", ...(robotIp ? { VITE_RRS_PY_HOST: robotIp } : {}) },
   });
 }
 
@@ -108,7 +108,7 @@ function waitForInitialBuild(distDir, timeoutMs = 30_000) {
 export async function runDevUi(args = []) {
   const parsed = parseArgs(args);
   const port = parsed.port ?? "4180";
-  const robotIp = parsed["robot-ip"] ?? await prompt("  Robot IP (Enter to skip): ");
+  const robotIp = parsed["robot-ip"] ?? process.env.MUSCAT_ROBOT_HOST ?? await prompt("  Robot IP (skip if no robot): ");
 
   await checkKitUpdate();
   const pluginRoot = findPluginRoot();

package/cli/src/util.mjs

@@ -76,6 +76,31 @@ export async function prompt(question, fallback = "") {
   return answer || fallback;
 }
 
+const LOCAL_HOSTS = new Set(["", "localhost", "127.0.0.1", "::1"]);
+
+/**
+ * Ask for robot IP (and token if remote). Returns { robotIp, robotToken }.
+ * Skips prompts if already set in process.env (from a parent command like `dev`).
+ * Supports --robot-ip / --robot-token flags for non-interactive use.
+ */
+export async function promptRobotConnection(args = []) {
+  const parsed = parseArgs(args);
+  const robotIp =
+    parsed["robot-ip"] ??
+    process.env.MUSCAT_ROBOT_HOST ??
+    (await prompt("  Robot IP (skip if no robot): "));
+
+  if (LOCAL_HOSTS.has(robotIp)) return { robotIp, robotToken: "" };
+
+  const robotToken =
+    parsed["robot-token"] ??
+    process.env.MUSCAT_ROBOT_TOKEN ??
+    (await prompt("  SDK Token (required for remote): "));
+
+  if (!robotToken) throw new Error("SDK token is required for remote robot connection.");
+  return { robotIp, robotToken };
+}
+
 /** Walk up from cwd to find the plugin project root (has manifest.json). */
 export function findPluginRoot(start = process.cwd()) {
   let dir = resolve(start);

package/cli/templates/common/README.md

@@ -99,6 +99,26 @@ connect(App);
 
 ---
 
+## Developing directly on the robot PC
+
+If you're running `muscat-pk dev` **on the robot PC itself**, Muscat is likely already
+running its own Socket.IO bridge on port 10000. In that case the CLI detects the port
+conflict and asks:
+
+```
+⚠ port 10000 is already in use — can't start Socket.IO bridge.
+  Proceed without Socket.IO bridge? [y/N]:
+```
+
+Answer **y**. Your plugin backend will connect to the Muscat bridge that's already
+running instead of starting a new one — exactly what you want when developing on the
+robot.
+
+> If you answer **n** (or just press Enter), the CLI exits so you can free the port
+> manually and retry.
+
+---
+
 ## Backend (`py/main.py`)
 
 The backend communicates with the frontend using `rainbow.rb_sdk.RBPluginCall`.

package/cli/templates/common/py/main.py

@@ -1,15 +1,19 @@
 """
 Muscat plugin backend — __PLUGIN_NAME__
 
-Run with:
+On-robot (default):
   muscat-pk dev:back
   python main.py
 
-This template uses the high-level Rainbow Python SDK instead of wiring the
-transport layer directly.
+Remote dev (from your laptop):
+  Set env vars before running:
+    MUSCAT_ROBOT_HOST=192.168.1.100
+    MUSCAT_ROBOT_TOKEN=<service token>
+  Then: muscat-pk dev:back
 """
 
-import time
+import asyncio
+import os
 from typing import Any
 
 from rainbow.rb_sdk import RBManipulateSDK, RBPluginCall
@@ -18,40 +22,30 @@ from rainbow.rb_sdk import RBManipulateSDK, RBPluginCall
 PLUGIN_NAME = "__PLUGIN_NAME__"
 
 plugin = RBPluginCall()
+manipulate = RBManipulateSDK()
 
 
-@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)
+def register_handlers():
+    # Register handlers here — called after connect() so subscriptions survive
+    # session reconnection in remote-dev mode.
 
+    @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)
 
-@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}")
+    @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}")
+        plugin.publish("state", {"ready": True, "last_grip_width": width})
+        return {"ok": True, "width": width}
 
-    plugin.publish("state", {"ready": True, "last_grip_width": width})
-    return {"ok": True, "width": width}
-
-
-@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}
-
-
-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
+    @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}
 
 
 def move_j_example():
@@ -61,8 +55,6 @@ def move_j_example():
     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={
@@ -73,16 +65,34 @@ def move_j_example():
     )
 
 
-def main():
+async def main():
+    robot_host = os.getenv("MUSCAT_ROBOT_HOST")
+    robot_token = os.getenv("MUSCAT_ROBOT_TOKEN")
+
+    if robot_host and robot_token:
+        # Remote dev: connect to the robot before registering any handlers.
+        # connect() closes and reopens the Zenoh session, so handlers registered
+        # before this call would be lost.
+        await manipulate.connect(token=robot_token, host=robot_host)
+
+    register_handlers()
+
     plugin.publish("state", {"ready": True, "plugin": PLUGIN_NAME})
     print(f"[{PLUGIN_NAME}] backend ready")
 
     try:
         while True:
-            time.sleep(1)
-    except KeyboardInterrupt:
+            await asyncio.sleep(1)
+    except (KeyboardInterrupt, asyncio.CancelledError):
+        pass
+    finally:
+        if robot_host and robot_token:
+            await manipulate.disconnect()
         print(f"[{PLUGIN_NAME}] stopped")
 
 
 if __name__ == "__main__":
-    main()
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass

package/package.json

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

package/cli/src/preview.mjs

@@ -1,91 +0,0 @@
-// muscat-pk preview — build the plugin and open preview-host connected to a
-// real Muscat server (robot or local). No local Socket.IO server is started.
-import { createInterface } from "node:readline";
-import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
-import { buildPlugin } from "./build.mjs";
-import { findPreviewHostRoot } from "./devUi.mjs";
-import { checkKitUpdate, log, parseArgs } from "./util.mjs";
-
-function prompt(question, defaultValue) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((res) => {
-    rl.question(question, (answer) => {
-      rl.close();
-      res(answer.trim() || defaultValue);
-    });
-  });
-}
-
-export async function runPreview(args = []) {
-  const opts = parseArgs(args, { booleans: ["help"] });
-
-  if (opts.help) {
-    console.log(
-      [
-        "",
-        "Usage: muscat-pk preview [options]",
-        "",
-        "  빌드된 플러그인을 실제 Muscat 서버에 연결해 미리봅니다.",
-        "  Socket.IO 서버를 직접 띄우지 않습니다.",
-        "",
-        "Options:",
-        "  --host <ip>    Muscat 서버 IP 또는 hostname (default: localhost)",
-        "  --port <n>     preview-host 로컬 포트 (default: 4180)",
-        "  --ws-port <n>  Muscat Socket.IO 포트 (default: 10000)",
-        "",
-      ].join("\n"),
-    );
-    return;
-  }
-
-  await checkKitUpdate();
-
-  // ── 로봇 IP 결정 ────────────────────────────────────────────────────────────
-  let robotHost = opts.host ?? "";
-  if (!robotHost) {
-    robotHost = await prompt(
-      "Muscat 서버 IP 또는 hostname [localhost]: ",
-      "localhost",
-    );
-  }
-  const wsPort = opts["ws-port"] ?? "10000";
-  const socketUrl = `ws://${robotHost}:${wsPort}`;
-
-  const previewPort = opts.port ?? "4180";
-
-  log.step(`Muscat 서버: ${socketUrl}`);
-
-  // ── 플러그인 빌드 ────────────────────────────────────────────────────────────
-  const { distDir } = await buildPlugin();
-
-  // ── preview-host 실행 ────────────────────────────────────────────────────────
-  const previewRoot = findPreviewHostRoot();
-  const serveEntry = resolve(previewRoot, "serve.mjs");
-
-  if (!existsSync(resolve(previewRoot, "dist", "index.html"))) {
-    log.step("preview-host 번들 빌드 중 (최초 1회)…");
-    await new Promise((res, rej) => {
-      const p = spawn(process.execPath, [resolve(previewRoot, "build.mjs")], {
-        stdio: "inherit",
-      });
-      p.on("exit", (c) => (c === 0 ? res() : rej(new Error("preview-host build failed"))));
-    });
-  }
-
-  log.step(`preview-host 시작 → http://localhost:${previewPort}`);
-  log.step(`Socket.IO URL: ${socketUrl}`);
-
-  const child = spawn(
-    process.execPath,
-    [
-      serveEntry,
-      "--plugin", distDir,
-      "--port", String(previewPort),
-      "--socket-url", socketUrl,
-    ],
-    { stdio: "inherit" },
-  );
-  child.on("exit", (code) => process.exit(code ?? 0));
-}