@jackwener/opencli 1.7.5 → 1.7.6

package/dist/src/cli.test.js

@@ -2,6 +2,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { TargetError } from './browser/target-errors.js';
 const { mockBrowserConnect, mockBrowserClose, browserState, } = vi.hoisted(() => ({
     mockBrowserConnect: vi.fn(),
     mockBrowserClose: vi.fn(),
@@ -233,6 +234,799 @@ describe('browser tab targeting commands', () => {
         expect(stderrSpy.mock.calls.flat().join('\n')).toContain('Target tab tab-stale is not part of the current browser session');
     });
 });
+describe('browser network command', () => {
+    const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+    function getNetworkCachePath(cacheDir) {
+        return path.join(cacheDir, 'browser-network', 'browser_default.json');
+    }
+    function lastJsonLog() {
+        const calls = consoleLogSpy.mock.calls;
+        if (calls.length === 0)
+            throw new Error('Expected at least one console.log call');
+        const last = calls[calls.length - 1][0];
+        if (typeof last !== 'string')
+            throw new Error(`Expected string arg to console.log, got ${typeof last}`);
+        return JSON.parse(last);
+    }
+    beforeEach(() => {
+        process.exitCode = undefined;
+        process.env.OPENCLI_CACHE_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-browser-net-'));
+        consoleLogSpy.mockClear();
+        mockBrowserConnect.mockClear();
+        mockBrowserClose.mockReset().mockResolvedValue(undefined);
+        browserState.page = {
+            setActivePage: vi.fn(),
+            getActivePage: vi.fn().mockReturnValue('tab-1'),
+            tabs: vi.fn().mockResolvedValue([{ page: 'tab-1', active: true }]),
+            evaluate: vi.fn().mockResolvedValue(''),
+            readNetworkCapture: vi.fn().mockResolvedValue([
+                {
+                    url: 'https://x.com/i/api/graphql/qid/UserTweets?v=1',
+                    method: 'GET',
+                    responseStatus: 200,
+                    responseContentType: 'application/json',
+                    responsePreview: JSON.stringify({ data: { user: { rest_id: '42' } } }),
+                },
+                {
+                    url: 'https://cdn.example.com/app.js',
+                    method: 'GET',
+                    responseStatus: 200,
+                    responseContentType: 'application/javascript',
+                    responsePreview: '// js',
+                },
+            ]),
+        };
+    });
+    it('emits JSON with shape previews and persists the capture to disk', async () => {
+        const cacheDir = String(process.env.OPENCLI_CACHE_DIR);
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+        const out = lastJsonLog();
+        expect(out.count).toBe(1);
+        expect(out.filtered_out).toBe(1);
+        expect(out.entries[0].key).toBe('UserTweets');
+        expect(out.entries[0].shape['$.data.user.rest_id']).toBe('string');
+        expect(out.entries[0]).not.toHaveProperty('body');
+        expect(fs.existsSync(getNetworkCachePath(cacheDir))).toBe(true);
+    });
+    it('--all includes static resources that the default filter drops', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'network', '--all']);
+        const out = lastJsonLog();
+        expect(out.count).toBe(2);
+        expect(out.entries.map((e) => e.key)).toContain('UserTweets');
+        expect(out.entries.map((e) => e.key)).toContain('GET cdn.example.com/app.js');
+    });
+    it('--raw emits full bodies inline for every entry', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'network', '--raw']);
+        const out = lastJsonLog();
+        expect(out.entries[0].body).toEqual({ data: { user: { rest_id: '42' } } });
+    });
+    it('--detail <key> returns the full body for the requested entry', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+        consoleLogSpy.mockClear();
+        await program.parseAsync(['node', 'opencli', 'browser', 'network', '--detail', 'UserTweets']);
+        const out = lastJsonLog();
+        expect(out.key).toBe('UserTweets');
+        expect(out.body).toEqual({ data: { user: { rest_id: '42' } } });
+        expect(out.shape['$.data.user.rest_id']).toBe('string');
+    });
+    it('--detail reports key_not_found with the list of available keys', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+        consoleLogSpy.mockClear();
+        await program.parseAsync(['node', 'opencli', 'browser', 'network', '--detail', 'NopeOp']);
+        const out = lastJsonLog();
+        expect(out.error.code).toBe('key_not_found');
+        expect(out.error.available_keys).toContain('UserTweets');
+        expect(process.exitCode).toBeDefined();
+    });
+    it('--detail reports cache_missing when no capture has been persisted yet', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'network', '--detail', 'UserTweets']);
+        const out = lastJsonLog();
+        expect(out.error.code).toBe('cache_missing');
+        expect(process.exitCode).toBeDefined();
+    });
+    it('emits capture_failed when readNetworkCapture throws', async () => {
+        browserState.page.readNetworkCapture = vi.fn().mockRejectedValue(new Error('CDP disconnected'));
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+        const out = lastJsonLog();
+        expect(out.error.code).toBe('capture_failed');
+        expect(out.error.message).toContain('CDP disconnected');
+        expect(process.exitCode).toBeDefined();
+    });
+    it('surfaces cache_warning in the envelope when persistence fails', async () => {
+        const cacheDir = String(process.env.OPENCLI_CACHE_DIR);
+        // Pre-create the target path as a file where a directory is expected,
+        // forcing the mkdir inside saveNetworkCache to throw.
+        const clashDir = path.join(cacheDir, 'browser-network');
+        fs.writeFileSync(clashDir, 'not-a-directory');
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+        const out = lastJsonLog();
+        expect(out.cache_warning).toMatch(/Could not persist capture cache/);
+        expect(out.count).toBe(1);
+        expect(process.exitCode).toBeUndefined();
+    });
+    describe('--filter', () => {
+        function apiResponse(url, body) {
+            return {
+                url,
+                method: 'GET',
+                responseStatus: 200,
+                responseContentType: 'application/json',
+                responsePreview: JSON.stringify(body),
+            };
+        }
+        beforeEach(() => {
+            browserState.page.readNetworkCapture = vi.fn().mockResolvedValue([
+                apiResponse('https://x.com/i/api/graphql/qid/UserTweets?v=1', { data: { items: [{ author: 'a', text: 't', likes: 1 }] } }),
+                apiResponse('https://x.com/i/api/graphql/qid/UserProfile?v=1', { data: { user: { id: 'u1', followers: 10 } } }),
+                apiResponse('https://x.com/i/api/graphql/qid/Settings?v=1', { config: { theme: 'dark' } }),
+            ]);
+        });
+        it('narrows entries to those whose shape has ALL named fields', async () => {
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', 'author,text,likes']);
+            const out = lastJsonLog();
+            expect(out.count).toBe(1);
+            expect(out.filter).toEqual(['author', 'text', 'likes']);
+            expect(out.filter_dropped).toBe(2);
+            expect(out.entries[0].key).toBe('UserTweets');
+        });
+        it('matches container segments too, not just leaf names (any-segment rule)', async () => {
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', 'data,items']);
+            const out = lastJsonLog();
+            expect(out.count).toBe(1);
+            expect(out.entries[0].key).toBe('UserTweets');
+        });
+        it('drops entries that are missing any required field (AND semantics)', async () => {
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', 'author,followers']);
+            const out = lastJsonLog();
+            expect(out.count).toBe(0);
+            expect(out.entries).toEqual([]);
+            expect(out.filter).toEqual(['author', 'followers']);
+            expect(out.filter_dropped).toBe(3);
+        });
+        it('returns empty entries (not an error) when nothing matches', async () => {
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', 'nonexistent_field']);
+            const out = lastJsonLog();
+            expect(out.count).toBe(0);
+            expect(out.entries).toEqual([]);
+            expect(out).not.toHaveProperty('error');
+            expect(process.exitCode).toBeUndefined();
+        });
+        it('is case-sensitive so agents do not conflate `Id` with `id`', async () => {
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', 'Data']);
+            const out = lastJsonLog();
+            expect(out.count).toBe(0);
+        });
+        it('persists the full (unfiltered) capture so --detail lookups still find filtered-out keys', async () => {
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', 'author,text,likes']);
+            consoleLogSpy.mockClear();
+            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--detail', 'UserProfile']);
+            const out = lastJsonLog();
+            expect(out.key).toBe('UserProfile');
+            expect(out.body).toEqual({ data: { user: { id: 'u1', followers: 10 } } });
+        });
+        it('composes with --raw: entries keep full bodies, filter still narrows', async () => {
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', 'author', '--raw']);
+            const out = lastJsonLog();
+            expect(out.count).toBe(1);
+            expect(out.entries[0].body).toEqual({ data: { items: [{ author: 'a', text: 't', likes: 1 }] } });
+        });
+        it('reports invalid_filter for empty value', async () => {
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', '']);
+            const out = lastJsonLog();
+            expect(out.error.code).toBe('invalid_filter');
+            expect(process.exitCode).toBeDefined();
+        });
+        it('reports invalid_filter for commas-only value', async () => {
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', ',,,']);
+            const out = lastJsonLog();
+            expect(out.error.code).toBe('invalid_filter');
+            expect(process.exitCode).toBeDefined();
+        });
+        it('rejects --filter combined with --detail as invalid_args', async () => {
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--filter', 'author', '--detail', 'UserTweets']);
+            const out = lastJsonLog();
+            expect(out.error.code).toBe('invalid_args');
+            expect(out.error.message).toContain('--filter');
+            expect(out.error.message).toContain('--detail');
+            expect(process.exitCode).toBeDefined();
+        });
+    });
+    describe('body truncation signals', () => {
+        it('flags body_truncated in list view when the capture layer capped the body', async () => {
+            browserState.page.readNetworkCapture = vi.fn().mockResolvedValue([
+                {
+                    url: 'https://api.example.com/huge',
+                    method: 'GET',
+                    responseStatus: 200,
+                    responseContentType: 'application/json',
+                    responsePreview: '{"data":"x"}',
+                    responseBodyFullSize: 99_999_999,
+                    responseBodyTruncated: true,
+                },
+            ]);
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+            const out = lastJsonLog();
+            expect(out.body_truncated_count).toBe(1);
+            expect(out.entries[0].body_truncated).toBe(true);
+            expect(out.entries[0].size).toBe(99_999_999);
+        });
+        it('--detail surfaces body_truncated + body_full_size when capture had to cap the body', async () => {
+            browserState.page.readNetworkCapture = vi.fn().mockResolvedValue([
+                {
+                    url: 'https://api.example.com/huge',
+                    method: 'GET',
+                    responseStatus: 200,
+                    responseContentType: 'application/json',
+                    responsePreview: 'truncated-prefix-not-valid-json',
+                    responseBodyFullSize: 50_000_000,
+                    responseBodyTruncated: true,
+                },
+            ]);
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+            consoleLogSpy.mockClear();
+            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--detail', 'GET api.example.com/huge']);
+            const out = lastJsonLog();
+            expect(out.body_truncated).toBe(true);
+            expect(out.body_full_size).toBe(50_000_000);
+            expect(out.body_truncation_reason).toBe('capture-limit');
+        });
+        it('--max-body caps the emitted body and marks body_truncation_reason = max-body', async () => {
+            const longString = 'x'.repeat(5000);
+            browserState.page.readNetworkCapture = vi.fn().mockResolvedValue([
+                {
+                    url: 'https://api.example.com/plain',
+                    method: 'GET',
+                    responseStatus: 200,
+                    responseContentType: 'text/plain',
+                    responsePreview: longString,
+                },
+            ]);
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+            consoleLogSpy.mockClear();
+            await program.parseAsync([
+                'node', 'opencli', 'browser', 'network',
+                '--detail', 'GET api.example.com/plain',
+                '--max-body', '100',
+            ]);
+            const out = lastJsonLog();
+            expect(typeof out.body).toBe('string');
+            expect(out.body).toHaveLength(100);
+            expect(out.body_truncated).toBe(true);
+            expect(out.body_truncation_reason).toBe('max-body');
+            expect(out.body_full_size).toBe(5000);
+        });
+        it('--max-body leaves parsed JSON bodies untouched (no mid-object cut)', async () => {
+            browserState.page.readNetworkCapture = vi.fn().mockResolvedValue([
+                {
+                    url: 'https://api.example.com/json',
+                    method: 'GET',
+                    responseStatus: 200,
+                    responseContentType: 'application/json',
+                    responsePreview: JSON.stringify({ data: { user: { rest_id: 'u1' } } }),
+                },
+            ]);
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+            consoleLogSpy.mockClear();
+            await program.parseAsync([
+                'node', 'opencli', 'browser', 'network',
+                '--detail', 'GET api.example.com/json',
+                '--max-body', '10',
+            ]);
+            const out = lastJsonLog();
+            // JSON body already parsed at capture time — --max-body only applies to
+            // string bodies (which is where the agent-visible hazard lives).
+            expect(out.body).toEqual({ data: { user: { rest_id: 'u1' } } });
+            expect(out).not.toHaveProperty('body_truncated');
+        });
+        it('rejects non-numeric --max-body with invalid_max_body', async () => {
+            browserState.page.readNetworkCapture = vi.fn().mockResolvedValue([
+                {
+                    url: 'https://api.example.com/x',
+                    method: 'GET',
+                    responseStatus: 200,
+                    responseContentType: 'application/json',
+                    responsePreview: '{"a":1}',
+                },
+            ]);
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+            consoleLogSpy.mockClear();
+            await program.parseAsync([
+                'node', 'opencli', 'browser', 'network',
+                '--detail', 'GET api.example.com/x',
+                '--max-body', 'abc',
+            ]);
+            expect(lastJsonLog().error.code).toBe('invalid_max_body');
+            expect(process.exitCode).toBeDefined();
+        });
+        it('--raw emits snake_case body_truncated / body_full_size, matching non-raw + detail', async () => {
+            browserState.page.readNetworkCapture = vi.fn().mockResolvedValue([
+                {
+                    url: 'https://api.example.com/huge',
+                    method: 'GET',
+                    responseStatus: 200,
+                    responseContentType: 'application/json',
+                    responsePreview: 'truncated-prefix',
+                    responseBodyFullSize: 20_000_000,
+                    responseBodyTruncated: true,
+                },
+            ]);
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'network', '--raw']);
+            const out = lastJsonLog();
+            expect(out.entries).toHaveLength(1);
+            const entry = out.entries[0];
+            expect(entry.body_truncated).toBe(true);
+            expect(entry.body_full_size).toBe(20_000_000);
+            // Internal camelCase must not leak into the agent-facing envelope.
+            expect(entry).not.toHaveProperty('bodyTruncated');
+            expect(entry).not.toHaveProperty('bodyFullSize');
+        });
+    });
+});
+describe('browser get html command', () => {
+    const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+    function lastLogArg() {
+        const calls = consoleLogSpy.mock.calls;
+        if (calls.length === 0)
+            throw new Error('expected console.log call');
+        return calls[calls.length - 1][0];
+    }
+    function lastJsonLog() {
+        const arg = lastLogArg();
+        if (typeof arg !== 'string')
+            throw new Error(`expected string arg, got ${typeof arg}`);
+        return JSON.parse(arg);
+    }
+    beforeEach(() => {
+        process.exitCode = undefined;
+        process.env.OPENCLI_CACHE_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-html-'));
+        consoleLogSpy.mockClear();
+        mockBrowserConnect.mockClear();
+        mockBrowserClose.mockReset().mockResolvedValue(undefined);
+        browserState.page = {
+            setActivePage: vi.fn(),
+            getActivePage: vi.fn().mockReturnValue('tab-1'),
+            tabs: vi.fn().mockResolvedValue([{ page: 'tab-1', active: true }]),
+            evaluate: vi.fn(),
+        };
+    });
+    it('returns full outerHTML by default with no truncation', async () => {
+        const big = '<div>' + 'x'.repeat(100_000) + '</div>';
+        browserState.page.evaluate.mockResolvedValueOnce({ kind: 'ok', html: big });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html']);
+        expect(lastLogArg()).toBe(big);
+    });
+    it('caps output with --max and prepends a visible truncation marker', async () => {
+        const big = '<div>' + 'x'.repeat(500) + '</div>';
+        browserState.page.evaluate.mockResolvedValueOnce({ kind: 'ok', html: big });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--max', '100']);
+        const out = String(lastLogArg());
+        expect(out.startsWith('<!-- opencli: truncated 100 of')).toBe(true);
+        expect(out.length).toBeGreaterThan(100);
+        expect(out.length).toBeLessThan(big.length);
+    });
+    it('rejects negative --max with invalid_max error', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--max', '-1']);
+        expect(lastJsonLog().error.code).toBe('invalid_max');
+        expect(process.exitCode).toBeDefined();
+        expect(browserState.page.evaluate).not.toHaveBeenCalled();
+    });
+    it('rejects fractional --max with invalid_max error', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--max', '1.5']);
+        expect(lastJsonLog().error.code).toBe('invalid_max');
+        expect(process.exitCode).toBeDefined();
+        expect(browserState.page.evaluate).not.toHaveBeenCalled();
+    });
+    it('rejects non-numeric --max (e.g. "10abc") with invalid_max error', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--max', '10abc']);
+        expect(lastJsonLog().error.code).toBe('invalid_max');
+        expect(process.exitCode).toBeDefined();
+        expect(browserState.page.evaluate).not.toHaveBeenCalled();
+    });
+    it('--as json returns structured tree envelope', async () => {
+        browserState.page.evaluate.mockResolvedValueOnce({
+            selector: '.hero',
+            matched: 1,
+            tree: { tag: 'div', attrs: { class: 'hero' }, text: 'Hi', children: [] },
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--selector', '.hero', '--as', 'json']);
+        const out = lastJsonLog();
+        expect(out.matched).toBe(1);
+        expect(out.tree.tag).toBe('div');
+        expect(out.tree.attrs.class).toBe('hero');
+    });
+    it('--as json emits selector_not_found when matched is 0', async () => {
+        browserState.page.evaluate.mockResolvedValueOnce({ selector: '.missing', matched: 0, tree: null });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--selector', '.missing', '--as', 'json']);
+        expect(lastJsonLog().error.code).toBe('selector_not_found');
+        expect(process.exitCode).toBeDefined();
+    });
+    it('raw mode emits selector_not_found when the selector matches nothing', async () => {
+        browserState.page.evaluate.mockResolvedValueOnce({ kind: 'ok', html: null });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--selector', '.missing']);
+        expect(lastJsonLog().error.code).toBe('selector_not_found');
+        expect(process.exitCode).toBeDefined();
+    });
+    it('raw mode emits invalid_selector when the page rejects the selector syntax', async () => {
+        browserState.page.evaluate.mockResolvedValueOnce({
+            kind: 'invalid_selector',
+            reason: "'##$@@' is not a valid selector",
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--selector', '##$@@']);
+        const err = lastJsonLog().error;
+        expect(err.code).toBe('invalid_selector');
+        expect(err.message).toContain('##$@@');
+        expect(err.message).toContain('not a valid selector');
+        expect(process.exitCode).toBeDefined();
+    });
+    it('--as json emits invalid_selector when the page rejects the selector syntax', async () => {
+        browserState.page.evaluate.mockResolvedValueOnce({
+            selector: '##$@@',
+            invalidSelector: true,
+            reason: "'##$@@' is not a valid selector",
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--selector', '##$@@', '--as', 'json']);
+        const err = lastJsonLog().error;
+        expect(err.code).toBe('invalid_selector');
+        expect(err.message).toContain('##$@@');
+        expect(process.exitCode).toBeDefined();
+    });
+    it('rejects unknown --as format with invalid_format error', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'html', '--as', 'yaml']);
+        expect(lastJsonLog().error.code).toBe('invalid_format');
+        expect(process.exitCode).toBeDefined();
+    });
+});
+// Shared helper for the selector-first describe blocks below.
+// Each block spies console.log, mocks the IPage surface it touches, and
+// parses the last stringified call to inspect the JSON envelope — the
+// canonical agent-facing contract for the selector-first commands.
+function installSelectorFirstTestHarness(label, pageOverrides) {
+    const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+    function lastLogArg() {
+        const calls = consoleLogSpy.mock.calls;
+        if (calls.length === 0)
+            throw new Error('expected console.log call');
+        return calls[calls.length - 1][0];
+    }
+    function lastJsonLog() {
+        const arg = lastLogArg();
+        if (typeof arg !== 'string')
+            throw new Error(`expected string arg, got ${typeof arg}`);
+        return JSON.parse(arg);
+    }
+    beforeEach(() => {
+        process.exitCode = undefined;
+        process.env.OPENCLI_CACHE_DIR = fs.mkdtempSync(path.join(os.tmpdir(), `opencli-${label}-`));
+        consoleLogSpy.mockClear();
+        mockBrowserConnect.mockClear();
+        mockBrowserClose.mockReset().mockResolvedValue(undefined);
+        browserState.page = {
+            setActivePage: vi.fn(),
+            getActivePage: vi.fn().mockReturnValue('tab-1'),
+            tabs: vi.fn().mockResolvedValue([{ page: 'tab-1', active: true }]),
+            ...pageOverrides(),
+        };
+    });
+    return { lastJsonLog };
+}
+describe('browser find command', () => {
+    const { lastJsonLog } = installSelectorFirstTestHarness('find', () => ({
+        evaluate: vi.fn(),
+    }));
+    it('returns a {matches_n, entries} envelope for a matching selector', async () => {
+        // `find` always returns numeric refs (existing on snapshot-tagged elements,
+        // allocated on the spot for fresh matches) — see reviewer contract in
+        // #opencli-browser msg 52c51eb6.
+        browserState.page.evaluate.mockResolvedValueOnce({
+            matches_n: 2,
+            entries: [
+                { nth: 0, ref: 5, tag: 'button', role: '', text: 'OK', attrs: { class: 'btn' }, visible: true },
+                { nth: 1, ref: 17, tag: 'button', role: '', text: 'Cancel', attrs: { class: 'btn' }, visible: true },
+            ],
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'find', '--css', '.btn']);
+        const out = lastJsonLog();
+        expect(out.matches_n).toBe(2);
+        expect(out.entries).toHaveLength(2);
+        expect(out.entries[0].ref).toBe(5);
+        expect(out.entries[1].ref).toBe(17);
+        expect(process.exitCode).toBeUndefined();
+    });
+    it('forwards --limit / --text-max into the generated JS', async () => {
+        browserState.page.evaluate.mockResolvedValueOnce({ matches_n: 0, entries: [] });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'find', '--css', '.btn', '--limit', '3', '--text-max', '20']);
+        const js = browserState.page.evaluate.mock.calls[0][0];
+        expect(js).toContain('LIMIT = 3');
+        expect(js).toContain('TEXT_MAX = 20');
+    });
+    it('emits invalid_selector envelope when the page rejects selector syntax', async () => {
+        browserState.page.evaluate.mockResolvedValueOnce({
+            error: { code: 'invalid_selector', message: 'Invalid CSS selector: ">>>"', hint: 'Check the selector syntax.' },
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'find', '--css', '>>>']);
+        expect(lastJsonLog().error.code).toBe('invalid_selector');
+        expect(process.exitCode).toBeDefined();
+    });
+    it('emits selector_not_found envelope when the selector matches nothing', async () => {
+        browserState.page.evaluate.mockResolvedValueOnce({
+            error: { code: 'selector_not_found', message: 'CSS selector ".missing" matched 0 elements', hint: 'Use browser state to inspect the page.' },
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'find', '--css', '.missing']);
+        expect(lastJsonLog().error.code).toBe('selector_not_found');
+        expect(process.exitCode).toBeDefined();
+    });
+    it('rejects missing --css with usage_error (no evaluate call)', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'find']);
+        expect(lastJsonLog().error.code).toBe('usage_error');
+        expect(browserState.page.evaluate).not.toHaveBeenCalled();
+        expect(process.exitCode).toBeDefined();
+    });
+    it('rejects malformed --limit with usage_error (no evaluate call)', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'find', '--css', '.btn', '--limit', 'abc']);
+        expect(lastJsonLog().error.code).toBe('usage_error');
+        expect(browserState.page.evaluate).not.toHaveBeenCalled();
+        expect(process.exitCode).toBeDefined();
+    });
+});
+describe('browser get text/value/attributes commands', () => {
+    const { lastJsonLog } = installSelectorFirstTestHarness('get-sel', () => ({
+        evaluate: vi.fn(),
+    }));
+    it('emits {value, matches_n, match_level} envelope for a numeric ref', async () => {
+        const evalMock = browserState.page.evaluate;
+        // 1st call: resolveTargetJs -> { ok: true, matches_n: 1, match_level: 'exact' }
+        evalMock.mockResolvedValueOnce({ ok: true, matches_n: 1, match_level: 'exact' });
+        // 2nd call: getTextResolvedJs -> the element's text
+        evalMock.mockResolvedValueOnce('Hello world');
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'text', '7']);
+        expect(lastJsonLog()).toEqual({ value: 'Hello world', matches_n: 1, match_level: 'exact' });
+    });
+    it('reports matches_n on multi-match CSS (read path: first match wins)', async () => {
+        const evalMock = browserState.page.evaluate;
+        evalMock.mockResolvedValueOnce({ ok: true, matches_n: 3, match_level: 'exact' });
+        evalMock.mockResolvedValueOnce('first');
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'text', '.btn']);
+        expect(lastJsonLog()).toEqual({ value: 'first', matches_n: 3, match_level: 'exact' });
+    });
+    it('parses the attributes payload back into a real object', async () => {
+        const evalMock = browserState.page.evaluate;
+        evalMock.mockResolvedValueOnce({ ok: true, matches_n: 1, match_level: 'exact' });
+        // getAttributesResolvedJs returns a JSON-encoded string — the CLI must parse it
+        evalMock.mockResolvedValueOnce(JSON.stringify({ id: 'nav', class: 'hero' }));
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'attributes', '#nav']);
+        const out = lastJsonLog();
+        expect(out.matches_n).toBe(1);
+        expect(out.match_level).toBe('exact');
+        expect(out.value).toEqual({ id: 'nav', class: 'hero' });
+    });
+    it('propagates selector_not_found from the resolver as an error envelope', async () => {
+        browserState.page.evaluate.mockResolvedValueOnce({
+            ok: false,
+            code: 'selector_not_found',
+            message: 'CSS selector ".missing" matched 0 elements',
+            hint: 'Try a less specific selector.',
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'text', '.missing']);
+        expect(lastJsonLog().error.code).toBe('selector_not_found');
+        expect(process.exitCode).toBeDefined();
+    });
+    it('forwards --nth into the resolver opts and reports matches_n', async () => {
+        const evalMock = browserState.page.evaluate;
+        evalMock.mockResolvedValueOnce({ ok: true, matches_n: 4, match_level: 'exact' });
+        evalMock.mockResolvedValueOnce('second');
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'value', '.btn', '--nth', '1']);
+        const resolveJs = evalMock.mock.calls[0][0];
+        // resolveTargetJs embeds nth as a raw number literal; look for the binding
+        expect(resolveJs).toContain('const nth = 1');
+        expect(lastJsonLog()).toEqual({ value: 'second', matches_n: 4, match_level: 'exact' });
+    });
+    it('rejects malformed --nth with usage_error before touching the page', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'text', '.btn', '--nth', 'abc']);
+        expect(lastJsonLog().error.code).toBe('usage_error');
+        expect(browserState.page.evaluate).not.toHaveBeenCalled();
+        expect(process.exitCode).toBeDefined();
+    });
+});
+describe('browser click/type commands', () => {
+    const { lastJsonLog } = installSelectorFirstTestHarness('click-type', () => ({
+        evaluate: vi.fn().mockResolvedValue(false),
+        click: vi.fn().mockResolvedValue({ matches_n: 1, match_level: 'exact' }),
+        typeText: vi.fn().mockResolvedValue({ matches_n: 1, match_level: 'exact' }),
+        wait: vi.fn().mockResolvedValue(undefined),
+    }));
+    it('emits {clicked, target, matches_n, match_level} on success', async () => {
+        browserState.page.click.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'click', '#save']);
+        expect(browserState.page.click).toHaveBeenCalledWith('#save', {});
+        expect(lastJsonLog()).toEqual({ clicked: true, target: '#save', matches_n: 1, match_level: 'exact' });
+    });
+    it('surfaces match_level=stable when resolver falls back to fingerprint match', async () => {
+        browserState.page.click.mockResolvedValueOnce({ matches_n: 1, match_level: 'stable' });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'click', '7']);
+        expect(lastJsonLog()).toEqual({ clicked: true, target: '7', matches_n: 1, match_level: 'stable' });
+    });
+    it('forwards --nth as ResolveOptions.nth to page.click', async () => {
+        browserState.page.click.mockResolvedValueOnce({ matches_n: 3, match_level: 'exact' });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'click', '.btn', '--nth', '2']);
+        expect(browserState.page.click).toHaveBeenCalledWith('.btn', { nth: 2 });
+        expect(lastJsonLog()).toEqual({ clicked: true, target: '.btn', matches_n: 3, match_level: 'exact' });
+    });
+    it('surfaces selector_ambiguous from page.click as an error envelope', async () => {
+        browserState.page.click.mockRejectedValueOnce(new TargetError({
+            code: 'selector_ambiguous',
+            message: 'CSS selector ".btn" matched 3 elements; clicks require a unique target.',
+            hint: 'Pass --nth <n> to pick one (0-based).',
+            matches_n: 3,
+        }));
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'click', '.btn']);
+        const err = lastJsonLog().error;
+        expect(err.code).toBe('selector_ambiguous');
+        expect(err.matches_n).toBe(3);
+        expect(process.exitCode).toBeDefined();
+    });
+    it('surfaces selector_nth_out_of_range from page.click as an error envelope', async () => {
+        browserState.page.click.mockRejectedValueOnce(new TargetError({
+            code: 'selector_nth_out_of_range',
+            message: '--nth 99 is out of range for CSS selector ".btn" (matches_n=3).',
+            hint: 'Pick an index in [0, 2].',
+            matches_n: 3,
+        }));
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'click', '.btn', '--nth', '99']);
+        expect(lastJsonLog().error.code).toBe('selector_nth_out_of_range');
+        expect(process.exitCode).toBeDefined();
+    });
+    it('rejects malformed --nth on click with usage_error before touching the page', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'click', '.btn', '--nth', 'abc']);
+        expect(lastJsonLog().error.code).toBe('usage_error');
+        expect(browserState.page.click).not.toHaveBeenCalled();
+        expect(process.exitCode).toBeDefined();
+    });
+    it('type: clicks, waits, then typeText — emits {typed, text, target, matches_n, match_level, autocomplete}', async () => {
+        browserState.page.click.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
+        browserState.page.typeText.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
+        browserState.page.evaluate.mockResolvedValueOnce(false); // isAutocomplete
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'type', '#q', 'hello']);
+        expect(browserState.page.click).toHaveBeenCalledWith('#q', {});
+        expect(browserState.page.wait).toHaveBeenCalledWith(0.3);
+        expect(browserState.page.typeText).toHaveBeenCalledWith('#q', 'hello', {});
+        expect(lastJsonLog()).toEqual({
+            typed: true, text: 'hello', target: '#q', matches_n: 1, match_level: 'exact', autocomplete: false,
+        });
+    });
+    it('type: waits an extra 0.4s when the input reports autocomplete=true', async () => {
+        browserState.page.click.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
+        browserState.page.typeText.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
+        browserState.page.evaluate.mockResolvedValueOnce(true);
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'type', '#q', 'hi']);
+        const waitCalls = browserState.page.wait.mock.calls;
+        expect(waitCalls).toContainEqual([0.3]);
+        expect(waitCalls).toContainEqual([0.4]);
+        expect(lastJsonLog().autocomplete).toBe(true);
+        expect(lastJsonLog().match_level).toBe('exact');
+    });
+    it('type: surfaces match_level=reidentified when ref had to be reidentified by fingerprint', async () => {
+        browserState.page.click.mockResolvedValueOnce({ matches_n: 1, match_level: 'reidentified' });
+        browserState.page.typeText.mockResolvedValueOnce({ matches_n: 1, match_level: 'reidentified' });
+        browserState.page.evaluate.mockResolvedValueOnce(false);
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'type', '9', 'hi']);
+        // The typeText call is the authoritative match_level source for the `type` envelope.
+        expect(lastJsonLog().match_level).toBe('reidentified');
+    });
+    it('type: forwards --nth to both click and typeText', async () => {
+        browserState.page.click.mockResolvedValueOnce({ matches_n: 5, match_level: 'exact' });
+        browserState.page.typeText.mockResolvedValueOnce({ matches_n: 5, match_level: 'exact' });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'type', '.field', 'x', '--nth', '3']);
+        expect(browserState.page.click).toHaveBeenCalledWith('.field', { nth: 3 });
+        expect(browserState.page.typeText).toHaveBeenCalledWith('.field', 'x', { nth: 3 });
+    });
+});
+describe('browser select command', () => {
+    const { lastJsonLog } = installSelectorFirstTestHarness('select', () => ({
+        evaluate: vi.fn(),
+    }));
+    it('emits {selected, target, matches_n, match_level} on success', async () => {
+        const evalMock = browserState.page.evaluate;
+        evalMock.mockResolvedValueOnce({ ok: true, matches_n: 1, match_level: 'exact' });
+        evalMock.mockResolvedValueOnce({ selected: 'US' });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'select', '#country', 'US']);
+        expect(lastJsonLog()).toEqual({ selected: 'US', target: '#country', matches_n: 1, match_level: 'exact' });
+    });
+    it('maps "Not a <select>" to a not_a_select error envelope', async () => {
+        const evalMock = browserState.page.evaluate;
+        evalMock.mockResolvedValueOnce({ ok: true, matches_n: 1, match_level: 'exact' });
+        evalMock.mockResolvedValueOnce({ error: 'Not a <select>' });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'select', '#not-select', 'US']);
+        const err = lastJsonLog().error;
+        expect(err.code).toBe('not_a_select');
+        expect(err.matches_n).toBe(1);
+        expect(process.exitCode).toBeDefined();
+    });
+    it('maps missing-option failures to an option_not_found envelope with available list', async () => {
+        const evalMock = browserState.page.evaluate;
+        evalMock.mockResolvedValueOnce({ ok: true, matches_n: 1, match_level: 'exact' });
+        evalMock.mockResolvedValueOnce({ error: 'Option "XX" not found', available: ['US', 'CA'] });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'select', '#country', 'XX']);
+        const err = lastJsonLog().error;
+        expect(err.code).toBe('option_not_found');
+        expect(err.available).toEqual(['US', 'CA']);
+        expect(process.exitCode).toBeDefined();
+    });
+    it('surfaces selector_ambiguous from the resolver before calling selectResolvedJs', async () => {
+        browserState.page.evaluate.mockResolvedValueOnce({
+            ok: false,
+            code: 'selector_ambiguous',
+            message: 'CSS selector ".dropdown" matched 2 elements.',
+            hint: 'Pass --nth <n>.',
+            matches_n: 2,
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'select', '.dropdown', 'US']);
+        expect(lastJsonLog().error.code).toBe('selector_ambiguous');
+        // The select payload JS must not fire when resolution fails
+        expect(browserState.page.evaluate.mock.calls).toHaveLength(1);
+        expect(process.exitCode).toBeDefined();
+    });
+});
 describe('findPackageRoot', () => {
     it('walks up from dist/src to the package root', () => {
         const packageRoot = path.join('repo-root');