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

package/cli/src/muscatLocal.mjs

@@ -1,209 +1,209 @@
-// Local Muscat runtime for `dev` / `dev:ui`, with or without a robot. It is the plugin gateway
-// (:10000, plugin-socketio — same Socket.IO protocol as on the robot), MediaMTX, and `common`:
-// preview-host hits http://localhost:3000/common/* (baked into the nexus bundle), so program
-// preview works with no front-end change. The backend container joins its netns. We reuse any
-// Muscat already publishing :10000 (e.g. a `muscat` / `muscat-dev` container) and only otherwise
-// start our own: the S3 runtime image with just the `common` service.
-import { spawnSync } from "node:child_process";
-import { createServer } from "node:net";
-import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { resolve } from "node:path";
-import { mediaPortFlags, MEDIA_PORTS, publishPortFlags } from "./ports.mjs";
-import { canSkipImageBuild, hasBin, log, buildCacheFlags } from "./util.mjs";
-import { LOCAL_HOSTS } from "./zenohDev.mjs";
-
-export const MUSCAT_CONTAINER = "muscat-pk-muscat";
-// Ports published for the backend (it shares this container's netns); a different set recreates it.
-const PORTS_LABEL = "com.rainbow-robotics.muscat-pk.ports";
-const IMAGE = "muscat-pk-runtime";
-const S3 = process.env.MUSCAT_PK_MUSCAT_S3 ?? "https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat/main";
-const CACHE = resolve(homedir(), ".muscat-pk", "muscat");
-const API_PORT = 3000;
-export const GATEWAY_PORT = 10000;
-// The bin runs inside Docker, so follow the Docker engine's arch, not this Node's
-// (Rosetta/x64 Node on an Apple Silicon host would otherwise pick amd64).
-const dockerArch = () => {
-  const r = spawnSync("docker", ["version", "--format", "{{.Server.Arch}}"], { encoding: "utf8" });
-  const a = (r.stdout || "").trim();
-  return a === "arm64" || a === "amd64" ? a : process.arch === "arm64" ? "arm64" : "amd64";
-};
-
-async function fetchBuffer(url) {
-  const res = await fetch(url);
-  if (!res.ok) throw new Error(`HTTP ${res.status}: ${url}`);
-  return Buffer.from(await res.arrayBuffer());
-}
-
-// macOS/Windows `tar` reads zip; GNU tar does not, Linux has `unzip`.
-function extractZip(zip, dir, members = []) {
-  mkdirSync(dir, { recursive: true });
-  const tries = [
-    ["unzip", ["-o", "-q", zip, ...members, "-d", dir]],
-    ["tar", ["-xf", zip, "-C", dir, ...members]],
-  ];
-  for (const [bin, args] of tries) {
-    if (hasBin(bin) && spawnSync(bin, args, { stdio: "ignore" }).status === 0) return;
-  }
-  throw new Error(`could not extract ${zip} (needs unzip or tar)`);
-}
-
-async function resolveVersions() {
-  const file = resolve(CACHE, "version.json");
-  try {
-    const data = await fetchBuffer(`${S3}/version.json`);
-    mkdirSync(CACHE, { recursive: true });
-    writeFileSync(file, data);
-    return JSON.parse(data.toString());
-  } catch (e) {
-    if (!existsSync(file)) throw e;
-    log.warn(`version.json unreachable (${e.message}) — using cached Muscat version`);
-    return JSON.parse(readFileSync(file, "utf8"));
-  }
-}
-
-async function ensureRuntimeImage(total) {
-  const image = `${IMAGE}:${total}`;
-  if (canSkipImageBuild(image)) return image;
-  const dir = resolve(CACHE, "runtime", total);
-  if (!existsSync(resolve(dir, "Dockerfile.runtime"))) {
-    log.step(`downloading Muscat runtime scripts (muscat.zip ${total})…`);
-    const zip = resolve(CACHE, "muscat.zip");
-    writeFileSync(zip, await fetchBuffer(`${S3}/muscat.zip`));
-    extractZip(zip, dir);
-    rmSync(zip, { force: true });
-  }
-  log.step(`docker build -t ${image} (first run downloads MongoDB/InfluxDB/ROS base — slow, then cached)…`);
-  const r = spawnSync(
-    "docker",
-    ["build", ...buildCacheFlags(), "-t", image, "-f", resolve(dir, "Dockerfile.runtime"), "--label", "com.rainbow-robotics.muscat-pk=true", dir],
-    { stdio: "inherit" },
-  );
-  if (r.status !== 0) throw new Error("docker build failed (Muscat runtime image).");
-  return image;
-}
-
-async function ensureCommonBinary(version) {
-  const ARCH = dockerArch();
-  const dir = resolve(CACHE, "services", "common");
-  const stamp = resolve(dir, ".version");
-  if (existsSync(stamp) && readFileSync(stamp, "utf8").trim() === version && existsSync(resolve(dir, `common.${ARCH}.bin`))) return dir;
-  log.step(`downloading Muscat common service ${version} (${ARCH})…`);
-  const zip = resolve(CACHE, `common-${version}.zip`);
-  writeFileSync(zip, await fetchBuffer(`${S3}/common/${version}.zip`));
-  extractZip(zip, dir, ["config.env", `common.${ARCH}.bin`]);
-  rmSync(zip, { force: true });
-  chmodSync(resolve(dir, `common.${ARCH}.bin`), 0o755);
-  writeFileSync(stamp, `${version}\n`);
-  return dir;
-}
-
-async function waitForApi(timeoutMs = 180_000) {
-  const start = Date.now();
-  for (;;) {
-    try {
-      const res = await fetch(`http://127.0.0.1:${API_PORT}/common/docs`);
-      if (res.ok) return;
-    } catch { /* not listening yet */ }
-    if (Date.now() - start > timeoutMs) throw new Error(`Muscat did not answer on :${API_PORT} in time — see \`docker logs ${MUSCAT_CONTAINER}\``);
-    await new Promise((r) => setTimeout(r, 1000));
-  }
-}
-
-// Does the robot at `ip` run Muscat (common answers /is-muscat)? Then the dev UI and backend use its
-// gateway and no local Muscat is started. Local addresses and unreachable hosts → false.
-export async function robotHasMuscat(ip) {
-  if (!ip || LOCAL_HOSTS.has(ip)) return false;
-  try {
-    const res = await fetch(`http://${ip}:${API_PORT}/common/is-muscat`, { signal: AbortSignal.timeout(3000) });
-    return res.ok && (await res.json())?.result === true;
-  } catch {
-    return false;
-  }
-}
-
-// Is a host TCP port already bound?
-export function isPortInUse(port) {
-  return new Promise((res) => {
-    const srv = createServer();
-    srv.once("error", (err) => res(err.code === "EADDRINUSE"));
-    srv.once("listening", () => srv.close(() => res(false)));
-    srv.listen(port, "0.0.0.0");
-  });
-}
-
-/** A running Muscat container (ours or e.g. muscat-dev) that owns host port 10000, or null. */
-export function localMuscatContainer() {
-  const r = spawnSync("docker", ["ps", "--filter", `publish=${GATEWAY_PORT}`, "--format", "{{.Names}}"], { encoding: "utf8" });
-  return (r.stdout || "").split("\n").map((n) => n.trim()).find(Boolean) ?? null;
-}
-
-const containerLabel = (name, label) =>
-  spawnSync("docker", ["inspect", "-f", `{{index .Config.Labels "${label}"}}`, name], { encoding: "utf8" }).stdout?.trim() ?? "";
-
-/**
- * Make sure a Muscat answers on localhost:3000 / :10000. Returns the container name,
- * or null when one can't be started (no Docker, foreign process on the ports).
- * The container is left running across runs — stop it with `docker rm -f muscat-pk-muscat`.
- */
-export async function ensureLocalMuscat({ pluginPorts = [], zenohPort = null } = {}) {
-  if (process.env.MUSCAT_PK_NO_LOCAL_MUSCAT === "1") return null;
-  const portsKey = [...pluginPorts, ...(zenohPort ? [`zenoh:${zenohPort}`] : [])].join(",");
-  const existing = hasBin("docker") ? localMuscatContainer() : null;
-  if (existing === MUSCAT_CONTAINER && containerLabel(existing, PORTS_LABEL) !== portsKey) {
-    log.step(`recreating local Muscat to publish ${portsKey || "no extra"} port(s)`);
-    spawnSync("docker", ["rm", "-f", MUSCAT_CONTAINER], { stdio: "ignore" });
-  } else if (existing) {
-    if (existing !== MUSCAT_CONTAINER && portsKey)
-      log.warn(`'${existing}' is not managed by muscat-pk — port(s) ${portsKey} are not published from it.`);
-    return existing;
-  }
-  if (!hasBin("docker")) {
-    log.warn("Docker not found — no local Muscat; program preview will have no back end.");
-    return null;
-  }
-  // Ports taken but no container publishing them: usually a Muscat on host networking (robot PC,
-  // CI runner) — the caller uses it as is.
-  for (const port of [API_PORT, GATEWAY_PORT]) {
-    if (await isPortInUse(port)) return null;
-  }
-
-  const versions = await resolveVersions();
-  const total = versions.total;
-  const commonVersion = versions.services?.common?.version;
-  if (!total || !commonVersion) throw new Error("version.json has no total / services.common.version");
-
-  const image = await ensureRuntimeImage(total);
-  const commonDir = await ensureCommonBinary(commonVersion);
-
-  let media = true;
-  for (const port of MEDIA_PORTS) if (await isPortInUse(port)) media = false;
-  // A busy plugin port would make `docker run` fail with a raw daemon error — skip it and say so.
-  const busy = [];
-  for (const port of pluginPorts) if (await isPortInUse(port)) busy.push(port);
-  if (busy.length) log.warn(`plugin port(s) already in use on the host: ${busy.join(", ")} — not published (the backend still listens inside).`);
-  const published = pluginPorts.filter((port) => !busy.includes(port));
-
-  spawnSync("docker", ["rm", "-f", MUSCAT_CONTAINER], { stdio: "ignore" });
-  log.step(`starting local Muscat (common ${commonVersion}) → http://localhost:${API_PORT}/common/docs`);
-  const r = spawnSync("docker", [
-    "run", "-d", "--name", MUSCAT_CONTAINER, "--label", "com.rainbow-robotics.muscat-pk=true", "--label", `${PORTS_LABEL}=${portsKey}`,
-    "-e", "RB_ENABLED_SERVICES=common",
-    "-e", "RB_RUNTIME_ENABLE_ZENOH_BRIDGE=0",
-    "-v", `${commonDir}:/app/services/common`,
-    "-v", `${resolve(CACHE, "data")}:/app/data`,
-    "-p", `127.0.0.1:${API_PORT}:${API_PORT}`,
-    "-p", `127.0.0.1:${GATEWAY_PORT}:${GATEWAY_PORT}`,
-    ...(media ? mediaPortFlags() : []),
-    ...publishPortFlags(published),
-    // The robot reverse-dials the backend's Zenoh session from the LAN, so not loopback-only.
-    ...(zenohPort ? ["-p", `${zenohPort}:${zenohPort}`] : []),
-    image,
-  ], { stdio: ["ignore", "ignore", "inherit"] });
-  if (r.status !== 0) throw new Error("failed to start the local Muscat container.");
-  await waitForApi();
-  log.step(`local Muscat ready — keeps running between runs; stop with: docker rm -f ${MUSCAT_CONTAINER}`);
-  if (published.length) log.step(`plugin backend ports published on 127.0.0.1: ${published.join(", ")}`);
-  if (zenohPort) log.step(`Zenoh dev peer port published on :${zenohPort}`);
-  return MUSCAT_CONTAINER;
-}
+// Local Muscat runtime for `dev` / `dev:ui`, with or without a robot. It is the plugin gateway
+// (:10000, plugin-socketio — same Socket.IO protocol as on the robot), MediaMTX, and `common`:
+// preview-host hits http://localhost:3000/common/* (baked into the nexus bundle), so program
+// preview works with no front-end change. The backend container joins its netns. We reuse any
+// Muscat already publishing :10000 (e.g. a `muscat` / `muscat-dev` container) and only otherwise
+// start our own: the S3 runtime image with just the `common` service.
+import { spawnSync } from "node:child_process";
+import { createServer } from "node:net";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { mediaPortFlags, MEDIA_PORTS, publishPortFlags } from "./ports.mjs";
+import { canSkipImageBuild, hasBin, log, buildCacheFlags } from "./util.mjs";
+import { LOCAL_HOSTS } from "./zenohDev.mjs";
+
+export const MUSCAT_CONTAINER = "muscat-pk-muscat";
+// Ports published for the backend (it shares this container's netns); a different set recreates it.
+const PORTS_LABEL = "com.rainbow-robotics.muscat-pk.ports";
+const IMAGE = "muscat-pk-runtime";
+const S3 = process.env.MUSCAT_PK_MUSCAT_S3 ?? "https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat/main";
+const CACHE = resolve(homedir(), ".muscat-pk", "muscat");
+const API_PORT = 3000;
+export const GATEWAY_PORT = 10000;
+// The bin runs inside Docker, so follow the Docker engine's arch, not this Node's
+// (Rosetta/x64 Node on an Apple Silicon host would otherwise pick amd64).
+const dockerArch = () => {
+  const r = spawnSync("docker", ["version", "--format", "{{.Server.Arch}}"], { encoding: "utf8" });
+  const a = (r.stdout || "").trim();
+  return a === "arm64" || a === "amd64" ? a : process.arch === "arm64" ? "arm64" : "amd64";
+};
+
+async function fetchBuffer(url) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${url}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+// macOS/Windows `tar` reads zip; GNU tar does not, Linux has `unzip`.
+function extractZip(zip, dir, members = []) {
+  mkdirSync(dir, { recursive: true });
+  const tries = [
+    ["unzip", ["-o", "-q", zip, ...members, "-d", dir]],
+    ["tar", ["-xf", zip, "-C", dir, ...members]],
+  ];
+  for (const [bin, args] of tries) {
+    if (hasBin(bin) && spawnSync(bin, args, { stdio: "ignore" }).status === 0) return;
+  }
+  throw new Error(`could not extract ${zip} (needs unzip or tar)`);
+}
+
+async function resolveVersions() {
+  const file = resolve(CACHE, "version.json");
+  try {
+    const data = await fetchBuffer(`${S3}/version.json`);
+    mkdirSync(CACHE, { recursive: true });
+    writeFileSync(file, data);
+    return JSON.parse(data.toString());
+  } catch (e) {
+    if (!existsSync(file)) throw e;
+    log.warn(`version.json unreachable (${e.message}) — using cached Muscat version`);
+    return JSON.parse(readFileSync(file, "utf8"));
+  }
+}
+
+async function ensureRuntimeImage(total) {
+  const image = `${IMAGE}:${total}`;
+  if (canSkipImageBuild(image)) return image;
+  const dir = resolve(CACHE, "runtime", total);
+  if (!existsSync(resolve(dir, "Dockerfile.runtime"))) {
+    log.step(`downloading Muscat runtime scripts (muscat.zip ${total})…`);
+    const zip = resolve(CACHE, "muscat.zip");
+    writeFileSync(zip, await fetchBuffer(`${S3}/muscat.zip`));
+    extractZip(zip, dir);
+    rmSync(zip, { force: true });
+  }
+  log.step(`docker build -t ${image} (first run downloads MongoDB/InfluxDB/ROS base — slow, then cached)…`);
+  const r = spawnSync(
+    "docker",
+    ["build", ...buildCacheFlags(), "-t", image, "-f", resolve(dir, "Dockerfile.runtime"), "--label", "com.rainbow-robotics.muscat-pk=true", dir],
+    { stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error("docker build failed (Muscat runtime image).");
+  return image;
+}
+
+async function ensureCommonBinary(version) {
+  const ARCH = dockerArch();
+  const dir = resolve(CACHE, "services", "common");
+  const stamp = resolve(dir, ".version");
+  if (existsSync(stamp) && readFileSync(stamp, "utf8").trim() === version && existsSync(resolve(dir, `common.${ARCH}.bin`))) return dir;
+  log.step(`downloading Muscat common service ${version} (${ARCH})…`);
+  const zip = resolve(CACHE, `common-${version}.zip`);
+  writeFileSync(zip, await fetchBuffer(`${S3}/common/${version}.zip`));
+  extractZip(zip, dir, ["config.env", `common.${ARCH}.bin`]);
+  rmSync(zip, { force: true });
+  chmodSync(resolve(dir, `common.${ARCH}.bin`), 0o755);
+  writeFileSync(stamp, `${version}\n`);
+  return dir;
+}
+
+async function waitForApi(timeoutMs = 180_000) {
+  const start = Date.now();
+  for (;;) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${API_PORT}/common/docs`);
+      if (res.ok) return;
+    } catch { /* not listening yet */ }
+    if (Date.now() - start > timeoutMs) throw new Error(`Muscat did not answer on :${API_PORT} in time — see \`docker logs ${MUSCAT_CONTAINER}\``);
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+}
+
+// Does the robot at `ip` run Muscat (common answers /is-muscat)? Then the dev UI and backend use its
+// gateway and no local Muscat is started. Local addresses and unreachable hosts → false.
+export async function robotHasMuscat(ip) {
+  if (!ip || LOCAL_HOSTS.has(ip)) return false;
+  try {
+    const res = await fetch(`http://${ip}:${API_PORT}/common/is-muscat`, { signal: AbortSignal.timeout(3000) });
+    return res.ok && (await res.json())?.result === true;
+  } catch {
+    return false;
+  }
+}
+
+// Is a host TCP port already bound?
+export function isPortInUse(port) {
+  return new Promise((res) => {
+    const srv = createServer();
+    srv.once("error", (err) => res(err.code === "EADDRINUSE"));
+    srv.once("listening", () => srv.close(() => res(false)));
+    srv.listen(port, "0.0.0.0");
+  });
+}
+
+/** A running Muscat container (ours or e.g. muscat-dev) that owns host port 10000, or null. */
+export function localMuscatContainer() {
+  const r = spawnSync("docker", ["ps", "--filter", `publish=${GATEWAY_PORT}`, "--format", "{{.Names}}"], { encoding: "utf8" });
+  return (r.stdout || "").split("\n").map((n) => n.trim()).find(Boolean) ?? null;
+}
+
+const containerLabel = (name, label) =>
+  spawnSync("docker", ["inspect", "-f", `{{index .Config.Labels "${label}"}}`, name], { encoding: "utf8" }).stdout?.trim() ?? "";
+
+/**
+ * Make sure a Muscat answers on localhost:3000 / :10000. Returns the container name,
+ * or null when one can't be started (no Docker, foreign process on the ports).
+ * The container is left running across runs — stop it with `docker rm -f muscat-pk-muscat`.
+ */
+export async function ensureLocalMuscat({ pluginPorts = [], zenohPort = null } = {}) {
+  if (process.env.MUSCAT_PK_NO_LOCAL_MUSCAT === "1") return null;
+  const portsKey = [...pluginPorts, ...(zenohPort ? [`zenoh:${zenohPort}`] : [])].join(",");
+  const existing = hasBin("docker") ? localMuscatContainer() : null;
+  if (existing === MUSCAT_CONTAINER && containerLabel(existing, PORTS_LABEL) !== portsKey) {
+    log.step(`recreating local Muscat to publish ${portsKey || "no extra"} port(s)`);
+    spawnSync("docker", ["rm", "-f", MUSCAT_CONTAINER], { stdio: "ignore" });
+  } else if (existing) {
+    if (existing !== MUSCAT_CONTAINER && portsKey)
+      log.warn(`'${existing}' is not managed by muscat-pk — port(s) ${portsKey} are not published from it.`);
+    return existing;
+  }
+  if (!hasBin("docker")) {
+    log.warn("Docker not found — no local Muscat; program preview will have no back end.");
+    return null;
+  }
+  // Ports taken but no container publishing them: usually a Muscat on host networking (robot PC,
+  // CI runner) — the caller uses it as is.
+  for (const port of [API_PORT, GATEWAY_PORT]) {
+    if (await isPortInUse(port)) return null;
+  }
+
+  const versions = await resolveVersions();
+  const total = versions.total;
+  const commonVersion = versions.services?.common?.version;
+  if (!total || !commonVersion) throw new Error("version.json has no total / services.common.version");
+
+  const image = await ensureRuntimeImage(total);
+  const commonDir = await ensureCommonBinary(commonVersion);
+
+  let media = true;
+  for (const port of MEDIA_PORTS) if (await isPortInUse(port)) media = false;
+  // A busy plugin port would make `docker run` fail with a raw daemon error — skip it and say so.
+  const busy = [];
+  for (const port of pluginPorts) if (await isPortInUse(port)) busy.push(port);
+  if (busy.length) log.warn(`plugin port(s) already in use on the host: ${busy.join(", ")} — not published (the backend still listens inside).`);
+  const published = pluginPorts.filter((port) => !busy.includes(port));
+
+  spawnSync("docker", ["rm", "-f", MUSCAT_CONTAINER], { stdio: "ignore" });
+  log.step(`starting local Muscat (common ${commonVersion}) → http://localhost:${API_PORT}/common/docs`);
+  const r = spawnSync("docker", [
+    "run", "-d", "--name", MUSCAT_CONTAINER, "--label", "com.rainbow-robotics.muscat-pk=true", "--label", `${PORTS_LABEL}=${portsKey}`,
+    "-e", "RB_ENABLED_SERVICES=common",
+    "-e", "RB_RUNTIME_ENABLE_ZENOH_BRIDGE=0",
+    "-v", `${commonDir}:/app/services/common`,
+    "-v", `${resolve(CACHE, "data")}:/app/data`,
+    "-p", `127.0.0.1:${API_PORT}:${API_PORT}`,
+    "-p", `127.0.0.1:${GATEWAY_PORT}:${GATEWAY_PORT}`,
+    ...(media ? mediaPortFlags() : []),
+    ...publishPortFlags(published),
+    // The robot reverse-dials the backend's Zenoh session from the LAN, so not loopback-only.
+    ...(zenohPort ? ["-p", `${zenohPort}:${zenohPort}`] : []),
+    image,
+  ], { stdio: ["ignore", "ignore", "inherit"] });
+  if (r.status !== 0) throw new Error("failed to start the local Muscat container.");
+  await waitForApi();
+  log.step(`local Muscat ready — keeps running between runs; stop with: docker rm -f ${MUSCAT_CONTAINER}`);
+  if (published.length) log.step(`plugin backend ports published on 127.0.0.1: ${published.join(", ")}`);
+  if (zenohPort) log.step(`Zenoh dev peer port published on :${zenohPort}`);
+  return MUSCAT_CONTAINER;
+}