@rainbow-robotics/muscat-plugin-kit 1.3.6-dev.8 → 1.3.7

package/cli/src/ports.mjs

@@ -4,7 +4,15 @@ import { usesHostNetwork } from "./zenohDev.mjs";
 
 export const PLUGIN_PORT_MIN = 28600;
 export const PLUGIN_PORT_MAX = 28999;
-export const INTERNAL_DEV_PORTS = new Set([10000]);
+export const MEDIA_PORTS = [8554, 8889, 8189]; // MediaMTX: RTSP publish, WebRTC, WebRTC media
+export const INTERNAL_DEV_PORTS = new Set([10000, ...MEDIA_PORTS]);
+
+export function mediaPortFlags() {
+  return [
+    "-p", "127.0.0.1:8554:8554", "-p", "127.0.0.1:8889:8889",
+    "-p", "127.0.0.1:8189:8189/udp", "-p", "127.0.0.1:8189:8189/tcp",
+  ];
+}
 export const RESERVED_BACKEND_PORTS = new Map([
   [502, "Modbus TCP"],
   [4840, "OPC-UA"],
@@ -118,14 +126,21 @@ export function publishPortFlags(ranges = []) {
   return ranges.flatMap((port) => ["-p", `127.0.0.1:${port}:${port}`]);
 }
 
+// Skips OS-assigned loopback listeners (127.0.0.1:0, e.g. the SDK's Zenoh session).
 function listeningTcpPorts(container) {
   const script = `
+read -r eph_lo eph_hi < /proc/sys/net/ipv4/ip_local_port_range 2>/dev/null || { eph_lo=32768; eph_hi=60999; }
 for f in /proc/net/tcp /proc/net/tcp6; do
   [ -r "$f" ] || continue
   tail -n +2 "$f" | while read -r sl local_address rem_address st rest; do
     [ "$st" = "0A" ] || continue
-    hex_port="\${local_address##*:}"
-    printf "%d\\n" "0x$hex_port"
+    hex_ip="\${local_address%%:*}"
+    port=$((0x\${local_address##*:}))
+    case "$hex_ip" in
+      0100007F|00000000000000000000000001000000)
+        [ "$port" -ge "$eph_lo" ] && [ "$port" -le "$eph_hi" ] && continue ;;
+    esac
+    echo "$port"
   done
 done | sort -n -u
 `;
@@ -141,10 +156,9 @@ done | sort -n -u
 }
 
 export function startPortContractMonitor({ container, ranges, log, intervalMs = 1000, allow = [] }) {
-  // Under --network host the container shares the host's netns, so
-  // /proc/net/tcp shows every host/robot service port, not just the plugin's —
-  // the contract can't be enforced. Skip it (no isolated ports to police).
-  if (usesHostNetwork()) return () => false;
+  // Under --network host (or a local Muscat container's netns) /proc/net/tcp shows every
+  // host/robot service port, not just the plugin's — the contract can't be enforced.
+  if (usesHostNetwork() || process.env.MUSCAT_PK_MUSCAT_CONTAINER) return () => false;
   const declared = ranges ?? [];
   // muscat-pk's own dev plumbing shares this netns — not the plugin's doing.
   const ignored = new Set([...INTERNAL_DEV_PORTS, ...allow.map(Number).filter(Number.isInteger)]);

package/cli/src/python.mjs

@@ -1,9 +1,9 @@
 // Shared Python Docker helpers (Ubuntu 24.04 + Python 3.12 — matches the robot).
 // Used by dev:back (hot-reload) and build (lock + wheel vendor).
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { canSkipImageBuild, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+import { canSkipImageBuild, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
 
 export const PYTHON_DEV_IMAGE = "muscat-pk-python-dev";
 
@@ -15,16 +15,17 @@ export function assertDockerReady() {
 
 /** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
 export async function ensureImage(image = PYTHON_DEV_IMAGE, { platform = null } = {}) {
-  if (canSkipImageBuild(image)) {
+  const dockerfile = await resolveDockerfile("Dockerfile.python");
+  const key = imageKey(dockerfile);
+  if (canSkipImageBuild(image, key)) {
     log.step(`${image} already built — skipping docker build`);
     return;
   }
-  const dockerfile = await resolveDockerfile("Dockerfile.python");
   log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
   const platformFlags = platform ? ["--platform", platform] : [];
   const r = spawnSync(
     "docker",
-    ["build", ...platformFlags, "-t", image, "-f", dockerfile, dirname(dockerfile)],
+    ["build", ...platformFlags, ...imageKeyLabel(key), "-t", image, "-f", dockerfile, dirname(dockerfile)],
     { stdio: "inherit" },
   );
   if (r.status !== 0) throw new Error("docker build failed.");
@@ -65,7 +66,11 @@ export async function lockAndVendor(pluginRoot, archs = ["amd64", "arm64"]) {
 
   await ensureImage();
 
-  log.step("generating lock (uv pip compile)…");
+  // A pinned pre-release (e.g. rainbow-rb-sdk==0.1.4.dev1) pins its sibling rainbow-rb-*
+  // pre-releases too; uv rejects those transitive pre-releases unless allowed.
+  const reqText = readFileSync(resolve(pluginRoot, "requirements.txt"), "utf8");
+  const prerelease = /==\s*\S*\d(a|b|rc|\.dev)\d*\s*$/im.test(reqText) ? " --prerelease=allow" : "";
+  log.step(`generating lock (uv pip compile${prerelease})…`);
   const lockResult = spawnSync(
     "docker",
     [
@@ -74,17 +79,16 @@ export async function lockAndVendor(pluginRoot, archs = ["amd64", "arm64"]) {
       "-v", `${pluginRoot}:/plugin`,
       PYTHON_DEV_IMAGE,
       "bash", "-c",
-      "set -e && cd /plugin && mkdir -p dist && uv pip compile requirements.txt --python-version 3.12 -o dist/requirements.lock",
+      "set -e && cd /plugin && mkdir -p dist && uv pip compile requirements.txt --python-version 3.12 -o dist/requirements.lock" + prerelease,
     ],
     { stdio: "inherit" },
   );
   if (lockResult.status !== 0) throw new Error("lock generation failed (uv pip compile)");
   log.ok("dist/requirements.lock ready");
 
-  const failed = [];
   for (const arch of archs) {
     const pipPlatforms = PIP_PLATFORM[arch];
-    if (!pipPlatforms) { log.warn(`unknown arch '${arch}' — skipped`); continue; }
+    if (!pipPlatforms) throw new Error(`unknown arch '${arch}'`);
     log.step(`vendoring wheels for ${arch}…`);
     const r = spawnSync(
       "docker",
@@ -102,16 +106,8 @@ export async function lockAndVendor(pluginRoot, archs = ["amd64", "arm64"]) {
       ],
       { stdio: "inherit" },
     );
-    if (r.status !== 0) {
-      log.warn(`wheel vendoring failed for ${arch}`);
-      failed.push(arch);
-    } else {
-      log.ok(`dist/wheels/ ready (${arch})`);
-    }
-  }
-
-  if (failed.length === archs.length) {
-    throw new Error(`wheel vendoring failed for all archs: ${failed.join(", ")}`);
+    // A ZIP missing wheels fails to import on the robot — stop instead.
+    if (r.status !== 0) throw new Error(`wheel download failed for ${arch} (see pip output above)`);
+    log.ok(`dist/wheels/ ready (${arch})`);
   }
-  return failed;
 }

package/cli/src/ros2.mjs

@@ -3,7 +3,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { canSkipImageBuild, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+import { canSkipImageBuild, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
 
 export const ROS2_DEV_IMAGE = "muscat-pk-ros2-dev";
 
@@ -30,16 +30,19 @@ export const ARCH_DOCKER_PLATFORM = {
 
 /** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
 export async function ensureImage(image = ROS2_DEV_IMAGE, { platform = null } = {}) {
-  if (canSkipImageBuild(image)) {
+  const dockerfile = await resolveDockerfile("Dockerfile.dev");
+  const sdkVer = process.env.MUSCAT_PK_RB_SDK_VERSION;
+  const key = imageKey(dockerfile, sdkVer ?? "");
+  if (canSkipImageBuild(image, key)) {
     log.step(`${image} already built — skipping docker build`);
     return;
   }
-  const dockerfile = await resolveDockerfile("Dockerfile.dev");
   log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
   const platformFlags = platform ? ["--platform", platform] : [];
+  const buildArgs = [...(sdkVer ? ["--build-arg", `RB_SDK_VERSION=${sdkVer}`] : []), ...imageKeyLabel(key)];
   const r = spawnSync(
     "docker",
-    ["build", ...platformFlags, "-t", image, "-f", dockerfile, dirname(dockerfile)],
+    ["build", ...platformFlags, ...buildArgs, "-t", image, "-f", dockerfile, dirname(dockerfile)],
     { stdio: "inherit" },
   );
   if (r.status !== 0) throw new Error("docker build failed.");
@@ -71,12 +74,16 @@ export function colconBuild(root, { image = ROS2_DEV_IMAGE, symlink = false, arc
     installBase = "../dist/ros2_ws/install";
   }
   const flag = symlink ? "--symlink-install" : "";
+  const buildBase = symlink ? "build" : arch ? `build-${arch}` : "build-dist";
   const script = [
     "pip install -r requirements.txt --break-system-packages --ignore-installed -q || true",
     "cd ros2_ws",
-    // ponytail: rm only on cross-arch; same-arch dev rebuilds keep the cache
-    ...(arch ? ["rm -rf build"] : []),
-    `colcon build ${flag} --install-base ${installBase}`.trim(),
+    // Export builds use their own build cache: sharing build/ with dev's --symlink-install
+    // (or another arch) breaks the next colcon build.
+    // rclcpp export: ship librb_sdk.so in <pkg>/lib/ (robot has no SDK) when the node links it.
+    `colcon build ${flag} --build-base ${buildBase} --install-base ${installBase}`.replace("  ", " ") +
+      (arch ? ` --cmake-args '-DCMAKE_INSTALL_RPATH=$ORIGIN/..'` : ""),
+    ...(arch ? [`for d in ${installBase}/*/lib; do if readelf -d $(find "$d" -mindepth 2 -type f -executable) 2>/dev/null | grep -q librb_sdk; then cp -a $(dpkg -L rainbow-rb-sdk | grep -E '/librb_sdk[.]so[.][0-9]') "$d"/; fi; done`] : []),
   ].join(" && ");
   const label = arch
     ? `colcon build (${arch}) → dist/ros2_ws/install-${arch}/…`
@@ -87,7 +94,8 @@ export function colconBuild(root, { image = ROS2_DEV_IMAGE, symlink = false, arc
   const platformFlags = dockerPlatform ? ["--platform", dockerPlatform] : [];
   const r = spawnSync(
     "docker",
-    ["run", "--rm", ...platformFlags, "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", actualImage, "bash", "-lc", script],
+    // python/cpp 와 같이 호스트 uid 로 돌린다 — root 소유 산출물이 남으면 사용자가 지우지 못한다.
+    ["run", "--rm", ...platformFlags, ...dockerUserFlags(), "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", actualImage, "bash", "-lc", script],
     { cwd: root, stdio: "inherit" },
   );
   if (r.status !== 0) throw new Error(`colcon build failed${arch ? ` (${arch})` : ""}.`);

package/cli/src/sdk.mjs

@@ -6,24 +6,24 @@
 // the new version immediately; this is best-effort only.
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { spawnSync } from "node:child_process";
-import { findPluginRoot, log, venvPython } from "./util.mjs";
+import { ensureIdeVenv, findPluginRoot, log, venvPython } from "./util.mjs";
 
 const PKG = "rainbow-rb-sdk";
 
-async function fetchVersions() {
+async function fetchPypi() {
   try {
     const res = await fetch(`https://pypi.org/pypi/${PKG}/json`);
-    if (!res.ok) return [];
-    const data = await res.json();
-    return Object.keys(data.releases || {}).sort((a, b) =>
-      b.localeCompare(a, undefined, { numeric: true }),
-    );
+    return res.ok ? await res.json() : null;
   } catch {
-    return [];
+    return null;
   }
 }
 
+async function fetchVersions() {
+  const data = await fetchPypi();
+  return Object.keys(data?.releases || {}).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+}
+
 export async function runSdk(args = []) {
   const sub = args[0];
   const root = findPluginRoot();
@@ -42,23 +42,25 @@ export async function runSdk(args = []) {
   if (sub === "update") {
     let version = args[1];
     if (!version) {
-      const versions = await fetchVersions();
-      version = versions[0] || "latest";
+      // info.version = latest stable
+      version = (await fetchPypi())?.info?.version;
+      if (!version) throw new Error("could not fetch the latest version (offline?). Pass one: muscat-pk sdk update <version>");
     }
+    // rainbow-rb-* pin each other exactly — bump them together.
     let content = existsSync(reqs) ? readFileSync(reqs, "utf8") : "";
-    const line = `${PKG}==${version}`;
-    if (new RegExp(`^${PKG}==`, "m").test(content)) {
-      content = content.replace(new RegExp(`^${PKG}==.*$`, "m"), line);
-    } else {
-      content = (content ? content.trimEnd() + "\n" : "") + line + "\n";
+    const pinned = /^(rainbow-rb-[\w-]+)\s*==.*$/gim;
+    const bumped = [...content.matchAll(pinned)].map((m) => m[1]);
+    content = content.replace(pinned, (_m, name) => `${name}==${version}`);
+    if (!bumped.some((n) => n.toLowerCase() === PKG)) {
+      content = (content ? content.trimEnd() + "\n" : "") + `${PKG}==${version}\n`;
+      bumped.push(PKG);
     }
     writeFileSync(reqs, content);
-    log.ok(`requirements.txt → ${line}`);
+    log.ok(`requirements.txt → ${bumped.map((n) => `${n}==${version}`).join(", ")}`);
 
-    const py = venvPython(resolve(root, ".venv"));
-    if (existsSync(py)) {
-      log.step("pip install -r requirements.txt (.venv, for your editor)…");
-      spawnSync(py, ["-m", "pip", "install", "-q", "-r", reqs], { cwd: root, stdio: "inherit" });
+    if (existsSync(venvPython(resolve(root, ".venv")))) {
+      log.step("refreshing .venv (for your editor)…");
+      if (!ensureIdeVenv(root)) log.warn(".venv refresh failed — the Docker dev container is unaffected.");
     } else {
       log.info("Installed automatically on the next `muscat-pk dev` / `dev:back` (Docker container).");
     }

package/cli/src/type.mjs

@@ -2,12 +2,14 @@
 //   python | cpp | ros2 (rclpy) | ros2-cpp (rclcpp).
 //   Adds the matching backend overlay; never deletes existing user code
 //   (e.g. ros2_ws/ or cpp/ are left in place when switching away).
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, resolve } from "node:path";
-import { findPluginRoot, log, prompt } from "./util.mjs";
+import { copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { findPluginRoot, log, prompt, templatesDir } from "./util.mjs";
 import {
   TYPE_CHOICES,
   applyTokens,
+  copyTemplate,
   deriveNames,
   overlayCpp,
   overlayRos2,
@@ -28,6 +30,28 @@ function currentTypeKey(runtime) {
   return runtime?.type ?? "python";
 }
 
+const isCpp = (key) => key === "cpp" || key === "ros2-cpp";
+
+async function offerReadme(root, toCpp, force, tokens) {
+  const lang = toCpp ? "C++" : "Python";
+  const answer = force ? "y" : await prompt(`Replace README.md with the ${lang} backend version? (current file kept as README.md.bak) [y/N]: `, "n");
+  if (!/^y/i.test(answer)) {
+    log.info(`README.md kept — to swap it later: muscat-pk type change --to <type> --readme`);
+    return;
+  }
+  const tmp = mkdtempSync(join(tmpdir(), "muscat-pk-readme-"));
+  try {
+    await copyTemplate(resolve(templatesDir, toCpp ? "readme-cpp" : "common"), tmp);
+    applyTokens(tmp, tokens);
+    const readme = resolve(root, "README.md");
+    if (existsSync(readme)) copyFileSync(readme, resolve(root, "README.md.bak"));
+    copyFileSync(join(tmp, "README.md"), readme);
+    log.ok(`README.md → ${lang} version${existsSync(resolve(root, "README.md.bak")) ? " (previous file: README.md.bak)" : ""}`);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
 export async function runType(args) {
   // accept `type change`, `type`, `type --to ros2-cpp`
   const sub = args[0];
@@ -39,17 +63,17 @@ export async function runType(args) {
   const current = currentTypeKey(json.runtime);
 
   if (sub && sub !== "change") {
-    log.warn(`unknown subcommand '${sub}'. Usage: muscat-pk type change [--to python|cpp|ros2|ros2-cpp]`);
+    log.warn(`unknown subcommand '${sub}'. Usage: muscat-pk type change [--to python|cpp|ros2|ros2-cpp] [--readme]`);
   }
 
   if (!to) {
-    console.log(`\n현재 타입: ${current}`);
-    console.log("변경할 타입을 선택하세요:");
+    console.log(`\nCurrent type: ${current}`);
+    console.log("Select the new type:");
     console.log("  1) Python");
     console.log("  2) C++");
     console.log("  3) ROS2 (rclpy / Python)");
     console.log("  4) ROS2 (rclcpp / C++)");
-    const choice = await prompt("\n선택 [1/2/3/4]: ", "");
+    const choice = await prompt("\nChoice [1/2/3/4]: ", "");
     to = { "1": "python", "2": "cpp", "3": "ros2", "4": "ros2-cpp" }[choice];
   }
 
@@ -62,7 +86,7 @@ export async function runType(args) {
   }
 
   const runtimeChoice = TYPE_CHOICES[to];
-  const { slug, pluginName, pluginClass, pluginId } = deriveNames(root);
+  const { dir, slug, pluginName, pluginClass, pluginId } = deriveNames(root);
 
   if (runtimeChoice.type === "ros2") {
     if (existsSync(resolve(root, "ros2_ws"))) {
@@ -70,7 +94,7 @@ export async function runType(args) {
     } else {
       log.step(`adding ros2_ws/ overlay (${runtimeChoice.rosClient})`);
       await overlayRos2(root, slug, runtimeChoice.rosClient);
-      applyTokens(root, {
+      applyTokens(resolve(root, "ros2_ws"), {
         __PLUGIN_ID__: pluginId,
         __PLUGIN_NAME__: pluginName,
         __PLUGIN_SLUG__: slug,
@@ -84,7 +108,7 @@ export async function runType(args) {
     } else {
       log.step("adding cpp/ overlay");
       await overlayCpp(root);
-      applyTokens(root, {
+      applyTokens(resolve(root, "cpp"), {
         __PLUGIN_ID__: pluginId,
         __PLUGIN_NAME__: pluginName,
         __PLUGIN_SLUG__: slug,
@@ -102,4 +126,14 @@ export async function runType(args) {
   json.runtime = runtimeForChoice(runtimeChoice, slug);
   writeFileSync(path, JSON.stringify(json, null, 2) + "\n");
   log.ok(`${basename(root)} type: ${current} → ${to}`);
+
+  if (isCpp(current) !== isCpp(to)) {
+    await offerReadme(root, isCpp(to), args.includes("--readme"), {
+      __PLUGIN_ID__: pluginId,
+      __PLUGIN_NAME__: pluginName,
+      __PLUGIN_DIR__: dir,
+      __PLUGIN_SLUG__: slug,
+      __PLUGIN_CLASS__: pluginClass,
+    });
+  }
 }

package/cli/src/uninstall.mjs

@@ -1,28 +1,11 @@
 // muscat-pk uninstall - remove the installed CLI, whether npm-global or S3 binary.
 import { execSync, spawn, spawnSync } from "node:child_process";
-import { existsSync, realpathSync, rmSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
-import { KIT_PUBLISHED_NAME, kitRoot, log, parseArgs } from "./util.mjs";
+import { existsSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { KIT_PUBLISHED_NAME, isNpmGlobalInstall, log, parseArgs } from "./util.mjs";
 
 const isBinaryMode = typeof Bun !== "undefined";
 
-function isInside(child, parent) {
-  const rel = relative(parent, child);
-  return rel === "" || (!!rel && !rel.startsWith("..") && !rel.includes(":"));
-}
-
-function npmGlobalRoot() {
-  return execSync("npm root -g", { encoding: "utf8" }).trim();
-}
-
-function isNpmGlobalInstall() {
-  try {
-    return isInside(realpathSync(kitRoot), realpathSync(npmGlobalRoot()));
-  } catch {
-    return false;
-  }
-}
-
 function uninstallNpmGlobal() {
   log.step(`npm uninstall -g ${KIT_PUBLISHED_NAME}`);
   execSync(`npm uninstall -g ${KIT_PUBLISHED_NAME}`, { stdio: "inherit" });

package/cli/src/update.mjs

@@ -10,9 +10,8 @@
 //
 // After updating the CLI itself, also bumps the plugin project's local deps
 // and migrates the project structure if it's outdated (src/ → ui/, root main.py → py/).
-import { execSync, spawn } from "node:child_process";
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { execSync, spawn, spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { findPluginRoot, isLocalKitInstall, KIT_PUBLISHED_NAME, kitVersion, log, parseArgs, prompt } from "./util.mjs";
 
@@ -91,11 +90,18 @@ async function updateBinary(tag) {
 
     log.ok(`v${version} will be applied on next run.`);
   } else {
-    // macOS / Linux: can replace the file while it's mapped into memory
-    const tmp = join(tmpdir(), `muscat-pk-${version}`);
-    writeFileSync(tmp, data);
-    chmodSync(tmp, 0o755);
-    copyFileSync(tmp, execPath);
+    // macOS / Linux: 실행 중인 파일에 덮어쓰면 Linux 는 ETXTBSY. 같은 디렉토리에 쓰고 rename 으로 바꿔치기한다.
+    const newPath = execPath + ".new";
+    writeFileSync(newPath, data);
+    chmodSync(newPath, 0o755);
+    try {
+      renameSync(newPath, execPath);
+    } catch (err) {
+      if (err?.code !== "EACCES" && err?.code !== "EPERM") throw err;
+      log.info("  sudo is required...");
+      const r = spawnSync("sudo", ["mv", "-f", newPath, execPath], { stdio: "inherit" });
+      if (r.status !== 0) throw new Error(`sudo mv failed: ${execPath}`);
+    }
     log.ok(`Updated to v${version}.`);
   }
 }

package/cli/src/util.mjs

@@ -1,7 +1,8 @@
 // Shared helpers for muscat-pk.
-import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, resolve, sep } from "node:path";
+import { execSync, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve, sep } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline/promises";
@@ -59,10 +60,43 @@ export function ensureIdeVenv(root) {
     if (created.status !== 0 || !existsSync(py)) return false;
   }
 
+  const pip = (pkgs) => spawnSync(py, ["-m", "pip", "install", "-q", ...pkgs], { cwd: root, stdio: "ignore" }).status === 0;
+
+  // host_agent.py only; not in requirements.txt, so it never ships in the ZIP.
+  if (!pip([HOST_AGENT_ZENOH])) return false;
+
   const reqs = resolve(root, "requirements.txt");
-  const args = ["-m", "pip", "install", "-q"];
-  if (existsSync(reqs)) args.push("-r", reqs);
-  return spawnSync(py, args, { cwd: root, stdio: "ignore" }).status === 0;
+  if (!existsSync(reqs)) return true;
+  if (process.platform !== "darwin") return pip(["-r", reqs]);
+
+  // No macOS wheels for rainbow-*: install the rest + type stubs.
+  const lines = readFileSync(reqs, "utf8").split("\n");
+  const isRainbow = (l) => /^\s*rainbow-/i.test(l);
+  const sdkPin = lines.map((l) => l.match(/^\s*rainbow-rb-sdk\s*==\s*(\S+)/i)?.[1]).find(Boolean);
+  const rest = lines.filter((l) => l.trim() && !l.trim().startsWith("#") && !isRainbow(l)).map((l) => l.trim());
+  if (rest.length && !pip(rest)) return false;
+  if (!pip([`rainbow-rb-sdk-stubs${sdkPin ? `==${sdkPin}` : ""}`])) {
+    log.warn(`rainbow-rb-sdk-stubs${sdkPin ? `==${sdkPin}` : ""} not on PyPI yet — editor types for rainbow.* unavailable.`);
+  }
+  ensurePyrightMissingSourceOff(root);
+  return true;
+}
+
+export const HOST_AGENT_ZENOH = "eclipse-zenoh==1.8.0"; // match the robot's zenoh-c minor version
+
+function ensurePyrightMissingSourceOff(root) {
+  const path = resolve(root, "pyrightconfig.json");
+  let cfg = {};
+  if (existsSync(path)) {
+    try {
+      cfg = JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+      return; // user-edited / JSONC — leave it alone
+    }
+  }
+  if (cfg.reportMissingModuleSource === "none") return;
+  cfg.reportMissingModuleSource = "none";
+  writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n");
 }
 
 /** Published install/CLI package name. Author imports use @rainbow-robotics/plugin-ui separately. */
@@ -153,9 +187,21 @@ export function resolveLocalCliBin(start = process.cwd()) {
   }
 }
 
+/** True if the code currently running was installed with `npm install -g`. */
+export function isNpmGlobalInstall() {
+  try {
+    const globalRoot = realpathSync(execSync("npm root -g", { encoding: "utf8" }).trim());
+    const rel = relative(globalRoot, realpathSync(kitRoot));
+    return rel === "" || (!rel.startsWith("..") && !rel.includes(":"));
+  } catch {
+    return false;
+  }
+}
+
 /** True if the code currently running is a project's local install (not global/binary). */
 export function isLocalKitInstall() {
-  return kitRoot.includes(`${sep}node_modules${sep}`);
+  // npm -g 도 node_modules 아래에 놓이므로 global root 는 제외한다.
+  return kitRoot.includes(`${sep}node_modules${sep}`) && !isNpmGlobalInstall();
 }
 
 const useColor = process.env.NO_COLOR !== "1" && (process.stdout.isTTY || process.env.FORCE_COLOR);
@@ -227,9 +273,23 @@ export function dockerImageExists(image) {
  * rebuilding an image we already have breaks `dev` offline for no benefit.
  * Force a rebuild with MUSCAT_PK_REBUILD_IMAGE=1.
  */
-export function canSkipImageBuild(image) {
+// Rebuild when the Dockerfile or build args change (image label holds the hash).
+const IMAGE_KEY_LABEL = "com.rainbow-robotics.muscat-pk.key";
+
+export function imageKey(dockerfile, extra = "") {
+  return createHash("sha256").update(readFileSync(dockerfile)).update(extra).digest("hex").slice(0, 16);
+}
+
+export function imageKeyLabel(key) {
+  return ["--label", `${IMAGE_KEY_LABEL}=${key}`];
+}
+
+export function canSkipImageBuild(image, key = null) {
   if (process.env.MUSCAT_PK_REBUILD_IMAGE === "1") return false;
-  return dockerImageExists(image);
+  if (!dockerImageExists(image)) return false;
+  if (!key) return true;
+  const r = spawnSync("docker", ["image", "inspect", "-f", `{{index .Config.Labels "${IMAGE_KEY_LABEL}"}}`, image], { encoding: "utf8" });
+  return r.status === 0 && r.stdout.trim() === key;
 }
 
 // Linux에서 컨테이너가 마운트에 root 소유 파일을 남기면 다음 빌드의 dist/ 삭제가 EACCES로 막힌다.
@@ -269,6 +329,7 @@ export async function resolveDockerfile(name) {
 
 /** This kit's installed version (from its package.json). */
 export function kitVersion() {
+  if (process.env.MUSCAT_PK_VERSION) return process.env.MUSCAT_PK_VERSION;
   try {
     return JSON.parse(readFileSync(resolve(kitRoot, "package.json"), "utf8"))
       .version;

package/cli/storybook-dist/_stories-src/RBDatePicker/RBRangeDateInput.stories.tsx

@@ -16,13 +16,25 @@ export default {
     },
     showPresets: { control: "boolean" },
     showFooter: { control: "boolean" },
+    min: { control: "date" },
+    max: { control: "date" },
+    maxDays: {
+      control: { type: "number", min: 0, step: 1 },
+      description: "선택 가능한 최대 일수. 0은 제한 없음.",
+    },
   },
+  args: { maxDays: 0 },
 } as Meta<typeof RBRangeDateInput>;
 
 const Template: StoryTemplate = (args) => {
   return (
     <div style={{ height: 700 }}>
-      <RBRangeDateInput {...args} />
+      <RBRangeDateInput
+        {...args}
+        min={args.min != null ? new Date(args.min) : undefined}
+        max={args.max != null ? new Date(args.max) : undefined}
+        maxDays={(args.maxDays ?? 0) > 0 ? args.maxDays : undefined}
+      />
     </div>
   );
 };