@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.5 → 0.1.2-dev.50

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,52 @@ import {
   readFileSync,
   readdirSync,
   renameSync,
+  rmSync,
   statSync,
   writeFileSync,
 } from "node:fs";
-import { createInterface } from "node:readline/promises";
-import { basename, resolve } from "node:path";
-import { detectPythonCmd, parseArgs, templatesDir, log, venvPython } from "./util.mjs";
+import { basename, dirname, resolve } from "node:path";
+import { 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;
+// 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) {
@@ -51,6 +81,7 @@ export function deriveNames(target) {
   const slug = base.toLowerCase().replace(/[^a-z0-9]+/g, "_");
   const pluginName = base.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
   return {
+    dir: base,
     slug,
     pluginName,
     pluginClass: pluginName.replace(/\s+/g, ""),
@@ -73,16 +104,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;
@@ -96,45 +136,88 @@ export async function runNew(args) {
     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("Author name: ", "");
+    if (!emailArg) emailArg = await prompt("Email (required): ", "");
+    if (!descriptionArg) descriptionArg = await prompt("Description (English): ", "");
+  }
+
   let type = opts.type;
   if (!type && !opts.yes) {
-    console.log("\n플러그인 타입을 선택하세요:");
+    console.log("\nSelect the plugin type:");
     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("  2) C++");
+    console.log("  3) ROS2 (rclpy / Python)");
+    console.log("  4) ROS2 (rclcpp / C++)");
+    const choice = await prompt("\n선택 [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(`Front-end package manager (${PMS.join("/")}) [${defaultPm}]: `, defaultPm);
   }
   pm = PMS.includes(pm) ? pm : "npm";
 
-  const { slug, pluginName, pluginClass, pluginId } = deriveNames(target);
+  const { dir, slug, pluginName, pluginClass, pluginId } = deriveNames(target);
 
   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,
     __PLUGIN_NAME__: pluginName,
+    __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"]) {
@@ -145,27 +228,44 @@ export async function runNew(args) {
       log.warn(`'${pm} install' failed; run it manually in ${targetName}`);
     }
 
-    // Python venv (robot targets 3.12) — cross-platform.
-    try {
-      const { cmd, is312 } = detectPythonCmd();
-      if (!is312) log.warn("python3.12 not found; venv uses fallback python (robot targets 3.12).");
-      log.step("creating .venv + installing requirements…");
-      const venv = resolve(target, ".venv");
-      execFileSync(cmd[0], [...cmd.slice(1), "-m", "venv", venv], { cwd: target, stdio: "inherit" });
-      const py = venvPython(venv);
-      if (existsSync(resolve(target, "requirements.txt"))) {
-        execFileSync(py, ["-m", "pip", "install", "-q", "-r", "requirements.txt"], {
-          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 {
+        log.warn("Could not create .venv (no local Python/uv?) — skipping, Docker dev still works.");
       }
-    } catch {
-      log.warn("venv setup failed; create it manually: python3.12 -m venv .venv");
     }
   }
 
+  // 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");
+
   log.ok(`created ${targetName} (type: ${type}, pm: ${pm})`);
   log.info(`\n  cd ${targetName}`);
-  log.info(`  ${pm} run dev      # preview in mini-Muscat + back end`);
-  log.info(`  ${pm} run pack     # build a distributable ZIP\n`);
+  log.info(`  muscat-pk dev      # preview in mini-Muscat + back end`);
+  log.info(`  muscat-pk build    # build + distributable ZIP\n`);
+
+  // ── post-scaffold environment warnings ───────────────────────────────────
+  const noNode = !hasBin("node");
+  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 (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;
+  };
+}

package/cli/src/python.mjs

@@ -0,0 +1,109 @@
+// Shared Python Docker helpers (Ubuntu 24.04 + Python 3.12 — matches the robot).
+// Used by dev:back (hot-reload) and build (lock + wheel vendor).
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+
+export const PYTHON_DEV_IMAGE = "muscat-pk-python-dev";
+
+export function assertDockerReady() {
+  if (!hasBin("docker")) {
+    throw new Error("Docker not found. The Python backend runs in a container (Ubuntu 24.04 + Python 3.12).");
+  }
+}
+
+/** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
+export async function ensureImage(image = PYTHON_DEV_IMAGE, { platform = null } = {}) {
+  const dockerfile = await resolveDockerfile("Dockerfile.python");
+  log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
+  const platformFlags = platform ? ["--platform", platform] : [];
+  const r = spawnSync(
+    "docker",
+    ["build", ...platformFlags, "-t", image, "-f", dockerfile, dirname(dockerfile)],
+    { stdio: "inherit" },
+  );
+  if (r.status !== 0) throw new Error("docker build failed.");
+  pruneMuskatImages();
+}
+
+// pip --platform does NOT auto-expand manylinux tags (unlike sys_tags()) — exact match only.
+// Specifying all common glibc milestones ensures packages built for any Ubuntu era are found.
+const PIP_PLATFORM = {
+  amd64: [
+    "manylinux_2_5_x86_64",
+    "manylinux_2_17_x86_64",
+    "manylinux_2_27_x86_64",
+    "manylinux_2_28_x86_64",
+    "manylinux_2_34_x86_64",
+    "manylinux_2_39_x86_64",
+    "linux_x86_64",
+  ],
+  arm64: [
+    "manylinux_2_17_aarch64",
+    "manylinux_2_27_aarch64",
+    "manylinux_2_28_aarch64",
+    "manylinux_2_34_aarch64",
+    "manylinux_2_39_aarch64",
+    "linux_aarch64",
+  ],
+};
+
+export async function lockAndVendor(pluginRoot, archs = ["amd64", "arm64"]) {
+  // ponytail: pip --platform used intentionally (not QEMU) — downloads wheels without running target arch code.
+  const reqTxt = resolve(pluginRoot, "requirements.txt");
+  if (!existsSync(reqTxt)) {
+    log.warn("requirements.txt not found — lock/vendor skipped");
+    return;
+  }
+
+  await ensureImage();
+
+  log.step("generating lock (uv pip compile)…");
+  const lockResult = spawnSync(
+    "docker",
+    [
+      "run", "--rm",
+      "-v", `${pluginRoot}:/plugin`,
+      PYTHON_DEV_IMAGE,
+      "bash", "-c",
+      "set -e && cd /plugin && mkdir -p dist && uv pip compile requirements.txt --python-version 3.12 -o dist/requirements.lock",
+    ],
+    { stdio: "inherit" },
+  );
+  if (lockResult.status !== 0) throw new Error("lock generation failed (uv pip compile)");
+  log.ok("dist/requirements.lock ready");
+
+  const failed = [];
+  for (const arch of archs) {
+    const pipPlatforms = PIP_PLATFORM[arch];
+    if (!pipPlatforms) { log.warn(`unknown arch '${arch}' — skipped`); continue; }
+    log.step(`vendoring wheels for ${arch}…`);
+    const r = spawnSync(
+      "docker",
+      [
+        "run", "--rm",
+        "-e", "PIP_ROOT_USER_ACTION=ignore",
+        "-v", `${pluginRoot}:/plugin`,
+        "-w", "/plugin",
+        PYTHON_DEV_IMAGE,
+        "bash", "-c",
+        "mkdir -p dist/wheels && pip3 download -r dist/requirements.lock --no-deps --only-binary=:all: -d dist/wheels -q " +
+          "--python-version 312 --implementation cp --abi cp312 " +
+          pipPlatforms.map((p) => `--platform ${p}`).join(" "),
+      ],
+      { stdio: "inherit" },
+    );
+    if (r.status !== 0) {
+      log.warn(`wheel vendoring failed for ${arch}`);
+      failed.push(arch);
+    } else {
+      log.ok(`dist/wheels/ ready (${arch})`);
+    }
+  }
+
+  if (failed.length === archs.length) {
+    throw new Error(`wheel vendoring failed for all archs: ${failed.join(", ")}`);
+  }
+  return failed;
+}