pw-repl 0.9.0 → 0.11.0

package/lib/inspect.js

@@ -12,7 +12,7 @@ const { keptSession } = require('./cdp');
 const { CDP_REFUSED } = require('./dialogs');
 const { onElement, soleSelector } = require('./elements');
 const { waitForLoad, waitForRequest } = require('./requestlog');
-const { deviceMetrics, viewportMetrics } = require('./emulation');
+const { deviceMetrics, viewportMetrics, reapplyMetrics } = require('./emulation');
 
 const SCREENSHOT_DELAY_MAX = 60;
 
@@ -51,6 +51,50 @@ async function deviceShot(device, { ref, full, type }) {
   return Buffer.from(data, 'base64');
 }
 
+// An element bigger than the viewport is taken with the page laid out again at its whole size, where
+// the page's scrollbar is gone and what was beside it moves over by its width, after the element was
+// measured: the shot came out shifted. Laid out without the scrollbar for the shot, by a stylesheet
+// adopted for it (under any CSP), the element is measured where it is taken. Someone looking at the
+// page sees its scrollbar go for a moment.
+const NO_SCROLLBAR = 'html:not([data-pw-repl])';
+async function elementShot(locator, type) {
+  const fits = await locator.evaluate(el => { const r = el.getBoundingClientRect(); return r.width <= innerWidth && r.height <= innerHeight; }, null, { timeout: 5000 });
+  if (fits) return locator.screenshot({ type, timeout: 5000 });
+  const sheet = hide => state.page.evaluate(([rule, on]) => {
+    const sheets = [...document.adoptedStyleSheets].filter(s => ![...s.cssRules].some(r => r.selectorText === rule));
+    if (on) {
+      const s = new CSSStyleSheet();
+      s.replaceSync(`${rule} { scrollbar-width: none !important; }`);
+      sheets.push(s);
+    }
+    document.adoptedStyleSheets = sheets;
+  }, [NO_SCROLLBAR, hide]);
+  await sheet(true);
+  try {
+    return await locator.screenshot({ type, timeout: 5000 });
+  } finally {
+    await sheet(false).catch(() => {});
+  }
+}
+
+// A password field's value shows in a snapshot as typed, and in html and attrs as its value attribute,
+// which some pages (React's) keep in step with it. It is left out, as watch leaves it out, so a password
+// filled in with {{ PW_PASSWORD }} stays out of the pane and the log too. These are the fields
+// watch counts as secret, but one only shown as text for now (Show password) unless its autocomplete
+// says so. A field that cannot be checked any more is taken to be one.
+const SECRET_FIELD = ['input[type=password]', ...['current-password', 'new-password', 'one-time-code', 'cc-number', 'cc-csc']
+  .map(kind => `[autocomplete~="${kind}"]`)].join(',');
+async function hideSecrets(page, text) {
+  const lines = text.split('\n');
+  for (const [i, line] of lines.entries()) {
+    const field = /^(\s*- (?:textbox|searchbox|spinbutton|combobox)\b.*\[ref=(\w+)\][^:]*): .+$/.exec(line);
+    if (!field) continue;
+    const secret = await page.locator(`aria-ref=${field[2]}`).evaluate((el, selector) => el.matches(selector), SECRET_FIELD, { timeout: 1000 }).catch(() => true);
+    if (secret) lines[i] = `${field[1]}: (a password: not shown)`;
+  }
+  return lines.join('\n');
+}
+
 // Unnamed generic nodes are layout wrappers (mostly divs): they add depth and
 // nothing to read. Drop them, lift their children, and drop cursor hints.
 function compactSnapshot(text) {
@@ -134,16 +178,23 @@ const commands = {
 
   async html(args, all) {
     const selector = soleSelector(args, 'html <selector>');
-    printOutput(await onElement(selector, () => state.page.$eval(selector, el => el.outerHTML)), all);
+    // A copy in a document of its own, where the page's code (a custom element's) does not run.
+    printOutput(await onElement(selector, () => state.page.$eval(selector, (el, secret) => {
+      const copy = document.implementation.createHTMLDocument('').importNode(el, true);
+      for (const field of [copy, ...copy.querySelectorAll('*')]) {
+        if (field.matches(secret) && field.hasAttribute('value')) field.setAttribute('value', '(a password: not shown)');
+      }
+      return copy.outerHTML;
+    }, SECRET_FIELD)), all);
   },
 
   async attrs(args, all) {
     const selector = soleSelector(args, 'attrs <selector>');
-    const result = await onElement(selector, () => state.page.$eval(selector, el => {
+    const result = await onElement(selector, () => state.page.$eval(selector, (el, secret) => {
       const out = {};
-      for (const attr of el.attributes) out[attr.name] = attr.value;
+      for (const attr of el.attributes) out[attr.name] = attr.name === 'value' && el.matches(secret) ? '(a password: not shown)' : attr.value;
       return out;
-    }));
+    }, SECRET_FIELD));
     printOutput(result, all);
   },
 
@@ -271,6 +322,8 @@ const commands = {
     // Chrome does not draw a tab that is not in front, and tabs open in the
     // background, so the tab is brought to the front for the shot.
     await state.page.bringToFront();
+    // A tab brought to the front before can be drawn at the window's size since its last navigation.
+    await reapplyMetrics(state.page);
     let image;
     const device = tabState(state.page).emulation?.device;
     try {
@@ -278,7 +331,7 @@ const commands = {
         image = await deviceShot(device, { ref, full, type });
       } else if (ref) {
         const selector = toSelector(ref);
-        image = await onElement(selector, () => state.page.locator(selector).screenshot({ type, timeout: 5000 }));
+        image = await onElement(selector, () => elementShot(state.page.locator(selector), type));
       } else {
         image = await state.page.screenshot({ fullPage: full, type });
       }
@@ -330,6 +383,7 @@ const commands = {
     } else {
       raw = await state.page.ariaSnapshot({ mode: 'ai', timeout: 5000 });
     }
+    raw = await hideSecrets(state.page, raw);
     const text = full ? raw : compactSnapshot(raw);
     if (needle !== null) {
       const hits = grepSnapshot(text, needle);
@@ -424,6 +478,11 @@ const commands = {
     const value = await withTimeout(state.page.evaluate(expression), 'Page evaluation', COMMAND_TIMEOUT);
     // An empty string is shown as one, not as no output at all.
     printOutput(value === '' ? '""' : value, all);
+    // Quotes around the whole of it, as a shell's quoting sent on, make it a string, not code to run:
+    // one plain literal only, not "a" + b or a template with ${...} in it, which ran.
+    if (typeof value === 'string' && value && /^(?:"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\$]|\\.|\$(?!\{))*`)$/s.test(args.trim())) {
+      out.log('(That is a string: the JavaScript was in quotes, which eval keeps. Without them, it runs: eval document.title)');
+    }
   },
 
   async cdp(args, all) {

package/lib/modes.js

@@ -9,8 +9,9 @@ const { emulatedKinds, setEmulation, setViewport } = require('./emulation');
 const { recordingOf, finishRecording } = require('./record');
 const { currentCapture, endCapture } = require('./capture');
 const { nextTabWanted, waitingText, stopWaitingForNextTab, stopWatching } = require('./watch');
-const { hideHighlights } = require('./elements');
+const { hideHighlights, setLabels } = require('./elements');
 const { cursorOf, cursorOff } = require('./cursor');
+const { toastOf, toastOff } = require('./toast');
 
 // The modes turned on in a tab, in the order the prompt shows them.
 function activeModes(p) {
@@ -26,7 +27,9 @@ function activeModes(p) {
   if (routes) modes.push(`routes:${routes}`);
   const highlights = tabState(p).highlights?.size;
   if (highlights) modes.push(`highlight:${highlights}`);
+  if (tabState(p).labelsOn) modes.push('labels');
   if (cursorOf(p)) modes.push('cursor');
+  if (toastOf(p)) modes.push('toast');
   if (currentCapture()?.page === p) modes.push('capture');
   if (recordingOf(p)) modes.push('record');
   return modes;
@@ -42,7 +45,7 @@ function listModes() {
   if (!on.length) {
     out.log('No modes are on in any tab.');
     out.log(hints([
-      ['watch on', 'record what the person at the browser does'],
+      ['watch on', 'record what the user at the browser does'],
       ['capture on', 'record requests and console messages together'],
       ['route <url-glob> <status> <json-body>', 'fake a response'],
       ['network off', 'cut the tab\'s network'],
@@ -76,8 +79,12 @@ function modeOwners(p) {
   if (viewport) owners.push([viewport.owner ?? null, 'viewport']);
   for (const [glob, route] of tabState(p).routes || []) owners.push([route.owner ?? null, `route ${glob}`]);
   for (const [selector, h] of tabState(p).highlights || []) owners.push([h.owner ?? null, `highlight ${selector}`]);
+  const labels = tabState(p).labelsOn;
+  if (labels) owners.push([labels.owner ?? null, 'labels']);
   const cursor = cursorOf(p);
   if (cursor) owners.push([cursor.owner ?? null, 'cursor']);
+  const toast = toastOf(p);
+  if (toast) owners.push([toast.owner ?? null, 'toast']);
   const capture = currentCapture();
   if (capture?.page === p) owners.push([capture.owner ?? null, 'capture']);
   const recording = recordingOf(p);
@@ -114,7 +121,9 @@ async function allModesOff(mine = false) {
       if ('network' in tabState(p) && ours(tabState(p).network.owner)) { await setNetwork(p, null); done.push('network on'); }
       const hidden = await hideHighlights(p, mine);
       if (hidden) done.push(`${hidden} highlight${hidden === 1 ? '' : 's'} hidden`);
+      if (tabState(p).labelsOn && ours(tabState(p).labelsOn.owner)) { await setLabels(p, false); done.push('labels off'); }
       if (cursorOf(p) && ours(cursorOf(p).owner) && await cursorOff(p)) done.push('cursor off');
+      if (toastOf(p) && ours(toastOf(p).owner) && await toastOff(p)) done.push('toast off');
       // Before the page's size is reset, which the recording would otherwise end with.
       const recording = recordingOf(p);
       if (recording && ours(recording.owner)) done.push(`record off (${(await finishRecording(recording)).replace(/\n/g, '; ')})`);

package/lib/output.js

@@ -58,7 +58,7 @@ function notice(text, page = null) {
   else log(text);
 }
 
-// Like notice, but never part of a command's answer: for what the person at
+// Like notice, but never part of a command's answer: for what the user at
 // the browser does, which is not the output of the command running now.
 function aside(text) {
   if (!sink && idlePrinter && idlePrinter.idle()) idlePrinter.print(String(text));

package/lib/overlay.js

@@ -0,0 +1,79 @@
+// What the REPL draws over a page (the cursor, a toast), each as a layer of one element of its own.
+const { tabState } = require('./tabstate');
+
+// Runs in the page. An element under <html>, not <body>, which frameworks replace, with a closed shadow
+// root, so the page's selectors, the snapshot and text do not find what is in it. It takes no pointer
+// events, so what is under it is clicked, and it is built with the DOM and inline styles, which a page's
+// Trusted Types or style-src rules do not block. It is shown as a popover, in the top layer, above the
+// page's own dialogs, as Playwright's highlight is. Kept on the document under a symbol, so each call
+// finds it again, and one the page removed is drawn again. Each layer is a box over the whole viewport,
+// in a fixed order (the cursor above a toast), whatever order they were drawn in; the element goes with
+// its last layer.
+function pageOverlay(create) {
+  const KEY = Symbol.for('pw-repl-overlay');
+  const ORDER = ['toast', 'cursor'];
+  // Important on the element in the page, whose own rules could reach it; inside, the page's cannot, and
+  // an important transform would win over an animation.
+  const set = (el, styles, important = '') => { for (const [name, value] of Object.entries(styles)) el.style.setProperty(name, value, important); };
+  let overlay = document[KEY];
+  if (!overlay || !overlay.host.isConnected) {
+    if (!create) return null;
+    const host = document.createElement('pw-repl-overlay');
+    host.setAttribute('aria-hidden', 'true');
+    host.setAttribute('popover', 'manual');
+    set(host, {
+      display: 'block', position: 'fixed', inset: '0', width: '100%', height: '100%', 'max-width': 'none',
+      'max-height': 'none', margin: '0', padding: '0', border: 'none', background: 'transparent',
+      overflow: 'visible', 'pointer-events': 'none', 'z-index': '2147483647',
+    }, 'important');
+    const root = host.attachShadow({ mode: 'closed' });
+    document.documentElement.append(host);
+    const layers = {};
+    overlay = document[KEY] = {
+      host,
+      set,
+      // A layer's box, made the first time it is asked for.
+      layer(name) {
+        if (layers[name]) return layers[name];
+        const box = document.createElement('div');
+        set(box, { position: 'absolute', inset: '0', overflow: 'visible' });
+        const after = ORDER.slice(ORDER.indexOf(name) + 1).map(n => layers[n]).find(Boolean);
+        root.insertBefore(box, after || null);
+        return (layers[name] = box);
+      },
+      has: name => !!layers[name],
+      drop(name) {
+        layers[name]?.remove();
+        delete layers[name];
+        if (Object.keys(layers).length) return;
+        host.remove();
+        delete document[KEY];
+      },
+    };
+  }
+  // Shown again, so it is above a dialog the page opened since.
+  try { overlay.host.hidePopover(); overlay.host.showPopover(); } catch {}
+  return overlay;
+}
+
+// Runs fn(overlay, args) in the page, fn a function of its own that uses nothing from here. A string,
+// so the two functions go to the page as one call; evaluated over CDP, it is not the page's own eval,
+// which a page's script-src may forbid. With create false, nothing is drawn if the overlay is not there.
+function inOverlay(p, fn, args = null, create = true) {
+  return p.evaluate(`(() => { const overlay = (${pageOverlay})(${create}); return overlay ? (${fn})(overlay, ${JSON.stringify(args)}) : undefined; })()`);
+}
+
+// A new document drops the overlay: each layer kept on the tab is drawn again by its redraw.
+function keepAcrossPages(p, name, redraw) {
+  if (!tabState(p).overlayKept) {
+    tabState(p).overlayKept = new Map();
+    p.on('domcontentloaded', () => { for (const again of tabState(p).overlayKept.values()) again().catch(() => {}); });
+  }
+  tabState(p).overlayKept.set(name, redraw);
+}
+
+function forget(p, name) {
+  tabState(p).overlayKept?.delete(name);
+}
+
+module.exports = { inOverlay, keepAcrossPages, forget };

package/lib/record.js

@@ -8,8 +8,7 @@ const out = require('./output');
 const { tabState } = require('./tabstate');
 const { clock, NO_TAB, STOPPED_RECORDING, ENDED_UNSEEN } = require('./util');
 const { shellWords, splitSelector } = require('./syntax');
-const { keptSession } = require('./cdp');
-const { deviceMetrics, viewportMetrics, settled } = require('./emulation');
+const { reapplyMetrics } = require('./emulation');
 
 const FPS = 25;
 const MAX_SECONDS = 3600;
@@ -134,13 +133,7 @@ function recordingOf(p) {
 
 async function restoreMetrics(p, rec) {
   if (rec?.finishing) return;
-  const tab = tabState(p);
-  if (!tab.viewport && !tab.emulation?.device) return;
-  const kept = await keptSession(p);
-  if (rec?.finishing) return;
-  if (tab.viewport) await viewportMetrics(kept, tab.viewport);
-  else if (tab.emulation?.device) await deviceMetrics(kept, tab.emulation.device);
-  await settled(p);
+  await reapplyMetrics(p);
 }
 
 // The tabs recording now, for the modes they count as.
@@ -408,6 +401,8 @@ function stepLabel(cmd, args) {
     const parsed = /^mouse/.test(cmd) ? null : splitSelector(words);
     return `${cmd} ${parsed ? [parsed.word, parsed.rest].filter(Boolean).join(' ') : words}`.trim();
   }
+  // A toast's text is what it said in the video, for whoever edits it.
+  if (cmd === 'toast') return `toast ${args.trim()}`.trim();
   if (!TARGET_FIRST.has(cmd)) return cmd;
   const rest = cmd === 'type' ? args.replace(/^\s*--delay(?:=|\s+)\S*\s*/, '') : args;
   const parsed = splitSelector(rest);
@@ -455,6 +450,13 @@ function cursorStep(p, what, point, ms) {
   rec.steps.push({ rec, t0, t1: t0 + ms / 1000, command: what.replace(/-?\d+(?:\.\d+)?/g, n => String(Math.round(Number(n) * rec.scale))), box: null, point: { x: scaled, y: Math.round(point.y * rec.scale) }, offSize: rec.resizedAt !== null, failed: false });
 }
 
+// Run by record off before it ends a recording, each with the recorded tab: for what the video must
+// still show first. Registered by the modules that know, which record cannot require.
+const beforeEnding = [];
+function beforeRecordingEnds(wait) {
+  beforeEnding.push(wait);
+}
+
 // The pause after an action on a recording tab, for its result to be seen (record on --pause).
 const ACTIONS = new Set([...WHOLE, ...TARGET_FIRST]);
 async function pauseAfter(p, cmd) {
@@ -623,7 +625,9 @@ const commands = {
       // Any client with the tab selected stops it, as it turns off any mode; both are told whose it was.
       const other = (rec.owner ?? null) !== (state.client ?? null);
       const clientName = c => c ?? 'the unnamed client';
-      // The tail: still page after the last action. Only record off has one; the seconds limit is a hard stop.
+      // What must be seen before the end (a toast's read time), then the tail: still page after the last
+      // action. Only record off has them; the seconds limit is a hard stop.
+      if (!rec.finishing) for (const wait of beforeEnding) await wait(state.page);
       if (!rec.finishing) await sleep(rec.pacing.tail);
       const text = await finishRecording(rec, other ? `${clientName(state.client)}'s record off ended ${clientName(rec.owner)}'s recording` : null);
       if (rec.failed) { lastEnded.get(rec.owner ?? null).reported = true; throw new Error(text); }
@@ -688,4 +692,4 @@ const commands = {
   },
 };
 
-module.exports = { commands, recordingOf, stepsOf, pauseAfter, finishRecording, endedByTabClose, findFfmpeg, jpegSize, stepStarted, stepEnded, stepTarget, cursorStep, stepLabel };
+module.exports = { commands, recordingOf, beforeRecordingEnds, stepsOf, pauseAfter, finishRecording, endedByTabClose, findFfmpeg, jpegSize, stepStarted, stepEnded, stepTarget, cursorStep, stepLabel };

package/lib/runner.js

@@ -9,6 +9,7 @@ const { activeModes } = require('./modes');
 const { NO_TAB } = require('./util');
 const { stepStarted, stepEnded, stepLabel, pauseAfter } = require('./record');
 const cliNames = require('./cli-names');
+const { expandVariables } = require('./syntax');
 
 // playwright-cli names already explained, per client: each client is told once.
 const explained = new Set();
@@ -186,8 +187,14 @@ function enqueue(line) {
 // Server commands share the prompt's queue and are echoed to the pane, so
 // someone watching sees everything an agent does.
 // client names the sender: its commands show as [server:<client>] and use its own selected tab.
-function submit(text, client = null) {
-  if (DIALOG.test(text)) return answerDialog(text, client);
+// 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.
+function submit(text, client = null, vars = null) {
+  let run = text;
+  if (vars) {
+    try { run = expandVariables(text, vars); } catch (error) { return Promise.resolve({ status: 'error', output: `Error: ${error.message}` }); }
+  }
+  if (DIALOG.test(run)) return answerDialog(text, client, run);
   if (CDP_ANSWER.test(text)) {
     console.log(`[server${client ? `:${client}` : ''}] ${text}\nError: ${CDP_REFUSED}`);
     return Promise.resolve({ status: 'error', output: `Error: ${CDP_REFUSED}` });
@@ -195,11 +202,11 @@ function submit(text, client = null) {
   return new Promise(resolve => {
     queue = queue.then(async () => {
       if (state.stopping) return resolve({ status: 'error', output: 'The REPL is shutting down.' });
-      // Printed above whatever the person at the prompt is typing, which is
+      // Printed above whatever the user at the prompt is typing, which is
       // redrawn afterwards rather than broken up.
       if (process.stdout.isTTY) { readline.clearLine(process.stdout, 0); readline.cursorTo(process.stdout, 0); }
       out.log(`[server${client ? `:${client}` : ''}] ${text}`);
-      // So the person at the prompt can bring an agent's command back with up-arrow.
+      // So the user at the prompt can bring an agent's command back with up-arrow.
       if (state.rl?.history && state.rl.history[0] !== text) {
         state.rl.history.unshift(text);
         state.rl.history.length = Math.min(state.rl.history.length, 1000);
@@ -211,7 +218,7 @@ function submit(text, client = null) {
         let result;
         const flight = { text, resolve, answered: false };
         inFlight = flight;
-        const output = await out.collect(async () => { result = await execute(text, client); });
+        const output = await out.collect(async () => { result = await execute(run, client); });
         if (inFlight === flight) inFlight = null;
         if (!flight.answered) resolve({ status: result.status, output, uncertain: result.uncertain });
       }
@@ -222,12 +229,12 @@ function submit(text, client = null) {
 
 // Outside the queue, and so outside out.collect, whose single sink belongs to
 // the command that is waiting on the dialog.
-async function answerDialog(text, client) {
+async function answerDialog(text, client, run = text) {
   console.log(`[server${client ? `:${client}` : ''}] ${text}`);
-  const translated = cliNames.translate(text);
-  const note = translated && explain(text, translated, client);
+  const translated = cliNames.translate(run);
+  const note = translated && explain(run, translated, client);
   let result;
-  try { result = { status: 'ok', output: await dialogCommand((translated?.text || text).slice(6), clientRecord(client).page) }; }
+  try { result = { status: 'ok', output: await dialogCommand((translated?.text || run).slice(6), clientRecord(client).page) }; }
   catch (error) { result = { status: 'error', output: `Error: ${error.message}` }; }
   if (note) result.output = `${note}\n${result.output}`;
   console.log(result.output);

package/lib/send.js

@@ -6,7 +6,7 @@ const fs = require('fs');
 const crypto = require('crypto');
 const { execFileSync } = require('child_process');
 const client = require('./client');
-const { shellWords } = require('./syntax');
+const { shellWords, variablesIn } = require('./syntax');
 
 // The prompt, after the modes on in the selected tab if any: (watch network:off) pw[serve]>
 const PROMPT = /^(?:\([^()]*\) )?pw(\[serve\])?>\s*$/;
@@ -113,6 +113,8 @@ function commandLine(words) {
       return words[n - 1] === '--filename' || !/^(?:\d+|-.*)$/.test(w) ? resolve(w) : w;
     });
   }
+  // watch save writes its file.
+  if (words[0] === 'watch' && words[1] === 'save' && words.length > 2) resolved = ['watch', 'save', resolve(words.slice(2).join(' '))];
   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));
   }
@@ -128,7 +130,18 @@ function commandLine(words) {
 
 // A file of commands, one per line, run in turn until one fails. A recording it started and did not
 // stop is still on: the next take would fail to start, so it says so.
-const PATHS = /^(?:upload|record|video-start|video-stop|screenshot)$/;
+const PATHS = /^(?:upload|record|video-start|video-stop|screenshot|watch)$/;
+// The values of the {{ PW_NAME }} variables in a command, from send's environment: { vars }, null with
+// none, or { error } for one that is not set or has a line break.
+function variablesFor(command) {
+  const names = variablesIn(command);
+  const unset = names.filter(name => process.env[name] === undefined);
+  const broken = names.filter(name => /[\r\n]/.test(process.env[name] || ''));
+  if (unset.length) return { error: `${unset.join(', ')} ${unset.length === 1 ? 'is' : 'are'} not set; set ${unset.length === 1 ? 'it' : 'them'} for send (${unset[0]}=... pw-repl send ...), or --no-vars sends {{ ${unset[0]} }} as it is` };
+  if (broken.length) return { error: `${broken.join(', ')} ${broken.length === 1 ? 'has' : 'have'} a line break, which a line cannot hold` };
+  return names.length ? { vars: Object.fromEntries(names.map(name => [name, process.env[name]])) } : null;
+}
+
 async function sendFile(options) {
   let text;
   try { text = fs.readFileSync(options.file, 'utf8'); } catch (error) { return fail(`cannot read ${options.file} (${error.code || error.message})`); }
@@ -141,7 +154,9 @@ 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);
     const command = PATHS.test(words[0]) ? commandLine(words) : line;
-    const status = await send({ ...options, file: null, command });
+    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 });
     if (status !== 0) {
       console.error(`pw-repl: stopped at line ${i + 1} of ${options.file} (${line}), exit status ${status}`);
       if (recording) console.error('pw-repl: record off was not reached, so the recording is still on; pw-repl send record off ends it');
@@ -159,14 +174,22 @@ async function send(options) {
   if (!command) return fail('no command given');
   // A newline would reach the REPL as a second, unmarked command.
   if (/[\r\n]/.test(command)) return fail('the command must be a single line');
+  // A command of its own, not a file's line, which sendFile has read its variables for already.
+  if (options.vars === undefined && !options.noVars) {
+    const found = variablesFor(command);
+    if (found?.error) return fail(found.error);
+    options = { ...options, vars: found?.vars || null };
+  }
   const timeoutMs = options.timeout * 1000;
   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');
   // The pane has one prompt, so a command typed there has no client of its own.
   if (way.kind === 'tmux' && options.client) return fail('-c needs the command server (pw-repl serve); a REPL in tmux has no clients');
+  // Typed into the pane, a variable's value would be on screen and in its scrollback.
+  if (way.kind === 'tmux' && options.vars) return fail(`{{ ${Object.keys(options.vars)[0]} }} needs the command server (pw-repl serve), which fills it in without showing it; --no-vars sends it as it is`);
   if (way.kind === 'tmux') return viaTmux(way.session, command, timeoutMs);
-  const answer = await client.request(way.endpoint, command, timeoutMs, name);
+  const answer = await client.request(way.endpoint, command, timeoutMs, name, options.vars || null);
   if (answer.result?.starting) return fail(`${answer.result.output} (pw-repl where says when it serves)`);
   if (answer.result) {
     if (answer.result.output) console.log(answer.result.output);

package/lib/server.js

@@ -31,7 +31,7 @@ function handle(req, res) {
   // cross-origin POST, and cannot send a JSON content type without a
   // preflight this server never answers.
   if (req.headers.origin) return send(res, 403, { status: 'error', output: 'Requests from web pages are refused' });
-  if (req.method === 'GET' && req.url === '/health') return send(res, 200, { status: state.serving ? 'ok' : 'starting', step: state.serving ? undefined : state.startingStep, browser: state.cdpUrl, launched: state.launched });
+  if (req.method === 'GET' && req.url === '/health') return send(res, 200, { status: state.serving ? 'ok' : 'starting', step: state.serving ? undefined : state.startingStep, browser: state.cdpUrl, launched: state.launched, pid: process.pid });
   if (req.method !== 'POST' || req.url !== '/run') return send(res, 404, { status: 'error', output: 'Use POST /run or GET /health' });
   if (!/^application\/json\b/.test(req.headers['content-type'] || '')) return send(res, 415, { status: 'error', output: 'Content-Type must be application/json' });
   let body = '';
@@ -43,16 +43,20 @@ function handle(req, res) {
   req.on('end', async () => {
     let command;
     let client;
-    try { ({ command, client } = JSON.parse(body)); } catch {}
+    let vars;
+    try { ({ command, client, vars } = JSON.parse(body)); } catch {}
     if (typeof command !== 'string' || !command.trim() || /[\r\n]/.test(command)) {
       return send(res, 400, { status: 'error', output: 'Body must be {"command": "<one line>"}, with "client": "<name>" if it has one' });
     }
     if (client !== undefined && client !== null && !CLIENT_NAME.test(client)) {
       return send(res, 400, { status: 'error', output: 'A client name is 1-40 letters, digits, dots, dashes and underscores' });
     }
+    if (vars !== undefined && (!vars || typeof vars !== 'object' || Object.values(vars).some(v => typeof v !== 'string' || /[\r\n]/.test(v)))) {
+      return send(res, 400, { status: 'error', output: '"vars" must be {"<NAME>": "<one line>", ...}' });
+    }
     // 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);
+    const result = await runner.submit(command.trim(), client || null, vars || null);
     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 });
@@ -69,7 +73,11 @@ async function clearStaleSocket(socketPath) {
     probe.on('connect', () => { probe.destroy(); resolve(true); });
     probe.on('error', () => resolve(false));
   });
-  if (live) throw new Error(`Another REPL is already serving on ${socketPath}`);
+  if (live) {
+    const why = await require('./background').alreadyServing(parseEndpoint(socketPath));
+    const message = why || `another REPL is already serving on ${socketPath}`;
+    throw new Error(message[0].toUpperCase() + message.slice(1));
+  }
   fs.unlinkSync(socketPath);
 }
 

package/lib/skill.js

@@ -7,7 +7,7 @@ const path = require('path');
 const FILE = path.join(__dirname, '..', 'skill', 'SKILL.md');
 const STAMP = '<!-- pw-repl skill stamp -->';
 
-// Only the skill's own text counts: not the stamp line, nor the Custom rules a person adds to a
+// Only the skill's own text counts: not the stamp line, nor the Custom rules the user adds to a
 // saved copy. Line endings are made the same first, so a Windows checkout gets the same hash.
 function hashOf(text) {
   const own = text.replace(/\r\n?/g, '\n').split('\n## Custom rules\n')[0]

package/lib/start.js

@@ -29,6 +29,9 @@ Or let pw-repl start a private one for this REPL: pw-repl run --launch (or serve
 
 async function start(options) {
   const START_URL = options.startUrl || process.env.PW_START_URL || null;
+  // First, so a terminal or a log says which pw-repl ran; where names the skill to compare a saved one with.
+  const skill = require('./skill').current();
+  out.log(`pw-repl ${skill.version} (skill ${skill.hash})`);
   if (options.pidFile) require('./background').markStopInLog();
   const serving = options.serve ? await require('./server').serve(options.endpoint) : null;
   if (options.launch) {
@@ -45,7 +48,7 @@ async function start(options) {
   state.launched = !!options.launch;
   out.log(`Connecting to ${CDP_URL}...`);
   state.startingStep = 'connecting to the browser';
-  try { state.browser = await chromium.connectOverCDP(CDP_URL, { timeout: CONNECT_TIMEOUT }); }
+  try { state.browser = await chromium.connectOverCDP(CDP_URL, { timeout: CONNECT_TIMEOUT, noDefaults: true }); }
   catch (error) { throw new Error(connectHelp(error)); }
   if (state.stopping) {
     try { await withTimeout(state.browser.close(), 'Chromium shutdown'); }

package/lib/syntax.js

@@ -54,4 +54,33 @@ function keyName(key) {
   return key.split(/\+(?!$)/).map(part => (part.length > 1 ? KEYS.get(part.toLowerCase()) || part : part)).join('+');
 }
 
-module.exports = { SELECTOR_FIRST, REF, toSelector, unquote, shellWords, splitSelector, keyName };
+// {{ PW_NAME }} in a command send sends: a variable from the sender's environment. The REPL fills it in
+// as it runs the line, so its pane and log show the line as written. Only PW_ names: {{ name }} is common
+// in a page's own text (a template's), which send must neither fail on nor fill with one of the
+// sender's own secrets (GITHUB_TOKEN). In double quotes the value is
+// escaped as they read it (a JS string's too); anywhere else it goes in as it is. Single quotes escape
+// nothing, so a value with one cannot go in them: refused, naming the variable, since a page or eval error
+// that quoted the broken line would show the value.
+const VARIABLE = /\{\{\s*(PW_\w+)\s*\}\}/g;
+
+function variablesIn(line) {
+  return [...new Set([...line.matchAll(VARIABLE)].map(m => m[1]))];
+}
+
+// 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`);
+    return values[name];
+  };
+  return line.replace(new RegExp(`"(?:[^"\\\\]|\\\\.)*"|'[^']*'|${VARIABLE.source}`, 'g'), (whole, name) => {
+    if (name) return value(name);
+    if (whole[0] === '"') return whole.replace(VARIABLE, (_, inner) => value(inner).replace(/[\\"]/g, '\\$&'));
+    return whole.replace(VARIABLE, (_, inner) => {
+      if (value(inner).includes("'")) throw new Error(`{{ ${inner} }} holds a ', which single quotes cannot hold: put it in double quotes`);
+      return value(inner);
+    });
+  });
+}
+
+module.exports = { SELECTOR_FIRST, REF, toSelector, unquote, shellWords, splitSelector, keyName, variablesIn, expandVariables };