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

package/cli/src/new.mjs

@@ -1,5 +1,5 @@
 // muscat-pk new — scaffold a new plugin project from templates.
-import { execFileSync, execSync } from "node:child_process";
+import { execSync } from "node:child_process";
 import {
   cpSync,
   existsSync,
@@ -7,22 +7,79 @@ import {
   readFileSync,
   readdirSync,
   renameSync,
+  rmSync,
   statSync,
   writeFileSync,
 } from "node:fs";
-import { createInterface } from "node:readline/promises";
-import { basename, resolve } from "node:path";
-import { detectPythonCmd, hasBin, parseArgs, templatesDir, log, venvPython } from "./util.mjs";
+import { basename, dirname, resolve } from "node:path";
+import { color, ensureIdeVenv, hasBin, kitVersion, parseArgs, prompt, templatesDir, log } from "./util.mjs";
 
-const TYPES = ["python", "ros2"];
+// Like cpSync(src, dst, {recursive:true}) but reads from the embedded snapshot
+// when the templates dir doesn't exist on disk (compiled binary mode).
+// ponytail: import() is module-cached by the runtime — no manual cache needed.
+async function copyTemplate(srcDir, dst) {
+  if (existsSync(templatesDir)) { cpSync(srcDir, dst, { recursive: true }); return; }
+  const { TEMPLATES } = await import("./templates-embedded.mjs");
+  const prefix = srcDir.slice(templatesDir.length + 1).replace(/\\/g, "/") + "/";
+  for (const [key, b64] of Object.entries(TEMPLATES)) {
+    if (!key.startsWith(prefix)) continue;
+    const dest = resolve(dst, key.slice(prefix.length));
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, Buffer.from(b64, "base64"));
+  }
+}
+
+// `--type` values map to a runtime descriptor. ros2 has a python (rclpy) and a
+// C++ (rclcpp) flavor; we expose them as distinct type choices for clarity.
+export const TYPE_CHOICES = {
+  python:    { type: "python" },
+  cpp:       { type: "cpp" },
+  ros2:      { type: "ros2", rosClient: "rclpy" },
+  "ros2-cpp":{ type: "ros2", rosClient: "rclcpp" },
+};
+const TYPES = Object.keys(TYPE_CHOICES);
 const PMS = ["npm", "yarn", "pnpm", "bun"];
 
-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;
+function printNewSuccess({ targetName, type, pm }) {
+  const mark = [
+    "             /\\",
+    "            /  \\_",
+    "       ____||__",
+    "      /  \\__/  \\",
+    "   __/\\__/  \\__/\\",
+    "  /  \\__/\\__/\\__/\\",
+    "  \\__/  \\__/  \\__/",
+    "     \\__/  \\__/",
+    "        \\__/",
+  ].map((line) => color.green(line)).join("\n");
+
+  log.info("");
+  log.info(mark);
+  log.info(color.bold(color.green("Welcome to Muscat Plugin Kit!")));
+  log.info(color.dim("A fresh plugin workspace is ready."));
+  log.info("");
+  log.ok(`created ${color.bold(targetName)} ${color.dim(`(type: ${type}, pm: ${pm})`)}`);
+  log.info("");
+  log.info(color.bold("Next steps"));
+  log.info(`  ${color.cyan("cd")} ${targetName}`);
+  log.info(`  ${color.cyan("muscat-pk dev")}      ${color.dim("# preview in mini-Muscat + back end")}`);
+  log.info(`  ${color.cyan("muscat-pk build")}    ${color.dim("# build + distributable ZIP")}`);
+  log.info("");
+}
+
+// Build the manifest runtime object for a given type choice + plugin slug.
+export function runtimeForChoice(choice, slug) {
+  switch (choice.type) {
+    case "cpp":
+      // entry = built executable name (matches add_executable in cpp/CMakeLists.txt)
+      return { type: "cpp", entry: slug };
+    case "ros2":
+      // package = colcon package name; launch = node executable run on the robot
+      return { type: "ros2", rosClient: choice.rosClient, package: slug, launch: `${slug}_node` };
+    case "python":
+    default:
+      return { type: "python", entry: "main.py" };
+  }
 }
 
 export function applyTokens(dir, tokens) {
@@ -74,16 +131,25 @@ function renameSlugPaths(dir, slug) {
 // Copy the ros2_ws/ overlay into a plugin and substitute the package slug into
 // every path segment. The dev Dockerfile is NOT scaffolded here — it lives in
 // the kit (cli/docker/) so authors can't edit it. Caller runs applyTokens after.
-export function overlayRos2(target, slug) {
-  cpSync(resolve(templatesDir, "ros2"), target, { recursive: true });
+//   rclpy  → templates/ros2      (ament_python)
+//   rclcpp → templates/ros2-cpp  (ament_cmake)
+export async function overlayRos2(target, slug, rosClient = "rclpy") {
+  const tmpl = rosClient === "rclcpp" ? "ros2-cpp" : "ros2";
+  await copyTemplate(resolve(templatesDir, tmpl), target);
   renameSlugPaths(resolve(target, "ros2_ws"), slug);
 }
 
+// Copy the cpp/ overlay (CMake project) into a plugin. Caller runs applyTokens after.
+export async function overlayCpp(target) {
+  await copyTemplate(resolve(templatesDir, "cpp"), target);
+}
+
 export async function runNew(args) {
   const opts = parseArgs(args, { booleans: ["yes", "no-install", "help"] });
   if (opts.help) {
     console.log(
-      "muscat-pk new [dir] [--type python|ros2] [--pm npm|yarn|pnpm|bun]\n" +
+      "muscat-pk new [dir] [--type python|cpp|ros2|ros2-cpp] [--pm npm|yarn|pnpm|bun]\n" +
+        "                 [--author <name>] [--email <email>] [--description <text>]\n" +
         "                 [--yes] [--no-install]",
     );
     return;
@@ -91,25 +157,53 @@ export async function runNew(args) {
 
   const dirArg = opts._[0];
   const targetName =
-    dirArg || (await prompt("Plugin directory name: ", "my-plugin"));
+    dirArg || (await prompt(color.cyan("Plugin directory name: "), "my-plugin"));
   const target = resolve(process.cwd(), targetName);
   if (existsSync(target) && readdirSync(target).length > 0) {
     throw new Error(`directory not empty: ${target}`);
   }
 
+  let authorArg = opts.author;
+  let emailArg = opts.email;
+  let descriptionArg = opts.description;
+
+  if (!opts.yes) {
+    if (!authorArg) authorArg = await prompt(color.cyan("Author name: "), "");
+    if (!emailArg) emailArg = await prompt(`${color.cyan("Email")} ${color.yellow("(required)")}: `, "");
+    if (!descriptionArg) descriptionArg = await prompt(color.cyan("Description (English): "), "");
+  }
+
   let type = opts.type;
   if (!type && !opts.yes) {
-    console.log("\n플러그인 타입을 선택하세요:");
-    console.log("  1) Python");
-    console.log("  2) ROS2(rclpy)");
-    const choice = await prompt("\n선택 [1/2, default: 1]: ", "1");
-    type = choice === "2" ? "ros2" : "python";
+    console.log(`\n${color.bold(color.cyan("Select the plugin type:"))}`);
+    console.log(`  ${color.green("1)") } ${color.bold("Python")}`);
+    console.log(`  ${color.green("2)") } ${color.bold("C++")}`);
+    console.log(`  ${color.green("3)") } ${color.bold("ROS2")} ${color.dim("(rclpy / Python)")}`);
+    console.log(`  ${color.green("4)") } ${color.bold("ROS2")} ${color.dim("(rclcpp / C++)")}`);
+    const choice = await prompt(`\n${color.cyan("선택")} ${color.dim("[1/2/3/4, default: 1]")}: `, "1");
+    type = { "2": "cpp", "3": "ros2", "4": "ros2-cpp" }[choice] ?? "python";
   }
   type = TYPES.includes(type) ? type : "python";
+  const runtimeChoice = TYPE_CHOICES[type];
+
+  // Auto-detect yarn workspace: if .yarnrc.yml exists anywhere up the tree, default to yarn.
+  function isInsideYarnWorkspace(dir) {
+    let cur = dir;
+    while (true) {
+      if (existsSync(resolve(cur, ".yarnrc.yml"))) return true;
+      const parent = resolve(cur, "..");
+      if (parent === cur) return false;
+      cur = parent;
+    }
+  }
 
   let pm = opts.pm;
   if (!pm && !opts.yes) {
-    pm = await prompt(`Package manager (${PMS.join("/")}) [npm]: `, "npm");
+    const defaultPm = isInsideYarnWorkspace(process.cwd()) ? "yarn" : "npm";
+    pm = await prompt(
+      `${color.cyan("Front-end package manager")} ${color.dim(`(${PMS.join("/")})`)} ${color.dim(`[${defaultPm}]`)}: `,
+      defaultPm,
+    );
   }
   pm = PMS.includes(pm) ? pm : "npm";
 
@@ -117,11 +211,18 @@ export async function runNew(args) {
 
   mkdirSync(target, { recursive: true });
 
-  // common(UI + main.py + requirements.txt + manifest/config)은 항상 포함.
-  // ros2면 ros2_ws/ 오버레이만 추가로 얹는다. python은 ros2_ws/가 없을 뿐 구조는 동일.
+  // common(UI + manifest/config)은 항상 포함. 백엔드 오버레이는 타입별로 얹는다.
+  //   python   → common의 py/ 사용
+  //   cpp      → cpp/ 오버레이, py/·requirements.txt 제거
+  //   ros2(*)  → ros2_ws/ 오버레이 (rclpy=ament_python, rclcpp=ament_cmake)
   log.step(`scaffolding ${type} plugin → ${target}`);
-  cpSync(resolve(templatesDir, "common"), target, { recursive: true });
-  if (type === "ros2") overlayRos2(target, slug);
+  await copyTemplate(resolve(templatesDir, "common"), target);
+  if (runtimeChoice.type === "ros2") await overlayRos2(target, slug, runtimeChoice.rosClient);
+  if (runtimeChoice.type === "cpp") {
+    await overlayCpp(target);
+    rmSync(resolve(target, "py"), { recursive: true, force: true });
+    rmSync(resolve(target, "requirements.txt"), { force: true });
+  }
 
   applyTokens(target, {
     __PLUGIN_ID__: pluginId,
@@ -129,14 +230,24 @@ export async function runNew(args) {
     __PLUGIN_DIR__: dir,
     __PLUGIN_SLUG__: slug,
     __PLUGIN_CLASS__: pluginClass,
+    __PLUGIN_AUTHOR__: authorArg || "",
+    __PLUGIN_EMAIL__: emailArg || "",
     __PM__: pm,
-    __RUNTIME_TYPE__: type,
+    __RUNTIME_TYPE__: runtimeChoice.type,
+    __RB_VERSION__: kitVersion(),
   });
 
+  // Write the correct runtime block into manifest.json (per-type fields).
+  const manifestPath = resolve(target, "manifest.json");
+  const manifestJson = JSON.parse(readFileSync(manifestPath, "utf8"));
+  manifestJson.runtime = runtimeForChoice(runtimeChoice, slug);
+  if (descriptionArg) manifestJson.description = { en: descriptionArg };
+  writeFileSync(manifestPath, JSON.stringify(manifestJson, null, 2) + "\n");
+
   // gitignore (templates can't ship a literal .gitignore via npm reliably)
   writeFileSync(
     resolve(target, ".gitignore"),
-    ["node_modules", "dist", ".venv", "*.zip", "ros2_ws/install", ""].join("\n"),
+    ["node_modules", "dist", ".muscat-dev", ".venv", "*.zip", "ros2_ws/install", "cpp/build", ""].join("\n"),
   );
 
   if (!opts["no-install"]) {
@@ -146,61 +257,53 @@ export async function runNew(args) {
     } catch {
       log.warn(`'${pm} install' failed; run it manually in ${targetName}`);
     }
-  }
-
-  let noPython = false;
-  let venvFailed = false;
 
-  if (!opts["no-install"]) {
-    // Python venv (robot targets 3.12) — cross-platform.
-    // uv is preferred: handles uv-managed Pythons that break standard ensurepip.
-    try {
-      const venv = resolve(target, ".venv");
-      log.step("creating .venv + installing requirements…");
-      if (hasBin("uv")) {
-        execFileSync("uv", ["venv", venv, "--python", "3.12", "--seed"], { cwd: target, stdio: "inherit" });
-      } else if (hasBin("conda")) {
-        execFileSync("conda", ["create", "-p", venv, "python=3.12", "-y", "--quiet"], { cwd: target, stdio: "inherit" });
-      } else if (hasBin("python3.12") || hasBin("python3") || hasBin("python")) {
-        const { cmd, is312 } = detectPythonCmd();
-        if (!is312) log.warn("python3.12 not found; venv uses fallback python (robot targets 3.12).");
-        execFileSync(cmd[0], [...cmd.slice(1), "-m", "venv", venv], { cwd: target, stdio: "inherit" });
+    // Local .venv is for your editor/linter (pylint, pyright, ...) only — the
+    // backend actually RUNS in Docker (see README), this never affects that.
+    // rclcpp is C++, so no venv applies there.
+    const needsIdeVenv =
+      runtimeChoice.type === "python" ||
+      (runtimeChoice.type === "ros2" && runtimeChoice.rosClient === "rclpy");
+    if (needsIdeVenv) {
+      log.step("creating .venv for your editor (pylint/pyright)…");
+      if (ensureIdeVenv(target)) {
+        log.ok(".venv ready — point your editor's Python interpreter there.");
       } else {
-        noPython = true;
-      }
-      if (!noPython) {
-        const py = venvPython(venv);
-        if (existsSync(resolve(target, "requirements.txt"))) {
-          execFileSync(py, ["-m", "pip", "install", "-q", "-r", "requirements.txt"], { cwd: target, stdio: "inherit" });
-        }
+        log.warn("Could not create .venv (no local Python/uv?) — skipping, Docker dev still works.");
       }
+    }
+  }
+
+  // git init (best-effort). Always runs, even nested inside another repo —
+  // delete target/.git if you don't want it.
+  if (hasBin("git")) {
+    try {
+      execSync("git init", { cwd: target, stdio: "ignore" });
+      execSync("git add -A", { cwd: target, stdio: "ignore" });
+      execSync('git commit -m "Initial commit from muscat-pk new" --no-verify', { cwd: target, stdio: "ignore" });
     } catch {
-      venvFailed = true;
+      log.warn("git init failed — run it manually if you want version control here.");
     }
-  } else {
-    noPython = !hasBin("uv") && !hasBin("conda") && !hasBin("python3.12") && !hasBin("python3") && !hasBin("python");
   }
 
-  log.ok(`created ${targetName} (type: ${type}, pm: ${pm})`);
-  log.info(`\n  cd ${targetName}`);
-  log.info(`  muscat-pk dev      # preview in mini-Muscat + back end`);
-  log.info(`  muscat-pk pack     # build a distributable ZIP\n`);
+  // The back end (python / cpp / ros2) runs in a Docker container that matches
+  // the robot — no local Python/toolchain setup needed. Only `none` skips it.
+  const needsDocker = runtimeChoice.type !== "none";
+  const noDocker = needsDocker && !hasBin("docker");
+
+  printNewSuccess({ targetName, type, pm });
 
   // ── post-scaffold environment warnings ───────────────────────────────────
   const noNode = !hasBin("node");
-  if (noNode || noPython || venvFailed) {
+  if (noNode || noDocker) {
     log.info("");
     if (noNode) {
       log.warn("Node.js not found. Install Node.js 20+ to run JS deps and dev:ui.");
       log.warn("  https://nodejs.org");
     }
-    if (noPython) {
-      log.warn("Python not found. Install Python 3.12 to run the backend.");
-      log.warn("  https://www.python.org/downloads/  (or: brew install python@3.12 / uv / conda)");
-      log.warn(`  Then: cd ${targetName} && python3.12 -m venv .venv && pip install -r requirements.txt`);
-    } else if (venvFailed) {
-      log.warn("venv setup failed. Create it manually:");
-      log.warn(`  cd ${targetName} && python3.12 -m venv .venv && pip install -r requirements.txt`);
+    if (noDocker) {
+      log.warn("Docker not found. The plugin back end runs in a container (matches the robot env).");
+      log.warn("  https://docs.docker.com/get-docker/");
     }
     log.info("");
   }

package/cli/src/pluginDevServer.mjs

@@ -0,0 +1,112 @@
+
+import { createRequire } from "node:module";
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const pluginRoot = resolve(process.argv[2]);
+const port = Number(process.argv[3] || "4181");
+const readyFile = process.argv[4] ? resolve(process.argv[4]) : "";
+
+
+process.chdir(pluginRoot);
+
+const require = createRequire(resolve(pluginRoot, "package.json"));
+
+const viteMod = await import(pathToFileURL(require.resolve("vite")));
+const createServer = viteMod.createServer ?? viteMod.default?.createServer;
+
+const BOOTSTRAP_PREFIX = "\0rb-bootstrap:";
+const PREAMBLE_ID = "\0rb-preamble";
+const bootstrapPlugin = {
+  name: "rb-plugin-bootstrap",
+  resolveId(id) {
+    if (id.startsWith("rb-bootstrap:")) return "\0" + id;
+    if (id === "rb-preamble") return PREAMBLE_ID;
+  },
+  load(id) {
+    if (id === PREAMBLE_ID) {
+      return `
+import RefreshRuntime from "/@react-refresh";
+RefreshRuntime.injectIntoGlobalHook(window);
+window.$RefreshReg$ = () => {};
+window.$RefreshSig$ = () => (type) => type;
+window.__vite_plugin_react_preamble_installed__ = true;
+`;
+    }
+    if (!id.startsWith(BOOTSTRAP_PREFIX)) return;
+    const ui = id.slice(BOOTSTRAP_PREFIX.length) || "content";
+    const entry = JSON.stringify(`muscat-ui-entry:${ui}`);
+    return `
+import "rb-preamble";
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { RbContext } from "@rainbow-robotics/plugin-ui/sdk";
+import { setHostServices } from "@rainbow-robotics/plugin-ui/host-ui";
+import { RbWs, createLazyRbSdk } from "@rainbow-robotics/plugin-ui/ws";
+import App from ${entry};
+
+// HMR passes the new module to the accept callback but doesn't rebind the
+// static \`App\` import, so we track the latest at module scope. Without this,
+// navigating away and back (a fresh mount() on this cached module) renders the
+// stale App from first import. \`activeRender\` points at the mounted root so
+// live edits re-render in place.
+let latestApp = App;
+let activeRender = null;
+if (import.meta.hot) {
+  import.meta.hot.accept(${entry}, (m) => {
+    if (!m || !m.default) return;
+    latestApp = m.default;
+    activeRender?.(latestApp);
+  });
+}
+
+export function mount(container, { socketUrl, pluginId, hostServices, data, onSave }) {
+  container.setAttribute("data-muscat-plugin-root", "");
+  container.setAttribute("data-muscat-plugin-id", pluginId);
+  setHostServices(hostServices);
+  // Lazy connect: don't block the first render on the WebSocket handshake
+  // (there may be no backend at all in dev, e.g. no robot reachable) — each rb
+  // method awaits this promise internally instead.
+  const wsPromise = RbWs.connect(socketUrl, pluginId);
+  const rb = createLazyRbSdk(wsPromise, hostServices, { data, onSave });
+  const root = createRoot(container);
+  let mounted = true;
+  const render = (Component) => {
+    if (!mounted) return;
+    root.render(createElement(RbContext.Provider, { value: rb }, createElement(Component)));
+  };
+  const boundRender = (Component) => queueMicrotask(() => render(Component));
+  activeRender = boundRender;
+  render(latestApp);
+  return () => {
+    mounted = false;
+    // Don't clobber a newer mount's render (host defers unmount a microtask).
+    if (activeRender === boundRender) activeRender = null;
+    root.unmount();
+  };
+}
+`;
+  },
+};
+
+const server = await createServer({
+  root: pluginRoot,
+  configFile: resolve(pluginRoot, "vite.config.ts"),
+  mode: "development",
+  plugins: [bootstrapPlugin],
+  server: {
+    port,
+    strictPort: false,
+    cors: true,
+    hmr: { host: "localhost", protocol: "ws" },
+  },
+});
+
+await server.listen();
+const address = server.httpServer?.address();
+const actualPort = typeof address === "object" && address ? address.port : port;
+if (readyFile) {
+  writeFileSync(readyFile, JSON.stringify({ port: actualPort }), "utf8");
+}
+console.log(`[plugin-dev] vite dev server → http://localhost:${actualPort}`);

package/cli/src/ports.mjs

@@ -0,0 +1,160 @@
+// Port contract helpers for plugin back ends.
+import { spawnSync } from "node:child_process";
+
+export const PLUGIN_PORT_MIN = 28600;
+export const PLUGIN_PORT_MAX = 28999;
+export const INTERNAL_DEV_PORTS = new Set([10000]);
+export const RESERVED_BACKEND_PORTS = new Map([
+  [502, "Modbus TCP"],
+  [4840, "OPC-UA"],
+  [10000, "muscat-pk Socket.IO bridge"],
+  [2222, "EtherNet/IP Implicit"],
+  [30004, "RTDE"],
+  [34964, "ProfiNET"],
+  [44818, "EtherNet/IP Explicit"],
+  [50051, "gRPC"],
+]);
+export const RESERVED_BACKEND_PORT_RANGES = [
+  { from: 5170, to: 5179, name: "UI 517x servers" },
+  { from: 8000, to: 8999, name: "Muscat/internal 8000 range" },
+  { from: 50000, to: 50005, name: "robot TCP/UDP ASCII and REST interfaces" },
+];
+
+function reservedPortReason(port) {
+  if (RESERVED_BACKEND_PORTS.has(port)) return RESERVED_BACKEND_PORTS.get(port);
+  const range = RESERVED_BACKEND_PORT_RANGES.find((item) => port >= item.from && port <= item.to);
+  if (!range) return null;
+  return `${range.name} (${range.from}-${range.to})`;
+}
+
+function isPluginManagedPort(port) {
+  return reservedPortReason(port) || (port >= PLUGIN_PORT_MIN && port <= PLUGIN_PORT_MAX);
+}
+
+function isInt(value) {
+  return Number.isInteger(value);
+}
+
+function validatePort(port, field, errors) {
+  if (!isInt(port)) {
+    errors.push(`${field}: must be a port number`);
+    return;
+  }
+  if (port < 1 || port > 65535) {
+    errors.push(`${field}: port must be between 1 and 65535`);
+    return;
+  }
+  const reserved = reservedPortReason(port);
+  if (reserved) {
+    errors.push(`${field}: ${port} is reserved for ${reserved}`);
+    return;
+  }
+  if (port < PLUGIN_PORT_MIN || port > PLUGIN_PORT_MAX) {
+    errors.push(
+      `${field}: external plugin backend ports must be within ${PLUGIN_PORT_MIN}-${PLUGIN_PORT_MAX}`,
+    );
+  }
+}
+
+export function normalizePorts(ports, errors = []) {
+  if (ports === undefined || ports === null) return [];
+  if (!Array.isArray(ports)) {
+    errors.push(`"ports" must be an array`);
+    return [];
+  }
+  if (ports.length === 0) {
+    errors.push(`"ports" must not be empty when provided`);
+    return [];
+  }
+
+  const normalized = [];
+  const seen = new Set();
+  ports.forEach((port, i) => {
+    validatePort(port, `ports[${i}]`, errors);
+    if (!isInt(port)) return;
+    if (seen.has(port)) {
+      errors.push(`"ports" entries must be unique (duplicate: ${port})`);
+      return;
+    }
+    seen.add(port);
+    normalized.push(port);
+  });
+
+  return normalized;
+}
+
+export function validatePorts(ports, errors) {
+  normalizePorts(ports, errors);
+}
+
+export function manifestPortRanges(manifest) {
+  return normalizePorts(manifest?.ports, []);
+}
+
+export function formatPortRange(range) {
+  return String(range);
+}
+
+export function formatPortRanges(ranges) {
+  return ranges.map(formatPortRange).join(", ");
+}
+
+export function portInRanges(port, ranges) {
+  return ranges.includes(port);
+}
+
+export function portEnvFlags(ranges) {
+  if (ranges.length === 0) return [];
+  return ["-e", `RB_PLUGIN_PORTS=${ranges.map(formatPortRange).join(",")}`];
+}
+
+function listeningTcpPorts(container) {
+  const script = `
+for f in /proc/net/tcp /proc/net/tcp6; do
+  [ -r "$f" ] || continue
+  tail -n +2 "$f" | while read -r sl local_address rem_address st rest; do
+    [ "$st" = "0A" ] || continue
+    hex_port="\${local_address##*:}"
+    printf "%d\\n" "0x$hex_port"
+  done
+done | sort -n -u
+`;
+  const r = spawnSync("docker", ["exec", container, "bash", "-lc", script], {
+    encoding: "utf8",
+  });
+  if (r.status !== 0) return [];
+  return String(r.stdout || "")
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((v) => Number(v))
+    .filter((v) => Number.isInteger(v));
+}
+
+export function startPortContractMonitor({ container, ranges, log, intervalMs = 1000 }) {
+  const declared = ranges ?? [];
+  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));
+    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}. ` +
+      `Declared: ${declaredText}`,
+    );
+    spawnSync("docker", ["rm", "-f", container], { stdio: "ignore" });
+    process.exit(1);
+  }, intervalMs);
+  timer.unref?.();
+
+  return () => {
+    clearInterval(timer);
+    return reported;
+  };
+}