@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.41 → 0.1.2-dev.43

package/cli/bin/muscat-pk.mjs

@@ -11,7 +11,6 @@ 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";
 
 const [, , cmd, ...args] = process.argv;
 
@@ -26,7 +25,6 @@ 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)
-  preview          Preview against a real Muscat server (prompts for robot IP)
   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
@@ -48,8 +46,6 @@ 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 "uninstall":

package/cli/src/bridge.mjs

@@ -59,19 +59,16 @@ function ensureImage() {
   pruneMuskatImages();
 }
 
-/** Build the image, preflight the port, and start the bridge container. */
+/**
+ * Build the image, preflight the port, and start the bridge container.
+ * Returns true if bridge started, false if port was already in use (caller decides).
+ */
 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.`,
-    );
-  }
+  if (await isPortInUse(BRIDGE_PORT)) return false;
 
   ensureImage();
 
@@ -85,6 +82,7 @@ export async function startBridge() {
 
   await waitForPort(BRIDGE_PORT);
   log.step(`Socket.IO bridge listening on ws://127.0.0.1:${BRIDGE_PORT}`);
+  return true;
 }
 
 export function stopBridge() {

package/cli/src/build.mjs

@@ -75,27 +75,33 @@ function isMainBranch() {
 // rclpy: arch-agnostic (pure Python) → dist/ros2_ws/install/ (built once)
 // rclcpp: arch-specific C++ binaries → dist/ros2_ws/install-{arch}/ per arch
 export async function exportRos2Build(root, archs = ["amd64", "arm64"]) {
-  if (manifestRuntime(root) !== "ros2") return;
+  if (manifestRuntime(root) !== "ros2") return [];
   const { assertDockerReady, ensureImage, colconBuild, ROS2_DEV_IMAGE, ARCH_DOCKER_PLATFORM } = await import("./ros2.mjs");
   try {
     assertDockerReady();
   } catch (e) {
     log.warn(`ros2 build skipped: ${e.message}`);
-    return;
+    return [];
   }
 
   const manifest = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8"));
   const rosClient = manifest.runtime?.rosClient;
 
+  const skipped = [];
   if (rosClient === "rclcpp") {
     // C++ ROS2: compile per arch so each robot picks the right install-{arch}/
     for (const arch of archs) {
       const dockerPlatform = ARCH_DOCKER_PLATFORM[arch];
-      if (!dockerPlatform) { log.warn(`unknown arch '${arch}' — skipped`); continue; }
+      if (!dockerPlatform) { log.warn(`unknown arch '${arch}' — skipped`); skipped.push(arch); continue; }
       const archImage = `${ROS2_DEV_IMAGE}-${arch}`;
-      await ensureImage(archImage, { platform: dockerPlatform });
-      colconBuild(root, { symlink: false, arch });
-      log.ok(`dist/ros2_ws/install-${arch}/ ready`);
+      try {
+        await ensureImage(archImage, { platform: dockerPlatform });
+        colconBuild(root, { symlink: false, arch });
+        log.ok(`dist/ros2_ws/install-${arch}/ ready`);
+      } catch {
+        log.warn(`${arch} ros2 build skipped — QEMU not available`);
+        skipped.push(arch);
+      }
     }
   } else {
     // rclpy / pure Python: arch-agnostic, build once
@@ -103,6 +109,7 @@ export async function exportRos2Build(root, archs = ["amd64", "arm64"]) {
     colconBuild(root, { symlink: false });
     log.ok("dist/ros2_ws/install/ ready");
   }
+  return skipped;
 }
 
 // For cpp plugins, compile cpp/ inside the Ubuntu container (Release) per arch
@@ -110,13 +117,13 @@ export async function exportRos2Build(root, archs = ["amd64", "arm64"]) {
 // robot-compatible executables. rb-runtime prefers dist/{arch}/ and falls back
 // to dist/{entry} (legacy). Skipped (with a warning) if Docker is unavailable.
 export async function exportCppBuild(root, distDir, archs = ["amd64", "arm64"]) {
-  if (manifestRuntime(root) !== "cpp") return;
+  if (manifestRuntime(root) !== "cpp") return [];
   const { assertDockerReady, ensureImage, cmakeBuild, CPP_DEV_IMAGE, ARCH_DOCKER_PLATFORM } = await import("./cpp.mjs");
   try {
     assertDockerReady();
   } catch (e) {
     log.warn(`cpp build skipped: ${e.message}`);
-    return;
+    return [];
   }
 
   const entry = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime?.entry;
@@ -125,26 +132,31 @@ export async function exportCppBuild(root, distDir, archs = ["amd64", "arm64"])
     return;
   }
 
+  const skipped = [];
   for (const arch of archs) {
-    // python과 동일하게 arch별 이미지를 빌드해야 --platform 불일치를 피할 수 있다.
     const dockerPlatform = ARCH_DOCKER_PLATFORM[arch];
-    if (!dockerPlatform) { log.warn(`unknown arch '${arch}' — skipped`); continue; }
+    if (!dockerPlatform) { log.warn(`unknown arch '${arch}' — skipped`); skipped.push(arch); continue; }
     const archImage = `${CPP_DEV_IMAGE}-${arch}`;
-    await ensureImage(archImage, { platform: dockerPlatform });
-    cmakeBuild(root, { buildType: "Release", arch });
-    const buildDir = `cpp/build-${arch}`;
-    const built = resolve(root, buildDir, entry);
-    if (existsSync(built)) {
-      const archDir = resolve(distDir, arch);
-      mkdirSync(archDir, { recursive: true });
-      const dest = resolve(archDir, entry);
-      copyFileSync(built, dest);
-      chmodSync(dest, 0o755);
-      log.ok(`cpp binary → dist/${arch}/${entry}`);
-    } else {
-      log.warn(`cpp binary not found at ${buildDir}/${entry} — skipped for ${arch}`);
+    try {
+      await ensureImage(archImage, { platform: dockerPlatform });
+      cmakeBuild(root, { buildType: "Release", arch });
+      const built = resolve(root, `cpp/build-${arch}`, entry);
+      if (existsSync(built)) {
+        const archDir = resolve(distDir, arch);
+        mkdirSync(archDir, { recursive: true });
+        const dest = resolve(archDir, entry);
+        copyFileSync(built, dest);
+        chmodSync(dest, 0o755);
+        log.ok(`cpp binary → dist/${arch}/${entry}`);
+      } else {
+        log.warn(`cpp binary not found at cpp/build-${arch}/${entry}`);
+      }
+    } catch {
+      log.warn(`${arch} cpp build skipped — QEMU not available`);
+      skipped.push(arch);
     }
   }
+  return skipped;
 }
 
 const PRERELEASE_RE = /\.(dev|a|b|rc|alpha|beta)\d*/i;
@@ -434,6 +446,8 @@ export async function runBuild(args) {
 
   const { pluginRoot, distDir } = await buildPlugin({ root, minify: true });
 
+  const skippedArches = { wheels: [], ros2: [], cpp: [] };
+
   // python / rclpy: lock + wheel vendor in Ubuntu 24.04 container
   if (!noLock) {
     const manifest = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime ?? {};
@@ -443,15 +457,29 @@ export async function runBuild(args) {
     if (needsLock) {
       const { lockAndVendor } = await import("./python.mjs");
       try {
-        await lockAndVendor(pluginRoot, archs);
+        skippedArches.wheels = await lockAndVendor(pluginRoot, archs);
       } catch (e) {
         log.warn(`python lock/vendor skipped: ${e.message}`);
+        skippedArches.wheels = archs;
       }
     }
   }
 
-  await exportRos2Build(root, archs);
-  await exportCppBuild(root, distDir, archs);
+  skippedArches.ros2 = await exportRos2Build(root, archs) ?? [];
+  skippedArches.cpp  = await exportCppBuild(root, distDir, archs) ?? [];
   calcInstalledSize(pluginRoot);
   if (!noZip) packZip(pluginRoot);
+
+  // Build summary
+  const allSkipped = [...new Set([...skippedArches.wheels, ...skippedArches.ros2, ...skippedArches.cpp])];
+  if (allSkipped.length > 0) {
+    const line = "─".repeat(58);
+    console.log(`\n${line}`);
+    log.warn(`Cross-arch builds skipped (QEMU not available): ${allSkipped.join(", ")}`);
+    if (skippedArches.wheels.length) log.warn(`  wheels:  ${skippedArches.wheels.join(", ")}`);
+    if (skippedArches.ros2.length)   log.warn(`  ros2:    ${skippedArches.ros2.join(", ")}`);
+    if (skippedArches.cpp.length)    log.warn(`  cpp:     ${skippedArches.cpp.join(", ")}`);
+    log.warn(`  Enable: docker run --privileged --rm tonistiigi/binfmt --install all`);
+    console.log(line);
+  }
 }

package/cli/src/dev.mjs

@@ -1,19 +1,29 @@
 // muscat-pk dev — run the Socket.IO bridge (Docker), dev:ui, and dev:back together.
 import { runDevUi } from "./devUi.mjs";
 import { runDevBack } from "./devBack.mjs";
-import { startBridge, stopBridge, BRIDGE_CONTAINER } from "./bridge.mjs";
-import { ensureDocker, log } from "./util.mjs";
+import { startBridge, stopBridge, BRIDGE_CONTAINER, BRIDGE_PORT } from "./bridge.mjs";
+import { ensureDocker, log, prompt, promptRobotConnection } from "./util.mjs";
 
 export async function runDev(args = []) {
   ensureDocker();
+  const { robotIp, robotToken } = await promptRobotConnection(args);
+  if (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");
-  await startBridge();
+  const bridgeStarted = await startBridge();
 
-  // Tell dev:back which bridge container to share a netns with, so the backend
-  // reaches the bridge at localhost:10000 (no host.docker.internal).
-  process.env.MUSCAT_PK_BRIDGE_CONTAINER = BRIDGE_CONTAINER;
+  if (!bridgeStarted) {
+    log.warn(`port ${BRIDGE_PORT} is already in use — can't start Socket.IO bridge.`);
+    const answer = await prompt("  Proceed without Socket.IO bridge? [y/N]: ");
+    if (answer.toLowerCase() !== "y") return;
+    log.info("proceeding without bridge — backend will skip network sharing.");
+  } else {
+    // Tell dev:back which bridge container to share a netns with, so the backend
+    // reaches the bridge at localhost:10000 (no host.docker.internal).
+    process.env.MUSCAT_PK_BRIDGE_CONTAINER = BRIDGE_CONTAINER;
+  }
 
-  const cleanup = () => stopBridge();
+  const cleanup = () => { if (bridgeStarted) stopBridge(); };
   process.once("SIGINT", cleanup);
   process.once("SIGTERM", cleanup);
   process.once("exit", cleanup);

package/cli/src/devBack.mjs

@@ -10,7 +10,7 @@
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync, watch } from "node:fs";
 import { resolve } from "node:path";
-import { ensureDocker, findPluginRoot, log } from "./util.mjs";
+import { ensureDocker, findPluginRoot, log, promptRobotConnection } from "./util.mjs";
 import { manifestRuntime, readManifest, validateManifest } from "./manifest.mjs";
 import {
   PYTHON_DEV_IMAGE,
@@ -40,7 +40,13 @@ async function runPython(root) {
   const manifest = readManifest(root);
   const pluginId = manifest.id ?? "";
   const container = `${PYTHON_DEV_IMAGE}-run`;
-  const envFlags = pluginId ? ["-e", `RB_PLUGIN_ID=${pluginId}`] : [];
+  const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
+  const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
+  const envFlags = [
+    ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
+    ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
+    ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
+  ];
   // 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.
   const bridgeContainer = process.env.MUSCAT_PK_BRIDGE_CONTAINER;
@@ -105,7 +111,13 @@ async function runRos2(root) {
   const pluginId = manifest.id ?? "";
   const isRclcpp = manifest.runtime?.rosClient === "rclcpp";
   const container = `${ROS2_DEV_IMAGE}-run`;
-  const envFlags = pluginId ? ["-e", `RB_PLUGIN_ID=${pluginId}`] : [];
+  const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
+  const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
+  const envFlags = [
+    ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
+    ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
+    ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
+  ];
   const docker = (args, opts = {}) =>
     spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
 
@@ -177,7 +189,13 @@ async function runCpp(root) {
 
   const pluginId = manifest.id ?? "";
   const container = `${CPP_DEV_IMAGE}-run`;
-  const envFlags = pluginId ? ["-e", `RB_PLUGIN_ID=${pluginId}`] : [];
+  const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
+  const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
+  const envFlags = [
+    ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
+    ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
+    ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
+  ];
   const docker = (args, opts = {}) =>
     spawnSync("docker", args, { cwd: root, stdio: "inherit", ...opts });
 
@@ -240,10 +258,13 @@ function warnManifest(root) {
   for (const e of errors) log.warn(`manifest.json: ${e}`);
 }
 
-export async function runDevBack() {
+export async function runDevBack(args = []) {
   ensureDocker();
   const root = findPluginRoot();
   warnManifest(root);
+  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);

package/cli/src/devUi.mjs

@@ -7,7 +7,7 @@ import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { SANDBOX_HTML } from "./build.mjs";
-import { checkKitUpdate, findPluginRoot, hasBin, kitRoot, log } from "./util.mjs";
+import { checkKitUpdate, findPluginRoot, hasBin, kitRoot, log, parseArgs, prompt } from "./util.mjs";
 
 const PREVIEW_PKG = "@rainbow-robotics/preview-host";
 const CACHE_DIR = resolve(homedir(), ".muscat-pk");
@@ -79,7 +79,7 @@ function findViteBin(pluginRoot) {
 
 // Spawn vite build --watch as a background process.
 // Returns the child process, or null if vite/node not available.
-function spawnViteWatch(pluginRoot, node) {
+function spawnViteWatch(pluginRoot, node, { robotIp = "" } = {}) {
   const viteBin = findViteBin(pluginRoot);
   if (!node || !viteBin || !existsSync(viteBin)) return null;
 
@@ -87,6 +87,7 @@ function spawnViteWatch(pluginRoot, node) {
   return spawn(node, [viteBin, "build", "--watch", "--mode", "development", "--outDir", DEV_OUT], {
     cwd: pluginRoot,
     stdio: "inherit",
+    env: { ...process.env, ...(robotIp ? { VITE_RRS_PY_HOST: robotIp } : {}) },
   });
 }
 
@@ -105,15 +106,18 @@ function waitForInitialBuild(distDir, timeoutMs = 30_000) {
 }
 
 export async function runDevUi(args = []) {
-  const portIdx = args.indexOf("--port");
-  const port = portIdx !== -1 ? args[portIdx + 1] : "4180";
+  const parsed = parseArgs(args);
+  const port = parsed.port ?? "4180";
+  const robotIp = parsed["robot-ip"] ?? process.env.MUSCAT_ROBOT_HOST ?? await prompt("  Robot IP (skip if no robot): ");
 
   await checkKitUpdate();
   const pluginRoot = findPluginRoot();
   const outDir = stageDevAssets(pluginRoot);
 
+  if (robotIp) log.info(`MUSCAT_API_ORIGIN → http://${robotIp}:*`);
+
   const node = findNodeBin();
-  const viteProc = spawnViteWatch(pluginRoot, node);
+  const viteProc = spawnViteWatch(pluginRoot, node, { robotIp });
 
   if (viteProc) {
     log.step("waiting for initial vite build…");

package/cli/src/python.mjs

@@ -27,22 +27,30 @@ export async function ensureImage(image = PYTHON_DEV_IMAGE, { platform = null }
   pruneMuskatImages();
 }
 
-// Docker --platform 플래그: 컨테이너를 target arch로 띄우면
-// pip이 glibc + arch를 자동 감지해 올바른 휠을 받는다.
-const ARCH_DOCKER_PLATFORM = {
-  amd64: "linux/amd64",
-  arm64: "linux/arm64",
+// pip --platform does NOT auto-expand manylinux tags (unlike sys_tags()) — exact match only.
+// Specifying all common glibc milestones ensures packages built for any Ubuntu era are found.
+const PIP_PLATFORM = {
+  amd64: [
+    "manylinux_2_5_x86_64",
+    "manylinux_2_17_x86_64",
+    "manylinux_2_27_x86_64",
+    "manylinux_2_28_x86_64",
+    "manylinux_2_34_x86_64",
+    "manylinux_2_39_x86_64",
+    "linux_x86_64",
+  ],
+  arm64: [
+    "manylinux_2_17_aarch64",
+    "manylinux_2_27_aarch64",
+    "manylinux_2_28_aarch64",
+    "manylinux_2_34_aarch64",
+    "manylinux_2_39_aarch64",
+    "linux_aarch64",
+  ],
 };
 
-/**
- * Ubuntu 24.04 + py3.12 컨테이너 안에서:
- *   1. uv pip compile requirements.txt → dist/requirements.lock  (arch 무관, 1회)
- *   2. archs별 pip download --platform <manylinux_tag> → dist/wheels/  (네이티브 휠 벤더링)
- *
- * none-any 휠은 pip이 두 번째 arch에서 자동 skip → 중복 없음.
- * requirements.txt 없으면 조용히 건너뜀.
- */
-export async function lockAndVendor(pluginRoot, archs = ["x86_64", "aarch64"]) {
+export async function lockAndVendor(pluginRoot, archs = ["amd64", "arm64"]) {
+  // ponytail: pip --platform used intentionally (not QEMU) — downloads wheels without running target arch code.
   const reqTxt = resolve(pluginRoot, "requirements.txt");
   if (!existsSync(reqTxt)) {
     log.warn("requirements.txt not found — lock/vendor skipped");
@@ -66,45 +74,28 @@ export async function lockAndVendor(pluginRoot, archs = ["x86_64", "aarch64"]) {
   if (lockResult.status !== 0) throw new Error("lock generation failed (uv pip compile)");
   log.ok("dist/requirements.lock ready");
 
-  // arch별 휠 벤더링 — QEMU 불필요 (download only, --platform 고정)
-  // 한 arch가 실패해도 나머지 arch는 계속 시도한다.
   const failed = [];
   for (const arch of archs) {
-    const dockerPlatform = ARCH_DOCKER_PLATFORM[arch];
-    if (!dockerPlatform) {
-      log.warn(`unknown arch '${arch}' — skipped`);
-      continue;
-    }
-    // arch별 이미지 빌드 (--platform 지정) → pip이 glibc+arch 자동 감지 → 올바른 휠 선택.
-    const archImage = `${PYTHON_DEV_IMAGE}-${arch}`;
-    await ensureImage(archImage, { platform: dockerPlatform });
-
-    log.step(`vendoring wheels for ${arch} (${dockerPlatform})…`);
-    // 패키지별 개별 download로 private/미공개 패키지 실패 시에도 나머지 계속 진행.
-    const script = [
-      `set -e`,
-      `cd /plugin`,
-      `mkdir -p dist/wheels`,
-      `pkgs=$(grep -v '^#' dist/requirements.lock | grep -v '^[[:space:]]' | grep -v '^$')`,
-      `SKIP=""`,
-      `for pkg in $pkgs; do`,
-      `  pip3 download "$pkg" --no-deps --only-binary=:all: -d dist/wheels -q 2>&1 || SKIP="$SKIP $pkg"`,
-      `done`,
-      `[ -z "$SKIP" ] || echo "WARN: no wheel found (package not on PyPI or missing binary wheel):$SKIP"`,
-    ].join("\n");
+    const pipPlatforms = PIP_PLATFORM[arch];
+    if (!pipPlatforms) { log.warn(`unknown arch '${arch}' — skipped`); continue; }
+    log.step(`vendoring wheels for ${arch}…`);
     const r = spawnSync(
       "docker",
       [
         "run", "--rm",
-        "--platform", dockerPlatform,
+        "-e", "PIP_ROOT_USER_ACTION=ignore",
         "-v", `${pluginRoot}:/plugin`,
-        archImage,
-        "bash", "-c", script,
+        "-w", "/plugin",
+        PYTHON_DEV_IMAGE,
+        "bash", "-c",
+        "mkdir -p dist/wheels && pip3 download -r dist/requirements.lock --no-deps --only-binary=:all: -d dist/wheels -q " +
+          "--python-version 312 --implementation cp --abi cp312 " +
+          pipPlatforms.map((p) => `--platform ${p}`).join(" "),
       ],
       { stdio: "inherit" },
     );
     if (r.status !== 0) {
-      log.warn(`wheel vendoring failed for ${arch} — some packages may not have manylinux wheels`);
+      log.warn(`wheel vendoring failed for ${arch}`);
       failed.push(arch);
     } else {
       log.ok(`dist/wheels/ ready (${arch})`);
@@ -114,9 +105,5 @@ export async function lockAndVendor(pluginRoot, archs = ["x86_64", "aarch64"]) {
   if (failed.length === archs.length) {
     throw new Error(`wheel vendoring failed for all archs: ${failed.join(", ")}`);
   }
-  if (failed.length > 0) {
-    log.warn(`wheel vendoring partial — failed: ${failed.join(", ")}, ok: ${archs.filter((a) => !failed.includes(a)).join(", ")}`);
-  } else {
-    log.ok(`dist/wheels/ ready (${archs.join(", ")})`);
-  }
+  return failed;
 }

package/cli/src/util.mjs

@@ -76,6 +76,31 @@ export async function prompt(question, fallback = "") {
   return answer || fallback;
 }
 
+const LOCAL_HOSTS = new Set(["", "localhost", "127.0.0.1", "::1"]);
+
+/**
+ * Ask for robot IP (and token if remote). Returns { robotIp, robotToken }.
+ * Skips prompts if already set in process.env (from a parent command like `dev`).
+ * Supports --robot-ip / --robot-token flags for non-interactive use.
+ */
+export async function promptRobotConnection(args = []) {
+  const parsed = parseArgs(args);
+  const robotIp =
+    parsed["robot-ip"] ??
+    process.env.MUSCAT_ROBOT_HOST ??
+    (await prompt("  Robot IP (skip if no robot): "));
+
+  if (LOCAL_HOSTS.has(robotIp)) return { robotIp, robotToken: "" };
+
+  const robotToken =
+    parsed["robot-token"] ??
+    process.env.MUSCAT_ROBOT_TOKEN ??
+    (await prompt("  SDK Token (required for remote): "));
+
+  if (!robotToken) throw new Error("SDK token is required for remote robot connection.");
+  return { robotIp, robotToken };
+}
+
 /** Walk up from cwd to find the plugin project root (has manifest.json). */
 export function findPluginRoot(start = process.cwd()) {
   let dir = resolve(start);

package/cli/templates/common/README.md

@@ -99,6 +99,26 @@ connect(App);
 
 ---
 
+## Developing directly on the robot PC
+
+If you're running `muscat-pk dev` **on the robot PC itself**, Muscat is likely already
+running its own Socket.IO bridge on port 10000. In that case the CLI detects the port
+conflict and asks:
+
+```
+⚠ port 10000 is already in use — can't start Socket.IO bridge.
+  Proceed without Socket.IO bridge? [y/N]:
+```
+
+Answer **y**. Your plugin backend will connect to the Muscat bridge that's already
+running instead of starting a new one — exactly what you want when developing on the
+robot.
+
+> If you answer **n** (or just press Enter), the CLI exits so you can free the port
+> manually and retry.
+
+---
+
 ## Backend (`py/main.py`)
 
 The backend communicates with the frontend using `rainbow.rb_sdk.RBPluginCall`.

package/cli/templates/common/py/main.py

@@ -1,15 +1,19 @@
 """
 Muscat plugin backend — __PLUGIN_NAME__
 
-Run with:
+On-robot (default):
   muscat-pk dev:back
   python main.py
 
-This template uses the high-level Rainbow Python SDK instead of wiring the
-transport layer directly.
+Remote dev (from your laptop):
+  Set env vars before running:
+    MUSCAT_ROBOT_HOST=192.168.1.100
+    MUSCAT_ROBOT_TOKEN=<service token>
+  Then: muscat-pk dev:back
 """
 
-import time
+import asyncio
+import os
 from typing import Any
 
 from rainbow.rb_sdk import RBManipulateSDK, RBPluginCall
@@ -18,40 +22,30 @@ from rainbow.rb_sdk import RBManipulateSDK, RBPluginCall
 PLUGIN_NAME = "__PLUGIN_NAME__"
 
 plugin = RBPluginCall()
+manipulate = RBManipulateSDK()
 
 
-@plugin.subscribe("event")
-def on_ui_event(payload: dict[str, Any] | None = None):
-    """Handle messages published from the plugin UI with rb.pub("event", ...)."""
-    print(f"[{PLUGIN_NAME}] event:", payload)
+def register_handlers():
+    # Register handlers here — called after connect() so subscriptions survive
+    # session reconnection in remote-dev mode.
 
+    @plugin.subscribe("event")
+    def on_ui_event(payload: dict[str, Any] | None = None):
+        """Handle messages published from the plugin UI with rb.pub("event", ...)."""
+        print(f"[{PLUGIN_NAME}] event:", payload)
 
-@plugin.serve("grip")
-def grip(payload: dict[str, Any] | None = None):
-    """Handle the default UI button: rb.action("grip", { width })."""
-    width = (payload or {}).get("width", 20)
-    print(f"[{PLUGIN_NAME}] grip requested: width={width}")
+    @plugin.serve("grip")
+    def grip(payload: dict[str, Any] | None = None):
+        """Handle the default UI button: rb.action("grip", { width })."""
+        width = (payload or {}).get("width", 20)
+        print(f"[{PLUGIN_NAME}] grip requested: width={width}")
+        plugin.publish("state", {"ready": True, "last_grip_width": width})
+        return {"ok": True, "width": width}
 
-    plugin.publish("state", {"ready": True, "last_grip_width": width})
-    return {"ok": True, "width": width}
-
-
-@plugin.serve("tool/echo")
-def echo(payload: dict[str, Any] | None = None):
-    """Small query example callable from the UI with rb.action("tool/echo", ...)."""
-    return {"echo": payload, "plugin": PLUGIN_NAME}
-
-
-def ping_ui_example():
-    """
-    Example: call a queryable served by the UI.
-
-    In the frontend, register:
-      rb.serve("tool/ping", async (payload) => ({ pong: payload }))
-    """
-    res = plugin.call("tool/ping", payload={"hello": "plugin"})
-    print(f"[{PLUGIN_NAME}] ping response:", res)
-    return res
+    @plugin.serve("tool/echo")
+    def echo(payload: dict[str, Any] | None = None):
+        """Small query example callable from the UI with rb.action("tool/echo", ...)."""
+        return {"echo": payload, "plugin": PLUGIN_NAME}
 
 
 def move_j_example():
@@ -61,8 +55,6 @@ def move_j_example():
     This function is not called automatically. Add safety checks and call it
     from your own handler when the robot is ready.
     """
-    manipulate = RBManipulateSDK()
-
     return manipulate.move.call_move_j(
         robot_model="C500920",
         target={
@@ -73,16 +65,34 @@ def move_j_example():
     )
 
 
-def main():
+async def main():
+    robot_host = os.getenv("MUSCAT_ROBOT_HOST")
+    robot_token = os.getenv("MUSCAT_ROBOT_TOKEN")
+
+    if robot_host and robot_token:
+        # Remote dev: connect to the robot before registering any handlers.
+        # connect() closes and reopens the Zenoh session, so handlers registered
+        # before this call would be lost.
+        await manipulate.connect(token=robot_token, host=robot_host)
+
+    register_handlers()
+
     plugin.publish("state", {"ready": True, "plugin": PLUGIN_NAME})
     print(f"[{PLUGIN_NAME}] backend ready")
 
     try:
         while True:
-            time.sleep(1)
-    except KeyboardInterrupt:
+            await asyncio.sleep(1)
+    except (KeyboardInterrupt, asyncio.CancelledError):
+        pass
+    finally:
+        if robot_host and robot_token:
+            await manipulate.disconnect()
         print(f"[{PLUGIN_NAME}] stopped")
 
 
 if __name__ == "__main__":
-    main()
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainbow-robotics/muscat-plugin-kit",
-  "version": "0.1.2-dev.41",
+  "version": "0.1.2-dev.43",
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -31,7 +31,7 @@
     "@types/react-dom": "^19.0.4"
   },
   "dependencies": {
-    "@rainbow-robotics/preview-host": "0.1.2-dev.41",
+    "@rainbow-robotics/preview-host": "0.1.2-dev.43",
     "socket.io": "^4.8.1"
   },
   "optionalDependencies": {

package/cli/src/preview.mjs

@@ -1,91 +0,0 @@
-// muscat-pk preview — build the plugin and open preview-host connected to a
-// real Muscat server (robot or local). No local Socket.IO server is started.
-import { createInterface } from "node:readline";
-import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
-import { buildPlugin } from "./build.mjs";
-import { findPreviewHostRoot } from "./devUi.mjs";
-import { checkKitUpdate, log, parseArgs } from "./util.mjs";
-
-function prompt(question, defaultValue) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((res) => {
-    rl.question(question, (answer) => {
-      rl.close();
-      res(answer.trim() || defaultValue);
-    });
-  });
-}
-
-export async function runPreview(args = []) {
-  const opts = parseArgs(args, { booleans: ["help"] });
-
-  if (opts.help) {
-    console.log(
-      [
-        "",
-        "Usage: muscat-pk preview [options]",
-        "",
-        "  빌드된 플러그인을 실제 Muscat 서버에 연결해 미리봅니다.",
-        "  Socket.IO 서버를 직접 띄우지 않습니다.",
-        "",
-        "Options:",
-        "  --host <ip>    Muscat 서버 IP 또는 hostname (default: localhost)",
-        "  --port <n>     preview-host 로컬 포트 (default: 4180)",
-        "  --ws-port <n>  Muscat Socket.IO 포트 (default: 10000)",
-        "",
-      ].join("\n"),
-    );
-    return;
-  }
-
-  await checkKitUpdate();
-
-  // ── 로봇 IP 결정 ────────────────────────────────────────────────────────────
-  let robotHost = opts.host ?? "";
-  if (!robotHost) {
-    robotHost = await prompt(
-      "Muscat 서버 IP 또는 hostname [localhost]: ",
-      "localhost",
-    );
-  }
-  const wsPort = opts["ws-port"] ?? "10000";
-  const socketUrl = `ws://${robotHost}:${wsPort}`;
-
-  const previewPort = opts.port ?? "4180";
-
-  log.step(`Muscat 서버: ${socketUrl}`);
-
-  // ── 플러그인 빌드 ────────────────────────────────────────────────────────────
-  const { distDir } = await buildPlugin();
-
-  // ── preview-host 실행 ────────────────────────────────────────────────────────
-  const previewRoot = findPreviewHostRoot();
-  const serveEntry = resolve(previewRoot, "serve.mjs");
-
-  if (!existsSync(resolve(previewRoot, "dist", "index.html"))) {
-    log.step("preview-host 번들 빌드 중 (최초 1회)…");
-    await new Promise((res, rej) => {
-      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"))));
-    });
-  }
-
-  log.step(`preview-host 시작 → http://localhost:${previewPort}`);
-  log.step(`Socket.IO URL: ${socketUrl}`);
-
-  const child = spawn(
-    process.execPath,
-    [
-      serveEntry,
-      "--plugin", distDir,
-      "--port", String(previewPort),
-      "--socket-url", socketUrl,
-    ],
-    { stdio: "inherit" },
-  );
-  child.on("exit", (code) => process.exit(code ?? 0));
-}