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

package/cli/src/util.mjs

@@ -1,8 +1,11 @@
 // Shared helpers for muscat-pk.
-import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { execSync, spawn, 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) {
@@ -37,6 +40,63 @@ 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 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";
 
@@ -65,7 +125,96 @@ 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 optional 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.
+ * An empty token is allowed: the robot API is then called without an Authorization header.
+ */
+export async function promptRobotConnection(args = []) {
+  const parsed = parseArgs(args);
+  // A simulator stands in for the robot.
+  if (parsed.sim !== undefined) return { robotIp: "", robotToken: "" };
+  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 (optional, Enter to skip): "));
+
+  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;
+}
+
+// Per-project dev output (staged UI assets, ROS peers, C++ sysroot). The leading dot hides it on macOS
+// and Linux; Windows needs the hidden attribute, set on every call so folders made by older kits hide too.
+export const DEV_DIR = ".muscat-dev";
+export function ensureDevDir(root) {
+  const dir = resolve(root, DEV_DIR);
+  mkdirSync(dir, { recursive: true });
+  if (process.platform === "win32") spawnSync("attrib", ["+h", dir], { stdio: "ignore" });
+  return dir;
+}
+
 export function findPluginRoot(start = process.cwd()) {
   let dir = resolve(start);
   for (;;) {
@@ -79,24 +228,175 @@ export function findPluginRoot(start = process.cwd()) {
   );
 }
 
-const ORANGE = "\x1b[33m";
-const RESET  = "\x1b[0m";
+/** 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("›", ...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 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.
+ * A rebuilt image's old layers stay in the build cache, which has no labels: drop cache
+ * nobody used for 30 days.
+ */
+export function pruneMuskatImages() {
+  spawnSync(
+    "docker",
+    ["image", "prune", "--force", "--filter", "label=com.rainbow-robotics.muscat-pk=true"],
+    { stdio: "ignore" },
+  );
+  spawnSync("docker", ["builder", "prune", "--force", "--filter", "until=720h"], { stdio: "ignore" });
+  spawnSync("docker", ["rmi", "muscat-pk-bridge"], { stdio: "ignore" }); // earlier kits' image
+}
+
+/**
+ * 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;
@@ -119,6 +419,18 @@ export function isNewer(a, b) {
   return a3 > b3;
 }
 
+/** Compare "x.y.z[-dev.N]" including the dev number (a release sorts after its dev builds). <0, 0, >0. */
+export function compareKitVersions(a, b) {
+  const parse = (v) => {
+    const [rel, pre] = String(v).split("-");
+    const nums = rel.split(".").map((n) => parseInt(n, 10) || 0);
+    return [...nums, pre === undefined ? Infinity : parseInt(pre.split(".").pop(), 10) || 0];
+  };
+  const pa = parse(a), pb = parse(b);
+  for (let i = 0; i < 4; i++) if (pa[i] !== pb[i]) return pa[i] > pb[i] ? 1 : -1;
+  return 0;
+}
+
 /**
  * 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
@@ -144,8 +456,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"),
@@ -155,3 +467,21 @@ export async function checkKitUpdate({ timeoutMs = 2000 } = {}) {
     /* offline or registry unreachable — ignore */
   }
 }
+
+export function openBrowser(url) {
+  const cmd =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "start"
+        : "xdg-open";
+  try {
+    spawn(cmd, [url], {
+      stdio: "ignore",
+      detached: true,
+      shell: process.platform === "win32",
+    }).unref();
+  } catch {
+    /* headless / no browser — the URL is printed anyway */
+  }
+}

package/cli/src/zenohDev.mjs

@@ -0,0 +1,83 @@
+// 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";
+import { release } from "node:os";
+
+export const DEFAULT_ZENOH_DEV_PORT = 53917;
+export const LOCAL_HOSTS = new Set(["", "localhost", "127.0.0.1", "::1"]);
+
+// Native Linux (not WSL) has real Docker host networking — dev:back runs with
+// --network host and reaches the robot/bridge directly. macOS/Windows/WSL don't.
+export const isWsl = () => process.platform === "linux" && /microsoft|wsl/i.test(release());
+// MUSCAT_PK_HOST_NETWORK=0 (CI): run the Docker Desktop (bridge) path on native Linux too.
+export const usesHostNetwork = () =>
+  process.env.MUSCAT_PK_HOST_NETWORK !== "0" && process.platform === "linux" && !isWsl();
+
+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 };
+}

package/cli/src/zip.mjs

@@ -0,0 +1,121 @@
+// Minimal ZIP writer (deflate) for `muscat-pk build`, instead of the `zip` CLI that Windows lacks.
+//
+// Entries carry Unix modes because the robot is Linux: C++ binaries and ROS 2 node scripts must stay
+// executable. macOS/Linux store each file's real mode. Windows (NTFS) has no executable bit, so there
+// an ELF binary or a `#!` script is stored as 0755 and everything else as 0644.
+// Like `zip -r`, symlinks are followed and their targets' contents stored. No ZIP64: a plugin ZIP over
+// 4 GB or 65535 entries is refused.
+import { closeSync, openSync, readdirSync, readFileSync, readSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { deflateRawSync } from "node:zlib";
+
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  return c >>> 0;
+});
+
+function crc32(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function dosTime(date) {
+  const d = date.getFullYear() < 1980 ? new Date(1980, 0, 1) : date;
+  return {
+    time: (d.getHours() << 11) | (d.getMinutes() << 5) | (d.getSeconds() >> 1),
+    date: ((d.getFullYear() - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate(),
+  };
+}
+
+function looksExecutable(file) {
+  const head = Buffer.alloc(4);
+  const fd = openSync(file, "r");
+  try {
+    readSync(fd, head, 0, 4, 0);
+  } finally {
+    closeSync(fd);
+  }
+  return head.equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])) || (head[0] === 0x23 && head[1] === 0x21);
+}
+
+function unixMode(file, stat) {
+  if (stat.isDirectory()) return 0o40755;
+  if (process.platform !== "win32") return 0o100000 | (stat.mode & 0o777);
+  return 0o100000 | (looksExecutable(file) ? 0o755 : 0o644);
+}
+
+function collect(root, rel, out) {
+  const full = resolve(root, rel);
+  const stat = statSync(full);
+  if (stat.isDirectory()) {
+    out.push({ name: `${rel.split(sep).join("/")}/`, full, stat });
+    for (const child of readdirSync(full).sort()) collect(root, join(rel, child), out);
+  } else {
+    out.push({ name: rel.split(sep).join("/"), full, stat });
+  }
+}
+
+/** Write `entries` (paths relative to `cwd`, files or directories) into a new ZIP at `zipPath`. */
+export function writeZip(zipPath, entries, cwd) {
+  const items = [];
+  for (const e of entries) collect(cwd, relative(cwd, resolve(cwd, e)), items);
+  if (items.length > 0xffff) throw new Error(`too many files for a ZIP (${items.length})`);
+
+  const chunks = [];
+  const central = [];
+  let offset = 0;
+  for (const { name, full, stat } of items) {
+    const isDir = name.endsWith("/");
+    const data = isDir ? Buffer.alloc(0) : readFileSync(full);
+    const deflated = isDir ? data : deflateRawSync(data);
+    const stored = deflated.length >= data.length;
+    const body = stored ? data : deflated;
+    const crc = crc32(data);
+    const nameBuf = Buffer.from(name, "utf8");
+    const { time, date } = dosTime(stat.mtime);
+    if (offset + body.length > 0xffffffff) throw new Error("plugin ZIP would exceed 4 GB");
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4); // version needed
+    local.writeUInt16LE(0x0800, 6); // UTF-8 names
+    local.writeUInt16LE(stored ? 0 : 8, 8);
+    local.writeUInt16LE(time, 10);
+    local.writeUInt16LE(date, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(body.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(nameBuf.length, 26);
+    local.writeUInt16LE(0, 28);
+
+    const cdir = Buffer.alloc(46);
+    cdir.writeUInt32LE(0x02014b50, 0);
+    cdir.writeUInt16LE((3 << 8) | 20, 4); // made by Unix, so unzip applies the mode below
+    cdir.writeUInt16LE(20, 6);
+    cdir.writeUInt16LE(0x0800, 8);
+    cdir.writeUInt16LE(stored ? 0 : 8, 10);
+    cdir.writeUInt16LE(time, 12);
+    cdir.writeUInt16LE(date, 14);
+    cdir.writeUInt32LE(crc, 16);
+    cdir.writeUInt32LE(body.length, 20);
+    cdir.writeUInt32LE(data.length, 24);
+    cdir.writeUInt16LE(nameBuf.length, 28);
+    cdir.writeUInt32LE(((unixMode(full, stat) << 16) | (isDir ? 0x10 : 0)) >>> 0, 38);
+    cdir.writeUInt32LE(offset, 42);
+
+    chunks.push(local, nameBuf, body);
+    central.push(cdir, nameBuf);
+    offset += local.length + nameBuf.length + body.length;
+  }
+
+  const centralBuf = Buffer.concat(central);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(items.length, 8);
+  end.writeUInt16LE(items.length, 10);
+  end.writeUInt32LE(centralBuf.length, 12);
+  end.writeUInt32LE(offset, 16);
+  writeFileSync(zipPath, Buffer.concat([...chunks, centralBuf, end]));
+}