@jackwener/opencli 0.4.2 → 0.4.3

package/SKILL.md

@@ -10,6 +10,11 @@ tags: [cli, browser, web, mcp, playwright, bilibili, zhihu, twitter, github, v2e
 
 > Make any website your CLI. Reuse Chrome login, zero risk, AI-powered discovery.
 
+> [!CAUTION]
+> **AI Agent 必读：创建或修改任何适配器之前，你必须先阅读 [CLI-CREATOR.md](./CLI-CREATOR.md)！**
+> 该文档包含完整的 API 发现工作流（必须使用 Playwright MCP Bridge 浏览器探索）、5 级认证策略决策树、平台 SDK 速查表、`tap` 步骤调试流程、分页 API 模板、级联请求模式、以及常见陷阱。
+> **本文件（SKILL.md）仅提供命令参考和简化模板，不足以正确开发适配器。**
+
 ## Install & Run
 
 ```bash
@@ -29,8 +34,8 @@ npm update -g @jackwener/opencli
 
 Browser commands require:
 1. Chrome browser running **(logged into target sites)**
-2. [Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm) extension
-3. Configure `PLAYWRIGHT_MCP_EXTENSION_TOKEN` (from extension settings) in your MCP config
+2. [Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm) extension (default connection mode)
+3. **Alternative**: Chrome 144+ CDP auto-discovery — set `OPENCLI_USE_CDP=1` (no extension needed)
 
 > **Note**: You must be logged into the target website in Chrome before running commands. Tabs opened during command execution are auto-closed afterwards.
 
@@ -129,6 +134,7 @@ opencli ctrip search --query "三亚"      # 搜索目的地
 ```bash
 opencli list                # List all commands
 opencli list --json         # JSON output
+opencli list -f yaml        # YAML output
 opencli validate            # Validate all CLI definitions
 opencli validate bilibili   # Validate specific site
 ```
@@ -157,11 +163,14 @@ opencli verify <site/name> --smoke
 
 ## Output Formats
 
-All commands support `--format` / `-f`:
+All built-in commands support `--format` / `-f` with `table`, `json`, `yaml`, `md`, and `csv`.
+The `list` command supports the same formats and also keeps `--json` as a compatibility alias.
 
 ```bash
+opencli list -f yaml            # YAML command registry
 opencli bilibili hot -f table   # Default: rich table
 opencli bilibili hot -f json    # JSON (pipe to jq, feed to AI agent)
+opencli bilibili hot -f yaml    # YAML (readable structured output)
 opencli bilibili hot -f md      # Markdown
 opencli bilibili hot -f csv     # CSV
 ```
@@ -174,6 +183,11 @@ opencli bilibili hot -v         # Show each pipeline step and data flow
 
 ## Creating Adapters
 
+> [!IMPORTANT]
+> **STOP — 在写任何代码之前，先阅读 [CLI-CREATOR.md](./CLI-CREATOR.md)。**
+> 它包含：① AI Agent 浏览器探索工作流（必须用 Playwright MCP 抓包验证 API）② 认证策略决策树 ③ 平台 SDK（如 Bilibili 的 `apiGet`/`fetchJson`）④ YAML vs TS 选择指南 ⑤ `tap` 步骤调试方法 ⑥ 级联请求模板 ⑦ 常见陷阱表。
+> **下方仅为简化模板参考，直接使用极易踩坑。**
+
 ### YAML Pipeline (declarative, recommended)
 
 Create `src/clis/<site>/<name>.yaml`:
@@ -322,6 +336,9 @@ ${{ index + 1 }}
 | `OPENCLI_BROWSER_COMMAND_TIMEOUT` | 45 | Command execution timeout (sec) |
 | `OPENCLI_BROWSER_EXPLORE_TIMEOUT` | 120 | Explore timeout (sec) |
 | `OPENCLI_EXTENSION_LOCK_TIMEOUT` | 120 | Extension lock timeout (sec) |
+| `OPENCLI_CDP_ENDPOINT` | — | Manual CDP WebSocket endpoint (overrides auto-discovery) |
+| `OPENCLI_USE_CDP` | — | Set to `1` to use Chrome 144+ CDP auto-discovery instead of extension |
+| `OPENCLI_FORCE_EXTENSION` | — | Set to `1` to skip CDP and force extension mode |
 | `PLAYWRIGHT_MCP_EXTENSION_TOKEN` | — | Auto-approve extension connection |
 
 ## Troubleshooting
@@ -329,7 +346,7 @@ ${{ index + 1 }}
 | Issue | Solution |
 |-------|----------|
 | `npx not found` | Install Node.js: `brew install node` |
-| `Timed out connecting to browser` | 1) Chrome must be open 2) Install MCP Bridge extension 3) Click to approve |
+| `Timed out connecting to browser` | 1) Chrome must be open 2) Enable remote debugging at `chrome://inspect#remote-debugging` or install MCP Bridge extension |
 | `Extension lock timed out` | Another opencli command is running; browser commands run serially |
 | `Target page context` error | Add `navigate:` step before `evaluate:` in YAML |
 | Empty table data | Check if evaluate returns JSON string (MCP parsing) or data path is wrong |

package/dist/browser.d.ts

@@ -1,7 +1,21 @@
 /**
- * Browser interaction via Playwright MCP Bridge extension.
- * Connects to an existing Chrome browser through the extension's stdio JSON-RPC.
+ * Browser interaction via Chrome DevTools Protocol.
+ * Connects to an existing Chrome browser through CDP auto-discovery or extension bridge.
  */
+export declare function discoverChromeEndpoint(): Promise<string | null>;
+type ConnectFailureKind = 'missing-token' | 'extension-timeout' | 'extension-not-installed' | 'cdp-timeout' | 'mcp-init' | 'process-exit' | 'unknown';
+type ConnectFailureInput = {
+    kind: ConnectFailureKind;
+    mode: 'extension' | 'cdp';
+    timeout: number;
+    hasExtensionToken: boolean;
+    tokenFingerprint?: string | null;
+    stderr?: string;
+    exitCode?: number | null;
+    rawMessage?: string;
+};
+export declare function getTokenFingerprint(token: string | undefined): string | null;
+export declare function formatBrowserConnectError(input: ConnectFailureInput): Error;
 import type { IPage } from './types.js';
 /**
  * Page abstraction wrapping JSON-RPC calls to Playwright MCP.
@@ -46,6 +60,9 @@ export declare class Page implements IPage {
  * Playwright MCP process manager.
  */
 export declare class PlaywrightMCP {
+    private static _activeInsts;
+    private static _cleanupRegistered;
+    private static _registerGlobalCleanup;
     private _proc;
     private _buffer;
     private _waiters;
@@ -54,8 +71,10 @@ export declare class PlaywrightMCP {
     private _page;
     connect(opts?: {
         timeout?: number;
+        forceExtension?: boolean;
     }): Promise<Page>;
     close(): Promise<void>;
     private _acquireLock;
     private _releaseLock;
 }
+export {};

package/dist/browser.js

@@ -1,13 +1,76 @@
 /**
- * Browser interaction via Playwright MCP Bridge extension.
- * Connects to an existing Chrome browser through the extension's stdio JSON-RPC.
+ * Browser interaction via Chrome DevTools Protocol.
+ * Connects to an existing Chrome browser through CDP auto-discovery or extension bridge.
  */
 import { spawn, execSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import * as net from 'node:net';
 import { fileURLToPath } from 'node:url';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { formatSnapshot } from './snapshotFormatter.js';
+/**
+ * Chrome 144+ auto-discovery: read DevToolsActivePort file to get CDP endpoint.
+ *
+ * Starting with Chrome 144, users can enable remote debugging from
+ * chrome://inspect#remote-debugging without any command-line flags.
+ * Chrome writes the active port and browser GUID to a DevToolsActivePort file
+ * in the user data directory, which we read to construct the WebSocket endpoint.
+ *
+ * Priority: OPENCLI_CDP_ENDPOINT env > DevToolsActivePort auto-discovery > --extension fallback
+ */
+/** Quick TCP port probe to verify Chrome is actually listening */
+function isPortReachable(port, host = '127.0.0.1', timeoutMs = 800) {
+    return new Promise(resolve => {
+        const sock = net.createConnection({ port, host });
+        sock.setTimeout(timeoutMs);
+        sock.on('connect', () => { sock.destroy(); resolve(true); });
+        sock.on('error', () => resolve(false));
+        sock.on('timeout', () => { sock.destroy(); resolve(false); });
+    });
+}
+export async function discoverChromeEndpoint() {
+    const candidates = [];
+    // User-specified Chrome data dir takes highest priority
+    if (process.env.CHROME_USER_DATA_DIR) {
+        candidates.push(path.join(process.env.CHROME_USER_DATA_DIR, 'DevToolsActivePort'));
+    }
+    // Standard Chrome/Edge user data dirs per platform
+    if (process.platform === 'win32') {
+        const localAppData = process.env.LOCALAPPDATA ?? path.join(os.homedir(), 'AppData', 'Local');
+        candidates.push(path.join(localAppData, 'Google', 'Chrome', 'User Data', 'DevToolsActivePort'));
+        candidates.push(path.join(localAppData, 'Microsoft', 'Edge', 'User Data', 'DevToolsActivePort'));
+    }
+    else if (process.platform === 'darwin') {
+        candidates.push(path.join(os.homedir(), 'Library', 'Application Support', 'Google', 'Chrome', 'DevToolsActivePort'));
+        candidates.push(path.join(os.homedir(), 'Library', 'Application Support', 'Microsoft Edge', 'DevToolsActivePort'));
+    }
+    else {
+        candidates.push(path.join(os.homedir(), '.config', 'google-chrome', 'DevToolsActivePort'));
+        candidates.push(path.join(os.homedir(), '.config', 'chromium', 'DevToolsActivePort'));
+        candidates.push(path.join(os.homedir(), '.config', 'microsoft-edge', 'DevToolsActivePort'));
+    }
+    for (const filePath of candidates) {
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8').trim();
+            const lines = content.split('\n');
+            if (lines.length >= 2) {
+                const port = parseInt(lines[0], 10);
+                const browserPath = lines[1]; // e.g. /devtools/browser/<GUID>
+                if (port > 0 && browserPath.startsWith('/devtools/browser/')) {
+                    const endpoint = `ws://127.0.0.1:${port}${browserPath}`;
+                    // Verify the port is actually reachable (Chrome may have closed, leaving a stale file)
+                    if (await isPortReachable(port)) {
+                        return endpoint;
+                    }
+                }
+            }
+        }
+        catch { }
+    }
+    return null;
+}
 // Read version from package.json (single source of truth)
 const __browser_dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_VERSION = (() => { try {
@@ -20,6 +83,67 @@ const EXTENSION_LOCK_TIMEOUT = parseInt(process.env.OPENCLI_EXTENSION_LOCK_TIMEO
 const EXTENSION_LOCK_POLL = parseInt(process.env.OPENCLI_EXTENSION_LOCK_POLL_INTERVAL ?? '1', 10);
 const CONNECT_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_CONNECT_TIMEOUT ?? '30', 10);
 const LOCK_DIR = path.join(os.tmpdir(), 'opencli-mcp-lock');
+export function getTokenFingerprint(token) {
+    if (!token)
+        return null;
+    return createHash('sha256').update(token).digest('hex').slice(0, 8);
+}
+export function formatBrowserConnectError(input) {
+    const stderr = input.stderr?.trim();
+    const suffix = stderr ? `\n\nMCP stderr:\n${stderr}` : '';
+    const tokenHint = input.tokenFingerprint ? ` Token fingerprint: ${input.tokenFingerprint}.` : '';
+    if (input.mode === 'extension') {
+        if (input.kind === 'missing-token') {
+            return new Error('Failed to connect to Playwright MCP Bridge: PLAYWRIGHT_MCP_EXTENSION_TOKEN is not set.\n\n' +
+                'Without this token, Chrome will show a manual approval dialog for every new MCP connection. ' +
+                'Copy the token from the Playwright MCP Bridge extension and set it in BOTH your shell environment and MCP client config.' +
+                suffix);
+        }
+        if (input.kind === 'extension-not-installed') {
+            return new Error('Failed to connect to Playwright MCP Bridge: the browser extension did not attach.\n\n' +
+                'Make sure Chrome is running and the "Playwright MCP Bridge" extension is installed and enabled. ' +
+                'If Chrome shows an approval dialog, click Allow.' +
+                suffix);
+        }
+        if (input.kind === 'extension-timeout') {
+            const likelyCause = input.hasExtensionToken
+                ? `The most likely cause is that PLAYWRIGHT_MCP_EXTENSION_TOKEN does not match the token currently shown by the browser extension.${tokenHint} Re-copy the token from the extension and update BOTH your shell environment and MCP client config.`
+                : 'PLAYWRIGHT_MCP_EXTENSION_TOKEN is not configured, so the extension may be waiting for manual approval.';
+            return new Error(`Timed out connecting to Playwright MCP Bridge (${input.timeout}s).\n\n` +
+                `${likelyCause} If a browser prompt is visible, click Allow. You can also switch to Chrome remote debugging mode with OPENCLI_USE_CDP=1 as a fallback.` +
+                suffix);
+        }
+    }
+    if (input.mode === 'cdp' && input.kind === 'cdp-timeout') {
+        return new Error(`Timed out connecting to browser via CDP (${input.timeout}s).\n\n` +
+            'Make sure Chrome is running and remote debugging is enabled at chrome://inspect#remote-debugging, or set OPENCLI_CDP_ENDPOINT explicitly.' +
+            suffix);
+    }
+    if (input.kind === 'mcp-init') {
+        return new Error(`Failed to initialize Playwright MCP: ${input.rawMessage ?? 'unknown error'}${suffix}`);
+    }
+    if (input.kind === 'process-exit') {
+        return new Error(`Playwright MCP process exited before the browser connection was established${input.exitCode == null ? '' : ` (code ${input.exitCode})`}.` +
+            suffix);
+    }
+    return new Error(input.rawMessage ?? 'Failed to connect to browser');
+}
+function inferConnectFailureKind(args) {
+    const haystack = `${args.rawMessage ?? ''}\n${args.stderr}`.toLowerCase();
+    if (args.mode === 'extension' && !args.hasExtensionToken)
+        return 'missing-token';
+    if (haystack.includes('extension connection timeout') || haystack.includes('playwright mcp bridge'))
+        return 'extension-not-installed';
+    if (args.rawMessage?.startsWith('MCP init failed:'))
+        return 'mcp-init';
+    if (args.exited)
+        return 'process-exit';
+    if (args.mode === 'extension')
+        return 'extension-timeout';
+    if (args.mode === 'cdp')
+        return 'cdp-timeout';
+    return 'unknown';
+}
 // JSON-RPC helpers
 let _nextId = 1;
 function jsonRpcRequest(method, params = {}) {
@@ -227,6 +351,33 @@ export class Page {
  * Playwright MCP process manager.
  */
 export class PlaywrightMCP {
+    static _activeInsts = new Set();
+    static _cleanupRegistered = false;
+    static _registerGlobalCleanup() {
+        if (this._cleanupRegistered)
+            return;
+        this._cleanupRegistered = true;
+        const cleanup = () => {
+            for (const inst of this._activeInsts) {
+                if (inst._lockAcquired) {
+                    try {
+                        fs.rmdirSync(LOCK_DIR);
+                    }
+                    catch { }
+                    inst._lockAcquired = false;
+                }
+                if (inst._proc && !inst._proc.killed) {
+                    try {
+                        inst._proc.kill('SIGKILL');
+                    }
+                    catch { }
+                }
+            }
+        };
+        process.on('exit', cleanup);
+        process.on('SIGINT', () => { cleanup(); process.exit(130); });
+        process.on('SIGTERM', () => { cleanup(); process.exit(143); });
+    }
     _proc = null;
     _buffer = '';
     _waiters = [];
@@ -239,15 +390,80 @@ export class PlaywrightMCP {
         const mcpPath = findMcpServerPath();
         if (!mcpPath)
             throw new Error('Playwright MCP server not found. Install: npm install -D @playwright/mcp');
+        // Connection priority:
+        // 1. OPENCLI_CDP_ENDPOINT env var → explicit CDP endpoint
+        // 2. OPENCLI_USE_CDP=1 → auto-discover via DevToolsActivePort
+        // 3. Default → --extension mode (Playwright MCP Bridge)
+        // Some anti-bot sites (e.g. BOSS Zhipin) detect CDP — use forceExtension to bypass.
+        const forceExt = opts.forceExtension || process.env.OPENCLI_FORCE_EXTENSION === '1';
+        let cdpEndpoint = null;
+        if (!forceExt) {
+            if (process.env.OPENCLI_CDP_ENDPOINT) {
+                cdpEndpoint = process.env.OPENCLI_CDP_ENDPOINT;
+            }
+            else if (process.env.OPENCLI_USE_CDP === '1') {
+                cdpEndpoint = await discoverChromeEndpoint();
+            }
+        }
         return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => reject(new Error(`Timed out connecting to browser (${timeout}s)`)), timeout * 1000);
-            const mcpArgs = [mcpPath, '--extension'];
+            const isDebug = process.env.DEBUG?.includes('opencli:mcp');
+            const debugLog = (msg) => isDebug && console.error(`[opencli:mcp] ${msg}`);
+            const mode = cdpEndpoint ? 'cdp' : 'extension';
+            const extensionToken = process.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN;
+            const tokenFingerprint = getTokenFingerprint(extensionToken);
+            let stderrBuffer = '';
+            let settled = false;
+            const settleError = (kind, extra = {}) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(formatBrowserConnectError({
+                    kind,
+                    mode,
+                    timeout,
+                    hasExtensionToken: !!extensionToken,
+                    tokenFingerprint,
+                    stderr: stderrBuffer,
+                    exitCode: extra.exitCode,
+                    rawMessage: extra.rawMessage,
+                }));
+            };
+            const settleSuccess = (pageToResolve) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(pageToResolve);
+            };
+            const timer = setTimeout(() => {
+                debugLog('Connection timed out');
+                settleError(inferConnectFailureKind({
+                    mode,
+                    hasExtensionToken: !!extensionToken,
+                    stderr: stderrBuffer,
+                }));
+            }, timeout * 1000);
+            const mcpArgs = [mcpPath];
+            if (cdpEndpoint) {
+                mcpArgs.push('--cdp-endpoint', cdpEndpoint);
+            }
+            else {
+                mcpArgs.push('--extension');
+            }
+            if (process.env.OPENCLI_VERBOSE) {
+                console.error(`[opencli] CDP mode: ${cdpEndpoint ? `auto-discovered ${cdpEndpoint}` : 'fallback to --extension'}`);
+                if (mode === 'extension') {
+                    console.error(`[opencli] Extension token: ${extensionToken ? `configured (fingerprint ${tokenFingerprint})` : 'missing'}`);
+                }
+            }
             if (process.env.OPENCLI_BROWSER_EXECUTABLE_PATH) {
                 mcpArgs.push('--executablePath', process.env.OPENCLI_BROWSER_EXECUTABLE_PATH);
             }
+            debugLog(`Spawning node ${mcpArgs.join(' ')}`);
             this._proc = spawn('node', mcpArgs, {
                 stdio: ['pipe', 'pipe', 'pipe'],
-                env: { ...process.env, ...(process.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN ? { PLAYWRIGHT_MCP_EXTENSION_TOKEN: process.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN } : {}) },
+                env: { ...process.env },
             });
             // Increase max listeners to avoid warnings
             this._proc.setMaxListeners(20);
@@ -263,45 +479,82 @@ export class PlaywrightMCP {
                 for (const line of lines) {
                     if (!line.trim())
                         continue;
+                    debugLog(`RECV: ${line}`);
                     try {
                         const parsed = JSON.parse(line);
                         const waiter = this._waiters.shift();
                         if (waiter)
                             waiter(parsed);
                     }
-                    catch { }
+                    catch (e) {
+                        debugLog(`Parse error: ${e}`);
+                    }
+                }
+            });
+            this._proc.stderr?.on('data', (chunk) => {
+                const text = chunk.toString();
+                stderrBuffer += text;
+                debugLog(`STDERR: ${text}`);
+            });
+            this._proc.on('error', (err) => {
+                debugLog(`Subprocess error: ${err.message}`);
+                settleError('process-exit', { rawMessage: err.message });
+            });
+            this._proc.on('close', (code) => {
+                debugLog(`Subprocess closed with code ${code}`);
+                if (!settled) {
+                    settleError(inferConnectFailureKind({
+                        mode,
+                        hasExtensionToken: !!extensionToken,
+                        stderr: stderrBuffer,
+                        exited: true,
+                    }), { exitCode: code });
                 }
             });
-            this._proc.stderr?.on('data', () => { });
-            this._proc.on('error', (err) => { clearTimeout(timer); reject(err); });
             // Initialize: send initialize request
             const initMsg = jsonRpcRequest('initialize', {
                 protocolVersion: '2024-11-05',
                 capabilities: {},
                 clientInfo: { name: 'opencli', version: PKG_VERSION },
             });
+            debugLog(`SEND: ${initMsg.trim()}`);
             this._proc.stdin?.write(initMsg);
             // Wait for initialize response, then send initialized notification
             const origRecv = () => new Promise((res) => { this._waiters.push(res); });
+            debugLog('Waiting for initialize response...');
             origRecv().then((resp) => {
+                debugLog('Got initialize response');
                 if (resp.error) {
-                    clearTimeout(timer);
-                    reject(new Error(`MCP init failed: ${resp.error.message}`));
+                    settleError(inferConnectFailureKind({
+                        mode,
+                        hasExtensionToken: !!extensionToken,
+                        stderr: stderrBuffer,
+                        rawMessage: `MCP init failed: ${resp.error.message}`,
+                    }), { rawMessage: resp.error.message });
                     return;
                 }
-                this._proc?.stdin?.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+                const initializedMsg = JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n';
+                debugLog(`SEND: ${initializedMsg.trim()}`);
+                this._proc?.stdin?.write(initializedMsg);
                 // Get initial tab count for cleanup
+                debugLog('Fetching initial tabs count...');
                 page.tabs().then((tabs) => {
+                    debugLog(`Tabs response: ${typeof tabs === 'string' ? tabs : JSON.stringify(tabs)}`);
                     if (typeof tabs === 'string') {
                         this._initialTabCount = (tabs.match(/Tab \d+/g) || []).length;
                     }
                     else if (Array.isArray(tabs)) {
                         this._initialTabCount = tabs.length;
                     }
-                    clearTimeout(timer);
-                    resolve(page);
-                }).catch(() => { clearTimeout(timer); resolve(page); });
-            }).catch((err) => { clearTimeout(timer); reject(err); });
+                    settleSuccess(page);
+                }).catch((err) => {
+                    debugLog(`Tabs fetch error: ${err.message}`);
+                    settleSuccess(page);
+                });
+            }).catch((err) => {
+                debugLog(`Init promise rejected: ${err.message}`);
+                settleError('mcp-init', { rawMessage: err.message });
+            });
         });
     }
     async close() {
@@ -334,6 +587,7 @@ export class PlaywrightMCP {
         finally {
             this._page = null;
             this._releaseLock();
+            PlaywrightMCP._activeInsts.delete(this);
         }
     }
     async _acquireLock() {

package/dist/browser.test.d.ts

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

package/dist/browser.test.js

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { formatBrowserConnectError, getTokenFingerprint } from './browser.js';
+describe('getTokenFingerprint', () => {
+    it('returns null for empty token', () => {
+        expect(getTokenFingerprint(undefined)).toBeNull();
+    });
+    it('returns stable short fingerprint for token', () => {
+        expect(getTokenFingerprint('abc123')).toBe('6ca13d52');
+    });
+});
+describe('formatBrowserConnectError', () => {
+    it('explains missing extension token clearly', () => {
+        const err = formatBrowserConnectError({
+            kind: 'missing-token',
+            mode: 'extension',
+            timeout: 30,
+            hasExtensionToken: false,
+        });
+        expect(err.message).toContain('PLAYWRIGHT_MCP_EXTENSION_TOKEN is not set');
+        expect(err.message).toContain('manual approval dialog');
+    });
+    it('mentions token mismatch as likely cause for extension timeout', () => {
+        const err = formatBrowserConnectError({
+            kind: 'extension-timeout',
+            mode: 'extension',
+            timeout: 30,
+            hasExtensionToken: true,
+            tokenFingerprint: 'deadbeef',
+        });
+        expect(err.message).toContain('does not match the token currently shown by the browser extension');
+        expect(err.message).toContain('deadbeef');
+    });
+    it('keeps CDP timeout guidance separate', () => {
+        const err = formatBrowserConnectError({
+            kind: 'cdp-timeout',
+            mode: 'cdp',
+            timeout: 30,
+            hasExtensionToken: false,
+        });
+        expect(err.message).toContain('via CDP');
+        expect(err.message).toContain('chrome://inspect#remote-debugging');
+    });
+});

package/dist/build-manifest.js

@@ -85,6 +85,10 @@ function scanTs(filePath, site) {
         const stratMatch = src.match(/strategy\s*:\s*Strategy\.(\w+)/);
         if (stratMatch)
             entry.strategy = stratMatch[1].toLowerCase();
+        // Extract browser: false (some adapters bypass browser entirely)
+        const browserMatch = src.match(/browser\s*:\s*(true|false)/);
+        if (browserMatch)
+            entry.browser = browserMatch[1] === 'true';
         // Extract columns
         const colMatch = src.match(/columns\s*:\s*\[([^\]]*)\]/);
         if (colMatch) {