@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.9 → 1.0.0

package/cli/src/uninstall.mjs

@@ -0,0 +1,98 @@
+// 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";
+
+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" });
+  log.ok("Global npm package removed.");
+}
+
+function uninstallBinary() {
+  const execPath = process.execPath;
+  log.step(`Removing binary: ${execPath}`);
+
+  if (process.platform === "win32") {
+    const ps = `Start-Sleep -Milliseconds 500; Remove-Item -Force '${execPath}'`;
+    spawn("powershell", ["-NoProfile", "-Command", ps], {
+      detached: true,
+      stdio: "ignore",
+    }).unref();
+    log.ok("Binary will be removed after this process exits.");
+    return;
+  }
+
+  try {
+    rmSync(execPath, { force: true });
+  } catch (err) {
+    if (err?.code !== "EACCES" && err?.code !== "EPERM") throw err;
+    log.info("  sudo is required...");
+    const result = spawnSync("sudo", ["rm", "-f", execPath], { stdio: "inherit" });
+    if (result.status !== 0) throw new Error(`sudo rm failed: ${execPath}`);
+  }
+
+  const parent = dirname(execPath);
+  for (const shim of ["muscat-pk.cmd", "muscat-pk.ps1"]) {
+    rmSync(join(parent, shim), { force: true });
+  }
+
+  log.ok("Binary removed.");
+}
+
+export async function runUninstall(args = []) {
+  const opts = parseArgs(args, { booleans: ["help"] });
+
+  if (opts.help) {
+    log.info(
+      [
+        "Usage: muscat-pk uninstall",
+        "",
+        "Removes the installed muscat-pk CLI.",
+        "  npm global install  -> npm uninstall -g @rainbow-robotics/muscat-plugin-kit",
+        "  S3 binary install   -> remove the muscat-pk executable",
+      ].join("\n"),
+    );
+    return;
+  }
+
+  if (isBinaryMode) {
+    uninstallBinary();
+    return;
+  }
+
+  if (isNpmGlobalInstall()) {
+    uninstallNpmGlobal();
+    return;
+  }
+
+  const localBin = process.argv[1] || "";
+  if (localBin.includes(`${join("node_modules", ".bin")}`) || existsSync(join(process.cwd(), "package.json"))) {
+    log.warn("This muscat-pk appears to be running from a project/local install.");
+    log.warn("Remove it from the project package manager instead, for example:");
+    log.warn(`  npm uninstall ${KIT_PUBLISHED_NAME}`);
+    return;
+  }
+
+  throw new Error("Could not determine install mode. Remove muscat-pk manually from your PATH.");
+}

package/cli/src/update.mjs

@@ -1,52 +1,281 @@
-// muscat-pk update — update the JS plugin kit and host-provided UI contract.
-import { execSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { findPluginRoot, KIT_PUBLISHED_NAME, log, parseArgs } from "./util.mjs";
+// muscat-pk update — update the CLI itself AND the plugin project's JS deps.
+//
+// Three install modes are handled:
+//   binary  : Bun self-contained binary downloaded from S3
+//             → re-download from S3, replace process.execPath
+//   npm -g  : globally installed Node.js package
+//             → npm install -g @rainbow-robotics/muscat-plugin-kit@<tag>
+//   local   : plugin project's node_modules (fallback)
+//             → <pm> add @rainbow-robotics/muscat-plugin-kit@<tag>
+//
+// 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 { join, resolve } from "node:path";
+import { findPluginRoot, 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";
+
+const isBinaryMode = typeof Bun !== "undefined";
+
+// ── helpers ───────────────────────────────────────────────────────────────────
 
 function detectPm(root) {
   try {
     const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
     if (pkg.packageManager) return pkg.packageManager.split("@")[0];
-  } catch {
-    /* ignore */
-  }
+  } catch { /* ignore */ }
   if (existsSync(resolve(root, "pnpm-lock.yaml"))) return "pnpm";
   if (existsSync(resolve(root, "yarn.lock"))) return "yarn";
   if (existsSync(resolve(root, "bun.lockb"))) return "bun";
   return "npm";
 }
 
-export async function runUpdate(args = []) {
-  const root = findPluginRoot();
-  const pm = detectPm(root);
-  const opts = parseArgs(args);
+async function fetchText(url) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${url}`);
+  return (await res.text()).trim();
+}
+
+async function fetchBinary(url) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${url}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+function s3BinaryName() {
+  const platform = process.platform;
+  const arch = process.arch;
+  const plat = platform === "win32" ? "win" : platform === "darwin" ? "darwin" : "linux";
+  const cpu = arch === "arm64" ? "arm64" : "x64";
+  const ext = platform === "win32" ? ".exe" : "";
+  return `muscat-pk-${plat}-${cpu}${ext}`;
+}
+
+async function resolveS3Version(tag) {
+  const pointer = tag === "dev" ? "dev-version.txt" : "latest-version.txt";
+  return fetchText(`${S3_BASE}/${pointer}`);
+}
+
+// ── self-update: binary ───────────────────────────────────────────────────────
+
+async function updateBinary(tag) {
+  const version = await resolveS3Version(tag);
+  const current = kitVersion();
+  if (version === current) {
+    log.ok(`Already up to date (v${current})`);
+    return;
+  }
 
-  const range =
-    opts._[0] ||
-    opts.version ||
-    opts["muscat-plugin-kit"] ||
-    opts["plugin-ui"] ||
-    "latest";
-  const list = [
-    `${KIT_PUBLISHED_NAME}@${range}`,
-    `${PLUGIN_UI_PACKAGE}@${range}`,
-  ];
+  const binaryName = s3BinaryName();
+  const url = `${S3_BASE}/v${version}/${binaryName}`;
+  log.step(`Downloading binary: v${current} → v${version}`);
+
+  const data = await fetchBinary(url);
+  const execPath = process.execPath;
+
+  if (process.platform === "win32") {
+    // Windows: cannot overwrite a running .exe — write .new then schedule replacement
+    const newPath = execPath + ".new";
+    writeFileSync(newPath, data);
+
+    // PowerShell snippet that waits for this process to exit, then renames
+    const ps = `Start-Sleep -Milliseconds 500; Move-Item -Force '${newPath}' '${execPath}'`;
+    spawn("powershell", ["-NoProfile", "-Command", ps], {
+      detached: true,
+      stdio: "ignore",
+    }).unref();
+
+    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);
+    log.ok(`Updated to v${version}.`);
+  }
+}
+
+// ── self-update: npm global ───────────────────────────────────────────────────
+
+function updateNpmGlobal(tag) {
+  log.step(`npm install -g ${KIT_PUBLISHED_NAME}@${tag}`);
+  execSync(`npm install -g ${KIT_PUBLISHED_NAME}@${tag}`, { stdio: "inherit" });
+  log.ok("Global CLI updated.");
+}
+
+// ── project structure migration ───────────────────────────────────────────────
+
+function detectOldStructure(root) {
+  const issues = [];
+
+  // src/ exists (old UI dir) or vite.config references src/content.tsx
+  const hasSrcDir = existsSync(resolve(root, "src"));
+  const hasUiDir  = existsSync(resolve(root, "ui"));
+  const viteRef   = (() => {
+    try {
+      return readFileSync(resolve(root, "vite.config.ts"), "utf8").includes("src/content.tsx");
+    } catch { return false; }
+  })();
+  if ((hasSrcDir || viteRef) && !hasUiDir) {
+    issues.push({ kind: "src→ui", desc: "src/  →  ui/  (+ vite.config.ts, tsconfig.json)" });
+  }
+
+  if (existsSync(resolve(root, "main.py")) && !existsSync(resolve(root, "py"))) {
+    issues.push({ kind: "main→py", desc: "main.py  →  py/main.py" });
+  }
+  if (existsSync(resolve(root, "backend"))) {
+    issues.push({ kind: "backend→py", desc: "backend/  →  py/" });
+  }
+  return issues;
+}
 
+async function migrateStructure(root, issues) {
+  log.warn("This plugin project's structure is outdated:");
+  for (const issue of issues) log.info("  • " + issue.desc);
+  log.warn("Files will be moved and modified. Back up or commit your work before proceeding.");
+
+  const answer = await prompt("Migrate project structure? [y/N] ");
+  if (answer.toLowerCase() !== "y") {
+    log.info("Structure migration skipped.");
+    return;
+  }
+
+  for (const issue of issues) {
+    if (issue.kind === "src→ui") {
+      if (existsSync(resolve(root, "src"))) {
+        renameSync(resolve(root, "src"), resolve(root, "ui"));
+        log.ok("src/  →  ui/");
+      }
+
+      const vitePath = resolve(root, "vite.config.ts");
+      if (existsSync(vitePath)) {
+        writeFileSync(vitePath, readFileSync(vitePath, "utf8").replace(/["']src\/content\.tsx["']/g, '"ui/content.tsx"'));
+        log.ok("vite.config.ts entry updated");
+      }
+      const tscPath = resolve(root, "tsconfig.json");
+      if (existsSync(tscPath)) {
+        writeFileSync(tscPath, readFileSync(tscPath, "utf8").replace(/"src"/g, '"ui"'));
+        log.ok("tsconfig.json include updated");
+      }
+    }
+
+    if (issue.kind === "main→py") {
+      mkdirSync(resolve(root, "py"), { recursive: true });
+      renameSync(resolve(root, "main.py"), resolve(root, "py", "main.py"));
+      log.ok("main.py  →  py/main.py");
+    }
+
+    if (issue.kind === "backend→py") {
+      renameSync(resolve(root, "backend"), resolve(root, "py"));
+      log.ok("backend/  →  py/");
+      const pyReqs = resolve(root, "py", "requirements.txt");
+      const rootReqs = resolve(root, "requirements.txt");
+      if (existsSync(pyReqs) && !existsSync(rootReqs)) {
+        renameSync(pyReqs, rootReqs);
+        log.ok("py/requirements.txt  →  requirements.txt (project root)");
+      }
+    }
+  }
+
+  log.ok("Migration complete. Run `muscat-pk build` to verify.");
+}
+
+// ── plugin project local deps ─────────────────────────────────────────────────
+
+function updateLocalDeps(root, tag) {
+  const pm = detectPm(root);
+  const list = [`${KIT_PUBLISHED_NAME}@${tag}`, `${PLUGIN_UI_PACKAGE}@${tag}`];
   const cmd =
-    pm === "npm"
-      ? `npm install ${list.join(" ")}`
-      : pm === "yarn"
-        ? `yarn add ${list.join(" ")}`
-        : `${pm} add ${list.join(" ")}`;
+    pm === "npm"   ? `npm install ${list.join(" ")}`
+    : pm === "yarn" ? `yarn add ${list.join(" ")}`
+    : `${pm} add ${list.join(" ")}`;
 
-  log.step(`${pm}: ${list.join(", ")}`);
+  log.step(`Updating plugin local deps (${pm}): ${list.join(", ")}`);
   try {
     execSync(cmd, { cwd: root, stdio: "inherit" });
-    log.ok("kit packages updated");
+    log.ok("Local deps updated.");
   } catch {
-    log.warn("update failed (offline?). Run manually:\n  " + cmd);
+    log.warn("Local deps update failed (offline?). Run manually:\n  " + cmd);
   }
 }
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+async function resolveTag(explicitTag) {
+  if (explicitTag) return explicitTag;
+
+  const current = kitVersion();
+  const isDevVersion = current.includes("-dev.");
+
+  if (!isDevVersion) return "latest";
+
+  const answer = await prompt(
+    `You are on a dev version (v${current}).\n` +
+    `  [1] Stay on dev  — update to latest dev build\n` +
+    `  [2] Switch to stable — update to latest stable release\n` +
+    `Choice [1/2, default: 1]: `
+  );
+  return answer.trim() === "2" ? "latest" : "dev";
+}
+
+export async function runUpdate(args = []) {
+  const opts = parseArgs(args);
+  const explicitTag = opts._[0] || opts.version || opts.tag || "";
+  const tag = await resolveTag(explicitTag);
+
+  // 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 = (() => {
+      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}`);
+      }
+    }
+  }
+
+  // 2. Plugin project: structure migration + local deps
+  let root;
+  try {
+    root = findPluginRoot();
+  } catch {
+    // Not inside a plugin project — skip
+    return;
+  }
+
+  try {
+    const structureIssues = detectOldStructure(root);
+    if (structureIssues.length > 0) {
+      await migrateStructure(root, structureIssues);
+    }
+  } catch (err) {
+    log.warn(`Structure check failed: ${err.message}`);
+  }
+
+  updateLocalDeps(root, tag);
+}

package/cli/src/util.mjs

@@ -1,8 +1,10 @@
 // Shared helpers for muscat-pk.
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } 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) {
@@ -37,6 +39,32 @@ export function venvPython(venvDir) {
     : 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 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;
+}
+
 /** Published install/CLI package name. Author imports use @rainbow-robotics/plugin-ui separately. */
 export const KIT_PUBLISHED_NAME = "@rainbow-robotics/muscat-plugin-kit";
 
@@ -65,6 +93,40 @@ export function parseArgs(args, { booleans = [] } = {}) {
   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). */
 export function findPluginRoot(start = process.cwd()) {
   let dir = resolve(start);
@@ -79,22 +141,74 @@ export function findPluginRoot(start = process.cwd()) {
   );
 }
 
-const ORANGE = "\x1b[33m";
-const RESET  = "\x1b[0m";
+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("›", ...m),
-  ok:   (...m) => console.log("✓", ...m),
-  warn: (...m) => console.warn(`${ORANGE}⚠${RESET}`, ...m.map(s => `${ORANGE}${s}${RESET}`)),
+  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 dev bridge, and cpp/ros2
+// compilation in Docker. Show a clear install hint when Docker is missing.
+export function ensureDocker() {
+  if (hasBin("docker")) return;
+  log.warn("Docker not found.");
+  log.warn("  muscat-pk runs the plugin back end, the dev bridge, 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.");
+}
+
+/**
+ * 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" },
+  );
+}
+
 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() {
   try {
@@ -144,8 +258,8 @@ export async function checkKitUpdate({ timeoutMs = 2000 } = {}) {
         [
           "",
           line,
-          `  muscat-plugin-kit 새 버전이 있습니다: ${current} → ${latest}`,
-          `  업데이트:  muscat-pk update`,
+          `  muscat-plugin-kit update available: ${current} → ${latest}`,
+          `  Update:  muscat-pk update`,
           line,
           "",
         ].join("\n"),

package/cli/src/zenohDev.mjs

@@ -0,0 +1,75 @@
+// Remote-robot Zenoh dev networking helpers, shared by `muscat-pk dev` and
+// standalone `muscat-pk dev:back`.
+//
+// The plugin backend runs in a Docker container. When it connects to a REMOTE
+// robot, rainbow.rb_sdk registers this machine as a Zenoh peer and the robot's
+// `common` service connects BACK to the advertised ip:port to form the mesh.
+// Inside a container, the SDK's own _detect_local_ip() returns the container's
+// internal IP (unreachable from the robot) and lets the OS pick a random listen
+// port (unpublished) — so the reverse connection never lands and SDK calls like
+// call_move_j get no reply. We fix both ends:
+//   - MUSCAT_ZENOH_ADVERTISE_HOST → the host's LAN IP toward the robot, which
+//     devBack's entry script uses to override _detect_local_ip.
+//   - MUSCAT_ZENOH_PORT → a fixed, host-published listen port the robot can reach.
+import { createSocket } from "node:dgram";
+import { createServer } from "node:net";
+
+export const DEFAULT_ZENOH_DEV_PORT = 53917;
+export const LOCAL_HOSTS = new Set(["", "localhost", "127.0.0.1", "::1"]);
+
+export const isRemoteRobot = (robotIp) => !!robotIp && !LOCAL_HOSTS.has(robotIp);
+
+/** The local interface IP the OS would use to reach `host` (no packet sent). */
+export function detectRouteAddress(host) {
+  return new Promise((resolve) => {
+    const socket = createSocket("udp4");
+    socket.once("error", () => {
+      socket.close();
+      resolve("");
+    });
+    socket.connect(80, host, () => {
+      const address = socket.address();
+      socket.close();
+      resolve(typeof address === "object" ? address.address : "");
+    });
+  });
+}
+
+/** `preferred` if free, otherwise an OS-assigned free port. */
+export function getFreePort(preferred) {
+  return new Promise((resolve) => {
+    const srv = createServer();
+    srv.once("error", () => {
+      const fallback = createServer();
+      fallback.listen(0, "0.0.0.0", () => {
+        const address = fallback.address();
+        const port = typeof address === "object" && address ? address.port : preferred;
+        fallback.close(() => resolve(port));
+      });
+    });
+    srv.listen(preferred, "0.0.0.0", () => srv.close(() => resolve(preferred)));
+  });
+}
+
+/**
+ * Compute and set MUSCAT_ZENOH_ADVERTISE_HOST / MUSCAT_ZENOH_PORT for a remote
+ * robot, unless already set by a parent command (idempotent). No-op for a local
+ * robot. Returns the resolved { advertiseHost, zenohPort } (or null if local).
+ */
+export async function ensureRemoteZenohEnv(robotIp, { log } = {}) {
+  if (!isRemoteRobot(robotIp)) return null;
+  // Already set (e.g. `muscat-pk dev` computed it before starting the bridge).
+  if (process.env.MUSCAT_ZENOH_PORT) {
+    return {
+      advertiseHost: process.env.MUSCAT_ZENOH_ADVERTISE_HOST || "",
+      zenohPort: Number(process.env.MUSCAT_ZENOH_PORT),
+    };
+  }
+  const advertiseHost =
+    process.env.MUSCAT_ZENOH_ADVERTISE_HOST || (await detectRouteAddress(robotIp));
+  const zenohPort = await getFreePort(DEFAULT_ZENOH_DEV_PORT);
+  if (advertiseHost) process.env.MUSCAT_ZENOH_ADVERTISE_HOST = advertiseHost;
+  process.env.MUSCAT_ZENOH_PORT = String(zenohPort);
+  log?.step?.(`remote Zenoh dev peer → ${advertiseHost || "(auto)"}:${zenohPort}`);
+  return { advertiseHost, zenohPort };
+}