pw-repl 0.1.0

package/lib/server.js

@@ -0,0 +1,91 @@
+// Opt-in command server (pw-repl serve): POST /run {"command": "..."} runs one
+// command through the same queue as the prompt and returns its output.
+const http = require('http');
+const net = require('net');
+const fs = require('fs');
+const out = require('./output');
+const runner = require('./runner');
+const { onShutdown, onBeforeExit } = require('./state');
+const { parseEndpoint, describe } = require('./client');
+
+const MAX_BODY = 1024 * 1024;
+const FLUSH_TIMEOUT = 1000;
+
+// Answers being written, so the REPL can let them reach their senders before it exits.
+const sending = new Set();
+
+function send(res, code, result) {
+  res.writeHead(code, { 'Content-Type': 'application/json' });
+  const done = new Promise(resolve => { res.once('finish', resolve); res.once('close', resolve); });
+  sending.add(done);
+  done.then(() => sending.delete(done));
+  res.end(`${JSON.stringify(result)}\n`);
+}
+
+onBeforeExit(() => Promise.race([Promise.all(sending), new Promise(resolve => setTimeout(resolve, FLUSH_TIMEOUT))]));
+
+function handle(req, res) {
+  // A web page can reach a loopback port; it always sends Origin on a
+  // cross-origin POST, and cannot send a JSON content type without a
+  // preflight this server never answers.
+  if (req.headers.origin) return send(res, 403, { status: 'error', output: 'Requests from web pages are refused' });
+  if (req.method === 'GET' && req.url === '/health') return send(res, 200, { status: 'ok' });
+  if (req.method !== 'POST' || req.url !== '/run') return send(res, 404, { status: 'error', output: 'Use POST /run or GET /health' });
+  if (!/^application\/json\b/.test(req.headers['content-type'] || '')) return send(res, 415, { status: 'error', output: 'Content-Type must be application/json' });
+  let body = '';
+  req.setEncoding('utf8');
+  req.on('data', chunk => {
+    body += chunk;
+    if (body.length > MAX_BODY) { send(res, 413, { status: 'error', output: 'Request too large' }); req.destroy(); }
+  });
+  req.on('end', async () => {
+    let command;
+    try { ({ command } = JSON.parse(body)); } catch {}
+    if (typeof command !== 'string' || !command.trim() || /[\r\n]/.test(command)) {
+      return send(res, 400, { status: 'error', output: 'Body must be {"command": "<one line>"}' });
+    }
+    const result = await runner.submit(command.trim());
+    if (!result.uncertain) return send(res, 200, { status: result.status, output: result.output });
+    // unconfirmed: the command may or may not have done what it was sent to do.
+    if (result.interrupted) return send(res, 200, { status: result.status, output: result.output, unconfirmed: true });
+    send(res, 200, { status: result.status, output: `${result.output}\nBrowser command outcome is unknown; the REPL is disconnecting.`, unconfirmed: true });
+    runner.giveUp();
+  });
+}
+
+// A socket file left by a REPL that died is removed; one still answering is not.
+async function clearStaleSocket(socketPath) {
+  let stat;
+  try { stat = fs.statSync(socketPath); } catch { return; }
+  if (!stat.isSocket()) throw new Error(`${socketPath} exists and is not a socket`);
+  const live = await new Promise(resolve => {
+    const probe = net.connect(socketPath);
+    probe.on('connect', () => { probe.destroy(); resolve(true); });
+    probe.on('error', () => resolve(false));
+  });
+  if (live) throw new Error(`Another REPL is already serving on ${socketPath}`);
+  fs.unlinkSync(socketPath);
+}
+
+async function serve(endpointArg) {
+  const endpoint = parseEndpoint(endpointArg);
+  if (endpoint.socket) await clearStaleSocket(endpoint.socket);
+  const server = http.createServer(handle);
+  // Owner-only from the moment the socket file exists.
+  const previousUmask = endpoint.socket ? process.umask(0o177) : null;
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      if (endpoint.socket) server.listen(endpoint.socket, resolve);
+      else server.listen(endpoint.port, endpoint.host, resolve);
+    });
+  } finally {
+    if (previousUmask !== null) process.umask(previousUmask);
+  }
+  const removeSocket = () => { if (endpoint.socket) try { fs.unlinkSync(endpoint.socket); } catch {} };
+  onShutdown(() => { server.close(); removeSocket(); });
+  process.on('exit', removeSocket);
+  out.log(`Serving commands on ${describe(endpoint)}`);
+}
+
+module.exports = { serve };

package/lib/start.js

@@ -0,0 +1,117 @@
+// Connects to the browser and runs the prompt (and the server with serve).
+const { chromium } = require('playwright-core');
+const readline = require('readline');
+const { state, withTimeout, shutdown, beforeExit } = require('./state');
+const out = require('./output');
+const { listTabs, watchPage, complete } = require('./commands');
+const runner = require('./runner');
+
+const CDP_URL = process.env.PW_CDP_URL || 'http://localhost:9222';
+
+async function start(options) {
+  const START_URL = options.startUrl || process.env.PW_START_URL || null;
+  out.log(`Connecting to ${CDP_URL}...`);
+  state.browser = await chromium.connectOverCDP(CDP_URL);
+  if (state.stopping) {
+    try { await withTimeout(state.browser.close(), 'Chromium shutdown'); }
+    catch (error) { process.exitCode = 1; out.error(`Could not confirm Chromium shutdown: ${error.message}`); }
+    return;
+  }
+  state.browser.on('disconnected', () => {
+    if (state.stopping) return;
+    state.connectionLost = true;
+    state.stopping = true;
+    process.exitCode = 1;
+    out.error('Chromium connection lost; queued commands will not run.');
+    void shutdown().then(() => process.exit(1));
+  });
+  out.log('Connected to Chromium via CDP');
+
+  const contexts = state.browser.contexts();
+  const pages = contexts.flatMap(c => c.pages());
+
+  state.page = pages[0];
+  state.tabListing = pages.slice();
+
+  // Hooks first, so the start URL's own requests, logs and dialogs are recorded.
+  for (const ctx of contexts) {
+    ctx.on('page', watchPage);
+    ctx.pages().forEach(watchPage);
+  }
+
+  if (START_URL) {
+    if (!state.page) {
+      state.page = await contexts[0].newPage();
+    }
+    await state.page.goto(START_URL, { waitUntil: 'networkidle', timeout: 15000 });
+    out.log(`Navigated to: ${state.page.url()}`);
+  }
+
+  if (!state.page) {
+    state.page = await (contexts[0] || await state.browser.newContext()).newPage();
+    out.log('Created new page');
+  }
+
+  out.log('');
+  await listTabs();
+  out.log('');
+  if (options.serve) await require('./server').serve(options.endpoint);
+  out.log("Run 'help' to see the commands. They act on the selected tab (*).");
+  out.log('');
+
+  // The prompt shows whether the command server is on.
+  state.promptBase = options.serve ? 'pw[serve]> ' : 'pw> ';
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: state.promptBase,
+    completer: complete,
+    historySize: 1000,
+    removeHistoryDuplicates: true,
+  });
+  state.rl = rl;
+  out.onIdlePrint({
+    idle: () => !runner.busy() && !state.stopping,
+    print: text => {
+      if (process.stdout.isTTY) { readline.clearLine(process.stdout, 0); readline.cursorTo(process.stdout, 0); }
+      console.log(text);
+      rl.prompt(true);
+    },
+  });
+
+  rl.prompt();
+  rl.on('line', line => {
+    // Up-arrow should bring back the command, not the caller's completion id.
+    const bare = line.trim().replace(/^@[A-Za-z0-9][A-Za-z0-9._-]*\s+/, '');
+    if (bare !== line.trim() && rl.history[0] === line.trim()) {
+      rl.history.shift();
+      if (bare && rl.history[0] !== bare) rl.history.unshift(bare);
+    }
+    runner.enqueue(line);
+  });
+  rl.on('close', () => {
+    if (state.stopping) return;
+    endPromptLine();
+    runner.drained().then(() => shutdown(), () => shutdown())
+      .then(() => process.exit(process.exitCode || 0));
+  });
+  rl.on('SIGINT', stop);
+}
+
+// Ctrl-C and Ctrl-D leave the cursor after the prompt; the shell's prompt
+// belongs on a line of its own.
+function endPromptLine() {
+  if (process.stdout.isTTY) process.stdout.write('\n');
+}
+
+// Like quit: a server command still running is answered before the REPL exits.
+function stop() {
+  endPromptLine();
+  runner.answerInterrupted();
+  shutdown().then(beforeExit).then(() => process.exit(process.exitCode || 0));
+}
+
+// SIGHUP too: closing the terminal must still remove the server's socket.
+for (const signal of ['SIGTERM', 'SIGHUP']) process.on(signal, stop);
+
+module.exports = { start: options => start(options).catch(e => { out.error(e.message); shutdown().finally(() => process.exit(1)); }) };

package/lib/state.js

@@ -0,0 +1,61 @@
+// Session state shared by the entry point, the runner, and the commands, plus
+// the shutdown that ends the session.
+const out = require('./output');
+
+const SHUTDOWN_TIMEOUT = 5000;
+
+const state = {
+  browser: null,
+  page: null,
+  previousPage: null,
+  tabListing: [],
+  rl: null,
+  promptBase: 'pw> ',
+  stopping: false,
+  connectionLost: false,
+  shutdownFailed: false,
+  previousCommandAt: 0,
+  currentCommandAt: 0,
+};
+
+const cleanups = [];
+const exitWaits = [];
+let shutdownPromise = null;
+
+function withTimeout(promise, label, duration = SHUTDOWN_TIMEOUT) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`${label} timed out`)), duration);
+    promise.then(
+      value => { clearTimeout(timer); resolve(value); },
+      error => { clearTimeout(timer); reject(error); },
+    );
+  });
+}
+
+function onShutdown(fn) {
+  cleanups.push(fn);
+}
+
+// Things to finish before the process exits, e.g. answers still being sent.
+function onBeforeExit(fn) {
+  exitWaits.push(fn);
+}
+
+async function beforeExit() {
+  await Promise.all(exitWaits.map(fn => fn()));
+}
+
+async function shutdown() {
+  if (shutdownPromise) return shutdownPromise;
+  state.stopping = true;
+  shutdownPromise = (async () => {
+    cleanups.forEach(fn => fn());
+    if (state.browser) {
+      try { await withTimeout(state.browser.close(), 'Chromium shutdown'); }
+      catch (error) { state.shutdownFailed = true; process.exitCode = 1; out.error(`Could not confirm Chromium shutdown: ${error.message}`); }
+    }
+  })();
+  return shutdownPromise;
+}
+
+module.exports = { state, withTimeout, onShutdown, onBeforeExit, beforeExit, shutdown };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "pw-repl",
+  "version": "0.1.0",
+  "description": "Text REPL for driving an existing Chromium through Playwright over CDP",
+  "keywords": [
+    "playwright",
+    "repl",
+    "cdp",
+    "chromium",
+    "browser",
+    "devtools",
+    "agents"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arcanemachine/playwright-repl.git"
+  },
+  "bin": {
+    "pw-repl": "bin/pw-repl.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "AGENTS.md",
+    "skill/",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "start": "node bin/pw-repl.js run",
+    "test": "node --test 'test/*.test.js'",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "playwright-core": "^1.63.0"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: pw-repl
+description: Inspect and drive a Chromium browser, possibly one a person is using, through the pw-repl (playwright-repl) REPL - tabs, page snapshots, clicks and typing, requests and their bodies, console messages, fake responses, cutting the network, and recording what the person does. Use when asked to look at, debug or test something in a browser that runs with remote debugging.
+---
+
+# pw-repl
+
+pw-repl (playwright-repl) is a REPL that drives a running Chromium over CDP. The browser may be a
+shared session: a person can have their own tabs open in it and be using it while you work.
+
+`pw-repl` below is the command the `pw-repl` npm package installs. Without a global install,
+`npx pw-repl` works the same; from a clone, `<clone>/bin/pw-repl.js`.
+
+## Start it
+
+The REPL runs in the tmux session `playwright-repl`. Check it first:
+
+```bash
+tmux capture-pane -t playwright-repl -p -S -5
+```
+
+If the pane is at a shell prompt, start the REPL there. If there is no session, ask the user before
+creating one.
+
+```bash
+tmux send-keys -t playwright-repl -l 'pw-repl run'
+tmux send-keys -t playwright-repl Enter
+```
+
+`pw-repl serve` is the same plus a command server on `/tmp/playwright-repl.sock` (owner-only); its
+prompt is `pw[serve]>` instead of `pw>`. It is opt-in: use it when the user asks for it or agrees.
+Prefer the socket: `pw-repl serve <port>` (TCP on 127.0.0.1) has no authentication, so any local
+process could drive the browser; use it only for a client that cannot reach the socket. Both take an
+optional start URL, which navigates tab [0]. Stop either at the pane (`quit`, or Ctrl-C); `send quit` is
+refused so an agent cannot close a REPL the user is using.
+
+## Send commands
+
+```bash
+pw-repl send tab
+pw-repl send -t 90 'screenshot -d 60'   # wait longer than the 20s default
+```
+
+Always send commands with `pw-repl send`; don't type into the pane yourself. Unquoted words are one
+command. It works however the REPL was started:
+
+- `run`: `send` types the command into the tmux pane and reads the result back off the screen. It
+  types only when the pane's last line is a bare prompt, so nothing lands in a shell or in the middle
+  of what the user is typing; while a command is running, the user is typing, or the REPL is exiting,
+  it refuses (exit 64). Wait and retry.
+- `serve`: `send` sends it over the socket and gets the output back as JSON. Same commands, more
+  reliable results: nothing is scraped, long output isn't cut off by scrollback, and a command can
+  never land in a shell. If you'll send many commands or read long output, ask the user whether to
+  restart the REPL with `pw-repl serve`.
+
+`pw-repl where` says which one a command would reach (the server, or the tmux pane running the
+REPL), or why neither is reachable, without running anything.
+
+Either way, every command you run and its output show in the pane (server commands as `[server]` lines),
+so the user sees what you do. The pane shows REPL commands only, not what the user clicked in the
+browser (unless `watch on --live` is on); for that, look at the browser itself: `tab` and `info` for
+where they are, `requests` for the requests their clicks made (`body <#>` for what one returned),
+`console` for console messages and page errors. When the user wants to show you what they do, `watch on`
+on their tab records each step with the requests it caused (`watch on --changes` adds what each step
+changed on the page); `watch` reads it back, and `watch new` only what it has not shown yet. Watching
+and reading are fine on the user's tabs; the rule below is about acting on them.
+
+Exit status: `0` ok, `1` the command failed, `2` completion not confirmed (outcome unknown: do not
+blindly retry a change), `64` usage or the REPL is not reachable. `pw-repl --help` has the options.
+
+## Learn the commands
+
+Run `pw-repl send help`. It lists six topics; `help <topic>` lists their commands, `help <command>`
+gives usage and caveats, and `help --all` prints everything at once. It needs no running REPL. The help is
+the command reference; this file does not repeat it.
+
+## Shared-browser rules
+
+- Act only on tabs you opened (`tab new`), unless the user asks you to act on theirs (e.g. a `route` in
+  their tab while they test); then say what you are doing and undo it the moment you are done. The REPL
+  selects tab [0] at startup, and that tab may be the user's: run `tab` before acting. Closing your
+  tab goes back only to a tab you opened; otherwise no tab is selected. Tab numbers change when tabs
+  open or close; `tab <url-part>` and `tab close <url-part>` pick a tab by its URL and refuse if it is
+  ambiguous.
+- Dialogs are never answered automatically. The person at the browser handles them.
+- Before leaving: turn off the modes you turned on (`modes` lists what is on in every tab; the prompt
+  shows the selected tab's, e.g. `(watch routes:1) pw>`), and close the tabs you opened. `modes off`
+  turns off everything, including modes the user turned on, so use it only when they are all yours.
+- The tmux session may be attached by the user. Never kill it.
+
+## Environment
+
+- Chromium must be running with `--remote-debugging-port=9222`.
+- `PW_CDP_URL` — CDP endpoint (default `http://localhost:9222`).
+- `PW_SCREENSHOT_DIR` — where screenshots go (default `/tmp`). They are all named `screenshot-*.png`,
+  so `rm /tmp/screenshot-*.png` cleans up.
+- `PW_ENDPOINT` / `PW_TMUX_SESSION` — defaults for `send -e` / `-s`. `PW_SOCKET` — the socket `send`
+  looks for when neither is given (default `/tmp/playwright-repl.sock`).
+
+## Custom rules
+
+No custom rules have been added yet.