pw-repl 0.12.6 → 0.12.8

package/AGENTS.md

@@ -53,7 +53,9 @@ If you hit a limitation or write a workaround, consider adding the capability to
   shown by `help <command> --all` and `help --all`. An error about something in `more` ends by naming it
   (`help record --all`). Paragraphs are plain: `wrap()` lays each out at 104 columns, and keeps as written
   a paragraph with a bullet, a table or an indented example. `test/fixtures` holds the rendered help;
-  after an intended change to it, save it again (the command is in `test/units.test.js`).
+  after an intended change to it, save it again (the command is in `test/units.test.js`). The common
+  tasks and modes on help's front page (`TASKS` and `MODES`) are the README's too: change both, as a
+  unit test compares them.
 - Time each full run, and put the result in the body of the commit it tests (`npm test: 151 tests, 79s`).
   Compare with the last commit that has one (`git log --grep='npm test:'`): a run that grew by more than
   a few seconds means a slow test crept in, usually one waiting out a real timeout (5s for a click).
@@ -104,7 +106,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

@@ -24,6 +24,39 @@ pw> reload
 pw> console error                       # and see how the page copes
 ```
 
+## Quick start
+
+You need Node.js 20 or newer. pw-repl can use a Chromium-based browser you already have (Chrome,
+Chromium, ...), or Playwright's own: `npx playwright-core install chromium` downloads it.
+
+```bash
+npx pw-repl@latest run --launch https://example.com
+```
+
+`--launch` starts a private headless Chromium for the REPL, in a 1280x800 window, and stops it when
+the REPL quits. Add `--headed` to see that browser and click in it yourself. The page opens, and a
+`pw>` prompt waits:
+
+```text
+pw> help                          # common tasks and topics; help <topic>, help <command>, help --all
+pw> snapshot
+pw> click e3
+pw> screenshot
+pw> quit
+```
+
+Commands act on the selected tab. `tab` lists the tabs, with `*` on the selected one.
+
+### Install
+
+| How          | Setup                                        | Then run                       |
+| ------------ | -------------------------------------------- | ------------------------------ |
+| Without      | nothing                                      | `npx pw-repl@latest <command>` |
+| Global       | `npm install -g pw-repl`                     | `pw-repl <command>`            |
+| From a clone | `npm install` (and `npm link` for `pw-repl`) | `bin/pw-repl.js <command>`     |
+
+With `npx`, use `npx pw-repl@latest` the same way every time, so every command runs the same version.
+
 ## Why use it
 
 - **Your browser, as it is.** It connects to a running Chromium, with your tabs, logins and state, and
@@ -42,14 +75,15 @@ pw> console error                       # and see how the page copes
 
 - **Read the page:** accessibility snapshots with clickable refs, text, HTML, attributes, links, form
   controls, event listeners, screenshots (viewport, full page or one element).
-- **Act on it:** click, fill, type, press keys, select, check, upload files, move the mouse, scroll the
-  wheel, answer dialogs.
+- **Act on it:** click, double-click, fill, type, press keys, select, check, drag and drop, upload files,
+  click or drag at a point, scroll the wheel, answer dialogs.
 - **Watch the network:** every request and response body, console messages and page errors, all recorded
   as they happen.
 - **Change the network:** fake a response (`route`), patch its JSON, delay it, fail it, or cut or slow the
   whole tab's network.
 - **Emulate:** a phone, dark mode, a locale, a timezone, a viewport size.
-- **Run code:** `eval` any JavaScript in the page, or send a raw CDP command with `cdp`.
+- **Run code:** `eval` any JavaScript in the page, a line or a file of it, or send a raw CDP command with
+  `cdp`.
 - **Wait:** for an element, some text, a response or a page load.
 - **Record:** what someone does in a tab (`watch`), a timeline of requests and console (`capture`), or a
   video of the tab (`record`), with a virtual pointer (`cursor`), captions (`toast`) and highlights
@@ -59,42 +93,10 @@ pw> console error                       # and see how the page copes
 - **Share:** many clients on one REPL, each with its own tab; a command server on a Unix socket or a local
   port, with an HTTP+JSON protocol.
 
-## Quick start
-
-You need Node.js 20 or newer. pw-repl can use a Chromium-based browser you already have (Chrome,
-Chromium, ...), or Playwright's own: `npx playwright-core install chromium` downloads it.
-
-```bash
-npx pw-repl@latest run --launch https://example.com
-```
-
-`--launch` starts a private headless Chromium for the REPL and stops it when the REPL quits. Add
-`--headed` to see that browser and click in it yourself. The page opens in a new tab, and a `pw>`
-prompt waits:
-
-```text
-pw> help                          # common tasks and topics; help <topic>, help <command>, help --all
-pw> snapshot
-pw> click e3
-pw> screenshot
-pw> quit
-```
-
-Commands act on the selected tab. `tab` lists the tabs, with `*` on the selected one.
-
-### Install
-
-| How          | Setup                                        | Then run                       |
-| ------------ | -------------------------------------------- | ------------------------------ |
-| Without      | nothing                                      | `npx pw-repl@latest <command>` |
-| Global       | `npm install -g pw-repl`                     | `pw-repl <command>`            |
-| From a clone | `npm install` (and `npm link` for `pw-repl`) | `bin/pw-repl.js <command>`     |
-
-With `npx`, use `npx pw-repl@latest` the same way every time, so every command runs the same version.
-
 ## Use your own browser
 
-Start Chrome with remote debugging, then run the REPL without `--launch`:
+Start Chrome with remote debugging (on Linux it may be `google-chrome` or `chromium`), then run the REPL
+without `--launch`:
 
 ```bash
 chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.config/chrome-debug"
@@ -126,47 +128,49 @@ 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.
 
 ## Common tasks
 
-| I want to…                            | Commands                                                                             |
-| ------------------------------------- | ------------------------------------------------------------------------------------ |
-| see where I am                        | `tab` (it marks the tab you are looking at `(visible)`), `info`                      |
-| see what is on the page               | `snapshot`, `screenshot`                                                             |
-| do something on it                    | `click`, `fill`, `type`, `press`                                                     |
-| click what has no selector (a canvas) | `mouseclick <x> <y>`                                                                 |
-| run some JavaScript in the page       | `eval document.title`                                                                |
-| wait for a page or element            | `wait load`, `wait <selector>`, `wait <selector> --gone`, `wait text <text>`         |
-| 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`                                                                    |
-| replay what I clicked through         | `watch on`, click around, `watch save flow.txt`, then `pw-repl send --file flow.txt` |
-| record requests and console together  | `capture on`, then `capture off`                                                     |
-| find what makes the page slow         | `profile on`, then `profile off`; `profile reload` for a page load                   |
-| fake a backend response               | `route <glob> <status> <json>`, `route <glob> abort`                                 |
-| change or slow an API response        | `route <glob> patch <json>`, `route <glob> delay <secs>`                             |
-| cut or slow the whole network         | `network off`, `network slow`, then `network on`                                     |
-| record a video of the page            | `record on`, then `record off` (`help video` for a take with a pointer)              |
-| show a pointer where the agent acts   | `cursor on`, then `cursor off` (in screenshots and videos)                           |
-| say what is happening on screen       | `toast <text>`, then `toast off` (`--duration=3s` hides it by itself)                |
-| point something out on the page       | `highlight <ref>` draws a box; `highlight off` hides it                              |
-| 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`, `type`, `press`, `drag`                      |
+| click what has no selector (a canvas) | `mouseclick <x> <y>`, `mousedblclick <x> <y>`                 |
+| run some JavaScript in the page       | `eval document.title`; `eval --file=check.js` for a long one  |
+| wait for a page or element            | `wait load`, `wait <selector> [--gone]`, `wait text <text>`   |
+| choose a file in a file input         | `upload <selector> <file>`                                    |
+| see it as a phone, or in dark mode    | `emulate mobile`, `emulate dark`                              |
+| 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, then `watch`                        |
+| see each step as I click              | `watch on --live`                                             |
+| watch a tab someone will open         | `watch on --next-tab [url-part]`                              |
+| replay what I clicked through         | `watch save flow.txt`, then `pw-repl send --file flow.txt`    |
+| record requests and console together  | `capture on`, then `capture off`                              |
+| find what makes the page slow         | `profile on`, then `profile off`; `profile reload` for a load |
+| fake a backend response               | `route <glob> <status> <json>`, `route <glob> abort`          |
+| change or slow an API response        | `route <glob> patch <json>`, `route <glob> delay <secs>`      |
+| cut or slow the whole network         | `network off`, `network slow`, then `network on`              |
+| record a video of the page            | `record on`, then `record off` (`help video` for a take)      |
+| show a pointer where the agent acts   | `cursor on`, then `cursor off`                                |
+| say what is happening on screen       | `toast <text>`, then `toast off`                              |
+| point something out on the page       | `highlight <ref>`, then `highlight off`                       |
+| clean up                              | `modes off`                                                   |
 
 `help <topic>` lists the rest, and `help <command>` has usage and caveats.
 
 ### Modes
 
-Some commands turn on a mode that stays on until you turn it off: `watch`, `capture`, `profile`, `route`,
-`network off` or `slow`, `emulate`, `viewport`, `record`, `highlight`, `cursor` and `toast`. 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. Each of these commands on its own shows its state and
-what you can run next.
+Some commands turn on a mode that stays on until you turn it off: `watch`, `capture`, `profile`,
+`record`, `route`, `network off` or `slow`, `emulate`, `viewport`, `highlight`, `cursor` and `toast`.
+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. Each of these commands on its own shows
+its state and what you can run next.
 
 ## For agents and scripts
 
@@ -204,12 +208,10 @@ each mode on, and `modes off --mine` turns off only the sender's own.
 `send --file take.txt` runs a file of commands, one per line, and stops at the first that fails: a
 repro to keep, or a video take.
 
-**Passwords:** type one as a variable: `PW_PASSWORD=... pw-repl send fill '#password' "{{ PW_PASSWORD
-}}"`, or the same line in a file run with `send --file`, as `watch save` writes it. `send` passes the
-value along with the command, and the REPL puts it in only as it runs the command, so the file, the
-REPL's output, its log and its history never hold it. Output that reads it back can: `snapshot`, `html`
-and `attrs` hide a password field's value, but `eval` on the field, a field that a Show password button
-made plain text, or page text that repeats it do not. Only `PW_` names are variables.
+**Passwords:** type one as a variable, so it is never in the command, a file of commands or the REPL's
+log: `PW_PASSWORD=... pw-repl send fill '#password' "{{ PW_PASSWORD }}"` (`watch save` writes them that
+way). What reads the page back can still show it: `snapshot`, `html` and `attrs` hide a password field's
+value; `eval` on the field does not.
 
 ### The HTTP protocol
 

package/bin/pw-repl.js

@@ -9,7 +9,8 @@ const USAGE = `Usage:
 
   pw-repl serve [--background] [--launch [--headed]] [[-e] endpoint] [start-url] [-- <chromium flags>]
       the same, plus a command server (socket, port, or 127.0.0.1:port; default /tmp/pw-repl.sock);
-      --background runs it detached, with its output in a log next to the socket
+      --background runs it detached, with its output in a log next to the socket; a socket's folder is
+      made if it is missing
 
   pw-repl attach [-e endpoint]
       see everything a background REPL does, and type commands to it; Ctrl-C leaves it running
@@ -18,7 +19,8 @@ const USAGE = `Usage:
       stop a background REPL, and say what became of each recording it ended; its socket is removed, its
       log stays
 
-  pw-repl send [-e endpoint | -s session] [-c client] [-t seconds] [--no-vars] <command...> | --file <file>
+  pw-repl send [-e endpoint | -s session] [-c client] [-t seconds] [--no-vars]
+               <command...> | --file <file>
       run one command in a running REPL and print its output; --file runs a file of them, one per line
 
   pw-repl where [-e endpoint | -s session]
@@ -30,59 +32,100 @@ const USAGE = `Usage:
   pw-repl skill
       print an agent skill (SKILL.md) that teaches an agent to use the REPL
 
+A browser: --launch starts a Chromium of the REPL's own, headless unless --headed, 1280x800, in a
+temporary profile, on a free port of its own (pw-repl where names it). It prints the command it ran, and
+stops with the REPL (Ctrl-C while it starts too); stop returns once it has exited. Flags after -- go to
+it, and only flags (a start URL goes before --); a --user-data-dir=<dir> among them is used instead of
+the temporary profile, and kept. PW_CHROME picks which Chromium.
+
+Without --launch, the REPL connects to a browser running with --remote-debugging-port, at $PW_CDP_URL
+(default http://localhost:9222).
+
 send uses the server when -e, $PW_ENDPOINT, or the socket ($PW_SOCKET, default /tmp/pw-repl.sock) is
-there, and the tmux session (-s, $PW_TMUX_SESSION, default pw-repl) otherwise. If the socket exists but
-nothing answers, send fails rather than fall back. serve without an endpoint serves on that same one:
-$PW_ENDPOINT, then $PW_SOCKET, then the default.
+there, and the tmux session where pw-repl run runs otherwise (-s, $PW_TMUX_SESSION, default pw-repl).
+serve without an endpoint serves on that same socket. send exit status: 0 ok, 1 command error, 2
+completion not confirmed, 64 usage or unreachable. pw-repl send --help has the rest: clients, -t,
+--file and variables.`;
+
+// pw-repl send --help: what send does beyond its usage line.
+const SEND_HELP = `send uses the server when -e, $PW_ENDPOINT, or the socket ($PW_SOCKET, default /tmp/pw-repl.sock) is
+there, and the tmux session (-s, $PW_TMUX_SESSION, default pw-repl) otherwise, where pw-repl run runs.
+If the socket exists but nothing answers, send fails rather than fall back. serve without an endpoint
+serves on that same one: $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 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.
-
-send --file <file> runs each line of a file as a command, in order, as if typed at the REPL's prompt:
-quoted as the prompt reads it (no shell), with a file it records, uploads or saves relative to this
-folder, as on send's command line, and # comments and blank lines skipped. It stops at the first
-command that fails, saying its line, with its exit status. -t is each command's own limit. Other
-clients' commands can run between its lines, on their own tabs.
-
-A {{ PW_NAME }} in a command, or in a line of the file, is a variable: send takes its value from its own
-environment (PW_NAME) and passes it along with the command, not in it, e.g. a password kept out of the
-file and out of the command as the REPL logs it. In a file: fill '#password' "{{ PW_PASSWORD }}",
-run with PW_PASSWORD=... pw-repl send --file login.txt; or one command: PW_PASSWORD=... pw-repl send
-fill '#password' "{{ PW_PASSWORD }}". Only names starting PW_ are variables: any other {{ ... }}, as in a
-page's template text, is sent as written. In a file, put it in double quotes: there its value is
-escaped as they read it (in single quotes, which escape nothing, a value with a ' is refused). The REPL
-puts it in only as it runs the command, and its pane and log show the command as written. A variable that
-is not set stops the command, or the file at that line, before it is sent. --no-vars sends
-{{ PW_NAME }} as it is. Variables need the command server (pw-repl serve), not the tmux pane.
-
-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, 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
-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.`;
+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.
+
+Exit status: 0 ok, 1 command error, 2 completion not confirmed, 64 usage or unreachable. -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.
+
+--file <file> runs each line of a file as a command, in order, as if typed at the REPL's prompt: quoted
+as the prompt reads it (no shell), with a file it records, uploads or saves relative to this folder, as
+on send's command line, and # comments and blank lines skipped. It stops at the first command that
+fails, saying its line, with its exit status. -t is each command's own limit. Other clients' commands
+can run between its lines, on their own tabs.
+
+Variables: a {{ PW_NAME }} in a command, or in a line of the file, takes its value from send's own
+environment (PW_NAME), passed along with the command, not in it, so a password stays out of the file and
+out of the REPL's log: PW_PASSWORD=... pw-repl send fill '#password' "{{ PW_PASSWORD }}", or
+PW_PASSWORD="$(cat <file>)" to give it from a file without typing it. Only PW_ names are variables; any
+other {{ ... }} is sent as written. In a file, put one in double quotes (in single quotes, a value with
+a ' is refused). One that is not set stops the command, or the file at that line, before it is sent;
+--no-vars sends {{ PW_NAME }} as it is. Variables need the command server (pw-repl serve), not the tmux
+pane.`;
 
 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] | --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 +140,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 +167,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 +184,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;
 }
@@ -174,26 +235,43 @@ function skill() {
 
 async function main() {
   let [subcommand, ...args] = process.argv.slice(2);
+  // -h after send, where, attach or stop is a request for help, never a command to send.
+  if (['send', 'where', 'attach', 'stop'].includes(subcommand) && /^(?:-h|--help)$/.test(args[0] || '')) {
+    if (subcommand !== 'send') return console.log(`${USAGE}\n\n${REPL_HELP}`);
+    const block = USAGE.split('\n\n').find(b => b.startsWith('  pw-repl send '));
+    return console.log(`Usage:\n${block}\n\n${SEND_HELP}`);
+  }
   // 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': {
       const options = startOptions(args, subcommand === 'serve');
+      // A socket of one's own is often in a folder of its own (/tmp/<name>/repl.sock): made here, before
+      // the log, the pid file or the socket go in it, whichever way serve runs. Owner-only, as the socket is.
+      const socket = subcommand === 'serve' ? require('../lib/client').parseEndpoint(options.endpoint).socket : null;
+      if (socket) {
+        const folder = require('path').dirname(socket);
+        try { require('fs').mkdirSync(folder, { recursive: true, mode: 0o700 }); } catch (error) {
+          console.error(`pw-repl: cannot create ${folder} for the socket (${error.code === 'EEXIST' ? 'a file is there' : error.code || error.message})`);
+          process.exit(64);
+        }
+      }
       if (options.background) process.exit(await require('../lib/background').start(options));
       return require('../lib/start').start(options);
     }
     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');
+      if (!options.command && !options.file) usage('no command given', '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 +279,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 +287,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 +295,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/cli-names.js

@@ -13,7 +13,7 @@ const NAMES = {
   'tab-select': [a => `tab-select ${a}`, 'tab <index>, by index only'],
   // By index there, by URL here: a number could match a port in another tab's URL.
   'tab-close': [a => (a ? null : 'tab close'), 'tab close [url-part], or tab <index> then tab close'],
-  open: [a => `tab new ${a}`.trim(), 'tab new [url]; --mobile or --device=<name> is emulate mobile [name]'],
+  open: [a => `tab new ${a}`.trim(), 'tab new [url] (goto <url> navigates); --mobile, --device=<name>: emulate mobile'],
   // It ends playwright-cli's own browser; this one is shared, so tabs stay open.
   close: [() => 'close', 'modes off --mine, and tabs stay open'],
   'go-back': [() => 'back', 'back'],
@@ -69,7 +69,7 @@ const NEAREST = {
   list: 'pw-repl where says which REPL is running; one REPL serves everyone using its browser',
   attach: 'pw-repl serve connects to the browser on PW_CDP_URL; pw-repl skill has the rest',
   detach: 'pw-repl stop, or quit at the prompt, disconnects and leaves the browser running',
-  drag: 'not here yet', drop: 'not here yet', 'webmcp-list': 'not here yet', 'webmcp-call': 'not here yet',
+  drop: 'not here yet', 'webmcp-list': 'not here yet', 'webmcp-call': 'not here yet',
   keydown: 'not here yet; press <key> presses and releases one', keyup: 'not here yet; press <key> presses and releases one',
   pdf: 'not here yet; screenshot --full saves the whole page as a PNG',
   'generate-locator': 'not here yet; a snapshot ref (e5) works as a selector in any command',
@@ -244,7 +244,7 @@ function translate(text) {
   if (name === 'open') {
     const { found, rest: url } = takeOptions(args, OPTIONS.open);
     const device = found.find(o => o.name === 'device');
-    if (!device && !found.length) return { text: `tab new ${url}`.trim(), as: 'tab new [url]' };
+    if (!device && !found.length) return { text: `tab new ${url}`.trim(), as: 'tab new [url], a new tab each time; goto <url> navigates the selected tab' };
     if (device && !device.value) return { refuse: 'Usage: open [url] [--mobile | --device=<name>]' };
     return {
       steps: ['tab new', `emulate mobile${device ? ` ${device.value}` : ''}`, ...(url ? [`goto ${url}`] : [])],