pw-repl 0.3.2 → 0.4.1

package/AGENTS.md

@@ -14,16 +14,21 @@ If you hit a limitation or write a workaround, consider adding the capability to
   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;
+  command line's words are read, shared with `send`; `lib/cli-names.js` maps playwright-cli's command
+  names to these; `lib/state.js` holds the session state, with each client's selected tab;
   `lib/output.js` routes all output so the server can return it.
+- Match playwright-cli (Microsoft's CLI for agents) where it is reasonable: agents are likelier to be
+  trained on it. A new command, option or output that does what one of its does takes its name and form,
+  or accepts them too (`lib/cli-names.js`, `help playwright-cli`). Differ where sharing a browser with a
+  person needs it, and say why in the help.
 - Comment the *why* when it isn't obvious from the code.
-- `npm test` runs the suite (about a minute): a private headless Chromium, a local test site
+- `npm test` runs the suite (under two minutes): 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.
+- For anything the tests can't reach, exercise the change in a running REPL of your own: on a socket of
+  your own, with `--launch` unless the change needs the user's browser, and then in a tab of your own.
 - `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.
 
@@ -41,6 +46,8 @@ Work goes in waves, and each one ends with a release that is ready to push.
      ask again.
    - Then it carries the plan out, in a browser and on a socket of its own, and reports as it goes:
      above all, where the tool did something other than what the docs led it to expect.
+   - Once it has confirmed the fixes work, it reviews them as a second pair of eyes: anything important
+     they miss or get wrong, not nitpicks.
 3. Triage what it reports. Fix what matters, and what is small and useful; don't put off something
    useful for later. Leave trivia alone, and say why.
 4. Repeat 2 and 3, with a fresh agent each time, until a pass comes back clean: no real bugs, and

package/README.md

@@ -1,7 +1,40 @@
 # 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.
+A text REPL for driving an existing Chromium through Playwright over CDP: one session that people and agents
+share. People click in the browser and type commands at the prompt; agents send the same commands, and every
+one shows in the REPL, so each sees what the other does. The REPL inspects the page, records what happened
+(requests, console, and each step a person takes), fakes, patches or slows responses, and emulates phones,
+dark mode, locales and timezones.
+
+## Why use it
+
+For working on a web page together with an agent, in the browser you already use:
+
+- **Your browser, as it is.** It connects to a running Chromium, with your tabs, sign-ins and state, and
+  leaves it running when it stops; nothing is reset to a fresh profile.
+- **One session, seen by everyone.** You and any number of agents drive the same browser, each with a
+  selected tab of its own, and every command shows in the REPL, whoever sent it.
+- **What you did, for an agent to read.** `watch` records each step you take in a tab, with the requests
+  it caused, so you can reproduce a bug by hand and the agent can see exactly what happened.
+- **Breaking things on purpose.** Fake, patch, delay or fail responses, cut or slow the network, emulate a
+  phone, a locale or a timezone, all per tab, so your other tabs are left alone.
+
+## How it differs from playwright-cli
+
+[playwright-cli](https://github.com/microsoft/playwright-cli) is Microsoft's command line for agents. It
+gives each agent a browser session of its own; pw-repl shares one browser between a person and agents.
+Its command names and most of their options work here too (`help playwright-cli` lists them), and where
+pw-repl differs, it is because someone else may be using the browser:
+
+- `open` and `close` open a tab and turn off your modes; they never start, close or wipe a browser.
+- Routes, network and emulation apply to one tab, not the whole browser.
+- File pickers are not caught, since they may be the person's: `upload` names the input instead.
+- There is no snapshot after every command, since a person reads the REPL too; `snapshot` shows one.
+- Instead of `-s=<session>`, an agent is a client of its own (`send -c <name>`).
+- `watch` records what a person does as steps with their requests, not as generated code.
+
+For a browser of its own per agent, isolated sessions, traces, video, PDFs or generated test code,
+playwright-cli is the better fit.
 
 ## Getting started
 
@@ -141,6 +174,10 @@ may not have done what it was sent to do (it timed out, or the REPL quit while i
 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.
 
+Several agents can share one REPL: `pw-repl send -c <name>` (or `PW_CLIENT=<name>`) sends as a client with a
+selected tab of its own, shown in the pane as `[server:<name>]`. `modes` says which client turned each mode on,
+and `modes off --mine` turns off only the sender's own.
+
 ### A skill for agents
 
 `pw-repl skill` prints an agent skill (`SKILL.md`) that teaches an agent to use the REPL: how to start

package/bin/pw-repl.js

@@ -17,7 +17,7 @@ const USAGE = `Usage:
   pw-repl stop [-e endpoint]
       stop a background REPL
 
-  pw-repl send [-e endpoint | -s session] [-t seconds] <command...>
+  pw-repl send [-e endpoint | -s session] [-c client] [-t seconds] <command...>
       run one command in a running REPL and print its output
 
   pw-repl where [-e endpoint | -s session]
@@ -33,6 +33,9 @@ send uses the server when -e, $PW_ENDPOINT, or the socket ($PW_SOCKET, default /
 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 -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.
 
 The browser must be running with --remote-debugging-port (default http://localhost:9222; set $PW_CDP_URL).
@@ -53,17 +56,27 @@ function usage() {
   process.exit(64);
 }
 
-// -e, -s and -t, then the command words (unquoted words are one command).
+// -e, -s, -c and -t, then the command words (unquoted words are one command).
 function parseSendArgs(args, allowCommand) {
-  const options = { endpoint: null, session: null, timeout: 20, command: '' };
+  const options = { endpoint: null, session: null, client: null, timeout: 20, command: '' };
   let i = 0;
   for (; i < args.length; i++) {
     const arg = args[i];
-    if (arg === '-e' || arg === '-s' || arg === '-t') {
+    // playwright-cli's --raw: the output here is only the command's already.
+    if (arg === '--raw') continue;
+    // playwright-cli's -s=<session> names a browser of its own; the nearest here is a client.
+    if (/^(?:-s|--session)=/.test(arg)) {
+      console.error(`pw-repl: ${arg} is playwright-cli's session, a browser of its own. Here -s <name> is a tmux session;`);
+      console.error('the nearest to a session is a client: -c <name> (or PW_CLIENT), with a selected tab of its own, in a');
+      console.error('browser it shares, cookies, storage and modes and all.');
+      process.exit(64);
+    }
+    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);
@@ -77,11 +90,23 @@ function parseSendArgs(args, allowCommand) {
   // command takes the rest of its line as it is (eval, route's JSON), so its
   // words are joined as they are.
   const { SELECTOR_FIRST } = require('../lib/syntax');
-  const requote = words.length > 1 && SELECTOR_FIRST.has(words[0]);
+  // So does playwright-cli's storage key (localstorage-set "my key" v).
+  const requote = words.length > 1 && (SELECTOR_FIRST.has(words[0]) || /^(?:local|session)storage-/.test(words[0]));
   // An empty word (fill #name "") is the empty value.
   // 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;
+  // So are the files upload reads and screenshot --filename writes.
+  const resolve = require('path').resolve;
+  let resolved = words[0] === 'upload' ? words.map((w, n) => (n > 1 ? resolve(w) : w)) : words;
+  if (words[0] === 'screenshot') {
+    resolved = words.map((w, n) => (w.startsWith('--filename=') && w.length > 11 ? `--filename=${resolve(w.slice(11))}` : words[n - 1] === '--filename' ? resolve(w) : w));
+  }
   const quoted = requote ? resolved.map(w => (w === '' || /[\s"']/.test(w) ? JSON.stringify(w) : w)) : resolved;
+  // An option's value the shell kept whole stays whole too: --device='iPhone 15'.
+  // Single quotes escape nothing, so a backslash (a regexp's \d) reaches it as typed.
+  for (const [n, w] of quoted.entries()) {
+    const option = /^(--[A-Za-z][\w-]*=)([\s\S]*\s[\s\S]*)$/.exec(w);
+    if (n && option && !requote) quoted[n] = `${option[1]}${option[2].includes("'") ? JSON.stringify(option[2]) : `'${option[2]}'`}`;
+  }
   options.command = quoted.join(' ').trim();
   return options;
 }
@@ -107,7 +132,7 @@ 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(', ')}`);
+    console.log(`Error: ${helpText.notFound(topic)}`);
     process.exit(1);
   }
   console.log(text);

package/lib/cli-names.js

@@ -0,0 +1,282 @@
+// playwright-cli's command names, for agents who know that tool: each is
+// rewritten to the pw-repl command that does the same, or refused with the
+// nearest one. Names both tools share (goto, click, fill, snapshot, eval, ...)
+// are pw-repl's own commands already.
+
+const { unquote, splitSelector } = require('./syntax');
+
+// name -> [what pw-repl runs (from the arguments), how it is written here]
+const NAMES = {
+  'tab-list': [() => 'tab', 'tab'],
+  'tab-new': [a => `tab new ${a}`.trim(), 'tab new [url]'],
+  // By index only, unlike tab <number>, which falls back to a URL containing it.
+  '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]'],
+  // 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'],
+  'go-forward': [() => 'forward', 'forward'],
+  find: [a => `snapshot --grep ${a}`, 'snapshot --grep <text>'],
+  'dialog-accept': [a => `dialog accept ${a}`.trim(), 'dialog accept [text]'],
+  'dialog-dismiss': [() => 'dialog dismiss', 'dialog dismiss'],
+  resize: [a => { const [w, h] = a.split(/\s+/); return w && h ? `viewport ${w}x${h}` : null; }, 'viewport <w>x<h>'],
+  'cookie-list': [() => 'cookies', 'cookies'],
+  'localstorage-list': [() => 'storage', 'storage'],
+  'set-color-scheme': [a => (/^(dark|light)$/.test(a) ? `emulate ${a}` : null), 'emulate dark|light'],
+  'clear-color-scheme': [() => 'emulate dark off', 'emulate dark off'],
+  'network-state-set': [a => ({ offline: 'network off', online: 'network on' })[a] || null, 'network off|on'],
+  'route-list': [() => 'route', 'route'],
+  unroute: [a => (a ? `route off ${a}` : 'route off --all'), 'route off <glob>|--all'],
+  request: [a => `body ${a}`, 'body <#>, the response body only'],
+  'response-body': [a => `body ${a}`, 'body <#>'],
+};
+
+// Storage by eval: a key is the first word, quoted if it has spaces, and a value the rest.
+function storage(which, make) {
+  return a => {
+    const parsed = splitSelector(a);
+    return make(parsed && JSON.stringify(parsed.word), parsed?.rest !== undefined ? JSON.stringify(unquote(parsed.rest)) : null, which);
+  };
+}
+for (const which of ['localStorage', 'sessionStorage']) {
+  const cli = which.toLowerCase();
+  Object.assign(NAMES, {
+    // Anything after the key would be a key with spaces, unquoted: refused.
+    [`${cli}-get`]: [storage(which, (k, v) => k && !v && `eval ${which}.getItem(${k})`), `eval ${which}.getItem("<key>")`, `quote a key with spaces: ${cli}-get "my key"`],
+    [`${cli}-set`]: [storage(which, (k, v) => k && v && `eval ${which}.setItem(${k}, ${v}), "Set " + ${k}`), `eval ${which}.setItem("<key>", "<value>")`],
+    [`${cli}-delete`]: [storage(which, (k, v) => k && !v && `eval ${which}.removeItem(${k}), "Deleted " + ${k}`), `eval ${which}.removeItem("<key>")`, `quote a key with spaces: ${cli}-delete "my key"`],
+    [`${cli}-clear`]: [() => `eval ${which}.clear(), "Cleared ${which}"`, `eval ${which}.clear()`],
+  });
+}
+// Keys only, as storage lists localStorage's: values can be tokens.
+NAMES['sessionstorage-list'] = [() => 'eval Object.keys(sessionStorage)', 'eval Object.keys(sessionStorage)'];
+Object.assign(NAMES, {
+  'tracing-start': [() => 'capture on', 'capture on, which records requests and console messages together'],
+  'tracing-stop': [() => 'capture off', 'capture off, which prints what it recorded'],
+  'recording-start': [() => 'watch on', 'watch on, which records the steps taken in the tab (as steps, not code)'],
+  // Run as its steps (translate), since stopping and showing are two commands here.
+  'recording-stop': [() => 'watch off', 'watch off, then watch, which shows the steps'],
+});
+
+// Why a name has no counterpart here, and the nearest command if there is one.
+const NEAREST = {
+  'run-code': 'eval <JavaScript> runs in the page; cdp <method> <json> sends a CDP command',
+  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', highlight: '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',
+  mousewheel: 'not here yet; eval scrollBy(<dx>, <dy>) scrolls the page, without wheel events',
+  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',
+  'cookie-get': 'not here yet; cookies lists them without values, and cdp Network.getCookies {} shows the values',
+  'cookie-set': 'not here yet; cdp Network.setCookie {"name": ..., "value": ..., "url": ...} sets one',
+  'cookie-delete': 'not here yet; cdp Network.deleteCookies {"name": ..., "url": ...} deletes one',
+  show: 'not here; pw-repl attach, or the REPL\'s pane, shows everything the REPL does',
+  'close-all': 'not here on purpose: it would close a browser someone else may be using; close turns off your modes',
+  'kill-all': 'not here on purpose: it would kill a browser someone else may be using; pw-repl stop stops a REPL',
+  'delete-data': 'not here on purpose: it would wipe the data of a browser someone else may be using',
+  'cookie-clear': 'not here on purpose: it clears every site\'s cookies, in a browser someone else may be using',
+  'state-save': 'not here on purpose: it would save the sign-ins of someone else sharing the browser',
+  'state-load': 'not here on purpose: it would replace the sign-ins of someone else sharing the browser',
+  install: 'not needed here: pw-repl needs no workspace set up; pw-repl skill says how to use it',
+  'install-browser': 'not needed here: --launch uses Playwright\'s Chromium or one on the PATH (PW_CHROME)',
+};
+for (const name of ['mousemove', 'mousedown', 'mouseup']) NEAREST[name] = 'not here yet; click, dblclick and hover act on an element';
+for (const what of ['reduced-motion', 'forced-colors', 'contrast', 'media']) {
+  NEAREST[`set-${what}`] = 'not here yet; emulate dark|light sets the color scheme';
+  NEAREST[`clear-${what}`] = 'not here yet; emulate dark|light sets the color scheme';
+}
+for (const name of ['request-headers', 'response-headers', 'request-body']) NEAREST[name] = 'not here yet; body <#> shows the response body';
+for (const name of ['video-start', 'video-stop', 'video-chapter', 'video-show-actions', 'video-hide-actions']) {
+  NEAREST[name] = 'not here; screenshot saves an image, and watch on records each step';
+}
+for (const name of ['pause-at', 'resume', 'step-over']) NEAREST[name] = 'not here: they step through a Playwright test';
+
+const NAME_LIST = Object.keys(NAMES);
+
+// playwright-cli's options on the commands both tools have, and on those
+// rewritten here: flag (no value), value, or rest (the rest of the line up to
+// the next option, for a body with spaces). One this tool does not take is
+// refused, rather than read as part of a selector, a value or a file name.
+const OPTIONS = {
+  click: { modifiers: 'value' },
+  dblclick: { modifiers: 'value' },
+  fill: { submit: 'flag' },
+  type: { submit: 'flag' },
+  eval: { filename: 'value' },
+  find: { regex: 'rest' },
+  screenshot: { filename: 'value', type: 'value', 'full-page': 'flag', hires: 'flag' },
+  snapshot: { filename: 'value', depth: 'value', boxes: 'flag' },
+  console: { clear: 'flag' },
+  requests: { static: 'flag', filter: 'value', clear: 'flag' },
+  request: { filename: 'value' },
+  'response-body': { filename: 'value' },
+  route: { status: 'value', body: 'rest', 'content-type': 'value', header: 'value', 'remove-header': 'value' },
+  open: { browser: 'value', config: 'value', device: 'value', headed: 'flag', 'idle-timeout': 'value', mobile: 'flag', persistent: 'flag', profile: 'value' },
+  'cookie-list': { domain: 'value', path: 'value' },
+};
+
+// Options each command takes here; the rest of OPTIONS are refused.
+const TAKEN = {
+  route: ['status', 'body', 'content-type'],
+  fill: ['submit'],
+  screenshot: ['filename', 'full-page'],
+  open: ['mobile', 'device'],
+  click: ['modifiers'],
+  find: ['regex'],
+  requests: ['static', 'filter'],
+  dblclick: ['modifiers'],
+  type: ['submit'],
+};
+
+// What to do instead of an option that is refused, where there is something.
+const INSTEAD = {
+  'snapshot --depth': 'snapshot <ref> outlines one element, and snapshot --grep <text> finds lines',
+  'snapshot --filename': 'the snapshot is printed; pw-repl send ... > file saves it',
+  'eval --filename': 'the result is printed; pw-repl send ... > file saves it',
+  'request --filename': 'the body is printed; pw-repl send ... > file saves it',
+  'response-body --filename': 'the body is printed; pw-repl send ... > file saves it',
+  'screenshot --hires': 'screenshots are at CSS pixel size',
+  'route --header': 'route <glob> patch <json> changes a JSON response',
+  'route --remove-header': 'route <glob> patch <json> changes a JSON response',
+  'cookie-list --domain': 'cookies lists them all',
+  'cookie-list --path': 'cookies lists them all',
+};
+for (const option of ['browser', 'config', 'headed', 'idle-timeout', 'persistent', 'profile']) {
+  INSTEAD[`open --${option}`] = 'the REPL uses the browser it connected to; pw-repl serve --launch [--headed] starts one of its own';
+}
+
+// A word, where quoted parts may hold spaces: --device="iPhone 15".
+const TOKEN = /(?:"(?:[^"\\]|\\.)*"|'[^']*'|[^\s"']+|["'])+/g;
+
+// The options of spec found in args, and the line without them.
+function takeOptions(args, spec) {
+  const tokens = [...args.matchAll(TOKEN)].map(m => ({ text: m[0], start: m.index, end: m.index + m[0].length }));
+  const optionAt = i => {
+    const match = /^--([A-Za-z][\w-]*)(?:=([\s\S]*))?$/.exec(tokens[i]?.text || '');
+    return match && Object.hasOwn(spec, match[1]) ? { name: match[1], value: match[2] } : null;
+  };
+  const found = [];
+  const cuts = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const option = optionAt(i);
+    if (!option) continue;
+    const start = tokens[i].start;
+    let end = tokens[i].end;
+    let { value } = option;
+    if (spec[option.name] === 'rest') {
+      let next = i + 1;
+      while (next < tokens.length && !optionAt(next)) next++;
+      end = next < tokens.length ? tokens[next].start : args.length;
+      value = args.slice(value === undefined ? tokens[i].end : start + option.name.length + 3, end).trim() || undefined;
+      i = next - 1;
+    } else if (spec[option.name] === 'value' && value === undefined && tokens[i + 1] && !tokens[i + 1].text.startsWith('--')) {
+      value = tokens[++i].text;
+      end = tokens[i].end;
+    }
+    // raw keeps a value as typed, quotes and backslashes and all, for a regexp.
+    found.push({ name: option.name, value: value === undefined ? undefined : unquote(value), raw: value });
+    cuts.push([start, end]);
+  }
+  let rest = '';
+  let at = 0;
+  for (const [start, end] of cuts) { rest += `${args.slice(at, start).trim()} `; at = end; }
+  rest += args.slice(at).trim();
+  return { found, rest: rest.trim() };
+}
+
+// { text } to run instead, { refuse } to explain, or null for any other command.
+function translate(text) {
+  const match = /^(\S+)(?:\s+([\s\S]*))?$/.exec(text.trim());
+  if (!match) return null;
+  const [, name, rest = ''] = match;
+  const args = rest.trim();
+  if (Object.hasOwn(OPTIONS, name)) {
+    const { found, rest: positional } = takeOptions(args, OPTIONS[name]);
+    // route <glob> <how> ... is this tool's own, and its body is free text.
+    if (name === 'route' && (positional.match(TOKEN) || []).length > 1) return null;
+    const refused = found.find(o => !(TAKEN[name] || []).includes(o.name));
+    if (refused) {
+      const instead = INSTEAD[`${name} --${refused.name}`];
+      return { refuse: `playwright-cli's ${name} --${refused.name} is not supported here${instead ? `; ${instead}` : ''}` };
+    }
+  }
+  // route <pattern> [--status=<code>] [--body=<text>] [--content-type=<type>] is how
+  // playwright-cli fakes a response; the status is 200 unless given, and a body
+  // that is not JSON is text unless its type is given.
+  if (name === 'route' && /(?:^|\s)--(?:status|body|content-type)(?:[=\s]|$)/.test(args)) {
+    const { found, rest: glob } = takeOptions(args, OPTIONS.route);
+    // route <glob> <status> --content-type=<type> <body> is this tool's own.
+    if (/\s/.test(unquote(glob))) return null;
+    const option = key => found.find(o => o.name === key)?.value;
+    const status = option('status') ?? '200';
+    const body = option('body') ?? '';
+    if (!/^\d{3}$/.test(status) || !glob) return { refuse: 'Usage: route <pattern> [--status=<code>] [--body=<text>] [--content-type=<type>]' };
+    let json = true;
+    try { if (body) JSON.parse(body); } catch { json = false; }
+    const type = option('content-type') ?? (json ? null : 'text/plain');
+    const typeWord = type && /\s/.test(type) ? JSON.stringify(type) : type;
+    return { text: `route ${unquote(glob)} ${status}${type ? ` --content-type=${typeWord}` : ''}${body ? ` ${body}` : ''}`, as: 'route <glob> <status> [--content-type=<type>] [body]' };
+  }
+  if (name === 'recording-stop' && !args) return { steps: ['watch off', 'watch'], as: NAMES[name][1] };
+  // find --regex takes a regular expression, as snapshot --regex does; requests --filter
+  // takes one too, as requests --regex does, and --static is --all.
+  if (name === 'find' && /(?:^|\s)--regex(?:[=\s]|$)/.test(args)) {
+    // As typed: snapshot --regex takes off the quotes and leaves its backslashes.
+    const regex = takeOptions(args, OPTIONS.find).found[0].raw;
+    return regex ? { text: `snapshot --regex ${regex}`, as: 'snapshot --regex <pattern>', key: 'find --regex' } : { refuse: 'Usage: find --regex <pattern>' };
+  }
+  if (name === 'requests' && /(?:^|\s)--(?:static|filter)(?:[=\s]|$)/.test(args)) {
+    const { found, rest } = takeOptions(args, OPTIONS.requests);
+    const filter = found.find(o => o.name === 'filter');
+    if (filter && !filter.value) return { refuse: 'Usage: requests --filter=<regexp>' };
+    const all = found.some(o => o.name === 'static');
+    // As typed: requests --regex takes off the quotes and leaves its backslashes.
+    const text = ['requests', all && '--all', rest, filter && `--regex ${filter.raw}`].filter(Boolean).join(' ');
+    return filter ? { text, as: 'requests --regex <pattern>', key: 'requests --filter' } : { text, as: 'requests --all', key: 'requests --static' };
+  }
+  // open [url] [--mobile | --device=<name>]: the emulation is set before the page loads.
+  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 && !device.value) return { refuse: 'Usage: open [url] [--mobile | --device=<name>]' };
+    return {
+      steps: ['tab new', `emulate mobile${device ? ` ${device.value}` : ''}`, ...(url ? [`goto ${url}`] : [])],
+      as: 'tab new, emulate mobile [device], then goto <url>',
+      failed: 'The new tab stays open and selected; tab close closes it.',
+    };
+  }
+  if (Object.hasOwn(NAMES, name)) {
+    const [make, as, hint] = NAMES[name];
+    const made = make(args);
+    return made ? { text: made, as } : { refuse: `${name} ${args}`.trim() + ` is not understood here; the command for it is ${as}${args && hint ? `; ${hint}` : ''}` };
+  }
+  if (Object.hasOwn(NEAREST, name)) return { refuse: `${name} is playwright-cli's${/^not /.test(NEAREST[name]) ? ` and ${NEAREST[name]}` : `; here, ${NEAREST[name]}`}` };
+  return null;
+}
+
+// Words filled into lines of up to width, each after the first indented.
+function wrap(text, width = 104, indent = '      ') {
+  const lines = [];
+  let line = '';
+  for (const word of text.split(' ')) {
+    if (line && `${line} ${word}`.length > width) { lines.push(line); line = `${indent}${word}`; } else line = line ? `${line} ${word}` : word;
+  }
+  return [...lines, line].join('\n');
+}
+
+// For help playwright-cli: names with the same reason are listed together.
+function table() {
+  const width = Math.max(...NAME_LIST.map(n => n.length));
+  const lines = NAME_LIST.map(n => `  ${n.padEnd(width)}  ${NAMES[n][1]}`);
+  const byReason = new Map();
+  for (const [name, why] of Object.entries(NEAREST)) byReason.set(why, [...(byReason.get(why) || []), name]);
+  const nearest = [...byReason].map(([why, names]) => `  ${wrap(`${names.join(', ')}: ${why}`)}`);
+  return [...lines, '', 'Not here as such:', ...nearest].join('\n');
+}
+
+module.exports = { translate, table, takeOptions, NAME_LIST };

package/lib/client.js

@@ -56,9 +56,9 @@ async function health(endpoint, timeoutMs) {
 // 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) {
+function request(endpoint, command, timeoutMs, client = null) {
   return new Promise(resolve => {
-    const body = JSON.stringify({ command });
+    const body = JSON.stringify(client ? { command, client } : { command });
     let connected = false;
     const req = http.request({
       ...target(endpoint),