@jackwener/opencli 0.7.3 → 0.7.5

package/src/doctor.test.ts

@@ -81,7 +81,55 @@ describe('json token helpers', () => {
       },
     }), 'abc123');
     const parsed = JSON.parse(next);
-    expect(parsed.mcp.playwright.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN).toBe('abc123');
+    expect(parsed.mcp.playwright.environment.PLAYWRIGHT_MCP_EXTENSION_TOKEN).toBe('abc123');
+  });
+
+  it('creates standard mcpServers format for empty file (not OpenCode)', () => {
+    const next = upsertJsonConfigToken('', 'abc123');
+    const parsed = JSON.parse(next);
+    expect(parsed.mcpServers.playwright.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN).toBe('abc123');
+    expect(parsed.mcp).toBeUndefined();
+  });
+
+  it('creates OpenCode format when filePath contains opencode', () => {
+    const next = upsertJsonConfigToken('', 'abc123', '/home/user/.config/opencode/opencode.json');
+    const parsed = JSON.parse(next);
+    expect(parsed.mcp.playwright.environment.PLAYWRIGHT_MCP_EXTENSION_TOKEN).toBe('abc123');
+    expect(parsed.mcpServers).toBeUndefined();
+  });
+
+  it('creates standard format when filePath is claude.json', () => {
+    const next = upsertJsonConfigToken('', 'abc123', '/home/user/.claude.json');
+    const parsed = JSON.parse(next);
+    expect(parsed.mcpServers.playwright.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN).toBe('abc123');
+  });
+});
+
+describe('fish shell support', () => {
+  it('generates fish set -gx syntax for fish config path', () => {
+    const next = upsertShellToken('', 'abc123', '/home/user/.config/fish/config.fish');
+    expect(next).toContain('set -gx PLAYWRIGHT_MCP_EXTENSION_TOKEN "abc123"');
+    expect(next).not.toContain('export');
+  });
+
+  it('replaces existing fish set line', () => {
+    const content = 'set -gx PLAYWRIGHT_MCP_EXTENSION_TOKEN "old"\n';
+    const next = upsertShellToken(content, 'new', '/home/user/.config/fish/config.fish');
+    expect(next).toContain('set -gx PLAYWRIGHT_MCP_EXTENSION_TOKEN "new"');
+    expect(next).not.toContain('"old"');
+  });
+
+  it('appends fish syntax to existing fish config', () => {
+    const content = 'set -gx PATH /usr/bin\n';
+    const next = upsertShellToken(content, 'abc123', '/home/user/.config/fish/config.fish');
+    expect(next).toContain('set -gx PLAYWRIGHT_MCP_EXTENSION_TOKEN "abc123"');
+    expect(next).toContain('set -gx PATH /usr/bin');
+  });
+
+  it('uses export syntax for zshrc even with filePath', () => {
+    const next = upsertShellToken('', 'abc123', '/home/user/.zshrc');
+    expect(next).toContain('export PLAYWRIGHT_MCP_EXTENSION_TOKEN="abc123"');
+    expect(next).not.toContain('set -gx');
   });
 });
 
@@ -94,6 +142,8 @@ describe('doctor report rendering', () => {
       envFingerprint: 'fp1',
       extensionToken: 'abc123',
       extensionFingerprint: 'fp1',
+      extensionInstalled: true,
+      extensionBrowsers: ['Chrome'],
       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 }],
       recommendedToken: 'abc123',
@@ -102,6 +152,7 @@ describe('doctor report rendering', () => {
       issues: [],
     }));
 
+    expect(text).toContain('[OK] Extension installed (Chrome)');
     expect(text).toContain('[OK] Environment token: configured (fp1)');
     expect(text).toContain('[OK] /tmp/mcp.json');
     expect(text).toContain('configured (fp1)');
@@ -113,6 +164,8 @@ describe('doctor report rendering', () => {
       envFingerprint: 'fp1',
       extensionToken: null,
       extensionFingerprint: null,
+      extensionInstalled: false,
+      extensionBrowsers: [],
       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 }],
       recommendedToken: 'abc123',
@@ -121,10 +174,50 @@ describe('doctor report rendering', () => {
       issues: ['Detected inconsistent Playwright MCP tokens across env/config files.'],
     }));
 
+    expect(text).toContain('[MISSING] Extension not installed in any browser');
     expect(text).toContain('[MISMATCH] Environment token: configured (fp1)');
     expect(text).toContain('[MISMATCH] /tmp/.zshrc');
     expect(text).toContain('configured (fp2)');
     expect(text).toContain('[MISMATCH] Recommended token fingerprint: fp1');
   });
+
+  it('renders connectivity OK when live test succeeds', () => {
+    const text = strip(renderBrowserDoctorReport({
+      envToken: 'abc123',
+      envFingerprint: 'fp1',
+      extensionToken: 'abc123',
+      extensionFingerprint: 'fp1',
+      extensionInstalled: true,
+      extensionBrowsers: ['Chrome'],
+      shellFiles: [],
+      configs: [],
+      recommendedToken: 'abc123',
+      recommendedFingerprint: 'fp1',
+      connectivity: { ok: true, durationMs: 1234 },
+      warnings: [],
+      issues: [],
+    }));
+
+    expect(text).toContain('[OK] Browser connectivity: connected in 1.2s');
+  });
+
+  it('renders connectivity WARN when not tested', () => {
+    const text = strip(renderBrowserDoctorReport({
+      envToken: 'abc123',
+      envFingerprint: 'fp1',
+      extensionToken: 'abc123',
+      extensionFingerprint: 'fp1',
+      extensionInstalled: true,
+      extensionBrowsers: ['Chrome'],
+      shellFiles: [],
+      configs: [],
+      recommendedToken: 'abc123',
+      recommendedFingerprint: 'fp1',
+      warnings: [],
+      issues: [],
+    }));
+
+    expect(text).toContain('[WARN] Browser connectivity: not tested (use --live)');
+  });
 });
 

package/src/doctor.ts

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { execSync } from 'node:child_process';
+
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import chalk from 'chalk';
@@ -16,6 +16,7 @@ const TOKEN_LINE_RE = /^(\s*export\s+PLAYWRIGHT_MCP_EXTENSION_TOKEN=)(['"]?)([^'
 export type DoctorOptions = {
   fix?: boolean;
   yes?: boolean;
+  live?: boolean;
   shellRc?: string;
   configPaths?: string[];
   token?: string;
@@ -41,16 +42,25 @@ export type McpConfigStatus = {
   parseError?: string;
 };
 
+export type ConnectivityResult = {
+  ok: boolean;
+  error?: string;
+  durationMs: number;
+};
+
 export type DoctorReport = {
   cliVersion?: string;
   envToken: string | null;
   envFingerprint: string | null;
   extensionToken: string | null;
   extensionFingerprint: string | null;
+  extensionInstalled: boolean;
+  extensionBrowsers: string[];
   shellFiles: ShellFileStatus[];
   configs: McpConfigStatus[];
   recommendedToken: string | null;
   recommendedFingerprint: string | null;
+  connectivity?: ConnectivityResult;
   warnings: string[];
   issues: string[];
 };
@@ -101,6 +111,15 @@ export function getDefaultShellRcPath(): string {
   return path.join(os.homedir(), '.zshrc');
 }
 
+function isFishConfig(filePath: string): boolean {
+  return filePath.endsWith('config.fish') || filePath.includes('/fish/');
+}
+
+/** Detect if a JSON config file uses OpenCode's `mcp` format vs standard `mcpServers` */
+function isOpenCodeConfig(filePath: string): boolean {
+  return filePath.includes('opencode');
+}
+
 export function getDefaultMcpConfigPaths(cwd: string = process.cwd()): string[] {
   const home = os.homedir();
   const candidates = [
@@ -126,7 +145,15 @@ export function readTokenFromShellContent(content: string): string | null {
   return m?.[3] ?? null;
 }
 
-export function upsertShellToken(content: string, token: string): string {
+export function upsertShellToken(content: string, token: string, filePath?: string): string {
+  if (filePath && isFishConfig(filePath)) {
+    // Fish shell uses `set -gx` instead of `export`
+    const fishLine = `set -gx ${PLAYWRIGHT_TOKEN_ENV} "${token}"`;
+    const fishRe = /^\s*set\s+(-gx\s+)?PLAYWRIGHT_MCP_EXTENSION_TOKEN\s+.*/m;
+    if (!content.trim()) return `${fishLine}\n`;
+    if (fishRe.test(content)) return content.replace(fishRe, fishLine);
+    return `${content.replace(/\s*$/, '')}\n${fishLine}\n`;
+  }
   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"${
@@ -147,29 +174,37 @@ function readJsonConfigToken(content: string): string | 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];
+  const opencode = parsed?.mcp?.[PLAYWRIGHT_SERVER_NAME]?.environment?.[PLAYWRIGHT_TOKEN_ENV];
   if (typeof opencode === 'string' && opencode) return opencode;
   return null;
 }
 
-export function upsertJsonConfigToken(content: string, token: string): string {
+export function upsertJsonConfigToken(content: string, token: string, filePath?: 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 {
+
+  // Determine format: use OpenCode format only if explicitly an opencode config,
+  // or if the existing content already uses `mcp` key (not `mcpServers`)
+  const useOpenCodeFormat = filePath
+    ? isOpenCodeConfig(filePath)
+    : (!parsed.mcpServers && parsed.mcp);
+
+  if (useOpenCodeFormat) {
     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;
+    parsed.mcp[PLAYWRIGHT_SERVER_NAME].environment = parsed.mcp[PLAYWRIGHT_SERVER_NAME].environment ?? {};
+    parsed.mcp[PLAYWRIGHT_SERVER_NAME].environment[PLAYWRIGHT_TOKEN_ENV] = token;
+  } else {
+    parsed.mcpServers = 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;
   }
   return `${JSON.stringify(parsed, null, 2)}\n`;
 }
@@ -252,12 +287,35 @@ function readConfigStatus(filePath: string): McpConfigStatus {
   }
 }
 
+/**
+ * Dynamically enumerate Chrome profiles by scanning for 'Default' and 'Profile *'
+ * directories across all browser base paths. Falls back to ['Default'] if none found.
+ */
+function enumerateProfiles(baseDirs: string[]): string[] {
+  const profiles = new Set<string>();
+  for (const base of baseDirs) {
+    if (!fileExists(base)) continue;
+    try {
+      for (const entry of fs.readdirSync(base, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        if (entry.name === 'Default' || /^Profile \d+$/.test(entry.name)) {
+          profiles.add(entry.name);
+        }
+      }
+    } catch { /* permission denied, etc. */ }
+  }
+  return profiles.size > 0 ? [...profiles].sort() : ['Default'];
+}
+
 /**
  * Discover the auth token stored by the Playwright MCP Bridge extension
  * by scanning Chrome's LevelDB localStorage files directly.
  *
- * Uses `strings` + `grep` for fast binary scanning on macOS/Linux,
- * with a pure-Node fallback on Windows.
+ * Reads LevelDB .ldb/.log files as raw binary and searches for the
+ * extension ID near base64url token values. This works reliably across
+ * platforms because LevelDB's internal encoding can split ASCII strings
+ * like "auth-token" and the extension ID across byte boundaries, making
+ * text-based tools like `strings` + `grep` unreliable.
  */
 export function discoverExtensionToken(): string | null {
   const home = os.homedir();
@@ -285,8 +343,7 @@ export function discoverExtensionToken(): string | null {
     );
   }
 
-  const profiles = ['Default', 'Profile 1', 'Profile 2', 'Profile 3'];
-  // Token is 43 chars of base64url (from 32 random bytes)
+  const profiles = enumerateProfiles(bases);
   const tokenRe = /([A-Za-z0-9_-]{40,50})/;
 
   for (const base of bases) {
@@ -294,14 +351,6 @@ export function discoverExtensionToken(): string | null {
       const dir = path.join(base, profile, 'Local Storage', 'leveldb');
       if (!fileExists(dir)) continue;
 
-      // Fast path: use strings + grep to find candidate files and extract token
-      if (platform !== 'win32') {
-        const token = extractTokenViaStrings(dir, tokenRe);
-        if (token) return token;
-        continue;
-      }
-
-      // Slow path (Windows): read binary files directly
       const token = extractTokenViaBinaryRead(dir, tokenRe);
       if (token) return token;
     }
@@ -310,39 +359,20 @@ export function discoverExtensionToken(): string | null {
   return null;
 }
 
-function extractTokenViaStrings(dir: string, tokenRe: RegExp): string | null {
-  try {
-    // Single shell pipeline: for each LevelDB file, extract strings, find lines
-    // after the extension ID, and filter for base64url token pattern.
-    //
-    // LevelDB `strings` output for the extension's auth-token entry:
-    //   auth-token                                    ← key name
-    //   4,mmlmfjhmonkocbjadbfplnigmagldckm.7          ← LevelDB internal key
-    //   hqI86ncsD1QpcVcj-k9CyzTF-ieCQd_4KreZ_wy1WHA  ← token value
-    //
-    // We get the line immediately after any EXTENSION_ID mention and check
-    // if it looks like a base64url token (40-50 chars, [A-Za-z0-9_-]).
-    const shellDir = dir.replace(/'/g, "'\\''");
-    const cmd = `for f in '${shellDir}'/*.ldb '${shellDir}'/*.log; do ` +
-      `[ -f "$f" ] && strings "$f" 2>/dev/null | ` +
-      `grep -A1 '${PLAYWRIGHT_EXTENSION_ID}' | ` +
-      `grep -v '${PLAYWRIGHT_EXTENSION_ID}' | ` +
-      `grep -E '^[A-Za-z0-9_-]{40,50}$' | head -1; ` +
-      `done 2>/dev/null`;
-    const result = execSync(cmd, { encoding: 'utf-8', timeout: 10000 }).trim();
-
-    // Take the first non-empty line
-    for (const line of result.split('\n')) {
-      const token = line.trim();
-      if (token && validateBase64urlToken(token)) return token;
-    }
-  } catch {}
-  return null;
-}
-
 function extractTokenViaBinaryRead(dir: string, tokenRe: RegExp): string | null {
+  // LevelDB fragments strings across byte boundaries, so we can't search
+  // for the full extension ID or "auth-token" as contiguous ASCII. Instead,
+  // search for a short prefix of the extension ID that reliably appears as
+  // contiguous bytes, then scan a window around each match for a base64url
+  // token value.
+  //
+  // Observed LevelDB layout near the auth-token entry:
+  //   ... auth-t<binary> ... 4,mmlmfjh<binary>Pocbjadbfplnigmagldckm.7 ...
+  //   <binary> hqI86ncsD1QpcVcj-k9CyzTF-ieCQd_4KreZ_wy1WHA <binary> ...
+  //
+  // The extension ID prefix "mmlmfjh" appears ~44 bytes before the token.
   const extIdBuf = Buffer.from(PLAYWRIGHT_EXTENSION_ID);
-  const keyBuf = Buffer.from('auth-token');
+  const extIdPrefix = Buffer.from(PLAYWRIGHT_EXTENSION_ID.slice(0, 7)); // "mmlmfjh"
 
   let files: string[];
   try {
@@ -351,7 +381,7 @@ function extractTokenViaBinaryRead(dir: string, tokenRe: RegExp): string | null
       .map(f => path.join(dir, f));
   } catch { return null; }
 
-  // Sort by mtime descending
+  // Sort by mtime descending so we find the freshest token first
   files.sort((a, b) => {
     try { return fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs; } catch { return 0; }
   });
@@ -360,14 +390,30 @@ function extractTokenViaBinaryRead(dir: string, tokenRe: RegExp): string | null
     let data: Buffer;
     try { data = fs.readFileSync(file); } catch { continue; }
 
-    // Quick check: does file contain both the extension ID and auth-token key?
-    const extPos = data.indexOf(extIdBuf);
-    if (extPos === -1) continue;
-    const keyPos = data.indexOf(keyBuf, Math.max(0, extPos - 500));
-    if (keyPos === -1) continue;
+    // Quick check: file must contain at least the prefix
+    if (data.indexOf(extIdPrefix) === -1) continue;
 
-    // Scan for token value after auth-token key
+    // Strategy 1: scan after each occurrence of the extension ID prefix
+    // for base64url tokens within a 500-byte window
     let idx = 0;
+    while (true) {
+      const pos = data.indexOf(extIdPrefix, idx);
+      if (pos === -1) break;
+
+      const scanStart = pos;
+      const scanEnd = Math.min(data.length, pos + 500);
+      const window = data.subarray(scanStart, scanEnd).toString('latin1');
+      const m = window.match(tokenRe);
+      if (m && validateBase64urlToken(m[1])) {
+        // Make sure this isn't another extension ID that happens to match
+        if (m[1] !== PLAYWRIGHT_EXTENSION_ID) return m[1];
+      }
+      idx = pos + 1;
+    }
+
+    // Strategy 2 (fallback): original approach using full extension ID + auth-token key
+    const keyBuf = Buffer.from('auth-token');
+    idx = 0;
     while (true) {
       const kp = data.indexOf(keyBuf, idx);
       if (kp === -1) break;
@@ -393,6 +439,69 @@ function validateBase64urlToken(token: string): boolean {
 }
 
 
+/**
+ * Check whether the Playwright MCP Bridge extension is installed in any browser.
+ * Scans Chrome/Chromium/Edge Extensions directories for the known extension ID.
+ */
+export function checkExtensionInstalled(): { installed: boolean; browsers: string[] } {
+  const home = os.homedir();
+  const platform = os.platform();
+  const browserDirs: Array<{ name: string; base: string }> = [];
+
+  if (platform === 'darwin') {
+    browserDirs.push(
+      { name: 'Chrome', base: path.join(home, 'Library', 'Application Support', 'Google', 'Chrome') },
+      { name: 'Chrome Canary', base: path.join(home, 'Library', 'Application Support', 'Google', 'Chrome Canary') },
+      { name: 'Chromium', base: path.join(home, 'Library', 'Application Support', 'Chromium') },
+      { name: 'Edge', base: path.join(home, 'Library', 'Application Support', 'Microsoft Edge') },
+    );
+  } else if (platform === 'linux') {
+    browserDirs.push(
+      { name: 'Chrome', base: path.join(home, '.config', 'google-chrome') },
+      { name: 'Chromium', base: path.join(home, '.config', 'chromium') },
+      { name: 'Edge', base: path.join(home, '.config', 'microsoft-edge') },
+    );
+  } else if (platform === 'win32') {
+    const appData = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+    browserDirs.push(
+      { name: 'Chrome', base: path.join(appData, 'Google', 'Chrome', 'User Data') },
+      { name: 'Edge', base: path.join(appData, 'Microsoft', 'Edge', 'User Data') },
+    );
+  }
+
+  const profiles = enumerateProfiles(browserDirs.map(d => d.base));
+  const foundBrowsers: string[] = [];
+
+  for (const { name, base } of browserDirs) {
+    for (const profile of profiles) {
+      const extDir = path.join(base, profile, 'Extensions', PLAYWRIGHT_EXTENSION_ID);
+      if (fileExists(extDir)) {
+        foundBrowsers.push(name);
+        break; // one match per browser is enough
+      }
+    }
+  }
+
+  return { installed: foundBrowsers.length > 0, browsers: [...new Set(foundBrowsers)] };
+}
+
+/**
+ * Test token connectivity by attempting a real MCP connection.
+ * Connects, does the JSON-RPC handshake, and immediately closes.
+ */
+export async function checkTokenConnectivity(opts?: { timeout?: number }): Promise<ConnectivityResult> {
+  const timeout = opts?.timeout ?? 8;
+  const start = Date.now();
+  try {
+    const mcp = new PlaywrightMCP();
+    await mcp.connect({ timeout });
+    await mcp.close();
+    return { ok: true, durationMs: Date.now() - start };
+  } catch (err: any) {
+    return { ok: false, error: err?.message ?? String(err), durationMs: Date.now() - start };
+  }
+}
+
 export async function runBrowserDoctor(opts: DoctorOptions = {}): Promise<DoctorReport> {
   const envToken = process.env[PLAYWRIGHT_TOKEN_ENV] ?? null;
   const shellPath = opts.shellRc ?? getDefaultShellRcPath();
@@ -418,24 +527,38 @@ export async function runBrowserDoctor(opts: DoctorOptions = {}): Promise<Doctor
   const uniqueTokens = [...new Set(allTokens)];
   const recommendedToken = opts.token ?? extensionToken ?? envToken ?? (uniqueTokens.length === 1 ? uniqueTokens[0] : null) ?? null;
 
+  // Check extension installation
+  const extInstall = checkExtensionInstalled();
+
+  // Connectivity test (only when --live)
+  let connectivity: ConnectivityResult | undefined;
+  if (opts.live) {
+    connectivity = await checkTokenConnectivity();
+  }
+
   const report: DoctorReport = {
     cliVersion: opts.cliVersion,
     envToken,
     envFingerprint: getTokenFingerprint(envToken ?? undefined),
     extensionToken,
     extensionFingerprint: getTokenFingerprint(extensionToken ?? undefined),
+    extensionInstalled: extInstall.installed,
+    extensionBrowsers: extInstall.browsers,
     shellFiles,
     configs,
     recommendedToken,
     recommendedFingerprint: getTokenFingerprint(recommendedToken ?? undefined),
+    connectivity,
     warnings: [],
     issues: [],
   };
 
+  if (!extInstall.installed) report.issues.push('Playwright MCP Bridge extension is not installed in any browser.');
   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 (connectivity && !connectivity.ok) report.issues.push(`Browser connectivity test failed: ${connectivity.error ?? 'unknown'}`);
   for (const config of configs) {
     if (config.parseError) report.warnings.push(`Could not parse ${config.path}: ${config.parseError}`);
   }
@@ -456,6 +579,12 @@ export function renderBrowserDoctorReport(report: DoctorReport): string {
   const hasMismatch = uniqueFingerprints.length > 1;
   const lines = [chalk.bold(`opencli v${report.cliVersion ?? 'unknown'} doctor`), ''];
 
+  const installStatus: ReportStatus = report.extensionInstalled ? 'OK' : 'MISSING';
+  const installDetail = report.extensionInstalled
+    ? `Extension installed (${report.extensionBrowsers.join(', ')})`
+    : 'Extension not installed in any browser';
+  lines.push(statusLine(installStatus, installDetail));
+
   const extStatus: ReportStatus = !report.extensionToken ? 'MISSING' : hasMismatch ? 'MISMATCH' : 'OK';
   lines.push(statusLine(extStatus, `Extension token (Chrome LevelDB): ${tokenSummary(report.extensionToken, report.extensionFingerprint)}`));
 
@@ -489,6 +618,18 @@ export function renderBrowserDoctorReport(report: DoctorReport): string {
   }
   if (missingConfigCount > 0) lines.push(chalk.dim(`     Other scanned config locations not present: ${missingConfigCount}`));
   lines.push('');
+
+  // Connectivity result
+  if (report.connectivity) {
+    const connStatus: ReportStatus = report.connectivity.ok ? 'OK' : 'WARN';
+    const connDetail = report.connectivity.ok
+      ? `Browser connectivity: connected in ${(report.connectivity.durationMs / 1000).toFixed(1)}s`
+      : `Browser connectivity: failed (${report.connectivity.error ?? 'unknown'})`;
+    lines.push(statusLine(connStatus, connDetail));
+  } else {
+    lines.push(statusLine('WARN', 'Browser connectivity: not tested (use --live)'));
+  }
+
   lines.push(statusLine(
     hasMismatch ? 'MISMATCH' : report.recommendedToken ? 'OK' : 'WARN',
     `Recommended token fingerprint: ${report.recommendedFingerprint ?? 'unavailable'}`,
@@ -547,7 +688,7 @@ export async function applyBrowserDoctorFix(report: DoctorReport, opts: DoctorOp
   const written: string[] = [];
   if (plannedWrites.includes(shellPath)) {
     const shellBefore = fileExists(shellPath) ? fs.readFileSync(shellPath, 'utf-8') : '';
-    writeFileWithMkdir(shellPath, upsertShellToken(shellBefore, token));
+    writeFileWithMkdir(shellPath, upsertShellToken(shellBefore, token, shellPath));
     written.push(shellPath);
   }
 
@@ -555,7 +696,9 @@ export async function applyBrowserDoctorFix(report: DoctorReport, opts: DoctorOp
     if (!plannedWrites.includes(config.path)) continue;
     if (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);
+    const next = config.format === 'toml'
+      ? upsertTomlConfigToken(before, token)
+      : upsertJsonConfigToken(before, token, config.path);
     writeFileWithMkdir(config.path, next);
     written.push(config.path);
   }

package/src/main.ts

@@ -100,12 +100,13 @@ program.command('doctor')
   .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('--live', 'Test browser connectivity (requires Chrome running)', false)
   .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 });
+    const report = await runBrowserDoctor({ token: opts.token, live: opts.live, 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 });

package/src/setup.ts

@@ -11,6 +11,8 @@ import { stdin as input, stdout as output } from 'node:process';
 import {
   type DoctorReport,
   PLAYWRIGHT_TOKEN_ENV,
+  checkExtensionInstalled,
+  checkTokenConnectivity,
   discoverExtensionToken,
   fileExists,
   getDefaultShellRcPath,
@@ -60,11 +62,24 @@ export async function runSetup(opts: { cliVersion?: string; token?: string } = {
   }
 
   if (!token) {
-    console.log(`  ${chalk.yellow('!')} No token found. Please enter it manually.`);
-    console.log(chalk.dim('    (Find it in the Playwright MCP Bridge extension → Status page)'));
+    // Give precise diagnosis of why token scan failed
+    const extInstall = checkExtensionInstalled();
+
+    console.log(`  ${chalk.red('✗')} Browser token scan failed\n`);
+    if (!extInstall.installed) {
+      console.log(chalk.dim('  Cause: Playwright MCP Bridge extension is not installed'));
+      console.log(chalk.dim('  Fix:   Install from https://chromewebstore.google.com/detail/'));
+      console.log(chalk.dim('         playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm'));
+    } else {
+      console.log(chalk.dim(`  Cause: Extension is installed (${extInstall.browsers.join(', ')}) but token not found in LevelDB`));
+      console.log(chalk.dim('  Fix:   1) Open the extension popup and verify the token is generated'));
+      console.log(chalk.dim('         2) Close Chrome completely, then re-run setup'));
+    }
+    console.log();
+    console.log(`  You can enter the token manually, or fix the above and re-run ${chalk.bold('opencli setup')}.`);
     console.log();
     const rl = createInterface({ input, output });
-    const answer = await rl.question('  Token: ');
+    const answer = await rl.question('  Token (press Enter to abort): ');
     rl.close();
     token = answer.trim();
     if (!token) {
@@ -129,7 +144,7 @@ export async function runSetup(opts: { cliVersion?: string; token?: string } = {
     if (sel.startsWith('shell:')) {
       const p = sel.slice('shell:'.length);
       const before = fileExists(p) ? fs.readFileSync(p, 'utf-8') : '';
-      writeFileWithMkdir(p, upsertShellToken(before, token));
+      writeFileWithMkdir(p, upsertShellToken(before, token, p));
       written.push(p);
       wroteShell = true;
     } else if (sel.startsWith('config:')) {
@@ -138,7 +153,7 @@ export async function runSetup(opts: { cliVersion?: string; token?: string } = {
       if (config && config.parseError) continue;
       const before = fileExists(p) ? fs.readFileSync(p, 'utf-8') : '';
       const format = config?.format ?? (p.endsWith('.toml') ? 'toml' : 'json');
-      const next = format === 'toml' ? upsertTomlConfigToken(before, token) : upsertJsonConfigToken(before, token);
+      const next = format === 'toml' ? upsertTomlConfigToken(before, token) : upsertJsonConfigToken(before, token, p);
       writeFileWithMkdir(p, next);
       written.push(p);
     }
@@ -161,6 +176,21 @@ export async function runSetup(opts: { cliVersion?: string; token?: string } = {
     console.log(chalk.yellow('  No files were changed.'));
   }
   console.log();
+
+  // Step 7: Auto-verify browser connectivity
+  console.log(chalk.dim('  Verifying browser connectivity...'));
+  try {
+    const result = await checkTokenConnectivity({ timeout: 5 });
+    if (result.ok) {
+      console.log(`  ${chalk.green('✓')} Browser connected in ${(result.durationMs / 1000).toFixed(1)}s`);
+    } else {
+      console.log(`  ${chalk.yellow('!')} Browser connectivity test failed: ${result.error ?? 'unknown'}`);
+      console.log(chalk.dim('    Make sure Chrome is running with the extension enabled.'));
+    }
+  } catch {
+    console.log(`  ${chalk.yellow('!')} Could not verify connectivity (Chrome may not be running)`);
+  }
+  console.log();
 }
 
 function padRight(s: string, n: number): string {