@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.44 → 0.1.2-dev.45

package/README.md

@@ -121,7 +121,7 @@ muscat-pk pack                 # 배포용 ZIP 생성
 
 | 패키지 | 역할 |
 |---|---|
-| `@rainbow-robotics/plugin-ui` | UI 런타임 계약: rb-* 엘리먼트, React 바인딩, sandbox connect |
+| `@rainbow-robotics/plugin-ui` | UI 런타임 계약: React direct mount, `useRb()` context, host services |
 | `@rainbow-robotics/muscat-plugin-kit` | CLI, 템플릿, 빌드/팩, 미리보기 호스트 |
 
 플러그인 ZIP에는 플러그인 코드와 에셋만 포함됩니다. `@rainbow-robotics/plugin-ui`, `react`, `react-dom`은 호스트(Muscat/로봇)의 import map에서 제공됩니다.

package/cli/README.md

@@ -20,6 +20,190 @@ 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/muscat-pk.mjs

@@ -11,6 +11,11 @@ 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 { 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;
 
@@ -25,6 +30,8 @@ Commands:
   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)
+  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
@@ -46,6 +53,12 @@ async function main() {
         return await runDevUi(args);
       case "dev:back":
         return await runDevBack(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":

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();

package/cli/src/build.mjs

@@ -223,32 +223,6 @@ export async function pinRequirements(root, { stableOnly = false } = {}) {
   if (pinned > 0) writeFileSync(reqPath, out.join("\n"));
 }
 
-export const SANDBOX_HTML = `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <title>plugin sandbox</title>
-    <script type="importmap">
-      {
-        "imports": {
-          "@rainbow-robotics/plugin-ui/connect":  "/plugin-runtime/@rainbow-robotics/plugin-ui/connect.js",
-          "@rainbow-robotics/plugin-ui/react":    "/plugin-runtime/@rainbow-robotics/plugin-ui/react.js",
-          "@rainbow-robotics/plugin-ui/sdk":      "/plugin-runtime/@rainbow-robotics/plugin-ui/sdk.js",
-          "@rainbow-robotics/plugin-ui/elements": "/plugin-runtime/@rainbow-robotics/plugin-ui/elements.js",
-          "react":                       "/plugin-runtime/vendor/react.js",
-          "react/jsx-runtime":           "/plugin-runtime/vendor/react-jsx-runtime.js",
-          "react/jsx-dev-runtime":       "/plugin-runtime/vendor/react-jsx-dev-runtime.js",
-          "react-dom/client":            "/plugin-runtime/vendor/react-dom-client.js"
-        }
-      }
-    </script>
-  </head>
-  <body>
-    <script type="module" src="./content.js"></script>
-  </body>
-</html>
-`;
-
 export async function buildPlugin({ root, minify = false } = {}) {
   const pluginRoot = root ?? findPluginRoot();
   assertManifest(pluginRoot);
@@ -280,9 +254,8 @@ export async function buildPlugin({ root, minify = false } = {}) {
   const manifestSrc = resolve(pluginRoot, "manifest.json");
   if (existsSync(manifestSrc)) copyFileSync(manifestSrc, resolve(distDir, "manifest.json"));
 
-  // Generate sandbox.html — plugin authors don't manage this file.
-  writeFileSync(resolve(distDir, "sandbox.html"), SANDBOX_HTML, "utf8");
-  log.step("generated dist/sandbox.html");
+  // No sandbox.html: the host dynamically imports dist/{ui}.js directly as a
+  // plain ESM module (see @rainbow-robotics/plugin-ui/host) — no iframe.
 
   const assetsSrc = resolve(pluginRoot, "assets");
   if (existsSync(assetsSrc)) {

package/cli/src/dev.mjs

@@ -2,12 +2,20 @@
 import { runDevUi } from "./devUi.mjs";
 import { runDevBack } from "./devBack.mjs";
 import { startBridge, stopBridge, BRIDGE_CONTAINER, BRIDGE_PORT } from "./bridge.mjs";
-import { ensureDocker, log, prompt, promptRobotConnection } from "./util.mjs";
+import { assertManifestPorts } from "./manifest.mjs";
+import { formatPortRanges } from "./ports.mjs";
+import { ensureDocker, findPluginRoot, log, prompt, promptRobotConnection } from "./util.mjs";
 
 export async function runDev(args = []) {
+  const root = findPluginRoot();
+  const portRanges = assertManifestPorts(root);
+  if (portRanges.length > 0) {
+    log.step(`plugin backend ports declared: ${formatPortRanges(portRanges)}`);
+    process.env.MUSCAT_PK_PORTS_PRECHECKED = "1";
+  }
   ensureDocker();
   const { robotIp, robotToken } = await promptRobotConnection(args);
-  if (robotIp)    process.env.MUSCAT_ROBOT_HOST  = robotIp;
+  process.env.MUSCAT_ROBOT_HOST  = robotIp;
   if (robotToken) process.env.MUSCAT_ROBOT_TOKEN = robotToken;
   log.step("starting Socket.IO bridge (Docker) + dev:ui + dev:back");
   const bridgeStarted = await startBridge();

package/cli/src/devBack.mjs

@@ -10,8 +10,21 @@
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync, watch } from "node:fs";
 import { resolve } from "node:path";
-import { ensureDocker, findPluginRoot, log, promptRobotConnection } from "./util.mjs";
-import { manifestRuntime, readManifest, validateManifest } from "./manifest.mjs";
+import {
+  detectPythonCmd,
+  ensureDocker,
+  findPluginRoot,
+  hasBin,
+  log,
+  promptRobotConnection,
+  venvPython,
+} from "./util.mjs";
+import { assertManifestPorts, manifestRuntime, readManifest, validateManifest } from "./manifest.mjs";
+import {
+  formatPortRanges,
+  portEnvFlags,
+  startPortContractMonitor,
+} from "./ports.mjs";
 import {
   PYTHON_DEV_IMAGE,
   assertDockerReady as pyAssertDockerReady,
@@ -29,13 +42,49 @@ import {
   ensureImage as cppEnsureImage,
 } from "./cpp.mjs";
 
+// ── IDE tooling venv (best-effort, non-blocking) ────────────────────────────
+// Docker is the source of truth for actually RUNNING the backend — this just
+// gives editors/linters (pylint, pyright, mypy, ...) a real interpreter with
+// the plugin's deps installed, since they inspect the host filesystem, not the
+// container. Runs in the background so it never delays `dev:back` starting,
+// and any failure here (no local Python toolchain, offline, ...) is silent —
+// Docker works fine with zero local Python.
+function syncIdeVenv(root) {
+  const venvDir = resolve(root, ".venv");
+  const py = venvPython(venvDir);
+
+  setImmediate(() => {
+    try {
+      if (!existsSync(py)) {
+        let created;
+        if (hasBin("uv")) {
+          created = spawnSync("uv", ["venv", venvDir, "--python", "3.12", "--seed"], { cwd: root, stdio: "ignore" });
+        } else {
+          const { cmd } = detectPythonCmd();
+          created = spawnSync(cmd[0], [...cmd.slice(1), "-m", "venv", venvDir], { cwd: root, stdio: "ignore" });
+        }
+        if (created.status !== 0 || !existsSync(py)) return;
+      }
+      const reqs = resolve(root, "requirements.txt");
+      const args = ["-m", "pip", "install", "-q"];
+      if (existsSync(reqs)) args.push("-r", reqs);
+      if (spawnSync(py, args, { cwd: root, stdio: "ignore" }).status === 0) {
+        log.info(`IDE venv ready → .venv (point your editor's Python interpreter there for pylint/pyright)`);
+      }
+    } catch {
+      /* best-effort only */
+    }
+  });
+}
+
 // ── python ────────────────────────────────────────────────────────────────────
 // Runs in a warm Ubuntu 24.04 + Python 3.12 container (matches the robot).
 // Under `muscat-pk dev`, it shares the bridge container's netns, so the SDK
 // reaches the Socket.IO bridge at the default localhost:10000.
-async function runPython(root) {
+async function runPython(root, portRanges) {
   pyAssertDockerReady();
   await pyEnsureImage();
+  syncIdeVenv(root);
 
   const manifest = readManifest(root);
   const pluginId = manifest.id ?? "";
@@ -46,6 +95,7 @@ async function runPython(root) {
     ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
     ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
     ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
+    ...portEnvFlags(portRanges),
   ];
   // Share the bridge container's network namespace so localhost:10000 is the
   // bridge (set by `muscat-pk dev`). Standalone dev:back has no bridge to join.
@@ -64,6 +114,7 @@ async function runPython(root) {
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
+  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log });
 
   log.step("pip install requirements + watchfiles (in container)…");
   docker(["exec", container, "bash", "-lc",
@@ -87,11 +138,13 @@ async function runPython(root) {
   });
 
   const cleanup = () => {
+    stopPortMonitor();
     if (!child.killed) child.kill();
     spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
     process.exit(0);
   };
   child.on("exit", (code) => {
+    stopPortMonitor();
     spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
     process.exit(code ?? 0);
   });
@@ -100,7 +153,7 @@ async function runPython(root) {
 }
 
 // ── ros2 ───────────────────────────────────────────────────────────────────────
-async function runRos2(root) {
+async function runRos2(root, portRanges) {
   assertDockerReady();
   const pkg = ros2PackageName(root);
   if (!pkg) throw new Error("no ROS2 package found under ros2_ws/src.");
@@ -110,6 +163,7 @@ async function runRos2(root) {
   const manifest = readManifest(root);
   const pluginId = manifest.id ?? "";
   const isRclcpp = manifest.runtime?.rosClient === "rclcpp";
+  if (!isRclcpp) syncIdeVenv(root); // rclpy is plain Python — rclcpp is C++, no venv needed
   const container = `${ROS2_DEV_IMAGE}-run`;
   const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
   const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
@@ -117,6 +171,7 @@ async function runRos2(root) {
     ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
     ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
     ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
+    ...portEnvFlags(portRanges),
   ];
   const docker = (args, opts = {}) =>
     spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
@@ -129,6 +184,7 @@ async function runRos2(root) {
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
+  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log });
 
   // one-time deps + symlink build (edits to .py reflect without rebuilding)
   log.step("pip install + colcon build --symlink-install (once)…");
@@ -170,6 +226,7 @@ async function runRos2(root) {
   }
 
   const cleanup = () => {
+    stopPortMonitor();
     if (child) child.kill();
     spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
     process.exit(0);
@@ -179,7 +236,7 @@ async function runRos2(root) {
 }
 
 // ── cpp ──────────────────────────────────────────────────────────────────────
-async function runCpp(root) {
+async function runCpp(root, portRanges) {
   cppAssertDockerReady();
   const manifest = readManifest(root);
   const entry = manifest.runtime?.entry;
@@ -195,6 +252,7 @@ async function runCpp(root) {
     ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
     ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
     ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
+    ...portEnvFlags(portRanges),
   ];
   const docker = (args, opts = {}) =>
     spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
@@ -207,6 +265,7 @@ async function runCpp(root) {
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
+  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log });
 
   const build = () => {
     log.step("cmake build…");
@@ -243,6 +302,7 @@ async function runCpp(root) {
   if (existsSync(cppDir)) watch(cppDir, { recursive: true }, onChange);
 
   const cleanup = () => {
+    stopPortMonitor();
     if (child) child.kill();
     spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
     process.exit(0);
@@ -259,14 +319,17 @@ function warnManifest(root) {
 }
 
 export async function runDevBack(args = []) {
-  ensureDocker();
   const root = findPluginRoot();
   warnManifest(root);
+  const portRanges = assertManifestPorts(root);
+  if (portRanges.length > 0 && process.env.MUSCAT_PK_PORTS_PRECHECKED !== "1")
+    log.step(`plugin backend ports declared: ${formatPortRanges(portRanges)}`);
+  ensureDocker();
   const { robotIp, robotToken } = await promptRobotConnection(args);
   if (robotIp)    process.env.MUSCAT_ROBOT_HOST  = robotIp;
   if (robotToken) process.env.MUSCAT_ROBOT_TOKEN = robotToken;
   const type = manifestRuntime(root);
-  if (type === "ros2") return await runRos2(root);
-  if (type === "cpp") return await runCpp(root);
-  return await runPython(root);
+  if (type === "ros2") return await runRos2(root, portRanges);
+  if (type === "cpp") return await runCpp(root, portRanges);
+  return await runPython(root, portRanges);
 }