@jackwener/opencli 0.7.6 → 0.7.9

package/dist/errors.js

@@ -0,0 +1,42 @@
+/**
+ * Unified error types for opencli.
+ *
+ * All errors thrown by the framework should extend CliError so that
+ * the top-level handler in main.ts can render consistent, helpful output.
+ */
+export class CliError extends Error {
+    /** Machine-readable error code (e.g. 'BROWSER_CONNECT', 'ADAPTER_LOAD') */
+    code;
+    /** Human-readable hint on how to fix the problem */
+    hint;
+    constructor(code, message, hint) {
+        super(message);
+        this.name = 'CliError';
+        this.code = code;
+        this.hint = hint;
+    }
+}
+export class BrowserConnectError extends CliError {
+    constructor(message, hint) {
+        super('BROWSER_CONNECT', message, hint);
+        this.name = 'BrowserConnectError';
+    }
+}
+export class AdapterLoadError extends CliError {
+    constructor(message, hint) {
+        super('ADAPTER_LOAD', message, hint);
+        this.name = 'AdapterLoadError';
+    }
+}
+export class CommandExecutionError extends CliError {
+    constructor(message, hint) {
+        super('COMMAND_EXEC', message, hint);
+        this.name = 'CommandExecutionError';
+    }
+}
+export class ConfigError extends CliError {
+    constructor(message, hint) {
+        super('CONFIG', message, hint);
+        this.name = 'ConfigError';
+    }
+}

package/dist/logger.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Unified logging for opencli.
+ *
+ * All framework output (warnings, debug info, errors) should go through
+ * this module so that verbosity levels are respected consistently.
+ */
+export declare const log: {
+    /** Informational message (always shown) */
+    info(msg: string): void;
+    /** Warning (always shown) */
+    warn(msg: string): void;
+    /** Error (always shown) */
+    error(msg: string): void;
+    /** Verbose output (only when OPENCLI_VERBOSE is set or -v flag) */
+    verbose(msg: string): void;
+    /** Debug output (only when DEBUG includes 'opencli') */
+    debug(msg: string): void;
+    /** Step-style debug (for pipeline steps, etc.) */
+    step(stepNum: number, total: number, op: string, preview?: string): void;
+    /** Step result summary */
+    stepResult(summary: string): void;
+};

package/dist/logger.js

@@ -0,0 +1,47 @@
+/**
+ * Unified logging for opencli.
+ *
+ * All framework output (warnings, debug info, errors) should go through
+ * this module so that verbosity levels are respected consistently.
+ */
+import chalk from 'chalk';
+function isVerbose() {
+    return !!process.env.OPENCLI_VERBOSE;
+}
+function isDebug() {
+    return !!process.env.DEBUG?.includes('opencli');
+}
+export const log = {
+    /** Informational message (always shown) */
+    info(msg) {
+        process.stderr.write(`${chalk.blue('ℹ')}  ${msg}\n`);
+    },
+    /** Warning (always shown) */
+    warn(msg) {
+        process.stderr.write(`${chalk.yellow('⚠')}  ${msg}\n`);
+    },
+    /** Error (always shown) */
+    error(msg) {
+        process.stderr.write(`${chalk.red('✖')}  ${msg}\n`);
+    },
+    /** Verbose output (only when OPENCLI_VERBOSE is set or -v flag) */
+    verbose(msg) {
+        if (isVerbose()) {
+            process.stderr.write(`${chalk.dim('[verbose]')} ${msg}\n`);
+        }
+    },
+    /** Debug output (only when DEBUG includes 'opencli') */
+    debug(msg) {
+        if (isDebug()) {
+            process.stderr.write(`${chalk.dim('[debug]')} ${msg}\n`);
+        }
+    },
+    /** Step-style debug (for pipeline steps, etc.) */
+    step(stepNum, total, op, preview = '') {
+        process.stderr.write(`  ${chalk.dim(`[${stepNum}/${total}]`)} ${chalk.bold.cyan(op)}${preview}\n`);
+    },
+    /** Step result summary */
+    stepResult(summary) {
+        process.stderr.write(`       ${chalk.dim(`→ ${summary}`)}\n`);
+    },
+};

package/dist/main.js

@@ -10,10 +10,11 @@ import chalk from 'chalk';
 import { discoverClis, executeCommand } from './engine.js';
 import { fullName, getRegistry, strategyLabel } from './registry.js';
 import { render as renderOutput } from './output.js';
-import { PlaywrightMCP } from './browser.js';
+import { PlaywrightMCP } from './browser/index.js';
 import { browserSession, DEFAULT_BROWSER_COMMAND_TIMEOUT, runWithTimeout } from './runtime.js';
 import { PKG_VERSION } from './version.js';
 import { getCompletions, printCompletionScript } from './completion.js';
+import { CliError } from './errors.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const BUILTIN_CLIS = path.resolve(__dirname, 'clis');
@@ -228,7 +229,12 @@ for (const [, cmd] of registry) {
             renderOutput(result, { fmt: actionOpts.format, columns: cmd.columns, title: `${cmd.site}/${cmd.name}`, elapsed: (Date.now() - startTime) / 1000, source: fullName(cmd) });
         }
         catch (err) {
-            if (actionOpts.verbose && err.stack) {
+            if (err instanceof CliError) {
+                console.error(chalk.red(`Error [${err.code}]: ${err.message}`));
+                if (err.hint)
+                    console.error(chalk.yellow(`Hint: ${err.hint}`));
+            }
+            else if (actionOpts.verbose && err.stack) {
                 console.error(chalk.red(err.stack));
             }
             else {

package/dist/pipeline/_debug.d.ts

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

package/dist/pipeline/_debug.js

@@ -0,0 +1,7 @@
+import { render, evalExpr } from './pipeline/template.js';
+const ctx = { item: { first: 'X', second: 'Y' } };
+console.log('evalExpr item.first:', JSON.stringify(evalExpr('item.first', ctx)));
+console.log('evalExpr item.second:', JSON.stringify(evalExpr('item.second', ctx)));
+const template = '$' + '{{ item.first }}-$' + '{{ item.second }}';
+console.log('template:', JSON.stringify(template));
+console.log('render result:', JSON.stringify(render(template, ctx)));

package/dist/pipeline/executor.js

@@ -1,12 +1,12 @@
 /**
  * Pipeline executor: runs YAML pipeline steps sequentially.
  */
-import chalk from 'chalk';
 import { stepNavigate, stepClick, stepType, stepWait, stepPress, stepSnapshot, stepEvaluate } from './steps/browser.js';
 import { stepFetch } from './steps/fetch.js';
 import { stepSelect, stepMap, stepFilter, stepSort, stepLimit } from './steps/transform.js';
 import { stepIntercept } from './steps/intercept.js';
 import { stepTap } from './steps/tap.js';
+import { log } from '../logger.js';
 /** Registry of all available step handlers */
 const STEP_HANDLERS = {
     navigate: stepNavigate,
@@ -43,7 +43,7 @@ export async function executePipeline(page, pipeline, ctx = {}) {
             }
             else {
                 if (debug)
-                    process.stderr.write(`  ${chalk.yellow('⚠')}  Unknown step: ${op}\n`);
+                    log.warn(`Unknown step: ${op}`);
             }
             if (debug)
                 debugStepResult(op, data);
@@ -59,24 +59,24 @@ function debugStepStart(stepNum, total, op, params) {
     else if (params && typeof params === 'object' && !Array.isArray(params)) {
         preview = ` (${Object.keys(params).join(', ')})`;
     }
-    process.stderr.write(`  ${chalk.dim(`[${stepNum}/${total}]`)} ${chalk.bold.cyan(op)}${preview}\n`);
+    log.step(stepNum, total, op, preview);
 }
 function debugStepResult(op, data) {
     if (data === null || data === undefined) {
-        process.stderr.write(`       ${chalk.dim('→ (no data)')}\n`);
+        log.stepResult('(no data)');
     }
     else if (Array.isArray(data)) {
-        process.stderr.write(`       ${chalk.dim(`→ ${data.length} items`)}\n`);
+        log.stepResult(`${data.length} items`);
     }
     else if (typeof data === 'object') {
         const keys = Object.keys(data).slice(0, 5);
-        process.stderr.write(`       ${chalk.dim(`→ dict (${keys.join(', ')}${Object.keys(data).length > 5 ? '...' : ''})`)}\n`);
+        log.stepResult(`dict (${keys.join(', ')}${Object.keys(data).length > 5 ? '...' : ''})`);
     }
     else if (typeof data === 'string') {
         const p = data.slice(0, 60).replace(/\n/g, '\\n');
-        process.stderr.write(`       ${chalk.dim(`→ "${p}${data.length > 60 ? '...' : ''}"`)}\n`);
+        log.stepResult(`"${p}${data.length > 60 ? '...' : ''}"`);
     }
     else {
-        process.stderr.write(`       ${chalk.dim(`→ ${typeof data}`)}\n`);
+        log.stepResult(`${typeof data}`);
     }
 }

package/dist/pipeline/steps/browser.d.ts

@@ -3,10 +3,10 @@
  * Browser interaction primitives.
  */
 import type { IPage } from '../../types.js';
-export declare function stepNavigate(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any>;
-export declare function stepClick(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any>;
-export declare function stepType(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any>;
-export declare function stepWait(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any>;
-export declare function stepPress(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any>;
-export declare function stepSnapshot(page: IPage, params: any, _data: any, _args: Record<string, any>): Promise<any>;
-export declare function stepEvaluate(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any>;
+export declare function stepNavigate(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;
+export declare function stepClick(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;
+export declare function stepType(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;
+export declare function stepWait(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;
+export declare function stepPress(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;
+export declare function stepSnapshot(page: IPage | null, params: any, _data: any, _args: Record<string, any>): Promise<any>;
+export declare function stepEvaluate(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;

package/dist/pipeline/steps/intercept.d.ts

@@ -2,4 +2,4 @@
  * Pipeline step: intercept — declarative XHR interception.
  */
 import type { IPage } from '../../types.js';
-export declare function stepIntercept(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any>;
+export declare function stepIntercept(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;

package/dist/pipeline/steps/tap.d.ts

@@ -9,4 +9,4 @@
  * 5. Returns the captured data (optionally sub-selected)
  */
 import type { IPage } from '../../types.js';
-export declare function stepTap(page: IPage, params: any, data: any, args: Record<string, any>): Promise<any>;
+export declare function stepTap(page: IPage | null, params: any, data: any, args: Record<string, any>): Promise<any>;

package/dist/promote.d.ts

@@ -0,0 +1 @@
+export declare function promoteCandidate(opts: any): any;

package/dist/promote.js

@@ -0,0 +1,3 @@
+/** Promote verified drafts. */
+import { registerCandidates } from './register.js';
+export function promoteCandidate(opts) { return registerCandidates(opts); }

package/dist/register.d.ts

@@ -0,0 +1,2 @@
+/** Register candidates, promote, scaffold, generate — stubs with exports. */
+export declare function registerCandidates(opts: any): any;

package/dist/register.js

@@ -0,0 +1,2 @@
+/** Register candidates, promote, scaffold, generate — stubs with exports. */
+export function registerCandidates(opts) { return { ok: true, count: 0 }; }

package/dist/scaffold.d.ts

@@ -0,0 +1,2 @@
+/** Scaffold a draft CLI from endpoint evidence. */
+export declare function scaffoldCli(opts: any): any;

package/dist/scaffold.js

@@ -0,0 +1,2 @@
+/** Scaffold a draft CLI from endpoint evidence. */
+export function scaffoldCli(opts) { return { ok: true }; }

package/dist/setup.js

@@ -9,7 +9,7 @@ import chalk from 'chalk';
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { PLAYWRIGHT_TOKEN_ENV, checkExtensionInstalled, checkTokenConnectivity, discoverExtensionToken, fileExists, getDefaultShellRcPath, runBrowserDoctor, shortenPath, toolName, upsertJsonConfigToken, upsertShellToken, upsertTomlConfigToken, writeFileWithMkdir, } from './doctor.js';
-import { getTokenFingerprint } from './browser.js';
+import { getTokenFingerprint } from './browser/index.js';
 import { checkboxPrompt } from './tui.js';
 export async function runSetup(opts = {}) {
     console.log();
@@ -159,12 +159,18 @@ export async function runSetup(opts = {}) {
             console.log(`  ${chalk.green('✓')} Browser connected in ${(result.durationMs / 1000).toFixed(1)}s`);
         }
         else {
+            console.log(`  ${chalk.green('✓')} Token saved successfully.`);
             console.log(`  ${chalk.yellow('!')} Browser connectivity test failed: ${result.error ?? 'unknown'}`);
-            console.log(chalk.dim('    Make sure Chrome is running with the extension enabled.'));
+            console.log(chalk.dim('    Token configuration is complete. To use opencli, make sure Chrome'));
+            console.log(chalk.dim('    is running with the Playwright MCP Bridge extension enabled.'));
+            console.log(chalk.dim(`    Run ${chalk.bold('opencli doctor --live')} to re-test connectivity.`));
         }
     }
     catch {
-        console.log(`  ${chalk.yellow('!')} Could not verify connectivity (Chrome may not be running)`);
+        console.log(`  ${chalk.green('✓')} Token saved successfully.`);
+        console.log(`  ${chalk.yellow('!')} Browser connectivity test skipped (Chrome may not be running).`);
+        console.log(chalk.dim('    Token configuration is complete. Start Chrome to begin using opencli.'));
+        console.log(chalk.dim(`    Run ${chalk.bold('opencli doctor --live')} to re-test connectivity.`));
     }
     console.log();
 }

package/dist/smoke.d.ts

@@ -0,0 +1,2 @@
+/** Smoke testing, verification, register, promote, explore, synthesize, scaffold, generate — stubs. */
+export declare function runSmoke(cmd: any, page: any, args?: any): Promise<any>;

package/dist/smoke.js

@@ -0,0 +1,2 @@
+/** Smoke testing, verification, register, promote, explore, synthesize, scaffold, generate — stubs. */
+export async function runSmoke(cmd, page, args) { return { ok: true, result: null }; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "0.7.6",
+  "version": "0.7.9",
   "publishConfig": {
     "access": "public"
   },
@@ -17,8 +17,8 @@
     "dev": "tsx src/main.ts",
     "build": "tsc && npm run clean-yaml && npm run copy-yaml && npm run build-manifest",
     "build-manifest": "node dist/build-manifest.js",
-    "clean-yaml": "node -e \"const{readdirSync:r,rmSync:d,existsSync:e,statSync:s}=require('fs'),p=require('path');function w(dir){if(!e(dir))return;for(const f of r(dir)){const fp=p.join(dir,f);s(fp).isDirectory()?w(fp):/\\.ya?ml$/.test(f)&&d(fp)}}w('dist/clis')\"",
-    "copy-yaml": "node -e \"const{readdirSync:r,copyFileSync:c,mkdirSync:m,existsSync:e,statSync:s}=require('fs'),p=require('path');function w(src,dst){if(!e(src))return;for(const f of r(src)){const sp=p.join(src,f),dp=p.join(dst,f);s(sp).isDirectory()?w(sp,dp):/\\.ya?ml$/.test(f)&&(m(p.dirname(dp),{recursive:!0}),c(sp,dp))}}w('src/clis','dist/clis')\"",
+    "clean-yaml": "node scripts/clean-yaml.cjs",
+    "copy-yaml": "node scripts/copy-yaml.cjs",
     "start": "node dist/main.js",
     "postinstall": "node scripts/postinstall.js || true",
     "typecheck": "tsc --noEmit",

package/scripts/clean-yaml.cjs

@@ -0,0 +1,19 @@
+/**
+ * Clean YAML files from dist/clis/ before copying fresh ones.
+ */
+const { readdirSync, rmSync, existsSync, statSync } = require('fs');
+const path = require('path');
+
+function walk(dir) {
+  if (!existsSync(dir)) return;
+  for (const f of readdirSync(dir)) {
+    const fp = path.join(dir, f);
+    if (statSync(fp).isDirectory()) {
+      walk(fp);
+    } else if (/\.ya?ml$/.test(f)) {
+      rmSync(fp);
+    }
+  }
+}
+
+walk('dist/clis');

package/scripts/copy-yaml.cjs

@@ -0,0 +1,21 @@
+/**
+ * Copy YAML files from src/clis/ to dist/clis/.
+ */
+const { readdirSync, copyFileSync, mkdirSync, existsSync, statSync } = require('fs');
+const path = require('path');
+
+function walk(src, dst) {
+  if (!existsSync(src)) return;
+  for (const f of readdirSync(src)) {
+    const sp = path.join(src, f);
+    const dp = path.join(dst, f);
+    if (statSync(sp).isDirectory()) {
+      walk(sp, dp);
+    } else if (/\.ya?ml$/.test(f)) {
+      mkdirSync(path.dirname(dp), { recursive: true });
+      copyFileSync(sp, dp);
+    }
+  }
+}
+
+walk('src/clis', 'dist/clis');

package/scripts/postinstall.js

@@ -70,30 +70,51 @@ function ensureDir(dir) {
 }
 
 /**
- * Ensure fpath contains the custom completions directory in .zshrc
+ * Ensure fpath contains the custom completions directory in .zshrc.
+ *
+ * Key detail: the fpath line MUST appear BEFORE the first `compinit` call,
+ * otherwise compinit won't scan our completions directory.  This is critical
+ * for oh-my-zsh users (source $ZSH/oh-my-zsh.sh calls compinit internally).
  */
 function ensureZshFpath(completionsDir, zshrcPath) {
   const fpathLine = `fpath=(${completionsDir} $fpath)`;
   const autoloadLine = `autoload -Uz compinit && compinit`;
+  const marker = '# opencli completion';
 
   if (!existsSync(zshrcPath)) {
-    writeFileSync(zshrcPath, `${fpathLine}\n${autoloadLine}\n`, 'utf8');
+    writeFileSync(zshrcPath, `${marker}\n${fpathLine}\n${autoloadLine}\n`, 'utf8');
     return;
   }
 
   const content = readFileSync(zshrcPath, 'utf8');
 
-  // Check if completions dir is already in fpath
+  // Already configured — nothing to do
   if (content.includes(completionsDir)) {
-    return; // already configured
+    return;
+  }
+
+  // Find the first line that triggers compinit (direct call or oh-my-zsh source)
+  const lines = content.split('\n');
+  let insertIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    // Skip comment-only lines
+    if (trimmed.startsWith('#')) continue;
+    if (/compinit/.test(trimmed) || /source\s+.*oh-my-zsh\.sh/.test(trimmed)) {
+      insertIdx = i;
+      break;
+    }
   }
 
-  // Append fpath configuration
-  let addition = `\n# opencli completion\n${fpathLine}\n`;
-  if (!content.includes('compinit')) {
-    addition += `${autoloadLine}\n`;
+  if (insertIdx !== -1) {
+    // Insert fpath BEFORE the compinit / oh-my-zsh source line
+    lines.splice(insertIdx, 0, marker, fpathLine);
+    writeFileSync(zshrcPath, lines.join('\n'), 'utf8');
+  } else {
+    // No compinit found — append fpath + compinit at the end
+    let addition = `\n${marker}\n${fpathLine}\n${autoloadLine}\n`;
+    appendFileSync(zshrcPath, addition, 'utf8');
   }
-  appendFileSync(zshrcPath, addition, 'utf8');
 }
 
 // ── Main ───────────────────────────────────────────────────────────────────

package/src/bilibili.ts

@@ -56,7 +56,7 @@ export async function wbiSign(
   const mixinKey = getMixinKey(imgKey, subKey);
   const wts = Math.floor(Date.now() / 1000);
   const sorted: Record<string, string> = {};
-  const allParams = { ...params, wts: String(wts) };
+  const allParams: Record<string, any> = { ...params, wts: String(wts) };
   for (const key of Object.keys(allParams).sort()) {
     sorted[key] = String(allParams[key]).replace(/[!'()*]/g, '');
   }

package/src/browser/discover.ts

@@ -0,0 +1,90 @@
+/**
+ * MCP server path discovery and argument building.
+ */
+
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+let _cachedMcpServerPath: string | null | undefined;
+
+export function findMcpServerPath(): string | null {
+  if (_cachedMcpServerPath !== undefined) return _cachedMcpServerPath;
+
+  const envMcp = process.env.OPENCLI_MCP_SERVER_PATH;
+  if (envMcp && fs.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)) {
+    _cachedMcpServerPath = localMcp;
+    return _cachedMcpServerPath;
+  }
+
+  // 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)) {
+    _cachedMcpServerPath = projectMcp;
+    return _cachedMcpServerPath;
+  }
+
+  // Check common locations
+  const candidates = [
+    path.join(os.homedir(), '.npm', '_npx'),
+    path.join(os.homedir(), 'node_modules', '.bin'),
+    '/usr/local/lib/node_modules',
+  ];
+
+  // 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)) {
+      _cachedMcpServerPath = result;
+      return _cachedMcpServerPath;
+    }
+  } catch {}
+
+  // Try which
+  try {
+    const result = execSync('which mcp-server-playwright 2>/dev/null', { encoding: 'utf-8', timeout: 5000 }).trim();
+    if (result && fs.existsSync(result)) {
+      _cachedMcpServerPath = result;
+      return _cachedMcpServerPath;
+    }
+  } catch {}
+
+  // Search in common npx cache
+  for (const base of candidates) {
+    if (!fs.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();
+      if (found) {
+        _cachedMcpServerPath = found;
+        return _cachedMcpServerPath;
+      }
+    } catch {}
+  }
+
+  _cachedMcpServerPath = null;
+  return _cachedMcpServerPath;
+}
+
+export function buildMcpArgs(input: { mcpPath: string; executablePath?: string | null }): string[] {
+  const args = [input.mcpPath];
+  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).
+  // xvfb provides a virtual display for headed mode in GitHub Actions.
+  if (input.executablePath) {
+    args.push('--executable-path', input.executablePath);
+  }
+  return args;
+}

package/src/browser/errors.ts

@@ -0,0 +1,89 @@
+/**
+ * Browser connection error classification and formatting.
+ */
+
+import { createHash } from 'node:crypto';
+
+export type ConnectFailureKind = 'missing-token' | 'extension-timeout' | 'extension-not-installed' | 'mcp-init' | 'process-exit' | 'unknown';
+
+export type ConnectFailureInput = {
+  kind: ConnectFailureKind;
+  timeout: number;
+  hasExtensionToken: boolean;
+  tokenFingerprint?: string | null;
+  stderr?: string;
+  exitCode?: number | null;
+  rawMessage?: string;
+};
+
+export function getTokenFingerprint(token: string | undefined): string | null {
+  if (!token) return null;
+  return createHash('sha256').update(token).digest('hex').slice(0, 8);
+}
+
+export function formatBrowserConnectError(input: ConnectFailureInput): Error {
+  const stderr = input.stderr?.trim();
+  const suffix = stderr ? `\n\nMCP stderr:\n${stderr}` : '';
+  const tokenHint = input.tokenFingerprint ? ` Token fingerprint: ${input.tokenFingerprint}.` : '';
+
+  if (input.kind === 'missing-token') {
+    return new Error(
+      'Failed to connect to Playwright MCP Bridge: PLAYWRIGHT_MCP_EXTENSION_TOKEN is not set.\n\n' +
+      'Without this token, Chrome will show a manual approval dialog for every new MCP connection. ' +
+      'Copy the token from the Playwright MCP Bridge extension and set it in BOTH your shell environment and MCP client config.' +
+      suffix,
+    );
+  }
+
+  if (input.kind === 'extension-not-installed') {
+    return new Error(
+      'Failed to connect to Playwright MCP Bridge: the browser extension did not attach.\n\n' +
+      'Make sure Chrome is running and the "Playwright MCP Bridge" extension is installed and enabled. ' +
+      'If Chrome shows an approval dialog, click Allow.' +
+      suffix,
+    );
+  }
+
+  if (input.kind === 'extension-timeout') {
+    const likelyCause = input.hasExtensionToken
+      ? `The most likely cause is that PLAYWRIGHT_MCP_EXTENSION_TOKEN does not match the token currently shown by the browser extension.${tokenHint} Re-copy the token from the extension and update BOTH your shell environment and MCP client config.`
+      : 'PLAYWRIGHT_MCP_EXTENSION_TOKEN is not configured, so the extension may be waiting for manual approval.';
+    return new Error(
+      `Timed out connecting to Playwright MCP Bridge (${input.timeout}s).\n\n` +
+      `${likelyCause} If a browser prompt is visible, click Allow.` +
+      suffix,
+    );
+  }
+
+  if (input.kind === 'mcp-init') {
+    return new Error(`Failed to initialize Playwright MCP: ${input.rawMessage ?? 'unknown error'}${suffix}`);
+  }
+
+  if (input.kind === 'process-exit') {
+    return new Error(
+      `Playwright MCP process exited before the browser connection was established${input.exitCode == null ? '' : ` (code ${input.exitCode})`}.` +
+      suffix,
+    );
+  }
+
+  return new Error(input.rawMessage ?? 'Failed to connect to browser');
+}
+
+export function inferConnectFailureKind(args: {
+  hasExtensionToken: boolean;
+  stderr: string;
+  rawMessage?: string;
+  exited?: boolean;
+}): ConnectFailureKind {
+  const haystack = `${args.rawMessage ?? ''}\n${args.stderr}`.toLowerCase();
+
+  if (!args.hasExtensionToken)
+    return 'missing-token';
+  if (haystack.includes('extension connection timeout') || haystack.includes('playwright mcp bridge'))
+    return 'extension-not-installed';
+  if (args.rawMessage?.startsWith('MCP init failed:'))
+    return 'mcp-init';
+  if (args.exited)
+    return 'process-exit';
+  return 'extension-timeout';
+}

package/src/browser/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Browser module — public API re-exports.
+ *
+ * This barrel replaces the former monolithic browser.ts.
+ * External code should import from './browser/index.js' (or './browser.js' via Node resolution).
+ */
+
+export { Page } from './page.js';
+export { PlaywrightMCP } from './mcp.js';
+export { getTokenFingerprint, formatBrowserConnectError } from './errors.js';
+export type { ConnectFailureKind, ConnectFailureInput } from './errors.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 { withTimeoutMs } from '../runtime.js';
+
+export const __test__ = {
+  createJsonRpcRequest,
+  extractTabEntries,
+  diffTabIndexes,
+  appendLimited,
+  buildMcpArgs,
+  withTimeoutMs,
+};