@guanzhu.me/pw-cli 0.0.13 → 0.0.15

package/README.md

@@ -20,8 +20,8 @@ Raw Playwright is excellent for test suites and scripted automation, but ad hoc
 - Headed mode by default
 - Named profile support
 - `run-code` for inline JavaScript or piped stdin
-- `run-script` for executing local JavaScript files
-- `run-script` supports CommonJS-style scripts that use `require`, `module`, `exports`, `__filename`, and `__dirname`
+- `run-script` for executing local JavaScript files with `main` function convention
+- `run-script` supports standard CommonJS modules (`require`, `__filename`, `__dirname`) and also bare-code scripts
 - Queue management for multi-step flows
 - Automatic browser launch when needed
 - XPath command conversion for common actions
@@ -74,46 +74,42 @@ Run a local script:
 pw-cli run-script ./scrape.js --url https://example.com
 ```
 
-`run-script` is intended for multi-step automation. Your script can use:
-
-- Playwright globals: `page`, `context`, `browser`, `playwright`
-- Script args: `args`
-- CommonJS globals: `require`, `module`, `exports`, `__filename`, `__dirname`
-
-More complete example:
+`run-script` is intended for multi-step automation. Define an `async function main` that receives Playwright globals as a single object:
 
 ```javascript
 // scripts/extract-links.js
 const fs = require('fs');
 
-const url = args[args.indexOf('--url') + 1] || 'https://example.com';
-const output = args[args.indexOf('--output') + 1] || 'links.json';
-
-await page.goto(url, { waitUntil: 'networkidle' });
-
-const links = await page.locator('a').evaluateAll(nodes =>
-  nodes
-    .map(a => ({
-      text: a.textContent.trim(),
-      href: a.href,
-    }))
-    .filter(item => item.href)
-);
-
-fs.writeFileSync(
-  output,
-  JSON.stringify(
-    {
-      url,
-      count: links.length,
-      links,
-    },
-    null,
-    2
-  )
-);
-
-return `saved ${links.length} links to ${output}`;
+async function main({ page, args }) {
+  const url = args[args.indexOf('--url') + 1] || 'https://example.com';
+  const output = args[args.indexOf('--output') + 1] || 'links.json';
+
+  await page.goto(url, { waitUntil: 'domcontentloaded' });
+
+  const links = await page.locator('a').evaluateAll(nodes =>
+    nodes
+      .map(a => ({
+        text: a.textContent.trim(),
+        href: a.href,
+      }))
+      .filter(item => item.href)
+  );
+
+  fs.writeFileSync(
+    output,
+    JSON.stringify(
+      {
+        url,
+        count: links.length,
+        links,
+      },
+      null,
+      2
+    )
+  );
+
+  return `saved ${links.length} links to ${output}`;
+}
 ```
 
 ```bash
@@ -154,7 +150,7 @@ pw-cli list
 - `open` injects headed and persistent defaults
 - Browser-backed commands can auto-open a browser session if needed
 - `run-code` accepts stdin and plain inline statements
-- `run-script` executes a local `.js` file with Playwright globals, CommonJS globals, and `args`
+- `run-script` executes a local `.js` file — auto-detects `main` function, `module.exports`, or bare code
 - Common element commands accept XPath refs
 - `queue` lets you batch multiple commands and run them in order
 
@@ -281,7 +277,7 @@ console [min-level]         list console messages
 run-code <code>             run playwright code snippet
                             pw-cli: reads code from stdin when <code> is omitted
                             pw-cli: wraps plain statements in an async function
-run-script <file> [...]     run a local JavaScript file with Playwright globals and script args
+run-script <file> [...]     run a local JavaScript file (main function or module.exports)
 network                     list all network requests since loading the page
 tracing-start               start trace recording
 tracing-stop                stop trace recording

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanzhu.me/pw-cli",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Persistent Playwright browser CLI with headed defaults, profile support, queueing, and script execution",
   "bin": {
     "pw-cli": "./bin/pw-cli.js"

package/src/browser-manager.js

@@ -7,7 +7,7 @@ const fs = require('fs');
 const crypto = require('crypto');
 const { execSync } = require('child_process');
 const { readState, writeState, clearState, getProfileDir } = require('./state');
-const { probeCDP, findFreePort, sleep } = require('./utils');
+const { probeCDP, findFreePort, sleep, fetchActivePageUrl } = require('./utils');
 
 const DAEMON_SCRIPT = path.join(__dirname, 'launch-daemon.js');
 
@@ -61,6 +61,32 @@ function loadPlaywright() {
   throw new Error('playwright is not installed. Run: npm install -g playwright');
 }
 
+function pickPage(pages, activeUrl) {
+  if (!pages || pages.length === 0) return null;
+  if (activeUrl) {
+    const matchingPages = pages.filter(page => {
+      try {
+        return page.url() === activeUrl;
+      } catch {
+        return false;
+      }
+    });
+    if (matchingPages.length > 0) {
+      return matchingPages[matchingPages.length - 1];
+    }
+  }
+  return pages[pages.length - 1];
+}
+
+async function resolveContextAndPage(browser, cdpPort) {
+  const contexts = browser.contexts();
+  const context = contexts.length > 0 ? contexts[0] : await browser.newContext();
+  const pages = context.pages();
+  const activeUrl = cdpPort ? await fetchActivePageUrl(cdpPort) : null;
+  const page = pickPage(pages, activeUrl) || await context.newPage();
+  return { context, page };
+}
+
 // ---------------------------------------------------------------------------
 // Our own CDP-based browser launcher (fallback when playwright-cli not running)
 // ---------------------------------------------------------------------------
@@ -131,10 +157,7 @@ async function getConnection({ headless = false, profile = 'default', port: pref
     if (alive) {
       try {
         const browser = await playwright.chromium.connectOverCDP(`http://127.0.0.1:${cliCdpPort}`);
-        const contexts = browser.contexts();
-        const context = contexts.length > 0 ? contexts[0] : await browser.newContext();
-        const pages = context.pages();
-        const page = pages.length > 0 ? pages[0] : await context.newPage();
+        const { context, page } = await resolveContextAndPage(browser, cliCdpPort);
         return { browser, context, page, playwright };
       } catch {
         // fall through to own browser
@@ -163,10 +186,7 @@ async function getConnection({ headless = false, profile = 'default', port: pref
   }
 
   const browser = await playwright.chromium.connectOverCDP(cdpUrl);
-  const contexts = browser.contexts();
-  const context = contexts.length > 0 ? contexts[0] : await browser.newContext();
-  const pages = context.pages();
-  const page = pages.length > 0 ? pages[0] : await context.newPage();
+  const { context, page } = await resolveContextAndPage(browser, state ? state.port : null);
 
   return { browser, context, page, playwright };
 }
@@ -188,4 +208,4 @@ async function killBrowser() {
   return true;
 }
 
-module.exports = { getConnection, killBrowser, getPlaywrightCliCdpPort };
+module.exports = { getConnection, killBrowser, getPlaywrightCliCdpPort, pickPage };

package/src/cli.js

@@ -55,10 +55,14 @@ function getRunScriptHelp() {
   return `Usage:
   pw-cli run-script <file.js> [args...]
 
-What the script receives:
-  - Playwright globals: page, context, browser, playwright
-  - Script args array: args
-  - CommonJS globals: require, module, exports, __filename, __dirname
+Script format (standard module):
+  module.exports = async function ({ page, context, browser, playwright, args }) {
+    // your code here
+  };
+
+  The exported function receives { page, context, browser, playwright, args }.
+  CommonJS globals (require, __filename, __dirname) are available as usual.
+  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`;

package/src/executor.js

@@ -79,25 +79,7 @@ async function execCode(code, { browser, context, page, playwright }) {
   return withTemporaryGlobals(globals, () => runCode(code, globals));
 }
 
-async function execScript(scriptPath, scriptArgs, { browser, context, page, playwright }) {
-  const absPath = path.resolve(scriptPath);
-  if (!fs.existsSync(absPath)) {
-    const err = new Error(`Script not found: ${absPath}`);
-    err.code = 'ENOENT';
-    throw err;
-  }
-
-  const code = fs.readFileSync(absPath, 'utf8');
-  const moduleDir = path.dirname(absPath);
-  const scriptModule = {
-    id: absPath,
-    filename: absPath,
-    path: moduleDir,
-    exports: {},
-    loaded: false,
-    children: [],
-    parent: require.main || module,
-  };
+function buildScriptRequire(absPath) {
   const localRequire = Module.createRequire(absPath);
   const scriptRequire = function scriptRequire(id) {
     try {
@@ -119,16 +101,92 @@ async function execScript(scriptPath, scriptArgs, { browser, context, page, play
   scriptRequire.resolve = localRequire.resolve.bind(localRequire);
   scriptRequire.cache = require.cache;
   scriptRequire.extensions = require.extensions;
+  return scriptRequire;
+}
+
+function isModuleExport(code) {
+  return /\bmodule\.exports\b/.test(code) || /\bexports\./.test(code);
+}
+
+function hasMainFunction(code) {
+  return /\b(async\s+)?function\s+main\s*\(/.test(code);
+}
+
+async function execScript(scriptPath, scriptArgs, { browser, context, page, playwright }) {
+  const absPath = path.resolve(scriptPath);
+  if (!fs.existsSync(absPath)) {
+    const err = new Error(`Script not found: ${absPath}`);
+    err.code = 'ENOENT';
+    throw err;
+  }
+
+  const code = fs.readFileSync(absPath, 'utf8');
+  const pwGlobals = { page, context, browser, playwright, args: scriptArgs };
+
+  // Standard module pattern: script uses module.exports = function(...)
+  // The exported function receives Playwright globals as a single object argument.
+  if (isModuleExport(code)) {
+    return execModuleScript(absPath, code, pwGlobals);
+  }
+
+  // Legacy bare-code pattern: script body is executed directly with globals as local variables.
+  return execBareScript(absPath, code, pwGlobals);
+}
+
+async function execModuleScript(absPath, code, pwGlobals) {
+  const moduleDir = path.dirname(absPath);
+  const scriptRequire = buildScriptRequire(absPath);
+  const scriptModule = {
+    id: absPath,
+    filename: absPath,
+    path: moduleDir,
+    exports: {},
+    loaded: false,
+    children: [],
+    parent: require.main || module,
+    require: scriptRequire,
+  };
   scriptRequire.main = scriptModule;
 
-  scriptModule.require = scriptRequire;
+  // Evaluate the module body to populate module.exports.
+  // Playwright globals are available during evaluation for backward compat.
+  const wrapGlobals = {
+    ...pwGlobals,
+    require: scriptRequire,
+    module: scriptModule,
+    exports: scriptModule.exports,
+    console,
+    process,
+    __filename: absPath,
+    __dirname: moduleDir,
+  };
+  await withTemporaryGlobals(wrapGlobals, () => runProgram(code, wrapGlobals));
+  scriptModule.loaded = true;
+
+  const exported = scriptModule.exports;
+  if (typeof exported === 'function') {
+    return exported(pwGlobals);
+  }
+  return exported;
+}
+
+async function execBareScript(absPath, code, pwGlobals) {
+  const moduleDir = path.dirname(absPath);
+  const scriptRequire = buildScriptRequire(absPath);
+  const scriptModule = {
+    id: absPath,
+    filename: absPath,
+    path: moduleDir,
+    exports: {},
+    loaded: false,
+    children: [],
+    parent: require.main || module,
+    require: scriptRequire,
+  };
+  scriptRequire.main = scriptModule;
 
   const globals = {
-    browser,
-    context,
-    page,
-    playwright,
-    args: scriptArgs,
+    ...pwGlobals,
     require: scriptRequire,
     module: scriptModule,
     exports: scriptModule.exports,
@@ -137,7 +195,11 @@ async function execScript(scriptPath, scriptArgs, { browser, context, page, play
     __filename: absPath,
     __dirname: moduleDir,
   };
-  const result = await withTemporaryGlobals(globals, () => runProgram(code, globals));
+  // If the script defines a main function, append a call to it.
+  const finalCode = hasMainFunction(code)
+    ? code + '\nreturn main({ page, context, browser, playwright, args });'
+    : code;
+  const result = await withTemporaryGlobals(globals, () => runProgram(finalCode, globals));
   scriptModule.loaded = true;
   return result === undefined ? scriptModule.exports : result;
 }

package/src/launch-daemon.js

@@ -62,7 +62,7 @@ if (!profileDir) {
       channel: 'chrome',
       headless,
       args: [`--remote-debugging-port=${port}`],
-      ignoreDefaultArgs: ['--enable-automation'],
+      ignoreDefaultArgs: ['--enable-automation', '--no-sandbox'],
     });
 
     // Wait briefly for CDP to be ready, then signal