@rainbow-robotics/muscat-plugin-kit 1.10.1-dev.1 → 1.10.1

package/cli/README.md

@@ -1,274 +1,274 @@
-# @rainbow-robotics/muscat-plugin-kit (`muscat-pk`)
-
-CLI to scaffold, build, and preview Muscat plugins.
-
-Install/use it the same way an external plugin author will:
-
-```bash
-npm i -g @rainbow-robotics/muscat-plugin-kit
-muscat-pk new my-plugin
-```
-
-```bash
-muscat-pk new my-plugin [--type python|cpp|ros2|ros2-cpp] [--pm npm|yarn|pnpm|bun] [--yes]
-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 in a Docker container (python / cpp / ros2)
-muscat-pk dev         # dev:ui + dev:back
-muscat-pk storybook   # browse the bundled rb-components Storybook subset
-muscat-pk mcp         # start an MCP server (stdio) exposing rb-components/design-token/SDK docs to AI agents
-muscat-pk update      # update @rainbow-robotics/muscat-plugin-kit and @rainbow-robotics/plugin-ui
-muscat-pk uninstall   # remove muscat-pk itself (npm global or S3 binary)
-muscat-pk sdk list | sdk update [version]   # manage rainbow-rb-sdk (python)
-muscat-pk version     # print the installed CLI version (-v / --version too)
-muscat-pk completion zsh   # print a shell completion script (bash | zsh | fish | powershell)
-```
-
-## Backend ports
-
-If a plugin backend opens a TCP server, declare it in `manifest.json`:
-
-```json
-{
-  "ports": [28600, 28601]
-}
-```
-
-`ports` is optional and accepts only `number[]`; ranges or objects are not
-accepted. External plugin backend ports are reserved for `28600-28999`.
-`muscat-pk dev` and `muscat-pk dev:back` validate the manifest before start and
-then watch the container: **any listening TCP port that is not declared stops
-the backend**, whatever its number. Since a port outside `28600-28999` cannot be
-declared, it cannot be opened either — otherwise it would slip past both this
-check and the robot's install-time conflict check.
-
-The kit's own dev ports (plugin gateway `10000`, the Zenoh dev peer port) are
-excluded from that check.
-
-Under `muscat-pk dev` the backend shares the local Muscat container's network, so
-declared ports are published to `127.0.0.1` from that container. A declared port
-that is already busy on the host is skipped with a warning.
-
-Known robot/industrial/internal ports such as `502`, `4840`, `5170-5179`,
-`8000-8999`, `10000`, `2222`, `30004`, `34964`, `44818`, `50000-50005`,
-and `50051` are reserved and must not be used by external plugins.
-
-## Backend runtimes
-
-`manifest.json` selects one runtime:
-
-| runtime | source | notes |
-|---|---|---|
-| `{ "type": "none" }` | — | UI-only plugin; no backend container |
-| `{ "type": "python", "entry": "main.py" }` | `py/` | Uses `rainbow.rb_sdk.RBPluginCall` for UI/backend messaging; `plugin.router` exposes external endpoints (`common/plugin/{id}/{path}`, needs sdk ≥ 0.0.9.dev5 on the robot; the dev bridge only registers routes — external calls need a running `common`) |
-| `{ "type": "cpp", "entry": "<executable name>" }` | `cpp/` | Built with CMake in Docker against the C++ SDK (apt `rainbow-rb-sdk-dev`, `find_package(rb_sdk)`, dynamic link) |
-| `{ "type": "ros2", "rosClient": "rclpy", ... }` | `ros2_ws/` | ROS2 Python node; may use Python SDK alongside ROS2 APIs |
-| `{ "type": "ros2", "rosClient": "rclcpp", ... }` | `ros2_ws/` | ROS2 C++ node built with colcon/CMake, links the C++ SDK like `cpp` |
-
-All non-`none` runtimes run in Docker during `muscat-pk dev:back`, `muscat-pk
-dev`, and build/export flows so development matches the robot environment.
-
-## JavaScript dependencies
-
-`muscat-pk build` runs the plugin project's own Vite build. Vite resolves imports
-from installed `node_modules`; it does not care whether a package is listed under
-`dependencies` or `devDependencies`, but the package must be installed.
-
-Do not run a production-only install such as `npm install --omit=dev` before
-building a plugin UI, because build tools like `vite`, `typescript`,
-`tailwindcss`, `@tailwindcss/vite`, `sass`, or `less` are usually
-`devDependencies`.
-
-The scaffold keeps this split:
-
-| package kind | examples | why |
-|---|---|---|
-| `dependencies` | `@rainbow-robotics/plugin-ui`, UI libraries imported by plugin source | Author-facing APIs used by `ui/*.tsx` |
-| `devDependencies` | `vite`, `typescript`, `tailwindcss`, `@tailwindcss/vite`, `sass`, `less` | Build/dev tools needed before `dist/*.js` is produced |
-
-The built plugin ZIP does not include `package.json` or `node_modules`. For
-production, Muscat provides `@rainbow-robotics/plugin-ui`, React, and ReactDOM
-through the host import map; plugin UI build output imports those as host
-externals.
-
-## Plugin styles
-
-`muscat()` auto-loads plugin styles from `ui/style.{css,scss,sass,less}` or
-`ui/styles.{css,scss,sass,less}` for every UI entry, and from
-`ui/{entry}.{css,scss,sass,less}` for a matching entry-specific file. Authors do
-not need to import CSS from every `.tsx` entry.
-
-The scaffold enables Tailwind in the plugin's own `vite.config.ts`; those
-Tailwind dependencies live in the plugin package, while `muscat()` injects the
-generated CSS into the plugin JS bundle so dynamic host imports do not need a
-separate CSS file.
-
-Built CSS selectors are scoped under the current plugin id
-(`[data-muscat-plugin-id="..."]`), so Tailwind utilities or plugin styles do not
-rewrite the host page or another plugin. CSS-in-JS libraries are allowed too,
-but global styles (for example Emotion `Global`) remain the author's
-responsibility to scope.
-
-### Tailwind
-
-New plugins include Tailwind by default:
-
-```ts
-import { defineConfig } from "vite";
-import tailwindcss from "@tailwindcss/vite";
-import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite";
-
-export default defineConfig({
-  plugins: [tailwindcss(), muscat()],
-});
-```
-
-The default `ui/style.css` uses Tailwind theme/utilities only, not preflight:
-
-```css
-@layer theme, utilities;
-
-@import "tailwindcss/theme.css" layer(theme);
-@import "tailwindcss/utilities.css" layer(utilities);
-
-@source "./**/*.{ts,tsx}";
-```
-
-### SCSS, Sass, and Less
-
-Install the preprocessor package in the plugin project, then create one of the
-auto-loaded style files.
-
-```bash
-npm i -D sass
-```
-
-```scss
-/* ui/style.scss */
-$accent: #3b82f6;
-
-.panel {
-  border: 1px solid color-mix(in srgb, $accent 40%, transparent);
-
-  &__title {
-    color: $accent;
-  }
-}
-```
-
-For Less, install `less` and use `ui/style.less`.
-
-### Emotion
-
-Emotion dependencies may be in `dependencies` or `devDependencies`; Vite can
-bundle them when they are installed and imported by the plugin.
-
-For `styled`, no Vite config change is needed:
-
-```bash
-npm i @emotion/react @emotion/styled
-```
-
-```tsx
-import styled from "@emotion/styled";
-
-const Panel = styled.div({
-  display: "grid",
-  gap: 12,
-});
-```
-
-For Emotion's `css` prop, pass React plugin options through `muscat()` and add
-`jsxImportSource` to `tsconfig.json`:
-
-```bash
-npm i @emotion/react @emotion/styled
-npm i -D @emotion/babel-plugin
-```
-
-```ts
-// vite.config.ts
-import { defineConfig } from "vite";
-import tailwindcss from "@tailwindcss/vite";
-import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite";
-
-export default defineConfig({
-  plugins: [
-    tailwindcss(),
-    muscat({
-      react: {
-        jsxImportSource: "@emotion/react",
-        babel: {
-          plugins: ["@emotion/babel-plugin"],
-        },
-      },
-    }),
-  ],
-});
-```
-
-```json
-{
-  "compilerOptions": {
-    "jsxImportSource": "@emotion/react"
-  }
-}
-```
-
-Emotion `Global` writes global CSS at runtime, so scope it manually or avoid it
-inside plugins.
-
-## How it fits together
-
-- **Install/CLI package** is `@rainbow-robotics/muscat-plugin-kit`.
-- **Author API** comes from `@rainbow-robotics/plugin-ui`. `build` keeps that package
-  external so robot/preview-host can provide the runtime.
-- **`build`** bundles plugin code into ESM while externalizing
-  `@rainbow-robotics/plugin-ui`, React, and ReactDOM.
-- **`dev:ui`** builds the plugin then serves it inside the bundled preview host
-  at `/plugin-dev` — a real mini-Muscat shell. Without a robot IP it needs a Muscat
-  on `localhost:3000` for program preview: `dev` / `dev:ui` reuse any container that
-  already publishes `:10000` (`muscat`, `muscat-dev`, …) and otherwise start
-  `muscat-pk-muscat` — the S3 runtime image (`muscat/main/muscat.zip`) running only the
-  `common` service from `muscat/main/version.json`, cached under `~/.muscat-pk/muscat/`.
-  It keeps running between runs (`docker rm -f muscat-pk-muscat` to stop);
-  `MUSCAT_PK_NO_LOCAL_MUSCAT=1` disables it.
-
-`create-muscat-plugin <dir>` is the bin alias for `muscat-pk new`.
-
-## Update check
-
-On `dev` / `dev:ui` the kit checks the registry for a newer published version and,
-if found, suggests `muscat-pk update`. It is non-blocking (≤2s) and silent when
-offline.
-
-- `RB_REGISTRY` — registry base URL (default `https://registry.npmjs.org`).
-- `MUSCAT_PK_NO_UPDATE_CHECK=1` — skip the check.
-
-## Local vs global install
-
-If the plugin project has its own `muscat-plugin-kit` in `node_modules`, the CLI
-delegates to it — so the CLI, the `vite` preset, and `preview-host` are always
-the one version the project pinned, no matter which `muscat-pk` you typed.
-
-`muscat-pk update` follows the same rule: run from a project's local install it
-updates only that project; add `--global` to also update the machine-wide CLI.
-`muscat-pk version` prints whichever copy actually ran.
-
-## Docker images
-
-Images are built only when missing, because `docker build` resolves the base
-image tag over the network on every run — even with all layers cached — which
-would break `dev` offline. Pre-seed an air-gapped machine with
-`docker save … | gzip` + `docker load`, or force a rebuild with
-`MUSCAT_PK_REBUILD_IMAGE=1`.
-
-The C++ images (`Dockerfile.cpp`, `Dockerfile.dev`) install `rainbow-rb-sdk-dev`
-from `https://rainbowrobotics.github.io/rb-sdk` (suite `dev`), pinned by the
-`RB_SDK_VERSION` build arg. Set `MUSCAT_PK_RB_SDK_VERSION=<version>` (with
-`MUSCAT_PK_REBUILD_IMAGE=1`) to match a robot running a different SDK version.
-
-On Linux the dev containers run as the invoking user (`--user`), so build output
-under `dist/` and `cpp/build-*` is not left root-owned.
-
-Full spec: [`docs/plugin-system/CREATE-CLI.md`](../../docs/plugin-system/CREATE-CLI.md).
+# @rainbow-robotics/muscat-plugin-kit (`muscat-pk`)
+
+CLI to scaffold, build, and preview Muscat plugins.
+
+Install/use it the same way an external plugin author will:
+
+```bash
+npm i -g @rainbow-robotics/muscat-plugin-kit
+muscat-pk new my-plugin
+```
+
+```bash
+muscat-pk new my-plugin [--type python|cpp|ros2|ros2-cpp] [--pm npm|yarn|pnpm|bun] [--yes]
+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 in a Docker container (python / cpp / ros2)
+muscat-pk dev         # dev:ui + dev:back
+muscat-pk storybook   # browse the bundled rb-components Storybook subset
+muscat-pk mcp         # start an MCP server (stdio) exposing rb-components/design-token/SDK docs to AI agents
+muscat-pk update      # update @rainbow-robotics/muscat-plugin-kit and @rainbow-robotics/plugin-ui
+muscat-pk uninstall   # remove muscat-pk itself (npm global or S3 binary)
+muscat-pk sdk list | sdk update [version]   # manage rainbow-rb-sdk (python)
+muscat-pk version     # print the installed CLI version (-v / --version too)
+muscat-pk completion zsh   # print a shell completion script (bash | zsh | fish | powershell)
+```
+
+## Backend ports
+
+If a plugin backend opens a TCP server, declare it in `manifest.json`:
+
+```json
+{
+  "ports": [28600, 28601]
+}
+```
+
+`ports` is optional and accepts only `number[]`; ranges or objects are not
+accepted. External plugin backend ports are reserved for `28600-28999`.
+`muscat-pk dev` and `muscat-pk dev:back` validate the manifest before start and
+then watch the container: **any listening TCP port that is not declared stops
+the backend**, whatever its number. Since a port outside `28600-28999` cannot be
+declared, it cannot be opened either — otherwise it would slip past both this
+check and the robot's install-time conflict check.
+
+The kit's own dev ports (plugin gateway `10000`, the Zenoh dev peer port) are
+excluded from that check.
+
+Under `muscat-pk dev` the backend shares the local Muscat container's network, so
+declared ports are published to `127.0.0.1` from that container. A declared port
+that is already busy on the host is skipped with a warning.
+
+Known robot/industrial/internal ports such as `502`, `4840`, `5170-5179`,
+`8000-8999`, `10000`, `2222`, `30004`, `34964`, `44818`, `50000-50005`,
+and `50051` are reserved and must not be used by external plugins.
+
+## Backend runtimes
+
+`manifest.json` selects one runtime:
+
+| runtime | source | notes |
+|---|---|---|
+| `{ "type": "none" }` | — | UI-only plugin; no backend container |
+| `{ "type": "python", "entry": "main.py" }` | `py/` | Uses `rainbow.rb_sdk.RBPluginCall` for UI/backend messaging; `plugin.router` exposes external endpoints (`common/plugin/{id}/{path}`, needs sdk ≥ 0.0.9.dev5 on the robot; the dev bridge only registers routes — external calls need a running `common`) |
+| `{ "type": "cpp", "entry": "<executable name>" }` | `cpp/` | Built with CMake in Docker against the C++ SDK (apt `rainbow-rb-sdk-dev`, `find_package(rb_sdk)`, dynamic link) |
+| `{ "type": "ros2", "rosClient": "rclpy", ... }` | `ros2_ws/` | ROS2 Python node; may use Python SDK alongside ROS2 APIs |
+| `{ "type": "ros2", "rosClient": "rclcpp", ... }` | `ros2_ws/` | ROS2 C++ node built with colcon/CMake, links the C++ SDK like `cpp` |
+
+All non-`none` runtimes run in Docker during `muscat-pk dev:back`, `muscat-pk
+dev`, and build/export flows so development matches the robot environment.
+
+## JavaScript dependencies
+
+`muscat-pk build` runs the plugin project's own Vite build. Vite resolves imports
+from installed `node_modules`; it does not care whether a package is listed under
+`dependencies` or `devDependencies`, but the package must be installed.
+
+Do not run a production-only install such as `npm install --omit=dev` before
+building a plugin UI, because build tools like `vite`, `typescript`,
+`tailwindcss`, `@tailwindcss/vite`, `sass`, or `less` are usually
+`devDependencies`.
+
+The scaffold keeps this split:
+
+| package kind | examples | why |
+|---|---|---|
+| `dependencies` | `@rainbow-robotics/plugin-ui`, UI libraries imported by plugin source | Author-facing APIs used by `ui/*.tsx` |
+| `devDependencies` | `vite`, `typescript`, `tailwindcss`, `@tailwindcss/vite`, `sass`, `less` | Build/dev tools needed before `dist/*.js` is produced |
+
+The built plugin ZIP does not include `package.json` or `node_modules`. For
+production, Muscat provides `@rainbow-robotics/plugin-ui`, React, and ReactDOM
+through the host import map; plugin UI build output imports those as host
+externals.
+
+## Plugin styles
+
+`muscat()` auto-loads plugin styles from `ui/style.{css,scss,sass,less}` or
+`ui/styles.{css,scss,sass,less}` for every UI entry, and from
+`ui/{entry}.{css,scss,sass,less}` for a matching entry-specific file. Authors do
+not need to import CSS from every `.tsx` entry.
+
+The scaffold enables Tailwind in the plugin's own `vite.config.ts`; those
+Tailwind dependencies live in the plugin package, while `muscat()` injects the
+generated CSS into the plugin JS bundle so dynamic host imports do not need a
+separate CSS file.
+
+Built CSS selectors are scoped under the current plugin id
+(`[data-muscat-plugin-id="..."]`), so Tailwind utilities or plugin styles do not
+rewrite the host page or another plugin. CSS-in-JS libraries are allowed too,
+but global styles (for example Emotion `Global`) remain the author's
+responsibility to scope.
+
+### Tailwind
+
+New plugins include Tailwind by default:
+
+```ts
+import { defineConfig } from "vite";
+import tailwindcss from "@tailwindcss/vite";
+import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite";
+
+export default defineConfig({
+  plugins: [tailwindcss(), muscat()],
+});
+```
+
+The default `ui/style.css` uses Tailwind theme/utilities only, not preflight:
+
+```css
+@layer theme, utilities;
+
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/utilities.css" layer(utilities);
+
+@source "./**/*.{ts,tsx}";
+```
+
+### SCSS, Sass, and Less
+
+Install the preprocessor package in the plugin project, then create one of the
+auto-loaded style files.
+
+```bash
+npm i -D sass
+```
+
+```scss
+/* ui/style.scss */
+$accent: #3b82f6;
+
+.panel {
+  border: 1px solid color-mix(in srgb, $accent 40%, transparent);
+
+  &__title {
+    color: $accent;
+  }
+}
+```
+
+For Less, install `less` and use `ui/style.less`.
+
+### Emotion
+
+Emotion dependencies may be in `dependencies` or `devDependencies`; Vite can
+bundle them when they are installed and imported by the plugin.
+
+For `styled`, no Vite config change is needed:
+
+```bash
+npm i @emotion/react @emotion/styled
+```
+
+```tsx
+import styled from "@emotion/styled";
+
+const Panel = styled.div({
+  display: "grid",
+  gap: 12,
+});
+```
+
+For Emotion's `css` prop, pass React plugin options through `muscat()` and add
+`jsxImportSource` to `tsconfig.json`:
+
+```bash
+npm i @emotion/react @emotion/styled
+npm i -D @emotion/babel-plugin
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import tailwindcss from "@tailwindcss/vite";
+import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite";
+
+export default defineConfig({
+  plugins: [
+    tailwindcss(),
+    muscat({
+      react: {
+        jsxImportSource: "@emotion/react",
+        babel: {
+          plugins: ["@emotion/babel-plugin"],
+        },
+      },
+    }),
+  ],
+});
+```
+
+```json
+{
+  "compilerOptions": {
+    "jsxImportSource": "@emotion/react"
+  }
+}
+```
+
+Emotion `Global` writes global CSS at runtime, so scope it manually or avoid it
+inside plugins.
+
+## How it fits together
+
+- **Install/CLI package** is `@rainbow-robotics/muscat-plugin-kit`.
+- **Author API** comes from `@rainbow-robotics/plugin-ui`. `build` keeps that package
+  external so robot/preview-host can provide the runtime.
+- **`build`** bundles plugin code into ESM while externalizing
+  `@rainbow-robotics/plugin-ui`, React, and ReactDOM.
+- **`dev:ui`** builds the plugin then serves it inside the bundled preview host
+  at `/plugin-dev` — a real mini-Muscat shell. Without a robot IP it needs a Muscat
+  on `localhost:3000` for program preview: `dev` / `dev:ui` reuse any container that
+  already publishes `:10000` (`muscat`, `muscat-dev`, …) and otherwise start
+  `muscat-pk-muscat` — the S3 runtime image (`muscat/main/muscat.zip`) running only the
+  `common` service from `muscat/main/version.json`, cached under `~/.muscat-pk/muscat/`.
+  It keeps running between runs (`docker rm -f muscat-pk-muscat` to stop);
+  `MUSCAT_PK_NO_LOCAL_MUSCAT=1` disables it.
+
+`create-muscat-plugin <dir>` is the bin alias for `muscat-pk new`.
+
+## Update check
+
+On `dev` / `dev:ui` the kit checks the registry for a newer published version and,
+if found, suggests `muscat-pk update`. It is non-blocking (≤2s) and silent when
+offline.
+
+- `RB_REGISTRY` — registry base URL (default `https://registry.npmjs.org`).
+- `MUSCAT_PK_NO_UPDATE_CHECK=1` — skip the check.
+
+## Local vs global install
+
+If the plugin project has its own `muscat-plugin-kit` in `node_modules`, the CLI
+delegates to it — so the CLI, the `vite` preset, and `preview-host` are always
+the one version the project pinned, no matter which `muscat-pk` you typed.
+
+`muscat-pk update` follows the same rule: run from a project's local install it
+updates only that project; add `--global` to also update the machine-wide CLI.
+`muscat-pk version` prints whichever copy actually ran.
+
+## Docker images
+
+Images are built only when missing, because `docker build` resolves the base
+image tag over the network on every run — even with all layers cached — which
+would break `dev` offline. Pre-seed an air-gapped machine with
+`docker save … | gzip` + `docker load`, or force a rebuild with
+`MUSCAT_PK_REBUILD_IMAGE=1`.
+
+The C++ images (`Dockerfile.cpp`, `Dockerfile.dev`) install `rainbow-rb-sdk-dev`
+from `https://rainbowrobotics.github.io/rb-sdk` (suite `dev`), pinned by the
+`RB_SDK_VERSION` build arg. Set `MUSCAT_PK_RB_SDK_VERSION=<version>` (with
+`MUSCAT_PK_REBUILD_IMAGE=1`) to match a robot running a different SDK version.
+
+On Linux the dev containers run as the invoking user (`--user`), so build output
+under `dist/` and `cpp/build-*` is not left root-owned.
+
+Full spec: [`docs/plugin-system/CREATE-CLI.md`](../../docs/plugin-system/CREATE-CLI.md).

package/cli/bin/create-muscat-plugin.mjs

@@ -1,8 +1,8 @@
-#!/usr/bin/env node
-// Thin alias: `npm create @rainbow/muscat-plugin <dir>` → `muscat-pk new <dir>`.
-import { runNew } from "../src/new.mjs";
-
-runNew(process.argv.slice(2)).catch((err) => {
-  console.error(`\n ✖ ${err?.message || err}`);
-  process.exit(1);
-});
+#!/usr/bin/env node
+// Thin alias: `npm create @rainbow/muscat-plugin <dir>` → `muscat-pk new <dir>`.
+import { runNew } from "../src/new.mjs";
+
+runNew(process.argv.slice(2)).catch((err) => {
+  console.error(`\n ✖ ${err?.message || err}`);
+  process.exit(1);
+});