@guanzhu.me/pw-cli 0.0.17 → 0.0.19

package/README.md

@@ -72,6 +72,7 @@ Run a local script:
 
 ```bash
 pw-cli run-script ./scrape.js --url https://example.com
+pw-cli run-script --extension ./scrape.js --url https://example.com
 ```
 
 `run-script` is intended for multi-step automation. Define an `async function main` that receives Playwright globals as a single object:
@@ -116,6 +117,13 @@ async function main({ page, args }) {
 pw-cli run-script ./scripts/extract-links.js --url https://example.com --output links.json
 ```
 
+To drive an already-open Chrome/Edge browser through Playwright MCP Bridge, add `--extension`:
+
+```bash
+pw-cli run-script --extension ./scripts/extract-links.js --url https://example.com
+pw-cli run-script --extension=msedge ./scripts/extract-links.js --url https://example.com
+```
+
 Reuse a page that was opened through `pw-cli open`:
 
 ```bash
@@ -332,6 +340,7 @@ pw-cli run-code "await page.goto('https://example.com'); return await page.title
 echo "return await page.url()" | pw-cli run-code
 pw-cli run-script ./scripts/smoke.js --env prod
 pw-cli run-script ./scripts/extract-links.js --url https://example.com --output links.json
+pw-cli run-script --extension ./scripts/extract-links.js --url https://example.com
 pw-cli click "//button[contains(., 'Submit')]"
 pw-cli queue add goto https://example.com
 pw-cli queue add snapshot

package/bin/pw-cli.js

@@ -113,12 +113,16 @@ function getCommandAndSession(argv) {
 }
 
 function parsePwCliGlobalOptions(argv) {
-  const options = { headless: false, profile: 'default', port: 9223 };
+  const options = { headless: false, profile: 'default', port: 9223, extension: false };
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '--headless') {
       options.headless = true;
+    } else if (arg === '--extension') {
+      options.extension = true;
+    } else if (arg.startsWith('--extension=')) {
+      options.extension = arg.split('=')[1] || true;
     } else if (arg === '--profile' && argv[i + 1]) {
       options.profile = argv[++i];
     } else if (arg === '--port' && argv[i + 1]) {
@@ -260,6 +264,7 @@ Global options:
   --version                   print version
   -s, --session <name>        choose browser session
   --headless                  used by pw-cli-managed browser launches
+  --extension[=browser]       run scripts/code through Playwright MCP Bridge (default browser: chrome)
 
 Requirements:
   Node.js 18+
@@ -302,6 +307,7 @@ What the script receives:
 
 Example:
   pw-cli run-script ./scripts/extract-links.js --url https://example.com --output links.json
+  pw-cli run-script --extension ./scripts/extract-links.js --url https://example.com
 `;
 }
 
@@ -736,7 +742,7 @@ async function handleRunScript(rawArgv) {
     process.stderr.write(`pw-cli: ${err.message || err}\n`);
     process.exit(1);
   } finally {
-    await conn.browser.close();
+    await (conn.close ? conn.close() : conn.browser.close());
   }
   process.exit(0);
 }
@@ -783,7 +789,7 @@ async function handleRunCode(rawArgv) {
     process.stderr.write(`pw-cli: ${err.message || err}\n`);
     process.exit(1);
   } finally {
-    await conn.browser.close();
+    await (conn.close ? conn.close() : conn.browser.close());
   }
 
   process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanzhu.me/pw-cli",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "Persistent Playwright browser CLI with headed defaults, profile support, queueing, and script execution",
   "bin": {
     "pw-cli": "./bin/pw-cli.js"
@@ -9,9 +9,12 @@
     "access": "public"
   },
   "scripts": {
+    "changeset": "changeset",
     "lint": "node scripts/check-syntax.js",
     "test": "node --test",
-    "verify": "npm run lint && npm test"
+    "verify": "npm run lint && npm test",
+    "version-packages": "changeset version",
+    "release": "changeset publish"
   },
   "files": [
     "bin/",
@@ -23,8 +26,8 @@
     "node": ">=18"
   },
   "peerDependencies": {
-    "playwright": ">=1.40.0",
-    "@playwright/cli": ">=0.1.0"
+    "@playwright/cli": ">=0.1.0",
+    "playwright": ">=1.40.0"
   },
   "keywords": [
     "playwright",
@@ -42,5 +45,9 @@
   "bugs": {
     "url": "https://github.com/wn0x00/pw-cli/issues"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "@changesets/cli": "^2.30.0",
+    "@types/node": "^25.5.2"
+  }
 }

package/src/browser-manager.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { spawn } = require('child_process');
+const http = require('http');
 const path = require('path');
 const os = require('os');
 const fs = require('fs');
@@ -9,6 +10,27 @@ const { execSync } = require('child_process');
 const { readState, writeState, clearState, getProfileDir } = require('./state');
 const { probeCDP, findFreePort, sleep, fetchActivePageUrl } = require('./utils');
 
+function loadPlaywrightUtilsBundle() {
+  const candidates = [
+    '../node_modules/@playwright/cli/node_modules/playwright-core/lib/utilsBundleImpl',
+    '../node_modules/@playwright/cli/node_modules/playwright-core/lib/utilsBundleImpl/index.js',
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      return require(candidate);
+    } catch (error) {
+      if (error.code !== 'MODULE_NOT_FOUND') {
+        throw error;
+      }
+    }
+  }
+
+  throw new Error('Unable to load playwright-core utilsBundleImpl from @playwright/cli. Reinstall @playwright/cli or playwright.');
+}
+
+const { ws, wsServer } = loadPlaywrightUtilsBundle();
+
 const DAEMON_SCRIPT = path.join(__dirname, 'launch-daemon.js');
 
 // ---------------------------------------------------------------------------
@@ -61,6 +83,27 @@ function loadPlaywright() {
   throw new Error('playwright is not installed. Run: npm install -g playwright');
 }
 
+function normalizeExtensionBrowser(extension) {
+  if (typeof extension === 'string' && extension.trim()) {
+    return extension.trim();
+  }
+  return 'chrome';
+}
+
+function buildExtensionConnectHeaders(extension) {
+  const browser = normalizeExtensionBrowser(extension);
+  const browserType = 'chromium';
+  const launchOptions = browser !== 'chromium' ? { channel: browser } : {};
+
+  return {
+    browserType,
+    headers: {
+      'x-playwright-browser': browserType,
+      'x-playwright-launch-options': JSON.stringify(launchOptions),
+    },
+  };
+}
+
 function pickPage(pages, activeUrl) {
   if (!pages || pages.length === 0) return null;
   if (activeUrl) {
@@ -87,6 +130,385 @@ async function resolveContextAndPage(browser, cdpPort) {
   return { context, page };
 }
 
+function getBrowserExecutableCandidates(browser) {
+  switch (browser) {
+    case 'msedge':
+      return process.platform === 'win32'
+        ? [
+            path.join(process.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)', 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+            path.join(process.env.ProgramFiles || 'C:\\Program Files', 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+          ]
+        : [];
+    case 'chromium':
+    case 'chrome':
+    default:
+      return process.platform === 'win32'
+        ? [
+            path.join(process.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)', 'Google', 'Chrome', 'Application', 'chrome.exe'),
+            path.join(process.env.ProgramFiles || 'C:\\Program Files', 'Google', 'Chrome', 'Application', 'chrome.exe'),
+          ]
+        : [];
+  }
+}
+
+function resolveExtensionExecutablePath(browser) {
+  if (process.env.PLAYWRIGHT_MCP_EXECUTABLE_PATH && fs.existsSync(process.env.PLAYWRIGHT_MCP_EXECUTABLE_PATH)) {
+    return process.env.PLAYWRIGHT_MCP_EXECUTABLE_PATH;
+  }
+
+  const candidates = getBrowserExecutableCandidates(browser);
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(`Unable to find executable for browser channel "${browser}". Set PLAYWRIGHT_MCP_EXECUTABLE_PATH or install ${browser}.`);
+}
+
+class ManualPromise {
+  constructor() {
+    this._settled = false;
+    this.promise = new Promise((resolve, reject) => {
+      this._resolve = value => {
+        if (this._settled) return;
+        this._settled = true;
+        resolve(value);
+      };
+      this._reject = error => {
+        if (this._settled) return;
+        this._settled = true;
+        reject(error);
+      };
+    });
+  }
+
+  resolve(value) {
+    this._resolve(value);
+  }
+
+  reject(error) {
+    this._reject(error);
+  }
+}
+
+class ExtensionConnection {
+  constructor(socket) {
+    this._socket = socket;
+    this._callbacks = new Map();
+    this._lastId = 0;
+    this._socket.on('message', this._onMessage.bind(this));
+    this._socket.on('close', this._onClose.bind(this));
+    this._socket.on('error', this._onError.bind(this));
+  }
+
+  send(method, params) {
+    if (this._socket.readyState !== ws.OPEN) {
+      throw new Error(`Unexpected WebSocket state: ${this._socket.readyState}`);
+    }
+
+    const id = ++this._lastId;
+    this._socket.send(JSON.stringify({ id, method, params }));
+
+    return new Promise((resolve, reject) => {
+      this._callbacks.set(id, {
+        resolve,
+        reject,
+        error: new Error(`Protocol error: ${method}`),
+      });
+    });
+  }
+
+  close(reason) {
+    if (this._socket.readyState === ws.OPEN) {
+      this._socket.close(1000, reason);
+    }
+  }
+
+  _onMessage(message) {
+    const object = JSON.parse(message.toString());
+
+    if (object.id && this._callbacks.has(object.id)) {
+      const callback = this._callbacks.get(object.id);
+      this._callbacks.delete(object.id);
+      if (object.error) {
+        callback.error.message = object.error;
+        callback.reject(callback.error);
+      } else {
+        callback.resolve(object.result);
+      }
+      return;
+    }
+
+    if (!object.id) {
+      this.onmessage?.(object.method, object.params);
+    }
+  }
+
+  _onClose() {
+    for (const callback of this._callbacks.values()) {
+      callback.reject(new Error('WebSocket closed'));
+    }
+    this._callbacks.clear();
+    this.onclose?.(this, 'WebSocket closed');
+  }
+
+  _onError() {
+    for (const callback of this._callbacks.values()) {
+      callback.reject(new Error('WebSocket error'));
+    }
+    this._callbacks.clear();
+  }
+}
+
+class CDPRelayServer {
+  constructor(server, browserChannel, userDataDir, executablePath) {
+    this._playwrightConnection = null;
+    this._extensionConnection = null;
+    this._nextSessionId = 1;
+    this._browserChannel = browserChannel;
+    this._userDataDir = userDataDir;
+    this._executablePath = executablePath;
+    const uuid = crypto.randomUUID();
+    const address = server.address();
+    this._wsHost = `ws://127.0.0.1:${address.port}`;
+    this._cdpPath = `/cdp/${uuid}`;
+    this._extensionPath = `/extension/${uuid}`;
+    this._resetExtensionConnection();
+    this._wss = new wsServer({ server });
+    this._wss.on('connection', this._onConnection.bind(this));
+  }
+
+  cdpEndpoint() {
+    return `${this._wsHost}${this._cdpPath}`;
+  }
+
+  extensionEndpoint() {
+    return `${this._wsHost}${this._extensionPath}`;
+  }
+
+  async ensureExtensionConnectionForMCPContext(clientName) {
+    if (this._extensionConnection) return;
+    this._connectBrowser(clientName);
+    await Promise.race([
+      this._extensionConnectionPromise.promise,
+      new Promise((_, reject) => setTimeout(() => {
+        reject(new Error('Extension connection timeout. Make sure the "Playwright MCP Bridge" extension is installed and enabled.'));
+      }, 5000)),
+    ]);
+  }
+
+  stop() {
+    this.closeConnections('Server stopped');
+    this._wss.close();
+  }
+
+  closeConnections(reason) {
+    this._closePlaywrightConnection(reason);
+    this._closeExtensionConnection(reason);
+  }
+
+  _connectBrowser(clientName) {
+    const relayUrl = `${this._wsHost}${this._extensionPath}`;
+    const url = new URL('chrome-extension://mmlmfjhmonkocbjadbfplnigmagldckm/connect.html');
+    url.searchParams.set('mcpRelayUrl', relayUrl);
+    url.searchParams.set('client', JSON.stringify({ name: clientName }));
+    url.searchParams.set('protocolVersion', '1');
+
+    const executablePath = this._executablePath || resolveExtensionExecutablePath(this._browserChannel);
+    const args = [];
+    if (this._userDataDir) {
+      args.push(`--user-data-dir=${this._userDataDir}`);
+    }
+    args.push(url.toString());
+
+    const child = spawn(executablePath, args, {
+      windowsHide: true,
+      detached: true,
+      shell: false,
+      stdio: 'ignore',
+    });
+    child.unref();
+  }
+
+  _onConnection(socket, request) {
+    const url = new URL(`http://localhost${request.url}`);
+    if (url.pathname === this._cdpPath) {
+      this._handlePlaywrightConnection(socket);
+      return;
+    }
+    if (url.pathname === this._extensionPath) {
+      this._handleExtensionConnection(socket);
+      return;
+    }
+    socket.close(4004, 'Invalid path');
+  }
+
+  _handlePlaywrightConnection(socket) {
+    if (this._playwrightConnection) {
+      socket.close(1000, 'Another CDP client already connected');
+      return;
+    }
+    this._playwrightConnection = socket;
+    socket.on('message', async data => {
+      const message = JSON.parse(data.toString());
+      try {
+        const result = await this._handleCDPCommand(message.method, message.params, message.sessionId);
+        this._sendToPlaywright({ id: message.id, sessionId: message.sessionId, result });
+      } catch (error) {
+        this._sendToPlaywright({
+          id: message.id,
+          sessionId: message.sessionId,
+          error: { message: error.message },
+        });
+      }
+    });
+    socket.on('close', () => {
+      if (this._playwrightConnection !== socket) return;
+      this._playwrightConnection = null;
+      this._closeExtensionConnection('Playwright client disconnected');
+    });
+  }
+
+  _handleExtensionConnection(socket) {
+    if (this._extensionConnection) {
+      socket.close(1000, 'Another extension connection already established');
+      return;
+    }
+    this._extensionConnection = new ExtensionConnection(socket);
+    this._extensionConnection.onclose = current => {
+      if (this._extensionConnection !== current) return;
+      this._resetExtensionConnection();
+      this._closePlaywrightConnection('Extension disconnected');
+    };
+    this._extensionConnection.onmessage = this._handleExtensionMessage.bind(this);
+    this._extensionConnectionPromise.resolve();
+  }
+
+  _handleExtensionMessage(method, params) {
+    if (method !== 'forwardCDPEvent') return;
+    const sessionId = params.sessionId || this._connectedTabInfo?.sessionId;
+    this._sendToPlaywright({
+      sessionId,
+      method: params.method,
+      params: params.params,
+    });
+  }
+
+  async _handleCDPCommand(method, params, sessionId) {
+    switch (method) {
+      case 'Browser.getVersion':
+        return {
+          protocolVersion: '1.3',
+          product: 'Chrome/Extension-Bridge',
+          userAgent: 'CDP-Bridge-Server/1.0.0',
+        };
+      case 'Browser.setDownloadBehavior':
+        return {};
+      case 'Target.setAutoAttach': {
+        if (sessionId) break;
+        const { targetInfo } = await this._extensionConnection.send('attachToTab', {});
+        this._connectedTabInfo = {
+          targetInfo,
+          sessionId: `pw-tab-${this._nextSessionId++}`,
+        };
+        this._sendToPlaywright({
+          method: 'Target.attachedToTarget',
+          params: {
+            sessionId: this._connectedTabInfo.sessionId,
+            targetInfo: {
+              ...this._connectedTabInfo.targetInfo,
+              attached: true,
+            },
+            waitingForDebugger: false,
+          },
+        });
+        return {};
+      }
+      case 'Target.getTargetInfo':
+        return this._connectedTabInfo?.targetInfo;
+      default:
+        return this._forwardToExtension(method, params, sessionId);
+    }
+  }
+
+  async _forwardToExtension(method, params, sessionId) {
+    if (!this._extensionConnection) {
+      throw new Error('Extension not connected');
+    }
+    if (this._connectedTabInfo?.sessionId === sessionId) {
+      sessionId = undefined;
+    }
+    return this._extensionConnection.send('forwardCDPCommand', { sessionId, method, params });
+  }
+
+  _sendToPlaywright(message) {
+    if (this._playwrightConnection?.readyState === ws.OPEN) {
+      this._playwrightConnection.send(JSON.stringify(message));
+    }
+  }
+
+  _closeExtensionConnection(reason) {
+    this._extensionConnection?.close(reason);
+    this._extensionConnectionPromise.reject(new Error(reason));
+    this._resetExtensionConnection();
+  }
+
+  _resetExtensionConnection() {
+    this._connectedTabInfo = undefined;
+    this._extensionConnection = null;
+    this._extensionConnectionPromise = new ManualPromise();
+  }
+
+  _closePlaywrightConnection(reason) {
+    if (this._playwrightConnection?.readyState === ws.OPEN) {
+      this._playwrightConnection.close(1000, reason);
+    }
+    this._playwrightConnection = null;
+  }
+}
+
+async function startExtensionRelay(extension) {
+  const browser = normalizeExtensionBrowser(extension);
+  if (!['chrome', 'chromium', 'msedge'].includes(browser)) {
+    throw new Error(`--extension currently supports Chromium-based channels only (received "${browser}")`);
+  }
+
+  const server = http.createServer();
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  const relay = new CDPRelayServer(server, browser, null, null);
+  await relay.ensureExtensionConnectionForMCPContext('pw-cli');
+  return { relay, server };
+}
+
+async function getExtensionConnection(extension) {
+  const playwright = loadPlaywright();
+  const { relay, server } = await startExtensionRelay(extension);
+
+  try {
+    const browser = await playwright.chromium.connectOverCDP(relay.cdpEndpoint());
+    const { context, page } = await resolveContextAndPage(browser, null);
+    return {
+      browser,
+      context,
+      page,
+      playwright,
+      close: async () => {
+        relay.stop();
+        await new Promise(resolve => server.close(resolve));
+        await browser.close();
+      },
+    };
+  } catch (error) {
+    relay.stop();
+    await new Promise(resolve => server.close(resolve));
+    throw error;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Our own CDP-based browser launcher (fallback when playwright-cli not running)
 // ---------------------------------------------------------------------------
@@ -147,7 +569,11 @@ async function launchBrowser({ headless = false, profile = 'default', port: pref
 // ---------------------------------------------------------------------------
 // getConnection — tries playwright-cli browser first, then our own
 // ---------------------------------------------------------------------------
-async function getConnection({ headless = false, profile = 'default', port: preferredPort = 9223 } = {}) {
+async function getConnection({ headless = false, profile = 'default', port: preferredPort = 9223, extension = false } = {}) {
+  if (extension) {
+    return getExtensionConnection(extension);
+  }
+
   const playwright = loadPlaywright();
 
   // 1. Try to reuse playwright-cli's browser via its CDP port
@@ -158,7 +584,15 @@ async function getConnection({ headless = false, profile = 'default', port: pref
       try {
         const browser = await playwright.chromium.connectOverCDP(`http://127.0.0.1:${cliCdpPort}`);
         const { context, page } = await resolveContextAndPage(browser, cliCdpPort);
-        return { browser, context, page, playwright };
+        return {
+          browser,
+          context,
+          page,
+          playwright,
+          close: async () => {
+            await browser.close();
+          },
+        };
       } catch {
         // fall through to own browser
       }
@@ -188,7 +622,15 @@ async function getConnection({ headless = false, profile = 'default', port: pref
   const browser = await playwright.chromium.connectOverCDP(cdpUrl);
   const { context, page } = await resolveContextAndPage(browser, state ? state.port : null);
 
-  return { browser, context, page, playwright };
+  return {
+    browser,
+    context,
+    page,
+    playwright,
+    close: async () => {
+      await browser.close();
+    },
+  };
 }
 
 async function killBrowser() {
@@ -208,4 +650,11 @@ async function killBrowser() {
   return true;
 }
 
-module.exports = { getConnection, killBrowser, getPlaywrightCliCdpPort, pickPage };
+module.exports = {
+  getConnection,
+  killBrowser,
+  getPlaywrightCliCdpPort,
+  pickPage,
+  buildExtensionConnectHeaders,
+  normalizeExtensionBrowser,
+};

package/src/cli.js

@@ -6,7 +6,7 @@ const { readState } = require('./state');
 const { readStdin, die, probeCDP } = require('./utils');
 
 function parseArgs(argv) {
-  const global = { headless: false, profile: 'default', port: 9222 };
+  const global = { headless: false, profile: 'default', port: 9222, extension: false };
   const rest = [];
   let i = 0;
 
@@ -14,6 +14,10 @@ function parseArgs(argv) {
     const arg = argv[i];
     if (arg === '--headless') {
       global.headless = true;
+    } else if (arg === '--extension') {
+      global.extension = true;
+    } else if (arg.startsWith('--extension=')) {
+      global.extension = arg.split('=')[1] || true;
     } else if (arg === '--profile' && argv[i + 1]) {
       global.profile = argv[++i];
     } else if (arg === '--port' && argv[i + 1]) {
@@ -47,7 +51,7 @@ async function cmdRunCode(rest, opts) {
       console.log(result);
     }
   } finally {
-    await conn.browser.close(); // disconnect only, browser keeps running
+    await (conn.close ? conn.close() : conn.browser.close());
   }
 }
 
@@ -65,7 +69,8 @@ Script format (standard module):
   Legacy bare-code scripts (without module.exports) are still supported.
 
 Example:
-  pw-cli run-script ./scripts/extract-links.js --url https://example.com --output links.json`;
+  pw-cli run-script ./scripts/extract-links.js --url https://example.com --output links.json
+  pw-cli run-script --extension ./scripts/extract-links.js --url https://example.com`;
 }
 
 async function cmdRunScript(rest, opts) {
@@ -81,7 +86,7 @@ async function cmdRunScript(rest, opts) {
       console.log(result);
     }
   } finally {
-    await conn.browser.close();
+    await (conn.close ? conn.close() : conn.browser.close());
   }
 }
 
@@ -117,6 +122,7 @@ USAGE
 
 GLOBAL OPTIONS
   --headless          Run browser headlessly (default: headed)
+  --extension[=name]  Run code/scripts through Playwright MCP Bridge (default: chrome)
   --profile <name>    Named profile to use (default: "default")
   --port <number>     CDP port (default: 9222)
 
@@ -134,6 +140,7 @@ EXAMPLES
   pw-cli run-code "await page.goto('https://example.com'); console.log(await page.title())"
   echo "await page.screenshot({ path: 'out.png' })" | pw-cli run-code
   pw-cli run-script ./scrape.js --url https://example.com
+  pw-cli run-script --extension ./scrape.js --url https://example.com
   pw-cli run-script ./scripts/extract-links.js --url https://example.com --output links.json
   pw-cli --headless run-code "await page.goto('https://example.com')"
   pw-cli --profile work status