@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.9 → 1.0.0

package/README.md

@@ -1,106 +1,170 @@
 # @rainbow-robotics/muscat-plugin-kit
 
-Muscat 플러그인 개발 CLI. 스캐폴딩, 빌드/팩, 개발 서버(UI + 백엔드)를 제공합니다.
+CLI for developing Muscat plugins. Provides scaffolding, build/pack, and dev servers (UI + backend).
 
-## 설치
+## Install
 
-### 방법 1 — npm (Node.js 20+ 필요)
+### Option 1 — npm (requires Node.js 20+)
 
 ```bash
-# 최신 stable
+# latest stable
 npm install -g @rainbow-robotics/muscat-plugin-kit
 
-# dev 채널 (최신 개발 빌드)
+# dev channel (latest dev build)
 npm install -g @rainbow-robotics/muscat-plugin-kit@dev
 
-# 특정 버전
+# specific version
 npm install -g @rainbow-robotics/muscat-plugin-kit@1.2.3
 ```
 
-### 방법 2 — 설치 스크립트 (Node.js 없어도 됨)
+### Option 2 — S3 install script (no Node.js required)
 
 macOS / Linux / WSL:
 
 ```bash
-# 최신 stable
-curl -fsSL https://raw.githubusercontent.com/rainbow-robotics/web-rainbow-ui/main/scripts/install-muscat-pk.sh | sh
+# latest stable
+curl -fsSL https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/install.sh | sh
 
-# dev 채널
-MUSCAT_PK_TAG=dev curl -fsSL https://raw.githubusercontent.com/rainbow-robotics/web-rainbow-ui/main/scripts/install-muscat-pk.sh | sh
+# dev channel
+curl -fsSL https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/install.sh | MUSCAT_PK_TAG=dev sh
 
-# 특정 버전
-MUSCAT_PK_TAG=1.2.3 curl -fsSL https://raw.githubusercontent.com/rainbow-robotics/web-rainbow-ui/main/scripts/install-muscat-pk.sh | sh
+# specific version
+curl -fsSL https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/install.sh | MUSCAT_PK_TAG=1.2.3 sh
 ```
 
 Windows PowerShell:
 
 ```powershell
-# 최신 stable
-irm https://raw.githubusercontent.com/rainbow-robotics/web-rainbow-ui/main/scripts/install-muscat-pk.ps1 | iex
+# latest stable
+irm https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/install.ps1 | iex
 
-# dev 채널
-$env:MUSCAT_PK_TAG="dev"; irm https://raw.githubusercontent.com/rainbow-robotics/web-rainbow-ui/main/scripts/install-muscat-pk.ps1 | iex
+# dev channel
+$env:MUSCAT_PK_TAG="dev"; irm https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/install.ps1 | iex
 ```
 
-> 설치 스크립트는 Node.js 20+가 있으면 npm을 우선 사용하고, 없으면 S3에서 self-contained 바이너리를 받습니다.
+> The install script uses npm when Node.js 20+ is present, otherwise it downloads a self-contained binary from S3.
 
-### 방법 3 — 바이너리 직접 다운로드
+### Option 3 — direct binary download
 
 ```
-https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/v{버전}/{바이너리}
+https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/v{version}/{binary}
+https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/stable/{binary}
+https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/dev/{binary}
 ```
 
-| OS | 파일 |
+| OS | File |
 |---|---|
 | Linux x64 | `muscat-pk-linux-x64` |
 | macOS ARM64 | `muscat-pk-darwin-arm64` |
+| macOS x64 | `muscat-pk-darwin-x64` |
 | Windows x64 | `muscat-pk-win-x64.exe` |
 
-채널 포인터:
+Channel pointers:
 
 ```
-# 최신 stable 버전 문자열
+# latest stable version string
 https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/latest-version.txt
 
-# 최신 dev 버전 문자열
+# latest dev version string
 https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/dev-version.txt
 ```
 
+### Uninstall
+
+Regardless of how it was installed, `muscat-pk` can remove itself:
+
+```bash
+muscat-pk uninstall
+```
+
+Manual removal:
+
+```bash
+# if installed via npm
+npm uninstall -g @rainbow-robotics/muscat-plugin-kit
+
+# if installed via the S3 binary (default macOS/Linux path)
+sudo rm -f /usr/local/bin/muscat-pk
+```
+
 ---
 
-## 빠른 시작
+## Quick start
 
 ```bash
-muscat-pk new my-plugin        # 플러그인 프로젝트 생성 (python 또는 ros2 선택)
+muscat-pk new my-plugin        # scaffold a plugin project (choose python / cpp / ros2 / ros2-cpp)
 cd my-plugin
 
-muscat-pk dev                  # UI + 백엔드 동시 실행
-muscat-pk dev:ui               # UI 미리보기만
-muscat-pk dev:back             # 백엔드만 (Python watchfiles / ROS2 Docker)
+muscat-pk dev                  # run UI + backend together
+muscat-pk dev:ui               # UI preview only
+muscat-pk dev:back             # backend only (Docker: python/cpp/ros2)
 
-muscat-pk build                # dist/ 빌드
-muscat-pk pack                 # 배포용 ZIP 생성
+muscat-pk build                # build dist/ and produce a distributable ZIP (skip the ZIP with --no-zip)
 ```
 
-## 명령어 목록
+## Command list
 
-| 명령 | 설명 |
+| Command | Description |
 |---|---|
-| `muscat-pk new [dir]` | 플러그인 프로젝트 스캐폴딩 |
-| `muscat-pk type change` | 백엔드 타입 전환 (python ↔ ros2) |
-| `muscat-pk build` | `src/content.tsx` → `dist/content.js` 빌드 |
-| `muscat-pk pack` | 빌드 후 배포용 ZIP 생성 |
-| `muscat-pk dev` | UI + 백엔드 동시 개발 서버 |
-| `muscat-pk dev:ui` | 미니 Muscat 미리보기 서버 |
-| `muscat-pk dev:back` | 백엔드 개발 서버 (hot-reload) |
-| `muscat-pk update` | kit + plugin-ui 최신 버전으로 업데이트 |
-| `muscat-pk sdk <list\|update>` | Python rainbow-rb-sdk 버전 관리 |
-
-## 패키지 역할
-
-| 패키지 | 역할 |
+| `muscat-pk new [dir]` | Scaffold a plugin project (also creates an IDE-only python `.venv`) |
+| `muscat-pk type change` | Switch backend type (`python` / `cpp` / `ros2` / `ros2-cpp`) |
+| `muscat-pk build` | Build `ui/*.tsx` → `dist/*.js` (one per `contributes[].ui` entry in the manifest) and produce a distributable ZIP |
+| `muscat-pk dev` | UI + backend dev server together |
+| `muscat-pk dev:ui` | Mini-Muscat preview server |
+| `muscat-pk dev:back` | Backend dev server (Docker, hot-reload) |
+| `muscat-pk storybook` | Browse the bundled rb-components Storybook |
+| `muscat-pk mcp` | Run an MCP server for AI coding agents (exposes rb-components/design-token/SDK docs) |
+| `muscat-pk update` | Update the kit + plugin-ui to the latest version |
+| `muscat-pk sdk <list\|update>` | Manage the Python `rainbow-rb-sdk` version |
+
+## IDE support (Python)
+
+`muscat-pk new` creates a `.venv` at the project root with `requirements.txt` installed. The real backend still runs in a Docker container — this `.venv` exists purely for editor linting (pylint/pyright).
+
+If it can't be created (no local Python 3 or `uv` found), scaffolding prints a warning and continues — Docker-based dev still works without it:
+
+```
+Could not create .venv (no local Python/uv?) — skipping, Docker dev still works.
+```
+
+Install `uv` (recommended) or a system Python 3.12, then re-run `muscat-pk new` (or `muscat-pk type change`) to create it.
+
+## AI coding agent setup (`muscat-pk mcp`)
+
+`muscat-pk mcp` runs an MCP server (stdio) that gives an AI coding agent grounded info about `rb-components`, design tokens, and the Python `rainbow-rb-sdk` — actual prop types, real Storybook examples, and live-introspected SDK signatures/docstrings, instead of the agent guessing from training data. Use it while working inside a plugin project scaffolded by `muscat-pk new`.
+
+### Claude Code
+
+Claude Code reads a project-scoped `.mcp.json` at the plugin's root:
+
+```json
+{
+  "mcpServers": {
+    "muscat": {
+      "command": "muscat-pk",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### Codex
+
+Codex has no project-scoped config file — it reads a single, per-user `~/.codex/config.toml`. Add:
+
+```toml
+[mcp_servers.muscat]
+command = "muscat-pk"
+args = ["mcp"]
+```
+
+You don't run `muscat-pk mcp` yourself either way — the agent spawns and manages it automatically once it's registered.
+
+## Package roles
+
+| Package | Role |
 |---|---|
-| `@rainbow-robotics/plugin-ui` | UI 런타임 계약: rb-* 엘리먼트, React 바인딩, sandbox connect |
-| `@rainbow-robotics/muscat-plugin-kit` | CLI, 템플릿, 빌드/팩, 미리보기 호스트 |
+| `@rainbow-robotics/plugin-ui` | UI runtime contract: React direct mount, `useRb()` context, host services |
+| `@rainbow-robotics/muscat-plugin-kit` | CLI, templates, build/pack, preview host |
 
-플러그인 ZIP에는 플러그인 코드와 에셋만 포함됩니다. `@rainbow-robotics/plugin-ui`, `react`, `react-dom`은 호스트(Muscat/로봇)의 import map에서 제공됩니다.
+A plugin ZIP only contains the plugin's own code and assets. `@rainbow-robotics/plugin-ui`, `react`, and `react-dom` are provided by the host's (Muscat/robot) import map.

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:
 
@@ -10,16 +10,202 @@ 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 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 (.venv + python main.py)
+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)
 ```
 
+## 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
+stop the backend if it opens an undeclared managed TCP listen port.
+
+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 |
+| `{ "type": "cpp", "entry": "<executable name>" }` | `cpp/` | Built with CMake in Docker; current template is a run skeleton |
+| `{ "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 |
+
+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`.

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

@@ -3,6 +3,6 @@
 import { runNew } from "../src/new.mjs";
 
 runNew(process.argv.slice(2)).catch((err) => {
-  console.error(`\n✖ ${err?.message || err}`);
+  console.error(`\n ✖ ${err?.message || err}`);
   process.exit(1);
 });

package/cli/bin/muscat-pk.mjs

@@ -1,16 +1,21 @@
 #!/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, uninstall, 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";
 import { runUpdate } from "../src/update.mjs";
+import { runUninstall } from "../src/uninstall.mjs";
 import { runSdk } from "../src/sdk.mjs";
 import { runType } from "../src/type.mjs";
-import { runPreview } from "../src/preview.mjs";
+import { runStorybook } from "../src/storybook.mjs";
+// mcp.mjs is dynamically imported below — it pulls in the MCP SDK + a full
+// TypeScript program, and every other command would pay that cold-start cost
+// on every invocation otherwise (see ros2.mjs/python.mjs/cpp.mjs for the same
+// pattern in build.mjs).
 
 const [, , cmd, ...args] = process.argv;
 
@@ -19,15 +24,16 @@ const HELP = `muscat-pk — Muscat plugin kit
 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)
-  dev              Run dev:ui and dev:back together
+  new [dir]        Scaffold a new plugin project (prompts: author, email, description, type, front-package-manager)
+  type change      Switch backend type (python | cpp | ros2-python | ros2-cpp)
+  build            Build + lock deps + vendor wheels + zip (--no-zip: skip zip, --no-lock: skip python lock/vendor, --arch amd64|arm64|both)
+  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)
-  preview          Preview against a real Muscat server (prompts for robot IP)
+  storybook        Browse the bundled rb-components Storybook (--port <n>, --rebuild)
+  mcp              Start an MCP server (stdio) exposing rb-components/rb SDK docs to AI agents
   update           Update @rainbow-robotics/muscat-plugin-kit and @rainbow-robotics/plugin-ui
+  uninstall        Remove the installed muscat-pk CLI (npm global or S3 binary)
   sdk <list|update [version]>   Manage the python rainbow-rb-sdk version
 
 Run "muscat-pk <command> --help" for details.`;
@@ -41,18 +47,22 @@ 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":
         return await runDevUi(args);
       case "dev:back":
         return await runDevBack(args);
-      case "preview":
-        return await runPreview(args);
+      case "storybook":
+        return await runStorybook(args);
+      case "mcp": {
+        const { runMcp } = await import("../src/mcp.mjs");
+        return await runMcp(args);
+      }
       case "update":
         return await runUpdate(args);
+      case "uninstall":
+        return await runUninstall(args);
       case "sdk":
         return await runSdk(args);
       case undefined:
@@ -67,7 +77,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/bundle-templates.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Pre-build step: serialise cli/templates/** into cli/src/templates-embedded.mjs
+// so that `bun build --compile` can embed them without needing the filesystem.
+import { readdirSync, readFileSync, writeFileSync, statSync } from "node:fs";
+import { resolve, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(fileURLToPath(import.meta.url), "..");
+const out = resolve(root, "src/templates-embedded.mjs");
+
+const files = {};
+function walk(baseDir, prefix) {
+  for (const name of readdirSync(baseDir)) {
+    const full = resolve(baseDir, name);
+    const key = prefix + name;
+    if (statSync(full).isDirectory()) { walk(full + "/", key + "/"); continue; }
+    files[key] = readFileSync(full, "base64");
+  }
+}
+walk(resolve(root, "templates") + "/", "");
+walk(resolve(root, "docker") + "/", "docker/");
+
+writeFileSync(out,
+  `// AUTO-GENERATED by cli/bundle-templates.mjs — do not edit.\n` +
+  `// ponytail: generated at publish time; not tracked in git.\n` +
+  `export const TEMPLATES = ${JSON.stringify(files)};\n`
+);
+console.log(`bundled ${Object.keys(files).length} template files → src/templates-embedded.mjs`);

package/cli/docker/Dockerfile.bridge

@@ -0,0 +1,17 @@
+# Socket.IO bridge container — the frontend (preview-host) and the backend
+# container rendezvous here during `muscat-pk dev`.
+#   - frontend (host)  → published port localhost:10000
+#   - backend container → shares this container's netns (--network container:),
+#                         so it reaches the bridge at localhost:10000 too
+# Build context is the `cli/` dir so it can copy src/socketBridge.mjs.
+FROM node:20-slim
+LABEL com.rainbow-robotics.muscat-pk="true"
+
+WORKDIR /bridge
+COPY docker/bridge-package.json package.json
+RUN npm install --omit=dev --no-audit --no-fund
+
+COPY src/socketBridge.mjs ./socketBridge.mjs
+
+EXPOSE 10000
+CMD ["node", "socketBridge.mjs"]

package/cli/docker/Dockerfile.cpp

@@ -0,0 +1,22 @@
+# Dev/build container for the pure C++ plugin back end.
+# Matches the Muscat robot backend OS (Ubuntu 24.04) so the compiled binary
+# is ABI-compatible with the robot. Used by `muscat-pk dev:back` and `build`
+# — NOT shipped in the plugin ZIP.
+FROM ubuntu:24.04
+LABEL com.rainbow-robotics.muscat-pk="true"
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      build-essential \
+      cmake \
+    && rm -rf /var/lib/apt/lists/*
+
+# TODO(cpp-sdk): install the rainbow cpp SDK (dev package) here, pinned to the
+# robot's version, so plugins build/link against the same SDK as production.
+# Plan: apt package + dynamic link (the robot provides the .so at runtime;
+# we do NOT bundle it into the plugin binary). e.g.:
+#   RUN apt-get update && apt-get install -y rainbow-cpp-sdk-dev=<robot-version> \
+#       && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /plugin
+
+CMD ["bash"]

package/cli/docker/Dockerfile.dev

@@ -2,6 +2,7 @@
 # Matches the Muscat robot backend: ROS2 Jazzy + Python 3.12 (Ubuntu 24.04).
 # Used by `muscat-pk dev:back` — NOT shipped in the plugin ZIP.
 FROM ros:jazzy-ros-base
+LABEL com.rainbow-robotics.muscat-pk="true"
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
       python3-pip \

package/cli/docker/Dockerfile.python

@@ -0,0 +1,20 @@
+# Dev/build container for the Python plugin back end.
+# Matches the Muscat robot backend: Ubuntu 24.04 + Python 3.12.
+# Used by `muscat-pk dev:back` (hot-reload) and `muscat-pk build` (lock + wheel vendor).
+# NOT shipped in the plugin ZIP — the robot installs deps from dist/wheels/ offline.
+FROM ubuntu:24.04
+LABEL com.rainbow-robotics.muscat-pk="true"
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      python3 \
+      python3-pip \
+    && rm -rf /var/lib/apt/lists/* \
+    && pip3 install uv==0.8.18 --break-system-packages
+
+# TODO(cpp-sdk): the Python SDK is a pybind wrapper over the cpp SDK, so the
+# cpp SDK shared lib must be present for the python module to load. Install the
+# rainbow cpp SDK (apt, pinned to the robot's version) here once it exists.
+
+WORKDIR /plugin
+
+CMD ["bash"]

package/cli/docker/bridge-package.json

@@ -0,0 +1,8 @@
+{
+  "name": "muscat-pk-bridge",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "socket.io": "^4.8.1"
+  }
+}

package/cli/prepack.mjs

@@ -0,0 +1,10 @@
+// Runs on `npm publish` / `yarn npm publish` (and `npm pack`) via the "prepack"
+// lifecycle hook. Builds the bundled Storybook (foundations + muscat) and stages
+// it into cli/storybook-dist so it ships inside the published muscat-pk and
+// `muscat-pk storybook` works from an external install.
+//
+// In the monorepo this runs the real build; outside it (re-packing an already
+// published copy) buildStorybook() no-ops and the pre-staged dist is used.
+import { buildStorybook } from "./src/storybook.mjs";
+
+buildStorybook();