pw-repl 0.1.0

package/AGENTS.md

@@ -0,0 +1,24 @@
+# Agent Instructions — playwright-repl
+
+How to use the REPL is in `skill/SKILL.md` (the same text `pw-repl skill` prints). Read it first. In
+this clone, `pw-repl` there means `bin/pw-repl.js` (from the folder this file is in) when it is not
+installed globally.
+
+## Contributing
+
+If you hit a limitation or write a workaround, consider adding the capability to the REPL instead.
+
+- A command is a function in the `commands` object in `lib/commands.js`, plus an entry in `lib/help.js`
+  under one topic.
+- `bin/pw-repl.js` is the command line; `lib/start.js` connects and runs the prompt; `lib/runner.js`
+  runs commands one at a time; `lib/server.js` is the opt-in server; `lib/send.js` and `lib/client.js`
+  are `send` and `where`; `lib/output.js` routes all output so the server can return it.
+- Comment the *why* when it isn't obvious from the code.
+- `npm test` runs the suite (about 40s): a private headless Chromium, a local test site, and the real
+  REPL with its server. Nothing is mocked, and the shared browser is never touched. It finds Chromium
+  through `PW_TEST_CHROME` or Playwright's installed browsers, and skips the browser tests if there is
+  none. Add a test with each new command or behaviour.
+- For anything the tests can't reach, exercise the change in a running REPL. Use your own tmux session
+  and a new tab, not the user's.
+- `skill/SKILL.md` is how agents learn to use the REPL: keep it in step with a change to how it is
+  used, and leave its Custom rules section empty.

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arcanemachine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# playwright-repl
+
+A text REPL for driving an existing Chromium through Playwright over CDP. You and agents can share the same
+browser: people click in it, and the REPL inspects it, fakes responses, and records what happened.
+
+## Getting started
+
+### Prerequisites
+
+- Node.js 20 or newer (`npm test` needs 21 or newer).
+- A Chromium-based browser (Chrome, Chromium, ungoogled-chromium, ...).
+- Optional: tmux, to use `pw-repl send` without the command server.
+
+### 1. Start the browser with remote debugging
+
+```bash
+chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.config/chrome-debug"
+# or: chromium --remote-debugging-port=9222 --user-data-dir="$HOME/.config/chromium-debug"
+```
+
+Use a separate `--user-data-dir`: recent Chrome versions do not open the debugging port on the default
+profile. Check it is up with `curl http://localhost:9222/json/version`.
+
+### 2. Install and start the REPL
+
+```bash
+npm install -g pw-repl
+pw-repl run              # connects to localhost:9222; pw-repl on its own shows the usage
+```
+
+Without installing: `npx pw-repl` (subcommands work the same way).
+From a clone: `npm install`, then `bin/pw-repl.js run` (or `npm link` to get `pw-repl`).
+
+It lists the open tabs and shows a `pw>` prompt. To send it commands from scripts or agents later
+(`pw-repl send`), run it in a tmux session named `playwright-repl` (`tmux new -s playwright-repl`), or
+start it with `pw-repl serve` instead, which needs no tmux.
+
+### 3. Try it
+
+```text
+pw> help                          # common tasks and topics; help <topic>, help <command>, help --all
+pw> tab new https://example.com   # open your own tab to work in
+pw> snapshot                      # the page by role and name, with [ref=eN] labels
+pw> click aria-ref=e3             # click by label (or any Playwright selector)
+pw> requests                      # requests the tab made
+pw> tab close
+```
+
+Commands act on the selected tab (`tab` lists the tabs, with `*` on the selected one).
+
+## Common tasks
+
+| I want to…                           | Commands                                                        |
+| ------------------------------------ | --------------------------------------------------------------- |
+| see where I am                       | `tab`, `info`                                                   |
+| see what is on the page              | `snapshot`, `screenshot`                                        |
+| do something on it                   | `click`, `fill`, `press`                                        |
+| see what the page requested          | `requests`, then `body <#>` for what one got back               |
+| see console messages and errors      | `console`                                                       |
+| show an agent what I do              | `watch on`, click around in the browser, then `watch`           |
+| see each step as I click             | `watch on --live`                                               |
+| record requests and console together | `capture on`, then `capture off`                                |
+| break the backend on purpose         | `route <glob> <status> <json>` (fake a response), `network off` |
+| clean up                             | `modes off`                                                     |
+
+Everything else is in `help <topic>`; `help <command>` has usage and caveats.
+
+### Modes
+
+`watch`, `capture`, `route` and `network off` stay on until you turn them off: `watch on|off`,
+`capture on|off`, `route ...|route off`, `network off|on`. While any are on in the selected tab, the prompt
+shows them: `(watch network:off routes:2) pw>`. `modes` lists them for every tab, and `modes off` turns them
+all off.
+
+`tab`, `watch`, `capture`, `route`, `network` and `modes` on their own show their state and what you can
+run next.
+
+## Options
+
+```bash
+pw-repl run http://localhost:3000        # connect and navigate tab [0] to a URL
+pw-repl serve                            # also accept commands on /tmp/playwright-repl.sock (prompt: pw[serve]>)
+PW_CDP_URL=http://host:9222 pw-repl run  # a browser elsewhere
+```
+
+**Browser on the host, REPL in a container:** with host networking, `localhost:9222` reaches the host's
+browser directly. Otherwise set `PW_CDP_URL` to the host's address as seen from the container (for example
+the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
+
+## From scripts and agents
+
+```bash
+pw-repl send info
+pw-repl send help       # the REPL's commands; works without a running REPL
+pw-repl where           # which REPL send would reach
+```
+
+`pw-repl send` sends one command and prints its result, through the server when it is running and through the
+`playwright-repl` tmux session otherwise. The server speaks HTTP with JSON:
+
+```bash
+curl --unix-socket /tmp/playwright-repl.sock -H 'Content-Type: application/json' \
+  -d '{"command": "info"}' http://localhost/run
+```
+
+It returns `{"status": "ok" | "error", "output": "..."}`, plus `"unconfirmed": true` when the command may or
+may not have done what it was sent to do (it timed out, or the REPL quit while it ran and it was not
+read-only). It is off unless started with `pw-repl serve`.
+`pw-repl serve <port>` serves TCP on 127.0.0.1 instead; other addresses are refused.
+
+### A skill for agents
+
+`pw-repl skill` prints an agent skill (`SKILL.md`) that teaches an agent to use the REPL: how to start
+it, send commands, and share the browser with a person. Save it as `pw-repl/SKILL.md` in the folder
+your agent reads skills from:
+
+```bash
+mkdir -p <skills folder>/pw-repl
+pw-repl skill > <skills folder>/pw-repl/SKILL.md
+```
+
+The same text is in `skill/SKILL.md`. Working on the REPL itself: see `AGENTS.md`.
+
+## Tests
+
+```bash
+npm test
+```
+
+Runs against a private headless Chromium it starts itself (via `PW_TEST_CHROME`, or Playwright's installed
+browsers: `npx playwright-core install chromium`) and a local test site; the browser tests are skipped when no
+Chromium is found.

package/bin/pw-repl.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// The one command: pw-repl run | serve | send | where | help | skill.
+
+const { looksLikeEndpoint } = require('../lib/client');
+
+const USAGE = `Usage:
+  pw-repl run [start-url]
+      connect to the browser and open the prompt
+
+  pw-repl serve [endpoint] [start-url]
+      the same, plus a command server (socket, port, or 127.0.0.1:port; default /tmp/playwright-repl.sock)
+
+  pw-repl send [-e endpoint | -s session] [-t seconds] <command...>
+      run one command in a running REPL and print its output
+
+  pw-repl where [-e endpoint | -s session]
+      say which REPL send would reach
+
+  pw-repl help [topic | command | --all]
+      this usage; with a topic or command, the REPL's help for it
+
+  pw-repl skill
+      print an agent skill (SKILL.md) that teaches an agent to use the REPL
+
+send uses the server when -e, $PW_ENDPOINT, or the socket ($PW_SOCKET, default /tmp/playwright-repl.sock)
+is there, and the tmux session (-s, $PW_TMUX_SESSION, default playwright-repl) otherwise. If the socket
+exists but nothing answers, send fails rather than fall back.
+
+send exit status: 0 ok, 1 command error, 2 completion not confirmed, 64 usage or unreachable.
+
+The browser must be running with --remote-debugging-port (default http://localhost:9222; set $PW_CDP_URL).`;
+
+const REPL_HELP = `The REPL's own commands: help at the pw> prompt, or pw-repl send help here (no REPL needed).
+
+pw-repl help <topic | command | --all> shows one part of it.`;
+
+function usage() {
+  console.error(USAGE);
+  process.exit(64);
+}
+
+// -e, -s and -t, then the command words (unquoted words are one command).
+function parseSendArgs(args, allowCommand) {
+  const options = { endpoint: null, session: null, timeout: 20, command: '' };
+  let i = 0;
+  for (; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '-e' || arg === '-s' || arg === '-t') {
+      const value = args[++i];
+      if (value === undefined) usage();
+      if (arg === '-e') options.endpoint = value;
+      if (arg === '-s') options.session = value;
+      if (arg === '-t') {
+        if (!/^\d+$/.test(value) || Number(value) < 1) usage();
+        options.timeout = Number(value);
+      }
+    } else if (arg === '--') { i++; break; } else break;
+  }
+  const words = args.slice(i);
+  if (!allowCommand && words.length) usage();
+  options.command = words.join(' ').trim();
+  return options;
+}
+
+function startOptions(args, serve) {
+  const options = { serve, endpoint: null, startUrl: null };
+  const rest = [...args];
+  if (serve && rest[0] && looksLikeEndpoint(rest[0])) options.endpoint = rest.shift();
+  if (rest.length > 1 || (rest[0] && rest[0].startsWith('-'))) usage();
+  options.startUrl = rest[0] || null;
+  return options;
+}
+
+function help(topic) {
+  const helpText = require('../lib/help');
+  const text = helpText.render(topic);
+  if (text === null) {
+    console.log(`Error: No help for ${topic}. Topics: ${Object.keys(helpText.TOPICS).join(', ')}`);
+    process.exit(1);
+  }
+  console.log(text);
+}
+
+// Printed as is, to be saved as a skill; the hint goes to the terminal only.
+function skill() {
+  process.stdout.write(require('fs').readFileSync(require('path').join(__dirname, '..', 'skill', 'SKILL.md'), 'utf8'));
+  if (process.stdout.isTTY) console.error('\nSave it as pw-repl/SKILL.md in the folder your agent reads skills from:\npw-repl skill > <skills folder>/pw-repl/SKILL.md');
+}
+
+async function main() {
+  let [subcommand, ...args] = process.argv.slice(2);
+  // Bare pw-repl explains itself rather than connect to someone's browser.
+  if (subcommand === undefined) return console.log(`${USAGE}\n\n${REPL_HELP}`);
+  switch (subcommand) {
+    case 'run':
+    case 'serve':
+      return require('../lib/start').start(startOptions(args, subcommand === 'serve'));
+    case 'send': {
+      const options = parseSendArgs(args, true);
+      // help is fixed text, so it needs no browser: answer it here.
+      const asksHelp = /^help(?:\s+(.*))?$/.exec(options.command);
+      if (asksHelp) return help((asksHelp[1] || '').trim());
+      process.exit(await require('../lib/send').send(options));
+    }
+    // falls through never: process.exit above
+    case 'where':
+      process.exit(await require('../lib/send').where(parseSendArgs(args, false)));
+    // falls through never
+    case 'help': {
+      const topic = args.join(' ').trim();
+      if (topic && topic !== '-h' && topic !== '--help') return help(topic);
+      return console.log(`${USAGE}\n\n${REPL_HELP}`);
+    }
+    case 'skill':
+      if (args.length) usage();
+      return skill();
+    case '-v':
+    case '--version':
+      return console.log(require('../package.json').version);
+    case '-h':
+    case '--help':
+      return console.log(`${USAGE}\n\n${REPL_HELP}`);
+    default:
+      return usage();
+  }
+}
+
+main();

package/lib/client.js

@@ -0,0 +1,78 @@
+// How to reach a REPL's command server, and one request to it.
+const http = require('http');
+const path = require('path');
+
+const DEFAULT_SOCKET = '/tmp/playwright-repl.sock';
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1']);
+
+// A port or loopback host:port is TCP; anything else is a unix socket path.
+function parseEndpoint(value) {
+  if (!value) return { socket: DEFAULT_SOCKET };
+  if (/^\d+$/.test(value)) return { host: '127.0.0.1', port: Number(value) };
+  const tcp = /^\[?([^\]/]+?)\]?:(\d+)$/.exec(value);
+  if (tcp) {
+    if (!LOOPBACK.has(tcp[1])) throw new Error(`Refusing non-loopback address ${tcp[1]}; use 127.0.0.1, localhost, or ::1`);
+    return { host: tcp[1], port: Number(tcp[2]) };
+  }
+  return { socket: path.resolve(value) };
+}
+
+// Tells an endpoint argument apart from a start URL on the command line.
+function looksLikeEndpoint(value) {
+  if (value.includes('://')) return false;
+  return /^\d+$/.test(value) || /:\d+$/.test(value) || value.endsWith('.sock') || value.startsWith('/') || value.startsWith('.');
+}
+
+function describe(endpoint) {
+  return endpoint.socket || `${endpoint.host}:${endpoint.port}`;
+}
+
+function target(endpoint) {
+  return endpoint.socket ? { socketPath: endpoint.socket } : { host: endpoint.host, port: endpoint.port };
+}
+
+// GET /health: does not go through the command queue or show in the pane.
+function health(endpoint, timeoutMs) {
+  return new Promise(resolve => {
+    const req = http.get({ ...target(endpoint), path: '/health', timeout: timeoutMs }, res => {
+      res.resume();
+      resolve(res.statusCode === 200);
+    });
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.on('error', () => resolve(false));
+  });
+}
+
+// One command. Resolves to { result }, { timeout: true }, { dropped: reason }
+// (the connection closed after the command was sent, so it may have run) or
+// { unreachable: reason } (it was never sent).
+function request(endpoint, command, timeoutMs) {
+  return new Promise(resolve => {
+    const body = JSON.stringify({ command });
+    let connected = false;
+    const req = http.request({
+      ...target(endpoint),
+      path: '/run',
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+    }, res => {
+      let text = '';
+      res.setEncoding('utf8');
+      res.on('close', () => { if (!res.complete) resolve({ dropped: 'the answer was cut off' }); });
+      res.on('data', chunk => { text += chunk; });
+      res.on('end', () => {
+        try { resolve({ result: JSON.parse(text) }); }
+        catch { resolve({ timeout: true }); }
+      });
+    });
+    req.setTimeout(timeoutMs, () => { req.destroy(); resolve({ timeout: true }); });
+    req.on('socket', socket => socket.once('connect', () => { connected = true; }));
+    req.on('error', error => {
+      const reason = error.code || error.message;
+      resolve(connected ? { dropped: reason } : { unreachable: reason });
+    });
+    req.end(body);
+  });
+}
+
+module.exports = { DEFAULT_SOCKET, parseEndpoint, looksLikeEndpoint, describe, health, request };