@rainbow-robotics/muscat-plugin-kit 1.10.1-dev.1 → 1.10.1

package/cli/src/util.mjs

@@ -1,441 +1,441 @@
-// Shared helpers for muscat-pk.
-import { execSync, spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readdirSync, 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";
-
-/** True if an executable is on PATH (cross-platform). */
-export function hasBin(bin) {
-  const probe = process.platform === "win32" ? "where" : "which";
-  return spawnSync(probe, [bin]).status === 0;
-}
-
-/**
- * Find a Python 3.12 interpreter (robot targets 3.12), cross-platform.
- * Returns the command as an argv array, e.g. ["py","-3.12"] or ["python3.12"].
- * Falls back to a generic python3/python with a warning flag.
- */
-export function detectPythonCmd() {
-  const candidates =
-    process.platform === "win32"
-      ? [["py", "-3.12"], ["python3.12"], ["py", "-3"], ["python"]]
-      : [["python3.12"], ["python3"], ["python"]];
-  for (const cmd of candidates) {
-    const r = spawnSync(cmd[0], [...cmd.slice(1), "--version"]);
-    if (r.status === 0) {
-      const ver = String(r.stdout || r.stderr || "");
-      return { cmd, is312: ver.includes("3.12") };
-    }
-  }
-  return { cmd: process.platform === "win32" ? ["python"] : ["python3"], is312: false };
-}
-
-/** Path to the venv's python interpreter (cross-platform). */
-export function venvPython(venvDir) {
-  return process.platform === "win32"
-    ? resolve(venvDir, "Scripts", "python.exe")
-    : resolve(venvDir, "bin", "python");
-}
-
-/**
- * Create/refresh a local `.venv` with requirements.txt installed, for the
- * editor/linter only (the backend actually runs in Docker). Uses `uv` if
- * present, else the system Python. Returns true if the venv is ready.
- */
-export function ensureIdeVenv(root) {
-  const venvDir = resolve(root, ".venv");
-  const py = venvPython(venvDir);
-
-  if (!existsSync(py)) {
-    let created;
-    if (hasBin("uv")) {
-      created = spawnSync("uv", ["venv", venvDir, "--python", "3.12", "--seed"], { cwd: root, stdio: "ignore" });
-    } else {
-      const { cmd } = detectPythonCmd();
-      created = spawnSync(cmd[0], [...cmd.slice(1), "-m", "venv", venvDir], { cwd: root, stdio: "ignore" });
-    }
-    if (created.status !== 0 || !existsSync(py)) return 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");
-  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;
-  pip([`rainbow-rb-sdk-stubs${sdkPin ? `==${sdkPin}` : ""}`]); // not on PyPI for every SDK version yet
-  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. */
-export const KIT_PUBLISHED_NAME = "@rainbow-robotics/muscat-plugin-kit";
-
-// This file lives at <pkg>/cli/src/util.mjs → package root is two levels up.
-export const kitRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
-export const templatesDir = resolve(kitRoot, "cli/templates");
-
-/** Parse `--flag value` and `--bool` from argv into an object. */
-export function parseArgs(args, { booleans = [] } = {}) {
-  const out = { _: [] };
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a.startsWith("--")) {
-      const key = a.slice(2);
-      if (booleans.includes(key)) {
-        out[key] = true;
-      } else if (args[i + 1] && !args[i + 1].startsWith("--")) {
-        out[key] = args[++i];
-      } else {
-        out[key] = true;
-      }
-    } else {
-      out._.push(a);
-    }
-  }
-  return out;
-}
-
-/** Prompt user for input. Returns trimmed answer or fallback (non-TTY or empty). */
-export async function prompt(question, fallback = "") {
-  if (!process.stdin.isTTY) return fallback;
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const answer = (await rl.question(question)).trim();
-  rl.close();
-  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). */
-// C++ backends pin the SDK where they declare it: find_package(rb_sdk <version> EXACT REQUIRED) in
-// cpp/CMakeLists.txt or ros2_ws/src/<pkg>/CMakeLists.txt. The dev image installs that version.
-const RB_SDK_FIND = /find_package\(\s*rb_sdk(\s+[0-9][\w.]*)?/;
-
-export function cppSdkFiles(root) {
-  const files = [resolve(root, "cpp", "CMakeLists.txt")];
-  const src = resolve(root, "ros2_ws", "src");
-  if (existsSync(src)) for (const pkg of readdirSync(src)) files.push(resolve(src, pkg, "CMakeLists.txt"));
-  return files.filter((f) => existsSync(f) && RB_SDK_FIND.test(readFileSync(f, "utf8")));
-}
-
-export function cppSdkPin(root) {
-  for (const f of cppSdkFiles(root)) {
-    const version = readFileSync(f, "utf8").match(RB_SDK_FIND)[1]?.trim();
-    if (version) return version;
-  }
-  return undefined;
-}
-
-/** SDK version for the C++ dev image: MUSCAT_PK_RB_SDK_VERSION overrides the project's CMake pin. */
-export function cppSdkVersion(root = pluginRootOrNull()) {
-  if (process.env.MUSCAT_PK_RB_SDK_VERSION) return process.env.MUSCAT_PK_RB_SDK_VERSION;
-  return root ? cppSdkPin(root) : undefined; // not in a plugin project: the Dockerfile default
-}
-
-export function pluginRootOrNull() {
-  try {
-    return findPluginRoot();
-  } catch {
-    return null;
-  }
-}
-
-/** Rewrite the pinned version in every CMakeLists.txt that finds rb_sdk; returns the files changed. */
-export function setCppSdkPin(root, version) {
-  const files = cppSdkFiles(root);
-  for (const f of files) {
-    const text = readFileSync(f, "utf8").replace(RB_SDK_FIND, (m, old) => `find_package(rb_sdk ${version}${old ? "" : " EXACT"}`);
-    writeFileSync(f, text);
-  }
-  return files;
-}
-
-export function findPluginRoot(start = process.cwd()) {
-  let dir = resolve(start);
-  for (;;) {
-    if (existsSync(resolve(dir, "manifest.json"))) return dir;
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  throw new Error(
-    "Not a muscat plugin project (no manifest.json found). Run from your plugin directory.",
-  );
-}
-
-/** Walk up from cwd looking for a project-local muscat-pk install. */
-export function resolveLocalCliBin(start = process.cwd()) {
-  let dir = resolve(start);
-  for (;;) {
-    const candidate = resolve(dir, "node_modules/@rainbow-robotics/muscat-plugin-kit/cli/bin/muscat-pk.mjs");
-    if (existsSync(candidate)) return candidate;
-    const parent = dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-}
-
-/** 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() {
-  // 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);
-const ansi = (code) => (s) => useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s);
-
-export const color = {
-  bold: ansi("1"),
-  dim: ansi("2"),
-  red: ansi("31"),
-  green: ansi("32"),
-  yellow: ansi("33"),
-  blue: ansi("34"),
-  magenta: ansi("35"),
-  cyan: ansi("36"),
-};
-
-export const log = {
-  info:  (...m) => console.log(...m),
-  step:  (...m) => console.log(color.cyan("›"), ...m.map(s => color.cyan(s))),
-  ok:    (...m) => console.log(color.green("✓"), ...m),
-  warn:  (...m) => console.warn(color.yellow("⚠"), ...m.map(s => color.yellow(s))),
-  error: (...m) => console.error(color.red("✖"), ...m.map(s => color.red(s))),
-};
-
-// dev / dev:back / build run the plugin back end, the local Muscat runtime, and cpp/ros2
-// compilation in Docker. Show a clear install hint when Docker is missing.
-export function ensureDocker() {
-  if (!hasBin("docker")) {
-    log.warn("Docker not found.");
-    log.warn("  muscat-pk runs the plugin back end, the local Muscat runtime, and cpp/ros2 builds in Docker.");
-    log.warn("  Install Docker, then retry: https://docs.docker.com/get-docker/");
-    throw new Error("Docker is required for dev / dev:back / build.");
-  }
-  // The binary alone is not enough: with the daemon down every docker step fails one by one
-  // (Docker Desktop not started is the usual case on macOS/Windows).
-  if (spawnSync("docker", ["info", "--format", "{{.ServerVersion}}"], { stdio: "ignore", timeout: 15_000 }).status === 0) return;
-  const hint = process.platform === "linux" ? "start it (e.g. `sudo systemctl start docker`)" : "start Docker Desktop and wait until it reports running";
-  throw new Error(`Docker is installed but the daemon is not running — ${hint}, then retry.`);
-}
-
-/**
- * Remove dangling (untagged) muscat-pk images left behind after a rebuild.
- * Uses label filter so only our images are touched — other Docker images are safe.
- */
-export function pruneMuskatImages() {
-  spawnSync(
-    "docker",
-    ["image", "prune", "--force", "--filter", "label=com.rainbow-robotics.muscat-pk=true"],
-    { stdio: "ignore" },
-  );
-}
-
-/**
- * Docker flags that let the backend take a realtime scheduling priority
- * (SCHED_FIFO/RR). Neither CAP_SYS_NICE nor a non-zero RLIMIT_RTPRIO is in
- * Docker's default set, so without these sched_setscheduler() fails with EPERM.
- * Mirrors the robot's `muscat` container (rby2 backend/docker-compose.yml) so
- * dev and the robot behave the same.
- */
-export function realtimeFlags() {
-  // memlock is bounded (not unlimited): mlockall'd pages can't be swapped out,
-  // so an unbounded limit lets a plugin pin RAM until the robot OOMs.
-  return ["--cap-add", "SYS_NICE", "--ulimit", "rtprio=99", "--ulimit", "memlock=536870912"];
-}
-
-/** True if the image already exists in the local Docker image store. */
-export function dockerImageExists(image) {
-  return spawnSync("docker", ["image", "inspect", image], { stdio: "ignore" }).status === 0;
-}
-
-/**
- * True if `docker build` should be skipped because the image is already built.
- * BuildKit resolves the FROM tag over the network on every build (the
- * "load metadata for docker.io/..." step) even when all layers are cached, so
- * rebuilding an image we already have breaks `dev` offline for no benefit.
- * Force a rebuild with MUSCAT_PK_REBUILD_IMAGE=1.
- */
-// 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);
-}
-
-// MUSCAT_PK_NO_BUILD_CACHE=1 (CI): build images without Docker's layer cache, so an apt/PyPI/GitHub
-// change that breaks a fresh build fails the test too instead of hiding behind a cached layer.
-export const buildCacheFlags = () => (process.env.MUSCAT_PK_NO_BUILD_CACHE === "1" ? ["--no-cache"] : []);
-
-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;
-  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로 막힌다.
-// (macOS/Windows는 Docker Desktop이 소유권을 호스트 유저로 매핑하므로 불필요)
-export function dockerUserFlags() {
-  if (process.platform !== "linux" || typeof process.getuid !== "function") return [];
-  return [
-    "--user", `${process.getuid()}:${process.getgid()}`,
-    "-e", "HOME=/tmp",
-    "-e", "XDG_CACHE_HOME=/tmp/.cache",
-  ];
-}
-
-export function humanSize(bytes) {
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
-  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
-}
-
-/**
- * Return the on-disk path of a bundled Dockerfile.
- * In npm-install mode the real file exists under cli/docker/.
- * In compiled-binary mode it doesn't — extract from the embedded snapshot to tmpdir.
- */
-export async function resolveDockerfile(name) {
-  const real = resolve(kitRoot, "cli/docker", name);
-  if (existsSync(real)) return real;
-  const { TEMPLATES } = await import("./templates-embedded.mjs");
-  const b64 = TEMPLATES[`docker/${name}`];
-  if (!b64) throw new Error(`Embedded Dockerfile missing: docker/${name}. Reinstall muscat-plugin-kit.`);
-  const dir = resolve(tmpdir(), "muscat-pk-docker");
-  mkdirSync(dir, { recursive: true });
-  const tmp = resolve(dir, name);
-  writeFileSync(tmp, Buffer.from(b64, "base64"));
-  return tmp;
-}
-
-/** 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;
-  } catch {
-    return "0.0.0";
-  }
-}
-
-/** Compare semver-ish "x.y.z[-pre]". Returns true if `a` > `b` (release parts). */
-export function isNewer(a, b) {
-  const parse = (v) =>
-    String(v)
-      .split("-")[0]
-      .split(".")
-      .map((n) => parseInt(n, 10) || 0);
-  const [a1, a2, a3] = parse(a);
-  const [b1, b2, b3] = parse(b);
-  if (a1 !== b1) return a1 > b1;
-  if (a2 !== b2) return a2 > b2;
-  return a3 > b3;
-}
-
-/**
- * Non-blocking check for a newer published kit. Prints an update suggestion if
- * one exists. Fails silently when offline. Honors `RB_REGISTRY` and is skipped
- * by `MUSCAT_PK_NO_UPDATE_CHECK=1`.
- */
-export async function checkKitUpdate({ timeoutMs = 2000 } = {}) {
-  if (process.env.MUSCAT_PK_NO_UPDATE_CHECK === "1") return;
-  const current = kitVersion();
-  const registry = (process.env.RB_REGISTRY || "https://registry.npmjs.org").replace(/\/$/, "");
-  try {
-    const ac = new AbortController();
-    const timer = setTimeout(() => ac.abort(), timeoutMs);
-    const res = await fetch(
-      `${registry}/${encodeURIComponent(KIT_PUBLISHED_NAME)}/latest`,
-      { signal: ac.signal },
-    );
-    clearTimeout(timer);
-    if (!res.ok) return;
-    const { version: latest } = await res.json();
-    if (latest && isNewer(latest, current)) {
-      const line = "─".repeat(58);
-      console.log(
-        [
-          "",
-          line,
-          `  muscat-plugin-kit update available: ${current} → ${latest}`,
-          `  Update:  muscat-pk update`,
-          line,
-          "",
-        ].join("\n"),
-      );
-    }
-  } catch {
-    /* offline or registry unreachable — ignore */
-  }
-}
+// Shared helpers for muscat-pk.
+import { execSync, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, 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";
+
+/** True if an executable is on PATH (cross-platform). */
+export function hasBin(bin) {
+  const probe = process.platform === "win32" ? "where" : "which";
+  return spawnSync(probe, [bin]).status === 0;
+}
+
+/**
+ * Find a Python 3.12 interpreter (robot targets 3.12), cross-platform.
+ * Returns the command as an argv array, e.g. ["py","-3.12"] or ["python3.12"].
+ * Falls back to a generic python3/python with a warning flag.
+ */
+export function detectPythonCmd() {
+  const candidates =
+    process.platform === "win32"
+      ? [["py", "-3.12"], ["python3.12"], ["py", "-3"], ["python"]]
+      : [["python3.12"], ["python3"], ["python"]];
+  for (const cmd of candidates) {
+    const r = spawnSync(cmd[0], [...cmd.slice(1), "--version"]);
+    if (r.status === 0) {
+      const ver = String(r.stdout || r.stderr || "");
+      return { cmd, is312: ver.includes("3.12") };
+    }
+  }
+  return { cmd: process.platform === "win32" ? ["python"] : ["python3"], is312: false };
+}
+
+/** Path to the venv's python interpreter (cross-platform). */
+export function venvPython(venvDir) {
+  return process.platform === "win32"
+    ? resolve(venvDir, "Scripts", "python.exe")
+    : resolve(venvDir, "bin", "python");
+}
+
+/**
+ * Create/refresh a local `.venv` with requirements.txt installed, for the
+ * editor/linter only (the backend actually runs in Docker). Uses `uv` if
+ * present, else the system Python. Returns true if the venv is ready.
+ */
+export function ensureIdeVenv(root) {
+  const venvDir = resolve(root, ".venv");
+  const py = venvPython(venvDir);
+
+  if (!existsSync(py)) {
+    let created;
+    if (hasBin("uv")) {
+      created = spawnSync("uv", ["venv", venvDir, "--python", "3.12", "--seed"], { cwd: root, stdio: "ignore" });
+    } else {
+      const { cmd } = detectPythonCmd();
+      created = spawnSync(cmd[0], [...cmd.slice(1), "-m", "venv", venvDir], { cwd: root, stdio: "ignore" });
+    }
+    if (created.status !== 0 || !existsSync(py)) return 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");
+  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;
+  pip([`rainbow-rb-sdk-stubs${sdkPin ? `==${sdkPin}` : ""}`]); // not on PyPI for every SDK version yet
+  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. */
+export const KIT_PUBLISHED_NAME = "@rainbow-robotics/muscat-plugin-kit";
+
+// This file lives at <pkg>/cli/src/util.mjs → package root is two levels up.
+export const kitRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+export const templatesDir = resolve(kitRoot, "cli/templates");
+
+/** Parse `--flag value` and `--bool` from argv into an object. */
+export function parseArgs(args, { booleans = [] } = {}) {
+  const out = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      if (booleans.includes(key)) {
+        out[key] = true;
+      } else if (args[i + 1] && !args[i + 1].startsWith("--")) {
+        out[key] = args[++i];
+      } else {
+        out[key] = true;
+      }
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+/** Prompt user for input. Returns trimmed answer or fallback (non-TTY or empty). */
+export async function prompt(question, fallback = "") {
+  if (!process.stdin.isTTY) return fallback;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = (await rl.question(question)).trim();
+  rl.close();
+  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). */
+// C++ backends pin the SDK where they declare it: find_package(rb_sdk <version> EXACT REQUIRED) in
+// cpp/CMakeLists.txt or ros2_ws/src/<pkg>/CMakeLists.txt. The dev image installs that version.
+const RB_SDK_FIND = /find_package\(\s*rb_sdk(\s+[0-9][\w.]*)?/;
+
+export function cppSdkFiles(root) {
+  const files = [resolve(root, "cpp", "CMakeLists.txt")];
+  const src = resolve(root, "ros2_ws", "src");
+  if (existsSync(src)) for (const pkg of readdirSync(src)) files.push(resolve(src, pkg, "CMakeLists.txt"));
+  return files.filter((f) => existsSync(f) && RB_SDK_FIND.test(readFileSync(f, "utf8")));
+}
+
+export function cppSdkPin(root) {
+  for (const f of cppSdkFiles(root)) {
+    const version = readFileSync(f, "utf8").match(RB_SDK_FIND)[1]?.trim();
+    if (version) return version;
+  }
+  return undefined;
+}
+
+/** SDK version for the C++ dev image: MUSCAT_PK_RB_SDK_VERSION overrides the project's CMake pin. */
+export function cppSdkVersion(root = pluginRootOrNull()) {
+  if (process.env.MUSCAT_PK_RB_SDK_VERSION) return process.env.MUSCAT_PK_RB_SDK_VERSION;
+  return root ? cppSdkPin(root) : undefined; // not in a plugin project: the Dockerfile default
+}
+
+export function pluginRootOrNull() {
+  try {
+    return findPluginRoot();
+  } catch {
+    return null;
+  }
+}
+
+/** Rewrite the pinned version in every CMakeLists.txt that finds rb_sdk; returns the files changed. */
+export function setCppSdkPin(root, version) {
+  const files = cppSdkFiles(root);
+  for (const f of files) {
+    const text = readFileSync(f, "utf8").replace(RB_SDK_FIND, (m, old) => `find_package(rb_sdk ${version}${old ? "" : " EXACT"}`);
+    writeFileSync(f, text);
+  }
+  return files;
+}
+
+export function findPluginRoot(start = process.cwd()) {
+  let dir = resolve(start);
+  for (;;) {
+    if (existsSync(resolve(dir, "manifest.json"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    "Not a muscat plugin project (no manifest.json found). Run from your plugin directory.",
+  );
+}
+
+/** Walk up from cwd looking for a project-local muscat-pk install. */
+export function resolveLocalCliBin(start = process.cwd()) {
+  let dir = resolve(start);
+  for (;;) {
+    const candidate = resolve(dir, "node_modules/@rainbow-robotics/muscat-plugin-kit/cli/bin/muscat-pk.mjs");
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** 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() {
+  // 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);
+const ansi = (code) => (s) => useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s);
+
+export const color = {
+  bold: ansi("1"),
+  dim: ansi("2"),
+  red: ansi("31"),
+  green: ansi("32"),
+  yellow: ansi("33"),
+  blue: ansi("34"),
+  magenta: ansi("35"),
+  cyan: ansi("36"),
+};
+
+export const log = {
+  info:  (...m) => console.log(...m),
+  step:  (...m) => console.log(color.cyan("›"), ...m.map(s => color.cyan(s))),
+  ok:    (...m) => console.log(color.green("✓"), ...m),
+  warn:  (...m) => console.warn(color.yellow("⚠"), ...m.map(s => color.yellow(s))),
+  error: (...m) => console.error(color.red("✖"), ...m.map(s => color.red(s))),
+};
+
+// dev / dev:back / build run the plugin back end, the local Muscat runtime, and cpp/ros2
+// compilation in Docker. Show a clear install hint when Docker is missing.
+export function ensureDocker() {
+  if (!hasBin("docker")) {
+    log.warn("Docker not found.");
+    log.warn("  muscat-pk runs the plugin back end, the local Muscat runtime, and cpp/ros2 builds in Docker.");
+    log.warn("  Install Docker, then retry: https://docs.docker.com/get-docker/");
+    throw new Error("Docker is required for dev / dev:back / build.");
+  }
+  // The binary alone is not enough: with the daemon down every docker step fails one by one
+  // (Docker Desktop not started is the usual case on macOS/Windows).
+  if (spawnSync("docker", ["info", "--format", "{{.ServerVersion}}"], { stdio: "ignore", timeout: 15_000 }).status === 0) return;
+  const hint = process.platform === "linux" ? "start it (e.g. `sudo systemctl start docker`)" : "start Docker Desktop and wait until it reports running";
+  throw new Error(`Docker is installed but the daemon is not running — ${hint}, then retry.`);
+}
+
+/**
+ * Remove dangling (untagged) muscat-pk images left behind after a rebuild.
+ * Uses label filter so only our images are touched — other Docker images are safe.
+ */
+export function pruneMuskatImages() {
+  spawnSync(
+    "docker",
+    ["image", "prune", "--force", "--filter", "label=com.rainbow-robotics.muscat-pk=true"],
+    { stdio: "ignore" },
+  );
+}
+
+/**
+ * Docker flags that let the backend take a realtime scheduling priority
+ * (SCHED_FIFO/RR). Neither CAP_SYS_NICE nor a non-zero RLIMIT_RTPRIO is in
+ * Docker's default set, so without these sched_setscheduler() fails with EPERM.
+ * Mirrors the robot's `muscat` container (rby2 backend/docker-compose.yml) so
+ * dev and the robot behave the same.
+ */
+export function realtimeFlags() {
+  // memlock is bounded (not unlimited): mlockall'd pages can't be swapped out,
+  // so an unbounded limit lets a plugin pin RAM until the robot OOMs.
+  return ["--cap-add", "SYS_NICE", "--ulimit", "rtprio=99", "--ulimit", "memlock=536870912"];
+}
+
+/** True if the image already exists in the local Docker image store. */
+export function dockerImageExists(image) {
+  return spawnSync("docker", ["image", "inspect", image], { stdio: "ignore" }).status === 0;
+}
+
+/**
+ * True if `docker build` should be skipped because the image is already built.
+ * BuildKit resolves the FROM tag over the network on every build (the
+ * "load metadata for docker.io/..." step) even when all layers are cached, so
+ * rebuilding an image we already have breaks `dev` offline for no benefit.
+ * Force a rebuild with MUSCAT_PK_REBUILD_IMAGE=1.
+ */
+// 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);
+}
+
+// MUSCAT_PK_NO_BUILD_CACHE=1 (CI): build images without Docker's layer cache, so an apt/PyPI/GitHub
+// change that breaks a fresh build fails the test too instead of hiding behind a cached layer.
+export const buildCacheFlags = () => (process.env.MUSCAT_PK_NO_BUILD_CACHE === "1" ? ["--no-cache"] : []);
+
+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;
+  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로 막힌다.
+// (macOS/Windows는 Docker Desktop이 소유권을 호스트 유저로 매핑하므로 불필요)
+export function dockerUserFlags() {
+  if (process.platform !== "linux" || typeof process.getuid !== "function") return [];
+  return [
+    "--user", `${process.getuid()}:${process.getgid()}`,
+    "-e", "HOME=/tmp",
+    "-e", "XDG_CACHE_HOME=/tmp/.cache",
+  ];
+}
+
+export function humanSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+/**
+ * Return the on-disk path of a bundled Dockerfile.
+ * In npm-install mode the real file exists under cli/docker/.
+ * In compiled-binary mode it doesn't — extract from the embedded snapshot to tmpdir.
+ */
+export async function resolveDockerfile(name) {
+  const real = resolve(kitRoot, "cli/docker", name);
+  if (existsSync(real)) return real;
+  const { TEMPLATES } = await import("./templates-embedded.mjs");
+  const b64 = TEMPLATES[`docker/${name}`];
+  if (!b64) throw new Error(`Embedded Dockerfile missing: docker/${name}. Reinstall muscat-plugin-kit.`);
+  const dir = resolve(tmpdir(), "muscat-pk-docker");
+  mkdirSync(dir, { recursive: true });
+  const tmp = resolve(dir, name);
+  writeFileSync(tmp, Buffer.from(b64, "base64"));
+  return tmp;
+}
+
+/** 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;
+  } catch {
+    return "0.0.0";
+  }
+}
+
+/** Compare semver-ish "x.y.z[-pre]". Returns true if `a` > `b` (release parts). */
+export function isNewer(a, b) {
+  const parse = (v) =>
+    String(v)
+      .split("-")[0]
+      .split(".")
+      .map((n) => parseInt(n, 10) || 0);
+  const [a1, a2, a3] = parse(a);
+  const [b1, b2, b3] = parse(b);
+  if (a1 !== b1) return a1 > b1;
+  if (a2 !== b2) return a2 > b2;
+  return a3 > b3;
+}
+
+/**
+ * Non-blocking check for a newer published kit. Prints an update suggestion if
+ * one exists. Fails silently when offline. Honors `RB_REGISTRY` and is skipped
+ * by `MUSCAT_PK_NO_UPDATE_CHECK=1`.
+ */
+export async function checkKitUpdate({ timeoutMs = 2000 } = {}) {
+  if (process.env.MUSCAT_PK_NO_UPDATE_CHECK === "1") return;
+  const current = kitVersion();
+  const registry = (process.env.RB_REGISTRY || "https://registry.npmjs.org").replace(/\/$/, "");
+  try {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    const res = await fetch(
+      `${registry}/${encodeURIComponent(KIT_PUBLISHED_NAME)}/latest`,
+      { signal: ac.signal },
+    );
+    clearTimeout(timer);
+    if (!res.ok) return;
+    const { version: latest } = await res.json();
+    if (latest && isNewer(latest, current)) {
+      const line = "─".repeat(58);
+      console.log(
+        [
+          "",
+          line,
+          `  muscat-plugin-kit update available: ${current} → ${latest}`,
+          `  Update:  muscat-pk update`,
+          line,
+          "",
+        ].join("\n"),
+      );
+    }
+  } catch {
+    /* offline or registry unreachable — ignore */
+  }
+}