pw-repl 0.9.0 → 0.11.0

package/lib/watch.js

@@ -2,19 +2,24 @@
 const { state, clientRecord } = require('./state');
 const out = require('./output');
 const { printOutput } = out;
+const fs = require('fs');
+const path = require('path');
 const { clipText, clock, hints, NO_TAB } = require('./util');
 const { tabState } = require('./tabstate');
 const { keptSession, keepDrawing } = require('./cdp');
 const { RECENT_HIDDEN_TYPES, keepBodiesDurable, keep, WATCH_HIDDEN_TYPES, RECENT_DEFAULT } = require('./requestlog');
 const { compactSnapshot } = require('./inspect');
 
-// Opt-in record of what the person at the browser does, so an agent can see
+// Opt-in record of what the user at the browser does, so an agent can see
 // the steps and the requests each one caused. Values typed into fields are
 // never recorded, and password fields not at all.
 const WATCH_MAX = 200;
 const WATCH_REQUESTS_SHOWN = 5;
 
 const TYPING_BACKDATE_MAX = 60000;
+const WATCH_FLAGS = new Set(['--changes', '--live', '--no-values']);
+const PW_SETTINGS = ['PW_CDP_URL', 'PW_CHROME', 'PW_CLIENT', 'PW_ENDPOINT', 'PW_FFMPEG', 'PW_REPL_PID_FILE', 'PW_SCREENSHOT_DIR',
+  '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';
 
@@ -37,7 +42,7 @@ const WATCH_SCRIPT = `(() => {
     if (/^h[1-6]$/.test(tag)) return 'heading';
     return tag;
   };
-  // Text inside these may be what the person typed, so it is never used as a name.
+  // Text inside these may be what the user typed, so it is never used as a name.
   const typedInto = el => el.matches('input,select,textarea,form') || el.isContentEditable || !!el.closest('[contenteditable]:not([contenteditable=false])');
   const isPassword = el => el.matches('input[type=password]') || (el.control && el.control.matches('input[type=password]'));
   // An element holding an editable area would be named partly by what was typed there.
@@ -57,15 +62,104 @@ const WATCH_SCRIPT = `(() => {
       || el.getAttribute('placeholder') || el.getAttribute('title') || (typedInto(el) || hasEditable(el) ? '' : el.innerText));
   };
   const describe = el => { const name = nameOf(el); return roleOf(el) + (name ? ' ' + JSON.stringify(name) : ''); };
+  // A field that was a password field while watched stays one when a "show password" button makes it
+  // text; and some take secrets under another type. Their values never leave the page.
+  const secrets = new WeakSet();
+  const SECRET_AUTOCOMPLETE = /\\b(?:current-password|new-password|one-time-code|cc-number|cc-csc)\\b/;
+  const notePasswords = () => { for (const el of document.querySelectorAll('input[type=password]')) secrets.add(el); };
+  notePasswords();
+  document.addEventListener('focusin', notePasswords, true);
+  const isSecret = el => !!el && (secrets.has(el) || (el.matches && el.matches('input[type=password]')) || SECRET_AUTOCOMPLETE.test((el.getAttribute && el.getAttribute('autocomplete')) || ''));
+  const valueOf = el => (el.isContentEditable ? el.innerText : el.value);
+  // A selector that finds this element and no other, as Playwright reads it, for watch save. Playwright's
+  // CSS goes into open shadow roots, so matches are counted in them too; inside one, the element's own
+  // selector there follows its host's, which a descendant combinator crosses into.
+  const shadowRoots = scope => {
+    const found = [scope];
+    for (let i = 0; i < found.length; i++) for (const el of found[i].querySelectorAll('*')) if (el.shadowRoot) found.push(el.shadowRoot);
+    return found;
+  };
+  const textOf = el => (el.textContent || '').replace(/\\s+/g, ' ').trim();
+  const cssString = text => '"' + text.replace(/\\\\/g, '\\\\\\\\').replace(/"/g, '\\\\"') + '"';
+  const selectorIn = (el, scope) => {
+    const roots = shadowRoots(scope);
+    const count = sel => { let n = 0; for (const r of roots) n += r.querySelectorAll(sel).length; return n; };
+    const tag = el.localName;
+    if (el.id && count('#' + CSS.escape(el.id)) === 1) return '#' + CSS.escape(el.id);
+    const testid = el.getAttribute('data-testid');
+    if (testid && count('[data-testid=' + cssString(testid) + ']') === 1) return '[data-testid=' + cssString(testid) + ']';
+    const name = el.getAttribute('name');
+    if (name && /^(?:input|select|textarea)$/.test(tag) && count(tag + '[name=' + cssString(name) + ']') === 1) return tag + '[name=' + cssString(name) + ']';
+    const text = textOf(el);
+    if (text && text.length <= 60 && !el.querySelector('input,select,textarea')) {
+      let same = 0;
+      for (const r of roots) for (const other of r.querySelectorAll(tag)) if (textOf(other) === text) same++;
+      if (same === 1) return tag + ':text-is(' + cssString(text) + ')';
+    }
+    // Its place: the path down from the nearest ancestor with an id of its own, or from the top.
+    const steps = [];
+    for (let at = el; at && at.parentNode; at = at.parentNode) {
+      if (at !== el && at.id && count('#' + CSS.escape(at.id)) === 1) { steps.unshift('#' + CSS.escape(at.id)); break; }
+      if (at.localName === 'body') { steps.unshift('body'); break; }
+      const same = [...at.parentNode.children].filter(c => c.localName === at.localName);
+      steps.unshift(same.length > 1 ? at.localName + ':nth-of-type(' + (same.indexOf(at) + 1) + ')' : at.localName);
+      if (!(at.parentNode instanceof Element)) break;
+    }
+    return steps.join(' > ');
+  };
+  const partsOf = el => {
+    const root = el.getRootNode();
+    if (root === document) return [selectorIn(el, document)];
+    if (!(root instanceof ShadowRoot) || root.mode !== 'open') return null;
+    const host = partsOf(root.host);
+    return host && [...host, selectorIn(el, root)];
+  };
+  // Each part matched in the element's own tree, the one before it by an ancestor, its host's included,
+  // as Playwright reads a descendant combinator. A path inside a shadow root is anchored to nothing
+  // there, so it could match deeper in the host: the whole selector is counted before it is used.
+  const composedParent = el => el.parentElement || (el.parentNode instanceof ShadowRoot ? el.parentNode.host : null);
+  const TEXT_IS = /^([a-z][\\w-]*):text-is\\("((?:[^"\\\\]|\\\\.)*)"\\)$/;
+  const matchesPart = (el, part) => {
+    const text = part.match(TEXT_IS);
+    return text ? el.localName === text[1] && textOf(el) === text[2].replace(/\\\\(.)/g, '$1') : el.matches(part);
+  };
+  const matchesParts = (el, parts) => {
+    if (!matchesPart(el, parts[parts.length - 1])) return false;
+    if (parts.length === 1) return true;
+    const rest = parts.slice(0, -1);
+    for (let at = composedParent(el); at; at = composedParent(at)) if (matchesParts(at, rest)) return true;
+    return false;
+  };
+  const selectorOf = el => {
+    if (window !== window.top) return null;
+    const parts = partsOf(el);
+    if (!parts) return null;
+    let n = 0;
+    for (const r of shadowRoots(document)) for (const other of r.querySelectorAll('*')) if (matchesParts(other, parts) && ++n > 1) return null;
+    return n === 1 ? parts.join(' ') : null;
+  };
   // el null: the page itself, e.g. Escape with nothing focused.
   const send = (action, el, extra, since) => {
     // Typing still waiting for its pause is recorded first, so the steps stay in order.
     if (action !== 'type') for (const field of [...pending.keys()]) flushTyping(field);
-    if (typeof window.__pwReplWatch === 'function') window.__pwReplWatch(JSON.stringify({ action, target: el ? describe(el) : 'page', extra: extra || '', since: since || 0 }));
+    if (typeof window.__pwReplWatch !== 'function') return;
+    let selector = null;
+    try { selector = el ? selectorOf(el) : null; } catch {}
+    const typed = (action === 'type' || action === 'fill') && el;
+    const secret = typed && isSecret(el);
+    const option = action === 'select' ? el.value : null;
+    window.__pwReplWatch(JSON.stringify({ action, target: el ? describe(el) : 'page', extra: extra || '', since: since || 0, selector, secret, value: typed && !secret ? valueOf(el) : null, option }));
   };
+  // The element itself, not its component's host, when it is inside an open shadow root.
+  const targetOf = e => (e.composedPath && e.composedPath()[0]) || e.target;
+  // Enter in a form's field submits it with a click on its submit button, which is the Enter's doing:
+  // recorded too, it would submit the form again when the steps run again.
+  let enteredForm = null;
   document.addEventListener('click', e => {
-    const el = e.target.closest ? (e.target.closest(INTERACTIVE) || e.target) : e.target;
+    const t = targetOf(e);
+    const el = t.closest ? (t.closest(INTERACTIVE) || t) : t;
     if (!el.matches || el.matches('input[type=checkbox],input[type=radio],select') || isPassword(el)) return;
+    if (e.detail === 0 && enteredForm && el.form === enteredForm) return;
     send('click', el);
   }, true);
   // Typing is recorded once it pauses, not on change, so a typeahead's requests
@@ -87,25 +181,30 @@ const WATCH_SCRIPT = `(() => {
   const editable = el => el.isContentEditable ? (el.closest('[contenteditable]:not([contenteditable=false])') || el) : null;
   const textEntry = el => el.matches('textarea,input:not([type=checkbox],[type=radio],[type=button],[type=submit],[type=reset],[type=image],[type=file],[type=range],[type=color])');
   document.addEventListener('input', e => {
-    const el = editable(e.target) || e.target;
-    if (!el.matches || isPassword(el) || !(textEntry(el) || el.isContentEditable)) return;
+    const el = editable(targetOf(e)) || targetOf(e);
+    if (!el.matches || !(textEntry(el) || el.isContentEditable)) return;
+    // Typing here ends typing anywhere else, recorded first: one that ended with no change event (the
+    // value it had before) would otherwise wait out its pause, and come after the fields typed since.
+    for (const field of [...pending.keys()]) if (field !== el) flushTyping(field);
     const start = pending.has(el) ? pending.get(el).start : Date.now();
     clearTimeout(pending.get(el)?.timer);
     pending.set(el, { start, timer: setTimeout(() => flushTyping(el), TYPING_PAUSE) });
   }, true);
   document.addEventListener('keydown', e => {
     if (e.key !== 'Enter' && e.key !== 'Escape') return;
-    if (!e.target.matches) return;
-    const el = editable(e.target) || e.target.closest(INTERACTIVE);
-    if (el && isPassword(el)) return;
+    const t = targetOf(e);
+    if (!t.matches) return;
+    const el = editable(t) || t.closest(INTERACTIVE);
     // Enter on a button or link is recorded as the click it causes.
     if (e.key === 'Enter' && !(el && (textEntry(el) || el.isContentEditable))) return;
     if (el) flushTyping(el);
     send('press', el, e.key);
+    // The click comes in the same task as the key, if at all.
+    if (e.key === 'Enter' && el && el.form) { enteredForm = el.form; setTimeout(() => { enteredForm = null; }); }
   }, true);
   document.addEventListener('change', e => {
-    const el = e.target;
-    if (!el.matches || isPassword(el)) return;
+    const el = targetOf(e);
+    if (!el.matches) return;
     if (el.matches('input[type=checkbox],input[type=radio]')) return send(el.checked ? 'check' : 'uncheck', el);
     if (el.matches('select')) return send('select', el, JSON.stringify(clip(el.selectedOptions[0]?.text)));
     if (pending.has(el)) { flushTyping(el); typed.delete(el); return; }
@@ -117,7 +216,7 @@ const WATCH_SCRIPT = `(() => {
 
 // What changed on screen between two snapshots, in a few lines. Refs, links'
 // URLs and focus are dropped, and so are the values of text fields, which may
-// be what the person typed. A new or removed element is shown once, with the
+// be what the user typed. A new or removed element is shown once, with the
 // first few named things inside it, not line by line.
 const CHANGES_SHOWN = 5;
 const CHANGE_WIDTH = 100;
@@ -202,7 +301,7 @@ function summarizeChanges(beforeText, afterText) {
 const SETTLE_QUIET = 800;
 const SETTLE_MAX = 3000;
 
-// Text in an editable area (contenteditable) may be what the person typed,
+// Text in an editable area (contenteditable) may be what the user typed,
 // and the snapshot shows it as ordinary text, so it is blanked out: a line's
 // text or name is dropped when it is part of an editable area's text.
 async function snapshotText(p) {
@@ -257,7 +356,7 @@ function printLive(p, watch) {
   out.aside(lines.map((line, i) => `${i ? ' '.repeat(prefix.length) : prefix}${line}`).join('\n'));
 }
 
-async function startWatching(p, changes = false, live = false) {
+async function startWatching(p, changes = false, live = false, values = true) {
   await keepBodiesDurable(p);
   let watch = tabState(p).watch;
   if (!watch) {
@@ -265,11 +364,14 @@ async function startWatching(p, changes = false, live = false) {
     const created = { on: false, startedAt: 0, changes: false, live: false, liveStep: null, snapshot: null, settleTimer: null, events: [], nextSeq: 1, shownSeq: 0, shownRequestId: 0 };
     // since backdates a step (typing is reported once it pauses), but never to
     // before the previous step, so the page cannot reorder the record.
-    const record = (action, target, extra, since = 0) => {
+    // more: what watch save needs, the element's selector and a typed value (kept whole), or a navigation's URL.
+    const record = (action, target, extra, since = 0, more = {}) => {
       if (!created.on) return;
       const previous = created.events[created.events.length - 1];
       const t = Math.max(Date.now() - Math.min(Math.max(Number(since) || 0, 0), TYPING_BACKDATE_MAX), previous ? previous.t : 0);
-      const step = { seq: created.nextSeq++, t, action, target: clipText(target), extra: clipText(extra) };
+      const step = { seq: created.nextSeq++, t, action, target: clipText(target), extra: clipText(extra), selector: more.selector || null, secret: !!more.secret, url: more.url };
+      if (typeof more.option === 'string') step.option = more.option;
+      if (typeof more.value === 'string' && created.values) step.value = more.value;
       keep(created.events, step);
       // A step that has not settled yet is printed now: this one ends it.
       printLive(p, created);
@@ -288,7 +390,10 @@ async function startWatching(p, changes = false, live = false) {
         if (name !== WATCH_BINDING || !binding.record) return;
         let event;
         try { event = JSON.parse(payload); } catch { return; }
-        if (event && PAGE_ACTIONS.has(event.action)) binding.record(event.action, String(event.target || ''), String(event.extra || ''), event.since);
+        if (event && PAGE_ACTIONS.has(event.action)) {
+          binding.record(event.action, String(event.target || ''), String(event.extra || ''), event.since,
+            { selector: typeof event.selector === 'string' ? event.selector : null, secret: !!event.secret, value: event.value, option: event.option });
+        }
       });
       // Calls are reported only to a session with Runtime on.
       await session.send('Runtime.enable');
@@ -297,7 +402,7 @@ async function startWatching(p, changes = false, live = false) {
     }
     tabState(p).watchBinding.record = record;
     await p.addInitScript(WATCH_SCRIPT);
-    p.on('framenavigated', frame => { if (frame === p.mainFrame()) record('navigate', frame.url(), ''); });
+    p.on('framenavigated', frame => { if (frame === p.mainFrame()) record('navigate', frame.url(), '', 0, { url: frame.url() }); });
     // Only now: a failed first attempt must leave nothing half set up to retry against.
     tabState(p).watch = created;
     watch = created;
@@ -311,6 +416,8 @@ async function startWatching(p, changes = false, live = false) {
   await p.evaluate(WATCH_SCRIPT);
   watch.changes = changes;
   watch.live = live;
+  watch.values = values;
+  if (!watch.on) watch.startUrl = p.url();
   if (!live) watch.liveStep = null;
   // The first step's changes are measured from how the page looks now. A page
   // too busy to snapshot is not a reason to fail: the step after one that
@@ -358,7 +465,7 @@ function watchNewTab(p) {
   const want = nextTab;
   tabState(p).watchStarting = true;
   keepBodiesDurable(p);
-  startWatching(p, want.changes, want.live).then(() => {
+  startWatching(p, want.changes, want.live, want.values).then(() => {
     delete tabState(p).watchStarting;
     tabState(p).watch.owner = want.client;
     const onNavigate = frame => {
@@ -378,7 +485,7 @@ function watchNewTab(p) {
       // A page that loaded before the watch was ready: its step is added, at its request's time.
       if (first < 0) {
         const request = (tabState(p).log || []).filter(e => e.navigation && e.url === url).pop();
-        watch.events.unshift({ seq: watch.nextSeq++, t: request ? request.t : Date.now(), action: 'navigate', target: clipText(url), extra: '' });
+        watch.events.unshift({ seq: watch.nextSeq++, t: request ? request.t : Date.now(), action: 'navigate', target: clipText(url), extra: '', url });
       }
       // Selected for the client that asked, whoever's command runs now.
       const record = clientRecord(want.client);
@@ -412,7 +519,8 @@ function requestsByStep(watch, p = state.page) {
 }
 
 function stepLines(e, caused, note = '', withChanges = true) {
-  const lines = [`${clock(e.t)} ${e.action} ${e.target}${e.extra ? ` ${e.extra}` : ''}${note}`];
+  const typed = e.secret ? ' (a password: not recorded)' : typeof e.value === 'string' ? ` ${JSON.stringify(clipText(e.value))}` : '';
+  const lines = [`${clock(e.t)} ${e.action} ${e.target}${typed}${e.extra ? ` ${e.extra}` : ''}${note}`];
   const indent = ' '.repeat(clock(e.t).length + 1);
   for (const r of caused.slice(0, WATCH_REQUESTS_SHOWN)) lines.push(`${indent}#${r.id} ${r.method} ${r.status} ${r.url}`);
   if (caused.length > WATCH_REQUESTS_SHOWN) lines.push(`${indent}… ${caused.length - WATCH_REQUESTS_SHOWN} more (requests)`);
@@ -436,12 +544,66 @@ function showWatch(watch, all) {
     if (steps > shown.length) lines.push(`(last ${shown.length} of ${steps})`);
   }
   const more = ['watch <n>', `the last n steps (up to ${WATCH_MAX})`];
-  if (watch?.on) lines.push(hints([more, ['watch new', 'only the steps not shown by watch new yet'], ['watch off', 'stop recording']]));
-  else if (steps) lines.push(hints([more, ['watch on [--changes] [--live]', 'record again']]));
+  const save = ['watch save <file>', 'save them as commands, for send --file to run again'];
+  if (watch?.on) lines.push(hints([more, ['watch new', 'only the steps not shown by watch new yet'], ...(steps ? [save] : []), ['watch off', 'stop recording']]));
+  else if (steps) lines.push(hints([more, save, ['watch on [--changes] [--live]', 'record again']]));
   else lines.push(hints([['watch on', 'record clicks, typing, form changes and navigations'], ['watch on --changes', 'also record what each step changes on the page'], ['watch on --live', 'also print each step here as it happens']]));
   printOutput(lines.join('\n'), 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
+// 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) {
+  const sel = text => (text.includes("'") ? `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"` : `'${text}'`);
+  const value = text => `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  const documents = (tabState(p).log || []).filter(r => r.navigation);
+  const events = watch.events.slice();
+  const first = events[0]?.action === 'navigate' ? events.shift().url : watch.startUrl;
+  const lines = [`goto ${first}`];
+  let skipped = 0;
+  const variables = new Map();
+  // PW_, so a field named User or pwd is not filled with the shell's USER or PWD; and never pw-repl's own.
+  const variableFor = e => {
+    if (variables.has(e.selector)) return variables.get(e.selector);
+    const label = /"([^"]+)"$/.exec(e.target)?.[1] || /(?:#|name=")([\w-]+)/.exec(e.selector)?.[1] || 'TEXT';
+    const base = `PW_${label.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'TEXT'}`;
+    const taken = new Set([...variables.values(), ...PW_SETTINGS]);
+    let name = base;
+    for (let n = 2; taken.has(name); n++) name = `${base}_${n}`;
+    variables.set(e.selector, name);
+    return name;
+  };
+  const comment = (e, why) => { skipped += 1; lines[lines.length - 1] += `: ${why}`; };
+  for (const [i, e] of events.entries()) {
+    const previous = events[i - 1];
+    if (e.action === 'navigate') {
+      // The page an action led to: waited for if it loaded a document, not if the app only changed its URL.
+      if (previous && previous.action !== 'navigate') {
+        const loaded = documents.some(r => r.url === e.url && r.t >= previous.t && r.t <= e.t + 1000);
+        lines.push(loaded ? `wait load` : `# the app went to ${e.url} without loading a page`);
+      } else {
+        lines.push(`goto ${e.url}`);
+      }
+      continue;
+    }
+    if (e.action === 'submit') continue;
+    lines.push(`# ${e.action} ${e.target}${e.extra ? ` ${e.extra}` : ''}`);
+    if (!e.selector && !(e.action === 'press' && e.target === 'page')) { comment(e, 'no selector finds it alone: it is in a frame or a closed shadow root, or its place matches others too'); continue; }
+    if (e.action === 'click' || e.action === 'check' || e.action === 'uncheck') lines.push(`${e.action} ${sel(e.selector)}`);
+    else if (e.action === 'select' && typeof e.option !== 'string') comment(e, 'the option was not recorded');
+    else if (e.action === 'select' && /[\r\n]/.test(e.option)) comment(e, 'the option\'s value has a line break, which a line of a file cannot hold');
+    else if (e.action === 'select') lines.push(`select ${sel(e.selector)} ${value(e.option)}`);
+    else if (e.action === 'press') lines.push(e.target === 'page' ? `press ${e.extra}` : `press ${sel(e.selector)} ${e.extra}`);
+    else if (e.secret || typeof e.value !== 'string') lines.push(`fill ${sel(e.selector)} "{{ ${variableFor(e)} }}"`);
+    else if (/[\r\n]/.test(e.value)) comment(e, 'what was typed has a line break, which a line of a file cannot hold: type it with type, line by line, pressing Enter');
+    else lines.push(`fill ${sel(e.selector)} ${value(e.value)}`);
+  }
+  return { lines, skipped, variables: [...new Set(variables.values())] };
+}
+
 function stopWatching(p, watch) {
   clearTimeout(watch.settleTimer);
   printLive(p, watch);
@@ -459,10 +621,10 @@ const commands = {
     if (sub === 'on' && next !== -1) {
       const part = flags[next + 1] && !flags[next + 1].startsWith('--') ? flags[next + 1] : null;
       const rest = flags.filter((f, i) => i !== next && !(part && i === next + 1));
-      if (!rest.every(f => f === '--changes' || f === '--live')) throw new Error('Usage: watch on [--changes] [--live] --next-tab [url-part]');
+      if (!rest.every(f => WATCH_FLAGS.has(f))) throw new Error('Usage: watch on [--changes] [--live] [--no-values] --next-tab [url-part]');
       // One wait at a time: a second client's would silently take the first's place.
       if (nextTab && nextTab.client !== state.client) throw new Error(`${waitingText()} already, for ${waiter()}: one at a time. modes shows it; that client's watch off, or modes off, stops it`);
-      nextTab = { part, changes: rest.includes('--changes'), live: rest.includes('--live'), client: state.client };
+      nextTab = { part, changes: rest.includes('--changes'), live: rest.includes('--live'), values: !rest.includes('--no-values'), client: state.client };
       out.log(`${waitingText()}: it is watched from its first page, and selected. watch off stops waiting.`);
       return;
     }
@@ -470,13 +632,15 @@ const commands = {
       out.log(`${waitingText()} (watch on --next-tab); it is selected once it opens, and watch then shows its steps.`);
       return;
     }
-    if (sub === 'on' && flags.every(f => f === '--changes' || f === '--live')) {
+    if (sub === 'on' && flags.every(f => WATCH_FLAGS.has(f))) {
       if (!state.page || state.page.isClosed()) throw new Error(NO_TAB);
       const changes = flags.includes('--changes');
       const live = flags.includes('--live');
-      await startWatching(state.page, changes, live);
+      const values = !flags.includes('--no-values');
+      await startWatching(state.page, changes, live, values);
       tabState(state.page).watch.owner = state.client;
-      out.log(`Watching the selected tab: clicks, typing, form changes, submits and navigations${changes ? ', and what each changed on screen' : ''} (typed values are not recorded)`);
+      out.log(`Watching the selected tab: clicks, typing, form changes, submits and navigations${changes ? ', and what each changed on screen' : ''}`);
+      out.log(values ? 'What is typed is recorded, except in password fields; --no-values leaves it out.' : 'What is typed is not recorded (--no-values).');
       out.log(live ? 'Each step prints here once it settles; watch shows them again.' : 'watch shows what it has recorded; watch on --live also prints each step here as it happens.');
       return;
     }
@@ -491,7 +655,24 @@ const commands = {
       return;
     }
     if (!arg) return showWatch(watch, all);
-    const usage = `Usage: watch on [--changes] [--live] | watch off | watch [n] | watch new (n from 1 to ${WATCH_MAX})`;
+    if (sub === 'save') {
+      const file = arg.slice(4).trim();
+      if (!file) throw new Error('Usage: watch save <file>, e.g. watch save flow.txt; pw-repl send --file flow.txt runs it');
+      if (!watch || !watch.events.length) throw new Error('Nothing to save: watch on records the steps first');
+      if (fs.existsSync(file)) throw new Error(`${file} exists already; name another file`);
+      const { lines, skipped, variables } = savedCommands(watch, state.page);
+      const run = `${variables.map(name => `${name}=... `).join('')}pw-repl send --file ${path.basename(file)}`;
+      const header = [`# pw-repl watch, saved ${new Date().toISOString()} from ${state.page.url()}`, `# ${run} runs it; a line starting with # is not run`];
+      const where = watch.values ? 'password fields' : 'fields (watch on --no-values)';
+      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' });
+      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.`);
+      return;
+    }
+    const usage = `Usage: watch on [--changes] [--live] [--no-values] | watch off | watch [n] | watch new | watch save <file> (n from 1 to ${WATCH_MAX})`;
     const onlyNew = arg === 'new';
     if (arg && !onlyNew && !/^\d+$/.test(arg)) throw new Error(usage);
     const count = onlyNew ? RECENT_DEFAULT : Number(arg);

package/package.json

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