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

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,214 @@ 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
 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 update      # update @rainbow-robotics/muscat-plugin-kit and @rainbow-robotics/plugin-ui
+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, plugin-ui and preview-host; lists old-API UI code to fix
+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`.
@@ -28,7 +226,15 @@ muscat-pk sdk list | sdk update [version]   # manage rainbow-rb-sdk (python)
 - **`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 with no robot/back end.
+  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 the
+  `common` service from `muscat/main/version.json`, cached under `~/.muscat-pk/muscat/`.
+  `dev --sim <model>` adds the services the model needs (log + manipulate / rby1), opens
+  common's Zenoh on the `muscat-pk` network, and starts simulators there (`cli/src/sim.mjs`).
+  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`.
 
@@ -41,4 +247,30 @@ 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

@@ -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,36 +1,108 @@
 #!/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, storybook, mcp, update, uninstall, sdk, version.
+import { readFileSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { color, compareKitVersions, kitVersion, log, resolveLocalCliBin } 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 { runUpdate, runUpdateCheck } 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";
+import { runCompletion } from "../src/completion.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;
+// 실행 중인 게 글로벌/바이너리인데 cwd 상위에 로컬 설치가 있으면 그쪽으로 넘긴다.
+// vite preset / preview-host / manifest 검증이 항상 프로젝트가 고정한 버전과
+// 맞아야 해서다 (버전이 안 맞으면 "module not found" 류 에러로 터진다).
+function readVersion(binPath) {
+  try {
+    return JSON.parse(readFileSync(resolve(binPath, "../../../package.json"), "utf8")).version;
+  } catch {
+    return "";
+  }
+}
+
+const isBinaryMode = typeof Bun !== "undefined";
+
+// 바이너리에는 package.json 이 없다 — 컴파일 시 임베드한 버전을 쓴다.
+if (isBinaryMode && !process.env.MUSCAT_PK_VERSION) {
+  process.env.MUSCAT_PK_VERSION = (await import("../src/templates-embedded.mjs")).KIT_VERSION;
+}
 
-const HELP = `muscat-pk — Muscat plugin kit
+(function delegateToLocalInstall() {
+  try {
+    const localBin = resolveLocalCliBin();
+    if (!localBin) return;
+    // 바이너리는 node_modules 안의 mjs일 수 없으니 자기 자신 비교 생략.
+    // (import.meta.url이 /$bunfs/ 가상 경로라 realpath가 throw하기도 한다.)
+    if (!isBinaryMode && realpathSync(localBin) === realpathSync(fileURLToPath(import.meta.url))) return;
+    // Say so — otherwise an outdated local copy silently answers instead, and
+    // its missing/renamed subcommands look like the CLI is broken.
+    const localVersion = readVersion(localBin);
+    // An older local copy can't update a project correctly — it doesn't know what changed since
+    // it was published. Run this CLI's update instead, still touching this project only.
+    if (process.argv[2] === "update" && localVersion && compareKitVersions(localVersion, kitVersion()) < 0) {
+      console.error(color.dim(`[muscat-pk] project's local install (v${localVersion}) is older — updating it with this CLI (v${kitVersion()})`));
+      process.env.MUSCAT_PK_UPDATE_PROJECT_ONLY = "1";
+      return;
+    }
+    console.error(
+      color.dim(`[muscat-pk] using this project's local install${localVersion ? ` (v${localVersion})` : ""}: ${localBin}`),
+    );
+    // Bun 바이너리의 execPath는 스크립트 인자를 실행하지 않으니 PATH의 node로 넘긴다.
+    const runtime = isBinaryMode ? "node" : process.execPath;
+    const r = spawnSync(runtime, [localBin, ...process.argv.slice(2)], { stdio: "inherit" });
+    if (r.error) {
+      log.warn(`Failed to run local install via ${runtime} (${r.error.code}); continuing with this binary.`);
+      return;
+    }
+    process.exit(r.status ?? 0);
+  } catch {
+    // realpath 실패 등 — 그냥 지금 프로세스로 계속.
+  }
+})();
 
-Usage: muscat-pk <command> [options]
+const [, , cmd, ...args] = process.argv;
 
-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
-  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)
-  update           Update @rainbow-robotics/muscat-plugin-kit and @rainbow-robotics/plugin-ui
-  sdk <list|update [version]>   Manage the python rainbow-rb-sdk version
+const commandRow = (command, description) => `  ${color.cyan(command.padEnd(30))}${description}`;
+const option = (text) => color.yellow(text);
 
-Run "muscat-pk <command> --help" for details.`;
+function formatHelp() {
+  return [
+    `${color.bold("muscat-pk")} ${color.dim("— Muscat plugin kit")}`,
+    "",
+    `${color.bold("Usage:")} ${color.cyan("muscat-pk")} ${color.yellow("<command>")} ${color.dim("[options]")}`,
+    "",
+    color.bold("Commands:"),
+    commandRow("new [dir]", `Scaffold a new plugin project ${color.dim("(prompts: author, email, description, type, front-package-manager)")}`),
+    commandRow("type change", `Switch backend type ${color.dim("(python | cpp | ros2-python | ros2-cpp)")}`),
+    commandRow("build", `Build + lock deps + vendor wheels + zip ${color.dim(`(${option("--arch")} amd64|arm64|both)`)}`),
+    commandRow("dev", `Run a local Muscat runtime, dev:ui, and dev:back together ${color.dim(`(${option("--sim")} 500920|RBY2|rby1-a|rby1-m|rby1-ub)`)}`),
+    commandRow("dev:ui", `Preview the plugin in a mini-Muscat ${color.dim("(preview-host)")}`),
+    commandRow("dev:back", `Run the plugin back end ${color.dim("(python: watchfiles reload / ros2: Docker)")}`),
+    commandRow("storybook", `Browse the bundled rb-components Storybook ${color.dim(`(${option("--port")} <n>, ${option("--rebuild")})`)}`),
+    commandRow("mcp", `Start an MCP server ${color.dim("(stdio)")} exposing rb-components/rb SDK docs to AI agents ${color.dim(`(${option("--install")} codex: register in ~/.codex/config.toml)`)}`),
+    commandRow("update", `Update ${color.magenta("@rainbow-robotics/muscat-plugin-kit")}, ${color.magenta("@rainbow-robotics/plugin-ui")} and ${color.magenta("@rainbow-robotics/preview-host")} ${color.dim(`(local-only if run from a project's local install; ${option("--global")} also updates the global CLI)`)}`),
+    commandRow("uninstall", `Remove the installed ${color.cyan("muscat-pk")} CLI ${color.dim("(npm global or S3 binary)")}`),
+    commandRow("sdk <list|update [version]>", "Manage the python rainbow-rb-sdk version"),
+    commandRow("sim list", `List the robot simulators for ${option("dev --sim")}`),
+    commandRow("version", `Print the installed ${color.cyan("muscat-pk")} version`),
+    commandRow("completion [shell]", `Print a shell completion script ${color.dim("(bash | zsh | fish | powershell)")}`),
+    "",
+    `Run ${color.cyan("muscat-pk <command> --help")} for details.`,
+  ].join("\n");
+}
 
 async function main() {
   try {
@@ -41,34 +113,58 @@ 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": {
+        // Relay by default so `muscat-pk update` reaches a running session; --serve is the server.
+        if (args[0] !== "--serve" && args[0] !== "--install" && args[0] !== "install")
+          return (await import("../src/mcpProxy.mjs")).runMcpProxy();
+        const { runMcp, installMcp } = await import("../src/mcp.mjs");
+        if (args[0] === "--install" || args[0] === "install")
+          return installMcp(args[1]);
+        return await runMcp(args);
+      }
       case "update":
         return await runUpdate(args);
+      case "update:check": // internal: update runs it with the freshly installed local kit
+        return await runUpdateCheck(args);
+      case "uninstall":
+        return await runUninstall(args);
       case "sdk":
         return await runSdk(args);
+      case "sim":
+        if (args[0] !== "list") throw new Error("usage: muscat-pk sim list");
+        return (await import("../src/sim.mjs")).runSimList();
+      case "completion":
+        return await runCompletion(args);
+      case "version":
+      case "-v":
+      case "--version":
+        console.log(kitVersion());
+        return;
       case undefined:
       case "-h":
       case "--help":
       case "help":
-        console.log(HELP);
+        console.log(formatHelp());
         return;
       default:
         console.error(`Unknown command: ${cmd}\n`);
-        console.log(HELP);
+        console.log(formatHelp());
         process.exitCode = 1;
     }
   } catch (err) {
-    console.error(`\n✖ ${err?.message || err}`);
-    process.exitCode = 1;
+    console.error();
+    log.error(err?.message || String(err));
+    // exit, not exitCode: a failed dev:ui (e.g. Ctrl+C before vite was ready) leaves file watchers that
+    // would keep the process hanging.
+    process.exit(1);
   }
 }
 

package/cli/bundle-templates.mjs

@@ -0,0 +1,31 @@
+#!/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 } 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/");
+
+const { version } = JSON.parse(readFileSync(resolve(root, "../package.json"), "utf8"));
+
+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 KIT_VERSION = ${JSON.stringify(version)};\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.cpp

@@ -0,0 +1,28 @@
+# 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/*
+
+# Rainbow Robotics C++ SDK for find_package(rb_sdk). muscat-pk passes the version pinned in the
+# project's CMakeLists.txt (find_package(rb_sdk <ver> EXACT)); without a pin (ROS 2 rclpy, `muscat-pk mcp`
+# outside a project) the newest SDK is installed. Runtime and -dev are installed together at one version.
+ARG RB_SDK_VERSION=
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl \
+    && install -d /etc/apt/keyrings \
+    && curl -fsSL https://rainbowrobotics.github.io/rb-sdk/rb-sdk-apt-repo.gpg.key -o /etc/apt/keyrings/rb-sdk.asc \
+    && printf 'deb [signed-by=/etc/apt/keyrings/rb-sdk.asc] https://rainbowrobotics.github.io/rb-sdk %s main\n' stable dev > /etc/apt/sources.list.d/rb-sdk.list \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends "rainbow-rb-sdk${RB_SDK_VERSION:+=$RB_SDK_VERSION}" "rainbow-rb-sdk-dev${RB_SDK_VERSION:+=$RB_SDK_VERSION}" \
+    && rm -rf /var/lib/apt/lists/*
+
+
+WORKDIR /plugin
+
+CMD ["bash"]

package/cli/docker/Dockerfile.dev

@@ -2,12 +2,29 @@
 # 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 \
       python3-colcon-common-extensions \
     && rm -rf /var/lib/apt/lists/*
 
+# Rainbow Robotics C++ SDK for find_package(rb_sdk). muscat-pk passes the version pinned in the
+# project's CMakeLists.txt (find_package(rb_sdk <ver> EXACT)); without a pin (ROS 2 rclpy, `muscat-pk mcp`
+# outside a project) the newest SDK is installed. Runtime and -dev are installed together at one version.
+ARG RB_SDK_VERSION=
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl \
+    && install -d /etc/apt/keyrings \
+    && curl -fsSL https://rainbowrobotics.github.io/rb-sdk/rb-sdk-apt-repo.gpg.key -o /etc/apt/keyrings/rb-sdk.asc \
+    && printf 'deb [signed-by=/etc/apt/keyrings/rb-sdk.asc] https://rainbowrobotics.github.io/rb-sdk %s main\n' stable dev > /etc/apt/sources.list.d/rb-sdk.list \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends "rainbow-rb-sdk${RB_SDK_VERSION:+=$RB_SDK_VERSION}" "rainbow-rb-sdk-dev${RB_SDK_VERSION:+=$RB_SDK_VERSION}" \
+    && rm -rf /var/lib/apt/lists/*
+
+
+# `docker exec` skips /ros_entrypoint.sh — source ROS for the login shells dev:back runs.
+RUN echo ". /opt/ros/${ROS_DISTRO}/setup.sh" > /etc/profile.d/ros.sh
+
 WORKDIR /plugin
 
 CMD ["bash"]

package/cli/docker/Dockerfile.python

@@ -0,0 +1,21 @@
+# 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/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();