@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/preflight.ts

@@ -0,0 +1,76 @@
+// F074.2 — Lens pre-flight.
+//
+// Pure, cheap checks run BEFORE launching a browser so a verify failure
+// means "the surface is wrong", not "the dev-server wasn't up" or
+// "Chromium isn't installed". Without this a forgotten `pnpm dev` reads as
+// a red AC — a false fail that erodes trust in the whole gate.
+
+import { chromiumExpectation, chromiumGapReason, ensureChromium } from './ensure-chromium.ts';
+
+export interface PreflightResult {
+  ok: boolean;
+  checks: {
+    playwright_installed: boolean;
+    target_reachable: boolean;
+  };
+  /** Present when ok === false: the first failing reason, caller-actionable. */
+  reason?: string;
+  http_status?: number;
+}
+
+/** Can we reach the target at all? A GET with a short timeout. Any HTTP
+ *  response (even 4xx/5xx) proves the server is up — only a connection
+ *  failure / timeout means "not reachable". */
+async function targetReachable(
+  url: string,
+  timeoutMs: number,
+): Promise<{ reachable: boolean; status?: number; error?: string }> {
+  try {
+    const res = await fetch(url, {
+      method: 'GET',
+      redirect: 'manual',
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return { reachable: true, status: res.status };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    // A TLS cert error (self-signed / mkcert dev-server, e.g. cms-admin :3010)
+    // means the handshake REACHED the server — it IS up, which is all preflight
+    // checks. The browser context ignores HTTPS errors at capture time, so don't
+    // fail preflight on a cert it would otherwise accept.
+    if (/certificate|self.?signed|unable to verify|ERR_TLS|SSL|DEPTH_ZERO/i.test(msg)) {
+      return { reachable: true };
+    }
+    return { reachable: false, error: msg };
+  }
+}
+
+export async function preflight(url: string, timeoutMs = 5_000): Promise<PreflightResult> {
+  const exp = chromiumExpectation();
+  if (!exp.installed) {
+    // lens-gap 019efc0e — kick off a self-provision in the background (deduped:
+    // boot may already be installing) and hand back an actionable reason naming
+    // the EXACT revision + path, so a retry succeeds without operator action.
+    void ensureChromium();
+    return {
+      ok: false,
+      checks: { playwright_installed: false, target_reachable: false },
+      reason: chromiumGapReason(exp),
+    };
+  }
+
+  const reach = await targetReachable(url, timeoutMs);
+  if (!reach.reachable) {
+    return {
+      ok: false,
+      checks: { playwright_installed: true, target_reachable: false },
+      reason: `target unreachable: ${url} (${reach.error}) — is the dev-server running?`,
+    };
+  }
+
+  return {
+    ok: true,
+    checks: { playwright_installed: true, target_reachable: true },
+    http_status: reach.status,
+  };
+}

package/src/readiness.ts

@@ -0,0 +1,282 @@
+// F213.8 — "is this page LISTENING?", without asking which framework it is.
+//
+// THE DEFECT THIS EXISTS FOR. The browser renders and owns form controls itself,
+// so a value written before the app's scripts attach lands in the DOM perfectly
+// and is readable back — while nothing ever hears it. F213.7's read-back asks
+// the ELEMENT; the element is not the APPLICATION. sanne lost three runs to this
+// and nearly filed a real product defect as a test flake.
+//
+// THE SIGNAL. Not a heuristic, and not a framework sniff: an event is heard iff
+// something is registered for it on the target or somewhere on its propagation
+// path. So we observe the DOM API that does the registering —
+// `EventTarget.prototype.addEventListener` — from an init script that runs
+// BEFORE any page script, and later ask whether anything on the path registered.
+//
+// WHY NOT CDP `DOMDebugger.getEventListeners`, which is the obvious answer:
+// it is Chromium-only, and this daemon also runs webkit and firefox (browser.ts
+// ENGINES). A gate that silently does nothing on two of three engines is an
+// absent guard that looks present — the exact shape the rest of this epic exists
+// to remove. addInitScript is engine-agnostic.
+//
+// WHY IT COVERS REACT WITHOUT KNOWING ABOUT REACT: React 17+ delegates, binding
+// one listener on the root container rather than per element. Walking the
+// ancestor path to document+window finds that listener, because that is the same
+// path the event itself would travel. Anything that hears the event is on it.
+
+/** Event types that carry a user's edit into an application.
+ *
+ *  MEASURED, and it is why `click` is NOT in here: `click` is bound on
+ *  `document` by almost every page (and by our own injected scripts), so
+ *  including it made the probe answer "listening" on a page that had not run a
+ *  line of its own code. A probe that is always true is not a probe. The
+ *  question is per-action — "is anything listening for the events THIS step will
+ *  dispatch?" — so a verb that clicks should ask for `click` explicitly rather
+ *  than have it folded into the default. */
+export const EDIT_EVENTS = ['input', 'change'] as const;
+
+/** How often to re-ask while waiting. Small enough that an already-listening
+ *  page pays roughly nothing (measured: it answers on the first poll, ~60-210ms
+ *  after navigation), large enough not to spin. */
+const POLL_MS = 50;
+
+/**
+ * Installed via `context.addInitScript` before any page script.
+ *
+ * It WRAPS, never blocks: the original is always called, and every bookkeeping
+ * step is inside try/catch. A readiness probe that could break the page it is
+ * measuring would be worse than no probe — this runs on every flow, including
+ * ones that never ask about readiness.
+ */
+export const READINESS_INIT_SCRIPT = `(() => {
+  try {
+    if (window.__lensListenerReg) return;
+    var reg = new WeakMap();
+    var origAdd = EventTarget.prototype.addEventListener;
+    Object.defineProperty(window, '__lensListenerReg', { value: reg, configurable: false, enumerable: false });
+    EventTarget.prototype.addEventListener = function (type) {
+      try {
+        var s = reg.get(this);
+        if (!s) { s = new Set(); reg.set(this, s); }
+        s.add(String(type));
+      } catch (e) {}
+      return origAdd.apply(this, arguments);
+    };
+  } catch (e) {}
+})();`;
+
+/**
+ * Page-side expression: is anything listening for `events` on `selector`'s
+ * propagation path?
+ *
+ * Returns a discriminated result rather than a bare boolean, because the three
+ * "no" answers need different messages: the element is not there yet, nothing is
+ * listening yet, or WE were never installed (in which case a `false` would be an
+ * instrument failure reported as a page verdict — the failure mode this whole
+ * epic keeps finding).
+ */
+export function readinessProbeExpr(selector: string, events: readonly string[] = EDIT_EVENTS): string {
+  const sel = JSON.stringify(selector);
+  const evs = JSON.stringify([...events]);
+  return `(${readinessOfElement.toString()})(document.querySelector(${sel}), ${evs})`;
+}
+
+/**
+ * The walk itself, as a REAL function so both callers can share one definition.
+ *
+ * ONE definition, two callers (F074.99). `waitForReady` asks by selector, via the
+ * expression above; `fill` hands this function straight to `locator.evaluate`, so
+ * it probes the exact element it is about to write to — not the same question
+ * when a selector matches several, because re-querying would probe one element
+ * and write to another.
+ *
+ * MEASURED, and it is why this is a function and not a string: Playwright's
+ * `locator.evaluate` does NOT call a string page-function with the element. All
+ * four shapes we tried — one-liner, braces, multiline, multiline-with-comment —
+ * returned `undefined` rather than throwing. A silent `undefined` read as a
+ * readiness verdict is exactly the false-green this card exists to remove.
+ *
+ * So it must stay SELF-CONTAINED: it is serialized into the page by `toString()`,
+ * and anything it closes over is not there. Same contract as `isEditableElement`.
+ */
+export function readinessOfElement(el: Element | null, want: readonly string[]): ReadinessResult {
+  const reg = (window as unknown as { __lensListenerReg?: WeakMap<object, Set<string>> }).__lensListenerReg;
+  if (!reg) return { state: 'uninstrumented' };
+  if (!el) return { state: 'no-element' };
+  // The propagation path: the element, every ancestor, then document + window.
+  // Delegated frameworks register at the top of it.
+  for (let n: Node | null = el; n; n = n.parentNode) {
+    const s = reg.get(n);
+    if (s) { for (let i = 0; i < want.length; i++) if (s.has(want[i]!)) return { state: 'listening', via: 'path', event: want[i] }; }
+  }
+  const tops: object[] = [document, window];
+  for (let j = 0; j < tops.length; j++) {
+    const ts = reg.get(tops[j]!);
+    if (ts) { for (let k = 0; k < want.length; k++) if (ts.has(want[k]!)) return { state: 'listening', via: 'delegated', event: want[k] }; }
+  }
+  // addEventListener is not the only way to register. An inline onchange="" or
+  // a direct el.oninput = fn never passes through our wrapper, and a page using
+  // them IS listening — reporting "not ready" there would hang a working flow.
+  for (let m = 0; m < want.length; m++) {
+    if (typeof (el as unknown as Record<string, unknown>)['on' + want[m]] === 'function') return { state: 'listening', via: 'property', event: want[m] };
+  }
+  return { state: 'not-listening' };
+}
+
+export type ReadinessState = 'listening' | 'not-listening' | 'no-element' | 'uninstrumented';
+export type ReadinessResult = { state: ReadinessState; via?: string; event?: string };
+
+/**
+ * Turn a probe result + how long we waited into the message the author reads.
+ *
+ * Pure and exported so the wording is testable without a browser — and because
+ * AC6 is specifically about the MESSAGE: a page that never becomes interactive
+ * has to say so, instead of producing a generic timeout that reads exactly like
+ * a mistyped selector.
+ */
+export function readinessFailure(r: ReadinessResult, selector: string, waitedMs: number, events: readonly string[]): string {
+  if (r.state === 'no-element') {
+    return `waitForReady: no element matched ${selector} within ${waitedMs}ms — readiness was never tested (this is a selector problem, not a hydration problem)`;
+  }
+  if (r.state === 'uninstrumented') {
+    // The instrument failed, and saying "not ready" here would report an
+    // instrument failure as a page verdict — the exact confusion this epic keeps
+    // finding. Name it as ours.
+    return `waitForReady: the listener observer was not installed on this page, so readiness cannot be judged — this is a Lens fault, not a page fault (init script missing; a page reached via a context Lens did not create, e.g. the flat/engine runner)`;
+  }
+  return `waitForReady: ${selector} exists and is rendered, but nothing is listening for ${events.join('/')} on its propagation path after ${waitedMs}ms — the page painted but its scripts never attached. A write here would land in the DOM and be silently lost.`;
+}
+
+/** What a readiness wait concluded. The failing half carries the STATE, not just
+ *  a message: a caller that must decide whether to act (F074.99's `fill`) needs
+ *  to tell "nothing is listening" — a verdict about the page — from "no element
+ *  yet" and "we were never installed", which are not verdicts about the page at
+ *  all. String-matching the message to recover that would be the same mistake
+ *  InstrumentError exists to avoid. */
+export type ListeningVerdict =
+  | { ok: true; waitedMs: number; via: string }
+  | { ok: false; error: string; state: ReadinessState; waitedMs: number; answered: boolean };
+
+/**
+ * Wait until the page is actually listening for `events` on `selector`.
+ *
+ * NOT a fixed sleep (AC3): the floor is "whatever this page's hydration costs on
+ * this machine", which sanne showed is unknowable in advance — her workaround
+ * `assert performance.now() > 3000` is green on a fast machine and red in CI,
+ * and that is the failure mode being replaced.
+ *
+ * On an already-listening page this returns on the FIRST poll (measured ~60-210ms
+ * after navigation, which is the poll interval, not a wait) so it cannot become
+ * the blanket delay AC5 forbids.
+ */
+export async function waitForListening(
+  page: { evaluate: (expr: string) => Promise<unknown> },
+  selector: string,
+  events: readonly string[],
+  timeoutMs: number,
+): Promise<ListeningVerdict> {
+  const expr = readinessProbeExpr(selector, events);
+  return waitForListeningOn(
+    () => page.evaluate(expr).then((v) => v as ReadinessResult).catch(() => null),
+    selector,
+    events,
+    timeoutMs,
+  );
+}
+
+/**
+ * The same wait, driven by whatever way the caller can ask the page ONCE.
+ *
+ * Exists so `fill` can ask through the LOCATOR it is about to write to, instead
+ * of re-querying a selector that might resolve to a different element (F074.99).
+ * `pollOnce` returns null for "no answer this round" — a rejection, a navigation
+ * mid-poll, a detached element — and the loop's deadline is what ends it.
+ */
+export async function waitForListeningOn(
+  pollOnce: () => Promise<ReadinessResult | null>,
+  selector: string,
+  events: readonly string[],
+  timeoutMs: number,
+): Promise<ListeningVerdict> {
+  const started = Date.now();
+  // THE SEED IS A GUESS, NOT AN ANSWER, and a caller that ACTS on the verdict has
+  // to be able to tell (F074.99). If every poll rejects — a locator that matches
+  // several elements, a detached node, a page navigating on every tick — the loop
+  // ends holding this seed, and reporting it as "the page is not listening" would
+  // be a verdict about the page derived from never having asked it.
+  let last: ReadinessResult = { state: 'not-listening' };
+  let answered = false;
+  for (;;) {
+    // TWO WAYS THE PROBE ITSELF CAN FAIL, and neither may take the run with it:
+    //
+    //  · the page navigates mid-poll → Playwright rejects with "Execution context
+    //    was destroyed". That is not a readiness verdict, it is the page moving
+    //    under us; the honest response is to ask again on the new document.
+    //  · `page.evaluate` has NO default timeout in Playwright, so a page busy in a
+    //    synchronous loop would hang here FOREVER — straight past the caller's
+    //    timeout. A gate that hangs is worse than one that fails: the author gets
+    //    no verdict at all and the flow never ends.
+    //
+    // Both collapse to "no answer this round". The loop's own deadline below is
+    // what ends it, so a caller's timeout_ms is always the wall clock.
+    const raced = await Promise.race([
+      pollOnce(),
+      new Promise<null>((r) => setTimeout(() => r(null), Math.max(POLL_MS, Math.min(2_000, timeoutMs)))),
+    ]);
+    if (raced) { last = raced; answered = true; }
+    if (last.state === 'listening') return { ok: true, waitedMs: Date.now() - started, via: last.via ?? 'path' };
+    // An uninstrumented page will never become instrumented by waiting — the
+    // init script runs at navigation or not at all. Failing fast here keeps a
+    // Lens fault from being reported as a slow page.
+    if (last.state === 'uninstrumented') break;
+    if (Date.now() - started >= timeoutMs) break;
+    await new Promise((r) => setTimeout(r, POLL_MS));
+  }
+  const waitedMs = Date.now() - started;
+  return { ok: false, error: readinessFailure(last, selector, waitedMs, events), state: last.state, waitedMs, answered };
+}
+
+/** F074.99 — an edit verb wrote to a field on a page that was not listening.
+ *
+ *  Reported on a PASSING run, never failing it: unlike `password_in_url` this
+ *  finding HAS a benign reading (a plain server-rendered form), so turning it red
+ *  would redden working flows fleet-wide on the day it ships. Naming the benign
+ *  reading in the message is the price of that choice — a warning a reader cannot
+ *  dismiss on sight is a warning they stop reading. */
+export interface NotListeningFinding {
+  /** How the step addressed the field, for the report. */
+  anchor: string;
+  /** The page it happened on. Also the memo key: once a page has answered, the
+   *  other edit verbs on it skip the probe rather than each paying the budget. */
+  url: string;
+  /** Which of the two answers this is. `uninstrumented` is OUR fault, not the
+   *  page's, and it means the check DID NOT RUN — which is a different fact from
+   *  "the page was fine" and must never be readable as it. */
+  state: 'not-listening' | 'uninstrumented';
+  waited_ms: number;
+  /** Ready to print. */
+  message: string;
+}
+
+export function notListeningMessage(
+  state: 'not-listening' | 'uninstrumented',
+  anchor: string,
+  waitedMs: number,
+  events: readonly string[],
+): string {
+  if (state === 'uninstrumented') {
+    return (
+      `The readiness check DID NOT RUN before writing to ${anchor}: the listener observer was not ` +
+      'installed on this page, so whether anything was listening is UNKNOWN — this is a Lens fault, ' +
+      'not a page fault, and it means this run carries no hydration verdict either way.'
+    );
+  }
+  return (
+    `A value was typed into ${anchor} on a page where nothing was listening for ${events.join('/')} ` +
+    `after ${waitedMs}ms. The element exists and is rendered, and the write landed in the DOM where it ` +
+    'reads back correctly — no application code heard it. Two readings: the page\'s scripts never ' +
+    'attached, in which case every step can still be green over fields the app never received (check ' +
+    'the app is served on the same hostname its client bundle is allowed to load from) — or this is a ' +
+    'plain server-rendered form that legitimately has no listener, in which case the write is real and ' +
+    'this note is noise.'
+  );
+}