pw-repl 0.12.6 → 0.12.8

package/lib/runner.js

@@ -38,6 +38,8 @@ const NO_TAB_NEEDED = new Set(['tab', 'modes', 'capture', 'profile', 'record', '
 // Commands that accept --all, right after the command or at the end, to lift the output limit.
 const INSPECTION = ['info', 'listeners', 'text', 'html', 'attrs', 'links', 'inputs', 'eval', 'cdp', 'cookies', 'storage', 'capture', 'profile', 'body', 'console', 'snapshot', 'watch'];
 
+const SUBCOMMANDS = ['run', 'serve', 'attach', 'stop', 'send', 'where', 'skill'];
+
 let queue = Promise.resolve();
 // The server command running now, so a quit at the prompt can answer it.
 let inFlight = null;
@@ -100,6 +102,11 @@ async function executeCommand(text) {
   state.currentCommandAt = Date.now();
   const run = Object.hasOwn(commands, cmd) ? commands[cmd] : translated && Object.hasOwn(cliCommands, cmd) ? cliCommands[cmd] : null;
   if (!run) {
+    // An agent fresh from the skill tries send where; those are the command line's, not the REPL's.
+    if (SUBCOMMANDS.includes(cmd)) {
+      out.error(`Error: ${cmd} is a pw-repl subcommand, run at the shell: pw-repl ${cmd}${args ? ' ...' : ''}`);
+      return { status: 'error', cmd };
+    }
     out.log(`Unknown command: ${cmd}. Type 'help' for commands.`);
     return { status: 'error', cmd };
   }
@@ -117,6 +124,10 @@ async function executeCommand(text) {
     stepEnded(step, true);
     // Playwright colours its call log; the codes are noise anywhere but a terminal.
     e.message = String(e.message || '').replace(/\x1b\[[0-9;]*m/g, '');
+    // A page's own error (eval's SyntaxError, a cdp method not found) without Playwright's method name
+    // or the stack of its injected script, which point at Playwright, not at the line that was sent.
+    e.message = e.message.split('\n').filter(line => !/^\s+at /.test(line)).join('\n')
+      .replace(/^(?:page|frame|elementHandle|jsHandle|cdpSession)\.(?:evaluate|evaluateHandle|send): /, '');
     out.error(`Error: ${e.message}`);
     const uncertain = !READ_ONLY.has(cmd) && isUncertain(e);
     if (uncertain) out.error('Outcome unknown: it timed out after it began acting on the page. Check the page before trying again.');

package/lib/send.js

@@ -88,6 +88,11 @@ async function viaTmux(session, command, timeoutMs) {
   return 2;
 }
 
+// A word in double quotes, as the REPL reads them (unescapeDouble): every other character goes as it is.
+function doubleQuote(word) {
+  return `"${word.replace(/[\\"]/g, '\\$&').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t')}"`;
+}
+
 // A command's words as send was given them, made into the line the REPL reads: quoted again where the
 // shell had kept a word whole, and with the files it reads or writes made absolute from the sender's
 // folder, since the REPL's may be another.
@@ -100,7 +105,7 @@ function commandLine(words) {
   // So does playwright-cli's storage key (localstorage-set "my key" v).
   // And record's file, which may have spaces in it, and wait's text, whose last word would otherwise be
   // taken as the seconds when it is a number (wait text 'Showing 1').
-  const requote = words.length > 1 && (SELECTOR_FIRST.has(words[0]) || /^(?:local|session)storage-/.test(words[0]) || words[0] === 'record' || words[0] === 'wait' || /^video-(?:start|stop)$/.test(words[0]));
+  const requote = words.length > 1 && (SELECTOR_FIRST.has(words[0]) || words[0] === 'drag' || /^(?:local|session)storage-/.test(words[0]) || words[0] === 'record' || words[0] === 'wait' || /^video-(?:start|stop)$/.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.
   // So are the files upload reads and screenshot --filename writes.
@@ -117,15 +122,21 @@ function commandLine(words) {
   // watch save and profile save write their files.
   if (words[0] === 'profile' && words[1] === 'save' && words.length > 2) resolved = ['profile', 'save', resolve(words.slice(2).join(' '))];
   if (words[0] === 'watch' && words[1] === 'save' && words.length > 2) resolved = ['watch', 'save', resolve(words.slice(2).join(' '))];
+  // So does the file eval --file reads.
+  if (words[0] === 'eval' && /^--file(?:=|$)/.test(words[1] || '')) {
+    // As one word, --file=<path>, which is quoted below when the path has spaces.
+    const [file, rest] = words[1] === '--file' ? [words[2], words.slice(3)] : [words[1].slice(7), words.slice(2)];
+    if (file) resolved = ['eval', `--file=${resolve(file)}`, ...rest];
+  }
   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;
+  const quoted = requote ? resolved.map(w => (w === '' || /[\s"']/.test(w) ? doubleQuote(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]}'`}`;
+    if (n && option && !requote) quoted[n] = `${option[1]}${option[2].includes("'") ? doubleQuote(option[2]) : `'${option[2]}'`}`;
   }
   return quoted.join(' ').trim();
 }
@@ -155,7 +166,8 @@ async function sendFile(options) {
     console.log(`> ${line}`);
     // Read as the prompt reads it; a file it reads or writes is the sender's, as on send's command line.
     const words = shellWords(line);
-    const command = PATHS.test(words[0]) ? commandLine(words) : line;
+    // eval's own line keeps its quotes; only eval --file names a file.
+    const command = PATHS.test(words[0]) || (words[0] === 'eval' && /^--file(?:=|$)/.test(words[1] || '')) ? commandLine(words) : line;
     const found = options.noVars ? null : variablesFor(command);
     if (found?.error) { console.error(`pw-repl: stopped at line ${i + 1} of ${options.file} (${line}): ${found.error}`); return 1; }
     const status = await send({ ...options, file: null, command, vars: found?.vars || null });

package/lib/start.js

@@ -5,6 +5,7 @@ const { state, withTimeout, shutdown, onBeforeExit, beforeExit } = require('./st
 const out = require('./output');
 const { watchPage, complete } = require('./commands');
 const { listTabs, openTab, markStartTab } = require('./tabs');
+const { tabState } = require('./tabstate');
 const runner = require('./runner');
 
 // A browser --launch starts has its own address instead.
@@ -88,10 +89,14 @@ async function start(options) {
 
   if (START_URL) {
     state.startingStep = 'opening the start URL';
-    state.page = await openTab();
+    // A Chromium the REPL launched has only its first blank tab, which nobody else is using: the start
+    // URL goes there, rather than into a second tab behind a blank one.
+    const first = state.launched && pages.length === 1 && pages[0].url() === 'about:blank' ? pages[0] : null;
+    if (first) Object.assign(tabState(first), { opened: true, owner: state.client });
+    state.page = first || await openTab();
     markStartTab(state.page);
     await state.page.goto(START_URL, { waitUntil: 'networkidle', timeout: 15000 });
-    out.log(`Opened ${state.page.url()} in a new tab`);
+    out.log(`Opened ${state.page.url()}${first ? '' : ' in a new tab'}`);
   }
 
   out.log('');
@@ -148,7 +153,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/lib/syntax.js

@@ -11,25 +11,31 @@ function toSelector(word) {
   return REF.test(word) ? `aria-ref=${word}` : word;
 }
 
-// Quotes around the whole of a value are removed; \" inside double quotes is a quote.
+// Inside double quotes, \n, \t and \r are a newline, tab and carriage return, so a value send quotes
+// keeps them on one line; any other \X is X (\" a quote, \\ a backslash).
+function unescapeDouble(text) {
+  return text.replace(/\\(.)/g, (_, c) => (c === 'n' ? '\n' : c === 't' ? '\t' : c === 'r' ? '\r' : c));
+}
+
+// Quotes around the whole of a value are removed.
 function unquote(text) {
   const match = /^"((?:[^"\\]|\\.)*)"$|^'([^']*)'$/.exec(text);
   if (!match) return text;
-  return match[1] !== undefined ? match[1].replace(/\\(.)/g, '$1') : match[2];
+  return match[1] !== undefined ? unescapeDouble(match[1]) : match[2];
 }
 
 // The words of a line as a shell reads them: quoted parts may hold spaces, and lose their quotes
 // (--filename="my dir/a.webm" is one word, --filename=my dir/a.webm).
 function shellWords(text) {
   return [...(text || '').matchAll(/(?:"(?:[^"\\]|\\.)*"|'[^']*'|[^\s"']+|["'])+/g)]
-    .map(m => m[0].replace(/"((?:[^"\\]|\\.)*)"|'([^']*)'/g, (_, double, single) => (double !== undefined ? double.replace(/\\(.)/g, '$1') : single)));
+    .map(m => m[0].replace(/"((?:[^"\\]|\\.)*)"|'([^']*)'/g, (_, double, single) => (double !== undefined ? unescapeDouble(double) : single)));
 }
 
 // The first word of args, or a quoted selector with spaces in it, and the rest of the line.
 function splitSelector(args) {
   const match = /^(?:"((?:[^"\\]|\\.)*)"|'([^']*)'|(\S+))(?:\s+([\s\S]*))?$/.exec((args || '').trim());
   if (!match) return null;
-  const word = match[1] !== undefined ? match[1].replace(/\\(.)/g, '$1') : match[2] !== undefined ? match[2] : match[3];
+  const word = match[1] !== undefined ? unescapeDouble(match[1]) : match[2] !== undefined ? match[2] : match[3];
   return { word, selector: toSelector(word), rest: match[4] };
 }
 
@@ -83,4 +89,4 @@ function expandVariables(line, values) {
   });
 }
 
-module.exports = { SELECTOR_FIRST, REF, toSelector, unquote, shellWords, splitSelector, keyName, variablesIn, expandVariables };
+module.exports = { SELECTOR_FIRST, REF, toSelector, unescapeDouble, unquote, shellWords, splitSelector, keyName, variablesIn, expandVariables };

package/package.json

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

package/skill/SKILL.md

@@ -43,7 +43,8 @@ and check the skill it names against the top of this file. It says whether a REP
 `send` reaches it, or that one is still starting (retry shortly; it exits 64 until the REPL serves, as
 when none is running). Right after you start one, for a moment before its process is up, it can still
 say none is there: retry for a few seconds before taking that as a failed start. There are three ways to
-run one; each takes an optional start URL, which opens in a new tab.
+run one; each takes an optional start URL, which opens in a new tab (with `--launch`, in its browser's
+first tab).
 
 - `pw-repl serve --background` runs it detached, with a command server on `/tmp/pw-repl.sock`
   (owner-only) and its output in `/tmp/pw-repl.log`. `pw-repl attach` shows everything it does and
@@ -52,14 +53,14 @@ run one; each takes an optional start URL, which opens in a new tab.
 - `pw-repl serve` runs the same in a terminal, where the pane shows every command. Its prompt is
   `pw[serve]>`. It stops at that prompt (`quit`, or Ctrl-C); `pw-repl stop` is for a background one.
 - 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.
+  own instead of connecting to one: headless unless `--headed`, in a 1280x800 window, 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 (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 +113,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
@@ -135,9 +137,10 @@ line, not in it; the REPL puts it in only as it runs the line, and its pane and
 written, so neither the file nor the line as logged holds the secret. Only `PW_` names are variables;
 any other `{{ ... }}` (a page's template text) is sent as written. One that is not set stops the file;
 `--no-vars` sends it as written. A single `send` takes them too: `PW_PASSWORD=... pw-repl send fill
-'#password' "{{ PW_PASSWORD }}"` types a password without it in the command. What reads it back can
-still show it: `snapshot`, `html` and `attrs` hide a password field's value, `eval` on the field does
-not.
+'#password' "{{ PW_PASSWORD }}"` types a password without it in the command. Give the value without
+typing it, from a file only you can read: `PW_PASSWORD="$(cat <file>)" pw-repl send ...`. What reads it
+back can still show it: `snapshot`, `html` and `attrs` hide a password field's value, `eval` on the
+field does not.
 
 `send` takes one command; chain several in your shell. Use `&&` when a step only makes sense if the one
 before it worked: it stops at any exit status but 0, a failure and an outcome not confirmed included.
@@ -160,40 +163,24 @@ background REPL (server commands as `[server]` lines), so whoever looks there se
 shows REPL commands only, not what was clicked in the browser (unless `watch on --live` is on); for
 that, look at the browser itself: `tab` and `info` for where things are, `requests` for the requests the
 clicks made (`body <#>` for what one returned), `console` for console messages and page errors.
-`watch on` records each step someone takes in a tab, with the requests it caused (`watch on --changes`
-adds what each step changed on the page); `watch` reads it back, and `watch new` only what it has not
-shown yet. For a tab they have not opened yet, `watch on --next-tab [url-part]` waits for it and
-watches it from its first page. `watch save <file>` writes the steps as commands that `send --file`
-runs again, a repro to keep. What is typed is recorded, except in password fields; `watch on
---no-values` leaves it out. The file has a `{{ PW_PASSWORD }}` variable where a password was typed,
-set when it runs (`PW_PASSWORD=... pw-repl send --file login.txt`), so the file can be shared without
-it.
-
-When watching someone:
-
-- A watched tab keeps response bodies of up to 100 KB, so `body <#>` still has them after the tab
-  navigates. Read a bigger one that matters as soon as it shows up in `requests`: the browser drops it
-  once the tab navigates.
-- `watch` leaves out images and other static files, failed ones too; `console error` and
-  `requests --all` show what failed.
-- Without a url-part, `--next-tab` takes the first tab anyone opens; check `tab` and `info` once it
-  fires, since another tab opening later does not show in `watch`.
-- A watch belongs to the tab: when another client watches it too, read it with `watch <n>`, since
-  `watch new`'s place is shared and each one's would hide steps from the other.
+`watch on` records each step someone takes in a tab, with the requests it caused; `watch` reads it back,
+and `watch save <file>` writes the steps as commands that `send --file` runs again, a repro to keep.
+Before you watch someone, read `help watch`: what it keeps and leaves out, passwords, and sharing a watch
+with another client.
 
 When a page is slow or feels laggy, `requests` shows a slow response; for what the page itself is busy
-with, `profile on` and `profile off` around what you do, or while the user uses it, sum up a performance
-trace of the tab: long tasks and the function behind each, forced layouts, each click's time to the next
-paint, and frames dropped while scrolling or dragging. `profile reload` profiles a load. `help profile`.
+with, `profile on` and `profile off` around what you do, or while the user uses it (`help profile`).
 
 Exit status: `0` ok, `1` the command failed, `2` completion not confirmed (outcome unknown: do not
-blindly retry a change), `64` usage or the REPL is not reachable. `pw-repl --help` has the options.
+blindly retry a change), `64` usage or the REPL is not reachable. `pw-repl --help` has the options, and
+`pw-repl send --help` the rest of send's.
 
 ## Learn the commands
 
 Run `pw-repl send help`. It lists seven topics; `help <topic>` lists their commands, `help <command>`
-gives usage and caveats: read it before you use a command, since this file does not repeat them. `help
---all` prints everything at once. pw-repl answers help itself: it needs no running REPL, and never
+gives usage and caveats: read it before you use a command, since this file does not repeat them. When a
+command fails or does something you did not expect, read its `help <command>` before working around it.
+`help --all` prints everything at once. pw-repl answers help itself: it needs no running REPL, and never
 reaches one. If you know playwright-cli, its command names work too (`help playwright-cli` lists them).
 
 ### Coming from playwright-cli
@@ -209,8 +196,9 @@ pw-repl send -c <name> click e5
 pw-repl send -c <name> close                        # your modes off; tab close <url-part> closes yours
 ```
 
-- There is no browser of your own to open or close: `open` opens a tab in the one the REPL uses, and
-  `close` turns off the modes you turned on and leaves every tab open.
+- There is no browser of your own to open or close: `open` opens a new tab in the one the REPL uses,
+  each time, so use it once and `goto <url>` after that, which navigates the selected tab. `close` turns
+  off the modes you turned on and leaves every tab open.
 - Instead of `-s=<session>`, send as a client: `-c <name>`, with a selected tab of its own, in a browser
   whose cookies and storage are shared.
 - `upload <selector> <file>` names the file input or the button that opens it; do not click a file