@jackwener/opencli 0.7.10 → 0.8.0

package/src/browser/discover.ts

@@ -9,19 +9,33 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 
 let _cachedMcpServerPath: string | null | undefined;
+let _existsSync = fs.existsSync;
+let _execSync = execSync;
+
+export function resetMcpServerPathCache(): void {
+  _cachedMcpServerPath = undefined;
+}
+
+export function setMcpDiscoveryTestHooks(input?: {
+  existsSync?: typeof fs.existsSync;
+  execSync?: typeof execSync;
+}): void {
+  _existsSync = input?.existsSync ?? fs.existsSync;
+  _execSync = input?.execSync ?? execSync;
+}
 
 export function findMcpServerPath(): string | null {
   if (_cachedMcpServerPath !== undefined) return _cachedMcpServerPath;
 
   const envMcp = process.env.OPENCLI_MCP_SERVER_PATH;
-  if (envMcp && fs.existsSync(envMcp)) {
+  if (envMcp && _existsSync(envMcp)) {
     _cachedMcpServerPath = envMcp;
     return _cachedMcpServerPath;
   }
 
   // Check local node_modules first (@playwright/mcp is the modern package)
   const localMcp = path.resolve('node_modules', '@playwright', 'mcp', 'cli.js');
-  if (fs.existsSync(localMcp)) {
+  if (_existsSync(localMcp)) {
     _cachedMcpServerPath = localMcp;
     return _cachedMcpServerPath;
   }
@@ -29,11 +43,33 @@ export function findMcpServerPath(): string | null {
   // Check project-relative path
   const __dirname2 = path.dirname(fileURLToPath(import.meta.url));
   const projectMcp = path.resolve(__dirname2, '..', '..', 'node_modules', '@playwright', 'mcp', 'cli.js');
-  if (fs.existsSync(projectMcp)) {
+  if (_existsSync(projectMcp)) {
     _cachedMcpServerPath = projectMcp;
     return _cachedMcpServerPath;
   }
 
+  // Check global npm/yarn locations derived from current Node runtime.
+  const nodePrefix = path.resolve(path.dirname(process.execPath), '..');
+  const globalNodeModules = path.join(nodePrefix, 'lib', 'node_modules');
+  const globalMcp = path.join(globalNodeModules, '@playwright', 'mcp', 'cli.js');
+  if (_existsSync(globalMcp)) {
+    _cachedMcpServerPath = globalMcp;
+    return _cachedMcpServerPath;
+  }
+
+  // Check npm global root directly.
+  try {
+    const npmRootGlobal = _execSync('npm root -g 2>/dev/null', {
+      encoding: 'utf-8',
+      timeout: 5000,
+    }).trim();
+    const npmGlobalMcp = path.join(npmRootGlobal, '@playwright', 'mcp', 'cli.js');
+    if (npmRootGlobal && _existsSync(npmGlobalMcp)) {
+      _cachedMcpServerPath = npmGlobalMcp;
+      return _cachedMcpServerPath;
+    }
+  } catch {}
+
   // Check common locations
   const candidates = [
     path.join(os.homedir(), '.npm', '_npx'),
@@ -43,8 +79,8 @@ export function findMcpServerPath(): string | null {
 
   // Try npx resolution (legacy package name)
   try {
-    const result = execSync('npx -y --package=@playwright/mcp which mcp-server-playwright 2>/dev/null', { encoding: 'utf-8', timeout: 10000 }).trim();
-    if (result && fs.existsSync(result)) {
+    const result = _execSync('npx -y --package=@playwright/mcp which mcp-server-playwright 2>/dev/null', { encoding: 'utf-8', timeout: 10000 }).trim();
+    if (result && _existsSync(result)) {
       _cachedMcpServerPath = result;
       return _cachedMcpServerPath;
     }
@@ -52,8 +88,8 @@ export function findMcpServerPath(): string | null {
 
   // Try which
   try {
-    const result = execSync('which mcp-server-playwright 2>/dev/null', { encoding: 'utf-8', timeout: 5000 }).trim();
-    if (result && fs.existsSync(result)) {
+    const result = _execSync('which mcp-server-playwright 2>/dev/null', { encoding: 'utf-8', timeout: 5000 }).trim();
+    if (result && _existsSync(result)) {
       _cachedMcpServerPath = result;
       return _cachedMcpServerPath;
     }
@@ -61,9 +97,9 @@ export function findMcpServerPath(): string | null {
 
   // Search in common npx cache
   for (const base of candidates) {
-    if (!fs.existsSync(base)) continue;
+    if (!_existsSync(base)) continue;
     try {
-      const found = execSync(`find "${base}" -name "cli.js" -path "*playwright*mcp*" 2>/dev/null | head -1`, { encoding: 'utf-8', timeout: 5000 }).trim();
+      const found = _execSync(`find "${base}" -name "cli.js" -path "*playwright*mcp*" 2>/dev/null | head -1`, { encoding: 'utf-8', timeout: 5000 }).trim();
       if (found) {
         _cachedMcpServerPath = found;
         return _cachedMcpServerPath;
@@ -75,16 +111,115 @@ export function findMcpServerPath(): string | null {
   return _cachedMcpServerPath;
 }
 
-export function buildMcpArgs(input: { mcpPath: string; executablePath?: string | null }): string[] {
-  const args = [input.mcpPath];
+/**
+ * Chrome 144+ auto-discovery: read DevToolsActivePort file to get CDP endpoint.
+ *
+ * Starting with Chrome 144, users can enable remote debugging from
+ * chrome://inspect#remote-debugging without any command-line flags.
+ * Chrome writes the active port and browser GUID to a DevToolsActivePort file
+ * in the user data directory, which we read to construct the WebSocket endpoint.
+ */
+export function discoverChromeEndpoint(): string | null {
+  const candidates: string[] = [];
+
+  // User-specified Chrome data dir takes highest priority
+  if (process.env.CHROME_USER_DATA_DIR) {
+    candidates.push(path.join(process.env.CHROME_USER_DATA_DIR, 'DevToolsActivePort'));
+  }
+
+  // Standard Chrome/Edge user data dirs per platform
+  if (process.platform === 'win32') {
+    const localAppData = process.env.LOCALAPPDATA ?? path.join(os.homedir(), 'AppData', 'Local');
+    candidates.push(path.join(localAppData, 'Google', 'Chrome', 'User Data', 'DevToolsActivePort'));
+    candidates.push(path.join(localAppData, 'Microsoft', 'Edge', 'User Data', 'DevToolsActivePort'));
+  } else if (process.platform === 'darwin') {
+    candidates.push(path.join(os.homedir(), 'Library', 'Application Support', 'Google', 'Chrome', 'DevToolsActivePort'));
+    candidates.push(path.join(os.homedir(), 'Library', 'Application Support', 'Microsoft Edge', 'DevToolsActivePort'));
+  } else {
+    candidates.push(path.join(os.homedir(), '.config', 'google-chrome', 'DevToolsActivePort'));
+    candidates.push(path.join(os.homedir(), '.config', 'chromium', 'DevToolsActivePort'));
+    candidates.push(path.join(os.homedir(), '.config', 'microsoft-edge', 'DevToolsActivePort'));
+  }
+
+  for (const filePath of candidates) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8').trim();
+      const lines = content.split('\n');
+      if (lines.length >= 2) {
+        const port = parseInt(lines[0], 10);
+        const browserPath = lines[1]; // e.g. /devtools/browser/<GUID>
+        if (port > 0 && browserPath.startsWith('/devtools/browser/')) {
+          return `ws://127.0.0.1:${port}${browserPath}`;
+        }
+      }
+    } catch {}
+  }
+  return null;
+}
+
+export function resolveCdpEndpoint(): { endpoint?: string; requestedCdp: boolean } {
+  const envVal = process.env.OPENCLI_CDP_ENDPOINT;
+  if (envVal === '1' || envVal?.toLowerCase() === 'true') {
+    const autoDiscovered = discoverChromeEndpoint();
+    return { endpoint: autoDiscovered ?? envVal, requestedCdp: true };
+  }
+
+  if (envVal) {
+    return { endpoint: envVal, requestedCdp: true };
+  }
+
+  // Fallback to auto-discovery if not explicitly set
+  const autoDiscovered = discoverChromeEndpoint();
+  if (autoDiscovered) {
+    return { endpoint: autoDiscovered, requestedCdp: true };
+  }
+
+  return { requestedCdp: false };
+}
+
+function buildRuntimeArgs(input?: { executablePath?: string | null; cdpEndpoint?: string }): string[] {
+  const args: string[] = [];
+
+  // Priority 1: CDP endpoint (remote Chrome debugging or local Auto-Discovery)
+  if (input?.cdpEndpoint) {
+    args.push('--cdp-endpoint', input.cdpEndpoint);
+    return args;
+  }
+
+  // Priority 2: Extension mode (local Chrome with MCP Bridge extension)
   if (!process.env.CI) {
-    // Local: always connect to user's running Chrome via MCP Bridge extension
     args.push('--extension');
   }
-  // CI: standalone mode — @playwright/mcp launches its own browser (headed by default).
+
+  // CI/standalone mode: @playwright/mcp launches its own browser (headed by default).
   // xvfb provides a virtual display for headed mode in GitHub Actions.
-  if (input.executablePath) {
+  if (input?.executablePath) {
     args.push('--executable-path', input.executablePath);
   }
   return args;
 }
+
+export function buildMcpArgs(input: { mcpPath: string; executablePath?: string | null; cdpEndpoint?: string }): string[] {
+  return [input.mcpPath, ...buildRuntimeArgs(input)];
+}
+
+export function buildMcpLaunchSpec(input: { mcpPath?: string | null; executablePath?: string | null; cdpEndpoint?: string }): {
+  command: string;
+  args: string[];
+  usedNpxFallback: boolean;
+} {
+  const runtimeArgs = buildRuntimeArgs(input);
+  if (input.mcpPath) {
+    return {
+      command: 'node',
+      args: [input.mcpPath, ...runtimeArgs],
+      usedNpxFallback: false,
+    };
+  }
+
+  return {
+    command: 'npx',
+    args: ['-y', '@playwright/mcp@latest', ...runtimeArgs],
+    usedNpxFallback: true,
+  };
+}

package/src/browser/errors.ts

@@ -4,7 +4,7 @@
 
 import { createHash } from 'node:crypto';
 
-export type ConnectFailureKind = 'missing-token' | 'extension-timeout' | 'extension-not-installed' | 'mcp-init' | 'process-exit' | 'unknown';
+export type ConnectFailureKind = 'missing-token' | 'extension-timeout' | 'extension-not-installed' | 'mcp-init' | 'process-exit' | 'cdp-connection-failed' | 'unknown';
 
 export type ConnectFailureInput = {
   kind: ConnectFailureKind;
@@ -26,6 +26,15 @@ export function formatBrowserConnectError(input: ConnectFailureInput): Error {
   const suffix = stderr ? `\n\nMCP stderr:\n${stderr}` : '';
   const tokenHint = input.tokenFingerprint ? ` Token fingerprint: ${input.tokenFingerprint}.` : '';
 
+  if (input.kind === 'cdp-connection-failed') {
+    return new Error(
+      `Failed to connect to remote Chrome via CDP endpoint.\n\n` +
+      `Check if Chrome is running with remote debugging enabled (--remote-debugging-port=9222) or DevToolsActivePort is available under chrome://inspect#remote-debugging.\n` +
+      `If you specified OPENCLI_CDP_ENDPOINT=1, auto-discovery might have failed.` +
+      suffix,
+    );
+  }
+
   if (input.kind === 'missing-token') {
     return new Error(
       'Failed to connect to Playwright MCP Bridge: PLAYWRIGHT_MCP_EXTENSION_TOKEN is not set.\n\n' +
@@ -74,9 +83,16 @@ export function inferConnectFailureKind(args: {
   stderr: string;
   rawMessage?: string;
   exited?: boolean;
+  isCdpMode?: boolean;
 }): ConnectFailureKind {
   const haystack = `${args.rawMessage ?? ''}\n${args.stderr}`.toLowerCase();
 
+  if (args.isCdpMode) {
+    if (args.rawMessage?.startsWith('MCP init failed:')) return 'mcp-init';
+    if (args.exited) return 'cdp-connection-failed';
+    return 'cdp-connection-failed';
+  }
+
   if (!args.hasExtensionToken)
     return 'missing-token';
   if (haystack.includes('extension connection timeout') || haystack.includes('playwright mcp bridge'))

package/src/browser/index.ts

@@ -9,11 +9,12 @@ export { Page } from './page.js';
 export { PlaywrightMCP } from './mcp.js';
 export { getTokenFingerprint, formatBrowserConnectError } from './errors.js';
 export type { ConnectFailureKind, ConnectFailureInput } from './errors.js';
+export { resolveCdpEndpoint } from './discover.js';
 
 // Test-only helpers — exposed for unit tests
 import { createJsonRpcRequest } from './mcp.js';
 import { extractTabEntries, diffTabIndexes, appendLimited } from './tabs.js';
-import { buildMcpArgs } from './discover.js';
+import { buildMcpArgs, buildMcpLaunchSpec, findMcpServerPath, resetMcpServerPathCache, setMcpDiscoveryTestHooks } from './discover.js';
 import { withTimeoutMs } from '../runtime.js';
 
 export const __test__ = {
@@ -22,5 +23,9 @@ export const __test__ = {
   diffTabIndexes,
   appendLimited,
   buildMcpArgs,
+  buildMcpLaunchSpec,
+  findMcpServerPath,
+  resetMcpServerPathCache,
+  setMcpDiscoveryTestHooks,
   withTimeoutMs,
 };

package/src/browser/mcp.ts

@@ -9,7 +9,7 @@ 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 { findMcpServerPath, buildMcpLaunchSpec, resolveCdpEndpoint } from './discover.js';
 import { extractTabIdentities, extractTabEntries, diffTabIndexes, appendLimited } from './tabs.js';
 
 const STDERR_BUFFER_LIMIT = 16 * 1024;
@@ -105,7 +105,6 @@ export class PlaywrightMCP {
     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);
@@ -115,7 +114,8 @@ export class PlaywrightMCP {
     return new Promise<Page>((resolve, reject) => {
       const isDebug = process.env.DEBUG?.includes('opencli:mcp');
       const debugLog = (msg: string) => isDebug && console.error(`[opencli:mcp] ${msg}`);
-      const useExtension = !!process.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN;
+      const { endpoint: cdpEndpoint, requestedCdp } = resolveCdpEndpoint();
+      const useExtension = !requestedCdp;
       const extensionToken = process.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN;
       const tokenFingerprint = getTokenFingerprint(extensionToken);
       let stderrBuffer = '';
@@ -151,20 +151,25 @@ export class PlaywrightMCP {
         settleError(inferConnectFailureKind({
           hasExtensionToken: !!extensionToken,
           stderr: stderrBuffer,
+          isCdpMode: requestedCdp,
         }));
       }, timeout * 1000);
 
-      const mcpArgs = buildMcpArgs({
+      const launchSpec = buildMcpLaunchSpec({
         mcpPath,
         executablePath: process.env.OPENCLI_BROWSER_EXECUTABLE_PATH,
+        cdpEndpoint,
       });
       if (process.env.OPENCLI_VERBOSE) {
-        console.error(`[opencli] Mode: ${useExtension ? 'extension' : 'standalone'}`);
+        console.error(`[opencli] Mode: ${requestedCdp ? 'CDP' : useExtension ? 'extension' : 'standalone'}`);
         if (useExtension) console.error(`[opencli] Extension token: fingerprint ${tokenFingerprint}`);
+        if (launchSpec.usedNpxFallback) {
+          console.error('[opencli] Playwright MCP not found locally; bootstrapping via npx @playwright/mcp@latest');
+        }
       }
-      debugLog(`Spawning node ${mcpArgs.join(' ')}`);
+      debugLog(`Spawning ${launchSpec.command} ${launchSpec.args.join(' ')}`);
 
-      this._proc = spawn('node', mcpArgs, {
+      this._proc = spawn(launchSpec.command, launchSpec.args, {
         stdio: ['pipe', 'pipe', 'pipe'],
         env: { ...process.env },
       });
@@ -216,6 +221,7 @@ export class PlaywrightMCP {
             hasExtensionToken: !!extensionToken,
             stderr: stderrBuffer,
             exited: true,
+            isCdpMode: requestedCdp,
           }), { exitCode: code });
         }
       });
@@ -233,6 +239,7 @@ export class PlaywrightMCP {
             hasExtensionToken: !!extensionToken,
             stderr: stderrBuffer,
             rawMessage: `MCP init failed: ${resp.error.message}`,
+            isCdpMode: requestedCdp,
           }), { rawMessage: resp.error.message });
           return;
         }

package/src/browser/page.ts

@@ -6,6 +6,7 @@ import { formatSnapshot } from '../snapshotFormatter.js';
 import { normalizeEvaluateSource } from '../pipeline/template.js';
 import { generateInterceptorJs, generateReadInterceptedJs } from '../interceptor.js';
 import type { IPage } from '../types.js';
+import { BrowserConnectError } from '../errors.js';
 
 /**
  * Page abstraction wrapping JSON-RPC calls to Playwright MCP.
@@ -18,10 +19,28 @@ export class Page implements IPage {
     if (resp.error) throw new Error(`page.${method}: ${(resp.error as any).message ?? JSON.stringify(resp.error)}`);
     // Extract text content from MCP result
     const result = resp.result as any;
+
+    if (result?.isError) {
+      const errorText = result.content?.find((c: any) => c.type === 'text')?.text || 'Unknown MCP Error';
+      throw new BrowserConnectError(
+        errorText,
+        'Please check if the browser is running or if the Playwright MCP / CDP connection is configured correctly.'
+      );
+    }
+
     if (result?.content) {
       const textParts = result.content.filter((c: any) => c.type === 'text');
-      if (textParts.length === 1) {
-        let text = textParts[0].text;
+      if (textParts.length >= 1) {
+        let text = textParts[textParts.length - 1].text; // Usually the main output is in the last text block
+
+        // Some versions of the MCP return error text without the `isError` boolean flag
+        if (typeof text === 'string' && text.trim().startsWith('### Error')) {
+            throw new BrowserConnectError(
+              text.trim(),
+              'Please check if the browser is running or if the Playwright MCP / CDP connection is configured correctly.'
+            );
+        }
+
         // 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');

package/src/browser.test.ts

@@ -1,6 +1,12 @@
-import { describe, it, expect } from 'vitest';
+import { afterEach, describe, it, expect, vi } from 'vitest';
 import { PlaywrightMCP, __test__ } from './browser/index.js';
 
+afterEach(() => {
+  __test__.resetMcpServerPathCache();
+  __test__.setMcpDiscoveryTestHooks();
+  delete process.env.OPENCLI_MCP_SERVER_PATH;
+});
+
 describe('browser helpers', () => {
   it('creates JSON-RPC requests with unique ids', () => {
     const first = __test__.createJsonRpcRequest('tools/call', { name: 'browser_tabs' });
@@ -106,9 +112,142 @@ describe('browser helpers', () => {
     }
   });
 
+  it('builds a direct node launch spec when a local MCP path is available', () => {
+    const savedCI = process.env.CI;
+    delete process.env.CI;
+    try {
+      expect(__test__.buildMcpLaunchSpec({
+        mcpPath: '/tmp/cli.js',
+        executablePath: '/usr/bin/google-chrome',
+      })).toEqual({
+        command: 'node',
+        args: ['/tmp/cli.js', '--extension', '--executable-path', '/usr/bin/google-chrome'],
+        usedNpxFallback: false,
+      });
+    } finally {
+      if (savedCI !== undefined) {
+        process.env.CI = savedCI;
+      } else {
+        delete process.env.CI;
+      }
+    }
+  });
+
+  it('falls back to npx bootstrap when no MCP path is available', () => {
+    const savedCI = process.env.CI;
+    delete process.env.CI;
+    try {
+      expect(__test__.buildMcpLaunchSpec({
+        mcpPath: null,
+      })).toEqual({
+        command: 'npx',
+        args: ['-y', '@playwright/mcp@latest', '--extension'],
+        usedNpxFallback: true,
+      });
+    } finally {
+      if (savedCI !== undefined) {
+        process.env.CI = savedCI;
+      } else {
+        delete process.env.CI;
+      }
+    }
+  });
+
   it('times out slow promises', async () => {
     await expect(__test__.withTimeoutMs(new Promise(() => {}), 10, 'timeout')).rejects.toThrow('timeout');
   });
+
+  it('prefers OPENCLI_MCP_SERVER_PATH over discovered locations', () => {
+    process.env.OPENCLI_MCP_SERVER_PATH = '/env/mcp/cli.js';
+    const existsSync = vi.fn((candidate: any) => candidate === '/env/mcp/cli.js');
+    const execSync = vi.fn();
+    __test__.setMcpDiscoveryTestHooks({ existsSync, execSync: execSync as any });
+
+    expect(__test__.findMcpServerPath()).toBe('/env/mcp/cli.js');
+    expect(execSync).not.toHaveBeenCalled();
+    expect(existsSync).toHaveBeenCalledWith('/env/mcp/cli.js');
+  });
+
+  it('discovers global @playwright/mcp from the current Node runtime prefix', () => {
+    const originalExecPath = process.execPath;
+    const runtimeExecPath = '/opt/homebrew/Cellar/node/25.2.1/bin/node';
+    const runtimeGlobalMcp = '/opt/homebrew/Cellar/node/25.2.1/lib/node_modules/@playwright/mcp/cli.js';
+    Object.defineProperty(process, 'execPath', {
+      value: runtimeExecPath,
+      configurable: true,
+    });
+
+    const existsSync = vi.fn((candidate: any) => candidate === runtimeGlobalMcp);
+    const execSync = vi.fn();
+    __test__.setMcpDiscoveryTestHooks({ existsSync, execSync: execSync as any });
+
+    try {
+      expect(__test__.findMcpServerPath()).toBe(runtimeGlobalMcp);
+      expect(execSync).not.toHaveBeenCalled();
+      expect(existsSync).toHaveBeenCalledWith(runtimeGlobalMcp);
+    } finally {
+      Object.defineProperty(process, 'execPath', {
+        value: originalExecPath,
+        configurable: true,
+      });
+    }
+  });
+
+  it('falls back to npm root -g when runtime prefix lookup misses', () => {
+    const originalExecPath = process.execPath;
+    const runtimeExecPath = '/opt/homebrew/Cellar/node/25.2.1/bin/node';
+    const runtimeGlobalMcp = '/opt/homebrew/Cellar/node/25.2.1/lib/node_modules/@playwright/mcp/cli.js';
+    const npmRootGlobal = '/Users/jakevin/.nvm/versions/node/v22.14.0/lib/node_modules';
+    const npmGlobalMcp = '/Users/jakevin/.nvm/versions/node/v22.14.0/lib/node_modules/@playwright/mcp/cli.js';
+    Object.defineProperty(process, 'execPath', {
+      value: runtimeExecPath,
+      configurable: true,
+    });
+
+    const existsSync = vi.fn((candidate: any) => candidate === npmGlobalMcp);
+    const execSync = vi.fn((command: string) => {
+      if (String(command).includes('npm root -g')) return `${npmRootGlobal}\n` as any;
+      throw new Error(`unexpected command: ${String(command)}`);
+    });
+    __test__.setMcpDiscoveryTestHooks({ existsSync, execSync: execSync as any });
+
+    try {
+      expect(__test__.findMcpServerPath()).toBe(npmGlobalMcp);
+      expect(execSync).toHaveBeenCalledOnce();
+      expect(existsSync).toHaveBeenCalledWith(runtimeGlobalMcp);
+      expect(existsSync).toHaveBeenCalledWith(npmGlobalMcp);
+    } finally {
+      Object.defineProperty(process, 'execPath', {
+        value: originalExecPath,
+        configurable: true,
+      });
+    }
+  });
+
+  it('returns null when new global discovery paths are unavailable', () => {
+    const originalExecPath = process.execPath;
+    const runtimeExecPath = '/opt/homebrew/Cellar/node/25.2.1/bin/node';
+    Object.defineProperty(process, 'execPath', {
+      value: runtimeExecPath,
+      configurable: true,
+    });
+
+    const existsSync = vi.fn(() => false);
+    const execSync = vi.fn((command: string) => {
+      if (String(command).includes('npm root -g')) return '/missing/global/node_modules\n' as any;
+      throw new Error(`missing command: ${String(command)}`);
+    });
+    __test__.setMcpDiscoveryTestHooks({ existsSync, execSync: execSync as any });
+
+    try {
+      expect(__test__.findMcpServerPath()).toBeNull();
+    } finally {
+      Object.defineProperty(process, 'execPath', {
+        value: originalExecPath,
+        configurable: true,
+      });
+    }
+  });
 });
 
 describe('PlaywrightMCP state', () => {

package/src/clis/barchart/flow.ts

@@ -0,0 +1,120 @@
+/**
+ * Barchart unusual options activity (options flow).
+ * Shows high volume/OI ratio trades that may indicate institutional activity.
+ * Auth: CSRF token from <meta name="csrf-token"> + session cookies.
+ */
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'barchart',
+  name: 'flow',
+  description: 'Barchart unusual options activity / options flow',
+  domain: 'www.barchart.com',
+  strategy: Strategy.COOKIE,
+  args: [
+    { name: 'type', type: 'str', default: 'all', help: 'Filter: all, call, or put', choices: ['all', 'call', 'put'] },
+    { name: 'limit', type: 'int', default: 20, help: 'Number of results' },
+  ],
+  columns: [
+    'symbol', 'type', 'strike', 'expiration', 'last',
+    'volume', 'openInterest', 'volOiRatio', 'iv',
+  ],
+  func: async (page, kwargs) => {
+    const optionType = kwargs.type || 'all';
+    const limit = kwargs.limit ?? 20;
+
+    await page.goto('https://www.barchart.com/options/unusual-activity/stocks');
+    await page.wait(5);
+
+    const data = await page.evaluate(`
+      (async () => {
+        const limit = ${limit};
+        const typeFilter = '${optionType}'.toLowerCase();
+
+        // Wait for CSRF token to appear (Angular may inject it after initial render)
+        let csrf = '';
+        for (let i = 0; i < 10; i++) {
+          csrf = document.querySelector('meta[name="csrf-token"]')?.content || '';
+          if (csrf) break;
+          await new Promise(r => setTimeout(r, 500));
+        }
+        if (!csrf) return { error: 'no-csrf' };
+
+        const headers = { 'X-CSRF-TOKEN': csrf };
+        const fields = [
+          'baseSymbol','strikePrice','expirationDate','optionType',
+          'lastPrice','volume','openInterest','volumeOpenInterestRatio','volatility',
+        ].join(',');
+
+        // Fetch extra rows when filtering by type since server-side filter doesn't work
+        const fetchLimit = typeFilter !== 'all' ? limit * 3 : limit;
+
+        // Try unusual_activity first, fall back to mostActive (unusual_activity is
+        // empty outside market hours)
+        const lists = [
+          'options.unusual_activity.stocks.us',
+          'options.mostActive.us',
+        ];
+
+        for (const list of lists) {
+          try {
+            const url = '/proxies/core-api/v1/options/get?list=' + list
+              + '&fields=' + fields
+              + '&orderBy=volumeOpenInterestRatio&orderDir=desc'
+              + '&raw=1&limit=' + fetchLimit;
+
+            const resp = await fetch(url, { credentials: 'include', headers });
+            if (!resp.ok) continue;
+            const d = await resp.json();
+            let items = d?.data || [];
+            if (items.length === 0) continue;
+
+            // Apply client-side type filter
+            if (typeFilter !== 'all') {
+              items = items.filter(i => {
+                const t = ((i.raw || i).optionType || '').toLowerCase();
+                return t === typeFilter;
+              });
+            }
+            return items.slice(0, limit).map(i => {
+              const r = i.raw || i;
+              return {
+                symbol: r.baseSymbol || r.symbol,
+                type: r.optionType,
+                strike: r.strikePrice,
+                expiration: r.expirationDate,
+                last: r.lastPrice,
+                volume: r.volume,
+                openInterest: r.openInterest,
+                volOiRatio: r.volumeOpenInterestRatio,
+                iv: r.volatility,
+              };
+            });
+          } catch(e) {}
+        }
+
+        return [];
+      })()
+    `);
+
+    if (!data) return [];
+
+    if (data.error === 'no-csrf') {
+      throw new Error('Could not extract CSRF token from barchart.com. Make sure you are logged in.');
+    }
+
+    if (!Array.isArray(data)) return [];
+
+    return data.slice(0, limit).map(r => ({
+      symbol: r.symbol || '',
+      type: r.type || '',
+      strike: r.strike,
+      expiration: r.expiration ?? null,
+      last: r.last != null ? Number(Number(r.last).toFixed(2)) : null,
+      volume: r.volume,
+      openInterest: r.openInterest,
+      volOiRatio: r.volOiRatio != null ? Number(Number(r.volOiRatio).toFixed(2)) : null,
+      iv: r.iv != null ? Number(Number(r.iv).toFixed(2)) + '%' : null,
+    }));
+  },
+});