@guanzhu.me/pw-cli 0.0.14 → 0.0.16

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/bin/pw-cli.js

@@ -771,6 +771,43 @@ async function main() {
     return;
   }
 
+  // ── Fast path: send command directly to playwright-cli daemon socket ────
+  // Skip heavy setup (npm root -g, require playwright, CDP probes) entirely.
+  // Only for commands that the daemon handles AND don't need local preprocessing.
+  if (command && !MGMT_COMMANDS.has(command)) {
+    // Build the args array the daemon expects: strip session flags, keep command + args
+    let fastArgs = [...rawArgv];
+    // Remove session flags (-s xxx / --session xxx / --session=xxx)
+    fastArgs = fastArgs.filter((a, i, arr) => {
+      if (a === '-s' || a === '--session') { arr[i + 1] = undefined; return false; }
+      if (a === undefined) return false;
+      if (a.startsWith('-s=') || a.startsWith('--session=')) return false;
+      return true;
+    }).filter(Boolean);
+
+    // Apply XPath conversion if needed
+    fastArgs = convertXPathCommand(fastArgs);
+
+    // Handle run-code wrapping for XPath-converted commands
+    if (fastArgs[0] === 'run-code' && fastArgs.length > 1) {
+      const code = fastArgs.slice(1).join(' ');
+      fastArgs = ['run-code', wrapCodeIfNeeded(code)];
+    }
+
+    const { sendCommand } = require('../src/fast-send');
+    const result = await sendCommand(fastArgs, session);
+    if (result !== null) {
+      // Daemon responded — use its result
+      if (result.isError) {
+        process.stderr.write(`${result.text}\n`);
+        process.exit(1);
+      }
+      if (result.text) process.stdout.write(result.text + '\n');
+      return;
+    }
+    // result === null means daemon not running — fall through to full path
+  }
+
   // ── From here on: delegate to playwright-cli (with enhancements) ─────────
   const cliPath = findPlaywrightCli();
   if (!cliPath) {

package/package.json

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

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/fast-send.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const net = require('net');
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const HOME_DIR = os.homedir();
+const PW_CLI_DIR = path.join(HOME_DIR, '.pw-cli');
+const WORKSPACE_HASH = crypto.createHash('sha1')
+  .update(PW_CLI_DIR)
+  .digest('hex')
+  .substring(0, 16);
+
+function getSocketPath(sessionName = 'default') {
+  const socketName = `${sessionName}.sock`;
+  if (os.platform() === 'win32')
+    return `\\\\.\\pipe\\${WORKSPACE_HASH}-${socketName}`;
+  const socketsDir = process.env.PLAYWRIGHT_DAEMON_SOCKETS_DIR || path.join(os.tmpdir(), 'playwright-cli');
+  return path.join(socketsDir, WORKSPACE_HASH, socketName);
+}
+
+function getVersion() {
+  // Read version from session file (already written by playwright-cli daemon)
+  const sessionFile = path.join(
+    os.platform() === 'win32'
+      ? path.join(process.env.LOCALAPPDATA || path.join(HOME_DIR, 'AppData', 'Local'), 'ms-playwright', 'daemon')
+      : os.platform() === 'darwin'
+        ? path.join(HOME_DIR, 'Library', 'Caches', 'ms-playwright', 'daemon')
+        : path.join(process.env.XDG_CACHE_HOME || path.join(HOME_DIR, '.cache'), 'ms-playwright', 'daemon'),
+    WORKSPACE_HASH,
+    'default.session'
+  );
+  try {
+    const session = JSON.parse(fs.readFileSync(sessionFile, 'utf8'));
+    return session.version;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Convert a string array to minimist-style object.
+ * The daemon expects { _: [cmd, arg1, ...], flagName: value, ... }.
+ */
+function toMinimistArgs(argv) {
+  const result = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('-')) {
+        result[key] = next;
+        i++;
+      } else {
+        result[key] = true;
+      }
+    } else if (arg.startsWith('-') && arg.length === 2) {
+      const key = arg.slice(1);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('-')) {
+        result[key] = next;
+        i++;
+      } else {
+        result[key] = true;
+      }
+    } else {
+      result._.push(arg);
+    }
+  }
+  return result;
+}
+
+/**
+ * Send a command directly to the playwright-cli daemon socket.
+ * Returns { text, isError } or null (daemon not running).
+ */
+function sendCommand(args, sessionName = 'default') {
+  const socketPath = getSocketPath(sessionName);
+  const version = getVersion();
+  if (!version) return Promise.resolve(null);
+
+  const minimistArgs = toMinimistArgs(args);
+
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath, () => {
+      const message = JSON.stringify({
+        id: 1,
+        method: 'run',
+        params: { args: minimistArgs, cwd: process.cwd() },
+        version,
+      }) + '\n';
+      socket.write(message);
+    });
+
+    let buf = '';
+    socket.on('data', chunk => {
+      buf += chunk.toString();
+      const nlIdx = buf.indexOf('\n');
+      if (nlIdx === -1) return;
+      const line = buf.slice(0, nlIdx);
+      clearTimeout(timer);
+      socket.destroy();
+      try {
+        const resp = JSON.parse(line);
+        if (resp.error) {
+          reject(new Error(resp.error));
+        } else {
+          resolve(resp.result);
+        }
+      } catch (e) {
+        reject(new Error('Invalid daemon response'));
+      }
+    });
+
+    socket.on('error', () => { clearTimeout(timer); resolve(null); }); // connection failed = daemon not running
+    const timer = setTimeout(() => { socket.destroy(); resolve(null); }, 3000);
+  });
+}
+
+module.exports = { sendCommand, getSocketPath, getVersion };

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