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

package/cli/README.md

@@ -1,6 +1,6 @@
 # @rainbow-robotics/muscat-plugin-kit (`muscat-pk`)
 
-CLI to scaffold, build, preview and pack Muscat plugins.
+CLI to scaffold, build, and preview Muscat plugins.
 
 Install/use it the same way an external plugin author will:
 
@@ -11,8 +11,7 @@ muscat-pk new my-plugin
 
 ```bash
 muscat-pk new my-plugin [--type sdk|ros2|ui] [--pm npm|yarn|pnpm|bun] [--yes]
-muscat-pk build       # src/content.tsx -> dist/content.js (+ manifest, sandbox, assets)
-muscat-pk pack        # build (minified) + distributable ZIP with a size report
+muscat-pk build       # ui/content.tsx -> dist/ (minified) + distributable ZIP (--no-zip to skip)
 muscat-pk dev:ui      # preview the plugin in a mini-Muscat (preview-host)
 muscat-pk dev:back    # run the back end (.venv + python main.py)
 muscat-pk dev         # dev:ui + dev:back

package/cli/bin/muscat-pk.mjs

@@ -1,10 +1,9 @@
 #!/usr/bin/env node
 // muscat-pk — Muscat plugin developer CLI.
-// Subcommands: new, build, pack, dev, dev:ui, dev:back, update, sdk.
+// Subcommands: new, build, 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";
 import { runDevUi } from "../src/devUi.mjs";
 import { runDevBack } from "../src/devBack.mjs";
 import { runDev } from "../src/dev.mjs";
@@ -22,8 +21,7 @@ Usage: muscat-pk <command> [options]
 Commands:
   new [dir]        Scaffold a new plugin project
   type change      Switch backend type (python <-> ros2)
-  build            Build src/content.tsx -> dist/content.js (+ manifest, assets)
-  pack             Build then create a distributable ZIP (with size report)
+  build            Build ui/content.tsx -> dist/ and zip into a distributable ZIP (--no-zip to skip)
   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)
@@ -42,8 +40,6 @@ async function main() {
         return await runType(args);
       case "build":
         return await runBuild(args);
-      case "pack":
-        return await runPack(args);
       case "dev":
         return await runDev(args);
       case "dev:ui":

package/cli/src/build.mjs

@@ -1,5 +1,6 @@
-// muscat-pk build — bundle src/content.tsx into dist/content.js and stage
-// manifest.json and assets/ for distribution.
+// muscat-pk build — bundle ui/content.tsx into dist/content.js, stage
+// manifest.json and assets/ for distribution, and zip dist/ into a
+// distributable ZIP (skip with --no-zip).
 //
 // sandbox.html is generated by the CLI — plugin authors never manage it.
 // The import map always reflects the current plugin-ui entry set, so users
@@ -8,11 +9,11 @@
 // 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, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, 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 { basename, dirname, resolve } from "node:path";
+import { execSync, spawnSync } from "node:child_process";
+import { findPluginRoot, hasBin, humanSize, log } from "./util.mjs";
 import { assertManifest } from "./manifest.mjs";
 
 // Find a usable node binary (for running vite as subprocess).
@@ -117,7 +118,7 @@ async function latestPypiVersion(pkg, { stableOnly = false } = {}) {
 }
 
 // Pin unpinned (no version specifier) entries in requirements.txt to the
-// latest PyPI release. Runs on explicit `build`/`pack` only — keeps the shipped
+// latest PyPI release. Runs on explicit `build` only — keeps the shipped
 // plugin reproducible without churning the source file on every dev rebuild.
 // stableOnly=true is used on main-branch builds to avoid shipping dev versions.
 export async function pinRequirements(root, { stableOnly = false } = {}) {
@@ -219,14 +220,55 @@ export async function buildPlugin({ root, minify = false } = {}) {
   return { pluginRoot, distDir };
 }
 
+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;
+}
+
+// Zip dist/ (+ ros2_ws/install) into a distributable ZIP with a size report.
+function packZip(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 });
+
+  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).");
+}
+
 export async function runBuild(args) {
-  const minify = args.includes("--minify");
+  const noZip = args.includes("--no-zip");
   const root = findPluginRoot();
   if (!args.includes("--no-pin")) {
     const stableOnly = isMainBranch();
     log.step(`pinning requirements.txt to latest ${stableOnly ? "stable " : ""}PyPI versions`);
     await pinRequirements(root, { stableOnly });
   }
-  await buildPlugin({ root, minify });
+  const { pluginRoot } = await buildPlugin({ root, minify: true });
   await exportRos2Build(root);
+  if (!noZip) packZip(pluginRoot);
 }

package/cli/src/devUi.mjs

@@ -13,6 +13,10 @@ 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");
 
+// Dev builds go to a throwaway dir, not dist/ — dist/ is reserved for
+// build/pack output (the shippable artifact).
+const DEV_OUT = ".muscat-dev";
+
 function findNodeBin() {
   if (typeof Bun === "undefined") return process.execPath;
   for (const c of ["node", "node20", "node18"]) {
@@ -52,14 +56,14 @@ function findPreviewHostRoot() {
   return CACHE_ROOT;
 }
 
-// Write sandbox.html + copy manifest into dist/ (vite doesn't generate these).
+// Write sandbox.html + copy manifest into the dev out dir (vite doesn't generate these).
 function stageDevAssets(pluginRoot) {
-  const distDir = resolve(pluginRoot, "dist");
-  mkdirSync(distDir, { recursive: true });
-  writeFileSync(resolve(distDir, "sandbox.html"), SANDBOX_HTML, "utf8");
+  const outDir = resolve(pluginRoot, DEV_OUT);
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(resolve(outDir, "sandbox.html"), SANDBOX_HTML, "utf8");
   const manifestSrc = resolve(pluginRoot, "manifest.json");
-  if (existsSync(manifestSrc)) copyFileSync(manifestSrc, resolve(distDir, "manifest.json"));
-  return distDir;
+  if (existsSync(manifestSrc)) copyFileSync(manifestSrc, resolve(outDir, "manifest.json"));
+  return outDir;
 }
 
 // Resolve vite bin path from the plugin root, hoisting-aware.
@@ -79,8 +83,8 @@ function spawnViteWatch(pluginRoot, node) {
   const viteBin = findViteBin(pluginRoot);
   if (!node || !viteBin || !existsSync(viteBin)) return null;
 
-  log.step("vite build --watch (ui/content.tsx → dist/content.js)");
-  return spawn(node, [viteBin, "build", "--watch", "--mode", "development"], {
+  log.step(`vite build --watch (ui/content.tsx → ${DEV_OUT}/content.js)`);
+  return spawn(node, [viteBin, "build", "--watch", "--mode", "development", "--outDir", DEV_OUT], {
     cwd: pluginRoot,
     stdio: "inherit",
   });
@@ -106,14 +110,14 @@ export async function runDevUi(args = []) {
 
   await checkKitUpdate();
   const pluginRoot = findPluginRoot();
-  const distDir = stageDevAssets(pluginRoot);
+  const outDir = stageDevAssets(pluginRoot);
 
   const node = findNodeBin();
   const viteProc = spawnViteWatch(pluginRoot, node);
 
   if (viteProc) {
     log.step("waiting for initial vite build…");
-    await waitForInitialBuild(distDir);
+    await waitForInitialBuild(outDir);
   } else {
     log.warn("vite not found — UI will not be bundled. Run `npm install` in the plugin project.");
   }
@@ -133,7 +137,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)],
+    [serveEntry, "--plugin", outDir, "--port", String(port)],
     { stdio: "inherit" },
   );
 

package/cli/src/manifest.mjs

@@ -7,6 +7,7 @@ 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"];
+const TARGET_CATEGORIES = ["manipulate", "amr", "rby1", "vision"];
 
 function validateI18nLabel(value, field, errors) {
   if (value === undefined || value === null) {
@@ -15,7 +16,7 @@ function validateI18nLabel(value, field, errors) {
   }
   if (typeof value === "string") return;
   if (typeof value === "object") {
-    if (typeof value.en !== "string" || value.en.length === 0)
+    if (typeof value.en !== "string")
       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)
@@ -133,8 +134,30 @@ export function validateManifest(manifest) {
     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)`);
+  if (typeof manifest.author !== "string" || manifest.author.length === 0)
+    errors.push(`"author" is required`);
+
+  const hasModels = manifest.targetModels !== undefined && manifest.targetModels !== null;
+  const hasCategorys = manifest.targetCategorys !== undefined && manifest.targetCategorys !== null;
+  if (!hasModels && !hasCategorys) {
+    errors.push(`"targetModels" or "targetCategorys" is required`);
+  } else {
+    if (hasModels) {
+      if (manifest.targetModels !== "all" && (!Array.isArray(manifest.targetModels) || manifest.targetModels.length === 0))
+        errors.push(`"targetModels" must be "all" or a non-empty array of model strings`);
+      else if (Array.isArray(manifest.targetModels) && manifest.targetModels.some((m) => typeof m !== "string"))
+        errors.push(`"targetModels": all entries must be strings`);
+    }
+    if (hasCategorys) {
+      if (manifest.targetCategorys !== "all" && (!Array.isArray(manifest.targetCategorys) || manifest.targetCategorys.length === 0))
+        errors.push(`"targetCategorys" must be "all" or a non-empty array`);
+      else if (Array.isArray(manifest.targetCategorys)) {
+        const invalid = manifest.targetCategorys.filter((c) => !TARGET_CATEGORIES.includes(c));
+        if (invalid.length > 0)
+          errors.push(`"targetCategorys": invalid value(s) ${invalid.map((c) => `"${c}"`).join(", ")} — allowed: ${TARGET_CATEGORIES.join(", ")}`);
+      }
+    }
+  }
   validateI18nLabel(manifest.description, "description", errors);
 
   validateIcons(manifest.icons, errors);

package/cli/src/new.mjs

@@ -149,7 +149,7 @@ export async function runNew(args) {
   // gitignore (templates can't ship a literal .gitignore via npm reliably)
   writeFileSync(
     resolve(target, ".gitignore"),
-    ["node_modules", "dist", ".venv", "*.zip", "ros2_ws/install", ""].join("\n"),
+    ["node_modules", "dist", ".muscat-dev", ".venv", "*.zip", "ros2_ws/install", ""].join("\n"),
   );
 
   if (!opts["no-install"]) {
@@ -197,7 +197,7 @@ export async function runNew(args) {
   log.ok(`created ${targetName} (type: ${type}, pm: ${pm})`);
   log.info(`\n  cd ${targetName}`);
   log.info(`  muscat-pk dev      # preview in mini-Muscat + back end`);
-  log.info(`  muscat-pk pack     # build a distributable ZIP\n`);
+  log.info(`  muscat-pk build    # build + distributable ZIP\n`);
 
   // ── post-scaffold environment warnings ───────────────────────────────────
   const noNode = !hasBin("node");

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.
@@ -192,6 +192,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
     {
@@ -258,9 +265,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 +290,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.
 
 ---
@@ -302,7 +311,7 @@ Run `muscat-pk dev` or `muscat-pk dev:back` — dependencies are installed autom
 - **Python plugin**: installed into `.venv` via `pip install -r requirements.txt`
 - **ROS2 plugin**: installed inside the Docker container via `pip install -r requirements.txt`
 
-> `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`.
 
 ---
 
@@ -321,12 +330,13 @@ muscat-pk type change --to python # ros2 → python
 ## 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 +349,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 +363,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

@@ -9,6 +9,8 @@
     "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainbow-robotics/muscat-plugin-kit",
-  "version": "0.1.2-dev.23",
+  "version": "0.1.2-dev.24",
   "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.24",
     "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).",
-  );
-}