@guanzhu.me/pw-cli 0.0.11 → 0.0.13

package/README.md

@@ -74,6 +74,52 @@ 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:
+
+```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}`;
+```
+
+```bash
+pw-cli run-script ./scripts/extract-links.js --url https://example.com --output links.json
+```
+
 Reuse a page that was opened through `pw-cli open`:
 
 ```bash
@@ -108,7 +154,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
+- `run-script` executes a local `.js` file with Playwright globals, CommonJS globals, and `args`
 - Common element commands accept XPath refs
 - `queue` lets you batch multiple commands and run them in order
 
@@ -235,7 +281,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 page/context/browser globals
+run-script <file> [...]     run a local JavaScript file with Playwright globals and script args
 network                     list all network requests since loading the page
 tracing-start               start trace recording
 tracing-stop                stop trace recording
@@ -289,6 +335,7 @@ pw-cli open https://example.com
 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 click "//button[contains(., 'Submit')]"
 pw-cli queue add goto https://example.com
 pw-cli queue add snapshot

package/bin/pw-cli.js

@@ -229,7 +229,7 @@ DevTools:
   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 page/context/browser globals
+  run-script <file> [...]     run a local JavaScript file with Playwright globals and script args
   network                     list all network requests since loading the page
   tracing-start               start trace recording
   tracing-stop                stop trace recording
@@ -271,13 +271,40 @@ Examples:
   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 click "//button[contains(., 'Submit')]"
   pw-cli queue add goto https://example.com
   pw-cli queue add snapshot
   pw-cli queue run
+
+run-script example:
+  // 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(x => x.href)
+  );
+  fs.writeFileSync(output, JSON.stringify({ url, count: links.length, links }, null, 2));
+  return \`saved \${links.length} links to \${output}\`;
 `.trim() + '\n');
 }
 
+function getRunScriptHelpText() {
+  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
+
+Example:
+  pw-cli run-script ./scripts/extract-links.js --url https://example.com --output links.json
+`;
+}
+
 // Management commands that don't need a running browser
 const MGMT_COMMANDS = new Set([
   'open', 'close', 'list', 'kill-all', 'close-all', 'delete-data',
@@ -631,7 +658,7 @@ async function handleRunScript(rawArgv) {
   const [scriptPath, ...scriptArgs] = positionals;
 
   if (!scriptPath) {
-    process.stderr.write('pw-cli: run-script requires a script path\n\nUsage: pw-cli run-script <file.js> [args...]\n');
+    process.stderr.write(`pw-cli: run-script requires a script path\n\n${getRunScriptHelpText()}`);
     process.exit(1);
   }
   if (!fs.existsSync(path.resolve(scriptPath))) {
@@ -719,6 +746,13 @@ async function main() {
     return;
   }
 
+  if (command === 'run-scirpt') {
+    process.stderr.write('pw-cli: unknown command: run-scirpt\n');
+    process.stderr.write('Did you mean: run-script?\n\n');
+    process.stdout.write(getRunScriptHelpText());
+    process.exit(1);
+  }
+
   // ── queue: batch actions and run them together ────────────────────────────
   if (command === 'queue') {
     await handleQueue(rawArgv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanzhu.me/pw-cli",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "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

@@ -5,6 +5,7 @@ const path = require('path');
 const os = require('os');
 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');
 
@@ -43,6 +44,23 @@ function getPlaywrightCliCdpPort(sessionName = 'default') {
   return session?.resolvedConfig?.browser?.launchOptions?.cdpPort || null;
 }
 
+function loadPlaywright() {
+  try {
+    return require('playwright');
+  } catch {}
+
+  try {
+    const globalRoot = execSync('npm root -g', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    const cliPlaywrightPath = path.join(globalRoot, '@playwright', 'cli', 'node_modules', 'playwright');
+    return require(cliPlaywrightPath);
+  } catch {}
+
+  throw new Error('playwright is not installed. Run: npm install -g playwright');
+}
+
 // ---------------------------------------------------------------------------
 // Our own CDP-based browser launcher (fallback when playwright-cli not running)
 // ---------------------------------------------------------------------------
@@ -104,12 +122,7 @@ 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 } = {}) {
-  let playwright;
-  try {
-    playwright = require('playwright');
-  } catch {
-    throw new Error('playwright is not installed. Run: npm install -g playwright');
-  }
+  const playwright = loadPlaywright();
 
   // 1. Try to reuse playwright-cli's browser via its CDP port
   const cliCdpPort = getPlaywrightCliCdpPort();

package/src/cli.js

@@ -51,10 +51,23 @@ async function cmdRunCode(rest, opts) {
   }
 }
 
+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
+
+Example:
+  pw-cli run-script ./scripts/extract-links.js --url https://example.com --output links.json`;
+}
+
 async function cmdRunScript(rest, opts) {
   const [scriptPath, ...scriptArgs] = rest;
   if (!scriptPath) {
-    die('No script path provided.\n\nUsage: pw-cli run-script <file.js> [args...]');
+    die(`No script path provided.\n\n${getRunScriptHelp()}`);
   }
 
   const conn = await getConnection(opts);
@@ -105,20 +118,34 @@ GLOBAL OPTIONS
 
 COMMANDS
   run-code [code]          Execute inline JS (reads stdin if omitted)
-  run-script <file> [...]  Execute a .js script with optional args
+  run-script <file> [...]  Execute a local .js file with Playwright globals and script args
   kill                     Stop the running browser
   status                   Show browser status
 
 SCRIPT GLOBALS
-  page, context, browser, playwright, args, require, __filename, __dirname
+  page, context, browser, playwright, args
+  require, module, exports, __filename, __dirname
 
 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 ./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
   pw-cli kill
+
+RUN-SCRIPT EXAMPLE
+  // 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(x => x.href)
+  );
+  fs.writeFileSync(output, JSON.stringify({ url, count: links.length, links }, null, 2));
+  return \`saved \${links.length} links to \${output}\`;
 `.trim());
 }
 
@@ -131,6 +158,13 @@ async function run(argv) {
     return;
   }
 
+  if (command === 'run-scirpt') {
+    console.error('Unknown command: run-scirpt');
+    console.error('Did you mean: run-script?\n');
+    console.log(getRunScriptHelp());
+    process.exit(1);
+  }
+
   try {
     switch (command) {
       case 'run-code':

package/src/launch-daemon.js

@@ -6,6 +6,8 @@
 // Args: --profile-dir <dir> --port <port> [--headless]
 
 const args = process.argv.slice(2);
+const path = require('path');
+const { execSync } = require('child_process');
 
 function getArg(name) {
   const i = args.indexOf(name);
@@ -16,22 +18,48 @@ const profileDir = getArg('--profile-dir');
 const port = parseInt(getArg('--port') || '9222', 10);
 const headless = args.includes('--headless');
 
+function loadPlaywright() {
+  try {
+    return require('playwright');
+  } catch {}
+
+  try {
+    const globalRoot = execSync('npm root -g', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    const cliPlaywrightPath = path.join(globalRoot, '@playwright', 'cli', 'node_modules', 'playwright');
+    return require(cliPlaywrightPath);
+  } catch {}
+
+  throw new Error('playwright not found - run: npm install -g playwright');
+}
+
+function formatLaunchError(error) {
+  const message = error && error.message ? error.message : String(error);
+  if (message.includes("Executable doesn't exist")) {
+    return [
+      'Playwright browser executable is not installed for the selected engine.',
+      'pw-cli now prefers your local Chrome install for fallback launches.',
+      'Run one of the following commands first:',
+      '  pw-cli open',
+      '  pw-cli install-browser',
+      '  npx playwright install chromium',
+    ].join('\n');
+  }
+  return message;
+}
+
 if (!profileDir) {
   process.stderr.write('ERROR:missing --profile-dir\n');
   process.exit(1);
 }
 
 (async () => {
-  let playwright;
-  try {
-    playwright = require('playwright');
-  } catch (e) {
-    process.stdout.write(`ERROR:playwright not found - run: npm install -g playwright\n`);
-    process.exit(1);
-  }
-
   try {
+    const playwright = loadPlaywright();
     const context = await playwright.chromium.launchPersistentContext(profileDir, {
+      channel: 'chrome',
       headless,
       args: [`--remote-debugging-port=${port}`],
       ignoreDefaultArgs: ['--enable-automation'],
@@ -59,7 +87,7 @@ if (!profileDir) {
     // Prevent premature exit
     process.stdin.resume();
   } catch (e) {
-    process.stdout.write(`ERROR:${e.message}\n`);
+    process.stdout.write(`ERROR:${formatLaunchError(e)}\n`);
     process.exit(1);
   }
 })();