@jackwener/opencli 0.7.5 → 0.7.8

package/dist/browser/mcp.js

@@ -0,0 +1,304 @@
+/**
+ * Playwright MCP process manager.
+ * Handles lifecycle management, JSON-RPC communication, and browser session orchestration.
+ */
+import { spawn } from 'node:child_process';
+import { withTimeoutMs, DEFAULT_BROWSER_CONNECT_TIMEOUT } from '../runtime.js';
+import { PKG_VERSION } from '../version.js';
+import { Page } from './page.js';
+import { getTokenFingerprint, formatBrowserConnectError, inferConnectFailureKind } from './errors.js';
+import { findMcpServerPath, buildMcpArgs } from './discover.js';
+import { extractTabIdentities, extractTabEntries, diffTabIndexes, appendLimited } from './tabs.js';
+const STDERR_BUFFER_LIMIT = 16 * 1024;
+const INITIAL_TABS_TIMEOUT_MS = 1500;
+const TAB_CLEANUP_TIMEOUT_MS = 2000;
+// JSON-RPC helpers
+let _nextId = 1;
+export function createJsonRpcRequest(method, params = {}) {
+    const id = _nextId++;
+    return {
+        id,
+        message: JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n',
+    };
+}
+/**
+ * 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._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 = '';
+    _pending = new Map();
+    _initialTabIdentities = [];
+    _closingPromise = null;
+    _state = 'idle';
+    _page = null;
+    get state() {
+        return this._state;
+    }
+    _sendRequest(method, params = {}) {
+        return new Promise((resolve, reject) => {
+            if (!this._proc?.stdin?.writable) {
+                reject(new Error('Playwright MCP process is not writable'));
+                return;
+            }
+            const { id, message } = createJsonRpcRequest(method, params);
+            this._pending.set(id, { resolve, reject });
+            this._proc.stdin.write(message, (err) => {
+                if (!err)
+                    return;
+                this._pending.delete(id);
+                reject(err);
+            });
+        });
+    }
+    _rejectPendingRequests(error) {
+        const pending = [...this._pending.values()];
+        this._pending.clear();
+        for (const waiter of pending)
+            waiter.reject(error);
+    }
+    _resetAfterFailedConnect() {
+        const proc = this._proc;
+        this._page = null;
+        this._proc = null;
+        this._buffer = '';
+        this._initialTabIdentities = [];
+        this._rejectPendingRequests(new Error('Playwright MCP connect failed'));
+        PlaywrightMCP._activeInsts.delete(this);
+        if (proc && !proc.killed) {
+            try {
+                proc.kill('SIGKILL');
+            }
+            catch { }
+        }
+    }
+    async connect(opts = {}) {
+        if (this._state === 'connected' && this._page)
+            return this._page;
+        if (this._state === 'connecting')
+            throw new Error('Playwright MCP is already connecting');
+        if (this._state === 'closing')
+            throw new Error('Playwright MCP is closing');
+        if (this._state === 'closed')
+            throw new Error('Playwright MCP session is closed');
+        const mcpPath = findMcpServerPath();
+        if (!mcpPath)
+            throw new Error('Playwright MCP server not found. Install: npm install -D @playwright/mcp');
+        PlaywrightMCP._registerGlobalCleanup();
+        PlaywrightMCP._activeInsts.add(this);
+        this._state = 'connecting';
+        const timeout = opts.timeout ?? DEFAULT_BROWSER_CONNECT_TIMEOUT;
+        return new Promise((resolve, reject) => {
+            const isDebug = process.env.DEBUG?.includes('opencli:mcp');
+            const debugLog = (msg) => isDebug && console.error(`[opencli:mcp] ${msg}`);
+            const useExtension = !!process.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN;
+            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;
+                this._state = 'idle';
+                clearTimeout(timer);
+                this._resetAfterFailedConnect();
+                reject(formatBrowserConnectError({
+                    kind,
+                    timeout,
+                    hasExtensionToken: !!extensionToken,
+                    tokenFingerprint,
+                    stderr: stderrBuffer,
+                    exitCode: extra.exitCode,
+                    rawMessage: extra.rawMessage,
+                }));
+            };
+            const settleSuccess = (pageToResolve) => {
+                if (settled)
+                    return;
+                settled = true;
+                this._state = 'connected';
+                clearTimeout(timer);
+                resolve(pageToResolve);
+            };
+            const timer = setTimeout(() => {
+                debugLog('Connection timed out');
+                settleError(inferConnectFailureKind({
+                    hasExtensionToken: !!extensionToken,
+                    stderr: stderrBuffer,
+                }));
+            }, timeout * 1000);
+            const mcpArgs = buildMcpArgs({
+                mcpPath,
+                executablePath: process.env.OPENCLI_BROWSER_EXECUTABLE_PATH,
+            });
+            if (process.env.OPENCLI_VERBOSE) {
+                console.error(`[opencli] Mode: ${useExtension ? 'extension' : 'standalone'}`);
+                if (useExtension)
+                    console.error(`[opencli] Extension token: fingerprint ${tokenFingerprint}`);
+            }
+            debugLog(`Spawning node ${mcpArgs.join(' ')}`);
+            this._proc = spawn('node', mcpArgs, {
+                stdio: ['pipe', 'pipe', 'pipe'],
+                env: { ...process.env },
+            });
+            // Increase max listeners to avoid warnings
+            this._proc.setMaxListeners(20);
+            if (this._proc.stdout)
+                this._proc.stdout.setMaxListeners(20);
+            const page = new Page((method, params = {}) => this._sendRequest(method, params));
+            this._page = page;
+            this._proc.stdout?.on('data', (chunk) => {
+                this._buffer += chunk.toString();
+                const lines = this._buffer.split('\n');
+                this._buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    debugLog(`RECV: ${line}`);
+                    try {
+                        const parsed = JSON.parse(line);
+                        if (typeof parsed?.id === 'number') {
+                            const waiter = this._pending.get(parsed.id);
+                            if (waiter) {
+                                this._pending.delete(parsed.id);
+                                waiter.resolve(parsed);
+                            }
+                        }
+                    }
+                    catch (e) {
+                        debugLog(`Parse error: ${e}`);
+                    }
+                }
+            });
+            this._proc.stderr?.on('data', (chunk) => {
+                const text = chunk.toString();
+                stderrBuffer = appendLimited(stderrBuffer, text, STDERR_BUFFER_LIMIT);
+                debugLog(`STDERR: ${text}`);
+            });
+            this._proc.on('error', (err) => {
+                debugLog(`Subprocess error: ${err.message}`);
+                this._rejectPendingRequests(new Error(`Playwright MCP process error: ${err.message}`));
+                settleError('process-exit', { rawMessage: err.message });
+            });
+            this._proc.on('close', (code) => {
+                debugLog(`Subprocess closed with code ${code}`);
+                this._rejectPendingRequests(new Error(`Playwright MCP process exited before response${code == null ? '' : ` (code ${code})`}`));
+                if (!settled) {
+                    settleError(inferConnectFailureKind({
+                        hasExtensionToken: !!extensionToken,
+                        stderr: stderrBuffer,
+                        exited: true,
+                    }), { exitCode: code });
+                }
+            });
+            // Initialize: send initialize request
+            debugLog('Waiting for initialize response...');
+            this._sendRequest('initialize', {
+                protocolVersion: '2024-11-05',
+                capabilities: {},
+                clientInfo: { name: 'opencli', version: PKG_VERSION },
+            }).then((resp) => {
+                debugLog('Got initialize response');
+                if (resp.error) {
+                    settleError(inferConnectFailureKind({
+                        hasExtensionToken: !!extensionToken,
+                        stderr: stderrBuffer,
+                        rawMessage: `MCP init failed: ${resp.error.message}`,
+                    }), { rawMessage: resp.error.message });
+                    return;
+                }
+                const initializedMsg = JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n';
+                debugLog(`SEND: ${initializedMsg.trim()}`);
+                this._proc?.stdin?.write(initializedMsg);
+                // Use tabs as a readiness probe and for tab cleanup bookkeeping.
+                debugLog('Fetching initial tabs count...');
+                withTimeoutMs(page.tabs(), INITIAL_TABS_TIMEOUT_MS, 'Timed out fetching initial tabs').then((tabs) => {
+                    debugLog(`Tabs response: ${typeof tabs === 'string' ? tabs : JSON.stringify(tabs)}`);
+                    this._initialTabIdentities = extractTabIdentities(tabs);
+                    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() {
+        if (this._closingPromise)
+            return this._closingPromise;
+        if (this._state === 'closed')
+            return;
+        this._state = 'closing';
+        this._closingPromise = (async () => {
+            try {
+                // Extension mode opens bridge/session tabs that we can clean up best-effort.
+                if (this._page && this._proc && !this._proc.killed) {
+                    try {
+                        const tabs = await withTimeoutMs(this._page.tabs(), TAB_CLEANUP_TIMEOUT_MS, 'Timed out fetching tabs during cleanup');
+                        const tabEntries = extractTabEntries(tabs);
+                        const tabsToClose = diffTabIndexes(this._initialTabIdentities, tabEntries);
+                        for (const index of tabsToClose) {
+                            try {
+                                await this._page.closeTab(index);
+                            }
+                            catch { }
+                        }
+                    }
+                    catch { }
+                }
+                if (this._proc && !this._proc.killed) {
+                    this._proc.kill('SIGTERM');
+                    const exited = await new Promise((res) => {
+                        let done = false;
+                        const finish = (value) => {
+                            if (done)
+                                return;
+                            done = true;
+                            res(value);
+                        };
+                        this._proc?.once('exit', () => finish(true));
+                        setTimeout(() => finish(false), 3000);
+                    });
+                    if (!exited && this._proc && !this._proc.killed) {
+                        try {
+                            this._proc.kill('SIGKILL');
+                        }
+                        catch { }
+                    }
+                }
+            }
+            finally {
+                this._rejectPendingRequests(new Error('Playwright MCP session closed'));
+                this._page = null;
+                this._proc = null;
+                this._state = 'closed';
+                PlaywrightMCP._activeInsts.delete(this);
+            }
+        })();
+        return this._closingPromise;
+    }
+}

package/dist/browser/page.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Page abstraction wrapping JSON-RPC calls to Playwright MCP.
+ */
+import type { IPage } from '../types.js';
+/**
+ * Page abstraction wrapping JSON-RPC calls to Playwright MCP.
+ */
+export declare class Page implements IPage {
+    private _request;
+    constructor(_request: (method: string, params?: Record<string, unknown>) => Promise<Record<string, unknown>>);
+    call(method: string, params?: Record<string, unknown>): Promise<any>;
+    goto(url: string): Promise<void>;
+    evaluate(js: string): Promise<any>;
+    snapshot(opts?: {
+        interactive?: boolean;
+        compact?: boolean;
+        maxDepth?: number;
+        raw?: boolean;
+    }): Promise<any>;
+    click(ref: string): Promise<void>;
+    typeText(ref: string, text: string): Promise<void>;
+    pressKey(key: string): Promise<void>;
+    wait(options: number | {
+        text?: string;
+        time?: number;
+        timeout?: number;
+    }): Promise<void>;
+    tabs(): Promise<any>;
+    closeTab(index?: number): Promise<void>;
+    newTab(): Promise<void>;
+    selectTab(index: number): Promise<void>;
+    networkRequests(includeStatic?: boolean): Promise<any>;
+    consoleMessages(level?: string): Promise<any>;
+    scroll(direction?: string, _amount?: number): Promise<void>;
+    autoScroll(options?: {
+        times?: number;
+        delayMs?: number;
+    }): Promise<void>;
+    installInterceptor(pattern: string): Promise<void>;
+    getInterceptedRequests(): Promise<any[]>;
+}

package/dist/browser/page.js

@@ -0,0 +1,142 @@
+/**
+ * Page abstraction wrapping JSON-RPC calls to Playwright MCP.
+ */
+import { formatSnapshot } from '../snapshotFormatter.js';
+import { normalizeEvaluateSource } from '../pipeline/template.js';
+import { generateInterceptorJs, generateReadInterceptedJs } from '../interceptor.js';
+/**
+ * Page abstraction wrapping JSON-RPC calls to Playwright MCP.
+ */
+export class Page {
+    _request;
+    constructor(_request) {
+        this._request = _request;
+    }
+    async call(method, params = {}) {
+        const resp = await this._request(method, params);
+        if (resp.error)
+            throw new Error(`page.${method}: ${resp.error.message ?? JSON.stringify(resp.error)}`);
+        // Extract text content from MCP result
+        const result = resp.result;
+        if (result?.content) {
+            const textParts = result.content.filter((c) => c.type === 'text');
+            if (textParts.length === 1) {
+                let text = textParts[0].text;
+                // MCP browser_evaluate returns: "[JSON]\n### Ran Playwright code\n```js\n...\n```"
+                // Strip the "### Ran Playwright code" suffix to get clean JSON
+                const codeMarker = text.indexOf('### Ran Playwright code');
+                if (codeMarker !== -1) {
+                    text = text.slice(0, codeMarker).trim();
+                }
+                // Also handle "### Result\n[JSON]" format (some MCP versions)
+                const resultMarker = text.indexOf('### Result\n');
+                if (resultMarker !== -1) {
+                    text = text.slice(resultMarker + '### Result\n'.length).trim();
+                }
+                try {
+                    return JSON.parse(text);
+                }
+                catch {
+                    return text;
+                }
+            }
+        }
+        return result;
+    }
+    // --- High-level methods ---
+    async goto(url) {
+        await this.call('tools/call', { name: 'browser_navigate', arguments: { url } });
+    }
+    async evaluate(js) {
+        // Normalize IIFE format to function format expected by MCP browser_evaluate
+        const normalized = normalizeEvaluateSource(js);
+        return this.call('tools/call', { name: 'browser_evaluate', arguments: { function: normalized } });
+    }
+    async snapshot(opts = {}) {
+        const raw = await this.call('tools/call', { name: 'browser_snapshot', arguments: {} });
+        if (opts.raw)
+            return raw;
+        if (typeof raw === 'string')
+            return formatSnapshot(raw, opts);
+        return raw;
+    }
+    async click(ref) {
+        await this.call('tools/call', { name: 'browser_click', arguments: { element: 'click target', ref } });
+    }
+    async typeText(ref, text) {
+        await this.call('tools/call', { name: 'browser_type', arguments: { element: 'type target', ref, text } });
+    }
+    async pressKey(key) {
+        await this.call('tools/call', { name: 'browser_press_key', arguments: { key } });
+    }
+    async wait(options) {
+        if (typeof options === 'number') {
+            await this.call('tools/call', { name: 'browser_wait_for', arguments: { time: options } });
+        }
+        else {
+            // Pass directly to native wait_for, which supports natively awaiting text strings without heavy DOM polling
+            await this.call('tools/call', { name: 'browser_wait_for', arguments: options });
+        }
+    }
+    async tabs() {
+        return this.call('tools/call', { name: 'browser_tabs', arguments: { action: 'list' } });
+    }
+    async closeTab(index) {
+        await this.call('tools/call', { name: 'browser_tabs', arguments: { action: 'close', ...(index !== undefined ? { index } : {}) } });
+    }
+    async newTab() {
+        await this.call('tools/call', { name: 'browser_tabs', arguments: { action: 'new' } });
+    }
+    async selectTab(index) {
+        await this.call('tools/call', { name: 'browser_tabs', arguments: { action: 'select', index } });
+    }
+    async networkRequests(includeStatic = false) {
+        return this.call('tools/call', { name: 'browser_network_requests', arguments: { includeStatic } });
+    }
+    async consoleMessages(level = 'info') {
+        return this.call('tools/call', { name: 'browser_console_messages', arguments: { level } });
+    }
+    async scroll(direction = 'down', _amount = 500) {
+        await this.call('tools/call', { name: 'browser_press_key', arguments: { key: direction === 'down' ? 'PageDown' : 'PageUp' } });
+    }
+    async autoScroll(options = {}) {
+        const times = options.times ?? 3;
+        const delayMs = options.delayMs ?? 2000;
+        const js = `
+      async () => {
+        const maxTimes = ${times};
+        const maxWaitMs = ${delayMs};
+        for (let i = 0; i < maxTimes; i++) {
+          const lastHeight = document.body.scrollHeight;
+          window.scrollTo(0, lastHeight);
+          await new Promise(resolve => {
+            let timeoutId;
+            const observer = new MutationObserver(() => {
+              if (document.body.scrollHeight > lastHeight) {
+                clearTimeout(timeoutId);
+                observer.disconnect();
+                setTimeout(resolve, 100); // Small debounce for rendering
+              }
+            });
+            observer.observe(document.body, { childList: true, subtree: true });
+            timeoutId = setTimeout(() => {
+              observer.disconnect();
+              resolve(null);
+            }, maxWaitMs);
+          });
+        }
+      }
+    `;
+        await this.evaluate(js);
+    }
+    async installInterceptor(pattern) {
+        await this.evaluate(generateInterceptorJs(JSON.stringify(pattern), {
+            arrayName: '__opencli_xhr',
+            patchGuard: '__opencli_interceptor_patched',
+        }));
+    }
+    async getInterceptedRequests() {
+        const result = await this.evaluate(generateReadInterceptedJs('__opencli_xhr'));
+        return result || [];
+    }
+}

package/dist/browser/tabs.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Browser tab management helpers: extract, diff, and cleanup tab state.
+ */
+export declare function extractTabEntries(raw: unknown): Array<{
+    index: number;
+    identity: string;
+}>;
+export declare function extractTabIdentities(raw: unknown): string[];
+export declare function diffTabIndexes(initialIdentities: string[], currentTabs: Array<{
+    index: number;
+    identity: string;
+}>): number[];
+export declare function appendLimited(current: string, chunk: string, limit: number): string;

package/dist/browser/tabs.js

@@ -0,0 +1,70 @@
+/**
+ * Browser tab management helpers: extract, diff, and cleanup tab state.
+ */
+export function extractTabEntries(raw) {
+    if (Array.isArray(raw)) {
+        return raw.map((tab, index) => ({
+            index,
+            identity: [
+                tab?.id ?? '',
+                tab?.url ?? '',
+                tab?.title ?? '',
+                tab?.name ?? '',
+            ].join('|'),
+        }));
+    }
+    if (typeof raw === 'string') {
+        return raw
+            .split('\n')
+            .map(line => line.trim())
+            .filter(Boolean)
+            .map(line => {
+            // Match actual Playwright MCP format: "- 0: (current) [title](url)"  or  "- 1: [title](url)"
+            const mcpMatch = line.match(/^-\s+(\d+):\s*(.*)$/);
+            if (mcpMatch) {
+                return {
+                    index: parseInt(mcpMatch[1], 10),
+                    identity: mcpMatch[2].trim() || `tab-${mcpMatch[1]}`,
+                };
+            }
+            // Legacy format: "Tab 0 ..."
+            const legacyMatch = line.match(/Tab\s+(\d+)\s*(.*)$/);
+            if (legacyMatch) {
+                return {
+                    index: parseInt(legacyMatch[1], 10),
+                    identity: legacyMatch[2].trim() || `tab-${legacyMatch[1]}`,
+                };
+            }
+            return null;
+        })
+            .filter((entry) => entry !== null);
+    }
+    return [];
+}
+export function extractTabIdentities(raw) {
+    return extractTabEntries(raw).map(tab => tab.identity);
+}
+export function diffTabIndexes(initialIdentities, currentTabs) {
+    if (initialIdentities.length === 0 || currentTabs.length === 0)
+        return [];
+    const remaining = new Map();
+    for (const identity of initialIdentities) {
+        remaining.set(identity, (remaining.get(identity) ?? 0) + 1);
+    }
+    const tabsToClose = [];
+    for (const tab of currentTabs) {
+        const count = remaining.get(tab.identity) ?? 0;
+        if (count > 0) {
+            remaining.set(tab.identity, count - 1);
+            continue;
+        }
+        tabsToClose.push(tab.index);
+    }
+    return tabsToClose.sort((a, b) => b - a);
+}
+export function appendLimited(current, chunk, limit) {
+    const next = current + chunk;
+    if (next.length <= limit)
+        return next;
+    return next.slice(-limit);
+}

package/dist/browser.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { PlaywrightMCP, __test__ } from './browser.js';
+import { PlaywrightMCP, __test__ } from './browser/index.js';
 describe('browser helpers', () => {
     it('creates JSON-RPC requests with unique ids', () => {
         const first = __test__.createJsonRpcRequest('tools/call', { name: 'browser_tabs' });

package/dist/completion.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shell tab-completion support for opencli.
+ *
+ * Provides:
+ *  - Shell script generators for bash, zsh, and fish
+ *  - Dynamic completion logic that returns candidates for the current cursor position
+ */
+/**
+ * Return completion candidates given the current command-line words and cursor index.
+ *
+ * @param words  - The argv after 'opencli' (words[0] is the first arg, e.g. site name)
+ * @param cursor - 1-based position of the word being completed (1 = first arg)
+ */
+export declare function getCompletions(words: string[], cursor: number): string[];
+export declare function bashCompletionScript(): string;
+export declare function zshCompletionScript(): string;
+export declare function fishCompletionScript(): string;
+/**
+ * Print the completion script for the requested shell.
+ */
+export declare function printCompletionScript(shell: string): void;