pw-repl 0.4.2 → 0.6.0

package/lib/skill.js

@@ -0,0 +1,29 @@
+// The agent skill, stamped as it is printed with the version it came from and a hash of its text,
+// so a saved copy can be told apart from the skill of the pw-repl being run.
+const crypto = require('crypto');
+const fs = require('fs');
+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
+// 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]
+    .split('\n').filter(line => line !== STAMP && !/^This skill is from pw-repl /.test(line)).join('\n').trimEnd();
+  return crypto.createHash('sha256').update(own).digest('hex').slice(0, 8);
+}
+
+function current() {
+  const text = fs.readFileSync(FILE, 'utf8');
+  return { text, hash: hashOf(text), version: require('../package.json').version };
+}
+
+// What `pw-repl skill` prints.
+function stamped() {
+  const { text, hash, version } = current();
+  return text.replace(STAMP, `This skill is from pw-repl ${version} (skill ${hash}).`);
+}
+
+module.exports = { STAMP, hashOf, current, stamped };

package/lib/start.js

@@ -3,7 +3,8 @@ const { chromium } = require('playwright-core');
 const readline = require('readline');
 const { state, withTimeout, shutdown, onBeforeExit, beforeExit } = require('./state');
 const out = require('./output');
-const { listTabs, openTab, startTabs, watchPage, complete } = require('./commands');
+const { watchPage, complete } = require('./commands');
+const { listTabs, openTab, markStartTab } = require('./tabs');
 const runner = require('./runner');
 
 // A browser --launch starts has its own address instead.
@@ -29,7 +30,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;
   if (options.pidFile) require('./background').markStopInLog();
+  const serving = options.serve ? await require('./server').serve(options.endpoint) : null;
   if (options.launch) {
+    state.startingStep = 'launching a Chromium of its own';
     const launched = await require('./launch').launch({ headed: options.headed, extraArgs: options.chromeArgs });
     onBeforeExit(launched.stop);
     CDP_URL = launched.url;
@@ -41,6 +44,7 @@ async function start(options) {
   state.cdpUrl = CDP_URL;
   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 }); }
   catch (error) { throw new Error(connectHelp(error)); }
   if (state.stopping) {
@@ -67,13 +71,14 @@ async function start(options) {
 
   // Hooks first, so the start URL's own requests, logs and dialogs are recorded.
   for (const ctx of contexts) {
-    ctx.on('page', watchPage);
-    ctx.pages().forEach(watchPage);
+    ctx.on('page', p => watchPage(p, true));
+    ctx.pages().forEach(p => watchPage(p));
   }
 
   if (START_URL) {
+    state.startingStep = 'opening the start URL';
     state.page = await openTab();
-    startTabs.add(state.page);
+    markStartTab(state.page);
     await state.page.goto(START_URL, { waitUntil: 'networkidle', timeout: 15000 });
     out.log(`Opened ${state.page.url()} in a new tab`);
   }
@@ -82,7 +87,7 @@ async function start(options) {
   await listTabs();
   out.log('');
   if (!state.page) out.log('No tab is selected: tab new [url] opens one of your own, tab <index|url-part> selects one.');
-  if (options.serve) await require('./server').serve(options.endpoint);
+  if (serving) serving();
   // In the background there is no prompt: commands come only through the server.
   if (options.pidFile) {
     require('./background').claimPidFile(options.pidFile);

package/lib/state.js

@@ -14,6 +14,9 @@ const state = {
   // The browser the REPL is connected to, and whether --launch started it.
   cdpUrl: null,
   launched: false,
+  // The command server takes commands; before, it answers that the REPL is starting, and what it is doing.
+  serving: false,
+  startingStep: 'starting',
   stopping: false,
   connectionLost: false,
   shutdownFailed: false,
@@ -26,6 +29,8 @@ const state = {
 const PER_CLIENT = { page: null, previousPage: null, tabListing: [], previousCommandAt: 0, currentCommandAt: 0 };
 const clients = new Map();
 
+out.onSelectedTab(() => state.page);
+
 function clientRecord(name = state.client) {
   if (!clients.has(name)) clients.set(name, { ...PER_CLIENT, tabListing: [] });
   return clients.get(name);

package/lib/tabs.js

@@ -0,0 +1,237 @@
+// Tabs: listing, selecting, opening and closing them, and navigating the selected one.
+const { state } = require('./state');
+const out = require('./output');
+const { hints } = require('./util');
+const { tabState } = require('./tabstate');
+const { keepDrawing } = require('./cdp');
+const { ensureDialogHandler } = require('./dialogs');
+const { notLoaded, stayedPut } = require('./requestlog');
+const { viewportText } = require('./emulation');
+
+// A navigation that does not load is said as wait load says it, from its request, rather than as
+// Playwright's net:: error and call log.
+async function navigating(go) {
+  const started = Date.now();
+  try {
+    return await go();
+  } catch (error) {
+    if (!/net::ERR_/.test(error.message)) throw error;
+    const find = () => (tabState(state.page).log || []).filter(e => e.navigation && e.t >= started && e.failed && e.status !== 'pending').pop();
+    for (let waited = 0; !find() && waited < 1000; waited += 50) await new Promise(resolve => setTimeout(resolve, 50));
+    const navigation = find();
+    if (!navigation) throw error;
+    throw new Error(notLoaded(navigation));
+  }
+}
+
+// A page restored from the back/forward cache never fires its load events
+// again, so back and forward wait only for the navigation, then briefly for
+// the document to be parsed, which a restored one already is.
+async function historyStep(go, direction) {
+  const before = state.page.url();
+  const response = await navigating(go);
+  if (response === null && state.page.url() === before) throw new Error(`No page to go ${direction} to`);
+  await state.page.waitForFunction(() => document.readyState !== 'loading', null, { timeout: 3000 }).catch(() => {});
+}
+
+// The tab the REPL opened for its start URL, which tab marks: in a kept profile it sits among restored tabs.
+function markStartTab(p) {
+  tabState(p).start = true;
+}
+
+// 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.
+const OPEN_TIMEOUT = 10000;
+
+// 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.
+let opening = false;
+
+function isOpening() {
+  return opening;
+}
+
+async function openTab() {
+  opening = true;
+  try { return await openOwnTab(); } finally { opening = false; }
+}
+
+async function openOwnTab() {
+  const ctx = state.browser.contexts()[0];
+  let opened = null;
+  const session = await state.browser.newBrowserCDPSession().catch(() => null);
+  if (session) {
+    try {
+      const { targetId } = await session.send('Target.createTarget', { url: 'about:blank', background: true });
+      opened = await pageForTarget(ctx, targetId);
+    } catch {} finally {
+      await session.detach().catch(() => {});
+    }
+  }
+  // A browser that cannot open one in the background (e.g. some headless ones) opens it as usual.
+  if (!opened) opened = await ctx.newPage();
+  tabState(opened).opened = true;
+  tabState(opened).owner = state.client;
+  keepDrawing(opened);
+  return opened;
+}
+
+// A page's CDP target id, asked for once per page.
+async function targetIdOf(ctx, p) {
+  if (!('targetId' in tabState(p))) {
+    const cdp = await ctx.newCDPSession(p).catch(() => null);
+    if (!cdp) return null;
+    const info = await cdp.send('Target.getTargetInfo').catch(() => null);
+    await cdp.detach().catch(() => {});
+    if (!info) return null;
+    tabState(p).targetId = info.targetInfo.targetId;
+  }
+  return tabState(p).targetId;
+}
+
+async function pageForTarget(ctx, targetId) {
+  const deadline = Date.now() + OPEN_TIMEOUT;
+  while (Date.now() < deadline) {
+    for (const p of ctx.pages()) {
+      if ('opened' in tabState(p)) continue;
+      if (await targetIdOf(ctx, p) === targetId) return p;
+    }
+    await new Promise(resolve => setTimeout(resolve, 50));
+  }
+  return null;
+}
+
+// Every tab, URL first, with * on the selected one. The numbers are what tab <index> uses.
+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; }
+  for (const [i, p] of all.entries()) {
+    let title;
+    try { title = await p.title(); } catch { title = '[title unavailable]'; }
+    const marker = p === state.page ? '*' : ' ';
+    // 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);
+    out.log(`${marker} [${i}] ${p.url()}${notes.length ? `  (${notes.join(', ')})` : ''}`);
+    out.log(`        ${JSON.stringify(title)}`);
+  }
+}
+
+const commands = {
+  async tab(args) {
+    const trimmed = (args || '').trim();
+    if (!trimmed) {
+      await listTabs();
+      if (!state.page) out.log('\nNo tab is selected.');
+      out.log(hints([
+        ['tab <index|url-part>', 'select a tab'],
+        ['tab new [url]', 'open a tab of your own and select it'],
+        ['tab close [url-part]', 'close the selected tab, or the one whose URL contains url-part'],
+      ]));
+      return;
+    }
+    const usage = 'Usage: tab [<index> | <url-part> | new [url] | close [<url-part>]]';
+    const parts = trimmed.split(/\s+/);
+    const subcommand = parts.shift();
+    const all = state.browser.contexts().flatMap(c => c.pages());
+    // 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 => {
+      if (p !== state.page) state.previousPage = state.page;
+      state.page = p;
+      ensureDialogHandler(p);
+      keepDrawing(p);
+    };
+    const byUrl = part => {
+      const matches = all.filter(p => p.url().includes(part));
+      if (matches.length === 1) return matches[0];
+      if (!matches.length) throw new Error(`No tab URL contains "${part}"`);
+      throw new Error(`${matches.length} tabs match "${part}"; use a longer part:\n${matches.map(p => `  ${p.url()}`).join('\n')}`);
+    };
+    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(); }
+      // 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).
+      const containing = all.filter(p => p.url().includes(subcommand)).length;
+      if (!containing) throw new Error(`No tab [${subcommand}] in the latest listing, and no tab URL contains ${subcommand}. Run tab to list them.`);
+      if (containing > 1) {
+        const listing = state.tabListing.length ? 'the latest listing' : 'a listing yet: each client has its own, from tab';
+        throw new Error(`No tab [${subcommand}] in ${listing}. As part of a URL, ${subcommand} is in ${containing} tabs. Run tab, then tab <index>.`);
+      }
+    }
+    if (subcommand === 'new') {
+      select(await openTab());
+      const url = parts.join(' ');
+      if (url) {
+        try { await commands.goto(url); }
+        catch (error) { throw new Error(`${error.message}\nThe new tab stays open and selected; tab close closes it.`); }
+      } else {
+        out.log('New tab created and selected');
+      }
+      return listTabs();
+    }
+    if (subcommand === 'close') {
+      const target = parts.length ? byUrl(parts.join(' ')) : state.page;
+      if (!target || target.isClosed() || !all.includes(target)) throw new Error('Selected tab is unavailable. Run tab again.');
+      if (all.length <= 1) throw new Error('Refusing to close the last tab');
+      const url = target.url();
+      const wasSelected = target === state.page;
+      await target.close();
+      if (wasSelected) {
+        const back = state.previousPage;
+        state.page = back && !back.isClosed() && 'opened' in tabState(back) ? back : null;
+        state.previousPage = null;
+      }
+      out.log(`Closed ${url}${wasSelected && !state.page ? '; no tab is selected now' : ''}`);
+      return listTabs();
+    }
+    select(byUrl(trimmed));
+    return commands.info();
+  },
+
+  async goto(args) {
+    if (!args) throw new Error('Usage: goto <url>');
+    let url = args;
+    // As a browser's address bar does: a local dev server is almost always plain http.
+    const local = /^(?:localhost|127(?:\.\d+){3}|\[::1\]|0\.0\.0\.0)(?:[:/?#]|$)/i.test(url);
+    if (!/^[a-z][a-z\d+.-]*:\/\//i.test(url) && !/^(about|data|file|javascript):/i.test(url)) url = `${local ? 'http' : 'https'}://${url}`;
+    await navigating(() => state.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 15000 }));
+    out.log(`${state.page.url()} — ${await state.page.title()}`);
+  },
+
+  async back() {
+    await historyStep(() => state.page.goBack({ waitUntil: 'commit', timeout: 10000 }), 'back');
+    out.log(`Back to: ${state.page.url()}`);
+  },
+
+  async forward() {
+    await historyStep(() => state.page.goForward({ waitUntil: 'commit', timeout: 10000 }), 'forward');
+    out.log(`Forward to: ${state.page.url()}`);
+  },
+
+  async reload() {
+    await navigating(() => state.page.reload({ waitUntil: 'domcontentloaded', timeout: 15000 }));
+    out.log(`Reloaded: ${state.page.url()}`);
+  },
+
+  async info() {
+    out.log(`  URL:   ${state.page.url()}`);
+    // Chrome's error page has a URL of its own; the one that failed is in the request log.
+    if (state.page.url().startsWith('chrome-error://')) {
+      const failed = (tabState(state.page).log || []).filter(e => e.navigation && e.failed && !stayedPut(e)).pop();
+      if (failed) out.log(`  Error: Chrome's error page, for #${failed.id} ${failed.url} ${failed.status}`);
+    }
+    out.log(`  Title: ${await state.page.title()}`);
+    out.log(`  Viewport: ${await viewportText()}`);
+  },
+};
+
+module.exports = { commands, markStartTab, isOpening, openTab, listTabs };

package/lib/tabstate.js

@@ -0,0 +1,35 @@
+// Everything the REPL keeps about a tab, in one record per page. A WeakMap, so a closed page's
+// record goes with it: the shutdown cleanups walk the browser's pages instead of the records.
+//   dialogHandled  its dialog handler is on
+//   session        the CDP session kept for it (a promise)
+//   drawing        it is kept drawing in the background
+//   targetId       its CDP target id
+//   networkEnabled its CDP session has Network on
+//   network        how its network is changed: { offline: true }, or slowed { latency, down, up }
+//                  (ms, kbps), with the owner
+//   emulation      what emulate changed: { device, scheme, locale, timezone }, each unset when off,
+//                  with the owner
+//   routes         Map(glob -> { status, body, handler, owner })
+//   log            its recent requests (requests)
+//   consoleLog     its recent console messages and page errors (console)
+//   loadedAt       when its page last fired its load event
+//   bodiesDurable  the browser keeps its response bodies after it navigates
+//   opened         this REPL opened it with tab new
+//   owner          the client that opened it (null: the prompt, or a sender without a name)
+//   start          the REPL opened it for its start URL
+//   watch          its watch: the steps recorded, and whether it is on
+//   watchStarting  its watch on --next-tab is still starting: the page can load before it is ready
+//   watchBinding   its binding's record function; the binding is added once per tab
+const tabStates = new WeakMap();
+
+function tabState(p) {
+  // No tab selected: an empty record, as a WeakMap's get finds nothing. It is not kept, so a
+  // write to it is lost (a WeakMap's set would throw): the runner keeps commands that need a tab
+  // from running without one, and nothing may rely on it holding anything.
+  if (!p) return {};
+  let record = tabStates.get(p);
+  if (!record) tabStates.set(p, record = {});
+  return record;
+}
+
+module.exports = { tabState };

package/lib/util.js

@@ -0,0 +1,49 @@
+// Small helpers the commands share: output hints, clipping, times, patterns and number arguments.
+
+const COMMAND_TIMEOUT = 15000;
+
+const MAX_EVENT_TEXT = 4000;
+
+// For a command that needs a tab, when none is selected.
+const NO_TAB = 'No tab is selected; select one with tab <index|url-part>, or open one with tab new';
+
+// What a command run on its own prints after its state: the commands that
+// come next, set apart from the state by a blank line.
+function hints(pairs) {
+  const width = Math.max(...pairs.map(([command]) => command.length));
+  return `\n${pairs.map(([command, what]) => `  ${command.padEnd(width)}  ${what}`).join('\n')}`;
+}
+
+function clipText(text) {
+  return text.length > MAX_EVENT_TEXT ? `${text.slice(0, MAX_EVENT_TEXT)}…` : text;
+}
+
+function numbers(args, usage) {
+  const words = (args || '').trim().split(/\s+/).filter(Boolean);
+  if (words.some(w => !/^-?\d+(?:\.\d+)?$/.test(w))) throw new Error(`Usage: ${usage}, in numbers of CSS pixels`);
+  return words.map(Number);
+}
+
+// For --regex, as playwright-cli's find --regex and requests --filter take one.
+function regexOf(pattern) {
+  try { return new RegExp(pattern); } catch (error) { throw new Error(`Not a regular expression: ${error.message}`); }
+}
+
+// A pattern without its quotes, and with \" inside them as ", as snapshot
+// reads one: other backslashes are the regexp's own (\d).
+function patternText(text) {
+  return text.replace(/^(["'])(.*)\1$/, '$2').replace(/\\"/g, '"');
+}
+
+// Local time with its offset (18:16:15.721-06:00), so it reads against the
+// user's clock and is still unambiguous.
+function clock(t) {
+  const d = new Date(t);
+  const pad = (n, width = 2) => String(n).padStart(width, '0');
+  const offset = -d.getTimezoneOffset();
+  const sign = offset < 0 ? '-' : '+';
+  const zone = `${sign}${pad(Math.floor(Math.abs(offset) / 60))}:${pad(Math.abs(offset) % 60)}`;
+  return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}${zone}`;
+}
+
+module.exports = { COMMAND_TIMEOUT, MAX_EVENT_TEXT, NO_TAB, hints, clipText, numbers, regexOf, patternText, clock };