@50arms/platform-mcp 0.0.0-stage → 0.1.436

package/dist/machine-toolkit.js

@@ -0,0 +1,460 @@
+// src/machine-toolkit/cli.ts
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+// src/machine-toolkit/contract.ts
+var CONTRACT_VERSION = 2;
+var EXIT = {
+  /** The command ran and everything it reports was read or done. */
+  ok: 0,
+  /** The command could not run, or part of its work failed. */
+  failed: 1,
+  /** `health` / `label-check` ran and answered, but at least one metric could not be read (it is `null` with a reason), or a label problem exists. */
+  degraded: 2,
+  /** `sweep` / `maintain` refused to start because a compaction window is open (the only refusal today). */
+  refused: 3
+};
+var REQUIRED_METRICS = ["docker_data_disk_bytes", "unowned_docker_resource_count", "orphan_process_count"];
+var HEALTH_ITEM_LISTS = ["unowned_docker_resources", "orphan_processes"];
+var ContractViolation = class extends Error {
+  constructor(command, path, what) {
+    super(`${command} output does not match machine-toolkit contract v${CONTRACT_VERSION}: ${path} ${what}`);
+    this.name = "ContractViolation";
+  }
+};
+var isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+var join = (path, key) => path === "" ? key : `${path}.${key}`;
+function objectAt(v, path, fail2) {
+  if (!isObject(v)) return fail2(path, "must be an object");
+  return v;
+}
+function exactKeys(o, path, keys, fail2) {
+  for (const k of keys) if (!(k in o)) fail2(join(path, k), "is required");
+  for (const k of Object.keys(o)) if (!keys.includes(k)) fail2(join(path, k), "is not part of the contract");
+}
+function stringAt(o, key, path, fail2) {
+  const v = o[key];
+  if (typeof v !== "string" || v === "") return fail2(join(path, key), "must be a non-empty string");
+  return v;
+}
+function listAt(v, path, fail2) {
+  if (!Array.isArray(v)) return fail2(path, "must be a list");
+  return v;
+}
+function checkItem(v, path, extra, fail2) {
+  const o = objectAt(v, path, fail2);
+  exactKeys(o, path, ["id", "detail", ...extra], fail2);
+  stringAt(o, "id", path, fail2);
+  if (typeof o.detail !== "string") fail2(join(path, "detail"), "must be a string");
+  for (const k of extra) stringAt(o, k, path, fail2);
+}
+function checkItems(v, path, extra, fail2) {
+  listAt(v, path, fail2).forEach((item, i) => checkItem(item, `${path}[${i}]`, extra, fail2));
+}
+function checkMetric(v, path, fail2) {
+  const o = objectAt(v, path, fail2);
+  exactKeys(o, path, ["value", "reason", "source", "age_seconds"], fail2);
+  if (o.value === null) {
+    if (typeof o.reason !== "string" || o.reason === "") fail2(`${path}.reason`, "must say why the value is null");
+  } else {
+    if (typeof o.value !== "number" || !Number.isFinite(o.value) || o.value < 0) fail2(`${path}.value`, "must be null or a finite number of at least 0");
+    if (o.reason !== null) fail2(`${path}.reason`, "must be null when the value was read");
+  }
+  if (o.source !== "fresh" && o.source !== "cached") fail2(`${path}.source`, "must be 'fresh' or 'cached'");
+  if (typeof o.age_seconds !== "number" || !Number.isFinite(o.age_seconds) || o.age_seconds < 0) fail2(`${path}.age_seconds`, "must be a number of at least 0");
+  if (o.source === "fresh" && o.age_seconds !== 0) fail2(`${path}.age_seconds`, "must be 0 for a fresh reading");
+}
+function checkEnvelope(o, fail2) {
+  if (o.contract_version !== CONTRACT_VERSION) fail2("contract_version", `must be ${CONTRACT_VERSION}`);
+  stringAt(o, "toolkit_version", "", fail2);
+  stringAt(o, "profile", "", fail2);
+  const at = stringAt(o, "measured_at", "", fail2);
+  if (Number.isNaN(new Date(at).getTime())) fail2("measured_at", "must be an ISO time");
+}
+var ENVELOPE_KEYS = ["contract_version", "toolkit_version", "profile", "measured_at"];
+var VALIDATORS = {
+  health(o, fail2) {
+    exactKeys(o, "", [...ENVELOPE_KEYS, "metrics", "items"], fail2);
+    checkEnvelope(o, fail2);
+    const metrics = objectAt(o.metrics, "metrics", fail2);
+    for (const name of REQUIRED_METRICS) if (!(name in metrics)) fail2(`metrics.${name}`, "is required");
+    for (const [name, metric] of Object.entries(metrics)) checkMetric(metric, `metrics.${name}`, fail2);
+    const items = objectAt(o.items, "items", fail2);
+    exactKeys(items, "items", HEALTH_ITEM_LISTS, fail2);
+    for (const list of HEALTH_ITEM_LISTS) checkItems(items[list], `items.${list}`, [], fail2);
+  },
+  sweep(o, fail2) {
+    exactKeys(o, "", [...ENVELOPE_KEYS, "dry_run", "kinds"], fail2);
+    checkEnvelope(o, fail2);
+    if (typeof o.dry_run !== "boolean") fail2("dry_run", "must be true or false");
+    listAt(o.kinds, "kinds", fail2).forEach((k, i) => {
+      const path = `kinds[${i}]`;
+      const kind = objectAt(k, path, fail2);
+      exactKeys(kind, path, ["kind", "removed", "kept", "failed", "flagged"], fail2);
+      stringAt(kind, "kind", path, fail2);
+      checkItems(kind.removed, `${path}.removed`, [], fail2);
+      checkItems(kind.kept, `${path}.kept`, ["reason"], fail2);
+      checkItems(kind.failed, `${path}.failed`, ["error"], fail2);
+      checkItems(kind.flagged, `${path}.flagged`, ["reason"], fail2);
+    });
+  },
+  maintain(o, fail2) {
+    exactKeys(o, "", [...ENVELOPE_KEYS, "steps"], fail2);
+    checkEnvelope(o, fail2);
+    listAt(o.steps, "steps", fail2).forEach((s, i) => {
+      const path = `steps[${i}]`;
+      const step = objectAt(s, path, fail2);
+      exactKeys(step, path, ["name", "status", "detail"], fail2);
+      stringAt(step, "name", path, fail2);
+      if (step.status !== "done" && step.status !== "skipped" && step.status !== "failed") fail2(`${path}.status`, "must be 'done', 'skipped' or 'failed'");
+      if (typeof step.detail !== "string") fail2(join(path, "detail"), "must be a string");
+    });
+  },
+  "label-check"(o, fail2) {
+    exactKeys(o, "", [...ENVELOPE_KEYS, "unowned", "malformed"], fail2);
+    checkEnvelope(o, fail2);
+    checkItems(o.unowned, "unowned", ["reason"], fail2);
+    checkItems(o.malformed, "malformed", ["reason"], fail2);
+  }
+};
+function assertContract(command, report) {
+  const fail2 = (path, what) => {
+    throw new ContractViolation(command, path === "" ? "(document)" : path, what);
+  };
+  VALIDATORS[command](objectAt(report, "", fail2), fail2);
+}
+var metricRead = (value, source = "fresh", ageSeconds = 0) => ({ value, reason: null, source, age_seconds: ageSeconds });
+var metricUnread = (reason) => ({ value: null, reason, source: "fresh", age_seconds: 0 });
+function healthExitCode(report) {
+  return Object.values(report.metrics).some((m) => m.value === null) ? EXIT.degraded : EXIT.ok;
+}
+
+// src/machine-toolkit/docker-data-disk.ts
+import { statSync } from "node:fs";
+import { join as join2 } from "node:path";
+var DATA_DISK_RELATIVE = ["Docker", "wsl", "disk", "docker_data.vhdx"];
+function readDockerDataDisk(localAppData = process.env.LOCALAPPDATA, stat = statSync) {
+  if (!localAppData) return { path: null, bytes: null, unavailableReason: "LOCALAPPDATA is not set (not a Windows session)" };
+  const path = join2(localAppData, ...DATA_DISK_RELATIVE);
+  try {
+    return { path, bytes: stat(path).size };
+  } catch (err) {
+    if (err.code === "ENOENT") return { path, bytes: null, unavailableReason: "the file does not exist (Docker Desktop's WSL2 backend is not in use here)" };
+    throw err;
+  }
+}
+
+// src/machine-toolkit/docker-flags.mjs
+import { readFileSync } from "node:fs";
+import { join as join4 } from "node:path";
+
+// src/machine-toolkit/machine-home.mjs
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir, release } from "node:os";
+import { join as join3 } from "node:path";
+function isWsl(kernelRelease = release(), platform = process.platform, hasDrvFs = existsSync("/mnt/c/Users")) {
+  return platform === "linux" && /microsoft/i.test(kernelRelease) && hasDrvFs;
+}
+var WSL_CALL_TIMEOUT_MS = 1e4;
+function windowsHomeFromWsl() {
+  const raw = execFileSync("cmd.exe", ["/c", "echo %USERPROFILE%"], { windowsHide: true, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: WSL_CALL_TIMEOUT_MS }).replace(/\r/g, "").trim();
+  if (raw === "" || raw.includes("%")) throw new Error(`could not resolve the Windows home from cmd.exe (it said '${raw}')`);
+  const path = execFileSync("wslpath", ["-u", raw], { windowsHide: true, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: WSL_CALL_TIMEOUT_MS }).trim();
+  if (!existsSync(path)) throw new Error(`the Windows home '${raw}' is not a directory under /mnt/c`);
+  return path;
+}
+var COMPACTION_WINDOW_FILE = "compaction-window";
+function compactionWindowOpen(home = machineHome()) {
+  return existsSync(join3(home, ".danxbot", COMPACTION_WINDOW_FILE));
+}
+function machineHome() {
+  return isWsl() ? windowsHomeFromWsl() : homedir();
+}
+
+// src/machine-toolkit/docker-flags.mjs
+var FLAGS_STALE_MS = 3 * 60 * 60 * 1e3;
+var UNOWNED_REASON_PREFIX = "UNOWNED: ";
+function flagsFile(home = machineHome()) {
+  return join4(home, ".danxbot", "docker-flags.json");
+}
+function fail(path, what) {
+  throw Object.assign(new Error(`${path} is malformed: ${what}`), { code: "EMALFORMED" });
+}
+function validateFlags(value, path) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) fail(path, "not a JSON object");
+  if (typeof value.at !== "string" || Number.isNaN(new Date(value.at).getTime())) fail(path, `"at" must be an ISO time, not ${JSON.stringify(value.at)}`);
+  if (!Number.isInteger(value.unowned) || value.unowned < 0) fail(path, `"unowned" must be a whole number, not ${JSON.stringify(value.unowned)}`);
+  if (!Array.isArray(value.flagged)) fail(path, `"flagged" must be a list`);
+  for (const f of value.flagged) {
+    if (f === null || typeof f !== "object" || typeof f.id !== "string" || typeof f.reason !== "string" || !(f.card === null || typeof f.card === "string")) {
+      fail(path, `every "flagged" entry needs a string id and reason and a card (string or null), not ${JSON.stringify(f)}`);
+    }
+  }
+  return { at: value.at, unowned: value.unowned, flagged: value.flagged.map((f) => ({ id: f.id, reason: f.reason, card: f.card })) };
+}
+function readFlags(path = flagsFile()) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (err) {
+    fail(path, `not JSON (${err.message})`);
+  }
+  return validateFlags(value, path);
+}
+
+// src/machine-toolkit/deadline.ts
+var realScheduler = (fire, ms) => {
+  const timer = setTimeout(fire, ms);
+  return () => clearTimeout(timer);
+};
+var DeadlineExceeded = class extends Error {
+};
+function withDeadline(work, ms, schedule, what) {
+  return new Promise((resolve, reject) => {
+    const cancel = schedule(() => reject(new DeadlineExceeded(`${what} did not answer within ${ms / 1e3}s`)), ms);
+    work.then(
+      (v) => {
+        cancel();
+        resolve(v);
+      },
+      (e) => {
+        cancel();
+        reject(e);
+      }
+    );
+  });
+}
+
+// src/machine-toolkit/errors.ts
+function errorCode(err) {
+  const failure = err;
+  if (typeof failure?.code === "string" || typeof failure?.code === "number") return String(failure.code);
+  return failure?.killed === true ? "timed out" : "unexpected error";
+}
+function errMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/machine-toolkit/toolkit.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+var PROFILE = "windows-wsl-docker";
+function resolveToolkitVersion(stamped, readManifest) {
+  return stamped ?? readManifest();
+}
+var readOwnManifest = () => JSON.parse(readFileSync2(new URL("../../package.json", import.meta.url), "utf8")).version;
+var TOOLKIT_VERSION = resolveToolkitVersion(false ? void 0 : "0.1.436", readOwnManifest);
+function envelope(now) {
+  return { contract_version: CONTRACT_VERSION, toolkit_version: TOOLKIT_VERSION, profile: PROFILE, measured_at: now.toISOString() };
+}
+
+// src/machine-toolkit/health.ts
+var HEALTH_BUDGET_MS = 1e4;
+var HEALTH_MARGIN_MS = 1500;
+var MIN_ORPHAN_DEADLINE_MS = 500;
+function orphanDeadlineMs(uptimeSeconds) {
+  return Math.max(MIN_ORPHAN_DEADLINE_MS, Math.floor(HEALTH_BUDGET_MS - uptimeSeconds * 1e3 - HEALTH_MARGIN_MS));
+}
+var unread = (reason) => ({ metric: metricUnread(reason), items: [] });
+async function read(reader, what) {
+  try {
+    return await reader();
+  } catch (err) {
+    return unread(err instanceof DeadlineExceeded ? err.message : `${what} failed (${errorCode(err)})`);
+  }
+}
+async function collectHealth(src, opts = {}) {
+  const now = src.now();
+  const deadlineMs = opts.deadlineMs ?? orphanDeadlineMs(process.uptime());
+  const [dataDisk, unowned, orphans] = await Promise.all([
+    read(() => {
+      const disk = src.dataDisk();
+      return disk.bytes === null ? unread(disk.unavailableReason) : { metric: metricRead(disk.bytes), items: [] };
+    }, "reading docker_data.vhdx"),
+    read(() => {
+      const flags = src.flags();
+      if (flags === null) return unread("no real Docker sweep has written docker-flags.json on this machine yet");
+      const ageMs = Math.max(0, now.getTime() - new Date(flags.at).getTime());
+      if (ageMs > FLAGS_STALE_MS) return unread(`the last Docker sweep result is ${(ageMs / 36e5).toFixed(1)} h old (older than ${FLAGS_STALE_MS / 36e5} h): the hourly sweep has stopped, so its count is stale`);
+      const ageSeconds = Math.round(ageMs / 1e3);
+      const items = flags.flagged.filter((f) => f.reason.startsWith(UNOWNED_REASON_PREFIX)).map((f) => ({ id: f.id, detail: f.reason.slice(UNOWNED_REASON_PREFIX.length) }));
+      return { metric: metricRead(flags.unowned, "cached", ageSeconds), items };
+    }, "reading the Docker flags file"),
+    read(async () => {
+      if (src.compactionWindowOpen()) return unread("a compaction window is open, so processes are not listed until it closes");
+      const abort = new AbortController();
+      let report2;
+      try {
+        report2 = await withDeadline(src.orphans(now, abort.signal), deadlineMs, opts.schedule ?? realScheduler, "the process listing");
+      } catch (err) {
+        abort.abort();
+        throw err;
+      }
+      if (report2.unavailable.length > 0) return unread(report2.unavailable.map((u) => `${u.source} processes not listed (${u.code})`).join("; "));
+      const items = report2.findings.map((f) => ({ id: `${f.source}:${f.pid}`, detail: `${f.kind} started ${f.startedAt.toISOString()}: ${f.commandLine}` }));
+      return { metric: metricRead(items.length), items };
+    }, "listing processes")
+  ]);
+  const report = {
+    ...envelope(now),
+    metrics: {
+      docker_data_disk_bytes: dataDisk.metric,
+      unowned_docker_resource_count: unowned.metric,
+      orphan_process_count: orphans.metric
+    },
+    items: { unowned_docker_resources: unowned.items, orphan_processes: orphans.items }
+  };
+  assertContract("health", report);
+  return report;
+}
+
+// src/machine-toolkit/processes.ts
+import { execFile } from "node:child_process";
+var ORPHAN_MIN_AGE_MS = 10 * 60 * 1e3;
+var COMMAND_LINE_MAX_CHARS = 140;
+var PROCESS_LISTING_TIMEOUT_MS = 2e4;
+var WSL_SHELL_NAMES = /* @__PURE__ */ new Set(["bash", "sh", "zsh", "dash"]);
+var DOCKER_BUILD = /(?:^|[\\/"\s])docker(?:\.exe)?"?\s+(?:buildx\s+)?build\b/;
+var NODE_NAMES = /* @__PURE__ */ new Set(["node", "node.exe"]);
+var INIT_PID = 1;
+var WSL_DISTRO = "Ubuntu";
+var DOCKER_DESKTOP_DISTROS = /* @__PURE__ */ new Set(["docker-desktop", "docker-desktop-data"]);
+var LISTING_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+function kindOf(row) {
+  if (DOCKER_BUILD.test(row.commandLine)) return "docker build";
+  if (NODE_NAMES.has(row.name.toLowerCase())) return "node";
+  if (row.source === "wsl" && WSL_SHELL_NAMES.has(row.name.toLowerCase())) return "shell";
+  return null;
+}
+function parentGone(row, bySourceAndPid) {
+  if (row.source === "wsl" && row.ppid === INIT_PID) return true;
+  const parent = bySourceAndPid.get(`${row.source}:${row.ppid}`);
+  if (!parent) return true;
+  return parent.startedAt !== null && row.startedAt !== null && parent.startedAt.getTime() > row.startedAt.getTime();
+}
+function findOrphans(rows, now) {
+  const bySourceAndPid = new Map(rows.map((r) => [`${r.source}:${r.pid}`, r]));
+  const found = [];
+  for (const row of rows) {
+    const kind = kindOf(row);
+    if (kind === null || row.startedAt === null) continue;
+    if (now.getTime() - row.startedAt.getTime() < ORPHAN_MIN_AGE_MS) continue;
+    if (!parentGone(row, bySourceAndPid)) continue;
+    found.push({ source: row.source, pid: row.pid, kind, startedAt: row.startedAt, commandLine: row.commandLine.slice(0, COMMAND_LINE_MAX_CHARS) });
+  }
+  return found.sort((a, b) => a.startedAt.getTime() - b.startedAt.getTime());
+}
+var WINDOWS_LISTING_SCRIPT = "[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; Get-CimInstance Win32_Process | ForEach-Object { [pscustomobject]@{ pid = $_.ProcessId; ppid = $_.ParentProcessId; started = $(if ($_.CreationDate) { $_.CreationDate.ToUniversalTime().ToString('o') } else { $null }); name = $_.Name; cmd = $_.CommandLine; exe = $_.ExecutablePath } } | ConvertTo-Json -Compress";
+function parseWindowsListing(stdout) {
+  const parsed = JSON.parse(stdout);
+  return (Array.isArray(parsed) ? parsed : [parsed]).map((p) => ({
+    source: "windows",
+    pid: p.pid,
+    ppid: p.ppid,
+    startedAt: p.started ? new Date(p.started) : null,
+    name: p.name,
+    commandLine: p.cmd ?? "",
+    executablePath: p.exe ?? ""
+  }));
+}
+function parseWslListing(stdout, now) {
+  const rows = [];
+  for (const line of stdout.split("\n")) {
+    if (line.trim() === "") continue;
+    const m = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s*(.*)$/.exec(line);
+    if (!m) throw new Error(`wsl ps printed a line this report cannot read: ${JSON.stringify(line)}`);
+    rows.push({ source: "wsl", pid: Number(m[1]), ppid: Number(m[2]), startedAt: new Date(now.getTime() - Number(m[3]) * 1e3), name: m[4], commandLine: m[5], executablePath: "" });
+  }
+  return rows;
+}
+var runCommand = (file, args, timeoutMs, signal) => new Promise((resolve, reject) => {
+  execFile(file, args, { timeout: timeoutMs, maxBuffer: LISTING_MAX_BUFFER_BYTES, windowsHide: true, signal }, (err, stdout) => err ? reject(err) : resolve(stdout));
+});
+async function wslDistroRunning(run, signal) {
+  const stdout = await run("wsl.exe", ["--list", "--running", "--quiet"], PROCESS_LISTING_TIMEOUT_MS, signal);
+  const running = stdout.replace(/\0/g, "").split(/\r?\n/).map((line) => line.trim()).filter((line) => line !== "" && !DOCKER_DESKTOP_DISTROS.has(line));
+  if (running.length === 0) return false;
+  if (running.includes(WSL_DISTRO)) return true;
+  throw Object.assign(new Error(`${WSL_DISTRO} is not among the running WSL distros: ${running.join(", ")}`), { code: "distro not running" });
+}
+async function listProcesses(now = /* @__PURE__ */ new Date(), run = runCommand, platform = process.platform, signal, wsl = "always") {
+  if (platform !== "win32") return { rows: [], unavailable: [{ source: "windows", reason: "orphan-process listing is implemented for the Windows dev machine only", code: "unsupported platform" }] };
+  const listings = [
+    { source: "windows", read: async () => parseWindowsListing(await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", WINDOWS_LISTING_SCRIPT], PROCESS_LISTING_TIMEOUT_MS, signal)) },
+    {
+      source: "wsl",
+      read: async () => {
+        if (wsl === "when-running" && !await wslDistroRunning(run, signal)) return [];
+        return parseWslListing(await run("wsl.exe", ["-d", WSL_DISTRO, "--", "ps", "-eo", "pid=,ppid=,etimes=,comm=,args="], PROCESS_LISTING_TIMEOUT_MS, signal), now);
+      }
+    }
+  ];
+  const settled = await Promise.allSettled(listings.map((l) => l.read()));
+  const rows = [];
+  const unavailable = [];
+  settled.forEach((s, i) => {
+    if (s.status === "fulfilled") rows.push(...s.value);
+    else unavailable.push({ source: listings[i].source, reason: errMessage(s.reason), code: errorCode(s.reason) });
+  });
+  return { rows, unavailable };
+}
+async function reportOrphanProcesses(now = /* @__PURE__ */ new Date(), run = runCommand, platform = process.platform, signal, wsl = "always") {
+  const { rows, unavailable } = await listProcesses(now, run, platform, signal, wsl);
+  return { findings: findOrphans(rows, now), unavailable };
+}
+
+// src/machine-toolkit/cli.ts
+async function runToolkitCli(args, io) {
+  const [command, ...rest] = args;
+  const extra = rest.filter((a) => a !== "--json");
+  if (command !== "health" || extra.length > 0) {
+    io.err(`machine-toolkit takes only: health --json (got '${args.join(" ")}')`);
+    return EXIT.failed;
+  }
+  try {
+    const report = await io.collect();
+    io.out(JSON.stringify(report, null, 2));
+    return healthExitCode(report);
+  } catch (err) {
+    io.err(errMessage(err));
+    return EXIT.failed;
+  }
+}
+function collectFromThisMachine() {
+  return collectHealth({
+    now: () => /* @__PURE__ */ new Date(),
+    dataDisk: () => readDockerDataDisk(),
+    flags: () => readFlags(),
+    orphans: (now, signal) => reportOrphanProcesses(now, void 0, void 0, signal, "when-running"),
+    compactionWindowOpen: () => compactionWindowOpen()
+  });
+}
+function isMainModule() {
+  const entry = process.argv[1];
+  return entry !== void 0 && pathToFileURL(realpathSync(entry)).href === import.meta.url;
+}
+if (isMainModule()) {
+  runToolkitCli(process.argv.slice(2), {
+    collect: collectFromThisMachine,
+    out: (text) => console.log(text),
+    err: (text) => console.error(text)
+  }).then(
+    // Exit explicitly: a process listing abandoned at its deadline would otherwise keep the event loop (and the budget) open.
+    (code) => process.stdout.write("", () => process.exit(code)),
+    (err) => {
+      console.error(errMessage(err));
+      process.exit(EXIT.failed);
+    }
+  );
+}
+export {
+  collectFromThisMachine,
+  runToolkitCli
+};

package/dist/mini-app-build.js

@@ -0,0 +1,159 @@
+/**
+ * DX-5294 - run a mini app target's build command and fold what it wrote into ONE self-contained HTML document.
+ *
+ * A target names a build command (an argument list, run in the repo root with NO shell). Danxbot makes a fresh, empty temporary folder
+ * for each build and appends two arguments to the command: the design folder (repo-relative, forward slashes) and that output folder
+ * (absolute). The command writes `index.html` and its assets into the output folder; danxbot reads them and deletes the folder. The command
+ * is the child process: when it exits the OS releases everything it loaded, so the long-lived MCP server never holds a file of the design's
+ * checkout (DX-4727, kept). Nothing in the person's checkout is ever deleted, and no two builds share a folder.
+ *
+ * This module carries no validator for the document it produces: that the document is self-contained is checked by exactly ONE
+ * validator, the dashboard's own parse5 check on the revision route, whose 400 comes back to the caller verbatim.
+ */
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { foldBuildOutput } from "./mini-app-output.js";
+/** A build id unique per call, so two publishes never share a local page. */
+export function newBuildId() {
+    return `${Date.now().toString(36)}-${randomBytes(4).toString("hex")}`;
+}
+// ---------------- running the build ----------------
+/** How long the build command may run before it is killed: a hung build must not hold the tool call (and the design's files) forever. */
+export const BUILD_TIMEOUT_MS = 5 * 60 * 1000;
+/** The most of the build's stdout+stderr kept (the tail, where a failure is): a chatty build must not grow this long-lived process without bound. */
+export const MAX_BUILD_OUTPUT_CHARS = 1024 * 1024;
+/** How long the build's output pipes may stay open after the build process itself has exited: a leftover child holding them is then killed. */
+export const PIPE_GRACE_MS = 2000;
+/** How often, and how far apart, the temporary output folder's delete is retried: a killed build's file handle can stay open on Windows for a moment. */
+const OUTPUT_DELETE_RETRIES = 10;
+const OUTPUT_DELETE_RETRY_MS = 200;
+/**
+ * DX-5294: end the build's WHOLE process tree. The command is arbitrary repo code that may start children of its own, and a child that
+ * keeps the output pipes open would otherwise outlive the limit. Windows: `taskkill /T /F` (waited for, never blocking the event loop;
+ * it can only find children while the parent is still alive); POSIX: the child leads its own process group (spawned `detached`), and the
+ * whole group gets SIGKILL.
+ */
+async function killProcessTree(pid, child) {
+    if (pid === undefined)
+        return;
+    if (process.platform === "win32") {
+        const status = await new Promise((resolve) => {
+            const killer = spawn("taskkill", ["/T", "/F", "/PID", String(pid)], { windowsHide: true, stdio: "ignore" });
+            killer.once("error", () => resolve(null));
+            killer.once("close", (code) => resolve(code));
+        });
+        if (status !== 0)
+            child.kill();
+        return;
+    }
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        child.kill("SIGKILL");
+    }
+}
+/**
+ * Run the target's build command in a fresh child (no shell, `cwd` the repo root, the design folder and the output folder as its last two arguments) and wait for
+ * it to exit. A failed build rejects with the tail of what the command wrote to stdout and stderr (verbatim unless it passed
+ * `MAX_BUILD_OUTPUT_CHARS`, which the message then says); a command still running after `timeoutMs` has its whole process tree killed
+ * and rejects with the output so far WITHOUT waiting for the pipes to close; a command that cannot be spawned rejects with the spawn
+ * error; warnings from a good build are relayed to this process's stderr. Once the process has exited, its pipes get `pipeGraceMs` to
+ * close; a leftover child still holding them is then killed (its process group on POSIX) and no longer waited for.
+ */
+export async function runBuildCommand(input, timeoutMs = BUILD_TIMEOUT_MS, pipeGraceMs = PIPE_GRACE_MS) {
+    const [program, ...args] = input.command;
+    const done = await new Promise((resolve, reject) => {
+        const child = spawn(program, [...args, input.designDirRel, input.outputDir], {
+            cwd: input.repoRoot,
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+            detached: process.platform !== "win32",
+        });
+        let text = "";
+        let truncated = false;
+        let settled = false;
+        for (const stream of [child.stdout, child.stderr]) {
+            stream.setEncoding("utf8");
+            stream.on("data", (chunk) => {
+                text += chunk;
+                if (text.length > MAX_BUILD_OUTPUT_CHARS) {
+                    text = text.slice(-MAX_BUILD_OUTPUT_CHARS);
+                    truncated = true;
+                }
+            });
+        }
+        let grace;
+        // The ONE way the wait ends: the first caller wins, both timers stop, and every later event is ignored. Returns false when already ended.
+        const finish = () => {
+            if (settled)
+                return false;
+            settled = true;
+            clearTimeout(timer);
+            clearTimeout(grace);
+            return true;
+        };
+        // The limit or the pipe grace ran out: kill the whole tree and stop waiting on its pipes.
+        const stopWaiting = (outcome) => {
+            if (!finish())
+                return;
+            void killProcessTree(child.pid, child).finally(() => {
+                child.stdout.destroy();
+                child.stderr.destroy();
+                resolve({ ...outcome, text, truncated });
+            });
+        };
+        const timer = setTimeout(() => stopWaiting({ code: null, signal: null, timedOut: true }), timeoutMs);
+        child.once("exit", (code, signal) => {
+            grace = setTimeout(() => stopWaiting({ code, signal, timedOut: false }), pipeGraceMs);
+        });
+        child.once("error", (err) => {
+            if (finish())
+                reject(new Error(`mini_app_publish: could not start \`${program}\`: ${err.message}`));
+        });
+        child.once("close", (code, signal) => {
+            if (finish())
+                resolve({ code, signal, text, truncated, timedOut: false });
+        });
+    });
+    const note = done.truncated ? `[output truncated: only the last ${MAX_BUILD_OUTPUT_CHARS} characters are shown]\n` : "";
+    const output = done.text.trim();
+    if (done.timedOut) {
+        throw new Error(`mini_app_publish: the build did not finish within ${timeoutMs / 1000}s and was killed${output === "" ? "" : `; its output so far:\n${note}${output}`}`);
+    }
+    if (done.code !== 0) {
+        const ended = done.signal !== null ? `was killed by ${done.signal}` : `exited with code ${String(done.code)}`;
+        throw new Error(output ? `${note}${output}` : `mini_app_publish: the build process ${ended} and wrote nothing`);
+    }
+    if (done.text !== "")
+        process.stderr.write(done.text);
+}
+/**
+ * Build the design: make a fresh temporary output folder, run the command with it, read the folder and fold it into one document, then
+ * delete the folder (success or not). If the run failed or timed out nothing is read.
+ */
+export async function buildMiniApp(input, timeoutMs = BUILD_TIMEOUT_MS, pipeGraceMs = PIPE_GRACE_MS) {
+    const outputDir = await mkdtemp(path.join(os.tmpdir(), "danx-mini-app-"));
+    try {
+        await runBuildCommand({ ...input, outputDir }, timeoutMs, pipeGraceMs);
+        return { html: await foldBuildOutput(outputDir), buildId: newBuildId() };
+    }
+    finally {
+        // A temp folder danxbot made: a failed delete (a killed build's file handle still open on Windows) leaks only that folder and must not discard the build.
+        await rm(outputDir, { recursive: true, force: true, maxRetries: OUTPUT_DELETE_RETRIES, retryDelay: OUTPUT_DELETE_RETRY_MS }).catch((err) => {
+            process.stderr.write(`mini_app_publish: could not delete the temporary output folder ${outputDir}: ${err.message}\n`);
+        });
+    }
+}
+/** `<os.tmpdir()>/danx-design/<build-id>.html`: the finished page, written before the upload so an agent can open it even when the revision is refused. */
+export async function writeLocalHtml(buildId, html) {
+    const dir = path.join(os.tmpdir(), "danx-design");
+    await mkdir(dir, { recursive: true });
+    const file = path.join(dir, `${buildId}.html`);
+    await writeFile(file, html, "utf8");
+    return file;
+}