pw-repl 0.12.8 → 0.13.0

package/lib/send.js

@@ -93,6 +93,15 @@ function doubleQuote(word) {
   return `"${word.replace(/[\\"]/g, '\\$&').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t')}"`;
 }
 
+// Where eval's --file is, after its --timeout if it has one; -1 when it has none.
+function evalFileAt(words) {
+  if (words[0] !== 'eval') return -1;
+  let at = 1;
+  if (/^--timeout=/.test(words[at] || '')) at += 1;
+  else if (words[at] === '--timeout') at += 2;
+  return /^--file(?:=|$)/.test(words[at] || '') ? at : -1;
+}
+
 // 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.
@@ -104,7 +113,7 @@ function commandLine(words) {
   const { SELECTOR_FIRST } = require('./syntax');
   // 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').
+  // taken as the time when it is a number (wait text 'Showing 1').
   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.
@@ -123,10 +132,11 @@ function commandLine(words) {
   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] || '')) {
+  const at = evalFileAt(words);
+  if (at > 0) {
     // 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];
+    const [file, rest] = words[at] === '--file' ? [words[at + 1], words.slice(at + 2)] : [words[at].slice(7), words.slice(at + 1)];
+    if (file) resolved = [...words.slice(0, at), `--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));
@@ -167,7 +177,7 @@ async function sendFile(options) {
     // 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);
     // 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 command = PATHS.test(words[0]) || evalFileAt(words) > 0 ? 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 });
@@ -194,7 +204,7 @@ async function send(options) {
     if (found?.error) return fail(found.error);
     options = { ...options, vars: found?.vars || null };
   }
-  const timeoutMs = options.timeout * 1000;
+  const timeoutMs = options.timeout;
   const way = route(options);
   const name = options.client || process.env.PW_CLIENT || null;
   if (name && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$/.test(name)) return fail('a client name is 1-40 letters, digits, dots, dashes and underscores');

package/lib/server.js

@@ -56,7 +56,10 @@ function handle(req, res) {
     }
     // Bound before the browser is reached, so where and send find it while it starts.
     if (!state.serving) return send(res, 503, { status: 'error', starting: true, output: `The REPL is starting (${state.startingStep}); retry shortly` });
-    const result = await runner.submit(command.trim(), client || null, vars || null);
+    // The sender gave up (send -t) once its connection closes before the answer is written.
+    const gone = new AbortController();
+    res.once('close', () => { if (!res.writableEnded) gone.abort(); });
+    const result = await runner.submit(command.trim(), client || null, vars || null, gone.signal);
     if (!result.uncertain) return send(res, 200, { status: result.status, output: result.output });
     // unconfirmed: the command may or may not have done what it was sent to do.
     send(res, 200, { status: result.status, output: result.output, unconfirmed: true });

package/lib/state.js

@@ -1,14 +1,12 @@
 // Session state shared by the entry point, the runner, and the commands, plus
 // the shutdown that ends the session.
+const { AsyncLocalStorage } = require('async_hooks');
 const out = require('./output');
 
 const SHUTDOWN_TIMEOUT = 5000;
 
 const state = {
   browser: null,
-  // The client whose command runs now: null for the prompt and senders without
-  // a name, who share one selected tab, as before clients had names.
-  client: null,
   rl: null,
   promptBase: 'pw> ',
   // The browser the REPL is connected to, and whether --launch started it.
@@ -36,18 +34,31 @@ function clientRecord(name = state.client) {
   return clients.get(name);
 }
 
+// The command running in this async context: its client, and whether its sender gave up on it.
+// Code outside any command (a browser event, quit and dialog, which skip the queue) goes by the
+// queued command running now.
+const running = new AsyncLocalStorage();
+let queued = null;
+
+// The client whose command runs now: null for the prompt and senders without a name, who share one
+// selected tab, as before clients had names. Each command keeps its own for its whole life, so one
+// its sender gave up on, still running, never acts as the command after it.
+Object.defineProperty(state, 'client', { enumerable: true, get: () => (running.getStore() ?? queued)?.client ?? null });
+
+out.onCancelled(() => running.getStore()?.cancelled === true);
+
 for (const key of Object.keys(PER_CLIENT)) {
   Object.defineProperty(state, key, { enumerable: true, get: () => clientRecord()[key], set: value => { clientRecord()[key] = value; } });
 }
 
-// Runs fn as the named client. Commands run one at a time, so this is safe.
-async function asClient(name, fn) {
-  const previous = state.client;
-  state.client = name || null;
-  try { return await fn(); } finally { state.client = previous; }
+// Runs fn as the named client. run is the command's record, whose cancelled the runner sets.
+async function asClient(name, fn, run = {}) {
+  queued = Object.assign(run, { client: name || null });
+  try { return await running.run(run, fn); } finally { if (queued === run) queued = null; }
 }
 
 const cleanups = [];
+const endings = [];
 const exitWaits = [];
 let shutdownPromise = null;
 
@@ -65,6 +76,11 @@ function onShutdown(fn) {
   cleanups.push(fn);
 }
 
+// Run once every cleanup has finished, before the browser is closed.
+function onShutdownEnd(fn) {
+  endings.push(fn);
+}
+
 // Things to finish before the process exits, e.g. answers still being sent.
 function onBeforeExit(fn) {
   exitWaits.push(fn);
@@ -80,6 +96,7 @@ async function shutdown() {
   shutdownPromise = (async () => {
     // Some undo what the REPL changed in the browser, so they finish first.
     await withTimeout(Promise.all(cleanups.map(async fn => fn())), 'Cleanup').catch(() => {});
+    for (const fn of endings) try { await fn(); } catch {}
     if (state.browser) {
       try { await withTimeout(state.browser.close(), 'Chromium shutdown'); }
       catch (error) { state.shutdownFailed = true; process.exitCode = 1; out.error(`Could not confirm Chromium shutdown: ${error.message}`); }
@@ -88,4 +105,4 @@ async function shutdown() {
   return shutdownPromise;
 }
 
-module.exports = { state, clientRecord, asClient, withTimeout, onShutdown, onBeforeExit, beforeExit, shutdown, SHUTDOWN_TIMEOUT };
+module.exports = { state, clientRecord, asClient, withTimeout, onShutdown, onShutdownEnd, onBeforeExit, beforeExit, shutdown, SHUTDOWN_TIMEOUT };

package/lib/toast.js

@@ -7,6 +7,7 @@ const { unquote } = require('./syntax');
 const { takeOptions } = require('./cli-names');
 const { inOverlay, keepAcrossPages, forget } = require('./overlay');
 const { recordingOf, beforeRecordingEnds } = require('./record');
+const { parseDuration } = require('./util');
 
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
 
@@ -81,12 +82,6 @@ async function toastOff(p, fade = true) {
 beforeRecordingEnds(p => (p && !p.isClosed() ? waitToRead(p) : null));
 
 // 3s, 1.5s, 800ms, or a number of milliseconds.
-function parseDuration(value) {
-  const match = /^(\d+(?:\.\d+)?)(ms|s)?$/.exec(value || '');
-  if (!match) return null;
-  return Math.round(Number(match[1]) * (match[2] === 's' ? 1000 : 1));
-}
-
 onShutdown(async () => {
   if (!state.browser || state.connectionLost) return;
   const pages = state.browser.contexts().flatMap(c => c.pages()).filter(p => !p.isClosed());

package/lib/util.js

@@ -20,6 +20,28 @@ function hints(pairs) {
   return `\n${pairs.map(([command, what]) => `  ${command.padEnd(width)}  ${what}`).join('\n')}`;
 }
 
+// A time: milliseconds, as Playwright and JavaScript count it, or seconds with an s (1500, 1.5s, 1500ms).
+const TIME = /^(\d+(?:\.\d+)?)(ms|s)?$/;
+
+function parseDuration(value) {
+  const match = TIME.exec(value || '');
+  if (!match) return null;
+  return Math.round(Number(match[1]) * (match[2] === 's' ? 1000 : 1));
+}
+
+// How a time reads back: 1.5s, or 250ms under a second.
+function durationText(ms) {
+  return ms >= 1000 ? `${Number((ms / 1000).toFixed(3))}s` : `${ms}ms`;
+}
+
+// A time that is a second or more, where a smaller one is most likely seconds written as before.
+function longDuration(value, what) {
+  const ms = parseDuration(value);
+  if (ms === null) throw new Error(`${what} is a time, in milliseconds or with s for seconds: 30000 or 30s (got ${value})`);
+  if (ms < 1000) throw new Error(`${what} is in milliseconds, 1000 or more: ${value} is ${durationText(ms)}; ${value}s for seconds`);
+  return ms;
+}
+
 function clipText(text) {
   return text.length > MAX_EVENT_TEXT ? `${text.slice(0, MAX_EVENT_TEXT)}…` : text;
 }
@@ -56,6 +78,8 @@ function clock(t) {
 // by itself unseen: stop prints those lines.
 const STOPPED_RECORDING = 'The REPL stopped, which ended a recording';
 const ENDED_UNSEEN = 'A recording ended before the REPL stopped, unseen since';
+// Each line stop prints of the files a client left.
+const FILES_LEFT = 'Files left';
 
 // Where Playwright installs its browsers and ffmpeg, worked out as playwright-core does it: a cache of
 // each platform's own (~/Library/Caches on macOS), unless PLAYWRIGHT_BROWSERS_PATH says otherwise.
@@ -69,4 +93,4 @@ function playwrightBrowsersDir() {
   return path.join(cache, 'ms-playwright');
 }
 
-module.exports = { BUSY_PAGE, STOPPED_RECORDING, ENDED_UNSEEN, COMMAND_TIMEOUT, MAX_EVENT_TEXT, NO_TAB, hints, clipText, numbers, regexOf, patternText, clock, playwrightBrowsersDir };
+module.exports = { TIME, parseDuration, durationText, longDuration, BUSY_PAGE, STOPPED_RECORDING, ENDED_UNSEEN, FILES_LEFT, COMMAND_TIMEOUT, MAX_EVENT_TEXT, NO_TAB, hints, clipText, numbers, regexOf, patternText, clock, playwrightBrowsersDir };

package/lib/watch.js

@@ -4,6 +4,7 @@ const out = require('./output');
 const { printOutput } = out;
 const fs = require('fs');
 const path = require('path');
+const { noteWritten } = require('./written');
 const { clipText, clock, hints, NO_TAB } = require('./util');
 const { tabState } = require('./tabstate');
 const { keptSession, keepDrawing } = require('./cdp');
@@ -22,8 +23,8 @@ const PW_SETTINGS = ['PW_CDP_URL', 'PW_CHROME', 'PW_CLIENT', 'PW_ENDPOINT', 'PW_
   'PW_SOCKET', 'PW_START_URL', 'PW_TEST_CHROME', 'PW_TMUX_SESSION'];
 const PAGE_ACTIONS = new Set(['click', 'check', 'uncheck', 'select', 'fill', 'type', 'press', 'submit']);
 const WATCH_BINDING = '__pwReplWatch';
-// Seconds a saved step waits for its element after the app's own routing (watch save).
-const ROUTE_WAIT = 30;
+// How long a saved step waits for its element after the app's own routing (watch save).
+const ROUTE_WAIT = '30s';
 
 // Runs in the page. Describes elements the way snapshot does: role and name.
 const WATCH_SCRIPT = `(() => {
@@ -811,6 +812,7 @@ const commands = {
       if (variables.length) header.push(`# It needs ${variables.join(', ')} set in the environment: what was typed into ${where}, not saved here`);
       // It holds what was typed, so it is the user's own to read.
       fs.writeFileSync(file, `${[...header, ...lines].join('\n')}\n`, { mode: 0o600, flag: 'wx' });
+      noteWritten(file, 'watch file');
       out.log(`Saved ${watch.events.length} step${watch.events.length === 1 ? '' : 's'} to ${file}${skipped ? `; ${skipped} could not be written as commands, and are comments there saying why` : ''}.`);
       if (variables.length) out.log(`What was typed into ${where} is a variable there, filled in from the environment: ${variables.map(name => `{{ ${name} }}`).join(', ')}.`);
       out.log(`${variables.map(name => `${name}=... `).join('')}pw-repl send --file ${file} runs them.`);

package/lib/written.js

@@ -0,0 +1,67 @@
+// The files the REPL wrote this session, and for whom, so close and stop can say which are still
+// there to clean up. Kept in memory only, and nothing is removed.
+const fs = require('fs');
+const path = require('path');
+const { state, onShutdownEnd } = require('./state');
+const out = require('./output');
+const { FILES_LEFT } = require('./util');
+
+const written = new Map();
+
+// kind: what it is, as the summary counts it (screenshot, video, steps file, profile, watch file).
+function noteWritten(file, kind, client = state.client) {
+  written.set(path.resolve(file), { kind, client: client ?? null });
+}
+
+// A file renamed (record off <file>) is still the same one.
+function noteMoved(from, to) {
+  const entry = written.get(path.resolve(from));
+  if (!entry) return;
+  written.delete(path.resolve(from));
+  written.set(path.resolve(to), entry);
+}
+
+function remaining(client) {
+  const files = [];
+  for (const [file, entry] of written) {
+    if (entry.client !== (client ?? null)) continue;
+    try { files.push({ file, kind: entry.kind, size: fs.statSync(file).size }); } catch {}
+  }
+  return files;
+}
+
+function sizeText(bytes) {
+  if (bytes < 1024 * 1024) return `${Math.max(1, Math.round(bytes / 1024))} KB`;
+  return `${Number((bytes / 1024 / 1024).toFixed(1))} MB`;
+}
+
+// For close: the client's own files, in full.
+function ownFilesText(client) {
+  const files = remaining(client);
+  if (!files.length) return null;
+  return [`Files you wrote that are still there; remove what is no longer needed:`, ...files.map(f => `  ${f.file} (${sizeText(f.size)})`)].join('\n');
+}
+
+const plural = (n, kind) => `${n} ${kind}${n === 1 ? '' : 's'}`;
+
+// For stop: one line for each client that left files, each with what and where.
+function summaryLines() {
+  const clients = [...new Set([...written.values()].map(e => e.client))];
+  const lines = [];
+  for (const client of clients) {
+    const files = remaining(client);
+    if (!files.length) continue;
+    const kinds = new Map();
+    for (const f of files) kinds.set(f.kind, (kinds.get(f.kind) || 0) + 1);
+    const folders = [...new Set(files.map(f => `${path.dirname(f.file)}/`))];
+    const bytes = files.reduce((sum, f) => sum + f.size, 0);
+    const who = client ? `by ${client}` : 'without a client name';
+    lines.push(`${FILES_LEFT} ${who}: ${plural(files.length, 'file')}, ${sizeText(bytes)} (${[...kinds].map(([k, n]) => plural(n, k)).join(', ')}) in ${folders.join(' and ')}`);
+  }
+  return lines;
+}
+
+// After every recording has been saved, so its file is whole.
+onShutdownEnd(() => { for (const line of summaryLines()) out.log(line); });
+
+module.exports = { noteWritten, noteMoved, ownFilesText, summaryLines };

package/package.json

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

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pw-repl
-description: Inspect and drive a Chromium browser, possibly one the user is using, through the pw-repl REPL - tabs, page snapshots, clicks and typing, the mouse at a point (moves, buttons, wheel), requests and their bodies, console messages, waiting for pages and elements, choosing files, faking, patching or delaying responses, cutting or slowing the network, emulating a phone, dark mode, a locale or a timezone, recording what the user does, profiling what makes a page slow (long tasks, forced layouts, input delay, dropped frames), and recording a video of a tab, with a pointer and on-screen captions. Use when asked to look at, debug or test something in a web page, in an existing Chromium with remote debugging or in one it starts itself.
+description: Inspect and drive a Chromium browser, possibly one the user is using, through the pw-repl REPL - tabs, page snapshots, clicks and typing, the mouse at a point (moves, buttons, wheel), requests and their bodies, console messages, what a page copied to the clipboard, waiting for pages and elements, choosing files, faking, patching or delaying responses, cutting or slowing the network, emulating a phone, dark mode, a locale or a timezone, recording what the user does, profiling what makes a page slow (long tasks, forced layouts, input delay, dropped frames), and recording a video of a tab, with a pointer and on-screen captions. Use when asked to look at, debug or test something in a web page, in an existing Chromium with remote debugging or in one it starts itself.
 allowed-tools: Bash(pw-repl:*) Bash(npx pw-repl@latest:*)
 ---
 
@@ -93,7 +93,7 @@ client of your own: `PW_CLIENT=<name>` (or `send -c <name>`), with a name that s
   as `[server:<name>]` lines.
 - `modes` and `tab` say which client turned each mode on and opened each tab. `modes off --mine` turns
   off only what you turned on; `tab close <url-part>` closes a tab you opened.
-- Commands run one at a time, from every client: a long one (`capture on 60`, `sleep`) holds the rest.
+- Commands run one at a time, from every client: a long one (`capture on 60s`, `sleep`) holds the rest.
 
 A REPL of your own, on a socket of its own, is for a browser of your own (`--launch`), or when you are
 asked for one. Several REPLs on one browser each see every tab but list only their own modes, and can
@@ -105,16 +105,19 @@ A REPL in a terminal stops at its prompt (`quit`, or Ctrl-C); `send quit` is ref
 
 ```bash
 pw-repl send tab
-pw-repl send -t 90 'screenshot -d 60'   # wait longer than the 20s default
+pw-repl send -t 90s 'screenshot -d 60s'   # wait longer than the 20s default
 ```
 
+Times, in send's `-t` and in every command, are in milliseconds, as in Playwright, or in seconds with an
+`s`: `-t 90000` or `-t 90s`.
+
 Always send commands with `pw-repl send`; don't type into the pane yourself, except `quit` at the prompt
 of a REPL of your own, which `send` refuses. The words after `send` are the command. For `fill`, `type`,
 `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"`. `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
+`-s`, `--no-vars`) go before the command or after it (`pw-repl send open <url> -t 30s`); 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.
@@ -227,6 +230,9 @@ pw-repl send -c <name> close                        # your modes off; tab close
   lists what is on in every tab (the prompt shows the selected tab's, e.g. `(watch routes:1) pw>`);
   `modes off` turns off every mode in every tab.
 - Someone may be attached to the REPL's tmux session; killing the session ends it for them too.
+- What a page copied (a Copy button): click it, then `clipboard` prints it. In a headless browser
+  (`--launch`) that is the browser's own clipboard. In one with a window it is the user's, which may
+  hold a password, so `clipboard` refuses there without `--shared-clipboard`: ask the user first.
 - To point something out, to the user or in a screenshot, `highlight <ref|selector>` draws a box over it
   without changing the page (`--style=<css>` restyles it; `highlight off` hides them), without
   Playwright's locator label unless `highlight --labels on`.
@@ -249,6 +255,8 @@ pw-repl send -c <name> close                        # your modes off; tab close
   not by `send`. Without it, a REPL on a socket of its own saves them next to its socket, and any other
   in `/tmp`. `screenshot` prints each file's path; other REPLs may save theirs in the same place. Remove
   only your own, and keep those too if they are needed, e.g. as evidence or as something to hand over.
+  `close` (as a client, `-c <name>`) lists every file you wrote that is still there: screenshots,
+  videos, saved profiles and watches.
 - `PW_ENDPOINT` / `PW_TMUX_SESSION` — defaults for `send -e` / `-s`. `PW_SOCKET` — the socket `serve`
   serves on and `send` looks for when neither is given (default `/tmp/pw-repl.sock`).