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

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/bin/muscat-pk.mjs

@@ -9,6 +9,8 @@ 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;
 
@@ -18,11 +20,13 @@ 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
+  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,6 +37,8 @@ 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":
@@ -43,6 +49,8 @@ async function main() {
         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":

package/cli/docker/Dockerfile.dev

@@ -0,0 +1,13 @@
+# 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
+
+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/src/build.mjs

@@ -8,11 +8,107 @@
 // The plugin author's `@rainbow-robotics/plugin-ui` and React imports are left external.
 // Muscat/robot and preview-host provide those modules through a sandbox import
 // map, so plugin ZIPs do not carry the UI runtime.
-import { cpSync, copyFileSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
 import { buildWithFallback } from "./esbuild.mjs";
 import { findPluginRoot, log } from "./util.mjs";
 
+function isMainBranch() {
+  const r = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
+  const branch = r.stdout?.trim();
+  return branch === "main" || branch === "master";
+}
+
+function manifestRuntime(root) {
+  try {
+    return JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime?.type ?? "python";
+  } catch {
+    return "python";
+  }
+}
+
+// For ros2 plugins, compile the colcon workspace inside the Jazzy + Python 3.12
+// container so the shipped ZIP carries ros2_ws/install. Real (non-symlink) build
+// → relocatable on the robot. Skipped (with a warning) if Docker is unavailable.
+export async function exportRos2Build(root) {
+  if (manifestRuntime(root) !== "ros2") return;
+  const { assertDockerReady, ensureImage, colconBuild } = await import("./ros2.mjs");
+  try {
+    assertDockerReady();
+  } catch (e) {
+    log.warn(`ros2 build skipped: ${e.message}`);
+    return;
+  }
+  ensureImage();
+  colconBuild(root, { symlink: false });
+  log.ok("ros2_ws/install ready (will be included in the ZIP)");
+}
+
+const PRERELEASE_RE = /\.(dev|a|b|rc|alpha|beta)\d*/i;
+
+function isPrerelease(version) {
+  return PRERELEASE_RE.test(version);
+}
+
+// Resolve the latest version of a PyPI package.
+// stableOnly=true → skips pre-release (dev/a/b/rc) versions.
+async function latestPypiVersion(pkg, { stableOnly = false } = {}) {
+  const res = await fetch(`https://pypi.org/pypi/${pkg}/json`, {
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!res.ok) throw new Error(`pypi ${pkg}: ${res.status}`);
+  const data = await res.json();
+
+  if (!stableOnly) return data.info.version;
+
+  // data.info.version is latest stable when stable releases exist.
+  // If it's still a pre-release, scan all releases for the newest stable.
+  if (!isPrerelease(data.info.version)) return data.info.version;
+
+  const stable = Object.keys(data.releases)
+    .filter((v) => !isPrerelease(v))
+    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+    .at(-1);
+
+  if (stable) return stable;
+
+  // No stable release exists — fall back with a warning.
+  log.warn(`  ${pkg}: no stable release found, using ${data.info.version}`);
+  return data.info.version;
+}
+
+// Pin unpinned (no version specifier) entries in requirements.txt to the
+// latest PyPI release. Runs on explicit `build`/`pack` only — keeps the shipped
+// plugin reproducible without churning the source file on every dev rebuild.
+// stableOnly=true is used on main-branch builds to avoid shipping dev versions.
+export async function pinRequirements(root, { stableOnly = false } = {}) {
+  const reqPath = resolve(root, "requirements.txt");
+  if (!existsSync(reqPath)) return;
+
+  const lines = readFileSync(reqPath, "utf8").split("\n");
+  const out = [];
+  let pinned = 0;
+  for (const line of lines) {
+    const name = line.trim();
+    // skip blanks, comments, and already-specified versions
+    if (!name || name.startsWith("#") || /[=<>~!]/.test(name)) {
+      out.push(line);
+      continue;
+    }
+    try {
+      const v = await latestPypiVersion(name, { stableOnly });
+      out.push(`${name}==${v}`);
+      pinned++;
+      log.info(`  pinned ${name}==${v}`);
+    } catch {
+      out.push(line);
+      log.warn(`  could not resolve ${name} (offline?) — left unpinned`);
+    }
+  }
+  if (pinned > 0) writeFileSync(reqPath, out.join("\n"));
+}
+
 const SANDBOX_HTML = `<!doctype html>
 <html lang="en">
   <head>
@@ -91,5 +187,12 @@ export async function buildPlugin({ root, minify = false } = {}) {
 
 export async function runBuild(args) {
   const minify = args.includes("--minify");
-  await buildPlugin({ minify });
+  const root = findPluginRoot();
+  if (!args.includes("--no-pin")) {
+    const stableOnly = isMainBranch();
+    log.step(`pinning requirements.txt to latest ${stableOnly ? "stable " : ""}PyPI versions`);
+    await pinRequirements(root, { stableOnly });
+  }
+  await buildPlugin({ root, minify });
+  await exportRos2Build(root);
 }

package/cli/src/check-package.mjs

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import { readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -22,6 +22,7 @@ function* mjsFiles(dir) {
 }
 
 for (const dir of roots) {
+  if (!existsSync(dir)) continue;
   for (const file of mjsFiles(dir)) {
     execFileSync(process.execPath, ["--check", file], { stdio: "inherit" });
   }

package/cli/src/dev.mjs

@@ -1,10 +1,17 @@
-// muscat-pk dev — run dev:ui and dev:back together.
+// muscat-pk dev — run Socket.IO bridge, dev:ui, and dev:back together.
 import { runDevUi } from "./devUi.mjs";
 import { runDevBack } from "./devBack.mjs";
+import { startSocketBridge } from "./socketBridge.mjs";
 import { log } from "./util.mjs";
 
 export async function runDev(args = []) {
-  log.step("starting dev:ui + dev:back");
+  log.step("starting Socket.IO bridge + dev:ui + dev:back");
+  const bridge = startSocketBridge();
+  const cleanup = () => bridge.close();
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
+  process.once("exit", cleanup);
+
   // dev:back runs to completion / detaches on its own; dev:ui owns the process.
   runDevBack().catch((e) => log.warn(`dev:back: ${e.message}`));
   await runDevUi(args);

package/cli/src/devBack.mjs

@@ -1,65 +1,153 @@
-// muscat-pk dev:back — run the plugin back end.
-//   sdk  : create/refresh .venv then `python main.py`
-//   ros2 : requires Docker (Jazzy container) — guidance only here
-//   none : nothing to run
+// muscat-pk dev:back — run the plugin back end during development.
+//   python : create/refresh .venv, then run main.py with watchfiles hot-reload
+//            (uvicorn's reloader). Watches ALL .py files, not just main.py.
+//   ros2   : keep a Jazzy + Python 3.12 container warm, colcon build once with
+//            --symlink-install, run the node, and restart on source changes —
+//            i.e. develop as if inside the container.
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, watch } from "node:fs";
 import { resolve } from "node:path";
-import { findPluginRoot, log } from "./util.mjs";
+import { detectPythonCmd, hasBin, findPluginRoot, log, venvPython } from "./util.mjs";
+import {
+  ROS2_DEV_IMAGE,
+  assertDockerReady,
+  ensureImage,
+  ros2PackageName,
+} from "./ros2.mjs";
 
-function manifestRuntime(root) {
+function readManifest(root) {
   try {
-    const m = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8"));
-    return m.runtime?.type ?? "none";
+    return JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8"));
   } catch {
-    return "none";
+    return {};
   }
 }
 
-export async function runDevBack() {
-  const root = findPluginRoot();
-  const type = manifestRuntime(root);
-
-  if (type === "none") {
-    log.info("runtime: none — no back end to run.");
-    return;
-  }
-
-  if (type === "ros2") {
-    log.warn(
-      "ROS2 back end runs in a Jazzy + Python 3.12 Docker container.\n" +
-        "  Ensure Docker is running, then: muscat-pk dev:back (container support TBD).",
-    );
-    return;
-  }
+function manifestRuntime(root) {
+  return readManifest(root).runtime?.type ?? "python";
+}
 
-  // python / rb_sdk
+// ── python ────────────────────────────────────────────────────────────────────
+function runPython(root) {
   const venv = resolve(root, ".venv");
-  const py = process.platform === "win32"
-    ? resolve(venv, "Scripts", "python.exe")
-    : resolve(venv, "bin", "python");
+  const py = venvPython(venv);
 
   if (!existsSync(py)) {
-    log.step("creating .venv (python3.12 preferred)…");
-    const python = spawnSync("python3.12", ["--version"]).status === 0
-      ? "python3.12"
-      : "python3";
-    if (python !== "python3.12") {
-      log.warn("python3.12 not found; using python3 (robot targets 3.12).");
+    log.step("creating .venv…");
+    if (hasBin("uv")) {
+      spawnSync("uv", ["venv", venv, "--python", "3.12", "--seed"], { cwd: root, stdio: "inherit" });
+    } else if (hasBin("conda")) {
+      spawnSync("conda", ["create", "-p", venv, "python=3.12", "-y", "--quiet"], { cwd: root, stdio: "inherit" });
+    } else if (hasBin("python3.12") || hasBin("python3") || hasBin("python")) {
+      const { cmd, is312 } = detectPythonCmd();
+      if (!is312) log.warn("python3.12 not found; using fallback (robot targets 3.12).");
+      spawnSync(cmd[0], [...cmd.slice(1), "-m", "venv", venv], { cwd: root, stdio: "inherit" });
+    } else {
+      throw new Error("Python not found (uv / conda / python3 none available). Install Python 3.12 to run the backend.");
     }
-    spawnSync(python, ["-m", "venv", venv], { cwd: root, stdio: "inherit" });
   }
 
   const reqs = resolve(root, "requirements.txt");
   if (existsSync(reqs)) {
     log.step("pip install -r requirements.txt…");
-    spawnSync(py, ["-m", "pip", "install", "-q", "-r", reqs], {
-      cwd: root,
-      stdio: "inherit",
-    });
+    spawnSync(py, ["-m", "pip", "install", "-q", "-r", reqs], { cwd: root, stdio: "inherit" });
   }
 
-  log.step("python main.py");
-  const child = spawn(py, ["main.py"], { cwd: root, stdio: "inherit" });
+  // watchfiles = uvicorn's reloader. --filter python watches every *.py in the
+  // project (and ignores .venv/__pycache__/node_modules), so interdependent
+  // modules trigger reloads — not just main.py.
+  log.step("pip install -q watchfiles (dev reloader)…");
+  spawnSync(py, ["-m", "pip", "install", "-q", "watchfiles"], { cwd: root, stdio: "inherit" });
+
+  const pluginId = readManifest(root).id ?? "";
+  const backEnv = { ...process.env, ...(pluginId ? { RB_PLUGIN_ID: pluginId } : {}) };
+  if (pluginId) log.step(`RB_PLUGIN_ID=${pluginId}`);
+
+  log.step("watchfiles → python main.py (reload on any .py change)");
+  const child = spawn(
+    py,
+    ["-m", "watchfiles", "--filter", "python", "--target-type", "command", "python main.py", "."],
+    { cwd: root, stdio: "inherit", env: backEnv },
+  );
+  const cleanup = () => { if (!child.killed) child.kill(); };
   child.on("exit", (code) => process.exit(code ?? 0));
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
+}
+
+// ── ros2 ───────────────────────────────────────────────────────────────────────
+function runRos2(root) {
+  assertDockerReady();
+  const pkg = ros2PackageName(root);
+  if (!pkg) throw new Error("no ROS2 package found under ros2_ws/src.");
+
+  ensureImage();
+
+  const pluginId = readManifest(root).id ?? "";
+  const container = `${ROS2_DEV_IMAGE}-run`;
+  const envFlags = pluginId ? ["-e", `RB_PLUGIN_ID=${pluginId}`] : [];
+  const docker = (args, opts = {}) =>
+    spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
+
+  // start a warm, long-lived container with the workspace mounted
+  docker(["rm", "-f", container], { stdio: "ignore" });
+  log.step("starting ROS2 dev container…");
+  const up = docker(
+    ["run", "-d", "--name", container, "-v", `${root}:/plugin`, "-w", "/plugin", ROS2_DEV_IMAGE, "sleep", "infinity"],
+    { stdio: "inherit" },
+  );
+  if (up.status !== 0) throw new Error("failed to start dev container.");
+
+  // one-time deps + symlink build (edits to .py reflect without rebuilding)
+  log.step("pip install + colcon build --symlink-install (once)…");
+  docker(["exec", container, "bash", "-lc",
+    "pip install -r requirements.txt --break-system-packages --ignore-installed -q || true; cd ros2_ws && colcon build --symlink-install"]);
+
+  let child = null;
+  const startNode = () => {
+    if (child) child.kill();
+    log.step(`ros2 run ${pkg} ${pkg}_node`);
+    child = spawn(
+      "docker",
+      ["exec", ...envFlags, container, "bash", "-lc",
+        `cd ros2_ws && source install/setup.bash && ros2 run ${pkg} ${pkg}_node`],
+      { cwd: root, stdio: "inherit" },
+    );
+  };
+  startNode();
+
+  // restart node on source change; rebuild only when package metadata changes
+  let timer = null;
+  const onChange = (_event, filename) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      const structural = filename && /(setup\.py|package\.xml|CMakeLists\.txt)$/.test(String(filename));
+      if (structural) {
+        log.info("package metadata changed — colcon rebuild…");
+        docker(["exec", container, "bash", "-lc", "cd ros2_ws && colcon build --symlink-install"]);
+      } else {
+        log.info("source changed — restarting node…");
+      }
+      startNode();
+    }, 300);
+  };
+  for (const target of ["ros2_ws/src", "main.py"]) {
+    const full = resolve(root, target);
+    if (existsSync(full)) watch(full, { recursive: true }, onChange);
+  }
+
+  const cleanup = () => {
+    if (child) child.kill();
+    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
+    process.exit(0);
+  };
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+}
+
+export async function runDevBack() {
+  const root = findPluginRoot();
+  const type = manifestRuntime(root);
+  if (type === "ros2") return runRos2(root);
+  return runPython(root);
 }

package/cli/src/devUi.mjs

@@ -1,22 +1,56 @@
 // muscat-pk dev:ui — preview the plugin inside a mini-Muscat (preview-host).
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { buildPlugin } from "./build.mjs";
-import { checkKitUpdate, findPluginRoot, kitRoot, log } from "./util.mjs";
+import { checkKitUpdate, findPluginRoot, hasBin, kitRoot, log } from "./util.mjs";
 
-/** Resolve @rainbow-robotics/preview-host package root.
- *  Works in monorepo (yarn workspace hoisting) and when both packages are
- *  installed as deps of the plugin project. */
+const PREVIEW_PKG = "@rainbow-robotics/preview-host";
+const CACHE_DIR = resolve(homedir(), ".muscat-pk");
+const CACHE_ROOT = resolve(CACHE_DIR, "node_modules", "@rainbow-robotics", "preview-host");
+
+/**
+ * Resolve preview-host root in order:
+ *  1. Standard require (npm/yarn global install)
+ *  2. Monorepo sibling (dev workspace)
+ *  3. ~/.muscat-pk cache (previous auto-install)
+ *  4. Auto-install to ~/.muscat-pk via npm (binary users who have Node.js)
+ */
 function findPreviewHostRoot() {
+  // 1. npm/yarn 설치 경로
   try {
     const req = createRequire(import.meta.url);
-    return dirname(req.resolve("@rainbow-robotics/preview-host/package.json"));
-  } catch {
-    // fallback: sibling package in muscat-plugin-kit/ workspace
-    return resolve(kitRoot, "../preview-host");
+    return dirname(req.resolve(`${PREVIEW_PKG}/package.json`));
+  } catch {}
+
+  // 2. 모노레포 sibling
+  const sibling = resolve(kitRoot, "../preview-host");
+  if (existsSync(resolve(sibling, "package.json"))) return sibling;
+
+  // 3. 캐시
+  if (existsSync(resolve(CACHE_ROOT, "package.json"))) return CACHE_ROOT;
+
+  // 4. npm 자동 설치 → 캐시
+  if (!hasBin("npm")) {
+    throw new Error(
+      `preview-host를 찾을 수 없습니다.\n` +
+      `Node.js 20+ 를 설치하면 자동으로 준비됩니다: https://nodejs.org`,
+    );
+  }
+  log.step(`preview-host 설치 중 (~/.muscat-pk) — 첫 실행 시 한 번만 수행됩니다…`);
+  mkdirSync(CACHE_DIR, { recursive: true });
+  const r = spawnSync(
+    "npm",
+    ["install", "--prefix", CACHE_DIR, "--save", PREVIEW_PKG],
+    { stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error("preview-host 설치 실패.");
+  if (!existsSync(resolve(CACHE_ROOT, "package.json"))) {
+    throw new Error("preview-host 설치 후에도 패키지를 찾을 수 없습니다.");
   }
+  return CACHE_ROOT;
 }
 
 export async function runDevUi(args = []) {
@@ -31,7 +65,7 @@ export async function runDevUi(args = []) {
   if (!existsSync(resolve(previewRoot, "dist", "index.html"))) {
     log.step("building preview-host bundle (first run)…");
     await new Promise((res, rej) => {
-      const p = spawn("node", [resolve(previewRoot, "build.mjs")], {
+      const p = spawn(process.execPath, [resolve(previewRoot, "build.mjs")], {
         stdio: "inherit",
       });
       p.on("exit", (c) => (c === 0 ? res() : rej(new Error("preview-host build failed"))));
@@ -40,11 +74,11 @@ export async function runDevUi(args = []) {
 
   log.step(`starting preview-host on :${port}`);
   const child = spawn(
-    "node",
+    process.execPath,
     [serveEntry, "--plugin", distDir, "--port", String(port)],
     { stdio: "inherit" },
   );
   child.on("exit", (code) => process.exit(code ?? 0));
 }
 
-export { findPluginRoot };
+export { findPluginRoot, findPreviewHostRoot };