@kaydash9999/banker-plugins 0.23.3 → 0.24.1

package/skills/build-testbox/scripts/containers.mjs

@@ -0,0 +1,237 @@
+// Container OS cells (docker or podman) and the macOS cell (Tart on Apple Silicon) of build-testbox.
+// A container cell: image inspect (no pull), create, cp a copy of the source to /src, start -a the command, rm -f.
+// No bind mount (SELinux relabel, Windows paths). Containers are named banker-testbox-<random>-<os> and removed on
+// success, failure, time-out and signal.
+import { spawnSync } from "node:child_process";
+import { copyFileSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { imageFor } from "./args.mjs";
+import { pool } from "./browser-cell.mjs";
+import { firstLine, runProc, which } from "./proc.mjs";
+import { cellOf } from "./report.mjs";
+
+export const NAME_PREFIX = "banker-testbox";
+const iso = () => new Date().toISOString();
+export const randomTag = () => Math.random().toString(16).slice(2, 10).padEnd(8, "0");
+
+export async function detectEngines(env = process.env) {
+  const engines = {};
+  for (const name of ["docker", "podman"]) {
+    const path = which(name, env);
+    if (!path) { engines[name] = { present: false }; continue; }
+    const r = await runProc(path, ["--version"], { timeoutMs: 15000, env });
+    engines[name] = { present: true, path, version: firstLine(r.stdout) || firstLine(r.stderr) };
+    if (name === "docker") engines.docker.podmanEmulation = /podman/i.test(`${r.stdout}\n${r.stderr}`);
+  }
+  return engines;
+}
+
+// auto: a real docker first, then podman, then a docker that is podman's emulation.
+function autoEngine(engines) {
+  if (engines.docker.present && !engines.docker.podmanEmulation) return "docker";
+  if (engines.podman.present) return "podman";
+  return engines.docker.present ? "docker" : null;
+}
+
+export function selectEngine(pref, engines) {
+  const name = pref && pref !== "auto" ? pref : autoEngine(engines);
+  const e = name ? engines[name] : null;
+  if (!e || !e.present) return null;
+  return { name, bin: e.path, kind: name === "podman" || e.podmanEmulation ? "podman" : "docker" };
+}
+
+// Engine errors: a permission error (a sandbox, a socket without access) or an engine that cannot be reached.
+export function engineReason(text) {
+  const t = String(text || "");
+  if (/permission denied|operation not permitted|\bEACCES\b|\bEPERM\b/i.test(t)) return "sandbox";
+  if (/cannot connect to|daemon running|connection refused/i.test(t)) return "needs-engine";
+  return null;
+}
+
+export async function imageState(engine, image, env = process.env) {
+  const r = await runProc(engine.bin, ["image", "inspect", "--format", "{{.Id}}", image], { timeoutMs: 60000, env });
+  if (r.code === 0) return { present: true };
+  const text = `${r.stderr}\n${r.stdout}\n${r.error || ""}`;
+  return { present: false, reason: engineReason(text) || (r.timedOut ? "timeout" : "needs-image"), detail: firstLine(r.stderr) };
+}
+
+export const rmArgs = (engine, name) => (engine.kind === "podman" ? ["rm", "-f", "-t", "0", name] : ["rm", "-f", name]);
+
+export function removeAllSync(engine, names) {
+  for (const name of names) spawnSync(engine.bin, rmArgs(engine, name), { stdio: "ignore", timeout: 30000 });
+}
+
+// ── source copy ────────────────────────────────────────────────────────────
+
+function gitFiles(src) {
+  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^GIT_/i.test(k)));
+  const r = spawnSync("git", ["-C", src, "ls-files", "-z", "-co", "--exclude-standard"], { encoding: "utf8", env, maxBuffer: 256 * 1024 * 1024 });
+  return r.status === 0 ? r.stdout.split("\0").filter(Boolean) : null;
+}
+
+const SKIP_DIRS = new Set(["node_modules", ".git", ".testbox"]);
+
+function walkFiles(root, rel = "", acc = []) {
+  for (const e of readdirSync(join(root, rel), { withFileTypes: true })) {
+    if (SKIP_DIRS.has(e.name)) continue;
+    const r = rel ? `${rel}/${e.name}` : e.name;
+    if (e.isDirectory()) walkFiles(root, r, acc);
+    else acc.push(r);
+  }
+  return acc;
+}
+
+function copyEntry(src, dest, rel) {
+  const from = join(src, rel);
+  const to = join(dest, rel);
+  let st;
+  try { st = lstatSync(from); } catch { return false; }
+  mkdirSync(dirname(to), { recursive: true });
+  if (st.isSymbolicLink()) symlinkSync(readlinkSync(from), to);
+  else if (st.isFile()) copyFileSync(from, to);
+  else return false;
+  return true;
+}
+
+// The files to put in /src: a git checkout gives its tracked and untracked-not-ignored files (working tree
+// contents); any other folder gives everything but node_modules, .git and .testbox. The result folder is left out.
+export function sourceFiles(src, out) {
+  const outRel = out ? relative(src, out).split(sep).join("/") : "";
+  const skipOut = outRel && !outRel.startsWith("..") && !isAbsolute(outRel);
+  const files = gitFiles(src) || walkFiles(src);
+  return files.filter((f) => !f.startsWith(".testbox/") && !(skipOut && (f === outRel || f.startsWith(`${outRel}/`))));
+}
+
+function stageSource(src, out) {
+  const dir = mkdtempSync(join(tmpdir(), `${NAME_PREFIX}-src-`));
+  try {
+    let count = 0;
+    for (const rel of sourceFiles(src, out)) if (copyEntry(src, dir, rel)) count += 1;
+    return { dir, count };
+  } catch (e) {
+    rmSync(dir, { recursive: true, force: true });
+    return { error: firstLine(e.message) };
+  }
+}
+
+// ── one container cell ─────────────────────────────────────────────────────
+
+export function startOutcome(r) {
+  if (r.timedOut) return ["unverified", "timeout"];
+  if (r.code === 0) return ["pass", ""];
+  if (r.code === 127) return ["unverified", "needs-tool"];
+  if (r.code === null) return ["unverified", "launch-failed"];
+  if (r.code === 125 && engineReason(r.out)) return ["unverified", engineReason(r.out)];
+  return ["fail", `exit-${r.code}`];
+}
+
+async function engineStep(ctx, args, timeoutMs) {
+  const r = await runProc(ctx.engine.bin, args, { timeoutMs, env: ctx.env });
+  if (r.code === 0) return { r };
+  const text = `${r.stderr}\n${r.stdout}\n${r.error || ""}`;
+  return { r, reason: engineReason(text) || (r.timedOut ? "timeout" : "launch-failed"), detail: firstLine(r.stderr) || r.error };
+}
+
+async function networkMode(ctx, name) {
+  const r = await runProc(ctx.engine.bin, ["inspect", "--format", "{{.HostConfig.NetworkMode}}", name], { timeoutMs: 30000, env: ctx.env });
+  return (r.code === 0 && r.stdout.trim()) || ctx.o.network || "default";
+}
+
+function writeLog(file, header, body) {
+  writeFileSync(file, `${header.map((h) => `# ${h}`).join("\n")}\n${body}`);
+}
+
+async function execContainer(ctx, base, stageDir) {
+  const { o, engine } = ctx;
+  const name = `${NAME_PREFIX}-${randomTag()}-${base.target}`;
+  ctx.tracker.containers.add(name);
+  try {
+    const net = o.network ? ["--network", o.network] : [];
+    const created = await engineStep(ctx, ["create", "--name", name, "-w", "/src", ...net, base.image, "sh", "-c", o.cmd], 120000);
+    if (created.reason) return cellOf(base, "unverified", created.reason, { detail: created.detail });
+    const network = await networkMode(ctx, name);
+    const copied = await engineStep(ctx, ["cp", `${stageDir}${sep}.`, `${name}:/src`], 600000);
+    if (copied.reason) return cellOf({ ...base, network }, "unverified", copied.reason, { detail: copied.detail });
+    const r = await runProc(engine.bin, ["start", "-a", name], { timeoutMs: o.timeout * 1000, env: ctx.env });
+    const log = join(ctx.out, `os-${base.target}.log`);
+    writeLog(log, [`image ${base.image}`, `engine ${engine.name}`, `network ${network}`, `cmd ${o.cmd}`, `exit ${r.timedOut ? "timeout" : r.code}`], r.out);
+    const [status, reason] = startOutcome(r);
+    return cellOf({ ...base, container: name, network, log, exitCode: r.code }, status, reason);
+  } finally {
+    await runProc(engine.bin, rmArgs(engine, name), { timeoutMs: 60000, env: ctx.env });
+    ctx.tracker.containers.delete(name);
+  }
+}
+
+export async function runContainerCell(ctx, os) {
+  const base = { id: `os:${os}`, group: "os", target: os, image: imageFor(ctx.o, os), engine: ctx.engine ? ctx.engine.name : null, startedAt: iso() };
+  if (!ctx.engine) return cellOf(base, "unverified", "needs-engine");
+  const img = await imageState(ctx.engine, base.image, ctx.env);
+  if (!img.present) return cellOf(base, "unverified", img.reason, { detail: img.detail });
+  const stage = await ctx.stage();
+  if (stage.error) return cellOf(base, "unverified", "launch-failed", { detail: `소스 사본 실패: ${stage.error}` });
+  return execContainer(ctx, base, stage.dir);
+}
+
+// ── macOS (Tart) ───────────────────────────────────────────────────────────
+
+async function tartVms(tart, env) {
+  const r = await runProc(tart, ["list", "--format", "json"], { timeoutMs: 30000, env });
+  if (r.code !== 0) return [];
+  try {
+    return JSON.parse(r.stdout).map((v) => v.Name || v.name).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+// Tart runs only on Apple Silicon Macs (the Apple SLA allows macOS VMs on Apple hardware). hw.model alone is not
+// trusted: an x86_64 macOS VM on QEMU reports a Mac model too.
+// The tart binary and VM to use: { tart, vm }, or { cell } that says why there is none.
+async function macosVm(ctx, base) {
+  const { host, o, env } = ctx;
+  if (host.platform !== "darwin") return { cell: cellOf(base, "unsupported", "apple-sla") };
+  if (!host.appleSilicon) return { cell: cellOf(base, "unsupported", "tart-needs-apple-silicon") };
+  const tart = which("tart", env);
+  if (!tart) return { cell: cellOf(base, "unverified", "needs-tart") };
+  const vms = await tartVms(tart, env);
+  const vm = o.tartVm ? vms.find((v) => v === o.tartVm) : vms[0];
+  if (!vm) return { cell: cellOf(base, "unverified", "needs-vm", { detail: `로컬 VM: ${vms.join(", ") || "없음"}` }) };
+  return { tart, vm };
+}
+
+export async function macosCell(ctx) {
+  const { o, env } = ctx;
+  const base = { id: "os:macos", group: "os", target: "macos", engine: "tart", startedAt: iso() };
+  const found = await macosVm(ctx, base);
+  if (found.cell) return found.cell;
+  const { tart, vm } = found;
+  const help = await runProc(tart, ["exec", "--help"], { timeoutMs: 15000, env });
+  if (help.code !== 0) return cellOf({ ...base, vm }, "unverified", "tart-exec-unsupported", { detail: firstLine(help.stderr) });
+  const r = await runProc(tart, ["exec", vm, "--", "sh", "-c", o.cmd], { timeoutMs: o.timeout * 1000, env });
+  const log = join(ctx.out, "os-macos.log");
+  writeLog(log, [`tart vm ${vm}`, `cmd ${o.cmd}`, `exit ${r.timedOut ? "timeout" : r.code}`], r.out);
+  if (r.code !== 0 && !r.timedOut && /not running/i.test(r.out)) return cellOf({ ...base, vm, log }, "unverified", "needs-vm");
+  const [status, reason] = startOutcome(r);
+  return cellOf({ ...base, vm, log, exitCode: r.code }, status, reason);
+}
+
+// All requested OS cells, --jobs at a time. The source copy is made once, on first need, and removed at the end.
+export async function runOsGroup(ctx) {
+  let staged = null;
+  const stage = async () => {
+    if (!staged) staged = stageSource(ctx.o.src, ctx.out);
+    if (staged.dir) ctx.tracker.temps.add(staged.dir);
+    return staged;
+  };
+  const c = { ...ctx, stage };
+  try {
+    return await pool(ctx.o.os, ctx.o.jobs, (os) => (os === "macos" ? macosCell(c) : runContainerCell(c, os)));
+  } finally {
+    if (staged && staged.dir) {
+      rmSync(staged.dir, { recursive: true, force: true });
+      ctx.tracker.temps.delete(staged.dir);
+    }
+  }
+}

package/skills/build-testbox/scripts/detect.mjs

@@ -0,0 +1,166 @@
+// detect: host, Playwright, browsers (a real headless start, not a file check), container engines, local images and
+// Tart. Downloads nothing.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir, release } from "node:os";
+import { dirname, join } from "node:path";
+import { BROWSERS, DEFAULT_IMAGES, imageFor } from "./args.mjs";
+import { importPlaywright, probeBrowser } from "./browser-cell.mjs";
+import { detectEngines, imageState, selectEngine } from "./containers.mjs";
+import { firstLine, runProc, which } from "./proc.mjs";
+
+function sysctl(key) {
+  const bin = existsSync("/usr/sbin/sysctl") ? "/usr/sbin/sysctl" : "sysctl";
+  const r = spawnSync(bin, ["-n", key], { encoding: "utf8", timeout: 10000 });
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+// appleSilicon: an arm64 Mac (also when this Node runs under Rosetta). hw.model is reported but not trusted.
+export function hostInfo() {
+  const host = { platform: process.platform, arch: process.arch, release: release(), node: process.version, appleSilicon: false, hwModel: null };
+  if (host.platform === "darwin") {
+    host.hwModel = sysctl("hw.model");
+    host.appleSilicon = host.arch === "arm64" || sysctl("hw.optional.arm64") === "1";
+  }
+  return host;
+}
+
+function resolveFrom(base) {
+  try { return createRequire(join(base, "noop.js")).resolve("playwright"); } catch { return null; }
+}
+
+// npm's global root, asked from the home folder so a project's npm.cmd or .npmrc is not used.
+function globalRoot() {
+  const opts = { encoding: "utf8", cwd: homedir(), timeout: 30000 };
+  const r = process.platform === "win32" ? spawnSync("npm.cmd root -g", { ...opts, shell: true }) : spawnSync("npm", ["root", "-g"], opts);
+  return String(r.stdout || "").trim();
+}
+
+function packageDir(entry, name) {
+  let dir = dirname(entry);
+  while (dir !== dirname(dir)) {
+    const pj = join(dir, "package.json");
+    if (existsSync(pj) && JSON.parse(readFileSync(pj, "utf8")).name === name) return dir;
+    dir = dirname(dir);
+  }
+  return null;
+}
+
+function coreDirOf(pwDir) {
+  try { return dirname(createRequire(join(pwDir, "package.json")).resolve("playwright-core/package.json")); } catch { return null; }
+}
+
+const PLAYWRIGHT_DIR_ENV = "BUILD_TESTBOX_PLAYWRIGHT_DIR";
+
+// A folder given by --playwright-dir or BUILD_TESTBOX_PLAYWRIGHT_DIR (the folder that holds node_modules), or null.
+const givenDir = (dir, env) => dir || env[PLAYWRIGHT_DIR_ENV] || null;
+
+// { entry, from, base } or { missing } (where it looked). Order: a given folder (--playwright-dir, then
+// BUILD_TESTBOX_PLAYWRIGHT_DIR; no fallback when it lacks Playwright), the project only with --playwright-from-project
+// (loading it runs that project's code), then the global npm root. A bare import is not used.
+function findEntry(fromProject, cwd, dir, env) {
+  const base = givenDir(dir, env);
+  if (base) {
+    const entry = resolveFrom(base);
+    return entry ? { entry, from: "dir", base } : { missing: `--playwright-dir 또는 ${PLAYWRIGHT_DIR_ENV}: ${base}` };
+  }
+  const projectEntry = fromProject ? resolveFrom(cwd) : null;
+  if (projectEntry) return { entry: projectEntry, from: "project", base: cwd };
+  const root = globalRoot();
+  const entry = root ? resolveFrom(root) : null;
+  return entry ? { entry, from: "global", base: null } : { missing: `${fromProject ? "프로젝트, " : ""}전역 npm root` };
+}
+
+// { info: { entry, dir, coreDir, version, from, base } } or { error }. from is dir, project or global; base is the
+// folder npx runs in for that Playwright (null for global).
+export function locatePlaywright(fromProject = false, cwd = process.cwd(), dir = null, env = process.env) {
+  const found = findEntry(fromProject, cwd, dir, env);
+  if (found.missing) return { error: `playwright 패키지가 없습니다(${found.missing})` };
+  const pkg = packageDir(found.entry, "playwright");
+  const at = { from: found.from, base: found.base };
+  if (!pkg) return { info: { entry: found.entry, dir: null, coreDir: null, version: null, ...at } };
+  const version = JSON.parse(readFileSync(join(pkg, "package.json"), "utf8")).version;
+  const entry = existsSync(join(pkg, "index.mjs")) ? join(pkg, "index.mjs") : found.entry;
+  return { info: { entry, dir: pkg, coreDir: coreDirOf(pkg), version, ...at } };
+}
+
+export async function loadPlaywright(fromProject = false, dir = null) {
+  const loc = locatePlaywright(fromProject, process.cwd(), dir);
+  if (loc.error) return loc;
+  try {
+    return { ...loc, pw: await importPlaywright(loc.info.entry) };
+  } catch (e) {
+    return { info: loc.info, error: `playwright 를 불러오지 못했습니다: ${firstLine(e.message)}` };
+  }
+}
+
+async function browsersOf(pw) {
+  const out = {};
+  for (const name of BROWSERS) out[name] = pw ? await probeBrowser(pw, name) : { runnable: false, reason: "needs-playwright", variants: {} };
+  return out;
+}
+
+async function imagesOf(o, engine, pwVersion) {
+  const names = [...new Set([...Object.keys(DEFAULT_IMAGES), ...(o.os || []).filter((x) => x !== "macos")])];
+  const targets = names.map((os) => [os, imageFor(o, os)]).filter(([, img]) => img);
+  if (pwVersion) targets.push(["playwright", o.images.playwright || playwrightImage(pwVersion)]);
+  const images = {};
+  for (const [key, image] of targets) images[key] = engine ? { image, ...(await imageState(engine, image)) } : { image, present: false, reason: "needs-engine" };
+  return images;
+}
+
+export const playwrightImage = (version) => `mcr.microsoft.com/playwright:v${version}-noble`;
+
+async function tartOf(host) {
+  if (host.platform !== "darwin") return { present: false, reason: "apple-sla" };
+  if (!host.appleSilicon) return { present: false, reason: "tart-needs-apple-silicon" };
+  const tart = which("tart");
+  if (!tart) return { present: false, reason: "needs-tart" };
+  const r = await runProc(tart, ["list", "--format", "json"], { timeoutMs: 30000 });
+  let vms = [];
+  try { vms = JSON.parse(r.stdout).map((v) => v.Name || v.name).filter(Boolean); } catch { vms = []; }
+  return { present: true, path: tart, vms };
+}
+
+export async function detect(o) {
+  const host = hostInfo();
+  const loaded = await loadPlaywright(o.fromProject, o.playwrightDir);
+  const engines = await detectEngines();
+  const engine = selectEngine(o.engine, engines);
+  const playwright = loaded.info ? { found: !loaded.error, ...loaded.info, error: loaded.error } : { found: false, error: loaded.error };
+  return {
+    tool: "build-testbox",
+    host,
+    playwright,
+    browsers: await browsersOf(loaded.pw),
+    engines,
+    engine: engine ? { name: engine.name, kind: engine.kind, path: engine.bin } : null,
+    images: await imagesOf(o, engine, loaded.pw ? loaded.info.version : null),
+    tart: await tartOf(host),
+  };
+}
+
+function browserLine(name, b) {
+  if (b.runnable) return `- ${name}: 실행 가능(${b.variant})`;
+  return `- ${name}: 실행 불가(${b.reason})${b.detail ? ` ${b.detail.slice(0, 160)}` : ""}`;
+}
+
+function hostLine(h) {
+  const mac = h.platform === "darwin" ? `, Apple Silicon ${h.appleSilicon ? "예" : "아니오"}, hw.model ${h.hwModel}` : "";
+  return `호스트: ${h.platform} ${h.arch}${mac}`;
+}
+
+function playwrightLine(p) {
+  return p.found ? `Playwright: ${p.version} (${p.from}, ${p.dir})` : `Playwright: 없음 (${p.error})`;
+}
+
+export function renderDetect(d) {
+  const lines = [hostLine(d.host), playwrightLine(d.playwright)];
+  for (const name of BROWSERS) lines.push(browserLine(name, d.browsers[name]));
+  const emu = d.engines.docker.present && d.engines.docker.podmanEmulation ? ", docker 는 podman 에뮬레이션" : "";
+  lines.push(`엔진: ${d.engine ? `${d.engine.name}${emu}` : "없음"}`);
+  for (const [key, img] of Object.entries(d.images)) lines.push(`- 이미지 ${key}: ${img.image} ${img.present ? "있음" : `없음(${img.reason})`}`);
+  lines.push(`Tart: ${d.tart.present ? `VM ${d.tart.vms.join(", ") || "없음"}` : d.tart.reason}`);
+  return `${lines.join("\n")}\n`;
+}

package/skills/build-testbox/scripts/proc.mjs

@@ -0,0 +1,91 @@
+// Child processes for build-testbox: PATH lookup (PATHEXT on Windows), a promise-returning runner with a time limit
+// and a set of live children, so a signal handler can stop them all. No shell: arguments go to the program as given.
+// On Windows a .cmd or .bat goes through cmd.exe with each argument quoted (Node refuses to spawn them directly).
+import { spawn } from "node:child_process";
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, extname, isAbsolute, join } from "node:path";
+
+const LIVE = new Set();
+const MAX_OUT = 8 * 1024 * 1024;
+
+function isExecutable(file) {
+  try {
+    if (!statSync(file).isFile()) return false;
+    if (process.platform !== "win32") accessSync(file, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// On Windows a name without extension also tries each PATHEXT entry.
+function candidates(name, env) {
+  const dirs = String(env.PATH || env.Path || "").split(delimiter).filter(Boolean);
+  const exts = process.platform === "win32" && !extname(name) ? String(env.PATHEXT || ".EXE;.CMD;.BAT").split(";").filter(Boolean) : [""];
+  return dirs.flatMap((dir) => exts.flatMap((ext) => [...new Set([name + ext.toLowerCase(), name + ext])].map((n) => join(dir, n))));
+}
+
+// The full path of a program on PATH, or null.
+export function which(name, env = process.env) {
+  if (isAbsolute(name)) return isExecutable(name) ? name : null;
+  return candidates(name, env).find(isExecutable) || null;
+}
+
+const quoteCmd = (a) => `"${String(a).replace(/"/g, '""')}"`;
+
+function spawnArgs(file, args) {
+  if (process.platform === "win32" && /\.(cmd|bat)$/i.test(file)) {
+    const line = [file, ...args].map(quoteCmd).join(" ");
+    return [process.env.ComSpec || "cmd.exe", ["/d", "/s", "/c", `"${line}"`], { windowsVerbatimArguments: true }];
+  }
+  return [file, args, {}];
+}
+
+function collector() {
+  const parts = { stdout: "", stderr: "", out: "" };
+  const add = (key) => (chunk) => {
+    const s = chunk.toString("utf8");
+    if (parts.out.length < MAX_OUT) parts.out += s;
+    if (parts[key].length < MAX_OUT) parts[key] += s;
+  };
+  return { parts, add };
+}
+
+// Runs a program and resolves { code, signal, stdout, stderr, out, timedOut, error }. Never rejects: a missing
+// program is { code: null, error: "ENOENT" }. out holds stdout and stderr in arrival order.
+export function runProc(cmd, args = [], opts = {}) {
+  const file = which(cmd, opts.env || process.env) || cmd;
+  const [bin, argv, extra] = spawnArgs(file, args);
+  const { parts, add } = collector();
+  return new Promise((resolveRun) => {
+    let timedOut = false;
+    let child;
+    try {
+      child = spawn(bin, argv, { cwd: opts.cwd, env: opts.env || process.env, stdio: ["ignore", "pipe", "pipe"], ...extra });
+    } catch (e) {
+      resolveRun({ code: null, signal: null, ...parts, timedOut, error: e.code || String(e.message) });
+      return;
+    }
+    LIVE.add(child);
+    const timer = opts.timeoutMs ? setTimeout(() => { timedOut = true; child.kill("SIGKILL"); }, opts.timeoutMs) : null;
+    child.stdout.on("data", add("stdout"));
+    child.stderr.on("data", add("stderr"));
+    let error = null;
+    child.on("error", (e) => { error = e.code || String(e.message); });
+    child.on("close", (code, signal) => {
+      if (timer) clearTimeout(timer);
+      LIVE.delete(child);
+      resolveRun({ code, signal, ...parts, timedOut, error });
+    });
+  });
+}
+
+// Stops every child still running (used by the SIGINT and SIGTERM handlers).
+export function killAll() {
+  for (const child of LIVE) {
+    try { child.kill("SIGKILL"); } catch { /* already gone */ }
+  }
+  LIVE.clear();
+}
+
+export const firstLine = (s) => String(s || "").split(/\r?\n/).map((l) => l.trim()).find(Boolean) || "";

package/skills/build-testbox/scripts/report.mjs

@@ -0,0 +1,109 @@
+// Cell states, reasons, hints, exit codes and the written results (results.json, summary.md) for build-testbox.
+// The screen table and summary.md come from one function, so they hold the same rows.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const STATUSES = ["pass", "fail", "unverified", "unsupported"];
+
+// Every reason a cell can end with. fail reasons are patterns (exit-<n>, http-<n>, page-error).
+export const UNVERIFIED_REASONS = [
+  "needs-playwright", "needs-browser", "needs-image", "needs-engine", "needs-network", "needs-tool",
+  "needs-tart", "needs-vm", "tart-exec-unsupported", "host-deps", "launch-failed", "unknown-device", "timeout", "sandbox",
+];
+export const UNSUPPORTED_REASONS = ["apple-sla", "tart-needs-apple-silicon"];
+export const FAIL_REASON = /^(exit-\d+|http-\d+|page-error)$/;
+
+const SANDBOX_HINT = "권한 오류. Codex 는 컨테이너, 브라우저 실행을 sandbox_permissions: \"require_escalated\" 로 승인 요청한 뒤 다시 실행";
+
+const HINTS = {
+  "needs-playwright": () => "Playwright 패키지 없음. setup-playwright 스킬로 설치",
+  "needs-browser": (c) => `브라우저 미설치. build-testbox setup --browsers ${c.browser || "<이름>"}`,
+  "needs-image": (c) => (c.group === "browser"
+    ? "Playwright 공식 이미지가 로컬에 없음. build-testbox setup --playwright-image"
+    : `로컬 이미지 없음. build-testbox setup --images ${c.target}`),
+  "needs-engine": () => "docker, podman 없음(또는 엔진에 연결 못 함)",
+  "needs-network": () => "setup 원천에 닿지 못함",
+  "needs-tool": () => "컨테이너 안 명령 없음(종료 127). 이미지에 도구를 넣거나 --cmd 를 바꿈",
+  "needs-tart": () => "Tart 없음(Apple Silicon 의 macOS 13 이상, https://tart.run)",
+  "needs-vm": () => "Tart VM 없음이나 꺼짐. tart clone 으로 받기(약 25GB) 뒤 tart run, --tart-vm <이름>",
+  "tart-exec-unsupported": () => "이 Tart 판에 tart exec 없음. Tart 를 올림",
+  "host-deps": () => "브라우저 실행에 필요한 OS 라이브러리 없음. --browser-in-container 사용",
+  "launch-failed": () => "실행 실패. 로그 확인",
+  "unknown-device": () => "이 Playwright 판에 없는 기기 이름",
+  timeout: () => "시간 초과. --timeout 을 늘림",
+  sandbox: () => SANDBOX_HINT,
+  "apple-sla": () => "Apple SLA 상 macOS 는 Apple 하드웨어에서만. 비 Apple 호스트는 지원 안 함",
+  "tart-needs-apple-silicon": () => "Tart 는 Apple Silicon(arm64) 전용. 이 macOS 는 Intel 이거나 가상 머신",
+};
+
+export function hintOf(cell) {
+  const h = HINTS[cell.reason];
+  if (h) return h(cell);
+  return cell.status === "fail" ? "로그 확인" : "";
+}
+
+function countOf(cells) {
+  const counts = { pass: 0, fail: 0, unverified: 0, unsupported: 0 };
+  for (const c of cells) counts[c.status] += 1;
+  return counts;
+}
+
+// 0 every requested cell passed, 1 a fail, 4 no fail but an unverified or unsupported cell.
+export function exitCodeOf(cells) {
+  const n = countOf(cells);
+  if (n.fail) return 1;
+  if (n.unverified || n.unsupported) return 4;
+  return 0;
+}
+
+export const summaryLine = (n) => `pass ${n.pass}, fail ${n.fail}, unverified ${n.unverified}, unsupported ${n.unsupported}`;
+
+const cellText = (v) => String(v ?? "").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+
+function seconds(c) {
+  const ms = Date.parse(c.endedAt) - Date.parse(c.startedAt);
+  return Number.isFinite(ms) ? (ms / 1000).toFixed(1) : "";
+}
+
+export function tableLines(cells) {
+  const lines = ["| 칸 | 상태 | 사유 | 초 | 안내 |", "|---|---|---|---|---|"];
+  for (const c of cells) lines.push(`| ${cellText(c.id)} | ${c.status} | ${cellText(c.reason)} | ${seconds(c)} | ${cellText(c.hint)} |`);
+  return lines;
+}
+
+// The text printed on screen and written to summary.md: summary line, notes, table.
+export function renderSummary(results) {
+  const lines = [summaryLine(results.counts), ""];
+  for (const note of results.notes) lines.push(`- ${note}`);
+  if (results.notes.length) lines.push("");
+  return [...lines, ...tableLines(results.cells), ""].join("\n");
+}
+
+export function buildResults({ cells, notes, host, startedAt, out }) {
+  const done = cells.map((c) => ({ ...c, hint: c.hint ?? hintOf(c) }));
+  return {
+    tool: "build-testbox",
+    schema: 1,
+    startedAt,
+    endedAt: new Date().toISOString(),
+    out,
+    host,
+    counts: countOf(done),
+    exitCode: exitCodeOf(done),
+    notes,
+    cells: done,
+  };
+}
+
+// Throws on a write failure; the caller turns that into exit 3.
+export function writeResults(out, results) {
+  mkdirSync(out, { recursive: true });
+  writeFileSync(join(out, "results.json"), `${JSON.stringify(results, null, 2)}\n`);
+  writeFileSync(join(out, "summary.md"), renderSummary(results));
+}
+
+// A finished cell record. Times are ISO strings.
+export function cellOf(base, status, reason, extra = {}) {
+  const now = new Date().toISOString();
+  return { startedAt: now, ...base, status, reason: reason || "", endedAt: extra.endedAt || base.endedAt || now, ...extra };
+}