pw-repl 0.4.1 → 0.5.0

package/skill/SKILL.md

@@ -1,16 +1,30 @@
 ---
 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, 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, and recording what the person does. 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:*)
+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, and recording what the person does. 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:*)
 ---
 
 # pw-repl
 
+<!-- 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.
 
-`pw-repl` below is the command the `pw-repl` npm package installs. Without a global install,
-`npx pw-repl` works the same; from a clone, `<clone>/bin/pw-repl.js`.
+`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:
+
+- 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
+  `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.
 
 ## Arguments
 
@@ -20,17 +34,27 @@ 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. There are three ways to run
-one; each takes an optional start URL, which opens in a new tab.
+`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.
 
 - `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
-  and takes commands; `pw-repl stop` stops it.
+  and takes commands; `pw-repl stop` stops it. It returns once the REPL serves; Ctrl-C before then gives
+  up on the start, stops the REPL, exits 130, and says so in the log.
 - `pw-repl serve` runs the same in a terminal, where the pane shows every command. Its prompt is
-  `pw[serve]>`.
+  `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, stopped with the
-  REPL. It prints the command it ran; flags after `--` are passed to that Chromium.
+  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
+  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 `playwright-repl`:
 
@@ -41,9 +65,11 @@ one; each takes an optional start URL, which opens in a new tab.
 
 `serve` and `serve --background` take a socket path of your own instead of the default
 (`pw-repl serve --background /tmp/mine.sock`); `send`, `attach`, `stop` and `where` then need
-`-e /tmp/mine.sock`, or `PW_SOCKET=/tmp/mine.sock`. The log of a background REPL is next to its socket
-(`/tmp/mine.log`); `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.
+`-e /tmp/mine.sock`, or `PW_SOCKET=/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.
 
 ### One REPL, many clients
 
@@ -70,11 +96,12 @@ pw-repl send tab
 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. 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:
+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:
 
 - `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
@@ -145,8 +172,10 @@ pw-repl send -c <name> close                        # your modes off; tab close
 - 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.
-- No tab is selected when the REPL starts (unless it was given a start URL). 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.
+- 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.
 - Dialogs are never answered on their own. While one is open, its page and the commands that read it
@@ -155,6 +184,11 @@ 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.
+- pw-repl does not record video. For one of a flow in a browser of its own, Microsoft's playwright-cli (a
+  separate tool, the npm package `@playwright/cli`: `video-start`, `video-stop`); for this browser as the
+  person sees it, a screen recorder (`ffmpeg -f x11grab`, macOS `screencapture -v`, OBS). A screen
+  recorder records their whole screen, not the tab: ask before starting one, or have them start it. A
+  headless browser is not on the screen, so it does not show.
 
 ## Environment