@jackwener/opencli 1.6.1 → 1.6.3

package/dist/src/browser/page.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Page abstraction — implements IPage by sending commands to the daemon.
+ *
+ * All browser operations are ultimately 'exec' (JS evaluation via CDP)
+ * plus a few native Chrome Extension APIs (tabs, cookies, navigate).
+ *
+ * IMPORTANT: After goto(), we remember the tabId returned by the navigate
+ * action and pass it to all subsequent commands. This avoids the issue
+ * where resolveTabId() in the extension picks a chrome:// or
+ * chrome-extension:// tab that can't be debugged.
+ */
+import type { BrowserCookie, ScreenshotOptions } from '../types.js';
+import { BasePage } from './base-page.js';
+export declare function isRetryableSettleError(err: unknown): boolean;
+/**
+ * Page — implements IPage by talking to the daemon via HTTP.
+ */
+export declare class Page extends BasePage {
+    private readonly workspace;
+    constructor(workspace?: string);
+    /** Active tab ID, set after navigate and used in all subsequent commands */
+    private _tabId;
+    /** Helper: spread workspace into command params */
+    private _wsOpt;
+    /** Helper: spread workspace + tabId into command params */
+    private _cmdOpts;
+    goto(url: string, options?: {
+        waitUntil?: 'load' | 'none';
+        settleMs?: number;
+    }): Promise<void>;
+    getActiveTabId(): number | undefined;
+    evaluate(js: string): Promise<unknown>;
+    getCookies(opts?: {
+        domain?: string;
+        url?: string;
+    }): Promise<BrowserCookie[]>;
+    /** Close the automation window in the extension */
+    closeWindow(): Promise<void>;
+    tabs(): Promise<unknown[]>;
+    selectTab(index: number): Promise<void>;
+    /**
+     * Capture a screenshot via CDP Page.captureScreenshot.
+     */
+    screenshot(options?: ScreenshotOptions): Promise<string>;
+    startNetworkCapture(pattern?: string): Promise<void>;
+    readNetworkCapture(): Promise<unknown[]>;
+    /**
+     * Set local file paths on a file input element via CDP DOM.setFileInputFiles.
+     * Chrome reads the files directly from the local filesystem, avoiding the
+     * payload size limits of base64-in-evaluate.
+     */
+    setFileInput(files: string[], selector?: string): Promise<void>;
+    insertText(text: string): Promise<void>;
+    cdp(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** CDP native click fallback — called when JS el.click() fails */
+    protected tryNativeClick(x: number, y: number): Promise<boolean>;
+    /** Precise click using DOM.getContentQuads/getBoxModel for inline elements */
+    clickWithQuads(ref: string): Promise<void>;
+    nativeClick(x: number, y: number): Promise<void>;
+    nativeType(text: string): Promise<void>;
+    nativeKeyPress(key: string, modifiers?: string[]): Promise<void>;
+}

package/dist/src/browser/page.js

@@ -0,0 +1,304 @@
+/**
+ * Page abstraction — implements IPage by sending commands to the daemon.
+ *
+ * All browser operations are ultimately 'exec' (JS evaluation via CDP)
+ * plus a few native Chrome Extension APIs (tabs, cookies, navigate).
+ *
+ * IMPORTANT: After goto(), we remember the tabId returned by the navigate
+ * action and pass it to all subsequent commands. This avoids the issue
+ * where resolveTabId() in the extension picks a chrome:// or
+ * chrome-extension:// tab that can't be debugged.
+ */
+import { sendCommand } from './daemon-client.js';
+import { wrapForEval } from './utils.js';
+import { saveBase64ToFile } from '../utils.js';
+import { generateStealthJs } from './stealth.js';
+import { waitForDomStableJs } from './dom-helpers.js';
+import { BasePage } from './base-page.js';
+export function isRetryableSettleError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return message.includes('Inspected target navigated or closed')
+        || (message.includes('-32000') && message.toLowerCase().includes('target'));
+}
+/**
+ * Page — implements IPage by talking to the daemon via HTTP.
+ */
+export class Page extends BasePage {
+    workspace;
+    constructor(workspace = 'default') {
+        super();
+        this.workspace = workspace;
+    }
+    /** Active tab ID, set after navigate and used in all subsequent commands */
+    _tabId;
+    /** Helper: spread workspace into command params */
+    _wsOpt() {
+        return { workspace: this.workspace };
+    }
+    /** Helper: spread workspace + tabId into command params */
+    _cmdOpts() {
+        return {
+            workspace: this.workspace,
+            ...(this._tabId !== undefined && { tabId: this._tabId }),
+        };
+    }
+    async goto(url, options) {
+        const result = await sendCommand('navigate', {
+            url,
+            ...this._cmdOpts(),
+        });
+        // Remember the tabId and URL for subsequent calls
+        if (result?.tabId) {
+            this._tabId = result.tabId;
+        }
+        this._lastUrl = url;
+        // Inject stealth + settle in a single round-trip instead of two sequential exec calls.
+        // The stealth guard flag prevents double-injection; settle uses DOM stability detection.
+        if (options?.waitUntil !== 'none') {
+            const maxMs = options?.settleMs ?? 1000;
+            const combinedCode = `${generateStealthJs()};\n${waitForDomStableJs(maxMs, Math.min(500, maxMs))}`;
+            const combinedOpts = {
+                code: combinedCode,
+                ...this._cmdOpts(),
+            };
+            try {
+                await sendCommand('exec', combinedOpts);
+            }
+            catch (err) {
+                if (!isRetryableSettleError(err))
+                    throw err;
+                // SPA client-side redirects can invalidate the CDP target after
+                // chrome.tabs reports 'complete'. Wait briefly for the new document
+                // to load, then retry the settle probe once.
+                try {
+                    await new Promise((r) => setTimeout(r, 200));
+                    await sendCommand('exec', combinedOpts);
+                }
+                catch (retryErr) {
+                    if (!isRetryableSettleError(retryErr))
+                        throw retryErr;
+                }
+            }
+        }
+        else {
+            // Even with waitUntil='none', still inject stealth (best-effort)
+            try {
+                await sendCommand('exec', {
+                    code: generateStealthJs(),
+                    ...this._cmdOpts(),
+                });
+            }
+            catch {
+                // Non-fatal: stealth is best-effort
+            }
+        }
+    }
+    getActiveTabId() {
+        return this._tabId;
+    }
+    async evaluate(js) {
+        const code = wrapForEval(js);
+        try {
+            return await sendCommand('exec', { code, ...this._cmdOpts() });
+        }
+        catch (err) {
+            if (!isRetryableSettleError(err))
+                throw err;
+            await new Promise((resolve) => setTimeout(resolve, 200));
+            return sendCommand('exec', { code, ...this._cmdOpts() });
+        }
+    }
+    async getCookies(opts = {}) {
+        const result = await sendCommand('cookies', { ...this._wsOpt(), ...opts });
+        return Array.isArray(result) ? result : [];
+    }
+    /** Close the automation window in the extension */
+    async closeWindow() {
+        try {
+            await sendCommand('close-window', { ...this._wsOpt() });
+        }
+        catch {
+            // Window may already be closed or daemon may be down
+        }
+        finally {
+            this._tabId = undefined;
+            this._lastUrl = null;
+        }
+    }
+    async tabs() {
+        const result = await sendCommand('tabs', { op: 'list', ...this._wsOpt() });
+        return Array.isArray(result) ? result : [];
+    }
+    async selectTab(index) {
+        const result = await sendCommand('tabs', { op: 'select', index, ...this._wsOpt() });
+        if (result?.selected)
+            this._tabId = result.selected;
+    }
+    /**
+     * Capture a screenshot via CDP Page.captureScreenshot.
+     */
+    async screenshot(options = {}) {
+        const base64 = await sendCommand('screenshot', {
+            ...this._cmdOpts(),
+            format: options.format,
+            quality: options.quality,
+            fullPage: options.fullPage,
+        });
+        if (options.path) {
+            await saveBase64ToFile(base64, options.path);
+        }
+        return base64;
+    }
+    async startNetworkCapture(pattern = '') {
+        await sendCommand('network-capture-start', {
+            pattern,
+            ...this._cmdOpts(),
+        });
+    }
+    async readNetworkCapture() {
+        const result = await sendCommand('network-capture-read', {
+            ...this._cmdOpts(),
+        });
+        return Array.isArray(result) ? result : [];
+    }
+    /**
+     * Set local file paths on a file input element via CDP DOM.setFileInputFiles.
+     * Chrome reads the files directly from the local filesystem, avoiding the
+     * payload size limits of base64-in-evaluate.
+     */
+    async setFileInput(files, selector) {
+        const result = await sendCommand('set-file-input', {
+            files,
+            selector,
+            ...this._cmdOpts(),
+        });
+        if (!result?.count) {
+            throw new Error('setFileInput returned no count — command may not be supported by the extension');
+        }
+    }
+    async insertText(text) {
+        const result = await sendCommand('insert-text', {
+            text,
+            ...this._cmdOpts(),
+        });
+        if (!result?.inserted) {
+            throw new Error('insertText returned no inserted flag — command may not be supported by the extension');
+        }
+    }
+    async cdp(method, params = {}) {
+        return sendCommand('cdp', {
+            cdpMethod: method,
+            cdpParams: params,
+            ...this._cmdOpts(),
+        });
+    }
+    /** CDP native click fallback — called when JS el.click() fails */
+    async tryNativeClick(x, y) {
+        try {
+            await this.nativeClick(x, y);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Precise click using DOM.getContentQuads/getBoxModel for inline elements */
+    async clickWithQuads(ref) {
+        const safeRef = JSON.stringify(ref);
+        const cssSelector = `[data-opencli-ref="${ref.replace(/"/g, '\\"')}"]`;
+        // Scroll element into view first
+        await this.evaluate(`
+      (() => {
+        const el = document.querySelector('[data-opencli-ref="' + ${safeRef} + '"]');
+        if (el) el.scrollIntoView({ behavior: 'instant', block: 'center' });
+        return !!el;
+      })()
+    `);
+        try {
+            // Find DOM node via CDP
+            const doc = await this.cdp('DOM.getDocument', {});
+            const result = await this.cdp('DOM.querySelectorAll', {
+                nodeId: doc.root.nodeId,
+                selector: cssSelector,
+            });
+            if (!result.nodeIds?.length)
+                throw new Error('DOM node not found');
+            const nodeId = result.nodeIds[0];
+            // Try getContentQuads first (precise for inline elements)
+            try {
+                const quads = await this.cdp('DOM.getContentQuads', { nodeId });
+                if (quads.quads?.length) {
+                    const q = quads.quads[0];
+                    const cx = (q[0] + q[2] + q[4] + q[6]) / 4;
+                    const cy = (q[1] + q[3] + q[5] + q[7]) / 4;
+                    await this.nativeClick(Math.round(cx), Math.round(cy));
+                    return;
+                }
+            }
+            catch { /* fallthrough */ }
+            // Try getBoxModel
+            try {
+                const box = await this.cdp('DOM.getBoxModel', { nodeId });
+                if (box.model?.content) {
+                    const c = box.model.content;
+                    const cx = (c[0] + c[2] + c[4] + c[6]) / 4;
+                    const cy = (c[1] + c[3] + c[5] + c[7]) / 4;
+                    await this.nativeClick(Math.round(cx), Math.round(cy));
+                    return;
+                }
+            }
+            catch { /* fallthrough */ }
+        }
+        catch { /* fallthrough */ }
+        // Final fallback: regular click
+        await this.evaluate(`
+      (() => {
+        const el = document.querySelector('[data-opencli-ref="' + ${safeRef} + '"]');
+        if (!el) throw new Error('Element not found: ' + ${safeRef});
+        el.click();
+        return 'clicked';
+      })()
+    `);
+    }
+    async nativeClick(x, y) {
+        await this.cdp('Input.dispatchMouseEvent', {
+            type: 'mousePressed',
+            x, y,
+            button: 'left',
+            clickCount: 1,
+        });
+        await this.cdp('Input.dispatchMouseEvent', {
+            type: 'mouseReleased',
+            x, y,
+            button: 'left',
+            clickCount: 1,
+        });
+    }
+    async nativeType(text) {
+        // Use Input.insertText for reliable Unicode/CJK text insertion
+        await this.cdp('Input.insertText', { text });
+    }
+    async nativeKeyPress(key, modifiers = []) {
+        let modifierFlags = 0;
+        for (const mod of modifiers) {
+            if (mod === 'Alt')
+                modifierFlags |= 1;
+            if (mod === 'Ctrl')
+                modifierFlags |= 2;
+            if (mod === 'Meta')
+                modifierFlags |= 4;
+            if (mod === 'Shift')
+                modifierFlags |= 8;
+        }
+        await this.cdp('Input.dispatchKeyEvent', {
+            type: 'keyDown',
+            key,
+            modifiers: modifierFlags,
+        });
+        await this.cdp('Input.dispatchKeyEvent', {
+            type: 'keyUp',
+            key,
+            modifiers: modifierFlags,
+        });
+    }
+}

package/dist/src/browser/page.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/stealth.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Utility functions for browser operations
+ */
+/**
+ * Wrap JS code for CDP Runtime.evaluate:
+ * - Already an IIFE `(...)()` → send as-is
+ * - Arrow/function literal → wrap as IIFE `(code)()`
+ * - `new Promise(...)` or raw expression → send as-is (expression)
+ */
+export declare function wrapForEval(js: string): string;

package/dist/src/browser/utils.js

@@ -0,0 +1,27 @@
+/**
+ * Utility functions for browser operations
+ */
+/**
+ * Wrap JS code for CDP Runtime.evaluate:
+ * - Already an IIFE `(...)()` → send as-is
+ * - Arrow/function literal → wrap as IIFE `(code)()`
+ * - `new Promise(...)` or raw expression → send as-is (expression)
+ */
+export function wrapForEval(js) {
+    if (typeof js !== 'string')
+        return 'undefined';
+    const code = js.trim();
+    if (!code)
+        return 'undefined';
+    // Already an IIFE: `(async () => { ... })()` or `(function() {...})()`
+    if (/^\([\s\S]*\)\s*\(.*\)\s*$/.test(code))
+        return code;
+    // Arrow function: `() => ...` or `async () => ...`
+    if (/^(async\s+)?(\([^)]*\)|[A-Za-z_]\w*)\s*=>/.test(code))
+        return `(${code})()`;
+    // Function declaration: `function ...` or `async function ...`
+    if (/^(async\s+)?function[\s(]/.test(code))
+        return `(${code})()`;
+    // Everything else: bare expression, `new Promise(...)`, etc. → evaluate directly
+    return code;
+}

package/dist/src/browser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser.test.js

@@ -0,0 +1,159 @@
+import { describe, it, expect, vi } from 'vitest';
+import { BrowserBridge, generateStealthJs } from './browser/index.js';
+import { extractTabEntries, diffTabIndexes, appendLimited } from './browser/tabs.js';
+import { withTimeoutMs } from './runtime.js';
+import { __test__ as cdpTest } from './browser/cdp.js';
+import { isRetryableSettleError } from './browser/page.js';
+import * as daemonClient from './browser/daemon-client.js';
+describe('browser helpers', () => {
+    it('extracts tab entries from string snapshots', () => {
+        const entries = extractTabEntries('Tab 0 https://example.com\nTab 1 Chrome Extension');
+        expect(entries).toEqual([
+            { index: 0, identity: 'https://example.com' },
+            { index: 1, identity: 'Chrome Extension' },
+        ]);
+    });
+    it('extracts tab entries from MCP markdown format', () => {
+        const entries = extractTabEntries('- 0: (current) [Playwright MCP extension](chrome-extension://abc/connect.html)\n- 1: [知乎 - 首页](https://www.zhihu.com/)');
+        expect(entries).toEqual([
+            { index: 0, identity: '(current) [Playwright MCP extension](chrome-extension://abc/connect.html)' },
+            { index: 1, identity: '[知乎 - 首页](https://www.zhihu.com/)' },
+        ]);
+    });
+    it('closes only tabs that were opened during the session', () => {
+        const tabsToClose = diffTabIndexes(['https://example.com', 'Chrome Extension'], [
+            { index: 0, identity: 'https://example.com' },
+            { index: 1, identity: 'Chrome Extension' },
+            { index: 2, identity: 'https://target.example/page' },
+            { index: 3, identity: 'chrome-extension://bridge' },
+        ]);
+        expect(tabsToClose).toEqual([3, 2]);
+    });
+    it('keeps only the tail of stderr buffers', () => {
+        expect(appendLimited('12345', '67890', 8)).toBe('34567890');
+    });
+    it('times out slow promises', async () => {
+        await expect(withTimeoutMs(new Promise(() => { }), 10, 'timeout')).rejects.toThrow('timeout');
+    });
+    it('retries settle only for target-invalidated errors', () => {
+        expect(isRetryableSettleError(new Error('{"code":-32000,"message":"Inspected target navigated or closed"}'))).toBe(true);
+        expect(isRetryableSettleError(new Error('attach failed: target no longer exists'))).toBe(false);
+        expect(isRetryableSettleError(new Error('malformed exec payload'))).toBe(false);
+    });
+    it('prefers the real Electron app target over DevTools and blank pages', () => {
+        const target = cdpTest.selectCDPTarget([
+            {
+                type: 'page',
+                title: 'DevTools - localhost:9224',
+                url: 'devtools://devtools/bundled/inspector.html',
+                webSocketDebuggerUrl: 'ws://127.0.0.1:9224/devtools',
+            },
+            {
+                type: 'page',
+                title: '',
+                url: 'about:blank',
+                webSocketDebuggerUrl: 'ws://127.0.0.1:9224/blank',
+            },
+            {
+                type: 'app',
+                title: 'Antigravity',
+                url: 'http://localhost:3000/',
+                webSocketDebuggerUrl: 'ws://127.0.0.1:9224/app',
+            },
+        ]);
+        expect(target?.webSocketDebuggerUrl).toBe('ws://127.0.0.1:9224/app');
+    });
+    it('honors OPENCLI_CDP_TARGET when multiple inspectable targets exist', () => {
+        vi.stubEnv('OPENCLI_CDP_TARGET', 'codex');
+        const target = cdpTest.selectCDPTarget([
+            {
+                type: 'app',
+                title: 'Cursor',
+                url: 'http://localhost:3000/cursor',
+                webSocketDebuggerUrl: 'ws://127.0.0.1:9226/cursor',
+            },
+            {
+                type: 'app',
+                title: 'OpenAI Codex',
+                url: 'http://localhost:3000/codex',
+                webSocketDebuggerUrl: 'ws://127.0.0.1:9226/codex',
+            },
+        ]);
+        expect(target?.webSocketDebuggerUrl).toBe('ws://127.0.0.1:9226/codex');
+    });
+});
+describe('BrowserBridge state', () => {
+    it('transitions to closed after close()', async () => {
+        const bridge = new BrowserBridge();
+        expect(bridge.state).toBe('idle');
+        await bridge.close();
+        expect(bridge.state).toBe('closed');
+    });
+    it('rejects connect() after the session has been closed', async () => {
+        const bridge = new BrowserBridge();
+        await bridge.close();
+        await expect(bridge.connect()).rejects.toThrow('Session is closed');
+    });
+    it('rejects connect() while already connecting', async () => {
+        const bridge = new BrowserBridge();
+        bridge._state = 'connecting';
+        await expect(bridge.connect()).rejects.toThrow('Already connecting');
+    });
+    it('rejects connect() while closing', async () => {
+        const bridge = new BrowserBridge();
+        bridge._state = 'closing';
+        await expect(bridge.connect()).rejects.toThrow('Session is closing');
+    });
+    it('fails fast when daemon is running but extension is disconnected', async () => {
+        vi.spyOn(daemonClient, 'isExtensionConnected').mockResolvedValue(false);
+        vi.spyOn(daemonClient, 'fetchDaemonStatus').mockResolvedValue({ extensionConnected: false });
+        const bridge = new BrowserBridge();
+        await expect(bridge.connect({ timeout: 0.1 })).rejects.toThrow('Browser Extension is not connected');
+    });
+});
+describe('stealth anti-detection', () => {
+    it('generates non-empty JS string', () => {
+        const js = generateStealthJs();
+        expect(typeof js).toBe('string');
+        expect(js.length).toBeGreaterThan(100);
+    });
+    it('contains all 7 anti-detection patches', () => {
+        const js = generateStealthJs();
+        // 1. webdriver
+        expect(js).toContain('navigator');
+        expect(js).toContain('webdriver');
+        // 2. chrome stub
+        expect(js).toContain('window.chrome');
+        // 3. plugins
+        expect(js).toContain('plugins');
+        expect(js).toContain('PDF Viewer');
+        // 4. languages
+        expect(js).toContain('languages');
+        // 5. permissions
+        expect(js).toContain('Permissions');
+        expect(js).toContain('notifications');
+        // 6. automation artifacts (dynamic cdc_ scan)
+        expect(js).toContain('__playwright');
+        expect(js).toContain('__puppeteer');
+        expect(js).toContain('getOwnPropertyNames');
+        expect(js).toContain('cdc_');
+        // 7. CDP stack trace cleanup
+        expect(js).toContain('Error.prototype');
+        expect(js).toContain('puppeteer_evaluation_script');
+        expect(js).toContain('getOwnPropertyDescriptor');
+    });
+    it('includes guard flag to prevent double-injection', () => {
+        const js = generateStealthJs();
+        // Guard uses a non-enumerable property on a built-in prototype
+        expect(js).toContain("EventTarget.prototype");
+        // Guard should check early and return 'skipped'
+        expect(js).toContain("return 'skipped'");
+        // Normal path returns 'applied'
+        expect(js).toContain("return 'applied'");
+    });
+    it('generates syntactically valid JS', () => {
+        const js = generateStealthJs();
+        // Should not throw when parsed
+        expect(() => new Function(js)).not.toThrow();
+    });
+});

package/dist/src/build-manifest.d.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * Build-time CLI manifest compiler.
+ *
+ * Scans all YAML/TS CLI definitions and pre-compiles them into a single
+ * manifest.json for instant cold-start registration (no runtime YAML parsing).
+ *
+ * Usage: npx tsx src/build-manifest.ts
+ * Output: dist/cli-manifest.json
+ */
+export interface ManifestEntry {
+    site: string;
+    name: string;
+    aliases?: string[];
+    description: string;
+    domain?: string;
+    strategy: string;
+    browser: boolean;
+    args: Array<{
+        name: string;
+        type?: string;
+        default?: unknown;
+        required?: boolean;
+        valueRequired?: boolean;
+        positional?: boolean;
+        help?: string;
+        choices?: string[];
+    }>;
+    columns?: string[];
+    pipeline?: Record<string, unknown>[];
+    timeout?: number;
+    deprecated?: boolean | string;
+    replacedBy?: string;
+    /** 'yaml' or 'ts' — determines how executeCommand loads the handler */
+    type: 'yaml' | 'ts';
+    /** Relative path from clis/ dir, e.g. 'bilibili/hot.yaml' or 'bilibili/search.js' */
+    modulePath?: string;
+    /** Pre-navigation control — see CliCommand.navigateBefore */
+    navigateBefore?: boolean | string;
+}
+export declare function loadTsManifestEntries(filePath: string, site: string, importer?: (moduleHref: string) => Promise<unknown>): Promise<ManifestEntry[]>;
+/**
+ * When both YAML and TS adapters exist for the same site/name,
+ * prefer the TS version (it self-registers and typically has richer logic).
+ */
+export declare function shouldReplaceManifestEntry(current: ManifestEntry, next: ManifestEntry): boolean;
+export declare function buildManifest(): Promise<ManifestEntry[]>;