argus-reviewer-e2e 0.1.2

package/dist/api.d.ts

@@ -0,0 +1,121 @@
+import { BrowserDriver } from './driver/browser.js';
+import { VisionClient } from './engine/loop.js';
+import { AssertionResult } from './engine/prompts.js';
+import { FingerprintRecord } from './cache/fingerprint.js';
+import { Ledger, LedgerState } from './vision/ledger.js';
+import { Config, defineConfig } from './config.js';
+import { ErrorRecord } from './journal/schema.js';
+import { Logger } from './log.js';
+export { defineConfig };
+/**
+ * Test-facing API (R13). Test files are plain TypeScript using a `td` object:
+ *
+ *   test('landing', async (td) => {
+ *     await td.find('the "See pricing" button').click()
+ *     await td.type('user@example.com')
+ *     await td.pressKeys(['tab'])
+ *     const ok = await td.assert('The pricing section is visible')
+ *   })
+ *
+ * `td` calls resolve elements through the engine's fingerprint cache — a
+ * cache hit costs zero vision calls, a miss grounds (or heals) via the model.
+ */
+export interface TypeOptions {
+    /**
+     * When true, `text` is a secret name: the typed value comes from
+     * `config.secrets[name]` (or the `name` environment variable) and is never
+     * sent to the model. The model only resolves which field receives it.
+     */
+    secret?: boolean;
+}
+export interface TdHandle {
+    click(): Promise<void>;
+    doubleClick(): Promise<void>;
+}
+export interface Td {
+    find(description: string): TdHandle;
+    type(text: string, options?: TypeOptions): Promise<void>;
+    pressKeys(keys: string[]): Promise<void>;
+    assert(question: string): Promise<AssertionResult>;
+    wait(ms: number): Promise<void>;
+    scroll(dx: number, dy: number): Promise<void>;
+}
+export interface TdStepRecord {
+    instruction: string;
+    action: string;
+    ok: boolean;
+    healed: boolean;
+    model: string | undefined;
+    reason: string | undefined;
+}
+export interface TdAssertRecord extends AssertionResult {
+    question: string;
+    cached: boolean;
+}
+export interface HealEvent {
+    instruction: string;
+    model: string | undefined;
+}
+export interface TdSessionOptions {
+    driver: BrowserDriver;
+    client: VisionClient;
+    config: Config;
+    /** Flow name used to load/save the fingerprint cache for this test. */
+    flowName?: string;
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Set by the run path when diff-aware invalidation fired — marks every
+     * loaded fingerprint `stale` so they re-ground on first use.
+     */
+    staleReason?: string;
+    logger?: Logger;
+}
+export declare function normalizeKey(key: string): string;
+/**
+ * One session per executed test. Owns the ledger + engine, replays the
+ * per-test fingerprint cache, and records steps/heals/asserts for the report.
+ */
+export declare class TdSession {
+    private readonly opts;
+    readonly td: Td;
+    readonly ledger: Ledger;
+    readonly steps: TdStepRecord[];
+    readonly asserts: TdAssertRecord[];
+    readonly healEvents: HealEvent[];
+    private readonly engine;
+    private readonly actions;
+    private readonly flow;
+    private readonly fingerprints;
+    private _failed;
+    private _failureReason;
+    private constructor();
+    static create(opts: TdSessionOptions): Promise<TdSession>;
+    get visionCalls(): number;
+    /** Non-fatal anomalies observed by the engine — journaled as evidence. */
+    get errorRecords(): ErrorRecord[];
+    get failed(): boolean;
+    get failureReason(): string | undefined;
+    get ledgerState(): LedgerState;
+    /** Persist the (possibly healed) fingerprints back to the cache (R4, R5). */
+    save(): Promise<void>;
+    private _record;
+    private _locate;
+    private _makeTd;
+}
+export interface RegisteredTest {
+    name: string;
+    fn: (td: Td) => void | Promise<void>;
+}
+/** Register a test; called by test files at import time. */
+export declare function test(name: string, fn: (td: Td) => void | Promise<void>): void;
+/** Drain the registry — the runner calls this after importing a test file. */
+export declare function takeTests(): RegisteredTest[];
+/** Bind the session the ambient `td` proxy delegates to. Internal to the runner. */
+export declare function bindSession(session: TdSession | undefined): void;
+/**
+ * Ambient `td` for test files that use top-level calls instead of `test()`.
+ * The CLI also exposes this as `globalThis.td` while importing test files.
+ */
+export declare const td: Td;
+/** Render a recorded flow as a plain-TS test file (R13). */
+export declare function renderTestFile(flowName: string, steps: FingerprintRecord[]): string;

package/dist/api.js

@@ -0,0 +1,256 @@
+import { Actions } from './engine/actions.js';
+import { Engine } from './engine/loop.js';
+import { loadFlow, saveFlow } from './cache/store.js';
+import { Ledger } from './vision/ledger.js';
+import { defineConfig } from './config.js';
+export { defineConfig };
+const KEY_ALIASES = {
+    tab: 'Tab',
+    enter: 'Enter',
+    return: 'Enter',
+    escape: 'Escape',
+    esc: 'Escape',
+    backspace: 'Backspace',
+    delete: 'Delete',
+    space: ' ',
+    up: 'ArrowUp',
+    down: 'ArrowDown',
+    left: 'ArrowLeft',
+    right: 'ArrowRight',
+    shift: 'Shift',
+    control: 'Control',
+    ctrl: 'Control',
+    alt: 'Alt',
+    meta: 'Meta',
+    cmd: 'Meta',
+    home: 'Home',
+    end: 'End',
+    pageup: 'PageUp',
+    pagedown: 'PageDown',
+};
+export function normalizeKey(key) {
+    if (key.includes('+')) {
+        return key
+            .split('+')
+            .map((part) => normalizeKey(part.trim()))
+            .join('+');
+    }
+    const lowered = key.toLowerCase();
+    const alias = KEY_ALIASES[lowered];
+    if (alias !== undefined)
+        return alias;
+    if (key.length === 1)
+        return key;
+    return key.charAt(0).toUpperCase() + key.slice(1);
+}
+/**
+ * One session per executed test. Owns the ledger + engine, replays the
+ * per-test fingerprint cache, and records steps/heals/asserts for the report.
+ */
+export class TdSession {
+    opts;
+    td;
+    ledger;
+    steps = [];
+    asserts = [];
+    healEvents = [];
+    engine;
+    actions;
+    flow;
+    fingerprints = [];
+    _failed = false;
+    _failureReason;
+    constructor(opts, flow) {
+        this.opts = opts;
+        this.flow = flow;
+        if (opts.staleReason !== undefined && flow !== undefined) {
+            const reason = opts.staleReason;
+            flow.steps = flow.steps.map((step) => ({ ...step, stale: reason }));
+        }
+        this.ledger = new Ledger(opts.config.budgetUsd);
+        this.actions = new Actions(opts.driver);
+        this.engine = new Engine({
+            driver: opts.driver,
+            actions: this.actions,
+            client: opts.client,
+            ledger: this.ledger,
+            config: opts.config,
+            ...(flow?.asserts !== undefined ? { initialAsserts: flow.asserts } : {}),
+            ...(opts.logger !== undefined ? { logger: opts.logger } : {}),
+        });
+        this.td = this._makeTd();
+    }
+    static async create(opts) {
+        const flow = opts.flowName !== undefined && opts.config.cacheDir !== undefined
+            ? await loadFlow(opts.config.cacheDir, opts.flowName)
+            : undefined;
+        return new TdSession(opts, flow);
+    }
+    get visionCalls() {
+        return this.engine.visionCalls;
+    }
+    /** Non-fatal anomalies observed by the engine — journaled as evidence. */
+    get errorRecords() {
+        return this.engine.errorRecords;
+    }
+    get failed() {
+        return this._failed;
+    }
+    get failureReason() {
+        return this._failureReason;
+    }
+    get ledgerState() {
+        return this.ledger.state;
+    }
+    /** Persist the (possibly healed) fingerprints back to the cache (R4, R5). */
+    async save() {
+        if (this.opts.flowName !== undefined && this.opts.config.cacheDir !== undefined) {
+            await saveFlow(this.opts.config.cacheDir, this.opts.flowName, this.fingerprints, this.engine.assertEntries);
+        }
+    }
+    _record(record) {
+        this.steps.push(record);
+        if (!record.ok) {
+            this._failed = true;
+            this._failureReason = record.reason ?? `${record.action} failed`;
+        }
+        if (record.healed) {
+            this.healEvents.push({ instruction: record.instruction, model: record.model });
+        }
+    }
+    async _locate(description) {
+        const index = this.fingerprints.length;
+        const cached = this.flow?.steps[index];
+        const result = await this.engine.locate(`locate: ${description}`, cached);
+        if (!result.ok || result.point === undefined || result.fingerprint === undefined) {
+            this._record({
+                instruction: description,
+                action: 'find',
+                ok: false,
+                healed: false,
+                model: result.model,
+                reason: result.reason,
+            });
+            throw new Error(`td.find("${description}") failed: ${result.reason ?? 'unknown reason'}`);
+        }
+        this.fingerprints.push(result.fingerprint);
+        this._record({
+            instruction: description,
+            action: 'find',
+            ok: true,
+            healed: result.healed,
+            model: result.model,
+            reason: undefined,
+        });
+        return result.point;
+    }
+    _makeTd() {
+        return {
+            find: (description) => ({
+                click: async () => {
+                    const point = await this._locate(description);
+                    await this.actions.click(point.x, point.y);
+                },
+                doubleClick: async () => {
+                    const point = await this._locate(description);
+                    await this.actions.doubleClick(point.x, point.y);
+                },
+            }),
+            type: async (text, options) => {
+                if (options?.secret === true) {
+                    const value = this.opts.config.secrets?.[text] ?? this.opts.env?.[text];
+                    if (value === undefined) {
+                        this._failed = true;
+                        this._failureReason = `secret "${text}" not found in config.secrets or environment`;
+                        throw new Error(this._failureReason);
+                    }
+                    // The model only picks the field; the secret value never leaves the
+                    // harness (prompt-injection mitigation).
+                    const point = await this._locate(`the "${text}" input field`);
+                    await this.actions.click(point.x, point.y);
+                    await this.actions.type(value);
+                    return;
+                }
+                await this.actions.type(text);
+            },
+            pressKeys: async (keys) => {
+                await this.actions.pressKeys(keys.map(normalizeKey));
+            },
+            assert: async (question) => {
+                const result = await this.engine.assert(question);
+                this.asserts.push({ question, ...result });
+                if (result.verdict === 'fail') {
+                    this._failed = true;
+                    this._failureReason = `assert("${question}") failed: ${result.reasoning}`;
+                }
+                return result;
+            },
+            wait: async (ms) => {
+                await this.actions.wait(ms);
+            },
+            scroll: async (dx, dy) => {
+                await this.actions.scroll(dx, dy);
+            },
+        };
+    }
+}
+const registeredTests = [];
+let currentSession;
+/** Register a test; called by test files at import time. */
+export function test(name, fn) {
+    registeredTests.push({ name, fn });
+}
+/** Drain the registry — the runner calls this after importing a test file. */
+export function takeTests() {
+    return registeredTests.splice(0, registeredTests.length);
+}
+/** Bind the session the ambient `td` proxy delegates to. Internal to the runner. */
+export function bindSession(session) {
+    currentSession = session;
+}
+function session() {
+    if (currentSession === undefined) {
+        throw new Error('td used outside an argus-reviewer run — no active session');
+    }
+    return currentSession;
+}
+/**
+ * Ambient `td` for test files that use top-level calls instead of `test()`.
+ * The CLI also exposes this as `globalThis.td` while importing test files.
+ */
+export const td = {
+    find: (description) => session().td.find(description),
+    type: (text, options) => session().td.type(text, options),
+    pressKeys: (keys) => session().td.pressKeys(keys),
+    assert: (question) => session().td.assert(question),
+    wait: (ms) => session().td.wait(ms),
+    scroll: (dx, dy) => session().td.scroll(dx, dy),
+};
+/** Render a recorded flow as a plain-TS test file (R13). */
+export function renderTestFile(flowName, steps) {
+    const lines = steps.map((step) => {
+        const instruction = JSON.stringify(step.instruction);
+        switch (step.action.action) {
+            case 'click':
+                return `  await td.find(${instruction}).click()`;
+            case 'type':
+                return `  await td.type(${JSON.stringify(step.action.text ?? '')})`;
+            case 'pressKeys':
+                return `  await td.pressKeys(${JSON.stringify(step.action.keys ?? [])})`;
+            case 'wait':
+                return `  await td.wait(${step.action.ms ?? 0})`;
+            case 'scroll':
+                return `  await td.scroll(${step.action.dx ?? 0}, ${step.action.dy ?? 0})`;
+            default:
+                return `  // TODO: unsupported recorded action ${JSON.stringify(step.action.action)}`;
+        }
+    });
+    return [
+        `// Recorded by argus-reviewer: ${flowName}`,
+        `// Run with: npx argus-reviewer run`,
+        `test(${JSON.stringify(flowName)}, async (td) => {`,
+        ...lines,
+        '})',
+        '',
+    ].join('\n');
+}

package/dist/cache/fingerprint.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Fingerprint record per KTD5: the durable, replayable identity of a single
+ * model-resolved step.  Resolve compares a freshly captured element region
+ * against the stored hash and verifies the a11y snippet is still present.
+ *
+ * The region hash is a simple 64-bit average-hash over the raw bytes of the
+ * cropped JPEG screenshot region.  It is fast, dependency-free, and stable
+ * enough for pinned-viewport fixtures.
+ */
+export interface Bbox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface ActionPayload {
+    action: 'click' | 'type' | 'pressKeys' | 'scroll' | 'wait' | 'done' | 'fail';
+    x?: number;
+    y?: number;
+    text?: string;
+    keys?: string[];
+    dx?: number;
+    dy?: number;
+    ms?: number;
+}
+export interface FingerprintRecord {
+    instruction: string;
+    action: ActionPayload;
+    bbox: Bbox;
+    clickPoint: Point;
+    model: string;
+    a11ySnippet: string;
+    regionHash: string;
+    /**
+     * Set by diff-aware invalidation before replay: the reason this entry is
+     * considered stale. Presence means "re-ground on next use" — the entry is
+     * kept for reference/heal context.
+     */
+    stale?: string;
+}
+export interface ResolveResult {
+    matched: boolean;
+    currentHash: string;
+    regionMatched: boolean;
+    a11yMatched: boolean;
+}
+export declare function computeRegionHash(buffer: Buffer, bits?: number): string;
+export declare class Fingerprint {
+    readonly record: FingerprintRecord;
+    constructor(record: FingerprintRecord);
+    resolve(regionScreenshot: Buffer, a11yYaml: string): ResolveResult;
+    mismatch(regionScreenshot: Buffer, a11yYaml: string): boolean;
+}
+/** FNV-1a 32-bit hash - stable content hash for the a11y snapshot text. */
+export declare function fnv1a(text: string): string;

package/dist/cache/fingerprint.js

@@ -0,0 +1,67 @@
+/**
+ * Fingerprint record per KTD5: the durable, replayable identity of a single
+ * model-resolved step.  Resolve compares a freshly captured element region
+ * against the stored hash and verifies the a11y snippet is still present.
+ *
+ * The region hash is a simple 64-bit average-hash over the raw bytes of the
+ * cropped JPEG screenshot region.  It is fast, dependency-free, and stable
+ * enough for pinned-viewport fixtures.
+ */
+export function computeRegionHash(buffer, bits = 64) {
+    if (buffer.length === 0) {
+        return '0'.repeat(Math.ceil(bits / 4));
+    }
+    const chunk = Math.max(1, Math.floor(buffer.length / bits));
+    const means = [];
+    let total = 0;
+    for (let i = 0; i < bits; i++) {
+        const start = i * chunk;
+        const end = Math.min(start + chunk, buffer.length);
+        let sum = 0;
+        let count = 0;
+        for (let j = start; j < end; j++) {
+            sum += buffer[j] ?? 0;
+            count++;
+        }
+        const mean = count > 0 ? sum / count : 0;
+        means.push(mean);
+        total += mean;
+    }
+    const globalMean = total / bits;
+    let hash = 0n;
+    for (let i = 0; i < bits; i++) {
+        if ((means[i] ?? 0) >= globalMean) {
+            hash |= 1n << BigInt(i);
+        }
+    }
+    return hash.toString(16).padStart(Math.ceil(bits / 4), '0');
+}
+export class Fingerprint {
+    record;
+    constructor(record) {
+        this.record = record;
+    }
+    resolve(regionScreenshot, a11yYaml) {
+        const currentHash = computeRegionHash(regionScreenshot);
+        const regionMatched = currentHash === this.record.regionHash;
+        const a11yMatched = a11yYaml.includes(this.record.a11ySnippet);
+        return {
+            matched: regionMatched && a11yMatched,
+            currentHash,
+            regionMatched,
+            a11yMatched,
+        };
+    }
+    mismatch(regionScreenshot, a11yYaml) {
+        return !this.resolve(regionScreenshot, a11yYaml).matched;
+    }
+}
+/** FNV-1a 32-bit hash - stable content hash for the a11y snapshot text. */
+export function fnv1a(text) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(16).padStart(8, '0');
+}

package/dist/cache/store.d.ts

@@ -0,0 +1,17 @@
+import { FingerprintRecord } from './fingerprint.js';
+/** A cached assertion verdict, keyed on (question, page-state hash). */
+export interface CachedAssert {
+    question: string;
+    /** FNV-1a hash of the a11y snapshot at assert time — stable across pixel noise. */
+    a11yHash: string;
+    verdict: 'pass' | 'fail';
+    reasoning: string;
+    model: string | undefined;
+}
+export interface FlowCache {
+    steps: FingerprintRecord[];
+    asserts?: CachedAssert[];
+}
+export declare function flowPath(cacheDir: string, flowName: string): string;
+export declare function loadFlow(cacheDir: string, flowName: string): Promise<FlowCache | undefined>;
+export declare function saveFlow(cacheDir: string, flowName: string, steps: FingerprintRecord[], asserts?: CachedAssert[]): Promise<void>;

package/dist/cache/store.js

@@ -0,0 +1,41 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { writeAtomicJson } from '../fsutil.js';
+function sortKeys(_, value) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+        return Object.fromEntries(entries);
+    }
+    return value;
+}
+export function flowPath(cacheDir, flowName) {
+    return join(cacheDir, `${flowName}.json`);
+}
+export async function loadFlow(cacheDir, flowName) {
+    const path = flowPath(cacheDir, flowName);
+    try {
+        const raw = await readFile(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return undefined;
+        }
+        const { steps, asserts } = parsed;
+        if (!Array.isArray(steps)) {
+            return undefined;
+        }
+        const out = { steps: steps };
+        if (Array.isArray(asserts))
+            out.asserts = asserts;
+        return out;
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'ENOENT') {
+            return undefined;
+        }
+        throw e;
+    }
+}
+export async function saveFlow(cacheDir, flowName, steps, asserts) {
+    await writeAtomicJson(flowPath(cacheDir, flowName), { steps, asserts: asserts ?? [] }, sortKeys);
+}

package/dist/cli.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { Config } from './config.js';
+import { type ExecFn } from './detect.js';
+import { BrowserDriver } from './driver/browser.js';
+import { VisionClient } from './engine/loop.js';
+export interface CliDeps {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    out?: (line: string) => void;
+    err?: (line: string) => void;
+    /** Inject a vision client (tests stub this; default builds OpenRouterClient). */
+    createClient?: (config: Config) => VisionClient;
+    /** Inject a driver factory (tests may stub browser launch). */
+    launchDriver?: (config: Config) => Promise<BrowserDriver>;
+    /** Inject a subprocess runner (tests stub `a0`/`gh` detection + delegation). */
+    exec?: ExecFn;
+}
+export declare function main(argv: string[], deps?: CliDeps): Promise<number>;
+interface PrFile {
+    filename: string;
+    previous_filename?: string;
+    patch?: string;
+}
+export declare function buildPatchChunks(files: PrFile[], contexts?: Record<string, string>): string[];
+export {};