@guanzhu.me/pw-cli 0.0.1

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@guanzhu.me/pw-cli",
+  "version": "0.0.1",
+  "description": "Persistent Playwright browser CLI with headed defaults, profile support, queueing, and script execution",
+  "bin": {
+    "pw-cli": "./bin/pw-cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "node scripts/check-syntax.js",
+    "test": "node --test",
+    "verify": "npm run lint && npm test"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.40.0",
+    "@playwright/cli": ">=0.1.0"
+  },
+  "keywords": [
+    "playwright",
+    "cli",
+    "browser",
+    "automation",
+    "chromium",
+    "testing"
+  ],
+  "license": "MIT"
+}

package/src/browser-manager.js

@@ -0,0 +1,178 @@
+'use strict';
+
+const { spawn } = require('child_process');
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+const crypto = require('crypto');
+const { readState, writeState, clearState, getProfileDir } = require('./state');
+const { probeCDP, findFreePort, sleep } = require('./utils');
+
+const DAEMON_SCRIPT = path.join(__dirname, 'launch-daemon.js');
+
+// ---------------------------------------------------------------------------
+// playwright-cli session integration
+// ---------------------------------------------------------------------------
+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 getDaemonDir() {
+  if (process.platform === 'win32') {
+    return path.join(process.env.LOCALAPPDATA || path.join(HOME_DIR, 'AppData', 'Local'), 'ms-playwright', 'daemon');
+  } else if (process.platform === 'darwin') {
+    return path.join(HOME_DIR, 'Library', 'Caches', 'ms-playwright', 'daemon');
+  }
+  return path.join(process.env.XDG_CACHE_HOME || path.join(HOME_DIR, '.cache'), 'ms-playwright', 'daemon');
+}
+
+function readPlaywrightCliSession(sessionName = 'default') {
+  const sessionFile = path.join(getDaemonDir(), WORKSPACE_HASH, `${sessionName}.session`);
+  try {
+    return JSON.parse(fs.readFileSync(sessionFile, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function getPlaywrightCliCdpPort(sessionName = 'default') {
+  const session = readPlaywrightCliSession(sessionName);
+  return session?.resolvedConfig?.browser?.launchOptions?.cdpPort || null;
+}
+
+// ---------------------------------------------------------------------------
+// Our own CDP-based browser launcher (fallback when playwright-cli not running)
+// ---------------------------------------------------------------------------
+async function launchBrowser({ headless = false, profile = 'default', port: preferredPort = 9223 } = {}) {
+  const profileDir = getProfileDir(profile);
+  const port = await findFreePort(preferredPort);
+
+  const daemonArgs = [
+    DAEMON_SCRIPT,
+    '--profile-dir', profileDir,
+    '--port', String(port),
+  ];
+  if (headless) daemonArgs.push('--headless');
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, daemonArgs, {
+      detached: true,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+
+    let output = '';
+    const timer = setTimeout(() => {
+      child.stdout.destroy();
+      reject(new Error('Browser launch timed out (15s)'));
+    }, 15000);
+
+    child.stdout.on('data', chunk => {
+      output += chunk.toString();
+      const readyMatch = output.match(/READY:(\d+)/);
+      const errorMatch = output.match(/ERROR:(.*)/);
+
+      if (readyMatch) {
+        clearTimeout(timer);
+        const actualPort = parseInt(readyMatch[1], 10);
+        writeState({ port: actualPort, cdpUrl: `http://127.0.0.1:${actualPort}`, profile });
+        child.unref();
+        resolve(actualPort);
+      } else if (errorMatch) {
+        clearTimeout(timer);
+        reject(new Error(`Browser launch failed: ${errorMatch[1]}`));
+      }
+    });
+
+    child.on('error', err => {
+      clearTimeout(timer);
+      reject(err);
+    });
+
+    child.on('exit', (code) => {
+      if (code !== null && code !== 0) {
+        clearTimeout(timer);
+        reject(new Error(`Daemon exited with code ${code}`));
+      }
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 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');
+  }
+
+  // 1. Try to reuse playwright-cli's browser via its CDP port
+  const cliCdpPort = getPlaywrightCliCdpPort();
+  if (cliCdpPort) {
+    const alive = await probeCDP(cliCdpPort, 2000);
+    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();
+        return { browser, context, page, playwright };
+      } catch {
+        // fall through to own browser
+      }
+    }
+  }
+
+  // 2. Try our own CDP browser (state file)
+  let state = readState();
+  let cdpUrl;
+
+  if (state) {
+    const alive = await probeCDP(state.port, 2000);
+    if (alive) {
+      cdpUrl = state.cdpUrl;
+    } else {
+      clearState();
+      state = null;
+    }
+  }
+
+  if (!state) {
+    const port = await launchBrowser({ headless, profile, port: preferredPort });
+    cdpUrl = `http://127.0.0.1:${port}`;
+    await sleep(200);
+  }
+
+  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();
+
+  return { browser, context, page, playwright };
+}
+
+async function killBrowser() {
+  const state = readState();
+  if (!state) return false;
+
+  const alive = await probeCDP(state.port, 1000);
+  if (alive) {
+    try {
+      const playwright = require('playwright');
+      const browser = await playwright.chromium.connectOverCDP(state.cdpUrl);
+      await browser.close();
+    } catch { /* ignore */ }
+  }
+
+  clearState();
+  return true;
+}
+
+module.exports = { getConnection, killBrowser };

package/src/cli.js

@@ -0,0 +1,168 @@
+'use strict';
+
+const { getConnection, killBrowser } = require('./browser-manager');
+const { execCode, execScript } = require('./executor');
+const { readState } = require('./state');
+const { readStdin, die, probeCDP } = require('./utils');
+
+function parseArgs(argv) {
+  const global = { headless: false, profile: 'default', port: 9222 };
+  const rest = [];
+  let i = 0;
+
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === '--headless') {
+      global.headless = true;
+    } else if (arg === '--profile' && argv[i + 1]) {
+      global.profile = argv[++i];
+    } else if (arg === '--port' && argv[i + 1]) {
+      global.port = parseInt(argv[++i], 10);
+    } else {
+      rest.push(arg);
+    }
+    i++;
+  }
+
+  return { global, rest };
+}
+
+async function cmdRunCode(rest, opts) {
+  let code;
+
+  if (rest.length > 0) {
+    code = rest.join(' ');
+  } else if (!process.stdin.isTTY) {
+    code = await readStdin();
+  } else {
+    die('No code provided. Pass inline or pipe via stdin.\n\nExamples:\n  pw-cli run-code "await page.goto(\'https://example.com\')"\n  cat script.js | pw-cli run-code');
+  }
+
+  if (!code) die('Empty code provided.');
+
+  const conn = await getConnection(opts);
+  try {
+    const result = await execCode(code, conn);
+    if (result !== undefined) {
+      console.log(result);
+    }
+  } finally {
+    await conn.browser.close(); // disconnect only, browser keeps running
+  }
+}
+
+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...]');
+  }
+
+  const conn = await getConnection(opts);
+  try {
+    const result = await execScript(scriptPath, scriptArgs, conn);
+    if (result !== undefined) {
+      console.log(result);
+    }
+  } finally {
+    await conn.browser.close();
+  }
+}
+
+async function cmdKill() {
+  const killed = await killBrowser();
+  console.log(killed ? 'Browser stopped.' : 'No browser running.');
+}
+
+async function cmdStatus() {
+  const state = readState();
+  if (!state) {
+    console.log('Status: stopped');
+    return;
+  }
+  const alive = await probeCDP(state.port, 2000);
+  if (alive) {
+    console.log(`Status: running`);
+    console.log(`  CDP:     ${state.cdpUrl}`);
+    console.log(`  Profile: ${state.profile || 'default'}`);
+  } else {
+    console.log('Status: stopped (stale state file cleared)');
+    const { clearState } = require('./state');
+    clearState();
+  }
+}
+
+function printHelp() {
+  console.log(`
+pw-cli — Persistent Playwright browser CLI
+
+USAGE
+  pw-cli [--headless] [--profile <name>] [--port <number>] <command> [...]
+
+GLOBAL OPTIONS
+  --headless          Run browser headlessly (default: headed)
+  --profile <name>    Named profile to use (default: "default")
+  --port <number>     CDP port (default: 9222)
+
+COMMANDS
+  run-code [code]          Execute inline JS (reads stdin if omitted)
+  run-script <file> [...]  Execute a .js script with optional args
+  kill                     Stop the running browser
+  status                   Show browser status
+
+SCRIPT GLOBALS
+  page, context, browser, playwright, args, require, __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 --headless run-code "await page.goto('https://example.com')"
+  pw-cli --profile work status
+  pw-cli kill
+`.trim());
+}
+
+async function run(argv) {
+  const { global: opts, rest } = parseArgs(argv);
+  const [command, ...cmdArgs] = rest;
+
+  if (!command || command === '--help' || command === '-h' || command === 'help') {
+    printHelp();
+    return;
+  }
+
+  try {
+    switch (command) {
+      case 'run-code':
+        await cmdRunCode(cmdArgs, opts);
+        break;
+      case 'run-script':
+        await cmdRunScript(cmdArgs, opts);
+        break;
+      case 'kill':
+        await cmdKill();
+        break;
+      case 'status':
+        await cmdStatus();
+        break;
+      default:
+        die(`Unknown command: ${command}\nRun "pw-cli help" for usage.`);
+    }
+  } catch (err) {
+    if (err.code === 'ENOENT' && err.message.includes('Script not found')) {
+      process.exit(3);
+    }
+    if (err.message && (err.message.includes('Target closed') || err.message.includes('Connection closed') || err.message.includes('Protocol error'))) {
+      const { clearState } = require('./state');
+      clearState();
+      process.stderr.write(`pw-cli error: Browser disconnected unexpectedly. Run the command again to relaunch.\n\nDetails: ${err.message}\n`);
+      process.exit(2);
+    }
+    process.stderr.write(`pw-cli error: ${err.message || err}\n`);
+    process.exit(1);
+  }
+  // Force exit: playwright CDP connections keep the event loop alive
+  process.exit(0);
+}
+
+module.exports = { run };

package/src/executor.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function isFunctionExpression(code) {
+  const text = code.trim();
+  return /^(async\s+function\b|function\b|async\s*(\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>|\([^)]*\)\s*=>|[A-Za-z_$][\w$]*\s*=>)/.test(text);
+}
+
+async function runFunctionExpression(code, globals) {
+  const factory = new Function(...Object.keys(globals), `return (${code});`);
+  const maybeFn = factory(...Object.values(globals));
+
+  if (typeof maybeFn === 'function') {
+    return maybeFn(
+      globals.page,
+      globals.context,
+      globals.browser,
+      globals.playwright,
+      globals.args
+    );
+  }
+
+  return maybeFn;
+}
+
+// Use AsyncFunction constructor to execute in the same V8 context as playwright objects.
+// This avoids vm.runInNewContext's cross-context prototype issues.
+async function runCode(code, globals) {
+  if (isFunctionExpression(code)) {
+    return runFunctionExpression(code, globals);
+  }
+
+  const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
+  const fn = new AsyncFunction(...Object.keys(globals), code);
+  return fn.call(globals, ...Object.values(globals));
+}
+
+async function execCode(code, { browser, context, page, playwright }) {
+  const globals = {
+    browser,
+    context,
+    page,
+    playwright,
+    require,
+    console,
+    process,
+  };
+  return 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 globals = {
+    browser,
+    context,
+    page,
+    playwright,
+    args: scriptArgs,
+    require,
+    console,
+    process,
+    __filename: absPath,
+    __dirname: path.dirname(absPath),
+  };
+  return runCode(code, globals);
+}
+
+module.exports = { execCode, execScript };

package/src/launch-daemon.js

@@ -0,0 +1,65 @@
+'use strict';
+
+// This script is spawned as a detached child process.
+// It launches a persistent Chromium browser and holds it open.
+// It signals readiness by writing "READY:<port>\n" to stdout.
+// Args: --profile-dir <dir> --port <port> [--headless]
+
+const args = process.argv.slice(2);
+
+function getArg(name) {
+  const i = args.indexOf(name);
+  return i !== -1 ? args[i + 1] : undefined;
+}
+
+const profileDir = getArg('--profile-dir');
+const port = parseInt(getArg('--port') || '9222', 10);
+const headless = args.includes('--headless');
+
+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 context = await playwright.chromium.launchPersistentContext(profileDir, {
+      headless,
+      args: [`--remote-debugging-port=${port}`],
+      ignoreDefaultArgs: ['--enable-automation'],
+    });
+
+    // Wait briefly for CDP to be ready, then signal
+    const { probeCDP, sleep } = require('./utils');
+    let ready = false;
+    for (let i = 0; i < 20; i++) {
+      if (await probeCDP(port, 1000)) { ready = true; break; }
+      await sleep(300);
+    }
+
+    if (!ready) {
+      process.stdout.write(`ERROR:CDP not available on port ${port} after launch\n`);
+      await context.close();
+      process.exit(1);
+    }
+
+    process.stdout.write(`READY:${port}\n`);
+
+    // Keep process alive until browser closes
+    context.on('close', () => process.exit(0));
+
+    // Prevent premature exit
+    process.stdin.resume();
+  } catch (e) {
+    process.stdout.write(`ERROR:${e.message}\n`);
+    process.exit(1);
+  }
+})();

package/src/queue.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+const HOME_DIR = os.homedir();
+const PW_CLI_DIR = path.join(HOME_DIR, '.pw-cli');
+const QUEUE_FILE = path.join(PW_CLI_DIR, 'queue.json');
+
+function readQueue() {
+  try {
+    return JSON.parse(fs.readFileSync(QUEUE_FILE, 'utf8'));
+  } catch {
+    return [];
+  }
+}
+
+function saveQueue(items) {
+  fs.mkdirSync(PW_CLI_DIR, { recursive: true });
+  const tmp = QUEUE_FILE + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(items, null, 2), 'utf8');
+  fs.renameSync(tmp, QUEUE_FILE);
+}
+
+function addItem(command, args) {
+  const queue = readQueue();
+  const id = Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+  const item = { id, command, args, addedAt: new Date().toISOString() };
+  queue.push(item);
+  saveQueue(queue);
+  return item;
+}
+
+function removeItem(idPrefix) {
+  const queue = readQueue();
+  const idx = queue.findIndex(i => i.id === idPrefix || i.id.startsWith(idPrefix));
+  if (idx === -1) return null;
+  const [removed] = queue.splice(idx, 1);
+  saveQueue(queue);
+  return removed;
+}
+
+function clearQueue() {
+  saveQueue([]);
+}
+
+module.exports = { readQueue, saveQueue, addItem, removeItem, clearQueue, QUEUE_FILE };

package/src/state.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function getPwCliDir() {
+  return path.join(os.homedir(), '.pw-cli');
+}
+
+function getStateFile() {
+  return path.join(getPwCliDir(), 'browser.json');
+}
+
+function getProfileDir(profile = 'default') {
+  const dir = path.join(getPwCliDir(), 'profiles', profile);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function readState() {
+  try {
+    const raw = fs.readFileSync(getStateFile(), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function writeState(state) {
+  const dir = getPwCliDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const file = getStateFile();
+  const tmp = file + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+function clearState() {
+  try {
+    fs.unlinkSync(getStateFile());
+  } catch {
+    // already gone
+  }
+}
+
+module.exports = { getPwCliDir, getProfileDir, readState, writeState, clearState };

package/src/utils.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const http = require('http');
+const net = require('net');
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => { data += chunk; });
+    process.stdin.on('end', () => resolve(data.trim()));
+    process.stdin.on('error', reject);
+  });
+}
+
+function die(msg, code = 1) {
+  process.stderr.write(`pw-cli error: ${msg}\n`);
+  process.exit(code);
+}
+
+function probeCDP(port, timeout = 3000) {
+  return new Promise(resolve => {
+    const req = http.get(`http://127.0.0.1:${port}/json/version`, { timeout }, res => {
+      res.resume();
+      resolve(res.statusCode === 200);
+    });
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+  });
+}
+
+function findFreePort(preferred = 9222) {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.listen(preferred, '127.0.0.1', () => {
+      const { port } = server.address();
+      server.close(() => resolve(port));
+    });
+    server.on('error', () => {
+      // preferred port busy, get a random free one
+      const s2 = net.createServer();
+      s2.listen(0, '127.0.0.1', () => {
+        const { port } = s2.address();
+        s2.close(() => resolve(port));
+      });
+      s2.on('error', reject);
+    });
+  });
+}
+
+function sleep(ms) {
+  return new Promise(r => setTimeout(r, ms));
+}
+
+module.exports = { readStdin, die, probeCDP, findFreePort, sleep };