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

package/cli/bin/muscat-pk.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // muscat-pk — Muscat plugin developer CLI.
 // Subcommands: new, build, pack, dev, dev:ui, dev:back, update, sdk.
+import { log } from "../src/util.mjs";
 import { runNew } from "../src/new.mjs";
 import { runBuild } from "../src/build.mjs";
 import { runPack } from "../src/pack.mjs";
@@ -67,7 +68,8 @@ async function main() {
         process.exitCode = 1;
     }
   } catch (err) {
-    console.error(`\n✖ ${err?.message || err}`);
+    console.error();
+    log.error(err?.message || String(err));
     process.exitCode = 1;
   }
 }

package/cli/src/build.mjs

@@ -8,11 +8,12 @@
 // The plugin author's `@rainbow-robotics/plugin-ui` and React imports are left external.
 // Muscat/robot and preview-host provide those modules through a sandbox import
 // map, so plugin ZIPs do not carry the UI runtime.
-import { cpSync, copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { findPluginRoot, hasBin, log } from "./util.mjs";
+import { assertManifest } from "./manifest.mjs";
 
 // Find a usable node binary (for running vite as subprocess).
 function findNodeBin() {
@@ -174,6 +175,7 @@ export const SANDBOX_HTML = `<!doctype html>
 
 export async function buildPlugin({ root, minify = false } = {}) {
   const pluginRoot = root ?? findPluginRoot();
+  assertManifest(pluginRoot);
   const distDir = resolve(pluginRoot, "dist");
   rmSync(distDir, { recursive: true, force: true });
   mkdirSync(distDir, { recursive: true });
@@ -196,6 +198,13 @@ export async function buildPlugin({ root, minify = false } = {}) {
     cpSync(assetsSrc, resolve(distDir, "assets"), { recursive: true });
   }
 
+  // README.md and README.[lang].md → dist/
+  for (const f of readdirSync(pluginRoot)) {
+    if (/^README(\.[a-z]{2}(-[A-Z]{2})?)?\.md$/i.test(f)) {
+      copyFileSync(resolve(pluginRoot, f), resolve(distDir, f));
+    }
+  }
+
   // Backend runtime files — copy entire py/ into dist/, then requirements.txt from root.
   const pySrc = resolve(pluginRoot, "py");
   if (existsSync(pySrc)) {

package/cli/src/devBack.mjs

@@ -8,6 +8,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { existsSync, readFileSync, watch } from "node:fs";
 import { resolve } from "node:path";
 import { detectPythonCmd, hasBin, findPluginRoot, log, venvPython } from "./util.mjs";
+import { readManifest as readManifestSchema, validateManifest } from "./manifest.mjs";
 import {
   ROS2_DEV_IMAGE,
   assertDockerReady,
@@ -146,8 +147,16 @@ function runRos2(root) {
   process.on("SIGTERM", cleanup);
 }
 
+function warnManifest(root) {
+  const manifest = readManifestSchema(root);
+  if (!manifest || Object.keys(manifest).length === 0) return;
+  const errors = validateManifest(manifest);
+  for (const e of errors) log.warn(`manifest.json: ${e}`);
+}
+
 export async function runDevBack() {
   const root = findPluginRoot();
+  warnManifest(root);
   const type = manifestRuntime(root);
   if (type === "ros2") return runRos2(root);
   return runPython(root);

package/cli/src/manifest.mjs

@@ -0,0 +1,160 @@
+// manifest.mjs — manifest.json schema definition and validation
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export const CONTRIBUTION_POINTS = ["program.command", "toolbar", "move.rnb"];
+const ICON_SIZES = ["16", "48", "128"];
+const RUNTIME_TYPES = ["none", "python", "ros2"];
+const ROS_CLIENTS = ["rclpy", "rclcpp"];
+const I18N_LANGS = ["ko", "en", "ja", "zh", "vi", "th", "es"];
+
+function validateI18nLabel(value, field, errors) {
+  if (value === undefined || value === null) {
+    errors.push(`${field} is required`);
+    return;
+  }
+  if (typeof value === "string") return;
+  if (typeof value === "object") {
+    if (typeof value.en !== "string" || value.en.length === 0)
+      errors.push(`${field}: "en" is required when using object form`);
+    const unknown = Object.keys(value).filter((k) => !I18N_LANGS.includes(k));
+    if (unknown.length > 0)
+      errors.push(`${field}: unsupported language key(s) — ${unknown.map((k) => `"${k}"`).join(", ")} (allowed: ${I18N_LANGS.join(", ")})`);
+    return;
+  }
+  errors.push(`${field}: must be a string or { en (required), ko, ja, zh, vi, th, es }`);
+}
+
+export function readManifest(root) {
+  const path = resolve(root, "manifest.json");
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function validateIcons(icons, errors) {
+  if (icons === undefined || icons === null) {
+    errors.push("icons is required");
+    return;
+  }
+  if (typeof icons === "string") {
+    if (!icons.toLowerCase().endsWith(".svg"))
+      errors.push(`icons: non-SVG images (PNG, JPG, etc.) must use the { "16": "...", "48": "...", "128": "..." } object form`);
+  } else if (typeof icons === "object") {
+    const missing = ICON_SIZES.filter((s) => typeof icons[s] !== "string" || icons[s].length === 0);
+    if (missing.length > 0)
+      errors.push(`icons: missing size(s) ${missing.map((s) => `"${s}"`).join(", ")} — all three (16, 48, 128) are required for image files`);
+  } else {
+    errors.push(`icons: must be a string (SVG path) or { "16", "48", "128" } object (PNG/JPG)`);
+  }
+}
+
+function validateRuntime(runtime, errors) {
+  if (runtime === undefined || runtime === null) {
+    errors.push("runtime is required");
+    return;
+  }
+  if (typeof runtime !== "object") {
+    errors.push("runtime must be an object");
+    return;
+  }
+  if (!RUNTIME_TYPES.includes(runtime.type))
+    errors.push(`runtime.type must be one of ${RUNTIME_TYPES.map((t) => `"${t}"`).join(" | ")}`);
+  if (runtime.type === "python" && !runtime.entry)
+    errors.push("runtime.entry is required for python runtime");
+  if (runtime.type === "ros2") {
+    if (!runtime.package) errors.push("runtime.package is required for ros2 runtime");
+    if (!runtime.launch) errors.push("runtime.launch is required for ros2 runtime");
+    if (!ROS_CLIENTS.includes(runtime.rosClient))
+      errors.push(`runtime.rosClient must be one of ${ROS_CLIENTS.map((c) => `"${c}"`).join(" | ")}`);
+  }
+}
+
+function validateCommandInfo(info, prefix, errors) {
+  if (typeof info.name !== "string" || info.name.length === 0)
+    errors.push(`${prefix}.commandInfo.name is required`);
+  if (typeof info.icon !== "string" || info.icon.length === 0)
+    errors.push(`${prefix}.commandInfo.icon is required`);
+  if (info.iconClassName !== undefined && typeof info.iconClassName !== "string")
+    errors.push(`${prefix}.commandInfo.iconClassName must be a string`);
+  if (info.funcName !== undefined && typeof info.funcName !== "string")
+    errors.push(`${prefix}.commandInfo.funcName must be a string`);
+  if (info.args !== undefined && (typeof info.args !== "object" || Array.isArray(info.args)))
+    errors.push(`${prefix}.commandInfo.args must be an object`);
+  for (const key of ["disabled", "syncGroupId", "disableCopy", "disableDelete", "requireChildren", "requireParent"]) {
+    if (info[key] !== undefined && typeof info[key] !== "boolean")
+      errors.push(`${prefix}.commandInfo.${key} must be a boolean`);
+  }
+  for (const key of ["allowChildren", "allowParents", "notAllowChildren"]) {
+    if (info[key] !== undefined && (!Array.isArray(info[key]) || info[key].some((v) => typeof v !== "string")))
+      errors.push(`${prefix}.commandInfo.${key} must be a string[]`);
+  }
+  if (info.childrenCommand !== undefined && typeof info.childrenCommand !== "string")
+    errors.push(`${prefix}.commandInfo.childrenCommand must be a string`);
+}
+
+function validateContributes(contributes, errors) {
+  if (!Array.isArray(contributes) || contributes.length === 0) {
+    errors.push("contributes is required and must be a non-empty array");
+    return;
+  }
+  if (!contributes.some((c) => c.point === "toolbar"))
+    errors.push(`contributes: at least one "toolbar" entry is required`);
+
+  const uiValues = contributes.map((c) => c.ui).filter(Boolean);
+  const duplicateUi = uiValues.filter((v, i) => uiValues.indexOf(v) !== i);
+  if (duplicateUi.length > 0)
+    errors.push(`contributes: "ui" values must be unique across all entries (duplicates: ${[...new Set(duplicateUi)].map((v) => `"${v}"`).join(", ")})`);
+
+  contributes.forEach((c, i) => {
+    validateI18nLabel(c.label, `contributes[${i}].label`, errors);
+    if (c.point === "program.command") {
+      if (!c.commandInfo)
+        errors.push(`contributes[${i}]: "commandInfo" is required when point is "program.command"`);
+      else
+        validateCommandInfo(c.commandInfo, `contributes[${i}]`, errors);
+    }
+  });
+}
+
+/**
+ * Validate manifest.json. Returns an array of error messages (empty = valid).
+ */
+export function validateManifest(manifest) {
+  const errors = [];
+
+  if (typeof manifest !== "object" || manifest === null)
+    return ["manifest.json is not a valid JSON object"];
+
+  for (const key of ["id", "name", "version", "minMuscatVersion"]) {
+    if (typeof manifest[key] !== "string" || manifest[key].length === 0)
+      errors.push(`"${key}" is required`);
+  }
+  if (typeof manifest.author !== "string")
+    errors.push(`"author" is required (empty string is allowed)`);
+  validateI18nLabel(manifest.description, "description", errors);
+
+  validateIcons(manifest.icons, errors);
+  validateRuntime(manifest.runtime, errors);
+  validateContributes(manifest.contributes, errors);
+
+  return errors;
+}
+
+/**
+ * Read and validate manifest.json. Throws if any errors are found.
+ */
+export function assertManifest(root) {
+  const manifest = readManifest(root);
+  if (manifest === null)
+    throw new Error("manifest.json parse failed — check JSON syntax");
+  if (Object.keys(manifest).length === 0)
+    return manifest;
+  const errors = validateManifest(manifest);
+  if (errors.length > 0)
+    throw new Error(`manifest.json errors:\n${errors.map((e) => `  • ${e}`).join("\n")}`);
+  return manifest;
+}

package/cli/src/util.mjs

@@ -79,14 +79,16 @@ 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(`${ORANGE}⚠${RESET}`, ...m.map(s => `${ORANGE}${s}${RESET}`)),
+  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}`)),
 };
 
 export function humanSize(bytes) {

package/cli/templates/common/README.md

@@ -17,12 +17,14 @@ muscat-pk pack       # build a distributable ZIP
 
 ```
 __PLUGIN_DIR__/
-├─ src/
+├─ 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
-├─ main.py              # backend (Python or ROS2)
+├─ README.md            # this file (copied to dist/ on build)
 └─ requirements.txt     # Python deps (auto-pinned to latest on pack)
 ```
 
@@ -30,7 +32,7 @@ __PLUGIN_DIR__/
 
 ---
 
-## Frontend (`src/content.tsx`)
+## Frontend (`ui/content.tsx`)
 
 ### useRb() hook
 
@@ -97,12 +99,11 @@ connect(App);
 
 ---
 
-## Backend (`main.py`)
+## Backend (`py/main.py`)
 
 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.
+`muscat-pk dev` starts the local Socket.IO bridge; `py/main.py` should contain plugin
+logic only and must not start its own server.
 
 ### Python plugin
 
@@ -148,7 +149,6 @@ if __name__ == "__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
@@ -173,30 +173,116 @@ class __PLUGIN_CLASS__Node(Node):
 
 ```jsonc
 {
-  "id": "com.example.my-plugin",   // unique plugin ID (reverse-domain recommended)
+  // unique plugin ID — reverse-domain format recommended
+  "id": "com.example.my-plugin",
   "name": "My Plugin",
   "version": "1.0.0",
-  "minAppVersion": "2.0.0",
-  "icon": "assets/icon.svg",
+
+  // 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" },
 
   "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" }
+    // 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
+    }
   ],
 
-  // "python" | "ros2"
+  // "none" | "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 |
+| 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 (empty string is fine)
+- `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
+- `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-pk pack`. Muscat displays the file matching the user's locale,
+falling back to `README.md` if none matches.
 
 ---
 
@@ -211,13 +297,11 @@ numpy==1.26.4
 opencv-python
 ```
 
-Then just run `muscat-pk dev` or `muscat-pk dev:back` — dependencies are installed automatically on every startup:
+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`.
 
 ---
@@ -240,8 +324,9 @@ muscat-pk type change --to python # ros2 → python
 muscat-pk pack
 ```
 
-- Builds `src/content.tsx` → `dist/content.js`
+- Builds `ui/content.tsx` → `dist/content.js`
 - Pins `requirements.txt` to latest versions (stable-only on `main` branch)
+- Copies `assets/`, `manifest.json`, and all `README*.md` files to `dist/`
 - ROS2: runs `colcon build` inside the Jazzy container; includes `ros2_ws/install/`
 - Output: `__PLUGIN_DIR__-{version}.zip`
 
@@ -249,10 +334,15 @@ ZIP layout:
 
 ```
 __PLUGIN_DIR__-1.0.0.zip
-├─ dist/             # built UI
-├─ main.py
-├─ requirements.txt  # pinned
-└─ ros2_ws/install/  # ROS2 only
+├─ dist/
+│   ├─ content.js        # built UI
+│   ├─ manifest.json
+│   ├─ assets/
+│   ├─ README.md
+│   └─ README.ko.md      # if present
+├─ py/
+│   └─ main.py
+└─ requirements.txt      # pinned
 ```
 
 ---

package/cli/templates/common/manifest.json

@@ -2,16 +2,38 @@
   "id": "__PLUGIN_ID__",
   "name": "__PLUGIN_NAME__",
   "version": "1.0.0",
-  "minAppVersion": "2.0.0",
-  "icon": "assets/icon.svg",
+  "minMuscatVersion": "1.0.0",
+  "author": "",
+  "description": {
+    "ko": "",
+    "en": ""
+  },
+  "icons": "assets/icon.svg",
   "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": "program.command",
       "icon": "assets/icon.svg",
+      "label": { "ko": "__PLUGIN_NAME__", "en": "__PLUGIN_NAME__" },
+      "ui": "program/content",
+      "commandInfo": {
+        "name": "__PLUGIN_NAME__",
+        "icon": "assets/icon.svg",
+        "funcName": "plugin.run",
+        "args": {}
+      }
+    },
+    {
+      "point": "toolbar",
+      "icon": "assets/icon.svg",
+      "label": { "ko": "__PLUGIN_NAME__", "en": "__PLUGIN_NAME__" },
+      "ui": "content",
       "opens": "popover"
+    },
+    {
+      "point": "move.rnb",
+      "icon": "assets/icon.svg",
+      "label": { "ko": "__PLUGIN_NAME__", "en": "__PLUGIN_NAME__" },
+      "ui": "move/content"
     }
   ],
   "runtime": { "type": "__RUNTIME_TYPE__", "entry": "main.py" }

package/package.json

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