@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.23 → 0.1.2-dev.25

package/cli/src/socketBridge.mjs

@@ -1,7 +1,14 @@
 import { createServer } from "node:http";
 import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import { Server } from "socket.io";
-import { log } from "./util.mjs";
+
+// Self-contained logger — this module also runs standalone inside the bridge
+// Docker container, where ./util.mjs is not available.
+const log = {
+  step: (...m) => console.log("›", ...m),
+  warn: (...m) => console.warn("⚠", ...m),
+};
 
 const DEFAULT_ACTION_TIMEOUT_MS = 10_000;
 
@@ -114,3 +121,9 @@ export function startSocketBridge({ port = 10000, host = "0.0.0.0" } = {}) {
     });
   });
 }
+
+// When executed directly (inside the bridge Docker container), start the server.
+if (process.argv[1] && process.argv[1] === fileURLToPath(import.meta.url)) {
+  const port = Number(process.env.PORT) || 10000;
+  startSocketBridge({ port });
+}

package/cli/src/type.mjs

@@ -1,13 +1,21 @@
 // muscat-pk type change — switch an existing plugin's backend type.
-//   python ↔ ros2.  python→ros2 adds the ros2_ws/ overlay; ros2→python flips
-//   the manifest type and leaves ros2_ws/ in place (never deletes user code).
+//   python | cpp | ros2 (rclpy) | ros2-cpp (rclcpp).
+//   Adds the matching backend overlay; never deletes existing user code
+//   (e.g. ros2_ws/ or cpp/ are left in place when switching away).
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { basename, resolve } from "node:path";
 import { findPluginRoot, log } from "./util.mjs";
-import { applyTokens, deriveNames, overlayRos2 } from "./new.mjs";
+import {
+  TYPE_CHOICES,
+  applyTokens,
+  deriveNames,
+  overlayCpp,
+  overlayRos2,
+  runtimeForChoice,
+} from "./new.mjs";
 
-const TYPES = ["python", "ros2"];
+const TYPES = Object.keys(TYPE_CHOICES);
 
 async function prompt(question, fallback) {
   if (!process.stdin.isTTY) return fallback;
@@ -23,44 +31,54 @@ function readManifest(root) {
   return { path, json: JSON.parse(readFileSync(path, "utf8")) };
 }
 
+// Derive the current `--type`-style key from a manifest runtime block.
+function currentTypeKey(runtime) {
+  if (runtime?.type === "ros2") return runtime.rosClient === "rclcpp" ? "ros2-cpp" : "ros2";
+  return runtime?.type ?? "python";
+}
+
 export async function runType(args) {
-  // accept `type change`, `type`, `type --to ros2`
+  // accept `type change`, `type`, `type --to ros2-cpp`
   const sub = args[0];
   const toFlagIdx = args.indexOf("--to");
   let to = toFlagIdx >= 0 ? args[toFlagIdx + 1] : undefined;
 
   const root = findPluginRoot();
   const { path, json } = readManifest(root);
-  const current = json.runtime?.type ?? "python";
+  const current = currentTypeKey(json.runtime);
 
   if (sub && sub !== "change") {
-    log.warn(`unknown subcommand '${sub}'. Usage: muscat-pk type change [--to python|ros2]`);
+    log.warn(`unknown subcommand '${sub}'. Usage: muscat-pk type change [--to python|cpp|ros2|ros2-cpp]`);
   }
 
   if (!to) {
     console.log(`\n현재 타입: ${current}`);
     console.log("변경할 타입을 선택하세요:");
     console.log("  1) Python");
-    console.log("  2) ROS2(rclpy)");
-    const choice = await prompt("\n선택 [1/2]: ", "");
-    to = choice === "1" ? "python" : choice === "2" ? "ros2" : undefined;
+    console.log("  2) C++");
+    console.log("  3) ROS2 (rclpy / Python)");
+    console.log("  4) ROS2 (rclcpp / C++)");
+    const choice = await prompt("\n선택 [1/2/3/4]: ", "");
+    to = { "1": "python", "2": "cpp", "3": "ros2", "4": "ros2-cpp" }[choice];
   }
 
   if (!TYPES.includes(to)) {
-    throw new Error(`invalid type. choose python or ros2.`);
+    throw new Error(`invalid type. choose python | cpp | ros2 | ros2-cpp.`);
   }
   if (to === current) {
     log.info(`already '${current}' — nothing to change.`);
     return;
   }
 
-  if (to === "ros2") {
-    const { slug, pluginName, pluginClass, pluginId } = deriveNames(root);
+  const runtimeChoice = TYPE_CHOICES[to];
+  const { slug, pluginName, pluginClass, pluginId } = deriveNames(root);
+
+  if (runtimeChoice.type === "ros2") {
     if (existsSync(resolve(root, "ros2_ws"))) {
       log.warn("ros2_ws/ already exists — keeping it, only flipping manifest type.");
     } else {
-      log.step("adding ros2_ws/ overlay");
-      overlayRos2(root, slug);
+      log.step(`adding ros2_ws/ overlay (${runtimeChoice.rosClient})`);
+      overlayRos2(root, slug, runtimeChoice.rosClient);
       applyTokens(root, {
         __PLUGIN_ID__: pluginId,
         __PLUGIN_NAME__: pluginName,
@@ -69,14 +87,28 @@ export async function runType(args) {
         __RUNTIME_TYPE__: "ros2",
       });
     }
+  } else if (runtimeChoice.type === "cpp") {
+    if (existsSync(resolve(root, "cpp"))) {
+      log.warn("cpp/ already exists — keeping it, only flipping manifest type.");
+    } else {
+      log.step("adding cpp/ overlay");
+      overlayCpp(root);
+      applyTokens(root, {
+        __PLUGIN_ID__: pluginId,
+        __PLUGIN_NAME__: pluginName,
+        __PLUGIN_SLUG__: slug,
+        __PLUGIN_CLASS__: pluginClass,
+        __RUNTIME_TYPE__: "cpp",
+      });
+    }
   } else {
-    // ros2 → python
-    if (existsSync(resolve(root, "ros2_ws"))) {
-      log.warn("ros2_ws/ left in place (not deleted). Remove it manually if unused.");
+    // → python. Leave any ros2_ws/ or cpp/ in place (never delete user code).
+    if (existsSync(resolve(root, "ros2_ws")) || existsSync(resolve(root, "cpp"))) {
+      log.warn("existing backend dir left in place (not deleted). Remove it manually if unused.");
     }
   }
 
-  json.runtime = { ...json.runtime, type: to };
+  json.runtime = runtimeForChoice(runtimeChoice, slug);
   writeFileSync(path, JSON.stringify(json, null, 2) + "\n");
   log.ok(`${basename(root)} type: ${current} → ${to}`);
 }

package/cli/src/util.mjs

@@ -91,6 +91,16 @@ export const log = {
   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.");
+}
+
 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

@@ -8,7 +8,7 @@ A Muscat plugin project. Build, develop, and ship with `muscat-pk` CLI.
 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
+muscat-pk build      # build + distributable ZIP
 ```
 
 ---
@@ -25,7 +25,7 @@ __PLUGIN_DIR__/
 │   └─ 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 pack)
+└─ requirements.txt     # Python deps (auto-pinned to latest on build)
 ```
 
 > ROS2 plugins additionally include a `ros2_ws/` directory.
@@ -102,8 +102,9 @@ connect(App);
 ## Backend (`py/main.py`)
 
 The backend communicates with the frontend using `rainbow.rb_sdk.RBPluginCall`.
-`muscat-pk dev` starts the local Socket.IO bridge; `py/main.py` should contain plugin
-logic only and must not start its own server.
+`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
 
@@ -192,6 +193,13 @@ class __PLUGIN_CLASS__Node(Node):
   "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
     {
@@ -223,11 +231,26 @@ class __PLUGIN_CLASS__Node(Node):
     }
   ],
 
-  // "none" | "python" | "ros2"
+  // 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 |
@@ -258,9 +281,11 @@ class __PLUGIN_CLASS__Node(Node):
 
 **Validation rules:**
 - `id`, `name`, `version`, `minMuscatVersion` — required non-empty strings
-- `author` — required (empty string is fine)
+- `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"`
@@ -281,7 +306,7 @@ README.ja.md     # Japanese
 ```
 
 All `README*.md` files found at the project root are automatically copied to `dist/` on
-`muscat-pk build` / `muscat-pk pack`. Muscat displays the file matching the user's locale,
+`muscat-pk build`. Muscat displays the file matching the user's locale,
 falling back to `README.md` if none matches.
 
 ---
@@ -297,36 +322,36 @@ numpy==1.26.4
 opencv-python
 ```
 
-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`
+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` / `muscat-pk pack` only **pins** versions in `requirements.txt` — it does not run `pip install`.
+> `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 ros2   # python → ros2
-muscat-pk type change --to python # ros2 → python
+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
 ```
 
-> `ros2_ws/` is not deleted when switching back to python. Remove it manually if no longer needed.
+> Existing backend dirs (`ros2_ws/`, `cpp/`) are not deleted when switching away. Remove them manually if no longer needed.
 
 ---
 
 ## Shipping
 
 ```bash
-muscat-pk pack
+muscat-pk build            # build + ZIP
+muscat-pk build --no-zip   # build only, no ZIP
 ```
 
-- Builds `ui/content.tsx` → `dist/content.js`
+- Builds `ui/content.tsx` → `dist/content.js` (minified)
 - Pins `requirements.txt` to latest versions (stable-only on `main` branch)
-- Copies `assets/`, `manifest.json`, and all `README*.md` files to `dist/`
+- 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`
 
@@ -339,10 +364,10 @@ __PLUGIN_DIR__-1.0.0.zip
 │   ├─ manifest.json
 │   ├─ assets/
 │   ├─ README.md
-│   └─ README.ko.md      # if present
-├─ py/
-│   └─ main.py
-└─ requirements.txt      # pinned
+│   ├─ README.ko.md      # if present
+│   ├─ main.py           # from py/
+│   └─ requirements.txt  # pinned
+└─ ros2_ws/install/      # ROS2 only
 ```
 
 ---
@@ -353,8 +378,7 @@ __PLUGIN_DIR__-1.0.0.zip
 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
+muscat-pk build      # build → dist/ + distributable ZIP (--no-zip to skip)
 ```
 
 ```bash

package/cli/templates/common/manifest.json

@@ -3,12 +3,15 @@
   "name": "__PLUGIN_NAME__",
   "version": "1.0.0",
   "minMuscatVersion": "1.0.0",
-  "author": "",
+  "author": "__PLUGIN_AUTHOR__",
+  "email": "__PLUGIN_EMAIL__",
   "description": {
     "ko": "",
     "en": ""
   },
   "icons": "assets/icon.svg",
+  "targetModels": "all",
+  "targetCategorys": "all",
   "contributes": [
     {
       "point": "program.command",

package/cli/templates/common/requirements.txt

@@ -1,4 +1,4 @@
-rainbow-rb-sdk==0.0.9.dev42
-rainbow-rb-flat-buffers==0.0.9.dev42
-rainbow-rb-zenoh==0.0.9.dev42
+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/cpp/cpp/CMakeLists.txt

@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 3.16)
+project(__PLUGIN_SLUG__ CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# The executable name must match runtime.entry in manifest.json.
+add_executable(__PLUGIN_SLUG__ main.cpp)
+
+# TODO(cpp-sdk): link the rainbow cpp SDK dynamically (the robot provides the
+# .so at runtime — do NOT bundle/static-link it). Once the SDK ships an apt
+# package with CMake config, enable:
+#   find_package(rainbow_cpp_sdk REQUIRED)
+#   target_link_libraries(__PLUGIN_SLUG__ PRIVATE rainbow::cpp_sdk)

package/cli/templates/cpp/cpp/main.cpp

@@ -0,0 +1,25 @@
+// __PLUGIN_NAME__ — C++ plugin back end.
+//
+// The C++ plugin SDK is not available yet, so this is a build/run skeleton.
+// Once the SDK lands, connect to the plugin gateway here (the host exposes it
+// at the RB_PLUGIN_GATEWAY / RB_PLUGIN_ID environment variables) and wire up
+// pub / sub / serve, mirroring the Python rainbow.rb_sdk.RBPluginCall API.
+
+#include <chrono>
+#include <cstdlib>
+#include <iostream>
+#include <thread>
+
+int main() {
+  const char* plugin_id = std::getenv("RB_PLUGIN_ID");
+  std::cout << "[__PLUGIN_NAME__] backend ready"
+            << (plugin_id ? std::string(" (id=") + plugin_id + ")" : "")
+            << std::endl;
+
+  // TODO: connect to the plugin gateway and register handlers once the
+  //       C++ SDK is available. For now, just keep the process alive.
+  while (true) {
+    std::this_thread::sleep_for(std::chrono::seconds(1));
+  }
+  return 0;
+}

package/cli/templates/ros2-cpp/ros2_ws/src/__PLUGIN_SLUG__/CMakeLists.txt

@@ -0,0 +1,17 @@
+cmake_minimum_required(VERSION 3.16)
+project(__PLUGIN_SLUG__)
+
+if(NOT CMAKE_CXX_STANDARD)
+  set(CMAKE_CXX_STANDARD 17)
+endif()
+
+find_package(ament_cmake REQUIRED)
+find_package(rclcpp REQUIRED)
+
+add_executable(__PLUGIN_SLUG___node src/node.cpp)
+ament_target_dependencies(__PLUGIN_SLUG___node rclcpp)
+
+install(TARGETS __PLUGIN_SLUG___node
+  DESTINATION lib/${PROJECT_NAME})
+
+ament_package()

package/cli/templates/ros2-cpp/ros2_ws/src/__PLUGIN_SLUG__/package.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0"?>
+<package format="3">
+  <name>__PLUGIN_SLUG__</name>
+  <version>0.0.1</version>
+  <description>__PLUGIN_NAME__ ROS2 node (rclcpp)</description>
+  <maintainer email="todo@example.com">maintainer</maintainer>
+  <license>Proprietary</license>
+  <buildtool_depend>ament_cmake</buildtool_depend>
+  <depend>rclcpp</depend>
+  <export><build_type>ament_cmake</build_type></export>
+</package>

package/cli/templates/ros2-cpp/ros2_ws/src/__PLUGIN_SLUG__/src/node.cpp

@@ -0,0 +1,22 @@
+// __PLUGIN_NAME__ — ROS2 node (rclcpp).
+//
+// The node is launched with `--ros-args -r __ns:=/{slug}` automatically by
+// dev:back. ROS2 topics are bridged to the plugin communication layer, so a
+// plain rclcpp node is all you need — relative topic names get the namespace
+// prefix applied automatically.
+#include "rclcpp/rclcpp.hpp"
+
+class __PLUGIN_CLASS__Node : public rclcpp::Node {
+public:
+  __PLUGIN_CLASS__Node() : Node("__PLUGIN_SLUG___node") {
+    RCLCPP_INFO(this->get_logger(), "__PLUGIN_NAME__ node started");
+    // create publishers / subscribers / services here
+  }
+};
+
+int main(int argc, char** argv) {
+  rclcpp::init(argc, argv);
+  rclcpp::spin(std::make_shared<__PLUGIN_CLASS__Node>());
+  rclcpp::shutdown();
+  return 0;
+}

package/package.json

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

package/cli/src/pack.mjs

@@ -1,58 +0,0 @@
-// muscat-pk pack — build, then create a distributable ZIP with a size report.
-import { execSync } from "node:child_process";
-import { existsSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
-import { basename, resolve } from "node:path";
-import { buildPlugin, exportRos2Build, pinRequirements } from "./build.mjs";
-import { findPluginRoot, humanSize, log } from "./util.mjs";
-
-function dirSize(dir) {
-  let total = 0;
-  for (const entry of readdirSync(dir)) {
-    const full = resolve(dir, entry);
-    const st = statSync(full);
-    total += st.isDirectory() ? dirSize(full) : st.size;
-  }
-  return total;
-}
-
-export async function runPack() {
-  const pluginRoot = findPluginRoot();
-  log.step("pinning requirements.txt to latest PyPI versions");
-  await pinRequirements(pluginRoot);
-  await buildPlugin({ root: pluginRoot, minify: true });
-  await exportRos2Build(pluginRoot);
-
-  const manifest = JSON.parse(
-    readFileSync(resolve(pluginRoot, "manifest.json"), "utf8"),
-  );
-  const zipName = `${basename(pluginRoot)}-${manifest.version || "0.0.0"}.zip`;
-  const zipPath = resolve(pluginRoot, zipName);
-  rmSync(zipPath, { force: true });
-
-  // dist/ already contains main.py, requirements.txt, manifest.json, assets/.
-  const entries = ["dist"];
-  if (existsSync(resolve(pluginRoot, "ros2_ws/install"))) {
-    entries.push("ros2_ws/install");
-  }
-
-  log.step(`packing ${entries.join(", ")} → ${zipName}`);
-  try {
-    execSync(`zip -r -q "${zipPath}" ${entries.map((e) => `"${e}"`).join(" ")}`, {
-      cwd: pluginRoot,
-      stdio: "inherit",
-    });
-  } catch {
-    throw new Error("`zip` not found. Install zip or pack manually.");
-  }
-
-  const zipBytes = statSync(zipPath).size;
-  log.ok(`${zipName}   ${humanSize(zipBytes)}`);
-  for (const e of entries) {
-    const full = resolve(pluginRoot, e);
-    const size = statSync(full).isDirectory() ? dirSize(full) : statSync(full).size;
-    log.info(`  ├─ ${e}   ${humanSize(size)}`);
-  }
-  log.warn(
-    "robot install checks free space via GET /plugin/capacity (507 if low).",
-  );
-}