pw-repl 0.2.2 → 0.3.1

package/AGENTS.md

@@ -11,13 +11,17 @@ If you hit a limitation or write a workaround, consider adding the capability to
 - 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.
+  runs commands one at a time (`quit` and `dialog` skip its queue); `lib/server.js` is the command
+  server; `lib/send.js` and `lib/client.js` are `send` and `where`; `lib/background.js` is
+  `serve --background`, `attach` and `stop`; `lib/launch.js` is `--launch`; `lib/syntax.js` is how a
+  command line's words are read, shared with `send`; `lib/state.js` holds the session state;
+  `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.
+- `npm test` runs the suite (about a minute): a private headless Chromium, a local test site
+  (`test/harness.js`), 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 where `--launch` looks (Playwright's
+  browsers, then the `PATH`), 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

package/README.md

@@ -21,6 +21,11 @@ chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.config/chrome-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`.
 
+**No browser to hand, or one you would rather not share?** Skip this step: `pw-repl run --launch` (or
+`serve --launch`) starts a private headless Chromium for the REPL and stops it with the REPL. It prints the
+command it ran, so you can start one your own way instead. If there is no Chromium at all,
+`npx playwright-core install chromium` downloads Playwright's.
+
 **Headless** works the same way:
 
 ```bash
@@ -61,30 +66,35 @@ Commands act on the selected tab (`tab` lists the tabs, with `*` on the selected
 
 ## 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`                                                     |
+| 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`                                                              |
+| wait for a page or element           | `wait load`, `wait <selector>`, `wait <selector> --gone`                              |
+| choose a file in a file input        | `upload <selector> <file>`                                                            |
+| see it as a phone, or in dark mode   | `emulate mobile`, `emulate dark` (also `emulate locale`, `emulate timezone`)          |
+| 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), `route <glob> abort`, `network off` |
+| change or slow an API response       | `route <glob> patch <json>`, `route <glob> delay <secs>`                              |
+| slow the whole network               | `network slow`                                                                        |
+| 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.
+`watch`, `capture`, `route`, `network off` or `slow`, and `emulate` stay on until you turn them off:
+`watch on|off`, `capture on|off`, `route ...|route off`, `network off|slow|on`, `emulate ...|emulate off`.
+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.
+`tab`, `watch`, `capture`, `route`, `network`, `emulate` and `modes` on their own show their state and what
+you can run next.
 
 ## Options
 
@@ -150,6 +160,6 @@ The same text is in `skill/SKILL.md`. Working on the REPL itself: see `AGENTS.md
 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.
+Runs against a private headless Chromium it starts itself (`PW_TEST_CHROME`, or the one `--launch` would
+use: Playwright's, e.g. from `npx playwright-core install chromium`, then one on the `PATH`) and a local
+test site; the browser tests are skipped when no Chromium is found.

package/bin/pw-repl.js

@@ -4,10 +4,10 @@
 const { looksLikeEndpoint } = require('../lib/client');
 
 const USAGE = `Usage:
-  pw-repl run [start-url]
+  pw-repl run [--launch [--headed]] [start-url] [-- <chromium flags>]
       connect to the browser and open the prompt
 
-  pw-repl serve [--background] [endpoint] [start-url]
+  pw-repl serve [--background] [--launch [--headed]] [endpoint] [start-url] [-- <chromium flags>]
       the same, plus a command server (socket, port, or 127.0.0.1:port; default /tmp/playwright-repl.sock);
       --background runs it detached, with its output in a log next to the socket
 
@@ -37,6 +37,11 @@ send exit status: 0 ok, 1 command error, 2 completion not confirmed, 64 usage or
 
 The browser must be running with --remote-debugging-port (default http://localhost:9222; set $PW_CDP_URL).
 
+--launch is the quick start instead: it starts a Chromium of the REPL's own (headless unless --headed, in
+a temporary profile), prints the command it ran, and stops it with the REPL. Flags after -- go to that
+Chromium; PW_CHROME picks which one. To set a browser up your own way, start it yourself and use
+PW_CDP_URL.
+
 In a tmux session named playwright-repl, pw-repl send reaches pw-repl run without the server.`;
 
 const REPL_HELP = `The REPL's own commands: help at the pw> prompt, or pw-repl send help here (no REPL needed).
@@ -74,15 +79,24 @@ function parseSendArgs(args, allowCommand) {
   const { SELECTOR_FIRST } = require('../lib/syntax');
   const requote = words.length > 1 && SELECTOR_FIRST.has(words[0]);
   // An empty word (fill #name "") is the empty value.
-  const quoted = requote ? words.map(w => (w === '' || /[\s"']/.test(w) ? JSON.stringify(w) : w)) : words;
+  // upload's files are read by the REPL, whose folder may not be this one.
+  const resolved = words[0] === 'upload' ? words.map((w, n) => (n > 1 ? require('path').resolve(w) : w)) : words;
+  const quoted = requote ? resolved.map(w => (w === '' || /[\s"']/.test(w) ? JSON.stringify(w) : w)) : resolved;
   options.command = quoted.join(' ').trim();
   return options;
 }
 
 function startOptions(args, serve) {
-  const options = { serve, endpoint: null, startUrl: null, background: false, pidFile: process.env.PW_REPL_PID_FILE || null };
-  const rest = [...args];
-  if (serve && rest.includes('--background')) { options.background = true; rest.splice(rest.indexOf('--background'), 1); }
+  const options = { serve, endpoint: null, startUrl: null, background: false, launch: false, headed: false, chromeArgs: [], pidFile: process.env.PW_REPL_PID_FILE || null };
+  // Whatever follows -- is for the Chromium that --launch starts.
+  const split = args.indexOf('--');
+  const rest = split === -1 ? [...args] : args.slice(0, split);
+  if (split !== -1) options.chromeArgs = args.slice(split + 1);
+  const flag = name => { const i = rest.indexOf(name); if (i === -1) return false; rest.splice(i, 1); return true; };
+  if (serve) options.background = flag('--background');
+  options.launch = flag('--launch');
+  options.headed = flag('--headed');
+  if ((options.headed || options.chromeArgs.length) && !options.launch) usage();
   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;

package/lib/background.js

@@ -64,7 +64,9 @@ async function start(options) {
   if (await client.health(endpoint, 2000)) return fail(`a REPL is already serving on ${name}, in a terminal; pw-repl where says more`);
   const log = fs.openSync(logFile, 'w', 0o600);
   fs.fchmodSync(log, 0o600);
-  const args = [BIN, 'serve', ...(options.endpoint ? [options.endpoint] : []), ...(options.startUrl ? [options.startUrl] : [])];
+  const args = [BIN, 'serve', ...(options.launch ? ['--launch'] : []), ...(options.headed ? ['--headed'] : []),
+    ...(options.endpoint ? [options.endpoint] : []), ...(options.startUrl ? [options.startUrl] : []),
+    ...(options.chromeArgs.length ? ['--', ...options.chromeArgs] : [])];
   const child = spawn(process.execPath, args, {
     detached: true,
     stdio: ['ignore', log, log],

package/lib/client.js

@@ -32,17 +32,27 @@ function target(endpoint) {
 }
 
 // GET /health: does not go through the command queue or show in the pane.
-function health(endpoint, timeoutMs) {
+// Resolves to what the REPL says about itself (e.g. its browser), or null.
+function healthInfo(endpoint, timeoutMs) {
   return new Promise(resolve => {
     const req = http.get({ ...target(endpoint), path: '/health', timeout: timeoutMs }, res => {
-      res.resume();
-      resolve(res.statusCode === 200);
+      let text = '';
+      res.setEncoding('utf8');
+      res.on('data', chunk => { text += chunk; });
+      res.on('end', () => {
+        if (res.statusCode !== 200) return resolve(null);
+        try { resolve(JSON.parse(text)); } catch { resolve({}); }
+      });
     });
-    req.on('timeout', () => { req.destroy(); resolve(false); });
-    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+    req.on('error', () => resolve(null));
   });
 }
 
+async function health(endpoint, timeoutMs) {
+  return (await healthInfo(endpoint, timeoutMs)) !== null;
+}
+
 // 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).
@@ -75,4 +85,4 @@ function request(endpoint, command, timeoutMs) {
   });
 }
 
-module.exports = { DEFAULT_SOCKET, parseEndpoint, looksLikeEndpoint, describe, health, request };
+module.exports = { DEFAULT_SOCKET, parseEndpoint, looksLikeEndpoint, describe, health, healthInfo, request };