@rainbow-robotics/muscat-plugin-kit 1.1.4 → 1.1.5

package/cli/bin/muscat-pk.mjs

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 // muscat-pk — Muscat plugin developer CLI.
 // Subcommands: new, build, dev, dev:ui, dev:back, storybook, mcp, update, uninstall, sdk, version.
-import { color, kitVersion, log } from "../src/util.mjs";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { color, kitVersion, log, resolveLocalCliBin } from "../src/util.mjs";
 import { runNew } from "../src/new.mjs";
 import { runBuild } from "../src/build.mjs";
 import { runDevUi } from "../src/devUi.mjs";
@@ -18,6 +21,21 @@ import { runCompletion } from "../src/completion.mjs";
 // on every invocation otherwise (see ros2.mjs/python.mjs/cpp.mjs for the same
 // pattern in build.mjs).
 
+// 실행 중인 게 글로벌/바이너리인데 cwd 상위에 로컬 설치가 있으면 그쪽으로 넘긴다.
+// vite preset / preview-host / manifest 검증이 항상 프로젝트가 고정한 버전과
+// 맞아야 해서다 (버전이 안 맞으면 "module not found" 류 에러로 터진다).
+(function delegateToLocalInstall() {
+  try {
+    const localBin = resolveLocalCliBin();
+    if (!localBin) return;
+    if (realpathSync(localBin) === realpathSync(fileURLToPath(import.meta.url))) return;
+    const r = spawnSync(process.execPath, [localBin, ...process.argv.slice(2)], { stdio: "inherit" });
+    process.exit(r.status ?? 0);
+  } catch {
+    // Bun 단일 바이너리 등 realpath가 안 통하는 환경 — 그냥 지금 프로세스로 계속.
+  }
+})();
+
 const [, , cmd, ...args] = process.argv;
 
 const commandRow = (command, description) => `  ${color.cyan(command.padEnd(30))}${description}`;
@@ -38,7 +56,7 @@ function formatHelp() {
     commandRow("dev:back", `Run the plugin back end ${color.dim("(python: watchfiles reload / ros2: Docker)")}`),
     commandRow("storybook", `Browse the bundled rb-components Storybook ${color.dim(`(${option("--port")} <n>, ${option("--rebuild")})`)}`),
     commandRow("mcp", `Start an MCP server ${color.dim("(stdio)")} exposing rb-components/rb SDK docs to AI agents`),
-    commandRow("update", `Update ${color.magenta("@rainbow-robotics/muscat-plugin-kit")} and ${color.magenta("@rainbow-robotics/plugin-ui")}`),
+    commandRow("update", `Update ${color.magenta("@rainbow-robotics/muscat-plugin-kit")} and ${color.magenta("@rainbow-robotics/plugin-ui")} ${color.dim(`(local-only if run from a project's local install; ${option("--global")} also updates the global CLI)`)}`),
     commandRow("uninstall", `Remove the installed ${color.cyan("muscat-pk")} CLI ${color.dim("(npm global or S3 binary)")}`),
     commandRow("sdk <list|update [version]>", "Manage the python rainbow-rb-sdk version"),
     commandRow("version", `Print the installed ${color.cyan("muscat-pk")} version`),

package/cli/src/bridge.mjs

@@ -7,7 +7,7 @@ import { spawnSync } from "node:child_process";
 import { createServer, connect } from "node:net";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
-import { hasBin, kitRoot, log, pruneMuskatImages } from "./util.mjs";
+import { canSkipImageBuild, hasBin, kitRoot, log, pruneMuskatImages } from "./util.mjs";
 
 export const BRIDGE_IMAGE = "muscat-pk-bridge";
 export const BRIDGE_CONTAINER = "muscat-pk-bridge-run";
@@ -53,6 +53,10 @@ function waitForPort(port, timeoutMs = 15_000) {
 }
 
 function ensureImage() {
+  if (canSkipImageBuild(BRIDGE_IMAGE)) {
+    log.step(`${BRIDGE_IMAGE} already built — skipping docker build`);
+    return;
+  }
   log.step(`docker build -t ${BRIDGE_IMAGE} (first run is slow, then cached)…`);
   const r = spawnSync("docker", ["build", "-t", BRIDGE_IMAGE, "-f", DOCKERFILE, BUILD_CONTEXT], { stdio: "inherit" });
   if (r.status !== 0) throw new Error("docker build failed (bridge image).");
@@ -63,19 +67,37 @@ function ensureImage() {
  * 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({ zenohPort = null } = {}) {
+export async function startBridge({ zenohPort = null, pluginPorts = [] } = {}) {
   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)) return false;
 
+  // Publishing a busy port makes `docker run` fail with a raw daemon error —
+  // say which port and keep the bridge up instead.
+  const busy = [];
+  for (const port of pluginPorts) {
+    if (await isPortInUse(port)) busy.push(port);
+  }
+  if (busy.length > 0) {
+    log.warn(
+      `declared plugin port(s) already in use on the host: ${busy.join(", ")} — ` +
+      `not published (the backend still listens inside the container).`,
+    );
+  }
+  const publishable = pluginPorts.filter((port) => !busy.includes(port));
+
   ensureImage();
 
   log.step("starting Socket.IO bridge container…");
+  // The backend joins THIS container's netns (--network container:), and a
+  // netns can only publish ports when its owner starts — so the plugin's
+  // declared ports have to be published here, not on the backend container.
   const portFlags = [
     "-p", `127.0.0.1:${BRIDGE_PORT}:${BRIDGE_PORT}`,
     ...(zenohPort ? ["-p", `${zenohPort}:${zenohPort}`] : []),
+    ...publishable.flatMap((port) => ["-p", `127.0.0.1:${port}:${port}`]),
   ];
   const up = spawnSync(
     "docker",
@@ -87,6 +109,8 @@ export async function startBridge({ zenohPort = null } = {}) {
   await waitForPort(BRIDGE_PORT);
   log.step(`Socket.IO bridge listening on ws://127.0.0.1:${BRIDGE_PORT}`);
   if (zenohPort) log.step(`Zenoh dev peer port published on :${zenohPort}`);
+  if (publishable.length > 0)
+    log.step(`plugin backend ports published on 127.0.0.1: ${publishable.join(", ")}`);
   return true;
 }
 

package/cli/src/build.mjs

@@ -227,7 +227,17 @@ export async function buildPlugin({ root, minify = false } = {}) {
   const pluginRoot = root ?? findPluginRoot();
   assertManifest(pluginRoot);
   const distDir = resolve(pluginRoot, "dist");
-  rmSync(distDir, { recursive: true, force: true });
+  try {
+    rmSync(distDir, { recursive: true, force: true });
+  } catch (err) {
+    if (err?.code !== "EACCES" && err?.code !== "EPERM") throw err;
+    // 이전 버전이 컨테이너를 root로 돌려 남긴 dist/ — 한 번만 정리하면 된다
+    throw new Error(
+      `Permission denied when deleting dist/ (${err.path ?? distDir}).\n` +
+      `The previous build left files owned by root. Please clean it up once:\n` +
+      `  sudo rm -rf ${distDir}`,
+    );
+  }
   mkdirSync(distDir, { recursive: true });
 
   const manifest = JSON.parse(readFileSync(resolve(pluginRoot, "manifest.json"), "utf8"));

package/cli/src/cpp.mjs

@@ -3,7 +3,7 @@
 // Used by dev:back (interactive dev loop) and build (export the binary into the ZIP).
 import { spawnSync } from "node:child_process";
 import { dirname } from "node:path";
-import { hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+import { canSkipImageBuild, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
 
 export const CPP_DEV_IMAGE = "muscat-pk-cpp-dev";
 
@@ -15,6 +15,10 @@ export function assertDockerReady() {
 
 /** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
 export async function ensureImage(image = CPP_DEV_IMAGE, { platform = null } = {}) {
+  if (canSkipImageBuild(image)) {
+    log.step(`${image} already built — skipping docker build`);
+    return;
+  }
   const dockerfile = await resolveDockerfile("Dockerfile.cpp");
   log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
   const platformFlags = platform ? ["--platform", platform] : [];
@@ -54,7 +58,7 @@ export function cmakeBuild(root, { image = CPP_DEV_IMAGE, buildType = "Debug", a
   log.step(label);
   const r = spawnSync(
     "docker",
-    ["run", "--rm", ...platformFlags, "-v", `${root}:/plugin`, "-w", "/plugin", actualImage, "bash", "-lc", script],
+    ["run", "--rm", ...dockerUserFlags(), ...platformFlags, "-v", `${root}:/plugin`, "-w", "/plugin", actualImage, "bash", "-lc", script],
     { cwd: root, stdio: "inherit" },
   );
   if (r.status !== 0) throw new Error(`cmake build failed${arch ? ` (${arch})` : ""}.`);

package/cli/src/dev.mjs

@@ -133,6 +133,8 @@ export async function runDev(args = []) {
     zenohPort: remoteRobot && !proxyEndpoint && !usesHostNetwork()
       ? Number(process.env.MUSCAT_ZENOH_PORT)
       : null,
+    // Linux uses --network host, so the ports are already on the host.
+    pluginPorts: usesHostNetwork() ? [] : portRanges,
   });
 
   if (!bridgeStarted) {

package/cli/src/devBack.mjs

@@ -16,6 +16,7 @@ import { assertManifestPorts, manifestRuntime, readManifest, validateManifest }
 import {
   formatPortRanges,
   portEnvFlags,
+  publishPortFlags,
   startPortContractMonitor,
 } from "./ports.mjs";
 import {
@@ -108,6 +109,10 @@ async function runPython(root, portRanges) {
     !useHostNet && !bridgeContainer && !proxyEndpoint && zenohPort
       ? ["-p", `${zenohPort}:${zenohPort}`]
       : [];
+  // Standalone dev:back owns its netns, so it publishes its own declared ports.
+  // Under `dev` the bridge owns the netns and published them already.
+  const pluginPortFlags =
+    !useHostNet && !bridgeContainer ? publishPortFlags(portRanges) : [];
   const hostGatewayFlags = useHostNet || bridgeContainer
     ? []
     : ["--add-host", "host.docker.internal:host-gateway"];
@@ -142,7 +147,7 @@ async function runPython(root, portRanges) {
   docker(["rm", "-f", container], { stdio: "ignore" });
   log.step("starting Python dev container…");
   const up = docker(
-    ["run", "-d", "--name", container, ...netFlags, ...standaloneZenohPortFlags,
+    ["run", "-d", "--name", container, ...netFlags, ...standaloneZenohPortFlags, ...pluginPortFlags,
       // host.docker.internal is automatic on Docker Desktop (macOS/Windows);
       // this makes it resolve on Linux too, for the no-bridge gateway fallback above.
       ...hostGatewayFlags,
@@ -151,7 +156,7 @@ async function runPython(root, portRanges) {
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
-  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log });
+  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [zenohPort] });
 
   log.step("pip install requirements + watchfiles (in container)…");
   docker(["exec", container, "bash", "-lc",
@@ -440,7 +445,7 @@ async function runRos2(root, portRanges) {
   docker(["rm", "-f", container], { stdio: "ignore" });
   log.step("starting ROS2 dev container…");
   const up = docker(
-    ["run", "-d", "--name", container, "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", ROS2_DEV_IMAGE, "sleep", "infinity"],
+    ["run", "-d", "--name", container, ...publishPortFlags(portRanges), "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", ROS2_DEV_IMAGE, "sleep", "infinity"],
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
@@ -521,7 +526,7 @@ async function runCpp(root, portRanges) {
   docker(["rm", "-f", container], { stdio: "ignore" });
   log.step("starting C++ dev container…");
   const up = docker(
-    ["run", "-d", "--name", container, "-v", `${root}:/plugin`, "-w", "/plugin", CPP_DEV_IMAGE, "sleep", "infinity"],
+    ["run", "-d", "--name", container, ...publishPortFlags(portRanges), "-v", `${root}:/plugin`, "-w", "/plugin", CPP_DEV_IMAGE, "sleep", "infinity"],
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");

package/cli/src/ports.mjs

@@ -109,6 +109,15 @@ export function portEnvFlags(ranges) {
   return ["-e", `RB_PLUGIN_PORTS=${ranges.map(formatPortRange).join(",")}`];
 }
 
+/**
+ * `docker run -p` flags for the plugin's declared ports, so macOS/Windows can
+ * reach the backend's listeners (native Linux uses --network host and already
+ * has them). Only valid on the container that owns the netns.
+ */
+export function publishPortFlags(ranges = []) {
+  return ranges.flatMap((port) => ["-p", `127.0.0.1:${port}:${port}`]);
+}
+
 function listeningTcpPorts(container) {
   const script = `
 for f in /proc/net/tcp /proc/net/tcp6; do
@@ -131,26 +140,31 @@ done | sort -n -u
     .filter((v) => Number.isInteger(v));
 }
 
-export function startPortContractMonitor({ container, ranges, log, intervalMs = 1000 }) {
+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;
   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)]);
   let reported = false;
   const timer = setInterval(() => {
-    const ports = listeningTcpPorts(container)
-      .filter((port) => !INTERNAL_DEV_PORTS.has(port))
-      .filter((port) => isPluginManagedPort(port));
-    const unexpected = ports.filter((port) => reservedPortReason(port) || !portInRanges(port, declared));
+    // Every listening port that isn't declared is a violation — a port outside
+    // 28600-28999 can't be declared at all, so it must not be opened either.
+    // Otherwise it silently escapes both this check and rby2's install-time
+    // conflict check, and only collides once it's on a robot.
+    const unexpected = listeningTcpPorts(container)
+      .filter((port) => !ignored.has(port))
+      .filter((port) => !portInRanges(port, declared));
     if (unexpected.length === 0) return;
 
     clearInterval(timer);
     reported = true;
     const declaredText = declared.length > 0 ? formatPortRanges(declared) : "(none)";
     log.error(
-      `backend opened reserved or undeclared plugin TCP port(s): ${unexpected.join(", ")}. ` +
-      `Add them to manifest.json "ports" within ${PLUGIN_PORT_MIN}-${PLUGIN_PORT_MAX}. ` +
+      `backend opened undeclared TCP port(s): ${unexpected.join(", ")}. ` +
+      `Every listening port must be in manifest.json "ports" within ${PLUGIN_PORT_MIN}-${PLUGIN_PORT_MAX}. ` +
       `Declared: ${declaredText}`,
     );
     spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });

package/cli/src/python.mjs

@@ -3,7 +3,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+import { canSkipImageBuild, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
 
 export const PYTHON_DEV_IMAGE = "muscat-pk-python-dev";
 
@@ -15,6 +15,10 @@ 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)) {
+    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] : [];
@@ -66,6 +70,7 @@ export async function lockAndVendor(pluginRoot, archs = ["amd64", "arm64"]) {
     "docker",
     [
       "run", "--rm",
+      ...dockerUserFlags(),
       "-v", `${pluginRoot}:/plugin`,
       PYTHON_DEV_IMAGE,
       "bash", "-c",
@@ -85,6 +90,7 @@ export async function lockAndVendor(pluginRoot, archs = ["amd64", "arm64"]) {
       "docker",
       [
         "run", "--rm",
+        ...dockerUserFlags(),
         "-e", "PIP_ROOT_USER_ACTION=ignore",
         "-v", `${pluginRoot}:/plugin`,
         "-w", "/plugin",

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 { hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+import { canSkipImageBuild, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
 
 export const ROS2_DEV_IMAGE = "muscat-pk-ros2-dev";
 
@@ -30,6 +30,10 @@ 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)) {
+    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] : [];

package/cli/src/update.mjs

@@ -14,7 +14,7 @@ import { execSync, spawn } from "node:child_process";
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
-import { findPluginRoot, KIT_PUBLISHED_NAME, kitVersion, log, parseArgs, prompt } from "./util.mjs";
+import { findPluginRoot, isLocalKitInstall, KIT_PUBLISHED_NAME, kitVersion, log, parseArgs, prompt } from "./util.mjs";
 
 const PLUGIN_UI_PACKAGE = "@rainbow-robotics/plugin-ui";
 const S3_BASE = "https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit";
@@ -224,39 +224,47 @@ async function resolveTag(explicitTag) {
 }
 
 export async function runUpdate(args = []) {
-  const opts = parseArgs(args);
+  const opts = parseArgs(args, { booleans: ["global"] });
   const explicitTag = opts._[0] || opts.version || opts.tag || "";
   const tag = await resolveTag(explicitTag);
 
+  // 지금 도는 게 프로젝트의 로컬 설치면 그 프로젝트만 건드린다. 이 머신의 다른
+  // 프로젝트들이 쓰는 글로벌 CLI까지 같이 올리려면 --global을 명시해야 한다.
+  const runningLocal = isLocalKitInstall();
+
   // 1. Update the CLI itself
-  if (isBinaryMode) {
-    log.step("Updating binary…");
-    try {
-      await updateBinary(tag);
-    } catch (err) {
-      log.warn(`Binary update failed: ${err.message}`);
-    }
-  } else {
-    const isGlobal = (() => {
+  if (!runningLocal || opts.global) {
+    if (isBinaryMode) {
+      log.step("Updating binary…");
       try {
-        const prefix = execSync("npm prefix -g", { encoding: "utf8" }).trim();
-        return (
-          // Unix: {prefix}/bin/muscat-pk
-          existsSync(join(prefix, "bin", "muscat-pk")) ||
-          // Windows npm: {prefix}/muscat-pk.cmd (no bin/ subdir)
-          existsSync(join(prefix, "muscat-pk.cmd")) ||
-          existsSync(join(prefix, "bin", "muscat-pk.cmd"))
-        );
-      } catch { return false; }
-    })();
-
-    if (isGlobal) {
-      try {
-        updateNpmGlobal(tag);
+        await updateBinary(tag);
       } catch (err) {
-        log.warn(`Global CLI update failed: ${err.message}`);
+        log.warn(`Binary update failed: ${err.message}`);
+      }
+    } else {
+      const isGlobal = (() => {
+        try {
+          const prefix = execSync("npm prefix -g", { encoding: "utf8" }).trim();
+          return (
+            // Unix: {prefix}/bin/muscat-pk
+            existsSync(join(prefix, "bin", "muscat-pk")) ||
+            // Windows npm: {prefix}/muscat-pk.cmd (no bin/ subdir)
+            existsSync(join(prefix, "muscat-pk.cmd")) ||
+            existsSync(join(prefix, "bin", "muscat-pk.cmd"))
+          );
+        } catch { return false; }
+      })();
+
+      if (isGlobal) {
+        try {
+          updateNpmGlobal(tag);
+        } catch (err) {
+          log.warn(`Global CLI update failed: ${err.message}`);
+        }
       }
     }
+  } else {
+    log.info("Local install detected — updating this project only. Pass --global to also update the global CLI.");
   }
 
   // 2. Plugin project: structure migration + local deps

package/cli/src/util.mjs

@@ -1,7 +1,7 @@
 // Shared helpers for muscat-pk.
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { dirname, resolve, sep } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline/promises";
@@ -141,6 +141,23 @@ export function findPluginRoot(start = process.cwd()) {
   );
 }
 
+/** 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 is a project's local install (not global/binary). */
+export function isLocalKitInstall() {
+  return kitRoot.includes(`${sep}node_modules${sep}`);
+}
+
 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);
 
@@ -185,6 +202,34 @@ export function pruneMuskatImages() {
   );
 }
 
+/** 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.
+ */
+export function canSkipImageBuild(image) {
+  if (process.env.MUSCAT_PK_REBUILD_IMAGE === "1") return false;
+  return dockerImageExists(image);
+}
+
+// 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`;