pw-repl 0.12.6 → 0.12.7

package/AGENTS.md

@@ -104,7 +104,7 @@ Commits follow [Conventional Commits](https://www.conventionalcommits.org/): `fe
 
 1. `npm test` passes and the working tree is clean.
 2. `npm outdated` and `npm audit` show nothing that needs doing first. The lockfile holds playwright-core
-   at 1.63: on 1.64, a click on a link to a 204 waits out its timeout instead of returning (the test
+   at 1.63: on 1.64 (and 1.64.1), a click on a link to a 204 waits out its timeout instead of returning (the test
    "waits for the page to load, counting a navigation that just began" fails). Update it once a version
    passes `npm test`.
 3. `npm version <patch|minor|major> -m "chore: release %s"` sets the version in `package.json` and

package/README.md

@@ -126,7 +126,7 @@ example the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
   it. `pw-repl where` says what is running and how `send` will reach it.
 - For `send` to reach `run`, start it in tmux: `tmux new -s pw-repl`, then `pw-repl run` there.
 - A URL after the command opens in a new tab: `pw-repl serve http://localhost:3000`.
-- `--launch` works with each of them. Flags after `--` go to that Chromium.
+- `--launch` works with each of them. Flags after `--` go to that Chromium (flags only; a start URL goes before `--`).
 - A REPL of your own goes on a socket of its own: `-e /tmp/mine.sock` on every command, `serve`
   included, or set `PW_SOCKET`. `serve <port>` listens on TCP, on 127.0.0.1 only.
 

package/bin/pw-repl.js

@@ -38,6 +38,9 @@ $PW_ENDPOINT, then $PW_SOCKET, then the default.
 send -c <client> (or $PW_CLIENT) sends as a client of the REPL's with a selected tab of its own, so
 several agents can share one REPL; pw-repl help session has the rest.
 
+send's options can also follow the command, as in pw-repl send open <url> -t 30; after a -- before the
+command, every word is the command's, -t 30 included.
+
 send exit status: 0 ok, 1 command error, 2 completion not confirmed, 64 usage or unreachable. send -t is
 how long send waits for the answer (default 20s); it does not lengthen a command's own limits, such as
 the 5s an action waits for its element.
@@ -64,7 +67,7 @@ The browser must be running with --remote-debugging-port (default http://localho
 --launch is the quick start instead: it starts a Chromium of the REPL's own (headless unless --headed, in
 a temporary profile, on a free port of its own, which pw-repl where names), prints the command it ran,
 and stops it with the REPL (Ctrl-C while it starts too); stop returns once that Chromium has exited.
-Flags after -- go to it; a --user-data-dir=<dir> among them is used instead of the temporary profile, and
+Flags after -- go to it, and only flags; a --user-data-dir=<dir> among them is used instead of the temporary profile, and
 kept. 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 pw-repl, pw-repl send reaches pw-repl run without the server.`;
@@ -74,15 +77,49 @@ const REPL_HELP = `The REPL's own commands: help at the pw> prompt, or pw-repl s
 pw-repl help <topic | command [--all] | --all> shows one part of it; pw-repl help video and pw-repl
 help playwright-cli are guides.`;
 
-function usage() {
-  console.error(USAGE);
+const SUBCOMMANDS = ['run', 'serve', 'attach', 'stop', 'send', 'where', 'help', 'skill'];
+
+// What is wrong, then only the usage of the subcommand it is about: the whole of it would bury the line
+// that matters. With no message, the whole usage (-h after a subcommand).
+function usage(message, subcommand) {
+  if (!message) {
+    console.error(USAGE);
+    process.exit(64);
+  }
+  console.error(`pw-repl: ${message}`);
+  const lines = subcommand && USAGE.split('\n\n').find(block => new RegExp(`^(?:Usage:\\n)?  pw-repl ${subcommand}(?: |\\n|$)`).test(block));
+  if (lines) console.error(`Usage:\n${lines.replace(/^Usage:\n/, '')}`);
+  console.error(`pw-repl --help has the ${lines ? 'rest' : 'usage'}.`);
   process.exit(64);
 }
 
-// -e, -s, -c and -t, then the command words (unquoted words are one command).
-function parseSendArgs(args, allowCommand) {
+// A command line to copy, quoted as a shell reads it.
+function shellLine(words) {
+  return words.map(w => (/^[\w@%+=:,./-]+$/.test(w) ? w : `'${w.replace(/'/g, "'\\''")}'`)).join(' ');
+}
+
+// -e, -s, -c and -t, then the command words (unquoted words are one command), and send's options again
+// at the end, as an agent types them (send open <url> -t 30); after --, every word is the command.
+function parseSendArgs(args, subcommand) {
+  const allowCommand = subcommand === 'send';
   const options = { endpoint: null, session: null, client: null, timeout: 20, command: '', file: null };
+  const given = new Set();
+  const take = (arg, value, after) => {
+    if (value === undefined) usage(`${arg} needs a value`, subcommand);
+    // Given before the command and after it, neither silently wins.
+    if (after && given.has(arg)) usage(`${arg} is given twice, ${value === true ? arg : `${arg} ${value}`} after the command; give it once`, subcommand);
+    given.add(arg);
+    if (arg === '--no-vars') options.noVars = true;
+    if (arg === '-e') options.endpoint = value;
+    if (arg === '-s') options.session = value;
+    if (arg === '-c') options.client = value;
+    if (arg === '-t') {
+      if (!/^\d+$/.test(value) || Number(value) < 1) usage(`-t takes whole seconds, 1 or more (got ${value})`, subcommand);
+      options.timeout = Number(value);
+    }
+  };
   let i = 0;
+  let dashes = false;
   for (; i < args.length; i++) {
     const arg = args[i];
     // playwright-cli's --raw: the output here is only the command's already.
@@ -97,22 +134,22 @@ function parseSendArgs(args, allowCommand) {
     // A file of commands, one per line, as typed at the prompt.
     if (arg.startsWith('--file=') && arg.length > 7) { options.file = require('path').resolve(arg.slice(7)); continue; }
     if (arg === '--file') {
-      if (args[i + 1] === undefined) usage();
+      if (args[i + 1] === undefined) usage('--file needs a file of commands', subcommand);
       options.file = require('path').resolve(args[++i]);
       continue;
     }
-    if (arg === '--no-vars') { options.noVars = true; continue; }
-    if (arg === '-e' || arg === '-s' || arg === '-c' || arg === '-t') {
-      const value = args[++i];
-      if (value === undefined) usage();
-      if (arg === '-e') options.endpoint = value;
-      if (arg === '-s') options.session = value;
-      if (arg === '-c') options.client = value;
-      if (arg === '-t') {
-        if (!/^\d+$/.test(value) || Number(value) < 1) usage();
-        options.timeout = Number(value);
-      }
-    } else if (arg === '--') { i++; break; } else break;
+    if (arg === '--no-vars') take(arg, true);
+    else if (arg === '-e' || arg === '-s' || arg === '-c' || arg === '-t') take(arg, args[++i]);
+    else if (arg === '--') { i++; dashes = true; break; } else break;
+  }
+  const words = args.slice(i);
+  // A word the shell kept whole ("a -t 3") is never one of these; an option with a bad value is still
+  // send's, refused, not the end of a URL or a selector.
+  while (allowCommand && !dashes) {
+    const last = words.length - 1;
+    if (last > 0 && words[last] === '--raw') words.pop();
+    else if (last > 0 && words[last] === '--no-vars') take(words.pop(), true, true);
+    else if (last > 1 && /^-[ecst]$/.test(words[last - 1])) { const value = words.pop(); take(words.pop(), value, true); } else break;
   }
   // An address that is refused (not loopback) is a usage error, said once, not a stack trace.
   const endpoint = options.endpoint || process.env.PW_ENDPOINT;
@@ -124,9 +161,9 @@ function parseSendArgs(args, allowCommand) {
       process.exit(64);
     }
   }
-  const words = args.slice(i);
-  if (!allowCommand && (words.length || options.file)) usage();
-  if (options.file && words.length) usage();
+  if (!allowCommand && options.file) usage(`--file is send's; ${subcommand} runs no commands`, subcommand);
+  if (!allowCommand && words.length) usage(`${subcommand} takes no command (got ${shellLine(words)})`, subcommand);
+  if (options.file && words.length) usage(`a command or --file, not both (got --file and ${shellLine(words)})`, subcommand);
   options.command = require('../lib/send').commandLine(words);
   return options;
 }
@@ -141,17 +178,35 @@ function startOptions(args, serve) {
   if (serve) options.background = flag('--background');
   options.launch = flag('--launch');
   options.headed = flag('--headed');
-  if ((options.headed || options.chromeArgs.length) && !options.launch) usage();
+  const subcommand = serve ? 'serve' : 'run';
+  if (options.headed && !options.launch) usage('--headed is for the Chromium --launch starts; add --launch', subcommand);
+  if (options.chromeArgs.length && !options.launch) usage('flags after -- go to the Chromium --launch starts; add --launch', subcommand);
+  // Chromium takes any word that is not a --switch as a page to open, and a headless one refuses a second.
+  const n = options.chromeArgs.findIndex(word => !word.startsWith('-'));
+  if (n !== -1) {
+    const [page, before] = [options.chromeArgs[n], options.chromeArgs[n - 1]];
+    // Most likely a switch's value given as a word of its own (--user-data-dir /tmp/p); a URL after a
+    // switch is a URL (--disable-gpu http://...).
+    if (before && /^--[^=]+$/.test(before) && !page.includes('://')) usage(`${page} after -- would go to Chromium as a page to open: it takes a switch's value as ${before}=${page}`, subcommand);
+    usage(`${page} after -- would go to Chromium as a page to open; only flags go after --. A start URL goes before --; for a browser already running, leave out --launch and set PW_CDP_URL`, subcommand);
+  }
   // -e <endpoint>, as send, attach, stop and where take it, or the endpoint as the first word.
   const e = rest.indexOf('-e');
   if (serve && e !== -1 && rest[e + 1] && looksLikeEndpoint(rest[e + 1])) {
     options.endpoint = rest.splice(e, 2)[1];
     // Two endpoints, one with -e: neither silently wins.
-    if (rest[0] && looksLikeEndpoint(rest[0])) usage();
+    if (rest[0] && looksLikeEndpoint(rest[0])) usage(`two endpoints, -e ${options.endpoint} and ${rest[0]}: give one`, subcommand);
   } else if (serve && rest[0] && looksLikeEndpoint(rest[0])) options.endpoint = rest.shift();
   // Otherwise the socket send would look for: PW_ENDPOINT, then PW_SOCKET, then the default.
   if (serve && !options.endpoint) options.endpoint = process.env.PW_ENDPOINT || process.env.PW_SOCKET || null;
-  if (rest.length > 1 || (rest[0] && rest[0].startsWith('-'))) usage();
+  const option = rest.find(word => word.startsWith('-'));
+  if (option === '-h' || option === '--help') usage();
+  if (option === '-e') {
+    usage(serve ? `-e takes an endpoint: a socket (/tmp/<name>.sock), a port, or 127.0.0.1:port (got ${rest[rest.indexOf('-e') + 1] ?? 'nothing'})` : 'run has no command server, so no endpoint; pw-repl serve has one', subcommand);
+  }
+  if (option === '--background') usage('--background is serve\'s: pw-repl serve --background', subcommand);
+  if (option) usage(`unknown option ${option}`, subcommand);
+  if (rest.length > 1) usage(`one start URL at most (got ${shellLine(rest)})`, subcommand);
   options.startUrl = rest[0] || null;
   return options;
 }
@@ -185,15 +240,15 @@ async function main() {
     }
     case 'attach':
     case 'stop': {
-      const options = parseSendArgs(args, false);
-      if (options.session) usage();
+      const options = parseSendArgs(args, subcommand);
+      if (options.session) usage(`-s is send's tmux session; ${subcommand} takes -e <endpoint>`, subcommand);
       // The same socket send would use when there is no -e: PW_ENDPOINT, then PW_SOCKET.
       const endpoint = options.endpoint || process.env.PW_ENDPOINT || process.env.PW_SOCKET || null;
       process.exit(await require('../lib/background')[subcommand]({ endpoint }));
     }
     // falls through never: process.exit above
     case 'send': {
-      const options = parseSendArgs(args, true);
+      const options = parseSendArgs(args, 'send');
       // 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());
@@ -201,7 +256,7 @@ async function main() {
     }
     // falls through never: process.exit above
     case 'where':
-      process.exit(await require('../lib/send').where(parseSendArgs(args, false)));
+      process.exit(await require('../lib/send').where(parseSendArgs(args, 'where')));
     // falls through never
     case 'help': {
       const topic = args.join(' ').trim();
@@ -209,7 +264,7 @@ async function main() {
       return console.log(`${USAGE}\n\n${REPL_HELP}`);
     }
     case 'skill':
-      if (args.length) usage();
+      if (args.length) usage(`skill takes no arguments (got ${shellLine(args)})`, 'skill');
       return skill();
     case '-v':
     case '--version':
@@ -217,8 +272,17 @@ async function main() {
     case '-h':
     case '--help':
       return console.log(`${USAGE}\n\n${REPL_HELP}`);
-    default:
-      return usage();
+    default: {
+      // An option before the subcommand (pw-repl -t 30 send ...): say where it goes, with the line fixed.
+      if (subcommand.startsWith('-')) {
+        const all = [subcommand, ...args];
+        const named = all.find(word => SUBCOMMANDS.includes(word));
+        const fixed = named ? shellLine(['pw-repl', named, ...all.filter((word, n) => n !== all.indexOf(named))]) : `pw-repl send ${shellLine(all)} <command>`;
+        return usage(`${subcommand} is an option of a subcommand, and goes after it: ${fixed}`, named || 'send');
+      }
+      const url = /^[a-z][\w+.-]*:/i.test(subcommand) && !looksLikeEndpoint(subcommand) ? `; a start URL goes after run or serve: pw-repl run ${subcommand}` : '';
+      return usage(`${subcommand} is not a command (they are ${SUBCOMMANDS.join(', ')})${url}`);
+    }
   }
 }
 

package/lib/emulation.js

@@ -175,9 +175,10 @@ const commands = {
       out.log(`Viewport off: ${await viewportText()}`);
       return;
     }
-    const match = /^(\d+)x(\d+)$/.exec(arg);
+    const match = /^(\d+)x(\d+)$/i.exec(arg);
     const [w, h] = match ? [Number(match[1]), Number(match[2])] : [];
-    if (!w || !h) throw new Error('Usage: viewport [<width>x<height> | off]');
+    if (!match) throw new Error(`A size is <width>x<height>, e.g. viewport 1280x900 (got ${arg}). Usage: viewport [<width>x<height> | off]`);
+    if (!w || !h) throw new Error(`A width and a height are 1 or more (got ${arg})`);
     // Both set the screen size; whichever came last would win without saying so.
     if (tabState(state.page).emulation?.device) throw new Error('emulate mobile sets the size of the selected tab; emulate mobile off first');
     await setViewport(state.page, { width: w, height: h });

package/lib/help.js

@@ -610,7 +610,11 @@ goes on recording. There is no --mp4 or --webm: the file's ending picks the form
       ['off', 'back to the window\'s size.'],
       ['(none)', 'shows the size, and whether it was set or is the window\'s.'],
     ],
-    detail: `emulate mobile sets a phone's size instead, and each refuses while the other is on.`,
+    detail: `emulate mobile sets a phone's size instead, and each refuses while the other is on.
+
+The window's size here is the size of the page in it. Chromium's --window-size flag sizes the whole
+window, frame included, so the page is smaller: --window-size=1280,900 gives 1280x757 in a headless one.
+For a page of an exact size, use viewport <W>x<H>.`,
   },
   emulate: {
     usage: 'emulate [<what> [off] | off]',

package/lib/inspect.js

@@ -442,7 +442,12 @@ const commands = {
     const onlyWhat = (tokens[0] === 'text' || tokens[0] === 'request') && tokens.length === 2;
     const tookSeconds = tokens.length > 1 && !onlyWhat && /^\d+$/.test(tokens[tokens.length - 1]);
     if (tookSeconds) seconds = Number(tokens.pop());
-    if (!tokens.length || seconds < 1 || seconds > WAIT_MAX) throw new Error(`${usage} (1-${WAIT_MAX})`);
+    if (!tokens.length) throw new Error(`${usage} (1-${WAIT_MAX})`);
+    if (seconds < 1 || seconds > WAIT_MAX) {
+      // Most likely text that ends in a number, not seconds at all.
+      const text = tokens[0] === 'text' && !/^["']/.test(tokens[1]) ? `; for text that ends in a number, quote it: wait text "${tokens.slice(1).join(' ')} ${seconds}"` : '';
+      throw new Error(`wait takes 1-${WAIT_MAX} seconds (got ${seconds})${text}`);
+    }
     const timeout = seconds * 1000;
     // Said plainly, not as Playwright's call log.
     const plainly = message => error => { throw /Timeout \d+ms exceeded/.test(error.message) ? new Error(message) : error; };

package/lib/start.js

@@ -148,7 +148,8 @@ async function start(options) {
   rl.on('close', () => {
     if (state.stopping) return;
     endPromptLine();
-    out.error('Input ended; disconnecting.');
+    // With no terminal (an agent's shell, a pipe), input ends at once: say what runs without one.
+    out.error(process.stdin.isTTY ? 'Input ended; disconnecting.' : 'Input ended (stdin is not a terminal); disconnecting. pw-repl serve --background runs it without one.');
     runner.drained().then(() => shutdown(), () => shutdown())
       .then(beforeExit).then(() => process.exit(process.exitCode || 0));
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pw-repl",
-  "version": "0.12.6",
+  "version": "0.12.7",
   "description": "Text REPL for driving an existing Chromium through Playwright over CDP",
   "keywords": [
     "playwright",

package/skill/SKILL.md

@@ -54,12 +54,12 @@ run one; each takes an optional start URL, which opens in a new tab.
 - Add `--launch` to `run` or `serve` (with or without `--background`) to have it start a Chromium of its
   own instead of connecting to one: headless unless `--headed`, in a temporary profile, on a free port
   of its own (never 9222). It stops with the REPL, Ctrl-C while it starts included, and `stop` returns
-  once it has exited. It prints the command it ran; flags after `--` are passed to that Chromium, and a
-  `--user-data-dir=<dir>` among them is used instead of the temporary profile, and kept. Started again
-  in a kept profile, Chromium picks up where it left off, as it would for the user, headless too: its
-  tabs come back, and session cookies with them, so a login stays. They start loading before the REPL is
-  attached, so `requests` and `console` have only what came after, often nothing: `reload` for a full
-  record.
+  once it has exited. It prints the command it ran; flags after `--` are passed to that Chromium (only
+  flags: a start URL goes before `--`), and a `--user-data-dir=<dir>` among them is used instead of the
+  temporary profile, and kept. Started again in a kept profile, Chromium picks up where it left off, as
+  it would for the user, headless too: its tabs come back, and session cookies with them, so a login
+  stays. They start loading before the REPL is attached, so `requests` and `console` have only what
+  came after, often nothing: `reload` for a full record.
 - `pw-repl run` runs it in a terminal with no server; `send` then reaches it through tmux, if it runs in
   the tmux session `pw-repl`:
 
@@ -112,8 +112,9 @@ of a REPL of your own, which `send` refuses. The words after `send` are the comm
 `select`, `press`, `upload` and `wait`, a word quoted in your shell stays one word
 (`pw-repl send fill "text=Your name" Ada`, `pw-repl send wait text "Showing 1"`); other commands get the words as they are, joined by
 spaces (`pw-repl send eval "document.title + ' x'"`). A command that takes only a selector takes the
-whole line, spaces and all: `pw-repl send click "text=Your name"`. It works however the REPL was
-started:
+whole line, spaces and all: `pw-repl send click "text=Your name"`. `send`'s own options (`-t`, `-c`, `-e`,
+`-s`, `--no-vars`) go before the command or after it (`pw-repl send open <url> -t 30`); after `--`, every
+word is the command's. It works however the REPL was started:
 
 - `run` (in tmux): `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