pw-repl 0.10.0 → 0.11.1

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 passes it along 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 };

package/lib/tabs.js

@@ -42,8 +42,9 @@ function markStartTab(p) {
 
 // A tab of the REPL's own: closing it can go back to the tab before. It opens
 // in the background, so it does not take the front of the window from the
-// person using the browser; Playwright's newPage would bring it to the front.
+// user using the browser; Playwright's newPage would bring it to the front.
 const OPEN_TIMEOUT = 10000;
+const FRONT_READ_TIMEOUT = 500;
 
 // True while tab new opens a tab: watch on --next-tab waits for one someone
 // else opens, not one a client of the REPL opens for itself.
@@ -74,7 +75,7 @@ async function openOwnTab() {
   if (!opened) opened = await ctx.newPage();
   tabState(opened).opened = true;
   tabState(opened).owner = state.client;
-  keepDrawing(opened);
+  await keepDrawing(opened);
   return opened;
 }
 
@@ -104,11 +105,24 @@ 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,
+// 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.
+async function inFront(p) {
+  if (tabState(p).focusEmulated) return null;
+  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';
+}
+
 async function listTabs() {
   const all = state.browser.contexts().flatMap(c => c.pages());
   if (state.page && !all.includes(state.page)) state.page = null;
   state.tabListing = all.slice();
   if (!all.length) { out.log('No tabs. Use tab new.'); return; }
+  const fronts = await Promise.all(all.map(inFront));
   for (const [i, p] of all.entries()) {
     let title;
     try { title = await p.title(); } catch { title = '[title unavailable]'; }
@@ -116,7 +130,7 @@ async function listTabs() {
     // URL first on its own line: it is what distinguishes otherwise
     // identically titled tabs, and titles wrap less badly when indented.
     if (i) out.log('');
-    const notes = ['start' in tabState(p) && 'the start URL', tabState(p).owner && `opened by ${tabState(p).owner}`].filter(Boolean);
+    const notes = [fronts[i], 'start' in tabState(p) && 'the start URL', tabState(p).owner && `opened by ${tabState(p).owner}`].filter(Boolean);
     out.log(`${marker} [${i}] ${p.url()}${notes.length ? `  (${notes.join(', ')})` : ''}`);
     out.log(`        ${JSON.stringify(title)}`);
   }
@@ -142,11 +156,13 @@ const commands = {
     // Matching on the URL, not an index, so a stale listing cannot point at someone else's tab.
     // Remembers where the REPL was, so closing a tab can go back there, but
     // only to a tab this REPL opened: the previous one may be someone else's.
-    const select = p => {
+    // Its focus is on before anything acts in it: a click in a tab that is not yet told it is focused
+    // can leave it drawing a frame a second (lib/cdp.js).
+    const select = async p => {
       if (p !== state.page) state.previousPage = state.page;
       state.page = p;
       ensureDialogHandler(p);
-      keepDrawing(p);
+      await keepDrawing(p);
     };
     const byUrl = part => {
       const matches = all.filter(p => p.url().includes(part));
@@ -157,7 +173,7 @@ const commands = {
     if (/^\d+$/.test(subcommand)) {
       if (parts.length) throw new Error(usage);
       const target = state.tabListing[Number(subcommand)];
-      if (target && all.includes(target)) { select(target); return commands.info(); }
+      if (target && all.includes(target)) { await select(target); return commands.info(); }
       // Not read as part of a URL instead: that could land in someone else's tab without a word.
       if (target) throw new Error(`Tab [${subcommand}] has closed since the latest listing. Run tab to list them again.`);
       // A number that is not a tab in the listing may be part of a URL (a port).
@@ -169,7 +185,7 @@ const commands = {
       }
     }
     if (subcommand === 'new') {
-      select(await openTab());
+      await select(await openTab());
       const url = parts.join(' ');
       if (url) {
         try { await commands.goto(url); }
@@ -196,7 +212,7 @@ const commands = {
       if (recording) out.log(await endedByTabClose(recording));
       return listTabs();
     }
-    select(byUrl(trimmed));
+    await select(byUrl(trimmed));
     return commands.info();
   },
 

package/lib/toast.js

@@ -0,0 +1,166 @@
+// A line of text over the page, to narrate a video or a screenshot: it stays until toast off, or for
+// --duration. One per tab; another replaces it.
+const { state, onShutdown } = require('./state');
+const out = require('./output');
+const { tabState } = require('./tabstate');
+const { unquote } = require('./syntax');
+const { takeOptions } = require('./cli-names');
+const { inOverlay, keepAcrossPages, forget } = require('./overlay');
+const { recordingOf, beforeRecordingEnds } = require('./record');
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+// While the tab records, a toast stays up at least this long (its read time) before another, toast off
+// or record off may take it down: about the pace captions are read at.
+const READ_MS_PER_WORD = 300;
+const READ_MS_MIN = 1500;
+const LONG_READ_MS = 15000;
+const DEFAULTS = { position: 'bottom', size: 24, align: 'center', color: '#fff', background: 'rgba(20, 20, 20, .85)', opacity: 1 };
+
+// Runs in the page, as the overlay's toast layer (lib/overlay.js). A new toast waits for the old one to
+// fade out, then fades in; both are waited on, but not past their time in a tab that draws no frames.
+function pageToast(overlay, { text, style, action, fade }) {
+  const { set } = overlay;
+  const old = overlay.toast;
+  const fadeTo = (el, from, to) => Promise.race([
+    el.animate([{ opacity: from }, { opacity: to }], { duration: 200, fill: 'forwards' }).finished,
+    new Promise(resolve => setTimeout(resolve, 500)),
+  ]).catch(() => {});
+  if (action === 'remove') {
+    if (!old) return;
+    delete overlay.toast;
+    return (fade ? fadeTo(old, getComputedStyle(old).opacity, 0) : Promise.resolve()).then(() => {
+      old.remove();
+      if (!overlay.toast) overlay.drop('toast');
+    });
+  }
+  const box = document.createElement('div');
+  overlay.toast = box;
+  box.textContent = text;
+  const edge = { top: { top: '6%' }, center: { top: '50%' }, bottom: { bottom: '6%' } }[style.position];
+  set(box, {
+    position: 'absolute', left: '50%', ...edge, transform: `translate(-50%, ${style.position === 'center' ? '-50%' : '0'})`,
+    'max-width': '80%', width: 'max-content', 'box-sizing': 'border-box', padding: `${Math.round(style.size * 0.5)}px ${Math.round(style.size * 0.9)}px`,
+    'border-radius': `${Math.round(style.size * 0.45)}px`, background: style.background, color: style.color, opacity: String(style.opacity),
+    font: `500 ${style.size}px/1.35 system-ui, -apple-system, 'Segoe UI', sans-serif`, 'text-align': style.align,
+    'white-space': 'pre-wrap', 'overflow-wrap': 'anywhere', 'box-shadow': '0 4px 18px rgba(0, 0, 0, .3)',
+  });
+  const out = old && fade ? fadeTo(old, getComputedStyle(old).opacity, 0) : Promise.resolve();
+  return out.then(() => {
+    old?.remove();
+    if (overlay.toast !== box) return;
+    overlay.layer('toast').append(box);
+    if (fade) return fadeTo(box, 0, style.opacity);
+  });
+}
+
+function toastOf(p) {
+  return tabState(p).toast || null;
+}
+
+// Waits out what is left of the toast's read time, while its tab records; says so, when it waited.
+async function waitToRead(p) {
+  const toast = toastOf(p);
+  if (!toast || !toast.readMs || !recordingOf(p)) return;
+  const left = toast.shownAt + toast.readMs - Date.now();
+  if (left <= 0) return;
+  await sleep(left);
+  out.log(`Waited ${(left / 1000).toFixed(1)}s for the toast's read time (the tab is recording)`);
+}
+
+async function toastOff(p, fade = true) {
+  const toast = toastOf(p);
+  if (!toast) return false;
+  clearTimeout(toast.timer);
+  delete tabState(p).toast;
+  forget(p, 'toast');
+  await inOverlay(p, pageToast, { action: 'remove', fade }, false).catch(() => {});
+  return true;
+}
+
+beforeRecordingEnds(p => (p && !p.isClosed() ? waitToRead(p) : null));
+
+// 3s, 1.5s, 800ms, or a number of milliseconds.
+function parseDuration(value) {
+  const match = /^(\d+(?:\.\d+)?)(ms|s)?$/.exec(value || '');
+  if (!match) return null;
+  return Math.round(Number(match[1]) * (match[2] === 's' ? 1000 : 1));
+}
+
+onShutdown(async () => {
+  if (!state.browser || state.connectionLost) return;
+  const pages = state.browser.contexts().flatMap(c => c.pages()).filter(p => !p.isClosed());
+  await Promise.all(pages.map(p => toastOff(p, false).catch(() => {})));
+});
+
+const commands = {
+  async toast(args) {
+    const p = state.page;
+    const line = (args || '').trim();
+    const toast = toastOf(p);
+    if (!line) {
+      out.log(toast
+        ? `A toast is up in the selected tab${toast.owner ? ` (by ${toast.owner})` : ''}: ${JSON.stringify(toast.text)}${toast.until ? `, for ${Math.max(0, Math.round((toast.until - Date.now()) / 100) / 10)}s more` : ''}; toast off hides it`
+        : 'No toast is up in the selected tab; toast <text> shows one');
+      return;
+    }
+    if (line === 'off') {
+      await waitToRead(p);
+      out.log(await toastOff(p) ? 'The toast is gone' : 'No toast was up in the selected tab');
+      return;
+    }
+    const usage = 'Usage: toast <text> [--duration=<time>] [--read-time=<time>] [--position=top|center|bottom] [--size=<px>] [--align=left|center|right] [--color=<css>] [--background=<css>] [--opacity=<0-1>] | toast off';
+    const { found, rest } = takeOptions(line, { duration: 'value', 'read-time': 'value', position: 'value', size: 'value', align: 'value', color: 'value', background: 'value', opacity: 'value' });
+    const text = unquote(rest.trim());
+    if (!text) throw new Error(usage);
+    const style = { ...DEFAULTS };
+    let duration = null;
+    let readTime = null;
+    for (const { name, value } of found) {
+      if (value === undefined || value === '') throw new Error(`--${name} needs a value: ${usage}`);
+      if (name === 'duration') {
+        duration = parseDuration(value);
+        if (!duration) throw new Error(`--duration is a time, e.g. --duration=3s or --duration=1500 (ms): ${usage}`);
+      } else if (name === 'read-time') {
+        readTime = parseDuration(value);
+        if (readTime === null) throw new Error(`--read-time is a time, e.g. --read-time=4s, or 0 for none: ${usage}`);
+      } else if (name === 'position') {
+        if (!['top', 'center', 'bottom'].includes(value)) throw new Error(`--position is top, center or bottom: ${usage}`);
+        style.position = value;
+      } else if (name === 'align') {
+        if (!['left', 'center', 'right'].includes(value)) throw new Error(`--align is left, center or right: ${usage}`);
+        style.align = value;
+      } else if (name === 'size') {
+        const size = Number(String(value).replace(/px$/, ''));
+        if (!(size >= 8 && size <= 200)) throw new Error(`--size is the text's size in pixels, 8 to 200: ${usage}`);
+        style.size = size;
+      } else if (name === 'opacity') {
+        const opacity = Number(value);
+        if (!(opacity > 0 && opacity <= 1)) throw new Error(`--opacity is above 0, up to 1: ${usage}`);
+        style.opacity = opacity;
+      } else {
+        style[name] = value;
+      }
+    }
+    if (duration && readTime !== null) throw new Error(`--duration and --read-time do not go together: a toast with a --duration ends by itself, and nothing waits for it`);
+    // Replaced, not stacked: the old one fades out, then the new one fades in.
+    if (toast) {
+      await waitToRead(p);
+      clearTimeout(toast.timer);
+    }
+    const words = text.split(/\s+/).filter(Boolean).length;
+    const readMs = duration ? 0 : readTime ?? Math.max(READ_MS_MIN, words * READ_MS_PER_WORD);
+    const shown = tabState(p).toast = { owner: state.client, text, style, until: duration ? Date.now() + duration : null, readMs, shownAt: Date.now() };
+    await inOverlay(p, pageToast, { text, style, action: 'draw', fade: true });
+    shown.shownAt = Date.now();
+    keepAcrossPages(p, 'toast', async () => { if (toastOf(p) === shown) await inOverlay(p, pageToast, { text, style, action: 'draw', fade: false }); });
+    if (duration) shown.timer = setTimeout(() => { if (toastOf(p) === shown && !p.isClosed()) toastOff(p).catch(() => {}); }, duration);
+    if (duration) { out.log(`Showing the toast for ${duration / 1000}s`); return; }
+    const why = readTime !== null ? '--read-time' : `${words} word${words === 1 ? '' : 's'}; ${READ_MS_PER_WORD}ms a word, at least ${READ_MS_MIN / 1000}s`;
+    // Past send's default 20s, the command that waits would come back unconfirmed while it still waits.
+    const long = readMs > LONG_READ_MS ? ` While recording, that one can wait up to ${readMs / 1000}s: send it with -t ${Math.ceil(readMs / 1000) + 10}.` : '';
+    out.log(`Showing the toast until toast off. ${readMs ? `Read time: ${readMs / 1000}s (${why}), which a recording waits out before the next toast, toast off or record off.${long}` : 'No read time (--read-time=0).'}`);
+  },
+};
+
+module.exports = { commands, toastOf, toastOff };