pw-repl 0.9.0 → 0.11.0

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pw-repl
-description: Inspect and drive a Chromium browser, possibly one a person is using, through the pw-repl (playwright-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 person does, and recording a video of a tab. 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 (playwright-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, 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:*)
 ---
 
@@ -9,22 +9,26 @@ allowed-tools: Bash(pw-repl:*) Bash(npx pw-repl@latest:*)
 <!-- pw-repl skill stamp -->
 
 pw-repl (playwright-repl) is a REPL that drives a running Chromium over CDP. The browser may be a
-shared session: a person can have their own tabs open in it and be using it while you work.
+shared session: the user can have their own tabs open in it and be using it while you work.
 
 `pw-repl` below is the command the `pw-repl` npm package installs. Without a global install, use
 `npx pw-repl@latest` in its place, in that same form for every command, so each one runs the same
 version; from a clone, `<clone>/bin/pw-repl.js`.
 
-`pw-repl where` also names the skill of the pw-repl you run: `skill: e5f6a7b8 (pw-repl 0.4.3)`. When that
-is not the skill named at the top of this file, tell the user before going on:
+`pw-repl where` also names the skill of the pw-repl you run: `skill: e5f6a7b8 (pw-repl 0.4.3)`. Compare
+its hash (`e5f6a7b8`) with the one at the top of this file. The same hash is the same skill, whatever
+the versions say, since a release that leaves the skill as it was keeps its hash: say nothing. When the
+hashes differ, tell the user once, in these words and in passing, with whatever else you are telling
+them, and carry on with the task:
 
-- if this file's pw-repl version is newer than that one, pw-repl is behind: say "⚠️ pw-repl is older
-  than this skill (pw-repl <that version>, skill from <this file's>); `npx pw-repl@latest` or
+- if this file's pw-repl version is newer than that one, pw-repl is behind: "🔄 pw-repl is older than
+  this skill (pw-repl <that version>, skill from <this file's>); `npx pw-repl@latest` or
   `npm install -g pw-repl` updates it."
-- otherwise, the skill is: ask "⚠️ This pw-repl skill is out of date (from pw-repl <this file's
-  version>; <that version> has a newer one). Update it? Everything but its Custom rules section will be
-  replaced." On a yes, save what `pw-repl skill` prints over this file, with this file's Custom rules
-  section in place of the new one's.
+- otherwise, the skill is: "🔄 This pw-repl skill is out of date (from pw-repl <this file's version>;
+  <that version> has a newer one). If you'd like me to update it, just ask: everything but its Custom
+  rules section would be replaced." Update it only when the user asks for that; a yes to something else
+  is not one. To update it, save what `pw-repl skill` prints over this file, with this file's Custom
+  rules section in place of the new one's.
 
 ## Arguments
 
@@ -34,11 +38,12 @@ the sections below are how to carry it out. With no args, get a REPL running and
 
 ## Start it
 
-`pw-repl where` says whether a REPL is running and how `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 `pw-repl where` first, before anything else (with `-e <socket>` for a REPL you were told is on one),
+and check the skill it names against the top of this file. It says whether a REPL is running and how
+`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.
 
 - `pw-repl serve --background` runs it detached, with a command server on `/tmp/playwright-repl.sock`
   (owner-only) and its output in `/tmp/playwright-repl.log`. `pw-repl attach` shows everything it does
@@ -47,12 +52,12 @@ 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 a person, headless too: its tabs
-  come back, and session cookies with them, so a login stays. They start loading before the REPL is
+  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.
 - `pw-repl run` runs it in a terminal with no server; `send` then reaches it through tmux, if it runs in
@@ -71,14 +76,15 @@ pw-repl send -e /tmp/mine.sock tab new http://localhost:3000
 pw-repl stop -e /tmp/mine.sock
 ```
 
-A socket file left by a REPL that died is replaced when the next one starts there. The log of a background REPL is next to its socket
-(`/tmp/mine.log`), appended to run after run, with a line where each starts and stops (past 5 MB, a
-start moves it to `/tmp/mine.log.1`); `tail -f` on it follows along without a terminal to attach from.
-`serve <port>` listens on TCP 127.0.0.1 instead of a socket, with no access control.
+A socket file left by a REPL that died is replaced when the next one starts there. The log of a
+background REPL is next to its socket (`/tmp/mine.log`), appended to run after run, with a line where
+each starts and stops (past 5 MB, a start moves it to `/tmp/mine.log.1`); `tail -f` on it follows along
+without a terminal to attach from. `serve <port>` listens on TCP 127.0.0.1 instead of a socket, with no
+access control.
 
 ### One REPL, many clients
 
-One REPL serves everyone using its browser: the person at its prompt and any number of agents. When
+One REPL serves everyone using its browser: the user at its prompt and any number of agents. When
 `pw-repl where` finds one running for the browser you need, use it rather than start another, as a
 client of your own: `PW_CLIENT=<name>` (or `send -c <name>`), with a name that says who you are.
 
@@ -104,9 +110,10 @@ pw-repl send -t 90 'screenshot -d 60'   # wait longer than the 20s default
 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` and `upload`, a word quoted in your shell stays one word
-(`pw-repl send fill "text=Your name" Ada`); 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:
+(`pw-repl send fill "text=Your name" Ada`); 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:
 
 - `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
@@ -120,8 +127,14 @@ spaces and all: `pw-repl send click "text=Your name"`. It works however the REPL
 REPL), or why neither is reachable, without running anything.
 
 `send --file take.txt` runs a file of commands, one per line, as typed at the prompt (no shell quoting;
-files relative to your folder, as on `send`'s command line; `#` comments), and stops at the first that fails, saying which line.
-It is the way to record a video without gaps (`help record`), and to keep a repro to run again.
+files relative to your folder, as on `send`'s command line; `#` comments), and stops at the first that
+fails, saying which line. It is the way to record a video without gaps (`help record`), and to keep a
+repro to run again. A `{{ PW_NAME }}` in a line is the variable PW_NAME from `send`'s environment, best
+in double quotes (`fill '#password' "{{ PW_PASSWORD }}"`): the REPL fills it in as it runs the line, and
+its pane and log show the line as written, so a secret stays out of both the file and the log. 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: to type a
+password, `PW_PASSWORD=... pw-repl send fill '#password' "{{ PW_PASSWORD }}"` keeps it out of the log.
 
 `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.
@@ -143,11 +156,15 @@ Every command you run and its output show in the REPL's pane, or in `attach` and
 background REPL (server commands as `[server]` lines), so whoever looks there sees what you do. The pane
 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.
+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,
+which `send --file` fills in from its environment (`PW_PASSWORD=... pw-repl send --file login.txt`), so
+the file can be shared without it.
 
 When watching someone:
 
@@ -182,7 +199,7 @@ task (`cart-bug`), since two agents with one name are one client:
 pw-repl send -c <name> open http://localhost:3000   # a tab of your own in the shared browser
 pw-repl send -c <name> snapshot                     # no snapshot after each command; ask for one
 pw-repl send -c <name> click e5
-pw-repl send -c <name> close                        # your modes off; tab close <url-part> closes your tab
+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
@@ -196,27 +213,27 @@ pw-repl send -c <name> close                        # your modes off; tab close
 ## Sharing the browser
 
 - The browser may have tabs that are not yours, and someone may be using it. Whether to read or act in
-  one of those tabs, or to open your own (`tab new <url>`), depends on the task; when that is not
-  clear, ask.
+  one of those tabs, or to open your own (`tab new <url>`), depends on the task; when that is not clear,
+  ask. `tab` marks `(in front)` the tab the user sees: "this page" is usually that one. A tab you have
+  selected is never marked (help tab says why).
 - No tab is selected when the REPL starts. A start URL's tab, marked `(the start URL)` in `tab`, is
   selected at its prompt and for `send` without a client name; a named client (`-c`) selects it with
   `tab <index>`. Closing a tab the REPL opened goes back to the tab before it, if the REPL opened that
-  one too; otherwise no tab is selected.
-  Tab numbers change when tabs open or close; `tab <url-part>` and `tab close <url-part>` pick a tab by
-  its URL and refuse if it is ambiguous.
-- You can answer any dialog yourself, one you opened included: `dialog` shows it, and `dialog accept`
-  or `dialog dismiss` answers it. Nothing answers one on its own, and while one is open its page and
-  the commands that read it wait. One answered in the browser is gone from `dialog` too.
+  one too; otherwise no tab is selected. Tab numbers change when tabs open or close; `tab <url-part>`
+  and `tab close <url-part>` pick a tab by its URL and refuse if it is ambiguous.
+- You can answer any dialog yourself, one you opened included: `dialog` shows it, and `dialog accept` or
+  `dialog dismiss` answers it. Nothing answers one on its own, and while one is open its page and the
+  commands that read it wait. One answered in the browser is gone from `dialog` too.
 - Modes and tabs stay on or open until they are turned off or closed, whoever started them. `modes`
   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.
-- To point something out, to the person or in a screenshot, `highlight <ref|selector>` draws a box over it
-  without changing the page (`--style=<css>` restyles it; `highlight off` hides them). Its label can
-  cover what is below it; `help highlight` says how to mark a screenshot without one.
+- 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`.
 - For a video, `help video` says how: a take written as a file and sent with `send --file`, `record on`
-  around it, `cursor on` for a pointer, and the pacing recording adds for the viewer; a screen recorder on
-  the user's machine records what they see.
+  around it, `cursor on` for a pointer, `toast` to say what is happening, and the pacing recording adds
+  for the viewer; a screen recorder on the user's machine records what they see.
 
 ## Environment
 
@@ -225,13 +242,13 @@ pw-repl send -c <name> close                        # your modes off; tab close
 - `PW_CHROME` — the Chromium `--launch` starts (default: Playwright's own, then one on the `PATH`).
 - `PW_FFMPEG` — the ffmpeg `record` uses, and no other, read by the REPL, not by `send` (default:
   Playwright's own, then one on the `PATH`).
-- Playwright's own Chromium and ffmpeg are found where Playwright installs them: `PLAYWRIGHT_BROWSERS_PATH`,
-  or `~/.cache/ms-playwright`.
+- Playwright's own Chromium and ffmpeg are found where Playwright installs them:
+  `PLAYWRIGHT_BROWSERS_PATH`, or `~/.cache/ms-playwright`.
 - `PW_CDP_URL` — CDP endpoint (default `http://localhost:9222`).
-- `PW_SCREENSHOT_DIR` — where the REPL saves screenshots, read when it starts, 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.
+- `PW_SCREENSHOT_DIR` — where the REPL saves screenshots, read when it starts, 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.
 - `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/playwright-repl.sock`).