@jackwener/opencli 0.4.1 → 0.4.3

package/src/doctor.test.ts

@@ -0,0 +1,133 @@
+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/src/doctor.ts

@@ -0,0 +1,424 @@
+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 type { IPage } from './types.js';
+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;
+export type DoctorOptions = {
+  fix?: boolean;
+  yes?: boolean;
+  shellRc?: string;
+  configPaths?: string[];
+  token?: string;
+  cliVersion?: string;
+};
+
+export type ShellFileStatus = {
+  path: string;
+  exists: boolean;
+  token: string | null;
+  fingerprint: string | null;
+};
+
+export type McpConfigFormat = 'json' | 'toml';
+
+export type McpConfigStatus = {
+  path: string;
+  exists: boolean;
+  format: McpConfigFormat;
+  token: string | null;
+  fingerprint: string | null;
+  writable: boolean;
+  parseError?: string;
+};
+
+export type DoctorReport = {
+  cliVersion?: string;
+  envToken: string | null;
+  envFingerprint: string | null;
+  shellFiles: ShellFileStatus[];
+  configs: McpConfigStatus[];
+  remoteDebuggingEnabled: boolean;
+  remoteDebuggingEndpoint: string | null;
+  cdpEnabled: boolean;
+  cdpToken: string | null;
+  cdpFingerprint: string | null;
+  recommendedToken: string | null;
+  recommendedFingerprint: string | null;
+  warnings: string[];
+  issues: string[];
+};
+
+type ReportStatus = 'OK' | 'MISSING' | 'MISMATCH' | 'WARN';
+
+function label(status: ReportStatus): string {
+  return `[${status}]`;
+}
+
+function statusLine(status: ReportStatus, text: string): string {
+  return `${label(status)} ${text}`;
+}
+
+function tokenSummary(token: string | null, fingerprint: string | null): string {
+  if (!token) return 'missing';
+  return `configured (${fingerprint})`;
+}
+
+export function getDefaultShellRcPath(): string {
+  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: string = process.cwd()): string[] {
+  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: string): string | null {
+  const m = content.match(TOKEN_LINE_RE);
+  return m?.[3] ?? null;
+}
+
+export function upsertShellToken(content: string, token: string): string {
+  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: string): string | null {
+  try {
+    const parsed = JSON.parse(content);
+    return readTokenFromJsonObject(parsed);
+  } catch {
+    return null;
+  }
+}
+
+function readTokenFromJsonObject(parsed: any): string | null {
+  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: string, token: string): string {
+  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: string): string | null {
+  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: string, token: string): string {
+  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: string): boolean {
+  try {
+    return fs.existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+
+function canWrite(filePath: string): boolean {
+  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: string): McpConfigStatus {
+  const format: McpConfigFormat = 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: any) {
+    return {
+      path: filePath,
+      exists: true,
+      format,
+      token: null,
+      fingerprint: null,
+      writable: canWrite(filePath),
+      parseError: error?.message ?? String(error),
+    };
+  }
+}
+
+async function extractTokenViaCdp(): Promise<string | null> {
+  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: IPage) => {
+    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: string) => v.length >= 24) : [];
+        if (matches.length > 0) return matches.sort((a: string, b: string) => b.length - a.length)[0];
+      } catch {}
+    }
+    return null;
+  });
+  return typeof result === 'string' && result ? result : null;
+}
+
+export async function runBrowserDoctor(opts: DoctorOptions = {}): Promise<DoctorReport> {
+  const envToken = process.env[PLAYWRIGHT_TOKEN_ENV] ?? null;
+  const remoteDebuggingEndpoint = await discoverChromeEndpoint().catch(() => null);
+  const shellPath = opts.shellRc ?? getDefaultShellRcPath();
+  const shellFiles: ShellFileStatus[] = [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 is string => !!v);
+  const uniqueTokens = [...new Set(allTokens)];
+  const recommendedToken = opts.token ?? envToken ?? (uniqueTokens.length === 1 ? uniqueTokens[0] : cdpToken) ?? null;
+
+  const report: DoctorReport = {
+    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: DoctorReport): string {
+  const tokenFingerprints = [
+    report.envFingerprint,
+    ...report.shellFiles.map(shell => shell.fingerprint),
+    ...report.configs.filter(config => config.exists).map(config => config.fingerprint),
+  ].filter((value): value is string => !!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: ReportStatus = !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: ReportStatus = !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: ReportStatus = 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: ReportStatus = 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: string): Promise<boolean> {
+  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: string, content: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf-8');
+}
+
+export async function applyBrowserDoctorFix(report: DoctorReport, opts: DoctorOptions = {}): Promise<string[]> {
+  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: string[] = [];
+  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: string[] = [];
+  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/src/main.ts

@@ -31,11 +31,29 @@ program.name('opencli').description('Make any website your CLI. Zero setup. AI-p
 
 // ── 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)); return; }
+    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<string, CliCommand[]>();
     for (const cmd of commands) { const g = sites.get(cmd.site) ?? []; g.push(cmd); sites.set(cmd.site, g); }
     console.log(); console.log(chalk.bold('  opencli') + chalk.dim(' — available commands')); console.log();
@@ -73,6 +91,30 @@ 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: string) => 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();
@@ -89,7 +131,7 @@ for (const [, cmd] of registry) {
     else if (arg.default != null) subCmd.option(flag, arg.help ?? '', String(arg.default));
     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();
@@ -99,9 +141,10 @@ for (const [, cmd] of registry) {
       else if (arg.default != null) kwargs[arg.name] = arg.default;
     }
     try {
+      if (actionOpts.verbose) process.env.OPENCLI_VERBOSE = '1';
       let result: any;
       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); }
       if (actionOpts.verbose && (!result || (Array.isArray(result) && result.length === 0))) {
         console.error(chalk.yellow(`[Verbose] Warning: Command returned an empty result. If the website structural API changed or requires authentication, check the network or update the adapter.`));

package/src/output.test.ts

@@ -0,0 +1,27 @@
+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');
+  });
+});