@jackwener/opencli 0.4.2 → 0.4.4

package/dist/doctor.js

@@ -0,0 +1,372 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { PlaywrightMCP, discoverChromeEndpoint, getTokenFingerprint } from './browser.js';
+import { browserSession } from './runtime.js';
+const PLAYWRIGHT_SERVER_NAME = 'playwright';
+const PLAYWRIGHT_TOKEN_ENV = 'PLAYWRIGHT_MCP_EXTENSION_TOKEN';
+const PLAYWRIGHT_EXTENSION_ID = 'mmlmfjhmonkocbjadbfplnigmagldckm';
+const TOKEN_LINE_RE = /^(\s*export\s+PLAYWRIGHT_MCP_EXTENSION_TOKEN=)(['"]?)([^'"\\\n]+)\2\s*$/m;
+function label(status) {
+    return `[${status}]`;
+}
+function statusLine(status, text) {
+    return `${label(status)} ${text}`;
+}
+function tokenSummary(token, fingerprint) {
+    if (!token)
+        return 'missing';
+    return `configured (${fingerprint})`;
+}
+export function getDefaultShellRcPath() {
+    const shell = process.env.SHELL ?? '';
+    if (shell.endsWith('/bash'))
+        return path.join(os.homedir(), '.bashrc');
+    if (shell.endsWith('/fish'))
+        return path.join(os.homedir(), '.config', 'fish', 'config.fish');
+    return path.join(os.homedir(), '.zshrc');
+}
+export function getDefaultMcpConfigPaths(cwd = process.cwd()) {
+    const home = os.homedir();
+    const candidates = [
+        path.join(home, '.codex', 'config.toml'),
+        path.join(home, '.codex', 'mcp.json'),
+        path.join(home, '.cursor', 'mcp.json'),
+        path.join(home, '.config', 'opencode', 'opencode.json'),
+        path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
+        path.join(home, '.config', 'Claude', 'claude_desktop_config.json'),
+        path.join(cwd, '.cursor', 'mcp.json'),
+        path.join(cwd, '.vscode', 'mcp.json'),
+        path.join(cwd, '.opencode', 'opencode.json'),
+    ];
+    return [...new Set(candidates)];
+}
+export function readTokenFromShellContent(content) {
+    const m = content.match(TOKEN_LINE_RE);
+    return m?.[3] ?? null;
+}
+export function upsertShellToken(content, token) {
+    const nextLine = `export ${PLAYWRIGHT_TOKEN_ENV}="${token}"`;
+    if (!content.trim())
+        return `${nextLine}\n`;
+    if (TOKEN_LINE_RE.test(content))
+        return content.replace(TOKEN_LINE_RE, `$1"${token}"`);
+    return `${content.replace(/\s*$/, '')}\n${nextLine}\n`;
+}
+function readJsonConfigToken(content) {
+    try {
+        const parsed = JSON.parse(content);
+        return readTokenFromJsonObject(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+function readTokenFromJsonObject(parsed) {
+    const direct = parsed?.mcpServers?.[PLAYWRIGHT_SERVER_NAME]?.env?.[PLAYWRIGHT_TOKEN_ENV];
+    if (typeof direct === 'string' && direct)
+        return direct;
+    const opencode = parsed?.mcp?.[PLAYWRIGHT_SERVER_NAME]?.env?.[PLAYWRIGHT_TOKEN_ENV];
+    if (typeof opencode === 'string' && opencode)
+        return opencode;
+    return null;
+}
+export function upsertJsonConfigToken(content, token) {
+    const parsed = content.trim() ? JSON.parse(content) : {};
+    if (parsed?.mcpServers) {
+        parsed.mcpServers[PLAYWRIGHT_SERVER_NAME] = parsed.mcpServers[PLAYWRIGHT_SERVER_NAME] ?? {
+            command: 'npx',
+            args: ['-y', '@playwright/mcp@latest', '--extension'],
+        };
+        parsed.mcpServers[PLAYWRIGHT_SERVER_NAME].env = parsed.mcpServers[PLAYWRIGHT_SERVER_NAME].env ?? {};
+        parsed.mcpServers[PLAYWRIGHT_SERVER_NAME].env[PLAYWRIGHT_TOKEN_ENV] = token;
+    }
+    else {
+        parsed.mcp = parsed.mcp ?? {};
+        parsed.mcp[PLAYWRIGHT_SERVER_NAME] = parsed.mcp[PLAYWRIGHT_SERVER_NAME] ?? {
+            command: ['npx', '-y', '@playwright/mcp@latest', '--extension'],
+            enabled: true,
+            type: 'local',
+        };
+        parsed.mcp[PLAYWRIGHT_SERVER_NAME].env = parsed.mcp[PLAYWRIGHT_SERVER_NAME].env ?? {};
+        parsed.mcp[PLAYWRIGHT_SERVER_NAME].env[PLAYWRIGHT_TOKEN_ENV] = token;
+    }
+    return `${JSON.stringify(parsed, null, 2)}\n`;
+}
+export function readTomlConfigToken(content) {
+    const sectionMatch = content.match(/\[mcp_servers\.playwright\.env\][\s\S]*?(?=\n\[|$)/);
+    if (!sectionMatch)
+        return null;
+    const tokenMatch = sectionMatch[0].match(/^\s*PLAYWRIGHT_MCP_EXTENSION_TOKEN\s*=\s*"([^"\n]+)"/m);
+    return tokenMatch?.[1] ?? null;
+}
+export function upsertTomlConfigToken(content, token) {
+    const envSectionRe = /(\[mcp_servers\.playwright\.env\][\s\S]*?)(?=\n\[|$)/;
+    const tokenLine = `PLAYWRIGHT_MCP_EXTENSION_TOKEN = "${token}"`;
+    if (envSectionRe.test(content)) {
+        return content.replace(envSectionRe, (section) => {
+            if (/^\s*PLAYWRIGHT_MCP_EXTENSION_TOKEN\s*=/m.test(section)) {
+                return section.replace(/^\s*PLAYWRIGHT_MCP_EXTENSION_TOKEN\s*=.*$/m, tokenLine);
+            }
+            return `${section.replace(/\s*$/, '')}\n${tokenLine}\n`;
+        });
+    }
+    const baseSectionRe = /(\[mcp_servers\.playwright\][\s\S]*?)(?=\n\[|$)/;
+    if (baseSectionRe.test(content)) {
+        return content.replace(baseSectionRe, (section) => `${section.replace(/\s*$/, '')}\n\n[mcp_servers.playwright.env]\n${tokenLine}\n`);
+    }
+    const prefix = content.trim() ? `${content.replace(/\s*$/, '')}\n\n` : '';
+    return `${prefix}[mcp_servers.playwright]\ntype = "stdio"\ncommand = "npx"\nargs = ["-y", "@playwright/mcp@latest", "--extension"]\n\n[mcp_servers.playwright.env]\n${tokenLine}\n`;
+}
+function fileExists(filePath) {
+    try {
+        return fs.existsSync(filePath);
+    }
+    catch {
+        return false;
+    }
+}
+function canWrite(filePath) {
+    try {
+        if (fileExists(filePath)) {
+            fs.accessSync(filePath, fs.constants.W_OK);
+            return true;
+        }
+        fs.accessSync(path.dirname(filePath), fs.constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readConfigStatus(filePath) {
+    const format = filePath.endsWith('.toml') ? 'toml' : 'json';
+    if (!fileExists(filePath)) {
+        return { path: filePath, exists: false, format, token: null, fingerprint: null, writable: canWrite(filePath) };
+    }
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const token = format === 'toml' ? readTomlConfigToken(content) : readJsonConfigToken(content);
+        return {
+            path: filePath,
+            exists: true,
+            format,
+            token,
+            fingerprint: getTokenFingerprint(token ?? undefined),
+            writable: canWrite(filePath),
+        };
+    }
+    catch (error) {
+        return {
+            path: filePath,
+            exists: true,
+            format,
+            token: null,
+            fingerprint: null,
+            writable: canWrite(filePath),
+            parseError: error?.message ?? String(error),
+        };
+    }
+}
+async function extractTokenViaCdp() {
+    if (!(process.env.OPENCLI_USE_CDP === '1' || process.env.OPENCLI_CDP_ENDPOINT))
+        return null;
+    const candidates = [
+        `chrome-extension://${PLAYWRIGHT_EXTENSION_ID}/options.html`,
+        `chrome-extension://${PLAYWRIGHT_EXTENSION_ID}/popup.html`,
+        `chrome-extension://${PLAYWRIGHT_EXTENSION_ID}/connect.html`,
+        `chrome-extension://${PLAYWRIGHT_EXTENSION_ID}/index.html`,
+    ];
+    const result = await browserSession(PlaywrightMCP, async (page) => {
+        for (const url of candidates) {
+            try {
+                await page.goto(url);
+                await page.wait(1);
+                const token = await page.evaluate(`() => {
+          const values = new Set();
+          const push = (value) => {
+            if (!value || typeof value !== 'string') return;
+            for (const match of value.matchAll(/[A-Za-z0-9_-]{24,}/g)) values.add(match[0]);
+          };
+          document.querySelectorAll('input, textarea, code, pre, span, div').forEach((el) => {
+            push(el.value);
+            push(el.textContent || '');
+            push(el.getAttribute && el.getAttribute('value'));
+          });
+          return Array.from(values);
+        }`);
+                const matches = Array.isArray(token) ? token.filter((v) => v.length >= 24) : [];
+                if (matches.length > 0)
+                    return matches.sort((a, b) => b.length - a.length)[0];
+            }
+            catch { }
+        }
+        return null;
+    });
+    return typeof result === 'string' && result ? result : null;
+}
+export async function runBrowserDoctor(opts = {}) {
+    const envToken = process.env[PLAYWRIGHT_TOKEN_ENV] ?? null;
+    const remoteDebuggingEndpoint = await discoverChromeEndpoint().catch(() => null);
+    const shellPath = opts.shellRc ?? getDefaultShellRcPath();
+    const shellFiles = [shellPath].map((filePath) => {
+        if (!fileExists(filePath))
+            return { path: filePath, exists: false, token: null, fingerprint: null };
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const token = readTokenFromShellContent(content);
+        return { path: filePath, exists: true, token, fingerprint: getTokenFingerprint(token ?? undefined) };
+    });
+    const configPaths = opts.configPaths?.length ? opts.configPaths : getDefaultMcpConfigPaths();
+    const configs = configPaths.map(readConfigStatus);
+    const cdpToken = !opts.token && !envToken ? await extractTokenViaCdp().catch(() => null) : null;
+    const allTokens = [
+        opts.token ?? null,
+        envToken,
+        ...shellFiles.map(s => s.token),
+        ...configs.map(c => c.token),
+        cdpToken,
+    ].filter((v) => !!v);
+    const uniqueTokens = [...new Set(allTokens)];
+    const recommendedToken = opts.token ?? envToken ?? (uniqueTokens.length === 1 ? uniqueTokens[0] : cdpToken) ?? null;
+    const report = {
+        cliVersion: opts.cliVersion,
+        envToken,
+        envFingerprint: getTokenFingerprint(envToken ?? undefined),
+        shellFiles,
+        configs,
+        remoteDebuggingEnabled: !!remoteDebuggingEndpoint,
+        remoteDebuggingEndpoint,
+        cdpEnabled: process.env.OPENCLI_USE_CDP === '1' || !!process.env.OPENCLI_CDP_ENDPOINT,
+        cdpToken,
+        cdpFingerprint: getTokenFingerprint(cdpToken ?? undefined),
+        recommendedToken,
+        recommendedFingerprint: getTokenFingerprint(recommendedToken ?? undefined),
+        warnings: [],
+        issues: [],
+    };
+    if (!envToken)
+        report.issues.push(`Current environment is missing ${PLAYWRIGHT_TOKEN_ENV}.`);
+    if (!shellFiles.some(s => s.token))
+        report.issues.push('Shell startup file does not export PLAYWRIGHT_MCP_EXTENSION_TOKEN.');
+    if (!configs.some(c => c.token))
+        report.issues.push('No scanned MCP config currently contains a Playwright extension token.');
+    if (uniqueTokens.length > 1)
+        report.issues.push('Detected inconsistent Playwright MCP tokens across env/config files.');
+    if (!report.remoteDebuggingEnabled)
+        report.warnings.push('Chrome remote debugging appears to be disabled or Chrome is not currently exposing a DevTools endpoint.');
+    for (const config of configs) {
+        if (config.parseError)
+            report.warnings.push(`Could not parse ${config.path}: ${config.parseError}`);
+    }
+    if (!recommendedToken) {
+        if (report.cdpEnabled)
+            report.warnings.push('CDP is enabled, but no token could be extracted automatically from the extension UI.');
+        else
+            report.warnings.push('No token source found. Enable OPENCLI_USE_CDP=1 to allow a best-effort token read from the extension page.');
+    }
+    return report;
+}
+export function renderBrowserDoctorReport(report) {
+    const tokenFingerprints = [
+        report.envFingerprint,
+        ...report.shellFiles.map(shell => shell.fingerprint),
+        ...report.configs.filter(config => config.exists).map(config => config.fingerprint),
+    ].filter((value) => !!value);
+    const uniqueFingerprints = [...new Set(tokenFingerprints)];
+    const hasMismatch = uniqueFingerprints.length > 1;
+    const lines = [`opencli v${report.cliVersion ?? 'unknown'} doctor`, ''];
+    lines.push(statusLine(report.remoteDebuggingEnabled ? 'OK' : 'WARN', `Chrome remote debugging: ${report.remoteDebuggingEnabled ? 'enabled' : 'disabled'}`));
+    if (report.remoteDebuggingEndpoint)
+        lines.push(`     ${report.remoteDebuggingEndpoint}`);
+    const envStatus = !report.envToken ? 'MISSING' : hasMismatch ? 'MISMATCH' : 'OK';
+    lines.push(statusLine(envStatus, `Environment token: ${tokenSummary(report.envToken, report.envFingerprint)}`));
+    for (const shell of report.shellFiles) {
+        const shellStatus = !shell.token ? 'MISSING' : hasMismatch ? 'MISMATCH' : 'OK';
+        lines.push(statusLine(shellStatus, `Shell file ${shell.path}: ${tokenSummary(shell.token, shell.fingerprint)}`));
+    }
+    const existingConfigs = report.configs.filter(config => config.exists);
+    const missingConfigCount = report.configs.length - existingConfigs.length;
+    if (existingConfigs.length > 0) {
+        for (const config of existingConfigs) {
+            const parseSuffix = config.parseError ? ` (parse error: ${config.parseError})` : '';
+            const configStatus = config.parseError
+                ? 'WARN'
+                : !config.token
+                    ? 'MISSING'
+                    : hasMismatch
+                        ? 'MISMATCH'
+                        : 'OK';
+            lines.push(statusLine(configStatus, `MCP config ${config.path}: ${tokenSummary(config.token, config.fingerprint)}${parseSuffix}`));
+        }
+    }
+    else {
+        lines.push(statusLine('MISSING', 'MCP config: no existing config files found in scanned locations'));
+    }
+    if (missingConfigCount > 0)
+        lines.push(`     Other scanned config locations not present: ${missingConfigCount}`);
+    if (report.cdpEnabled) {
+        const cdpStatus = report.cdpToken ? 'OK' : 'WARN';
+        lines.push(statusLine(cdpStatus, `CDP token probe: ${tokenSummary(report.cdpToken, report.cdpFingerprint)}`));
+    }
+    lines.push('');
+    lines.push(statusLine(hasMismatch ? 'MISMATCH' : report.recommendedToken ? 'OK' : 'WARN', `Recommended token fingerprint: ${report.recommendedFingerprint ?? 'unavailable'}`));
+    if (report.issues.length) {
+        lines.push('', 'Issues:');
+        for (const issue of report.issues)
+            lines.push(`- ${issue}`);
+    }
+    if (report.warnings.length) {
+        lines.push('', 'Warnings:');
+        for (const warning of report.warnings)
+            lines.push(`- ${warning}`);
+    }
+    return lines.join('\n');
+}
+async function confirmPrompt(question) {
+    const rl = createInterface({ input, output });
+    try {
+        const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
+        return answer === 'y' || answer === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
+function writeFileWithMkdir(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf-8');
+}
+export async function applyBrowserDoctorFix(report, opts = {}) {
+    const token = opts.token ?? report.recommendedToken;
+    if (!token)
+        throw new Error('No Playwright MCP token is available to write. Provide --token or enable CDP token probing first.');
+    const plannedWrites = [];
+    const shellPath = opts.shellRc ?? report.shellFiles[0]?.path ?? getDefaultShellRcPath();
+    plannedWrites.push(shellPath);
+    for (const config of report.configs) {
+        if (!config.writable)
+            continue;
+        plannedWrites.push(config.path);
+    }
+    if (!opts.yes) {
+        const ok = await confirmPrompt(`Update ${plannedWrites.length} file(s) with Playwright MCP token fingerprint ${getTokenFingerprint(token)}?`);
+        if (!ok)
+            return [];
+    }
+    const written = [];
+    const shellBefore = fileExists(shellPath) ? fs.readFileSync(shellPath, 'utf-8') : '';
+    writeFileWithMkdir(shellPath, upsertShellToken(shellBefore, token));
+    written.push(shellPath);
+    for (const config of report.configs) {
+        if (!config.writable || config.parseError)
+            continue;
+        const before = fileExists(config.path) ? fs.readFileSync(config.path, 'utf-8') : '';
+        const next = config.format === 'toml' ? upsertTomlConfigToken(before, token) : upsertJsonConfigToken(before, token);
+        writeFileWithMkdir(config.path, next);
+        written.push(config.path);
+    }
+    process.env[PLAYWRIGHT_TOKEN_ENV] = token;
+    return written;
+}

package/dist/doctor.test.d.ts

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

package/dist/doctor.test.js

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+import { readTokenFromShellContent, renderBrowserDoctorReport, upsertShellToken, readTomlConfigToken, upsertTomlConfigToken, upsertJsonConfigToken, } from './doctor.js';
+describe('shell token helpers', () => {
+    it('reads token from shell export', () => {
+        expect(readTokenFromShellContent('export PLAYWRIGHT_MCP_EXTENSION_TOKEN="abc123"\n')).toBe('abc123');
+    });
+    it('appends token export when missing', () => {
+        const next = upsertShellToken('export PATH="/usr/bin"\n', 'abc123');
+        expect(next).toContain('export PLAYWRIGHT_MCP_EXTENSION_TOKEN="abc123"');
+    });
+    it('replaces token export when present', () => {
+        const next = upsertShellToken('export PLAYWRIGHT_MCP_EXTENSION_TOKEN="old"\n', 'new');
+        expect(next).toContain('export PLAYWRIGHT_MCP_EXTENSION_TOKEN="new"');
+        expect(next).not.toContain('"old"');
+    });
+});
+describe('toml token helpers', () => {
+    it('reads token from playwright env section', () => {
+        const content = `
+[mcp_servers.playwright.env]
+PLAYWRIGHT_MCP_EXTENSION_TOKEN = "abc123"
+`;
+        expect(readTomlConfigToken(content)).toBe('abc123');
+    });
+    it('updates token inside existing env section', () => {
+        const content = `
+[mcp_servers.playwright.env]
+PLAYWRIGHT_MCP_EXTENSION_TOKEN = "old"
+`;
+        const next = upsertTomlConfigToken(content, 'new');
+        expect(next).toContain('PLAYWRIGHT_MCP_EXTENSION_TOKEN = "new"');
+        expect(next).not.toContain('"old"');
+    });
+    it('creates env section when missing', () => {
+        const content = `
+[mcp_servers.playwright]
+type = "stdio"
+`;
+        const next = upsertTomlConfigToken(content, 'abc123');
+        expect(next).toContain('[mcp_servers.playwright.env]');
+        expect(next).toContain('PLAYWRIGHT_MCP_EXTENSION_TOKEN = "abc123"');
+    });
+});
+describe('json token helpers', () => {
+    it('writes token into standard mcpServers config', () => {
+        const next = upsertJsonConfigToken(JSON.stringify({
+            mcpServers: {
+                playwright: {
+                    command: 'npx',
+                    args: ['-y', '@playwright/mcp@latest', '--extension'],
+                },
+            },
+        }), 'abc123');
+        const parsed = JSON.parse(next);
+        expect(parsed.mcpServers.playwright.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN).toBe('abc123');
+    });
+    it('writes token into opencode mcp config', () => {
+        const next = upsertJsonConfigToken(JSON.stringify({
+            $schema: 'https://opencode.ai/config.json',
+            mcp: {
+                playwright: {
+                    command: ['npx', '-y', '@playwright/mcp@latest', '--extension'],
+                    enabled: true,
+                    type: 'local',
+                },
+            },
+        }), 'abc123');
+        const parsed = JSON.parse(next);
+        expect(parsed.mcp.playwright.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN).toBe('abc123');
+    });
+});
+describe('doctor report rendering', () => {
+    it('renders OK-style report when tokens match', () => {
+        const text = renderBrowserDoctorReport({
+            envToken: 'abc123',
+            envFingerprint: 'fp1',
+            shellFiles: [{ path: '/tmp/.zshrc', exists: true, token: 'abc123', fingerprint: 'fp1' }],
+            configs: [{ path: '/tmp/mcp.json', exists: true, format: 'json', token: 'abc123', fingerprint: 'fp1', writable: true }],
+            remoteDebuggingEnabled: true,
+            remoteDebuggingEndpoint: 'ws://127.0.0.1:9222/devtools/browser/test',
+            cdpEnabled: false,
+            cdpToken: null,
+            cdpFingerprint: null,
+            recommendedToken: 'abc123',
+            recommendedFingerprint: 'fp1',
+            warnings: [],
+            issues: [],
+        });
+        expect(text).toContain('[OK] Chrome remote debugging: enabled');
+        expect(text).toContain('[OK] Environment token: configured (fp1)');
+        expect(text).toContain('[OK] MCP config /tmp/mcp.json: configured (fp1)');
+    });
+    it('renders MISMATCH-style report when fingerprints differ', () => {
+        const text = renderBrowserDoctorReport({
+            envToken: 'abc123',
+            envFingerprint: 'fp1',
+            shellFiles: [{ path: '/tmp/.zshrc', exists: true, token: 'def456', fingerprint: 'fp2' }],
+            configs: [{ path: '/tmp/mcp.json', exists: true, format: 'json', token: 'abc123', fingerprint: 'fp1', writable: true }],
+            remoteDebuggingEnabled: false,
+            remoteDebuggingEndpoint: null,
+            cdpEnabled: false,
+            cdpToken: null,
+            cdpFingerprint: null,
+            recommendedToken: 'abc123',
+            recommendedFingerprint: 'fp1',
+            warnings: ['Chrome remote debugging appears to be disabled or Chrome is not currently exposing a DevTools endpoint.'],
+            issues: ['Detected inconsistent Playwright MCP tokens across env/config files.'],
+        });
+        expect(text).toContain('[WARN] Chrome remote debugging: disabled');
+        expect(text).toContain('[MISMATCH] Environment token: configured (fp1)');
+        expect(text).toContain('[MISMATCH] Shell file /tmp/.zshrc: configured (fp2)');
+        expect(text).toContain('[MISMATCH] Recommended token fingerprint: fp1');
+    });
+});

package/dist/main.js

@@ -24,12 +24,27 @@ await discoverClis(BUILTIN_CLIS, USER_CLIS);
 const program = new Command();
 program.name('opencli').description('Make any website your CLI. Zero setup. AI-powered.').version(PKG_VERSION);
 // ── Built-in commands ──────────────────────────────────────────────────────
-program.command('list').description('List all available CLI commands').option('--json', 'JSON output')
+program.command('list').description('List all available CLI commands').option('-f, --format <fmt>', 'Output format: table, json, yaml, md, csv', 'table').option('--json', 'JSON output (deprecated)')
     .action((opts) => {
     const registry = getRegistry();
     const commands = [...registry.values()].sort((a, b) => fullName(a).localeCompare(fullName(b)));
-    if (opts.json) {
-        console.log(JSON.stringify(commands.map(c => ({ command: fullName(c), site: c.site, name: c.name, description: c.description, strategy: strategyLabel(c), browser: c.browser, args: c.args.map(a => a.name) })), null, 2));
+    const rows = commands.map(c => ({
+        command: fullName(c),
+        site: c.site,
+        name: c.name,
+        description: c.description,
+        strategy: strategyLabel(c),
+        browser: c.browser,
+        args: c.args.map(a => a.name).join(', '),
+    }));
+    const fmt = opts.json && opts.format === 'table' ? 'json' : opts.format;
+    if (fmt !== 'table') {
+        renderOutput(rows, {
+            fmt,
+            columns: ['command', 'site', 'name', 'description', 'strategy', 'browser', 'args'],
+            title: 'opencli/list',
+            source: 'opencli list',
+        });
         return;
     }
     const sites = new Map();
@@ -77,6 +92,31 @@ program.command('cascade').description('Strategy cascade: find simplest working
     });
     console.log(renderCascadeResult(result));
 });
+program.command('doctor')
+    .description('Diagnose Playwright MCP Bridge, token consistency, and Chrome remote debugging')
+    .option('--fix', 'Apply suggested fixes to shell rc and detected MCP configs', false)
+    .option('-y, --yes', 'Skip confirmation prompts when applying fixes', false)
+    .option('--token <token>', 'Override token to write instead of auto-detecting')
+    .option('--shell-rc <path>', 'Shell startup file to update')
+    .option('--mcp-config <paths>', 'Comma-separated MCP config paths to scan/update')
+    .action(async (opts) => {
+    const { runBrowserDoctor, renderBrowserDoctorReport, applyBrowserDoctorFix } = await import('./doctor.js');
+    const configPaths = opts.mcpConfig ? String(opts.mcpConfig).split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+    const report = await runBrowserDoctor({ token: opts.token, shellRc: opts.shellRc, configPaths, cliVersion: PKG_VERSION });
+    console.log(renderBrowserDoctorReport(report));
+    if (opts.fix) {
+        const written = await applyBrowserDoctorFix(report, { fix: true, yes: opts.yes, token: opts.token, shellRc: opts.shellRc, configPaths });
+        console.log();
+        if (written.length > 0) {
+            console.log(chalk.green('Updated files:'));
+            for (const filePath of written)
+                console.log(`- ${filePath}`);
+        }
+        else {
+            console.log(chalk.yellow('No files were changed.'));
+        }
+    }
+});
 // ── Dynamic site commands ──────────────────────────────────────────────────
 const registry = getRegistry();
 const siteGroups = new Map();
@@ -96,7 +136,7 @@ for (const [, cmd] of registry) {
         else
             subCmd.option(flag, arg.help ?? '');
     }
-    subCmd.option('-f, --format <fmt>', 'Output format: table, json, md, csv', 'table').option('-v, --verbose', 'Debug output', false);
+    subCmd.option('-f, --format <fmt>', 'Output format: table, json, yaml, md, csv', 'table').option('-v, --verbose', 'Debug output', false);
     subCmd.action(async (actionOpts) => {
         const startTime = Date.now();
         const kwargs = {};
@@ -108,9 +148,11 @@ for (const [, cmd] of registry) {
                 kwargs[arg.name] = arg.default;
         }
         try {
+            if (actionOpts.verbose)
+                process.env.OPENCLI_VERBOSE = '1';
             let result;
             if (cmd.browser) {
-                result = await browserSession(PlaywrightMCP, async (page) => runWithTimeout(executeCommand(cmd, page, kwargs, actionOpts.verbose), { timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT, label: fullName(cmd) }));
+                result = await browserSession(PlaywrightMCP, async (page) => runWithTimeout(executeCommand(cmd, page, kwargs, actionOpts.verbose), { timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT, label: fullName(cmd) }), { forceExtension: cmd.forceExtension });
             }
             else {
                 result = await executeCommand(cmd, null, kwargs, actionOpts.verbose);

package/dist/output.test.d.ts

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

package/dist/output.test.js

@@ -0,0 +1,20 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render } from './output.js';
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe('render', () => {
+    it('renders YAML output', () => {
+        const log = vi.spyOn(console, 'log').mockImplementation(() => { });
+        render([{ title: 'Hello', rank: 1 }], { fmt: 'yaml' });
+        expect(log).toHaveBeenCalledOnce();
+        expect(log.mock.calls[0]?.[0]).toContain('- title: Hello');
+        expect(log.mock.calls[0]?.[0]).toContain('rank: 1');
+    });
+    it('renders yml alias as YAML output', () => {
+        const log = vi.spyOn(console, 'log').mockImplementation(() => { });
+        render({ title: 'Hello' }, { fmt: 'yml' });
+        expect(log).toHaveBeenCalledOnce();
+        expect(log.mock.calls[0]?.[0]).toContain('title: Hello');
+    });
+});

package/dist/registry.d.ts

@@ -33,6 +33,8 @@ export interface CliCommand {
     /** Internal: lazy-loaded TS module support */
     _lazy?: boolean;
     _modulePath?: string;
+    /** Force extension bridge mode (bypass CDP), for anti-bot sites */
+    forceExtension?: boolean;
 }
 export interface CliOptions {
     site: string;
@@ -46,6 +48,8 @@ export interface CliOptions {
     func?: (page: IPage | null, kwargs: Record<string, any>, debug?: boolean) => Promise<any>;
     pipeline?: any[];
     timeoutSeconds?: number;
+    /** Force extension bridge mode (bypass CDP), for anti-bot sites */
+    forceExtension?: boolean;
 }
 export declare function cli(opts: CliOptions): CliCommand;
 export declare function getRegistry(): Map<string, CliCommand>;

package/dist/registry.js

@@ -23,6 +23,7 @@ export function cli(opts) {
         func: opts.func,
         pipeline: opts.pipeline,
         timeoutSeconds: opts.timeoutSeconds,
+        forceExtension: opts.forceExtension,
     };
     const key = fullName(cmd);
     _registry.set(key, cmd);

package/dist/runtime.d.ts

@@ -10,4 +10,6 @@ export declare function runWithTimeout<T>(promise: Promise<T>, opts: {
     timeout: number;
     label?: string;
 }): Promise<T>;
-export declare function browserSession<T>(BrowserFactory: new () => any, fn: (page: IPage) => Promise<T>): Promise<T>;
+export declare function browserSession<T>(BrowserFactory: new () => any, fn: (page: IPage) => Promise<T>, opts?: {
+    forceExtension?: boolean;
+}): Promise<T>;

package/dist/runtime.js

@@ -15,10 +15,10 @@ export async function runWithTimeout(promise, opts) {
             .catch((err) => { clearTimeout(timer); reject(err); });
     });
 }
-export async function browserSession(BrowserFactory, fn) {
+export async function browserSession(BrowserFactory, fn, opts) {
     const mcp = new BrowserFactory();
     try {
-        const page = await mcp.connect({ timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT });
+        const page = await mcp.connect({ timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT, forceExtension: opts?.forceExtension });
         return await fn(page);
     }
     finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "publishConfig": {
     "access": "public"
   },
@@ -31,7 +31,7 @@
     "playwright"
   ],
   "author": "jackwener",
-  "license": "MIT",
+  "license": "BSD-3-Clause",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jackwener/opencli.git"