@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.3 → 0.1.2-dev.31

package/cli/src/util.mjs

@@ -1,8 +1,42 @@
 // Shared helpers for muscat-pk.
+import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+/** True if an executable is on PATH (cross-platform). */
+export function hasBin(bin) {
+  const probe = process.platform === "win32" ? "where" : "which";
+  return spawnSync(probe, [bin]).status === 0;
+}
+
+/**
+ * Find a Python 3.12 interpreter (robot targets 3.12), cross-platform.
+ * Returns the command as an argv array, e.g. ["py","-3.12"] or ["python3.12"].
+ * Falls back to a generic python3/python with a warning flag.
+ */
+export function detectPythonCmd() {
+  const candidates =
+    process.platform === "win32"
+      ? [["py", "-3.12"], ["python3.12"], ["py", "-3"], ["python"]]
+      : [["python3.12"], ["python3"], ["python"]];
+  for (const cmd of candidates) {
+    const r = spawnSync(cmd[0], [...cmd.slice(1), "--version"]);
+    if (r.status === 0) {
+      const ver = String(r.stdout || r.stderr || "");
+      return { cmd, is312: ver.includes("3.12") };
+    }
+  }
+  return { cmd: process.platform === "win32" ? ["python"] : ["python3"], is312: false };
+}
+
+/** Path to the venv's python interpreter (cross-platform). */
+export function venvPython(venvDir) {
+  return process.platform === "win32"
+    ? resolve(venvDir, "Scripts", "python.exe")
+    : resolve(venvDir, "bin", "python");
+}
+
 /** Published install/CLI package name. Author imports use @rainbow-robotics/plugin-ui separately. */
 export const KIT_PUBLISHED_NAME = "@rainbow-robotics/muscat-plugin-kit";
 
@@ -45,13 +79,40 @@ export function findPluginRoot(start = process.cwd()) {
   );
 }
 
+const RED    = "\x1b[31m";
+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),
+  info:  (...m) => console.log(...m),
+  step:  (...m) => console.log("›", ...m),
+  ok:    (...m) => console.log("✓", ...m),
+  warn:  (...m) => console.warn(`${ORANGE}⚠${RESET}`, ...m.map(s => `${ORANGE}${s}${RESET}`)),
+  error: (...m) => console.error(`${RED}✖${RESET}`, ...m.map(s => `${RED}${s}${RESET}`)),
 };
 
+// dev / dev:back / build run the plugin back end, the dev bridge, and cpp/ros2
+// compilation in Docker. Show a clear install hint when Docker is missing.
+export function ensureDocker() {
+  if (hasBin("docker")) return;
+  log.warn("Docker not found.");
+  log.warn("  muscat-pk runs the plugin back end, the dev bridge, and cpp/ros2 builds in Docker.");
+  log.warn("  Install Docker, then retry: https://docs.docker.com/get-docker/");
+  throw new Error("Docker is required for dev / dev:back / build.");
+}
+
+/**
+ * Remove dangling (untagged) muscat-pk images left behind after a rebuild.
+ * Uses label filter so only our images are touched — other Docker images are safe.
+ */
+export function pruneMuskatImages() {
+  spawnSync(
+    "docker",
+    ["image", "prune", "--force", "--filter", "label=com.rainbow-robotics.muscat-pk=true"],
+    { stdio: "ignore" },
+  );
+}
+
 export function humanSize(bytes) {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;

package/cli/templates/common/README.md

@@ -1,16 +1,389 @@
 # __PLUGIN_NAME__
 
-A Muscat plugin scaffolded with `muscat-pk`.
+A Muscat plugin project. Build, develop, and ship with `muscat-pk` CLI.
+
+## Quick start
 
 ```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 dev        # UI preview + backend together
+muscat-pk dev:ui     # UI preview only
+muscat-pk dev:back   # backend only (Python watchfiles / ROS2 Docker)
+muscat-pk build      # build + distributable ZIP
+```
+
+---
+
+## Project structure
+
+```
+__PLUGIN_DIR__/
+├─ ui/
+│   └─ content.tsx      # plugin UI entry point
+├─ py/
+│   └─ main.py          # Python backend entry point
+├─ assets/
+│   └─ icon.svg         # icon referenced from manifest
+├─ manifest.json        # metadata, contribution points, runtime config
+├─ README.md            # this file (copied to dist/ on build)
+└─ requirements.txt     # Python deps (auto-pinned to latest on build)
 ```
 
-- `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`.
+> ROS2 plugins additionally include a `ros2_ws/` directory.
+
+---
+
+## Frontend (`ui/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 (`py/main.py`)
+
+The backend communicates with the frontend using `rainbow.rb_sdk.RBPluginCall`.
+`muscat-pk dev` starts the Socket.IO bridge in Docker (published on port 10000) and
+runs the backend container sharing its network, so the SDK connects at localhost:10000.
+`py/main.py` should contain plugin logic only and must not start its own server.
+
+### Python plugin
+
+```python
+import time
+from rainbow.rb_sdk import RBAmrSDK, RBManipulateSDK, RBPluginCall
+
+plugin = RBPluginCall()
+
+
+plugin.publish("state", {"ready": True})
+
+
+@plugin.subscribe("event")
+def on_ui_event(payload=None):
+    print(payload)
+
+
+@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__":
+    while True:
+        time.sleep(1)
+```
+
+### ROS2 plugin
+
+The node is launched with `--ros-args -r __ns:=/{slug}` automatically by `dev:back`.
+
+```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
 
-The plugin only emits `rb-*` name tags; Muscat renders the real components.
+```jsonc
+{
+  // unique plugin ID — reverse-domain format recommended
+  "id": "com.example.my-plugin",
+  "name": "My Plugin",
+  "version": "1.0.0",
+
+  // minimum Muscat version required to load this plugin
+  "minMuscatVersion": "1.0.0",
+
+  // plugin author (empty string is fine)
+  "author": "Your Name",
+
+  // displayed in the Muscat plugin store / info panel
+  // string or { en (required), ko, ja, zh, vi, th, es }
+  "description": { "en": "Plugin description", "ko": "플러그인 설명" },
+
+  // SVG string (single file) or PNG/JPG size map (all three sizes required)
+  "icons": "assets/icon.svg",
+  // "icons": { "16": "assets/icon-16.png", "48": "assets/icon-48.png", "128": "assets/icon-128.png" },
+
+  // targetModels and/or targetCategorys — at least one is required
+  // "all" = every target, or list specific values
+  "targetModels": "all",
+  // "targetModels": ["C500920", "C500930"],
+  "targetCategorys": "all",
+  // "targetCategorys": ["manipulate", "amr", "rby1", "vision"],
+
+  "contributes": [
+    // program.command — adds a step node to the program tree
+    {
+      "point": "program.command",
+      "icon": "assets/icon.svg",
+      "label": { "ko": "내 플러그인", "en": "My Plugin" },
+      "ui": "program/content",   // must be unique across all contributions
+      "commandInfo": {
+        "name": "My Plugin",
+        "icon": "assets/icon.svg",
+        "funcName": "plugin.run",
+        "args": {}
+      }
+    },
+    // toolbar — adds a button to the top toolbar (required)
+    {
+      "point": "toolbar",
+      "icon": "assets/icon.svg",
+      "label": { "ko": "내 플러그인", "en": "My Plugin" },
+      "ui": "content",           // must be unique across all contributions
+      "opens": "popover"
+    },
+    // move.rnb — adds a panel to the Move screen right-side area
+    {
+      "point": "move.rnb",
+      "icon": "assets/icon.svg",
+      "label": { "ko": "내 플러그인", "en": "My Plugin" },
+      "ui": "move/content"       // must be unique across all contributions
+    }
+  ],
+
+  // runtime — one of:
+  //   { "type": "none" }
+  //   { "type": "python", "entry": "main.py" }
+  //   { "type": "cpp", "entry": "<executable name>" }
+  //   { "type": "ros2", "rosClient": "rclpy" | "rclcpp", "package": "...", "launch": "..._node" }
+  "runtime": { "type": "python", "entry": "main.py" }
+}
+```
+
+**Backend types:**
+
+| type | source dir | build / run | entry |
+|---|---|---|---|
+| `python` | `py/` | pip + run in Docker | `main.py` |
+| `cpp` | `cpp/` | CMake in Docker | built executable name |
+| `ros2` (rclpy) | `ros2_ws/` | colcon (ament_python) in Docker | — |
+| `ros2` (rclcpp) | `ros2_ws/` | colcon (ament_cmake) in Docker | — |
+
+> Every back end runs in a Docker container matching the robot (Ubuntu 24.04 + Python 3.12), so dev behaves like production and compiled binaries are ABI-compatible. **Docker is required** for all backend types (only a frontend-only `none` plugin skips it). No local Python/toolchain setup is needed.
+
+**Contribution points:**
+
+| point | Where it appears | `commandInfo` required |
+|---|---|:---:|
+| `toolbar` | Top toolbar button (must have at least one) | — |
+| `program.command` | Program tree step node | ✓ |
+| `move.rnb` | Move screen right-side panel | — |
+
+**`commandInfo` fields** (for `program.command`):
+
+| field | type | description |
+|---|---|---|
+| `name` | `string` | Display name of the step node |
+| `icon` | `string` | Icon path |
+| `iconClassName` | `string?` | Optional CSS class for the icon |
+| `funcName` | `string?` | Backend function name to call |
+| `args` | `Record<string, any>?` | Default arguments |
+| `disabled` | `boolean?` | Whether the node is disabled |
+| `allowChildren` | `string[]?` | Allowed child commands |
+| `allowParents` | `string[]?` | Allowed parent commands |
+| `notAllowChildren` | `string[]?` | Disallowed child commands |
+| `syncGroupId` | `boolean?` | Sync group ID across children |
+| `disableCopy` | `boolean?` | Prevent copy |
+| `disableDelete` | `boolean?` | Prevent delete |
+| `requireChildren` | `boolean?` | Whether a child command is required |
+| `requireParent` | `boolean?` | Whether a parent command is required |
+| `childrenCommand` | `string?` | Default command type for children |
+
+**Validation rules:**
+- `id`, `name`, `version`, `minMuscatVersion` — required non-empty strings
+- `author` — required non-empty string
+- `description` — required (`string` or `{ en (required), ko?, ja?, zh?, vi?, th?, es? }`)
+- `icons` — SVG: single string path ending in `.svg`; PNG/JPG: object with `"16"`, `"48"`, `"128"` all present
+- `targetModels` — `"all"` or a non-empty array of robot model ID strings (at least one of `targetModels` / `targetCategorys` required)
+- `targetCategorys` — `"all"` or a non-empty array of `"manipulate" | "amr" | "rby1" | "vision"` (at least one of `targetModels` / `targetCategorys` required)
+- `contributes` — required array; must contain at least one `toolbar` entry
+- `ui` — each contribution must have a unique value
+- `commandInfo` — required when `point` is `"program.command"`
+
+`muscat-pk build` throws on any validation error. `muscat-pk dev` prints warnings.
+
+---
+
+## Localized documentation
+
+You can ship per-language README files alongside the main `README.md`. Place them in the project root:
+
+```
+README.md        # default / English fallback
+README.ko.md     # Korean
+README.en.md     # explicit English (optional)
+README.ja.md     # Japanese
+```
+
+All `README*.md` files found at the project root are automatically copied to `dist/` on
+`muscat-pk build`. Muscat displays the file matching the user's locale,
+falling back to `README.md` if none matches.
+
+---
+
+## 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
+```
+
+Run `muscat-pk dev` or `muscat-pk dev:back` — dependencies are installed automatically inside the dev container (`pip install -r requirements.txt`) on every startup. No local Python or venv needed.
+
+> `muscat-pk build` only **pins** versions in `requirements.txt` — it does not run `pip install` (the robot installs them at load time).
+
+---
+
+## Switching backend type
+
+```bash
+muscat-pk type change                 # interactive
+muscat-pk type change --to cpp        # → C++
+muscat-pk type change --to ros2       # → ROS2 (rclpy / Python)
+muscat-pk type change --to ros2-cpp   # → ROS2 (rclcpp / C++)
+muscat-pk type change --to python     # → Python
+```
+
+> Existing backend dirs (`ros2_ws/`, `cpp/`) are not deleted when switching away. Remove them manually if no longer needed.
+
+---
+
+## Shipping
+
+```bash
+muscat-pk build            # build + ZIP
+muscat-pk build --no-zip   # build only, no ZIP
+```
+
+- Builds `ui/content.tsx` → `dist/content.js` (minified)
+- Pins `requirements.txt` to latest versions (stable-only on `main` branch)
+- Copies `assets/`, `manifest.json`, `README*.md`, `py/`, and `requirements.txt` into `dist/`
+- ROS2: runs `colcon build` inside the Jazzy container; includes `ros2_ws/install/`
+- Output: `__PLUGIN_DIR__-{version}.zip`
+
+ZIP layout:
+
+```
+__PLUGIN_DIR__-1.0.0.zip
+├─ dist/
+│   ├─ content.js        # built UI
+│   ├─ manifest.json
+│   ├─ assets/
+│   ├─ README.md
+│   ├─ README.ko.md      # if present
+│   ├─ main.py           # from 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      # build → dist/ + distributable ZIP (--no-zip to skip)
+```
+
+```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/manifest.json

@@ -2,24 +2,24 @@
   "id": "__PLUGIN_ID__",
   "name": "__PLUGIN_NAME__",
   "version": "1.0.0",
-  "minAppVersion": "2.0.0",
-  "icon": "assets/icon.svg",
+  "minMuscatVersion": "1.0.0",
+  "author": "__PLUGIN_AUTHOR__",
+  "email": "__PLUGIN_EMAIL__",
+  "description": {
+    "ko": "",
+    "en": ""
+  },
+  "icons": "assets/icon.svg",
+  "targetModels": "all",
+  "targetCategorys": "all",
   "contributes": [
-    { "point": "program.panel", "label": "__PLUGIN_NAME__", "icon": "assets/icon.svg" },
-    { "point": "lnb", "label": "__PLUGIN_NAME__", "icon": "assets/icon.svg" },
     {
-      "point": "header.toolbar",
-      "label": "__PLUGIN_NAME__",
+      "point": "toolbar",
       "icon": "assets/icon.svg",
+      "label": { "ko": "__PLUGIN_NAME__", "en": "__PLUGIN_NAME__" },
+      "ui": "content",
       "opens": "popover"
     }
   ],
-  "actions": [
-    {
-      "id": "grip",
-      "topic": "rby2/plugin/__PLUGIN_ID__/grip",
-      "schema": { "width": "number" }
-    }
-  ],
   "runtime": { "type": "__RUNTIME_TYPE__", "entry": "main.py" }
 }

package/cli/templates/common/package.json

@@ -3,20 +3,14 @@
   "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"
+    "@rainbow-robotics/plugin-ui": "__RB_VERSION__"
   },
   "devDependencies": {
-    "@rainbow-robotics/muscat-plugin-kit": "^0.1.0",
-    "@rainbow-robotics/preview-host": "^0.1.0",
+    "@rainbow-robotics/muscat-plugin-kit": "__RB_VERSION__",
+    "@rainbow-robotics/preview-host": "__RB_VERSION__",
+    "@vitejs/plugin-react": "^4.0.0",
     "typescript": "^5.8.0",
-    "vite": "^6.4.1"
+    "vite": "^6.0.0"
   }
 }

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

@@ -0,0 +1,88 @@
+"""
+Muscat plugin backend — __PLUGIN_NAME__
+
+Run with:
+  muscat-pk dev:back
+  python main.py
+
+This template uses the high-level Rainbow Python SDK instead of wiring the
+transport layer directly.
+"""
+
+import time
+from typing import Any
+
+from rainbow.rb_sdk import RBManipulateSDK, RBPluginCall
+
+
+PLUGIN_NAME = "__PLUGIN_NAME__"
+
+plugin = RBPluginCall()
+
+
+@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.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
+
+
+def move_j_example():
+    """
+    Example: use other robot SDKs from the same backend.
+
+    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 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")
+
+
+if __name__ == "__main__":
+    main()

package/cli/templates/common/requirements.txt

@@ -0,0 +1,4 @@
+rainbow-rb-sdk==0.0.9.dev43
+rainbow-rb-flat-buffers==0.0.9.dev43
+rainbow-rb-zenoh==0.0.9.dev43
+requests==2.34.2

package/cli/templates/common/tsconfig.json

@@ -9,5 +9,5 @@
     "noEmit": true,
     "lib": ["DOM", "DOM.Iterable", "ESNext"]
   },
-  "include": ["src"]
+  "include": ["ui"]
 }

package/cli/templates/common/{src → ui}/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");
         }}
       />
     </>