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

package/cli/docker/Dockerfile.dev

@@ -10,6 +10,4 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 
 WORKDIR /plugin
 
-# requirements are installed at run time from the mounted volume so version
-# bumps don't require an image rebuild.
 CMD ["bash"]

package/cli/src/build.mjs

@@ -10,9 +10,16 @@
 // map, so plugin ZIPs do not carry the UI runtime.
 import { cpSync, copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
 import { buildWithFallback } from "./esbuild.mjs";
 import { findPluginRoot, log } from "./util.mjs";
 
+function isMainBranch() {
+  const r = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
+  const branch = r.stdout?.trim();
+  return branch === "main" || branch === "master";
+}
+
 function manifestRuntime(root) {
   try {
     return JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime?.type ?? "python";
@@ -38,20 +45,44 @@ export async function exportRos2Build(root) {
   log.ok("ros2_ws/install ready (will be included in the ZIP)");
 }
 
-// Resolve the latest released version of a PyPI package.
-async function latestPypiVersion(pkg) {
+const PRERELEASE_RE = /\.(dev|a|b|rc|alpha|beta)\d*/i;
+
+function isPrerelease(version) {
+  return PRERELEASE_RE.test(version);
+}
+
+// Resolve the latest version of a PyPI package.
+// stableOnly=true → skips pre-release (dev/a/b/rc) versions.
+async function latestPypiVersion(pkg, { stableOnly = false } = {}) {
   const res = await fetch(`https://pypi.org/pypi/${pkg}/json`, {
     signal: AbortSignal.timeout(5000),
   });
   if (!res.ok) throw new Error(`pypi ${pkg}: ${res.status}`);
   const data = await res.json();
+
+  if (!stableOnly) return data.info.version;
+
+  // data.info.version is latest stable when stable releases exist.
+  // If it's still a pre-release, scan all releases for the newest stable.
+  if (!isPrerelease(data.info.version)) return data.info.version;
+
+  const stable = Object.keys(data.releases)
+    .filter((v) => !isPrerelease(v))
+    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+    .at(-1);
+
+  if (stable) return stable;
+
+  // No stable release exists — fall back with a warning.
+  log.warn(`  ${pkg}: no stable release found, using ${data.info.version}`);
   return data.info.version;
 }
 
 // Pin unpinned (no version specifier) entries in requirements.txt to the
 // latest PyPI release. Runs on explicit `build`/`pack` only — keeps the shipped
 // plugin reproducible without churning the source file on every dev rebuild.
-export async function pinRequirements(root) {
+// stableOnly=true is used on main-branch builds to avoid shipping dev versions.
+export async function pinRequirements(root, { stableOnly = false } = {}) {
   const reqPath = resolve(root, "requirements.txt");
   if (!existsSync(reqPath)) return;
 
@@ -66,7 +97,7 @@ export async function pinRequirements(root) {
       continue;
     }
     try {
-      const v = await latestPypiVersion(name);
+      const v = await latestPypiVersion(name, { stableOnly });
       out.push(`${name}==${v}`);
       pinned++;
       log.info(`  pinned ${name}==${v}`);
@@ -158,8 +189,9 @@ export async function runBuild(args) {
   const minify = args.includes("--minify");
   const root = findPluginRoot();
   if (!args.includes("--no-pin")) {
-    log.step("pinning requirements.txt to latest PyPI versions");
-    await pinRequirements(root);
+    const stableOnly = isMainBranch();
+    log.step(`pinning requirements.txt to latest ${stableOnly ? "stable " : ""}PyPI versions`);
+    await pinRequirements(root, { stableOnly });
   }
   await buildPlugin({ root, minify });
   await exportRos2Build(root);

package/cli/src/devBack.mjs

@@ -7,7 +7,7 @@
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync, readFileSync, watch } from "node:fs";
 import { resolve } from "node:path";
-import { detectPythonCmd, findPluginRoot, log, venvPython } from "./util.mjs";
+import { detectPythonCmd, hasBin, findPluginRoot, log, venvPython } from "./util.mjs";
 import {
   ROS2_DEV_IMAGE,
   assertDockerReady,
@@ -30,10 +30,18 @@ function runPython(root) {
   const py = venvPython(venv);
 
   if (!existsSync(py)) {
-    const { cmd, is312 } = detectPythonCmd();
-    if (!is312) log.warn("python3.12 not found; using fallback (robot targets 3.12).");
     log.step("creating .venv…");
-    spawnSync(cmd[0], [...cmd.slice(1), "-m", "venv", venv], { cwd: root, stdio: "inherit" });
+    if (hasBin("uv")) {
+      spawnSync("uv", ["venv", venv, "--python", "3.12", "--seed"], { cwd: root, stdio: "inherit" });
+    } else if (hasBin("conda")) {
+      spawnSync("conda", ["create", "-p", venv, "python=3.12", "-y", "--quiet"], { cwd: root, stdio: "inherit" });
+    } else if (hasBin("python3.12") || hasBin("python3") || hasBin("python")) {
+      const { cmd, is312 } = detectPythonCmd();
+      if (!is312) log.warn("python3.12 not found; using fallback (robot targets 3.12).");
+      spawnSync(cmd[0], [...cmd.slice(1), "-m", "venv", venv], { cwd: root, stdio: "inherit" });
+    } else {
+      throw new Error("Python not found (uv / conda / python3 none available). Install Python 3.12 to run the backend.");
+    }
   }
 
   const reqs = resolve(root, "requirements.txt");

package/cli/src/devUi.mjs

@@ -1,22 +1,56 @@
 // muscat-pk dev:ui — preview the plugin inside a mini-Muscat (preview-host).
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { buildPlugin } from "./build.mjs";
-import { checkKitUpdate, findPluginRoot, kitRoot, log } from "./util.mjs";
+import { checkKitUpdate, findPluginRoot, hasBin, kitRoot, log } from "./util.mjs";
 
-/** Resolve @rainbow-robotics/preview-host package root.
- *  Works in monorepo (yarn workspace hoisting) and when both packages are
- *  installed as deps of the plugin project. */
+const PREVIEW_PKG = "@rainbow-robotics/preview-host";
+const CACHE_DIR = resolve(homedir(), ".muscat-pk");
+const CACHE_ROOT = resolve(CACHE_DIR, "node_modules", "@rainbow-robotics", "preview-host");
+
+/**
+ * Resolve preview-host root in order:
+ *  1. Standard require (npm/yarn global install)
+ *  2. Monorepo sibling (dev workspace)
+ *  3. ~/.muscat-pk cache (previous auto-install)
+ *  4. Auto-install to ~/.muscat-pk via npm (binary users who have Node.js)
+ */
 function findPreviewHostRoot() {
+  // 1. npm/yarn 설치 경로
   try {
     const req = createRequire(import.meta.url);
-    return dirname(req.resolve("@rainbow-robotics/preview-host/package.json"));
-  } catch {
-    // fallback: sibling package in muscat-plugin-kit/ workspace
-    return resolve(kitRoot, "../preview-host");
+    return dirname(req.resolve(`${PREVIEW_PKG}/package.json`));
+  } catch {}
+
+  // 2. 모노레포 sibling
+  const sibling = resolve(kitRoot, "../preview-host");
+  if (existsSync(resolve(sibling, "package.json"))) return sibling;
+
+  // 3. 캐시
+  if (existsSync(resolve(CACHE_ROOT, "package.json"))) return CACHE_ROOT;
+
+  // 4. npm 자동 설치 → 캐시
+  if (!hasBin("npm")) {
+    throw new Error(
+      `preview-host를 찾을 수 없습니다.\n` +
+      `Node.js 20+ 를 설치하면 자동으로 준비됩니다: https://nodejs.org`,
+    );
+  }
+  log.step(`preview-host 설치 중 (~/.muscat-pk) — 첫 실행 시 한 번만 수행됩니다…`);
+  mkdirSync(CACHE_DIR, { recursive: true });
+  const r = spawnSync(
+    "npm",
+    ["install", "--prefix", CACHE_DIR, "--save", PREVIEW_PKG],
+    { stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error("preview-host 설치 실패.");
+  if (!existsSync(resolve(CACHE_ROOT, "package.json"))) {
+    throw new Error("preview-host 설치 후에도 패키지를 찾을 수 없습니다.");
   }
+  return CACHE_ROOT;
 }
 
 export async function runDevUi(args = []) {
@@ -31,7 +65,7 @@ export async function runDevUi(args = []) {
   if (!existsSync(resolve(previewRoot, "dist", "index.html"))) {
     log.step("building preview-host bundle (first run)…");
     await new Promise((res, rej) => {
-      const p = spawn("node", [resolve(previewRoot, "build.mjs")], {
+      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"))));
@@ -40,7 +74,7 @@ export async function runDevUi(args = []) {
 
   log.step(`starting preview-host on :${port}`);
   const child = spawn(
-    "node",
+    process.execPath,
     [serveEntry, "--plugin", distDir, "--port", String(port)],
     { stdio: "inherit" },
   );

package/cli/src/new.mjs

@@ -12,7 +12,7 @@ import {
 } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { basename, resolve } from "node:path";
-import { detectPythonCmd, parseArgs, templatesDir, log, venvPython } from "./util.mjs";
+import { detectPythonCmd, hasBin, parseArgs, templatesDir, log, venvPython } from "./util.mjs";
 
 const TYPES = ["python", "ros2"];
 const PMS = ["npm", "yarn", "pnpm", "bun"];
@@ -51,6 +51,7 @@ export function deriveNames(target) {
   const slug = base.toLowerCase().replace(/[^a-z0-9]+/g, "_");
   const pluginName = base.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
   return {
+    dir: base,
     slug,
     pluginName,
     pluginClass: pluginName.replace(/\s+/g, ""),
@@ -112,7 +113,7 @@ export async function runNew(args) {
   }
   pm = PMS.includes(pm) ? pm : "npm";
 
-  const { slug, pluginName, pluginClass, pluginId } = deriveNames(target);
+  const { dir, slug, pluginName, pluginClass, pluginId } = deriveNames(target);
 
   mkdirSync(target, { recursive: true });
 
@@ -125,6 +126,7 @@ export async function runNew(args) {
   applyTokens(target, {
     __PLUGIN_ID__: pluginId,
     __PLUGIN_NAME__: pluginName,
+    __PLUGIN_DIR__: dir,
     __PLUGIN_SLUG__: slug,
     __PLUGIN_CLASS__: pluginClass,
     __PM__: pm,
@@ -144,28 +146,62 @@ export async function runNew(args) {
     } catch {
       log.warn(`'${pm} install' failed; run it manually in ${targetName}`);
     }
+  }
+
+  let noPython = false;
+  let venvFailed = false;
 
+  if (!opts["no-install"]) {
     // Python venv (robot targets 3.12) — cross-platform.
+    // uv is preferred: handles uv-managed Pythons that break standard ensurepip.
     try {
-      const { cmd, is312 } = detectPythonCmd();
-      if (!is312) log.warn("python3.12 not found; venv uses fallback python (robot targets 3.12).");
-      log.step("creating .venv + installing requirements…");
       const venv = resolve(target, ".venv");
-      execFileSync(cmd[0], [...cmd.slice(1), "-m", "venv", venv], { cwd: target, stdio: "inherit" });
-      const py = venvPython(venv);
-      if (existsSync(resolve(target, "requirements.txt"))) {
-        execFileSync(py, ["-m", "pip", "install", "-q", "-r", "requirements.txt"], {
-          cwd: target,
-          stdio: "inherit",
-        });
+      log.step("creating .venv + installing requirements…");
+      if (hasBin("uv")) {
+        execFileSync("uv", ["venv", venv, "--python", "3.12", "--seed"], { cwd: target, stdio: "inherit" });
+      } else if (hasBin("conda")) {
+        execFileSync("conda", ["create", "-p", venv, "python=3.12", "-y", "--quiet"], { cwd: target, stdio: "inherit" });
+      } else if (hasBin("python3.12") || hasBin("python3") || hasBin("python")) {
+        const { cmd, is312 } = detectPythonCmd();
+        if (!is312) log.warn("python3.12 not found; venv uses fallback python (robot targets 3.12).");
+        execFileSync(cmd[0], [...cmd.slice(1), "-m", "venv", venv], { cwd: target, stdio: "inherit" });
+      } else {
+        noPython = true;
+      }
+      if (!noPython) {
+        const py = venvPython(venv);
+        if (existsSync(resolve(target, "requirements.txt"))) {
+          execFileSync(py, ["-m", "pip", "install", "-q", "-r", "requirements.txt"], { cwd: target, stdio: "inherit" });
+        }
       }
     } catch {
-      log.warn("venv setup failed; create it manually: python3.12 -m venv .venv");
+      venvFailed = true;
     }
+  } else {
+    noPython = !hasBin("uv") && !hasBin("conda") && !hasBin("python3.12") && !hasBin("python3") && !hasBin("python");
   }
 
   log.ok(`created ${targetName} (type: ${type}, pm: ${pm})`);
   log.info(`\n  cd ${targetName}`);
-  log.info(`  ${pm} run dev      # preview in mini-Muscat + back end`);
-  log.info(`  ${pm} run pack     # build a distributable ZIP\n`);
+  log.info(`  muscat-pk dev      # preview in mini-Muscat + back end`);
+  log.info(`  muscat-pk pack     # build a distributable ZIP\n`);
+
+  // ── post-scaffold environment warnings ───────────────────────────────────
+  const noNode = !hasBin("node");
+  if (noNode || noPython || venvFailed) {
+    log.info("");
+    if (noNode) {
+      log.warn("Node.js not found. Install Node.js 20+ to run JS deps and dev:ui.");
+      log.warn("  https://nodejs.org");
+    }
+    if (noPython) {
+      log.warn("Python not found. Install Python 3.12 to run the backend.");
+      log.warn("  https://www.python.org/downloads/  (or: brew install python@3.12 / uv / conda)");
+      log.warn(`  Then: cd ${targetName} && python3.12 -m venv .venv && pip install -r requirements.txt`);
+    } else if (venvFailed) {
+      log.warn("venv setup failed. Create it manually:");
+      log.warn(`  cd ${targetName} && python3.12 -m venv .venv && pip install -r requirements.txt`);
+    }
+    log.info("");
+  }
 }

package/cli/src/util.mjs

@@ -79,11 +79,14 @@ export function findPluginRoot(start = process.cwd()) {
   );
 }
 
+const ORANGE = "\x1b[33m";
+const RESET  = "\x1b[0m";
+
 export const log = {
   info: (...m) => console.log(...m),
   step: (...m) => console.log("›", ...m),
-  ok: (...m) => console.log("✓", ...m),
-  warn: (...m) => console.warn("⚠", ...m),
+  ok:   (...m) => console.log("✓", ...m),
+  warn: (...m) => console.warn(`${ORANGE}⚠${RESET}`, ...m.map(s => `${ORANGE}${s}${RESET}`)),
 };
 
 export function humanSize(bytes) {

package/cli/templates/common/README.md

@@ -1,16 +1,261 @@
 # __PLUGIN_NAME__
 
-A Muscat plugin scaffolded with `muscat-pk`.
+A Muscat plugin project. Build, develop, and ship with `muscat-pk` CLI.
+
+## Quick start
+
+```bash
+muscat-pk dev        # UI preview + backend together
+muscat-pk dev:ui     # UI preview only
+muscat-pk dev:back   # backend only (Python watchfiles / ROS2 Docker)
+muscat-pk pack       # build a distributable ZIP
+```
+
+---
+
+## Project structure
+
+```
+__PLUGIN_DIR__/
+├─ src/
+│   └─ content.tsx      # plugin UI entry point
+├─ assets/
+│   └─ icon.svg         # icon referenced from manifest
+├─ manifest.json        # metadata, contribution points, runtime config
+├─ main.py              # backend (Python or ROS2)
+└─ requirements.txt     # Python deps (auto-pinned to latest on pack)
+```
+
+> ROS2 plugins additionally include a `ros2_ws/` directory.
+
+---
+
+## Frontend (`src/content.tsx`)
+
+### useRb() hook
+
+Access the communication API between the plugin module and UI from any plugin component.
+
+```tsx
+import { useRb } from "@rainbow-robotics/plugin-ui/sdk";
+
+function App() {
+  const rb = useRb();
+}
+```
+
+### rb API
+
+| Method | Description |
+|---|---|
+| `rb.pub(topic, payload)` | Publish a message to a topic |
+| `rb.sub(topic, handler)` | Subscribe to a topic — returns `{ undeclare() }` |
+| `rb.action(topic, payload?)` | Send a request and await a reply |
+| `rb.serve(topic, handler)` | Handle incoming requests from the backend |
+| `rb.toast(message, type?)` | Host toast notification (`"info" · "success" · "warning" · "error"`) |
+
+All methods support Generic Types:
+
+```tsx
+const status = await rb.action<{ ok: boolean }, { id: number }>(
+  "get-status",
+  { id: 1 },
+);
+
+const sub = await rb.sub<{ value: number }>("sensor/data", (data) => {
+  console.log(data.value);
+});
+sub.undeclare(); // cleanup
+```
+
+### Topic namespace
+
+Topics are automatically namespaced by plugin ID to prevent collisions across plugins.
+
+```
+"sensor/data"   →  plugin/{pluginId}/sensor/data   (auto-namespaced)
+"/broadcast/x"  →  broadcast/x                    (leading / = absolute)
+```
+
+### UI components
+
+Import Muscat components from `@rainbow-robotics/plugin-ui/react`. The plugin emits
+`rb-*` tags; the host renders the actual components.
+
+```tsx
+import { connect } from "@rainbow-robotics/plugin-ui/connect";
+import { Button, Slider, Text, Switch } from "@rainbow-robotics/plugin-ui/react";
+import { useRb } from "@rainbow-robotics/plugin-ui/sdk";
+
+function App() {
+  const rb = useRb();
+  return <Button label="Run" onPress={() => rb.action("run")} />;
+}
+
+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.
+
+### Python plugin
+
+```python
+import asyncio
+from rainbow_rb_zenoh import ZenohRouter, ZenohClient
+
+router = ZenohRouter(prefix="plugin/__PLUGIN_ID__")
+client = ZenohClient()
+
+
+@router.subscribe("sensor/data")
+async def on_sensor(*, dict_payload, **_):
+    print("received:", dict_payload)
+
+
+@router.queryable("get-status")
+async def get_status(req=None, **_):
+    return {"ok": True}
+
+
+async def main():
+    await router.startup()
+    await asyncio.Event().wait()  # keep alive
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### ROS2 plugin
+
+The node is launched with `--ros-args -r __ns:=/{slug}` automatically by `dev:back`.
+ROS2 topics are bridged to the plugin communication layer — no extra code needed.
+
+```python
+# ros2_ws/src/__PLUGIN_SLUG__/__PLUGIN_SLUG__/node.py
+import rclpy
+from rclpy.node import Node
+from std_msgs.msg import Float32
+
+class __PLUGIN_CLASS__Node(Node):
+    def __init__(self):
+        super().__init__("__PLUGIN_SLUG___node")
+        # relative topic name — __ns prefix applied automatically
+        self.pub = self.create_publisher(Float32, "sensor_data", 10)
+        self.create_timer(1.0, self.timer_cb)
+
+    def timer_cb(self):
+        self.pub.publish(Float32(data=42.0))
+```
+
+---
+
+## manifest.json
+
+```jsonc
+{
+  "id": "com.example.my-plugin",   // unique plugin ID (reverse-domain recommended)
+  "name": "My Plugin",
+  "version": "1.0.0",
+  "minAppVersion": "2.0.0",
+  "icon": "assets/icon.svg",
+
+  "contributes": [
+    { "point": "program.panel", "label": "My Plugin", "icon": "assets/icon.svg" },
+    { "point": "lnb",           "label": "My Plugin", "icon": "assets/icon.svg" },
+    { "point": "header.toolbar","label": "My Plugin", "icon": "assets/icon.svg", "opens": "popover" }
+  ],
+
+  // "python" | "ros2"
+  "runtime": { "type": "python", "entry": "main.py" }
+}
+```
+
+**Contribution points:**
+
+| point | Where it appears |
+|---|---|
+| `program.panel` | Program panel tab |
+| `lnb` | Left navigation bar |
+| `header.toolbar` | Header toolbar button |
+
+---
+
+## Installing Python dependencies
+
+Add any package with an optional version pin to `requirements.txt`:
+
+```
+rainbow-rb-sdk
+rainbow-rb-flat-buffers
+numpy==1.26.4
+opencv-python
+```
+
+Then just run `muscat-pk dev` or `muscat-pk dev:back` — dependencies are installed automatically on every startup:
+
+- **Python plugin**: installed into `.venv` via `pip install -r requirements.txt`
+- **ROS2 plugin**: installed inside the Docker container via `pip install -r requirements.txt`
+
+No extra steps needed.
+
+> `muscat-pk build` / `muscat-pk pack` only **pins** versions in `requirements.txt` — it does not run `pip install`.
+
+---
+
+## Switching backend type
+
+```bash
+muscat-pk type change             # interactive
+muscat-pk type change --to ros2   # python → ros2
+muscat-pk type change --to python # ros2 → python
+```
+
+> `ros2_ws/` is not deleted when switching back to python. Remove it manually if no longer needed.
+
+---
+
+## Shipping
 
 ```bash
-__PM__ run dev        # preview in a mini-Muscat (preview-host) + back end
-__PM__ run dev:ui     # UI preview only
-__PM__ run pack       # build a distributable ZIP
+muscat-pk pack
 ```
 
-- `src/content.tsx` — your plugin UI. Import components from `@rainbow-robotics/plugin-ui/react`.
-- `manifest.json` — id, contributions, actions, runtime.
-- `assets/` — static assets (icons referenced from the manifest).
-- `main.py` — (sdk runtime) back-end handler using `rainbow-rb-sdk`.
+- Builds `src/content.tsx` → `dist/content.js`
+- Pins `requirements.txt` to latest versions (stable-only on `main` branch)
+- ROS2: runs `colcon build` inside the Jazzy container; includes `ros2_ws/install/`
+- Output: `__PLUGIN_DIR__-{version}.zip`
 
-The plugin only emits `rb-*` name tags; Muscat renders the real components.
+ZIP layout:
+
+```
+__PLUGIN_DIR__-1.0.0.zip
+├─ dist/             # built UI
+├─ main.py
+├─ requirements.txt  # pinned
+└─ ros2_ws/install/  # ROS2 only
+```
+
+---
+
+## All commands
+
+```bash
+muscat-pk dev        # UI + backend
+muscat-pk dev:ui     # UI preview only (preview-host)
+muscat-pk dev:back   # backend only (Python: watchfiles / ROS2: Docker)
+muscat-pk build      # UI build only → dist/
+muscat-pk pack       # build + ZIP
+```
+
+```bash
+muscat-pk type change    # switch backend type
+muscat-pk sdk list       # show current Python SDK version
+muscat-pk sdk update     # update Python SDK to latest
+muscat-pk update         # update muscat-plugin-kit itself
+```

package/cli/templates/common/main.py

@@ -1,21 +1,114 @@
+"""
+Muscat plugin backend — __PLUGIN_NAME__
+
+플러그인 UI(브라우저)와 Socket.IO로 통신한다.
+`muscat-pk dev:back` 또는 `python main.py`로 실행.
+
+토픽 자동 네임스페이스:
+  "sensor/data"  →  plugin/__PLUGIN_ID__/sensor/data  (자동)
+  "/broadcast/x" →  broadcast/x                       (앞 / = 절대경로)
+"""
+
 import asyncio
+import socketio
+from aiohttp import web
+
+sio = socketio.AsyncServer(async_mode="aiohttp", cors_allowed_origins="*")
+app = web.Application()
+sio.attach(app)
+
+PLUGIN_ID = "__PLUGIN_ID__"
+_PREFIX = f"plugin/{PLUGIN_ID}"
+
+
+def _topic(relative: str) -> str:
+    """상대 토픽 → 전체 네임스페이스 토픽."""
+    return relative if relative.startswith("/") else f"{_PREFIX}/{relative}"
+
+
+# ── 구독·쿼리어블 핸들러 저장소 ────────────────────────────────────────────────
+_sub_handlers: dict[str, list] = {}
+_queryable_handlers: dict[str, object] = {}
+_serve_pending: dict[str, asyncio.Future] = {}
+
+
+# ── Socket.IO 이벤트 ───────────────────────────────────────────────────────────
+
+@sio.event
+async def sub(sid, data):
+    """브라우저가 토픽을 구독."""
+    await sio.enter_room(sid, f"t:{data['topic']}")
+
+
+@sio.event
+async def unsub(sid, data):
+    await sio.leave_room(sid, f"t:{data['topic']}")
+
+
+@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))
+
+
+@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"))
+
+
+@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"))
+
+
+# ── 헬퍼 데코레이터 ────────────────────────────────────────────────────────────
+
+def subscribe(relative_topic: str):
+    """브라우저 → Python 메시지 구독 핸들러 등록."""
+    def decorator(fn):
+        _sub_handlers.setdefault(_topic(relative_topic), []).append(fn)
+        return fn
+    return decorator
+
+
+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}")
 
-from rb_sdk import RBManipulateSDK  # PyPI: rainbow-rb-sdk
 
-sdk = RBManipulateSDK()
+# ── 플러그인 로직 ──────────────────────────────────────────────────────────────
 
+@subscribe("sensor/data")
+async def on_sensor_data(payload):
+    print(f"[__PLUGIN_NAME__] sensor/data: {payload}")
 
-async def on_action(payload: dict):
-    # Matches manifest.actions[].topic — handle the "grip" action here.
-    width = payload.get("width")
-    print(f"[__PLUGIN_NAME__] grip width={width}")
-    # TODO: drive the robot via the SDK.
 
+@queryable("get-status")
+async def get_status(payload=None):
+    return {"ok": True, "plugin": "__PLUGIN_NAME__"}
 
-async def main():
-    await sdk.subscribe("rby2/plugin/__PLUGIN_ID__/grip", on_action)
-    await sdk.spin()
 
+# ── 진입점 ─────────────────────────────────────────────────────────────────────
 
 if __name__ == "__main__":
-    asyncio.run(main())
+    print("[__PLUGIN_NAME__] Socket.IO server starting on :10000")
+    web.run_app(app, host="0.0.0.0", port=10000)

package/cli/templates/common/package.json

@@ -3,13 +3,6 @@
   "version": "1.0.0",
   "private": true,
   "type": "module",
-  "scripts": {
-    "dev": "muscat-pk dev",
-    "dev:ui": "muscat-pk dev:ui",
-    "dev:back": "muscat-pk dev:back",
-    "build": "muscat-pk build",
-    "pack": "muscat-pk pack"
-  },
   "dependencies": {
     "@rainbow-robotics/plugin-ui": "^0.1.0"
   },

package/cli/templates/common/requirements.txt

@@ -1,3 +1,3 @@
 rainbow-rb-sdk
 rainbow-rb-flat-buffers
-rainbow-rb-zenoh
+python-socketio[aiohttp]

package/cli/templates/common/src/content.tsx

@@ -1,6 +1,7 @@
 import { useState } from "react";
 import { connect } from "@rainbow-robotics/plugin-ui/connect";
-import { Slider, Button, Text, Switch, useRb } from "@rainbow-robotics/plugin-ui/react";
+import { Slider, Button, Text, Switch } from "@rainbow-robotics/plugin-ui/react";
+import { useRb } from "@rainbow-robotics/plugin-ui/sdk";
 
 function App() {
   const rb = useRb();
@@ -22,7 +23,7 @@ function App() {
         onChange={(event: { detail?: boolean }) => {
           const next = event.detail ?? false;
           setOpen(next);
-          rb.notify(next ? "opened" : "closed", "info");
+          rb.toast(next ? "opened" : "closed", "info");
         }}
       />
     </>

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

@@ -1,11 +1,16 @@
 import rclpy
 from rclpy.node import Node
+from rb_sdk import RBManipulateSDK  # PyPI: rainbow-rb-sdk (installed from requirements.txt)
+
+
+sdk = RBManipulateSDK()
 
 
 class __PLUGIN_CLASS__Node(Node):
     def __init__(self):
         super().__init__("__PLUGIN_SLUG___node")
         self.get_logger().info("__PLUGIN_NAME__ node started")
+        # sdk is available here — use it alongside ROS2 topics as needed
 
 
 def main(args=None):

package/package.json

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