@jackwener/opencli 1.7.6 → 1.7.8

package/dist/src/browser/verify-fixture.test.js

@@ -0,0 +1,161 @@
+import { describe, expect, it } from 'vitest';
+import { deriveFixture, expandFixtureArgs, validateRows } from './verify-fixture.js';
+describe('validateRows', () => {
+    it('passes when rows meet all expectations', () => {
+        const fixture = {
+            expect: {
+                rowCount: { min: 1, max: 3 },
+                columns: ['id', 'title', 'url'],
+                types: { id: 'number', title: 'string', url: 'string' },
+                patterns: { url: '^https://' },
+                notEmpty: ['title', 'url'],
+            },
+        };
+        const rows = [
+            { id: 1, title: 'a', url: 'https://x.com/a' },
+            { id: 2, title: 'b', url: 'https://x.com/b' },
+        ];
+        expect(validateRows(rows, fixture)).toEqual([]);
+    });
+    it('reports rowCount below min', () => {
+        const failures = validateRows([], { expect: { rowCount: { min: 1 } } });
+        expect(failures).toHaveLength(1);
+        expect(failures[0]).toMatchObject({ rule: 'rowCount' });
+        expect(failures[0].detail).toContain('at least 1');
+    });
+    it('reports rowCount above max', () => {
+        const failures = validateRows([{}, {}, {}, {}], { expect: { rowCount: { max: 3 } } });
+        expect(failures).toHaveLength(1);
+        expect(failures[0].detail).toContain('at most 3');
+    });
+    it('reports missing columns per row', () => {
+        const failures = validateRows([{ a: 1 }, { a: 2, b: 3 }], { expect: { columns: ['a', 'b'] } });
+        // row 0 missing 'b', row 1 complete
+        expect(failures).toEqual([
+            { rule: 'column', detail: 'missing column "b"', rowIndex: 0 },
+        ]);
+    });
+    it('reports type mismatch including null', () => {
+        const failures = validateRows([{ a: 'abc' }, { a: null }, { a: 42 }], { expect: { types: { a: 'string' } } });
+        // row 0 string ok, row 1 null fail, row 2 number fail
+        expect(failures).toHaveLength(2);
+        expect(failures[0].rowIndex).toBe(1);
+        expect(failures[0].detail).toContain('null');
+        expect(failures[1].rowIndex).toBe(2);
+        expect(failures[1].detail).toContain('number');
+    });
+    it('accepts union types like "number|string"', () => {
+        const failures = validateRows([{ id: 1 }, { id: 'abc' }], { expect: { types: { id: 'number|string' } } });
+        expect(failures).toEqual([]);
+    });
+    it('accepts "any" as wildcard type', () => {
+        const failures = validateRows([{ v: 1 }, { v: 'x' }, { v: null }, { v: [1, 2] }], { expect: { types: { v: 'any' } } });
+        expect(failures).toEqual([]);
+    });
+    it('reports pattern mismatch with row index and truncated value', () => {
+        const failures = validateRows([{ url: 'https://ok.com' }, { url: 'not-a-url' }], { expect: { patterns: { url: '^https?://' } } });
+        expect(failures).toHaveLength(1);
+        expect(failures[0]).toMatchObject({ rule: 'pattern', rowIndex: 1 });
+        expect(failures[0].detail).toContain('not-a-url');
+    });
+    it('skips pattern check for null/undefined values', () => {
+        const failures = validateRows([{ url: null }, { url: undefined }], { expect: { patterns: { url: '^x' } } });
+        expect(failures).toEqual([]);
+    });
+    it('reports invalid regex without crashing', () => {
+        const failures = validateRows([{ a: 'x' }], { expect: { patterns: { a: '[unclosed' } } });
+        expect(failures.some((f) => f.rule === 'pattern' && f.detail.includes('invalid'))).toBe(true);
+    });
+    it('treats empty/whitespace/null as failing notEmpty', () => {
+        const failures = validateRows([{ t: '' }, { t: '   ' }, { t: null }, { t: 'ok' }], { expect: { notEmpty: ['t'] } });
+        expect(failures).toHaveLength(3);
+        expect(failures.map((f) => f.rowIndex)).toEqual([0, 1, 2]);
+    });
+    it('no failures when fixture has no expect block', () => {
+        expect(validateRows([{ anything: 1 }], {})).toEqual([]);
+    });
+    it('mustNotContain flags substring bleed in columns', () => {
+        const failures = validateRows([
+            { description: 'Lead engineer, 5 years exp. address: Shanghai. category: IT' },
+            { description: 'Clean text.' },
+        ], {
+            expect: {
+                mustNotContain: { description: ['address:', 'category:'] },
+            },
+        });
+        expect(failures).toHaveLength(2);
+        expect(failures.every((f) => f.rule === 'mustNotContain')).toBe(true);
+        expect(failures.every((f) => f.rowIndex === 0)).toBe(true);
+    });
+    it('mustNotContain skips null/undefined values', () => {
+        const failures = validateRows([{ description: null }, { description: undefined }], { expect: { mustNotContain: { description: ['x'] } } });
+        expect(failures).toEqual([]);
+    });
+    it('mustBeTruthy catches silent 0 / false / "" fallbacks', () => {
+        const failures = validateRows([{ count: 10 }, { count: 0 }, { count: false }, { count: '' }, { count: null }], { expect: { mustBeTruthy: ['count'] } });
+        expect(failures).toHaveLength(4);
+        expect(failures.every((f) => f.rule === 'mustBeTruthy')).toBe(true);
+        expect(failures.map((f) => f.rowIndex)).toEqual([1, 2, 3, 4]);
+    });
+});
+describe('deriveFixture', () => {
+    it('returns rowCount.min=0 when rows are empty', () => {
+        expect(deriveFixture([])).toEqual({ expect: { rowCount: { min: 0 } } });
+    });
+    it('extracts columns from first row and infers types per column', () => {
+        const fixture = deriveFixture([
+            { id: 1, title: 'a', url: 'https://x' },
+            { id: 2, title: 'b', url: 'https://y' },
+        ]);
+        expect(fixture.expect?.columns).toEqual(['id', 'title', 'url']);
+        expect(fixture.expect?.types).toEqual({
+            id: 'number',
+            title: 'string',
+            url: 'string',
+        });
+        expect(fixture.expect?.rowCount).toEqual({ min: 1 });
+    });
+    it('unions mixed types across rows as "a|b"', () => {
+        const fixture = deriveFixture([
+            { v: 1 },
+            { v: 'two' },
+            { v: null },
+        ]);
+        expect(fixture.expect?.types?.v).toBe('null|number|string');
+    });
+    it('embeds args when provided', () => {
+        const fixture = deriveFixture([{ x: 1 }], { limit: 5 });
+        expect(fixture.args).toEqual({ limit: 5 });
+    });
+    it('embeds positional argv array when provided', () => {
+        const fixture = deriveFixture([{ x: 1 }], ['123', '--limit', '3']);
+        expect(fixture.args).toEqual(['123', '--limit', '3']);
+    });
+    it('does not add patterns or notEmpty automatically', () => {
+        const fixture = deriveFixture([{ a: 'x' }]);
+        expect(fixture.expect?.patterns).toBeUndefined();
+        expect(fixture.expect?.notEmpty).toBeUndefined();
+    });
+});
+describe('expandFixtureArgs', () => {
+    it('returns [] for undefined', () => {
+        expect(expandFixtureArgs(undefined)).toEqual([]);
+    });
+    it('expands object form as --key value pairs', () => {
+        expect(expandFixtureArgs({ limit: 3, sort: 'hot' })).toEqual(['--limit', '3', '--sort', 'hot']);
+    });
+    it('passes array form verbatim, stringifying values', () => {
+        expect(expandFixtureArgs(['123456', '--limit', 3])).toEqual(['123456', '--limit', '3']);
+    });
+    it('handles empty object and empty array', () => {
+        expect(expandFixtureArgs({})).toEqual([]);
+        expect(expandFixtureArgs([])).toEqual([]);
+    });
+    it('preserves positional + flag mix (e.g. <tid> --limit 3)', () => {
+        expect(expandFixtureArgs(['https://example.com/thread-1', '--comments', '5'])).toEqual([
+            'https://example.com/thread-1',
+            '--comments',
+            '5',
+        ]);
+    });
+});

package/dist/src/cli.d.ts

@@ -6,6 +6,38 @@
  */
 import { Command } from 'commander';
 import { findPackageRoot } from './package-paths.js';
+/**
+ * Check whether the site-memory scaffolding exists under
+ * ~/.opencli/sites/<site>/. Agents have a strong tendency to forget to write
+ * endpoints.json / notes.md after a successful verify, which dooms the next
+ * agent to redo recon from scratch. Surfacing the current state as part of
+ * verify's final report converts that "silent skip" into a visible nudge;
+ * `--strict-memory` escalates it to a failure so agents driving a hardened
+ * workflow can't forget.
+ */
+export type SiteMemoryReport = {
+    ok: boolean;
+    siteDir: string;
+    endpoints: {
+        present: boolean;
+        count: number;
+        path: string;
+    };
+    notes: {
+        present: boolean;
+        path: string;
+    };
+};
+export declare function checkSiteMemory(site: string): SiteMemoryReport;
+export declare function printSiteMemoryReport(report: SiteMemoryReport, strict: boolean | undefined): void;
+/** Coerce adapter JSON output into a row array. Accepts `[{...}]`, single `{}`, or `{items:[...]}`-style envelopes. */
+export declare function normalizeVerifyRows(data: unknown): Record<string, unknown>[];
+/** Render up to 10 rows as a compact padded table for eyeball inspection during verify. */
+export declare function renderVerifyPreview(rows: Record<string, unknown>[], opts?: {
+    maxRows?: number;
+    maxCols?: number;
+    cellMax?: number;
+}): string;
 export declare function createProgram(BUILTIN_CLIS: string, USER_CLIS: string): Command;
 export declare function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void;
 export interface BrowserVerifyInvocation {

package/dist/src/cli.js

@@ -28,6 +28,7 @@ import { DEFAULT_TTL_MS, findEntry, loadNetworkCache, saveNetworkCache } from '.
 import { parseFilter, shapeMatchesFilter } from './browser/shape-filter.js';
 import { buildHtmlTreeJs } from './browser/html-tree.js';
 import { buildExtractHtmlJs, runExtractFromHtml } from './browser/extract.js';
+import { analyzeSite } from './browser/analyze.js';
 import { daemonStatus, daemonStop } from './commands/daemon.js';
 import { log } from './logger.js';
 const CLI_FILE = fileURLToPath(import.meta.url);
@@ -43,38 +44,42 @@ const BROWSER_TAB_OPTION_DESCRIPTION = 'Target tab/page identity returned by "br
 async function captureNetworkItems(page) {
     if (page.readNetworkCapture) {
         const raw = await page.readNetworkCapture();
-        return raw.map((e) => {
-            const preview = e.responsePreview ?? null;
-            let body = null;
-            if (preview) {
-                try {
-                    body = JSON.parse(preview);
-                }
-                catch {
-                    body = preview;
+        if (Array.isArray(raw) && raw.length > 0) {
+            return raw.map((e) => {
+                const preview = e.responsePreview ?? null;
+                let body = null;
+                if (preview) {
+                    try {
+                        body = JSON.parse(preview);
+                    }
+                    catch {
+                        body = preview;
+                    }
                 }
-            }
-            const fullSize = typeof e.responseBodyFullSize === 'number'
-                ? e.responseBodyFullSize
-                : (preview ? preview.length : 0);
-            const truncated = e.responseBodyTruncated === true;
-            return {
-                url: e.url || '',
-                method: e.method || 'GET',
-                status: e.responseStatus || 0,
-                size: fullSize,
-                ct: e.responseContentType || '',
-                body,
-                bodyFullSize: fullSize,
-                bodyTruncated: truncated,
-            };
-        });
+                const fullSize = typeof e.responseBodyFullSize === 'number'
+                    ? e.responseBodyFullSize
+                    : (preview ? preview.length : 0);
+                const truncated = e.responseBodyTruncated === true;
+                return {
+                    url: e.url || '',
+                    method: e.method || 'GET',
+                    status: e.responseStatus || 0,
+                    size: fullSize,
+                    ct: e.responseContentType || '',
+                    body,
+                    bodyFullSize: fullSize,
+                    bodyTruncated: truncated,
+                };
+            });
+        }
     }
-    const raw = await page.evaluate(`(function(){ return JSON.stringify(window.__opencli_net || []); })()`);
+    const raw = await page.evaluate(`(function(){ var out = window.__opencli_net || []; window.__opencli_net = []; return JSON.stringify(out); })()`);
     try {
         return JSON.parse(raw);
     }
     catch {
+        if (process.env.OPENCLI_VERBOSE)
+            log.warn(`[network] Failed to parse interceptor buffer: ${typeof raw === 'string' ? raw.slice(0, 200) : String(raw)}`);
         return [];
     }
 }
@@ -84,10 +89,108 @@ function filterNetworkItems(items) {
         !/\.(js|css|png|jpg|gif|svg|woff|ico|map)(\?|$)/i.test(r.url) &&
         !/analytics|tracking|telemetry|beacon|pixel|gtag|fbevents/i.test(r.url));
 }
+/** Exit codes by network error code — usage errors vs runtime failures. */
+const NETWORK_ERROR_EXIT = {
+    invalid_args: EXIT_CODES.USAGE_ERROR,
+    invalid_filter: EXIT_CODES.USAGE_ERROR,
+    invalid_max_body: EXIT_CODES.USAGE_ERROR,
+};
 /** Emit a structured error JSON so agents can branch on `error.code` without regex. */
 function emitNetworkError(code, message, extra = {}) {
     console.log(JSON.stringify({ error: { code, message, ...extra } }, null, 2));
-    process.exitCode = EXIT_CODES.USAGE_ERROR;
+    process.exitCode = NETWORK_ERROR_EXIT[code] ?? EXIT_CODES.GENERIC_ERROR;
+}
+export function checkSiteMemory(site) {
+    const siteDir = path.join(os.homedir(), '.opencli', 'sites', site);
+    const endpointsPath = path.join(siteDir, 'endpoints.json');
+    const notesPath = path.join(siteDir, 'notes.md');
+    let endpointsCount = 0;
+    let endpointsPresent = fs.existsSync(endpointsPath);
+    if (endpointsPresent) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(endpointsPath, 'utf-8'));
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                endpointsCount = Object.keys(parsed).length;
+            }
+            else if (Array.isArray(parsed)) {
+                endpointsCount = parsed.length;
+            }
+        }
+        catch {
+            endpointsPresent = false;
+        }
+    }
+    const notesPresent = fs.existsSync(notesPath);
+    return {
+        ok: endpointsPresent && endpointsCount > 0 && notesPresent,
+        siteDir,
+        endpoints: { present: endpointsPresent, count: endpointsCount, path: endpointsPath },
+        notes: { present: notesPresent, path: notesPath },
+    };
+}
+export function printSiteMemoryReport(report, strict) {
+    if (report.ok) {
+        console.log(`  ✓ Memory: endpoints.json (${report.endpoints.count}), notes.md present at ${report.siteDir}`);
+        return;
+    }
+    const marker = strict ? '✗' : '⚠';
+    const missing = [];
+    if (!report.endpoints.present)
+        missing.push('endpoints.json');
+    else if (report.endpoints.count === 0)
+        missing.push('endpoints.json (empty)');
+    if (!report.notes.present)
+        missing.push('notes.md');
+    console.log(`  ${marker} Memory: missing ${missing.join(', ')} under ${report.siteDir}`);
+    console.log(`    Write the endpoint you just verified + a 1-line session note so the next agent starts from minute 0, not minute 95.`);
+    if (!strict) {
+        console.log(`    (Re-run with --strict-memory to fail instead of warn.)`);
+    }
+}
+/** Coerce adapter JSON output into a row array. Accepts `[{...}]`, single `{}`, or `{items:[...]}`-style envelopes. */
+export function normalizeVerifyRows(data) {
+    if (Array.isArray(data)) {
+        return data.map((r) => (r && typeof r === 'object' ? r : { value: r }));
+    }
+    if (data && typeof data === 'object') {
+        const obj = data;
+        for (const k of ['rows', 'items', 'data', 'results']) {
+            if (Array.isArray(obj[k])) {
+                return obj[k].map((r) => (r && typeof r === 'object' ? r : { value: r }));
+            }
+        }
+        return [obj];
+    }
+    return [];
+}
+/** Render up to 10 rows as a compact padded table for eyeball inspection during verify. */
+export function renderVerifyPreview(rows, opts = {}) {
+    const maxRows = opts.maxRows ?? 10;
+    const maxCols = opts.maxCols ?? 6;
+    const cellMax = opts.cellMax ?? 40;
+    if (rows.length === 0)
+        return '  (no rows)';
+    const allCols = Array.from(new Set(rows.flatMap((r) => Object.keys(r))));
+    const cols = allCols.slice(0, maxCols);
+    const shown = rows.slice(0, maxRows);
+    const cellOf = (v) => {
+        if (v === null || v === undefined)
+            return '';
+        const s = typeof v === 'object' ? JSON.stringify(v) : String(v);
+        return s.replace(/\s+/g, ' ').slice(0, cellMax);
+    };
+    const widths = cols.map((c) => Math.max(c.length, ...shown.map((r) => cellOf(r[c]).length)));
+    const fmtRow = (vals) => vals.map((v, i) => v.padEnd(widths[i])).join('  ');
+    const out = [];
+    out.push(`  ${fmtRow(cols)}`);
+    out.push(`  ${widths.map((w) => '-'.repeat(w)).join('  ')}`);
+    for (const r of shown)
+        out.push(`  ${fmtRow(cols.map((c) => cellOf(r[c])))}`);
+    if (rows.length > maxRows)
+        out.push(`  ... and ${rows.length - maxRows} more row(s)`);
+    if (allCols.length > maxCols)
+        out.push(`  (${allCols.length - maxCols} more column(s) hidden)`);
+    return out.join('\n');
 }
 function getBrowserCacheDir() {
     return process.env.OPENCLI_CACHE_DIR || path.join(os.homedir(), '.opencli', 'cache');
@@ -521,6 +624,73 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             console.log(await page.screenshot({ format: 'png' }));
         }
     }));
+    // ── Analyze (site recon, agent-native) ──
+    //
+    // Mechanizes the `site-recon.md` decision tree into one CLI call. The agent
+    // calls `browser analyze <url>` and gets back:
+    //
+    //   - pattern: A/B/C/D (mapped from network + SSR-globals signals)
+    //   - anti_bot: vendor + evidence + the one-liner for "what to do next"
+    //   - initial_state: which window globals are populated
+    //   - nearest_adapter: existing commands for the same site, if any
+    //   - recommended_next_step: a single imperative sentence
+    //
+    // Intent: replace the "open → eyeball network → curl → WAF → try again"
+    // feedback loop with a single deterministic verdict. Without this, agents
+    // burn ~20min per WAF-protected site re-discovering anti-bot posture.
+    addBrowserTabOption(browser.command('analyze').argument('<url>'))
+        .description('Classify site: anti-bot vendor, pattern (A/B/C/D), nearest adapter, recommended next step')
+        .action(browserAction(async (page, url) => {
+        const hasSessionCapture = await page.startNetworkCapture?.() ?? false;
+        await page.goto(url);
+        await page.wait(2);
+        if (!hasSessionCapture) {
+            try {
+                await page.evaluate(NETWORK_INTERCEPTOR_JS);
+            }
+            catch { /* non-fatal */ }
+        }
+        await captureNetworkItems(page);
+        // Best-effort: give the page another beat so XHR after DOMContentLoaded lands.
+        await page.wait(1);
+        const rawItems = await captureNetworkItems(page);
+        const networkEntries = rawItems.map((e) => ({
+            url: e.url,
+            status: e.status,
+            contentType: e.ct,
+            bodyPreview: typeof e.body === 'string'
+                ? e.body.slice(0, 2000)
+                : (e.body ? JSON.stringify(e.body).slice(0, 2000) : null),
+        }));
+        const probeJs = `(function(){
+        return {
+          cookieNames: (document.cookie || '').split(';').map(function(c){ return c.trim().split('=')[0]; }).filter(Boolean),
+          initialState: {
+            __INITIAL_STATE__: typeof window.__INITIAL_STATE__ !== 'undefined',
+            __NUXT__: typeof window.__NUXT__ !== 'undefined',
+            __NEXT_DATA__: typeof window.__NEXT_DATA__ !== 'undefined',
+            __APOLLO_STATE__: typeof window.__APOLLO_STATE__ !== 'undefined',
+          },
+          title: document.title || '',
+          finalUrl: location.href,
+        };
+      })()`;
+        const probe = await page.evaluate(probeJs);
+        const browserCookieNames = (await page.getCookies({ url: probe.finalUrl || url }).catch(() => []))
+            .map((c) => c.name)
+            .filter(Boolean);
+        const cookieNames = [...new Set([...probe.cookieNames, ...browserCookieNames])];
+        const signals = {
+            requestedUrl: url,
+            finalUrl: probe.finalUrl,
+            cookieNames,
+            networkEntries,
+            initialState: probe.initialState,
+            title: probe.title,
+        };
+        const report = analyzeSite(signals, getRegistry());
+        console.log(JSON.stringify(report, null, 2));
+    }));
     // ── Find (structured CSS query, agent-native) ──
     //
     // `browser find --css <sel>` lets agents jump straight from a semantic
@@ -850,10 +1020,10 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     }));
     // ── Wait commands ──
     addBrowserTabOption(browser.command('wait'))
-        .argument('<type>', 'selector, text, or time')
-        .argument('[value]', 'CSS selector, text string, or seconds')
+        .argument('<type>', 'selector, text, time, or xhr')
+        .argument('[value]', 'CSS selector, text string, seconds, or XHR URL regex')
         .option('--timeout <ms>', 'Timeout in milliseconds', '10000')
-        .description('Wait for selector, text, or time (e.g. wait selector ".loaded", wait text "Success", wait time 3)')
+        .description('Wait for selector, text, time, or matching XHR (e.g. wait selector ".loaded", wait text "Success", wait time 3, wait xhr "/api/search")')
         .action(browserAction(async (page, type, value, opts) => {
         const timeout = parseInt(opts.timeout, 10);
         if (type === 'time') {
@@ -879,8 +1049,59 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             await page.wait({ text: value, timeout: timeout / 1000 });
             console.log(`Text "${value}" appeared`);
         }
+        else if (type === 'xhr') {
+            // Poll the capture ring until an entry matches the URL regex — turns
+            // the common "open page, wait N seconds, hope the data landed" idiom
+            // into a deterministic barrier keyed on the API the agent actually
+            // cares about. Prevents silent "empty DOM" failures on slow SPAs.
+            if (!value) {
+                console.error('Missing XHR URL regex');
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            let re;
+            try {
+                re = new RegExp(value);
+            }
+            catch (err) {
+                console.error(`Invalid regex "${value}": ${err instanceof Error ? err.message : String(err)}`);
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            const hasSessionCapture = await page.startNetworkCapture?.() ?? false;
+            if (!hasSessionCapture) {
+                try {
+                    await page.evaluate(NETWORK_INTERCEPTOR_JS);
+                }
+                catch { /* non-fatal */ }
+            }
+            await captureNetworkItems(page);
+            const deadline = Date.now() + timeout;
+            const pollMs = 400;
+            let matched = null;
+            while (Date.now() < deadline && !matched) {
+                const items = await captureNetworkItems(page);
+                matched = items.find((e) => re.test(e.url)) ?? null;
+                if (!matched)
+                    await new Promise((r) => setTimeout(r, pollMs));
+            }
+            if (!matched) {
+                console.log(JSON.stringify({
+                    error: {
+                        code: 'xhr_not_seen',
+                        message: `No captured XHR matched /${value}/ within ${timeout}ms`,
+                        hint: 'Check the pattern against `browser network` output; the endpoint may not have fired yet, or capture is disabled.',
+                    },
+                }, null, 2));
+                process.exitCode = EXIT_CODES.GENERIC_ERROR;
+                return;
+            }
+            console.log(JSON.stringify({
+                matched: { url: matched.url, status: matched.status, contentType: matched.ct },
+            }, null, 2));
+        }
         else {
-            console.error(`Unknown wait type "${type}". Use: selector, text, or time`);
+            console.error(`Unknown wait type "${type}". Use: selector, text, time, or xhr`);
             process.exitCode = EXIT_CODES.USAGE_ERROR;
         }
     }));
@@ -1212,8 +1433,12 @@ cli({
     // ── Verify (test adapter) ──
     browser.command('verify')
         .argument('<name>', 'Adapter name in site/command format (e.g. hn/top)')
-        .description('Execute an adapter and show results')
-        .action(async (name) => {
+        .option('--write-fixture', 'Write a starter fixture to ~/.opencli/sites/<site>/verify/<command>.json if none exists')
+        .option('--update-fixture', 'Overwrite an existing fixture with one derived from current output')
+        .option('--no-fixture', 'Ignore any fixture file for this run (no value-level validation)')
+        .option('--strict-memory', 'Fail (not just warn) when ~/.opencli/sites/<site>/endpoints.json or notes.md is missing')
+        .description('Execute an adapter and validate output; uses fixture at ~/.opencli/sites/<site>/verify/<cmd>.json when present')
+        .action(async (name, opts = {}) => {
         try {
             const parts = name.split('/');
             if (parts.length !== 2) {
@@ -1228,7 +1453,7 @@ cli({
                 return;
             }
             const { execFileSync } = await import('node:child_process');
-            const os = await import('node:os');
+            const { loadFixture, writeFixture, deriveFixture, validateRows, fixturePath, expandFixtureArgs } = await import('./browser/verify-fixture.js');
             const filePath = path.join(os.homedir(), '.opencli', 'clis', site, `${command}.js`);
             if (!fs.existsSync(filePath)) {
                 console.error(`Adapter not found: ${filePath}`);
@@ -1238,14 +1463,24 @@ cli({
             }
             console.log(`🔍 Verifying ${name}...\n`);
             console.log(`  Loading: ${filePath}`);
-            // Read adapter to check if it defines a 'limit' arg
+            const useFixture = opts.fixture !== false;
+            let fixture = useFixture ? loadFixture(site, command) : null;
+            // Build adapter args: fixture.args override the legacy --limit 3 heuristic.
+            //   - object form   { "limit": 3 }            → `--limit 3`
+            //   - array form    ["123", "--limit", "3"]   → verbatim (for positional subjects)
             const adapterSrc = fs.readFileSync(filePath, 'utf-8');
             const hasLimitArg = /['"]limit['"]/.test(adapterSrc);
-            const limitFlag = hasLimitArg ? ' --limit 3' : '';
-            const limitArgs = hasLimitArg ? ['--limit', '3'] : [];
+            const fixtureArgs = fixture?.args;
+            const cliArgs = expandFixtureArgs(fixtureArgs);
+            if (cliArgs.length === 0 && hasLimitArg)
+                cliArgs.push('--limit', '3');
+            const argDisplay = cliArgs.join(' ');
             const invocation = resolveBrowserVerifyInvocation();
+            // Always request JSON so we can validate structurally.
+            const execArgs = [...invocation.args, site, command, ...cliArgs, '--format', 'json'];
+            let rawJson;
             try {
-                const output = execFileSync(invocation.binary, [...invocation.args, site, command, ...limitArgs], {
+                rawJson = execFileSync(invocation.binary, execArgs, {
                     cwd: invocation.cwd,
                     timeout: 30000,
                     encoding: 'utf-8',
@@ -1253,13 +1488,9 @@ cli({
                     stdio: ['pipe', 'pipe', 'pipe'],
                     ...(invocation.shell ? { shell: true } : {}),
                 });
-                console.log(`  Executing: opencli ${site} ${command}${limitFlag}\n`);
-                console.log(output);
-                console.log(`\n  ✓ Adapter works!`);
             }
             catch (err) {
-                console.log(`  Executing: opencli ${site} ${command}${limitFlag}\n`);
-                // execFileSync attaches captured stdout/stderr on its thrown Error.
+                console.log(`  Executing: opencli ${site} ${command} ${argDisplay}\n`);
                 const execErr = err;
                 if (execErr.stdout)
                     console.log(String(execErr.stdout));
@@ -1267,7 +1498,66 @@ cli({
                     console.error(String(execErr.stderr).slice(0, 500));
                 console.log(`\n  ✗ Adapter failed. Fix the code and try again.`);
                 process.exitCode = EXIT_CODES.GENERIC_ERROR;
+                return;
+            }
+            console.log(`  Executing: opencli ${site} ${command} ${argDisplay}\n`);
+            let rows;
+            try {
+                rows = normalizeVerifyRows(JSON.parse(rawJson));
+            }
+            catch {
+                console.log(rawJson);
+                console.log('\n  ✗ Could not parse adapter output as JSON. Is `--format json` broken?');
+                process.exitCode = EXIT_CODES.GENERIC_ERROR;
+                return;
+            }
+            console.log(renderVerifyPreview(rows));
+            console.log(`\n  → ${rows.length} row${rows.length === 1 ? '' : 's'}`);
+            // ── Fixture handling ───────────────────────────────────────────
+            if (opts.writeFixture || opts.updateFixture) {
+                if (fixture && !opts.updateFixture) {
+                    console.log(`\n  Fixture already exists at ${fixturePath(site, command)}.`);
+                    console.log(`  Use --update-fixture to overwrite.`);
+                }
+                else {
+                    const seedArgs = fixtureArgs !== undefined
+                        ? fixtureArgs
+                        : (hasLimitArg ? { limit: 3 } : undefined);
+                    const derived = deriveFixture(rows, seedArgs);
+                    const p = writeFixture(site, command, derived);
+                    console.log(`\n  ${fixture ? '↻ Updated' : '✎ Wrote'} fixture: ${p}`);
+                    console.log(`  Review and hand-tune the derived expectations (add patterns / notEmpty, tighten rowCount).`);
+                    fixture = derived;
+                }
+            }
+            if (!fixture) {
+                console.log(`\n  ✓ Adapter runs. (No fixture at ${fixturePath(site, command)} — consider --write-fixture to seed one.)`);
+                const memoryReport = checkSiteMemory(site);
+                printSiteMemoryReport(memoryReport, opts.strictMemory);
+                if (!memoryReport.ok && opts.strictMemory) {
+                    process.exitCode = EXIT_CODES.GENERIC_ERROR;
+                }
+                return;
             }
+            const failures = validateRows(rows, fixture);
+            if (failures.length === 0) {
+                console.log(`\n  ✓ Adapter matches fixture (${fixturePath(site, command)}).`);
+                const memoryReport = checkSiteMemory(site);
+                printSiteMemoryReport(memoryReport, opts.strictMemory);
+                if (!memoryReport.ok && opts.strictMemory) {
+                    process.exitCode = EXIT_CODES.GENERIC_ERROR;
+                }
+                return;
+            }
+            console.log(`\n  ✗ Adapter output does not match fixture:`);
+            for (const f of failures.slice(0, 20)) {
+                const where = f.rowIndex !== undefined ? `row[${f.rowIndex}] ` : '';
+                console.log(`    - [${f.rule}] ${where}${f.detail}`);
+            }
+            if (failures.length > 20) {
+                console.log(`    ... and ${failures.length - 20} more failure(s)`);
+            }
+            process.exitCode = EXIT_CODES.GENERIC_ERROR;
         }
         catch (err) {
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);