verikun 0.4.1

package/dist/image.js

@@ -0,0 +1,212 @@
+"use strict";
+// Hand-rolled, dependency-free PNG downscaler.
+//
+// A device screenshot is ~1080×2400; an agent reading that image pays for its
+// pixel area in tokens. Downscaling to a smaller longest edge keeps UI text
+// legible while cutting that cost markedly. We do it in pure Node — decode the
+// PNG, box-average the pixels, re-encode — using only `node:zlib` (a builtin),
+// honoring the project's zero-runtime-dependency rule.
+//
+// Scope: 8-bit, non-interlaced PNGs in grayscale / RGB / gray+alpha / RGBA
+// (color types 0/2/4/6) — what `screencap` and `simctl` emit. Anything else
+// (palette, 16-bit, interlaced) is left untouched and reported via `reason`,
+// so a screenshot is never corrupted, only (sometimes) not shrunk.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.downscalePng = downscalePng;
+const node_zlib_1 = require("node:zlib");
+const PNG_SIG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/** Channel count for a supported PNG color type, or 0 if unsupported (e.g. palette). */
+function channelsFor(colorType) {
+    switch (colorType) {
+        case 0: return 1; // grayscale
+        case 2: return 3; // RGB
+        case 4: return 2; // gray + alpha
+        case 6: return 4; // RGBA
+        default: return 0; // 3 = palette, etc. — unsupported
+    }
+}
+function paeth(a, b, c) {
+    const p = a + b - c;
+    const pa = Math.abs(p - a);
+    const pb = Math.abs(p - b);
+    const pc = Math.abs(p - c);
+    return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+/** Reverse PNG per-scanline filtering into packed pixels (height*width*channels bytes). */
+function unfilter(data, width, height, ch) {
+    const stride = width * ch;
+    const raw = Buffer.alloc(height * stride);
+    let pos = 0;
+    let prev = Buffer.alloc(stride); // row above the first row is all zeros
+    for (let y = 0; y < height; y++) {
+        const ft = data[pos++];
+        const cur = raw.subarray(y * stride, (y + 1) * stride);
+        for (let x = 0; x < stride; x++) {
+            const filt = data[pos++];
+            const a = x >= ch ? cur[x - ch] : 0; // left
+            const b = prev[x]; // above
+            const c = x >= ch ? prev[x - ch] : 0; // above-left
+            let val;
+            switch (ft) {
+                case 1:
+                    val = filt + a;
+                    break; // Sub
+                case 2:
+                    val = filt + b;
+                    break; // Up
+                case 3:
+                    val = filt + ((a + b) >> 1);
+                    break; // Average
+                case 4:
+                    val = filt + paeth(a, b, c);
+                    break; // Paeth
+                default:
+                    val = filt;
+                    break; // None (0) / unknown
+            }
+            cur[x] = val & 0xff;
+        }
+        prev = cur;
+    }
+    return raw;
+}
+/** Box-average downscale of packed pixels from (sw,sh) to (tw,th). */
+function boxDownscale(src, sw, sh, tw, th, ch) {
+    const dst = Buffer.alloc(tw * th * ch);
+    const acc = new Array(ch);
+    for (let dy = 0; dy < th; dy++) {
+        const sy0 = Math.floor((dy * sh) / th);
+        const sy1 = Math.max(sy0 + 1, Math.floor(((dy + 1) * sh) / th));
+        for (let dx = 0; dx < tw; dx++) {
+            const sx0 = Math.floor((dx * sw) / tw);
+            const sx1 = Math.max(sx0 + 1, Math.floor(((dx + 1) * sw) / tw));
+            acc.fill(0);
+            for (let sy = sy0; sy < sy1; sy++) {
+                let p = (sy * sw + sx0) * ch;
+                for (let sx = sx0; sx < sx1; sx++) {
+                    for (let k = 0; k < ch; k++)
+                        acc[k] += src[p + k];
+                    p += ch;
+                }
+            }
+            const count = (sy1 - sy0) * (sx1 - sx0);
+            const d = (dy * tw + dx) * ch;
+            for (let k = 0; k < ch; k++)
+                dst[d + k] = Math.round(acc[k] / count);
+        }
+    }
+    return dst;
+}
+/** Prepend a None (0) filter byte to each scanline, ready for deflate. */
+function applyNoneFilter(raw, w, h, ch) {
+    const stride = w * ch;
+    const out = Buffer.alloc(h * (stride + 1));
+    for (let y = 0; y < h; y++) {
+        out[y * (stride + 1)] = 0;
+        raw.copy(out, y * (stride + 1) + 1, y * stride, (y + 1) * stride);
+    }
+    return out;
+}
+// CRC-32 (IEEE) for chunk integrity. node:zlib.crc32 only exists on newer Node,
+// and the project targets Node ≥ 18, so we keep our own tiny table.
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(buf) {
+    let c = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(data.length, 0);
+    const typeBuf = Buffer.from(type, 'ascii');
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])), 0);
+    return Buffer.concat([len, typeBuf, data, crc]);
+}
+function buildPng(w, h, bitDepth, colorType, idat) {
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(w, 0);
+    ihdr.writeUInt32BE(h, 4);
+    ihdr[8] = bitDepth;
+    ihdr[9] = colorType;
+    // compression, filter, interlace methods are all 0 (the only standard values)
+    return Buffer.concat([PNG_SIG, chunk('IHDR', ihdr), chunk('IDAT', idat), chunk('IEND', Buffer.alloc(0))]);
+}
+/**
+ * Downscale a PNG so its longest edge is at most `maxEdge` px (never upscales).
+ * Returns the original buffer unchanged when it is already small enough or is in
+ * an unsupported PNG form; `reason` explains which.
+ */
+function downscalePng(input, maxEdge) {
+    const asis = (width, height, reason) => ({
+        buf: input, width, height, scaled: false, origWidth: width, origHeight: height, reason,
+    });
+    if (input.length < 8 || !input.subarray(0, 8).equals(PNG_SIG))
+        return asis(0, 0, 'not a PNG');
+    if (!(maxEdge >= 1))
+        return asis(0, 0, 'no target size');
+    // Walk chunks for IHDR + concatenated IDAT.
+    let width = 0, height = 0, bitDepth = 0, colorType = 0, interlace = 0;
+    let haveIhdr = false;
+    const idat = [];
+    let off = 8;
+    while (off + 8 <= input.length) {
+        const len = input.readUInt32BE(off);
+        const type = input.toString('ascii', off + 4, off + 8);
+        const start = off + 8;
+        if (start + len > input.length)
+            break; // truncated
+        if (type === 'IHDR' && len >= 13) {
+            width = input.readUInt32BE(start);
+            height = input.readUInt32BE(start + 4);
+            bitDepth = input[start + 8];
+            colorType = input[start + 9];
+            interlace = input[start + 12];
+            haveIhdr = true;
+        }
+        else if (type === 'IDAT') {
+            idat.push(input.subarray(start, start + len));
+        }
+        else if (type === 'IEND') {
+            break;
+        }
+        off = start + len + 4; // +4 skips the chunk CRC
+    }
+    if (!haveIhdr || width < 1 || height < 1)
+        return asis(width, height, 'no IHDR');
+    const ch = channelsFor(colorType);
+    if (bitDepth !== 8 || interlace !== 0 || ch === 0) {
+        return asis(width, height, 'unsupported PNG format (need 8-bit, non-interlaced, non-palette)');
+    }
+    if (Math.max(width, height) <= maxEdge)
+        return asis(width, height, 'already within target');
+    let raw;
+    try {
+        const inflated = (0, node_zlib_1.inflateSync)(Buffer.concat(idat));
+        if (inflated.length < height * (1 + width * ch))
+            return asis(width, height, 'short pixel data');
+        raw = unfilter(inflated, width, height, ch);
+    }
+    catch {
+        return asis(width, height, 'could not decode pixel data');
+    }
+    const scale = maxEdge / Math.max(width, height);
+    const tw = Math.max(1, Math.round(width * scale));
+    const th = Math.max(1, Math.round(height * scale));
+    const small = boxDownscale(raw, width, height, tw, th, ch);
+    const idatOut = (0, node_zlib_1.deflateSync)(applyNoneFilter(small, tw, th, ch));
+    return {
+        buf: buildPng(tw, th, bitDepth, colorType, idatOut),
+        width: tw, height: th, scaled: true, origWidth: width, origHeight: height,
+    };
+}

package/dist/output.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setOutputQuiet = setOutputQuiet;
+exports.out = out;
+exports.err = err;
+exports.json = json;
+exports.artifactDir = artifactDir;
+exports.defaultScreenshotPath = defaultScreenshotPath;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// Output discipline: primary results -> stdout, diagnostics/errors -> stderr.
+// Everything that prints data also supports --json for structured consumption.
+// `vk ai` runs many leaf commands in one process; their per-step `out()`
+// confirmations ("tapped …") would pollute stdout (which must stay the one
+// parseable result). The engine sets quiet for the duration of the run so that
+// per-step `out()` is suppressed while `err()` (stderr progress) still streams.
+let quiet = false;
+/** Suppress/restore `out()` (not `err()`/`json()`). Returns the previous value. */
+function setOutputQuiet(q) {
+    const prev = quiet;
+    quiet = q;
+    return prev;
+}
+function out(s) {
+    if (quiet)
+        return;
+    process.stdout.write(s + '\n');
+}
+function err(s) {
+    process.stderr.write(s + '\n');
+}
+function json(obj) {
+    process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+}
+/** Local run artifacts live in ./.verikun (gitignored). */
+function artifactDir() {
+    const dir = (0, node_path_1.resolve)(process.cwd(), '.verikun');
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    return dir;
+}
+function defaultScreenshotPath() {
+    return (0, node_path_1.join)(artifactDir(), 'screen.png');
+}

package/dist/report.js

@@ -0,0 +1,223 @@
+"use strict";
+// Pure report rendering: a finished RunState in -> a JUnit XML / HTML string out.
+// No fs, no device, no side effects — so it is trivially testable and the run
+// recorder (run.ts) owns all the I/O. The data model lives in run.ts; we import
+// the types only.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toJUnitXml = toJUnitXml;
+exports.toHtml = toHtml;
+// --- escaping -------------------------------------------------------------
+// XML 1.0 forbids most control chars even when escaped; drop them so a stray
+// byte in a UI label can't produce an unparseable report.
+const stripCtl = (s) => s.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '');
+const xmlAttr = (s) => stripCtl(s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+const xmlText = (s) => stripCtl(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const htmlEsc = (s) => s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+// --- shared labels --------------------------------------------------------
+function selectorLabel(s) {
+    return s.selector ? `${s.selector.raw} (${s.selector.kind})` : '';
+}
+function resolvedLabel(s) {
+    const r = s.resolved;
+    if (!r)
+        return '';
+    const id = r.id || (r.idShort ? '@' + r.idShort : '') || r.type;
+    const text = r.text ? ` ${JSON.stringify(r.text)}` : '';
+    return `${id}${text} (${r.center.x},${r.center.y})`;
+}
+function fmtDuration(ms) {
+    return ms < 1000 ? `${ms} ms` : `${(ms / 1000).toFixed(2)} s`;
+}
+function counts(run) {
+    const passed = run.steps.filter((s) => s.status === 'passed').length;
+    const failures = run.steps.filter((s) => s.status === 'failed').length;
+    const errors = run.steps.filter((s) => s.status === 'error').length;
+    const timeMs = run.steps.reduce((a, s) => a + s.durationMs, 0);
+    return { tests: run.steps.length, passed, failures, errors, timeMs };
+}
+// --- JUnit ----------------------------------------------------------------
+function toJUnitXml(run) {
+    const c = counts(run);
+    const suiteTime = (c.timeMs / 1000).toFixed(3);
+    const cases = run.steps
+        .map((s) => {
+        const time = (s.durationMs / 1000).toFixed(3);
+        const classname = 'verikun.' + s.command;
+        const attrs = `name="${xmlAttr(s.name)}" classname="${xmlAttr(classname)}" time="${time}"`;
+        const lines = [];
+        if (selectorLabel(s))
+            lines.push(`selector: ${selectorLabel(s)}`);
+        if (s.tier && s.tier !== 'exact')
+            lines.push(`healed: matched via ${s.tier}, not exact`);
+        if (s.healed)
+            lines.push(`model-healed: ${s.message ?? 'repaired'}`);
+        if (resolvedLabel(s))
+            lines.push(`resolved: ${resolvedLabel(s)}`);
+        if (s.failImage)
+            lines.push(`screenshot: ${s.failImage}`);
+        if (s.image)
+            lines.push(`image: ${s.image}`);
+        let body = '';
+        if (s.status === 'failed' || s.status === 'error') {
+            const tag = s.status === 'failed' ? 'failure' : 'error';
+            const type = s.status === 'failed' ? 'AssertionFailure' : 'EnvironmentError';
+            const detail = [
+                s.message ?? s.status,
+                ...lines,
+                s.failHierarchy ? `\nUI hierarchy at failure:\n${s.failHierarchy}` : '',
+                s.logs ? `\nDevice logs:\n${s.logs}` : '',
+            ]
+                .filter(Boolean)
+                .join('\n');
+            body =
+                `\n    <${tag} message="${xmlAttr(s.message ?? s.status)}" type="${type}">` +
+                    `${xmlText(detail)}</${tag}>`;
+        }
+        else if (lines.length || s.logs) {
+            const sysOut = [...lines, s.logs ? `Device logs:\n${s.logs}` : ''].filter(Boolean).join('\n');
+            body = `\n    <system-out>${xmlText(sysOut)}</system-out>`;
+        }
+        return `  <testcase ${attrs}>${body}\n  </testcase>`;
+    })
+        .join('\n');
+    const suiteAttrs = `name="${xmlAttr(run.name)}" tests="${c.tests}" failures="${c.failures}" ` +
+        `errors="${c.errors}" time="${suiteTime}" timestamp="${xmlAttr(run.startedAt)}"`;
+    return (`<?xml version="1.0" encoding="UTF-8"?>\n` +
+        `<testsuites name="verikun" tests="${c.tests}" failures="${c.failures}" errors="${c.errors}" time="${suiteTime}">\n` +
+        `<testsuite ${suiteAttrs}>\n` +
+        `${cases}\n` +
+        (run.ai
+            ? `  <system-out>${xmlText('vk ai: ' +
+                run.ai.cost +
+                (run.ai.improvements.length ? '\nSuggested improvements:\n' + run.ai.improvements.join('\n') : ''))}</system-out>\n`
+            : '') +
+        `</testsuite>\n</testsuites>\n`);
+}
+// --- HTML -----------------------------------------------------------------
+const STYLE = `
+  :root { --pass:#1a7f37; --fail:#cf222e; --err:#9a6700; --bg:#f6f8fa; --line:#d0d7de; --muted:#57606a; }
+  * { box-sizing: border-box; }
+  body { margin:0; font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif; color:#1f2328; background:var(--bg); }
+  .wrap { max-width: 920px; margin: 0 auto; padding: 24px 20px 64px; }
+  h1 { font-size: 20px; margin: 0 0 4px; }
+  .meta { color: var(--muted); font-size: 13px; margin-bottom: 16px; }
+  .meta code { background:#eaeef2; padding:1px 5px; border-radius:4px; }
+  .summary { display:flex; gap:8px; flex-wrap:wrap; align-items:center; margin-bottom: 20px; }
+  .chip { font-weight:600; font-size:13px; padding:4px 10px; border-radius:999px; color:#fff; }
+  .chip.pass{background:var(--pass)} .chip.fail{background:var(--fail)} .chip.err{background:var(--err)}
+  .chip.muted{ background:#eaeef2; color:var(--muted); }
+  ol.steps { list-style:none; margin:0; padding:0; }
+  li.step { background:#fff; border:1px solid var(--line); border-left-width:4px; border-radius:8px; margin-bottom:10px; padding:12px 14px; }
+  li.step.passed{ border-left-color:var(--pass) } li.step.failed{ border-left-color:var(--fail) } li.step.error{ border-left-color:var(--err) }
+  .row { display:flex; align-items:center; gap:10px; }
+  .idx { color:var(--muted); font-variant-numeric:tabular-nums; }
+  .st { font-weight:700; font-size:11px; letter-spacing:.04em; padding:2px 7px; border-radius:4px; color:#fff; }
+  .st.passed{background:var(--pass)} .st.failed{background:var(--fail)} .st.error{background:var(--err)}
+  .name { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:13px; }
+  .time { margin-left:auto; color:var(--muted); font-variant-numeric:tabular-nums; }
+  .detail { margin-top:8px; font-size:13px; color:#1f2328; }
+  .detail .k { color:var(--muted); }
+  .detail code { background:#eaeef2; padding:1px 5px; border-radius:4px; font-size:12px; }
+  .msg { margin-top:6px; font-size:13px; }
+  .msg.fail { color:var(--fail); }
+  img.shot { display:block; margin-top:10px; max-width:300px; max-height:520px; border:1px solid var(--line); border-radius:6px; }
+  details { margin-top:8px; }
+  summary { cursor:pointer; color:var(--muted); font-size:13px; }
+  pre { background:#0d1117; color:#e6edf3; padding:12px; border-radius:6px; overflow:auto; font-size:12px; line-height:1.45; max-height:360px; }
+  .aibox { background:#fff; border:1px solid var(--line); border-radius:8px; padding:12px 14px; margin-bottom:20px; font-size:13px; }
+  .aibox .cost { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; color:var(--muted); margin-top:4px; }
+  .aibox ul { margin:8px 0 0; padding-left:18px; }
+`;
+function aiPanelHtml(ai) {
+    const improvements = ai.improvements.length
+        ? `<details open><summary>Suggested test improvements (${ai.improvements.length})</summary><ul>${ai.improvements
+            .map((s) => `<li>${htmlEsc(s)}</li>`)
+            .join('')}</ul></details>`
+        : '';
+    return `<div class="aibox">
+      <div><span class="k">vk ai</span> ${ai.ok ? 'passed' : 'did not pass'}${ai.modelRepairs ? ` &middot; ${ai.modelRepairs} model repair(s)` : ''}</div>
+      <div class="cost">${htmlEsc(ai.cost)}</div>
+      ${improvements}
+    </div>`;
+}
+function stepHtml(s) {
+    const detail = [];
+    if (selectorLabel(s))
+        detail.push(`<span class="k">selector</span> <code>${htmlEsc(s.selector.raw)}</code> <span class="k">(${htmlEsc(s.selector.kind)})</span>`);
+    if (s.tier && s.tier !== 'exact')
+        detail.push(`<span class="k">healed</span> <code>${htmlEsc(s.tier)}</code>`);
+    if (s.healed)
+        detail.push(`<span class="k">model-healed</span>`);
+    if (resolvedLabel(s))
+        detail.push(`<span class="k">resolved</span> <code>${htmlEsc(resolvedLabel(s))}</code>`);
+    const parts = [];
+    parts.push(`<div class="row">
+      <span class="idx">#${s.index}</span>
+      <span class="st ${s.status}">${s.status.toUpperCase()}</span>
+      <span class="name">${htmlEsc(s.name)}</span>
+      <span class="time">${fmtDuration(s.durationMs)}</span>
+    </div>`);
+    if (detail.length)
+        parts.push(`<div class="detail">${detail.join(' &middot; ')}</div>`);
+    if (s.message)
+        parts.push(`<div class="msg ${s.status !== 'passed' ? 'fail' : ''}">${htmlEsc(s.message)}</div>`);
+    if (s.image)
+        parts.push(`<a href="${htmlEsc(s.image)}"><img class="shot" src="${htmlEsc(s.image)}" alt="screenshot"></a>`);
+    if (s.failImage)
+        parts.push(`<a href="${htmlEsc(s.failImage)}"><img class="shot" src="${htmlEsc(s.failImage)}" alt="screen at failure"></a>`);
+    if (s.failHierarchy)
+        parts.push(`<details><summary>UI hierarchy at failure</summary><pre>${htmlEsc(s.failHierarchy)}</pre></details>`);
+    if (s.logs)
+        parts.push(`<details><summary>Device logs</summary><pre>${htmlEsc(s.logs)}</pre></details>`);
+    return `<li class="step ${s.status}">${parts.join('\n    ')}</li>`;
+}
+function toHtml(run) {
+    const c = counts(run);
+    const chips = [
+        `<span class="chip pass">${c.passed} passed</span>`,
+        c.failures ? `<span class="chip fail">${c.failures} failed</span>` : '',
+        c.errors ? `<span class="chip err">${c.errors} errors</span>` : '',
+        `<span class="chip muted">${c.tests} steps &middot; ${fmtDuration(c.timeMs)}</span>`,
+    ]
+        .filter(Boolean)
+        .join('\n      ');
+    const metaBits = [
+        `<code>${htmlEsc(run.id)}</code>`,
+        htmlEsc(run.platform) + (run.device ? ` · ${htmlEsc(run.device)}` : ''),
+        `started ${htmlEsc(run.startedAt)}`,
+        run.finishedAt ? `finished ${htmlEsc(run.finishedAt)}` : '',
+        run.implicit ? 'implicit run' : '',
+    ].filter(Boolean);
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>verikun run — ${htmlEsc(run.name)}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>verikun test run — ${htmlEsc(run.name)}</h1>
+  <div class="meta">${metaBits.join(' &middot; ')}</div>
+  <div class="summary">
+      ${chips}
+  </div>
+  ${run.ai ? aiPanelHtml(run.ai) : ''}
+  <ol class="steps">
+    ${run.steps.map(stepHtml).join('\n    ')}
+  </ol>
+</div>
+</body>
+</html>
+`;
+}