pw-repl 0.11.0 → 0.11.2

package/AGENTS.md

@@ -25,7 +25,7 @@ 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/cli-names.js` maps playwright-cli's command
+  command line's words are read, shared with `send`, and its `{{ PW_NAME }}` variables; `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; `lib/skill.js` stamps the skill
   `pw-repl skill` prints, and gives `where` its hash.

package/README.md

@@ -88,7 +88,7 @@ the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
 
 | I want to…                           | Commands                                                                              |
 | ------------------------------------ | ------------------------------------------------------------------------------------- |
-| see where I am                       | `tab` (it marks the tab you are looking at `(in front)`), `info`                      |
+| see where I am                       | `tab` (it marks the tab you are looking at `(visible)`), `info`                       |
 | see what is on the page              | `snapshot`, `screenshot`                                                              |
 | do something on it                   | `click`, `fill`, `press`                                                              |
 | wait for a page or element           | `wait load`, `wait <selector>`, `wait <selector> --gone`                              |
@@ -179,6 +179,14 @@ Several agents can share one REPL: `pw-repl send -c <name>` (or `PW_CLIENT=<name
 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 password can be typed as a variable: `PW_PASSWORD=... pw-repl send fill '#password' "{{ PW_PASSWORD }}"`,
+or the same line in a file run with `send --file`, as `watch save` writes it. `send` takes the value of
+`{{ PW_NAME }}` from its own environment and passes it along with the command; the REPL puts it in only as
+it runs the command, so the file, and the command as the pane, the log and the prompt's history show it,
+never hold it. Output that reads it back can: `snapshot`, `html` and `attrs` hide a password field's value,
+but `eval` reading the field, a field a Show password button made plain text (`help snapshot`), or page
+text that repeats it do not. Only `PW_` names are variables (`pw-repl --help` has the rest).
+
 ### The HTTP protocol
 
 With `pw-repl serve`, the server speaks HTTP with JSON, for clients of your own:
@@ -188,11 +196,12 @@ curl --unix-socket /tmp/playwright-repl.sock -H 'Content-Type: application/json'
   -d '{"command": "info"}' http://localhost/run
 ```
 
-It returns `{"status": "ok" | "error", "output": "..."}`, plus `"unconfirmed": true` when the command may or
-may not have done what it was sent to do (it timed out, or the REPL quit while it ran and it was not
-read-only). While the REPL starts, `/run` answers 503 with `"starting": true`: retry. `GET /health` says
-`"status": "starting"` until it serves, then `"ok"`. `pw-repl serve <port>` serves TCP on 127.0.0.1
-instead; other addresses are refused.
+The body may also have `"client": "<name>"`, and `"vars": {"PW_NAME": "<value>"}` with the values of the
+`{{ PW_NAME }}` variables in the command, one line each (else 400). It returns `{"status": "ok" | "error", "output": "..."}`, plus
+`"unconfirmed": true` when the command may or may not have done what it was sent to do (it timed out, or
+the REPL quit while it ran and it was not read-only). While the REPL starts, `/run` answers 503 with
+`"starting": true`: retry. `GET /health` says `"status": "starting"` until it serves, then `"ok"`.
+`pw-repl serve <port>` serves TCP on 127.0.0.1 instead; other addresses are refused.
 
 ## Tests
 

package/bin/pw-repl.js

@@ -45,13 +45,14 @@ folder, as on send's command line, and # comments and blank lines skipped. It st
 command that fails, saying its line, with its exit status. -t is each command's own limit. Other
 clients' commands can run between its lines, on their own tabs.
 
-A {{ PW_NAME }} in a command, or in a line of the file, is the variable PW_NAME from send's environment,
-e.g. a password kept out of the file and the REPL's log. In a file: fill '#password' "{{ PW_PASSWORD }}",
+A {{ PW_NAME }} in a command, or in a line of the file, is a variable: send takes its value from its own
+environment (PW_NAME) and passes it along with the command, not in it, e.g. a password kept out of the
+file and out of the command as the REPL logs it. In a file: fill '#password' "{{ PW_PASSWORD }}",
 run with PW_PASSWORD=... pw-repl send --file login.txt; or one command: PW_PASSWORD=... pw-repl send
 fill '#password' "{{ PW_PASSWORD }}". Only names starting PW_ are variables: any other {{ ... }}, as in a
 page's template text, is sent as written. In a file, put it in double quotes: there its value is
 escaped as they read it (in single quotes, which escape nothing, a value with a ' is refused). The REPL
-fills it in as it runs the command, and its pane and log show the command as written. A variable that
+puts it in only as it runs the command, and its pane and log show the command as written. A variable that
 is not set stops the command, or the file at that line, before it is sent. --no-vars sends
 {{ PW_NAME }} as it is. Variables need the command server (pw-repl serve), not the tmux pane.
 

package/lib/help.js

@@ -152,7 +152,7 @@ const COMMANDS = {
     usage: 'tab [<index>|<url-part>|new [url]|close [url-part]]',
     summary: 'list tabs (* is selected); select, open or close one',
     args: [
-      ['(none)', 'lists the tabs: * marks the selected one, (in front) the one the browser shows, and each says who opened it with tab new.'],
+      ['(none)', 'lists the tabs: * marks the selected one, (visible) the one the browser shows, and each says who opened it with tab new.'],
       ['<index>', 'selects by the number in your latest listing (each client has its own); numbers change when tabs open or close.'],
       ['<url-part>', 'selects the one tab whose URL contains it; refused if none or several do.'],
       ['new [url]', 'opens a tab behind the one in front, so it does not take the window from whoever is using it, and selects it. The URL is read as goto reads it.'],
@@ -161,11 +161,11 @@ const COMMANDS = {
     detail: `Closing the selected tab goes back to the previous tab if tab new opened it; otherwise no tab is
 selected, and commands that need one refuse until one is.
 
-In front: (in front) marks the tab the browser shows in its window, the one the user sees; (in front,
+Visible: (visible) marks the tab the browser shows in its window, the one the user sees; (visible,
 focused) when its window has the keyboard too, and it is not in the address bar. A tab a client has
 selected or opened is never marked: pw-repl tells it that it is in front, so that it keeps drawing and
 clicks in it work while it is behind another, and so cannot ask it. The user's other tabs are told
-nothing, and say truly whether they are seen. Each window has a tab in front, so with several windows
+nothing, and say truly whether they are seen. Each window shows a tab, so with several windows
 (an incognito one, say) several tabs are marked; focused is the one with the keyboard.`,
   },
   goto: {
@@ -353,8 +353,8 @@ describing it: click, fill, select, check, press, and wait load after a step tha
 element is found by its id, data-testid or name, its text, or else its place in the page, which a change
 to the page can break. A select step chooses the option by its value. What was typed into a password
 field (or any field, with --no-values) is a variable named after the field, e.g. fill '#password'
-"{{ PW_PASSWORD }}", which pw-repl send --file fills in from its environment: PW_PASSWORD=... pw-repl
-send --file login.txt. A step that cannot be a command (a value with a line break, an element in a frame, or
+"{{ PW_PASSWORD }}": run it with PW_PASSWORD=... pw-repl send --file login.txt, and send passes the
+value along for the REPL to put in, which shows the line as written. A step that cannot be a command (a value with a line break, an element in a frame, or
 one no selector finds alone) stays a comment saying why, and the save says how many there are.
 
 Shared: every client sees the same steps, and watch new's place is shared.`,

package/lib/runner.js

@@ -188,7 +188,7 @@ function enqueue(line) {
 // someone watching sees everything an agent does.
 // client names the sender: its commands show as [server:<client>] and use its own selected tab.
 // vars: values for the {{ PW_NAME }} variables in text (from send), filled in to run it; text is shown
-// as written, so a password in one stays out of the pane, the log and the prompt's history.
+// as written, so a password in one is not in the command as the pane, the log and the prompt's history show it.
 function submit(text, client = null, vars = null) {
   let run = text;
   if (vars) {

package/lib/syntax.js

@@ -70,7 +70,7 @@ function variablesIn(line) {
 // values: { NAME: value }. Throws on a variable it has no value for.
 function expandVariables(line, values) {
   const value = name => {
-    if (typeof values[name] !== 'string') throw new Error(`{{ ${name} }} has no value: send --file fills it in from ${name} in its environment`);
+    if (typeof values[name] !== 'string') throw new Error(`{{ ${name} }} has no value: send passes it along from ${name} in its environment`);
     return values[name];
   };
   return line.replace(new RegExp(`"(?:[^"\\\\]|\\\\.)*"|'[^']*'|${VARIABLE.source}`, 'g'), (whole, name) => {

package/lib/tabs.js

@@ -105,7 +105,7 @@ async function pageForTarget(ctx, targetId) {
 }
 
 // Every tab, URL first, with * on the selected one. The numbers are what tab <index> uses.
-// Whether a tab is the one in front in its window, as the tab itself says: 'in front', 'in front,
+// Whether a tab is the one in front in its window, as the tab itself says: 'visible', 'visible,
 // focused' (its window has the keyboard, and not in the address bar), or null. Not for a tab a client
 // uses, which is told it is in front so that it draws (lib/cdp.js); nor for one that does not answer
 // at once (a dialog open, a frozen tab). Each window has one in front, an incognito one too.
@@ -114,7 +114,7 @@ async function inFront(p) {
   const read = p.evaluate(() => [document.visibilityState, document.hasFocus()]).catch(() => null);
   const seen = await Promise.race([read, new Promise(resolve => setTimeout(resolve, FRONT_READ_TIMEOUT, null))]);
   if (!seen || seen[0] !== 'visible') return null;
-  return seen[1] ? 'in front, focused' : 'in front';
+  return seen[1] ? 'visible, focused' : 'visible';
 }
 
 async function listTabs() {

package/lib/watch.js

@@ -553,7 +553,7 @@ function showWatch(watch, all) {
 
 // watch save: the steps as commands for send --file to run again, a step that cannot be one (a value
 // with a line break, an element in a frame) as a comment saying so. What was typed into a password field,
-// or with --no-values, is a {{ PW_NAME }} variable, named after the field, that send --file fills in. A
+// or with --no-values, is a {{ PW_NAME }} variable, named after the field, set when send --file runs it. A
 // selector is quoted as lib/syntax.js reads one: single quotes, which escape nothing, unless it holds
 // one. A value is always double-quoted, so an empty one, or one that starts with -, stays the value.
 function savedCommands(watch, p) {

package/package.json

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

package/skill/SKILL.md

@@ -129,12 +129,15 @@ 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. 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.
+repro to run again. A `{{ PW_NAME }}` in a line is a variable, best in double quotes (`fill '#password'
+"{{ PW_PASSWORD }}"`): `send` takes its value from its own environment and passes it along with the
+line, not in it; the REPL puts it in only as it runs the line, and its pane and log show the line as
+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.
 
 `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.
@@ -163,8 +166,8 @@ shown yet. For a tab they have not opened yet, `watch on --next-tab [url-part]`
 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.
+set when it runs (`PW_PASSWORD=... pw-repl send --file login.txt`), so the file can be shared without
+it.
 
 When watching someone:
 
@@ -214,7 +217,7 @@ 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. `tab` marks `(in front)` the tab the user sees: "this page" is usually that one. A tab you have
+  ask. `tab` marks `(visible)` 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