${escapeHtml(title)}

#!/usr/bin/env node import { spawnSync } from "node:child_process"; import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { basename, join, resolve } from "node:path"; import { pathToFileURL } from "node:url"; import { DEFAULT_TERMINAL_BACKGROUND, DEFAULT_TERMINAL_FOREGROUND, ansiColorCss, escapeHtml, renderAnsiToHtml, stripAnsi, } from "./web-terminal-renderer.mjs"; const HELP = `web-terminal-visual-qa Render terminal/TUI evidence through a browser-capturable web page. Usage: node script/qa/web-terminal-visual-qa.mjs --title "Codex TUI" --from-file pane.txt --evidence-dir .omo/evidence/run node script/qa/web-terminal-visual-qa.mjs --title "OpenCode TUI" --command "opencode --help" --evidence-dir .omo/evidence/run Inputs: --from-file Replay an existing terminal/tmux transcript. --command Run a command through a tmux-backed PTY connector, capture the pane, then clean up. --cwd Working directory for --command. Defaults to current directory. --cols Terminal columns for tmux connector. Default: 140. --rows Terminal rows for tmux connector. Default: 40. --dwell-ms Milliseconds to let --command render before capture. Default: 3000. --wrap Wrap long terminal lines in HTML/PNG evidence. Default. --no-wrap Preserve long lines with horizontal scrolling. --evidence-dir Directory for terminal.txt, terminal-ansi.txt, terminal.html, terminal.png, metadata.json. --chrome-bin Chrome/Chromium executable for PNG capture. --no-browser Skip PNG capture, but still write HTML/text/metadata. Connector notes: --command uses tmux as the tmux-backed PTY connector on macOS/Linux and on Windows environments that provide tmux. Windows-native ConPTY live mode should plug into this same metadata contract later; until then use --from-file or Git Bash/tmux. `; function parseArgs(argv) { const args = { cols: 140, rows: 40, dwellMs: 3000, cwd: process.cwd(), browser: true, wrap: true }; for (let i = 0; i < argv.length; i += 1) { const arg = argv[i]; if (arg === "--help" || arg === "-h") return { ...args, help: true }; if (arg === "--no-browser") { args.browser = false; continue; } if (arg === "--wrap") { args.wrap = true; continue; } if (arg === "--no-wrap") { args.wrap = false; continue; } const next = argv[i + 1]; if (!next) throw new Error(`missing value for ${arg}`); i += 1; if (arg === "--title") args.title = next; else if (arg === "--from-file") args.fromFile = next; else if (arg === "--command") args.command = next; else if (arg === "--cwd") args.cwd = next; else if (arg === "--evidence-dir") args.evidenceDir = next; else if (arg === "--chrome-bin") args.chromeBin = next; else if (arg === "--cols") args.cols = parsePositiveInt(arg, next); else if (arg === "--rows") args.rows = parsePositiveInt(arg, next); else if (arg === "--dwell-ms") args.dwellMs = parsePositiveInt(arg, next); else throw new Error(`unknown argument: ${arg}`); } return args; } function parsePositiveInt(name, value) { const parsed = Number.parseInt(value, 10); if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`${name} must be a positive integer`); return parsed; } function requireArgs(args) { if (!args.evidenceDir) throw new Error("--evidence-dir is required"); if (!args.title) throw new Error("--title is required"); if (args.fromFile && args.command) throw new Error("choose exactly one of --from-file or --command"); if (!args.fromFile && !args.command) throw new Error("choose --from-file or --command"); } function terminalWidthCh(cols) { return Math.max(80, Math.min(cols, 160)); } function screenshotSize({ cols, rows }) { return { width: Math.max(900, Math.min(1440, Math.round(cols * 8.2 + 120))), height: Math.max(520, Math.min(1200, Math.round(rows * 18 + 120))), }; } function writeHtml({ title, ansi, outPath, cols, wrap }) { const whiteSpace = wrap ? "pre-wrap" : "pre"; const overflowWrap = wrap ? "anywhere" : "normal"; const terminalWidth = terminalWidthCh(cols); const html = ` ${escapeHtml(title)}

${escapeHtml(title)}

${renderAnsiToHtml(ansi)}

`; writeFileSync(outPath, html, "utf8"); } function captureFromFile(path) { const ansi = readFileSync(path, "utf8"); return { ansi, cleanup: "cleanup: file replay; no live process", connector: "file-replay" }; } function shellQuote(value) { return `'${value.replaceAll("'", "'\\''")}'`; } function runTmuxCommand(args) { const tmux = spawnSync("tmux", ["-V"], { encoding: "utf8" }); if (tmux.status !== 0) throw new Error("--command requires tmux on PATH; use --from-file on hosts without tmux"); const session = `omo_webterm_${process.pid}_${Date.now()}`; const wrapped = `${args.command}; printf '\\n[web-terminal-visual-qa exit:%s]\\n' "$?"; sleep 600`; const launch = spawnSync("tmux", ["new-session", "-d", "-s", session, "-x", String(args.cols), "-y", String(args.rows), "-c", resolve(args.cwd), "sh", "-lc", wrapped], { encoding: "utf8" }); if (launch.status !== 0) throw new Error(`tmux launch failed: ${launch.stderr || launch.stdout}`); Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, args.dwellMs); const plain = spawnSync("tmux", ["capture-pane", "-p", "-S", "-", "-t", session], { encoding: "utf8" }); const ansi = spawnSync("tmux", ["capture-pane", "-e", "-p", "-S", "-", "-t", session], { encoding: "utf8" }); spawnSync("tmux", ["kill-session", "-t", session], { encoding: "utf8" }); return { ansi: ansi.stdout || plain.stdout, cleanup: `cleanup: tmux kill-session -t ${shellQuote(session)}`, connector: "tmux-backed-pty", }; } function chromeCandidates(explicit) { const candidates = [explicit, process.env.CHROME_BIN, process.env.GOOGLE_CHROME_BIN]; if (process.platform === "darwin") candidates.push("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium"); if (process.platform === "linux") candidates.push("google-chrome", "google-chrome-stable", "chromium", "chromium-browser"); if (process.platform === "win32") { candidates.push(join(process.env.PROGRAMFILES || "C:\\Program Files", "Google\\Chrome\\Application\\chrome.exe")); candidates.push(join(process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)", "Google\\Chrome\\Application\\chrome.exe")); } return candidates.filter((candidate) => candidate && (candidate.includes("/") || candidate.includes("\\") ? existsSync(candidate) : true)); } function capturePng(args) { for (const chrome of chromeCandidates(args.chromeBin)) { const result = spawnSync(chrome, ["--headless=new", "--disable-gpu", `--window-size=${args.width},${args.height}`, `--screenshot=${args.pngPath}`, pathToFileURL(args.htmlPath).href], { encoding: "utf8" }); if (result.status === 0 && existsSync(args.pngPath)) return { status: "captured", chrome }; } throw new Error("PNG capture failed: set --chrome-bin or --no-browser"); } function main() { const args = parseArgs(process.argv.slice(2)); if (args.help) { process.stdout.write(HELP); return; } requireArgs(args); const evidenceDir = resolve(args.evidenceDir); mkdirSync(evidenceDir, { recursive: true }); const htmlPath = join(evidenceDir, "terminal.html"); const textPath = join(evidenceDir, "terminal.txt"); const ansiPath = join(evidenceDir, "terminal-ansi.txt"); const pngPath = join(evidenceDir, "terminal.png"); const metadataPath = join(evidenceDir, "metadata.json"); const capture = args.fromFile ? captureFromFile(args.fromFile) : runTmuxCommand(args); const text = stripAnsi(capture.ansi); writeFileSync(textPath, text, "utf8"); writeFileSync(ansiPath, capture.ansi, "utf8"); writeHtml({ title: args.title, ansi: capture.ansi, outPath: htmlPath, cols: args.cols, wrap: args.wrap }); const size = screenshotSize({ cols: args.cols, rows: args.rows }); const browser = args.browser ? capturePng({ chromeBin: args.chromeBin, htmlPath, pngPath, ...size }) : { status: "skipped" }; const metadata = { title: args.title, connector: capture.connector, browserCapture: browser.status, source: args.fromFile ? resolve(args.fromFile) : args.command, wrap: args.wrap ? "on" : "off", dimensions: { cols: args.cols, rows: args.rows, screenshotWidth: size.width, screenshotHeight: size.height }, cleanup: capture.cleanup, files: { html: htmlPath, text: textPath, ansi: ansiPath, png: browser.status === "captured" ? pngPath : null, metadata: metadataPath }, }; writeFileSync(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8"); process.stdout.write(`web terminal visual QA evidence (${basename(evidenceDir)}):\n${JSON.stringify(metadata.files, null, 2)}\n${capture.cleanup}\n`); } try { main(); } catch (error) { const message = error instanceof Error ? error.message : String(error); process.stderr.write(`${message}\n`); process.exit(1); }