@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.3 → 0.1.2-dev.31

package/README.md

@@ -1,27 +1,106 @@
 # @rainbow-robotics/muscat-plugin-kit
 
-Muscat plugin developer kit: `muscat-pk`, `create-muscat-plugin`, build/pack,
-and preview-host.
+Muscat 플러그인 개발 CLI. 스캐폴딩, 빌드/팩, 개발 서버(UI + 백엔드)를 제공합니다.
 
-This package does **not** own the UI contract. Plugin source imports
-`@rainbow-robotics/plugin-ui/*`, and `muscat-pk build` leaves that package external so the
-robot/preview-host can provide its own runtime.
+## 설치
+
+### 방법 1 — npm (Node.js 20+ 필요)
+
+```bash
+# 최신 stable
+npm install -g @rainbow-robotics/muscat-plugin-kit
+
+# dev 채널 (최신 개발 빌드)
+npm install -g @rainbow-robotics/muscat-plugin-kit@dev
+
+# 특정 버전
+npm install -g @rainbow-robotics/muscat-plugin-kit@1.2.3
+```
+
+### 방법 2 — 설치 스크립트 (Node.js 없어도 됨)
+
+macOS / Linux / WSL:
+
+```bash
+# 최신 stable
+curl -fsSL https://raw.githubusercontent.com/rainbow-robotics/web-rainbow-ui/main/scripts/install-muscat-pk.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
+
+# 특정 버전
+MUSCAT_PK_TAG=1.2.3 curl -fsSL https://raw.githubusercontent.com/rainbow-robotics/web-rainbow-ui/main/scripts/install-muscat-pk.sh | sh
+```
+
+Windows PowerShell:
+
+```powershell
+# 최신 stable
+irm https://raw.githubusercontent.com/rainbow-robotics/web-rainbow-ui/main/scripts/install-muscat-pk.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
+```
+
+> 설치 스크립트는 Node.js 20+가 있으면 npm을 우선 사용하고, 없으면 S3에서 self-contained 바이너리를 받습니다.
+
+### 방법 3 — 바이너리 직접 다운로드
+
+```
+https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/v{버전}/{바이너리}
+```
+
+| OS | 파일 |
+|---|---|
+| Linux x64 | `muscat-pk-linux-x64` |
+| macOS ARM64 | `muscat-pk-darwin-arm64` |
+| Windows x64 | `muscat-pk-win-x64.exe` |
+
+채널 포인터:
+
+```
+# 최신 stable 버전 문자열
+https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/latest-version.txt
+
+# 최신 dev 버전 문자열
+https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit/dev-version.txt
+```
+
+---
+
+## 빠른 시작
 
 ```bash
-npm i -g @rainbow-robotics/muscat-plugin-kit
-muscat-pk new my-plugin --type sdk
+muscat-pk new my-plugin        # 플러그인 프로젝트 생성 (python 또는 ros2 선택)
 cd my-plugin
-muscat-pk build
-muscat-pk dev:ui
-muscat-pk pack
+
+muscat-pk dev                  # UI + 백엔드 동시 실행
+muscat-pk dev:ui               # UI 미리보기만
+muscat-pk dev:back             # 백엔드만 (Python watchfiles / ROS2 Docker)
+
+muscat-pk build                # dist/ 빌드
+muscat-pk pack                 # 배포용 ZIP 생성
 ```
 
-Published package responsibilities:
+## 명령어 목록
+
+| 명령 | 설명 |
+|---|---|
+| `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 버전 관리 |
+
+## 패키지 역할
 
-| Package | Role |
+| 패키지 | 역할 |
 |---|---|
-| `@rainbow-robotics/plugin-ui` | Contract/runtime: rb-* elements, author React bindings, sandbox connect, host renderer |
-| `@rainbow-robotics/muscat-plugin-kit` | CLI, scaffold templates, build/pack, preview-host |
+| `@rainbow-robotics/plugin-ui` | UI 런타임 계약: rb-* 엘리먼트, React 바인딩, sandbox connect |
+| `@rainbow-robotics/muscat-plugin-kit` | CLI, 템플릿, 빌드/팩, 미리보기 호스트 |
 
-The plugin ZIP contains plugin code and assets only. It relies on the host's
-import map for `@rainbow-robotics/plugin-ui`, `react`, and `react-dom`.
+플러그인 ZIP에는 플러그인 코드와 에셋만 포함됩니다. `@rainbow-robotics/plugin-ui`, `react`, `react-dom`은 호스트(Muscat/로봇)의 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,11 +10,10 @@ 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 update      # update @rainbow-robotics/muscat-plugin-kit and @rainbow-robotics/plugin-ui
 muscat-pk sdk list | sdk update [version]   # manage rainbow-rb-sdk (python)

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,14 +1,16 @@
 #!/usr/bin/env node
 // muscat-pk — Muscat plugin developer CLI.
-// Subcommands: new, build, pack, dev, dev:ui, dev:back, update, sdk.
+// Subcommands: new, build, dev, dev:ui, dev:back, update, sdk.
+import { log } from "../src/util.mjs";
 import { runNew } from "../src/new.mjs";
 import { runBuild } from "../src/build.mjs";
-import { runPack } from "../src/pack.mjs";
 import { runDevUi } from "../src/devUi.mjs";
 import { runDevBack } from "../src/devBack.mjs";
 import { runDev } from "../src/dev.mjs";
 import { runUpdate } from "../src/update.mjs";
 import { runSdk } from "../src/sdk.mjs";
+import { runType } from "../src/type.mjs";
+import { runPreview } from "../src/preview.mjs";
 
 const [, , cmd, ...args] = process.argv;
 
@@ -17,12 +19,13 @@ const HELP = `muscat-pk — Muscat plugin kit
 Usage: muscat-pk <command> [options]
 
 Commands:
-  new [dir]        Scaffold a new plugin project
-  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)
+  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 main.py)
+  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
 
@@ -33,16 +36,18 @@ async function main() {
     switch (cmd) {
       case "new":
         return await runNew(args);
+      case "type":
+        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 "update":
         return await runUpdate(args);
       case "sdk":
@@ -59,7 +64,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/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

@@ -0,0 +1,14 @@
+# Dev-only container for the ROS2 plugin back end.
+# 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/*
+
+WORKDIR /plugin
+
+CMD ["bash"]

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 --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/src/bridge.mjs

@@ -0,0 +1,92 @@
+// Socket.IO bridge container lifecycle for `muscat-pk dev`.
+// The bridge runs in Docker and publishes port 10000 to the host:
+//   - frontend (preview-host, on the host) connects to localhost:10000
+//   - the backend container joins via `--network container:<bridge>` and reaches
+//     it at localhost:10000 too — no host.docker.internal needed (robust cross-OS).
+import { spawnSync } from "node:child_process";
+import { createServer, connect } from "node:net";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { hasBin, kitRoot, log, pruneMuskatImages } from "./util.mjs";
+
+export const BRIDGE_IMAGE = "muscat-pk-bridge";
+export const BRIDGE_CONTAINER = "muscat-pk-bridge-run";
+export const BRIDGE_PORT = 10000;
+
+const DOCKERFILE = resolve(kitRoot, "cli/docker/Dockerfile.bridge");
+const BUILD_CONTEXT = resolve(kitRoot, "cli");
+
+function assertDockerReady() {
+  if (!hasBin("docker")) {
+    throw new Error("Docker not found. `muscat-pk dev` runs the Socket.IO bridge in a container.");
+  }
+  if (!existsSync(DOCKERFILE)) {
+    throw new Error(`kit Dockerfile missing at ${DOCKERFILE} (reinstall muscat-plugin-kit).`);
+  }
+}
+
+// Is a host TCP port already bound? (Catches another bridge or a stray process.)
+function isPortInUse(port) {
+  return new Promise((res) => {
+    const srv = createServer();
+    srv.once("error", (err) => res(err.code === "EADDRINUSE"));
+    srv.once("listening", () => srv.close(() => res(false)));
+    srv.listen(port, "0.0.0.0");
+  });
+}
+
+// Wait until the published port accepts a TCP connection (bridge is ready).
+function waitForPort(port, timeoutMs = 15_000) {
+  const start = Date.now();
+  return new Promise((res, rej) => {
+    const tryOnce = () => {
+      const sock = connect(port, "127.0.0.1");
+      sock.once("connect", () => { sock.destroy(); res(); });
+      sock.once("error", () => {
+        sock.destroy();
+        if (Date.now() - start > timeoutMs) rej(new Error("bridge container did not become ready in time"));
+        else setTimeout(tryOnce, 300);
+      });
+    };
+    tryOnce();
+  });
+}
+
+function ensureImage() {
+  log.step(`docker build -t ${BRIDGE_IMAGE} (first run is slow, then cached)…`);
+  const r = spawnSync("docker", ["build", "-t", BRIDGE_IMAGE, "-f", DOCKERFILE, BUILD_CONTEXT], { stdio: "inherit" });
+  if (r.status !== 0) throw new Error("docker build failed (bridge image).");
+  pruneMuskatImages();
+}
+
+/** Build the image, preflight the port, and start the bridge container. */
+export async function startBridge() {
+  assertDockerReady();
+
+  // remove our own stale container first, then check the host port is free
+  spawnSync("docker", ["rm", "-f", BRIDGE_CONTAINER], { stdio: "ignore" });
+  if (await isPortInUse(BRIDGE_PORT)) {
+    throw new Error(
+      `port ${BRIDGE_PORT} is already in use.\n` +
+      `  Another 'muscat-pk dev' may be running, or a process is holding the port.\n` +
+      `  Stop it, or free the port, then retry.`,
+    );
+  }
+
+  ensureImage();
+
+  log.step("starting Socket.IO bridge container…");
+  const up = spawnSync(
+    "docker",
+    ["run", "-d", "--name", BRIDGE_CONTAINER, "-p", `${BRIDGE_PORT}:${BRIDGE_PORT}`, BRIDGE_IMAGE],
+    { stdio: "inherit" },
+  );
+  if (up.status !== 0) throw new Error("failed to start bridge container.");
+
+  await waitForPort(BRIDGE_PORT);
+  log.step(`Socket.IO bridge listening on ws://127.0.0.1:${BRIDGE_PORT}`);
+}
+
+export function stopBridge() {
+  spawnSync("docker", ["rm", "-f", BRIDGE_CONTAINER], { stdio: "ignore" });
+}