verikun 0.5.0 → 0.7.0

package/dist/drivers/simctl.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimctlDriver = void 0;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const errors_1 = require("../errors");
+const exec_1 = require("../exec");
+const XCRUN = 'xcrun';
+function listPhysicalDevices() {
+    const r = (0, exec_1.runText)(XCRUN, ['devicectl', 'list', 'devices']);
+    if (r.code !== 0)
+        return [];
+    const lines = r.stdout.split('\n');
+    const headerIdx = lines.findIndex((l) => l.includes('Identifier'));
+    if (headerIdx < 0)
+        return [];
+    const header = lines[headerIdx];
+    const nameCol = header.indexOf('Name');
+    const hostCol = header.indexOf('Hostname');
+    const idCol = header.indexOf('Identifier');
+    const stateCol = header.indexOf('State');
+    const modelCol = header.indexOf('Model');
+    const devices = [];
+    for (const line of lines.slice(headerIdx + 2)) {
+        if (!line.trim() || line.startsWith('-'))
+            continue;
+        const identifier = line.slice(idCol, stateCol).trim();
+        const state = line.slice(stateCol, modelCol).trim();
+        const name = line.slice(nameCol, hostCol).trim();
+        const model = line.slice(modelCol).trim();
+        if (!identifier)
+            continue;
+        const productMatch = model.match(/\(([^)]+)\)$/);
+        devices.push({
+            serial: identifier,
+            state,
+            model: name,
+            product: productMatch?.[1],
+            platform: 'ios',
+            note: 'physical — screenshot only, tap/ui not supported',
+        });
+    }
+    return devices;
+}
+// iOS support is intentionally partial. `simctl` covers screenshots, launch,
+// and stop. Full interaction (tap, swipe, type) and the accessibility hierarchy
+// require WebDriverAgent (https://github.com/appium/WebDriverAgent) — the
+// planned next step. WDA is an open-source XCTest HTTP server: build it once
+// in Xcode, sign it with your Apple developer certificate, and run it on the
+// target device or simulator. No Python required; works on both simulators and
+// physical devices. The Driver seam is already in place so the command layer
+// won't change when WDA support is added.
+function notSupported(feature) {
+    throw new errors_1.CliError(`iOS ${feature} is not supported yet.\n` +
+        'Screenshots, launch, and stop work today via xcrun simctl.\n' +
+        'Full interaction (tap / swipe / type) and UI hierarchy inspection are planned\n' +
+        'via WebDriverAgent — build it once in Xcode and vk will drive it over HTTP.\n' +
+        'See: https://github.com/appium/WebDriverAgent', 3);
+}
+class SimctlDriver {
+    platform = 'ios';
+    udid;
+    constructor(device) {
+        this.udid = device || 'booted';
+    }
+    listDevices() {
+        const devices = [];
+        // Simulators via simctl
+        const { stdout } = (0, exec_1.runText)(XCRUN, ['simctl', 'list', 'devices', 'available', '--json']);
+        try {
+            const data = JSON.parse(stdout);
+            for (const [runtime, list] of Object.entries(data.devices)) {
+                for (const d of list) {
+                    devices.push({
+                        serial: d.udid,
+                        state: d.state.toLowerCase(),
+                        model: d.name,
+                        product: runtime.split('.').pop(),
+                        platform: 'ios',
+                    });
+                }
+            }
+        }
+        catch {
+            /* tolerate unexpected simctl output */
+        }
+        // Physical devices via devicectl (Xcode 15+)
+        devices.push(...listPhysicalDevices());
+        return devices;
+    }
+    resolvedSerial() {
+        return this.udid;
+    }
+    screenshot() {
+        const tmp = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `verikun-ios-${process.pid}.png`);
+        const r = (0, exec_1.runText)(XCRUN, ['simctl', 'io', this.udid, 'screenshot', tmp]);
+        if (r.code !== 0)
+            throw new errors_1.CliError(`simctl screenshot failed: ${r.stderr.trim()}`, 3);
+        const buf = (0, node_fs_1.readFileSync)(tmp);
+        try {
+            (0, node_fs_1.unlinkSync)(tmp);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        return buf;
+    }
+    launch(appId) {
+        const r = (0, exec_1.runText)(XCRUN, ['simctl', 'launch', this.udid, appId]);
+        if (r.code !== 0)
+            throw new errors_1.CliError(`simctl launch failed: ${r.stderr.trim()}`, 3);
+    }
+    stop(appId) {
+        const r = (0, exec_1.runText)(XCRUN, ['simctl', 'terminate', this.udid, appId]);
+        if (r.code !== 0)
+            throw new errors_1.CliError(`simctl terminate failed: ${r.stderr.trim()}`, 3);
+    }
+    clearApp(appId) {
+        // simctl has no per-app data reset. The manual equivalent is to uninstall and
+        // reinstall, which also removes the app itself — so we don't do it implicitly.
+        throw new errors_1.CliError(`iOS app-data clearing is not supported yet (requested for '${appId}').\n` +
+            'simctl has no per-app data reset; uninstall + reinstall ' +
+            '(`xcrun simctl uninstall <udid> <bundleId>`) is the manual equivalent, but it removes the app too.', 3);
+    }
+    getElements() {
+        return notSupported('hierarchy inspection');
+    }
+    screenSize() {
+        return notSupported('screen size');
+    }
+    tap() {
+        notSupported('tap');
+    }
+    swipe() {
+        notSupported('swipe');
+    }
+    inputText() {
+        notSupported('text input');
+    }
+    pressKey() {
+        notSupported('key events');
+    }
+    currentApp() {
+        return notSupported('current app');
+    }
+    getLogs() {
+        // Eventually: `xcrun simctl spawn <udid> log show` (simulators) / devicectl
+        // (physical). Heavier (predicate language, large output) — deferred with WDA.
+        return notSupported('log capture');
+    }
+    deviceTime() {
+        return ''; // no log window to anchor while iOS log capture is unsupported
+    }
+}
+exports.SimctlDriver = SimctlDriver;

package/dist/report.js

@@ -1,10 +1,14 @@
 "use strict";
-// Pure report rendering: a finished RunState in -> a JUnit XML / HTML string out.
+// Pure report rendering: a finished RunState in -> a JUnit XML / HTML string out,
+// and a finished SuiteRun in -> the suite index.json / index.html 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.
+// recorder (run.ts) / suite runner (suite.ts) own all the I/O. The RunState data
+// model lives in run.ts; we import the types only.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toJUnitXml = toJUnitXml;
+exports.suiteTotals = suiteTotals;
+exports.toSuiteIndexJson = toSuiteIndexJson;
+exports.toSuiteHtml = toSuiteHtml;
 exports.toHtml = toHtml;
 // --- escaping -------------------------------------------------------------
 // XML 1.0 forbids most control chars even when escaped; drop them so a stray
@@ -180,6 +184,92 @@ function stepHtml(s) {
         parts.push(`<details><summary>Device logs</summary><pre>${htmlEsc(s.logs)}</pre></details>`);
     return `<li class="step ${s.status}">${parts.join('\n    ')}</li>`;
 }
+/** Tally a suite's tests into its totals (pure; used by suite.ts and tests). */
+function suiteTotals(tests) {
+    const round = (n) => Number(n.toFixed(4));
+    return {
+        tests: tests.length,
+        passed: tests.filter((t) => t.ok).length,
+        failed: tests.filter((t) => !t.ok).length,
+        steps: tests.reduce((a, t) => a + t.steps, 0),
+        costUsd: round(tests.reduce((a, t) => a + t.costUsd, 0)),
+        durationMs: tests.reduce((a, t) => a + t.durationMs, 0),
+    };
+}
+function toSuiteIndexJson(suite) {
+    return JSON.stringify(suite, null, 2) + '\n';
+}
+const SUITE_STYLE = `
+  table.tests { width:100%; border-collapse:collapse; background:#fff; border:1px solid var(--line); border-radius:8px; overflow:hidden; }
+  table.tests th, table.tests td { text-align:left; padding:10px 12px; border-top:1px solid var(--line); font-size:13px; }
+  table.tests th { background:#eaeef2; color:var(--muted); border-top:none; font-size:12px; letter-spacing:.03em; text-transform:uppercase; }
+  table.tests td.num { text-align:right; font-variant-numeric:tabular-nums; white-space:nowrap; }
+  table.tests a { color:inherit; }
+  .fail-reason { color:var(--fail); font-size:12px; margin-top:2px; }
+`;
+function suiteTestRow(t, linkBase) {
+    // A test that errored before its run started (id '') has no report to link.
+    const label = t.id
+        ? `<a href="${htmlEsc(`${linkBase}runs/${encodeURIComponent(t.id)}/report.html`)}">${htmlEsc(t.name)}</a>`
+        : htmlEsc(t.name);
+    const failure = t.failure ? `<div class="fail-reason">${htmlEsc(t.failure)}</div>` : '';
+    return `  <tr>
+    <td><span class="st ${t.ok ? 'passed' : 'failed'}">${t.ok ? 'PASS' : 'FAIL'}</span></td>
+    <td>${label}${failure}</td>
+    <td class="num">${t.passedSteps}/${t.steps}${t.failedSteps ? ` (${t.failedSteps} failed)` : ''}</td>
+    <td class="num">${t.modelRepairs || ''}</td>
+    <td class="num">$${t.costUsd.toFixed(4)}</td>
+    <td class="num">${fmtDuration(t.durationMs)}</td>
+  </tr>`;
+}
+/**
+ * The suite overview page. `linkBase` is the relative path from index.html to the
+ * directory holding `runs/<id>/report.html` — '../../' when the suite lives at
+ * .verikun/suites/<id>/ and runs at .verikun/runs/<id>/ (the default layout).
+ */
+function toSuiteHtml(suite, opts = {}) {
+    const linkBase = opts.linkBase ?? '../../';
+    const t = suite.totals;
+    const chips = [
+        `<span class="chip pass">${t.passed} passed</span>`,
+        t.failed ? `<span class="chip fail">${t.failed} failed</span>` : '',
+        `<span class="chip muted">${t.tests} tests &middot; ${t.steps} steps &middot; ${fmtDuration(t.durationMs)} &middot; $${t.costUsd.toFixed(4)}</span>`,
+    ]
+        .filter(Boolean)
+        .join('\n      ');
+    const metaBits = [
+        `<code>${htmlEsc(suite.id)}</code>`,
+        htmlEsc(suite.platform) + (suite.device ? ` · ${htmlEsc(suite.device)}` : ''),
+        `started ${htmlEsc(suite.startedAt)}`,
+        `finished ${htmlEsc(suite.finishedAt)}`,
+        `verikun ${htmlEsc(suite.verikun)}`,
+    ].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 suite — ${htmlEsc(suite.name)}</title>
+<style>${STYLE}${SUITE_STYLE}</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>verikun test suite — ${htmlEsc(suite.name)}</h1>
+  <div class="meta">${metaBits.join(' &middot; ')}</div>
+  <div class="summary">
+      ${chips}
+  </div>
+  <table class="tests">
+    <thead><tr><th></th><th>Test</th><th>Steps</th><th>Repairs</th><th>Cost</th><th>Duration</th></tr></thead>
+    <tbody>
+${suite.tests.map((x) => suiteTestRow(x, linkBase)).join('\n')}
+    </tbody>
+  </table>
+</div>
+</body>
+</html>
+`;
+}
 function toHtml(run) {
     const c = counts(run);
     const chips = [

package/dist/rpc.js

@@ -0,0 +1,46 @@
+"use strict";
+// The remote-execution wire contract shared by `vk server` (src/server.ts) and the
+// remote backend (src/agent/remote.ts): request/response shapes plus the error codec
+// that carries a thrown error's SUBCLASS IDENTITY across the wire. The `vk ai` engine
+// decides heal-vs-terminal via `instanceof SelectorNotFoundError/AmbiguousSelectorError`
+// (agent/engine.ts), so a serialized error must rebuild into the same class — a plain
+// `{message}` would silently turn every remote selector miss into a terminal failure.
+//
+// Pure types + pure functions only: no http, no fetch, no fs — so both sides (and the
+// unit tests) can import it without dragging in transport code.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeError = describeError;
+exports.rebuildError = rebuildError;
+const errors_1 = require("./errors");
+// --- error codec ------------------------------------------------------------
+/** Serialize a thrown error for the wire, preserving what the engine needs to
+ *  tell a heal trigger from a terminal failure. */
+function describeError(e) {
+    if (e instanceof errors_1.AmbiguousSelectorError) {
+        return { kind: 'AmbiguousSelectorError', name: e.name, message: e.message, exitCode: e.exitCode, candidates: e.candidates };
+    }
+    if (e instanceof errors_1.SelectorNotFoundError) {
+        return { kind: 'SelectorNotFoundError', name: e.name, message: e.message, exitCode: e.exitCode };
+    }
+    if (e instanceof errors_1.CliError) {
+        return { kind: 'CliError', name: e.name, message: e.message, exitCode: e.exitCode };
+    }
+    return { kind: 'Error', name: e.name || 'Error', message: e.message, exitCode: 3 };
+}
+/** Rebuild the error a server serialized, restoring its class so `instanceof`
+ *  checks (and `candidates` / `exitCode`) behave as if it were thrown locally. */
+function rebuildError(d) {
+    switch (d.kind) {
+        case 'AmbiguousSelectorError':
+            return new errors_1.AmbiguousSelectorError(d.message, d.candidates ?? []);
+        case 'SelectorNotFoundError':
+            return new errors_1.SelectorNotFoundError(d.message);
+        case 'CliError':
+            return new errors_1.CliError(d.message, d.exitCode);
+        default: {
+            const e = new Error(d.message);
+            e.name = d.name || 'Error';
+            return e;
+        }
+    }
+}

package/dist/run.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Recorder = void 0;
 exports.isRecordable = isRecordable;
+exports.runId = runId;
+exports.uniqueDir = uniqueDir;
 exports.rolloverReason = rolloverReason;
 exports.stepName = stepName;
 const node_fs_1 = require("node:fs");
@@ -54,11 +56,13 @@ function saveState(dir, state) {
 function nowIso() {
     return new Date().toISOString();
 }
+/** Timestamp id used for runs — exported so `vk suite` mints suite ids the same way. */
 function runId() {
     const d = new Date();
     const p = (n) => String(n).padStart(2, '0');
     return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
 }
+/** First non-existing `<base>`, `<base>-2`, `<base>-3`, … — exported for `vk suite`. */
 function uniqueDir(base) {
     if (!(0, node_fs_1.existsSync)(base))
         return base;
@@ -155,11 +159,17 @@ class Recorder {
     dir;
     step;
     startMs;
-    constructor(state, dir, step, startMs) {
+    sink;
+    constructor(state, dir, step, startMs, 
+    /** Ephemeral mode (vk server): artifacts land here instead of on disk, and
+     *  commit() never touches ./.verikun — the step is returned to the caller
+     *  via takeEphemeral() and spliced into the CALLER's run instead. */
+    sink) {
         this.state = state;
         this.dir = dir;
         this.step = step;
         this.startMs = startMs;
+        this.sink = sink;
     }
     /**
      * Open a step for a recordable command, auto-starting an implicit run if none
@@ -234,6 +244,43 @@ class Recorder {
         };
         return new Recorder(state, dir, step, Date.now());
     }
+    /**
+     * Open a single-step recorder that never touches disk — the `vk server` path.
+     * The step (and any artifacts, e.g. failure screenshots) accumulate in memory
+     * and are handed back by takeEphemeral() for the wire; the CALLING verikun
+     * splices them into its own on-disk run via appendForeignStep. Deliberately
+     * ignores VERIKUN_NO_RUN: this is how step detail reaches the remote caller,
+     * not a local test run.
+     */
+    static beginEphemeralStep(command, positionals, flags, platform, serial) {
+        const state = {
+            id: 'ephemeral',
+            name: 'ephemeral',
+            startedAt: nowIso(),
+            updatedAt: nowIso(),
+            platform,
+            device: serial,
+            implicit: true,
+            steps: [],
+        };
+        const step = {
+            index: 0,
+            command,
+            name: stepName(command, positionals, flags),
+            startedAt: nowIso(),
+            durationMs: 0,
+            status: 'passed',
+            exitCode: 0,
+        };
+        // No dir: ephemeral recording never touches disk (activeDir() would mkdir
+        // ./.verikun as a side effect), and writeArtifact/commit divert to the sink.
+        return new Recorder(state, '', step, Date.now(), {});
+    }
+    /** The finished ephemeral step + its in-memory artifacts. Only meaningful after
+     *  finish()/finishError() on a beginEphemeralStep recorder. */
+    takeEphemeral() {
+        return { step: this.step, artifacts: this.sink ?? {} };
+    }
     /** Attach selector / heal-tier / resolved-element / message detail to the current step. */
     note(info) {
         const s = this.step;
@@ -319,11 +366,17 @@ class Recorder {
         }
     }
     writeArtifact(rel, buf) {
+        if (this.sink) {
+            this.sink[rel] = buf;
+            return;
+        }
         (0, node_fs_1.mkdirSync)((0, node_path_1.join)(this.dir, 'artifacts'), { recursive: true });
         (0, node_fs_1.writeFileSync)((0, node_path_1.join)(this.dir, rel), buf);
     }
     commit() {
         this.step.durationMs = Date.now() - this.startMs;
+        if (this.sink)
+            return; // ephemeral: the step goes to the wire, not to disk
         this.state.steps.push(this.step);
         this.state.updatedAt = nowIso();
         saveState(this.dir, this.state);
@@ -364,6 +417,53 @@ class Recorder {
         Object.assign(state, patch);
         saveState(dir, state);
     }
+    /**
+     * Splice a step another verikun produced (a `vk server`'s ephemeral step) into
+     * the ACTIVE local run, so a remote `vk ai` run archives a report identical to
+     * a local one. Re-indexes the step, writes its artifact buffers under the new
+     * index, and rewrites the step's artifact references to match. Creates an
+     * implicit run first if none is active (parity with beginStep's auto-start).
+     */
+    static appendForeignStep(step, artifacts = {}, ctx = {}) {
+        if (process.env.VERIKUN_NO_RUN)
+            return;
+        const dir = activeDir();
+        let state = loadState(dir);
+        if (!state) {
+            state = {
+                id: runId(),
+                name: 'run',
+                startedAt: nowIso(),
+                updatedAt: nowIso(),
+                platform: ctx.platform ?? 'android',
+                device: ctx.device,
+                session: currentSession(),
+                implicit: true,
+                steps: [],
+            };
+            (0, output_1.err)('[verikun] recording test run (implicit) — archive: `vk run archive` · discard: `vk run clear`');
+        }
+        const index = state.steps.length;
+        const spliced = { ...step, index };
+        for (const [rel, buf] of Object.entries(artifacts)) {
+            // The rel path comes from the (authenticated) server's response; still, never
+            // let it steer the write outside the run's artifacts/ directory.
+            if (!/^artifacts\/[A-Za-z0-9._-]+$/.test(rel)) {
+                (0, output_1.err)(`[verikun] skipping remote artifact with unexpected path '${rel}'`);
+                continue;
+            }
+            const newRel = rel.replace(/\bstep-\d+-/, `step-${index}-`);
+            (0, node_fs_1.mkdirSync)((0, node_path_1.join)(dir, 'artifacts'), { recursive: true });
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, newRel), buf);
+            if (spliced.image === rel)
+                spliced.image = newRel;
+            if (spliced.failImage === rel)
+                spliced.failImage = newRel;
+        }
+        state.steps.push(spliced);
+        state.updatedAt = nowIso();
+        saveState(dir, state);
+    }
     /** Downgrade the most-recently-recorded step from a failed attempt to a healed
      *  pass — the `vk ai` engine calls this after a successful repair so a
      *  self-healed leaf does not count as a failure (and the run that the engine