@monoes/monobrowse 1.0.12 → 1.0.14

package/src/cli/session.ts

@@ -0,0 +1,412 @@
+/**
+ * Browse session runtime — the one live CDP session every browse subcommand
+ * acts on, the helpers that establish and tear it down, and the small
+ * flag/output helpers they all share.
+ *
+ * A CLI invocation is a single process with a single session, so the state is
+ * module-level. It is a mutable record rather than separate bindings because
+ * the subcommand modules that update it import it (see `session`).
+ *
+ * Split out of commands.ts, which is now the command catalogue.
+ */
+
+import type { CdpClient, ElementRef } from '../index.js';
+import { output } from './output.js';
+
+const DEFAULT_PORT = 9222;
+
+// Runtime state (single session per CLI process).
+//
+// One mutable record rather than separate module-level bindings: every
+// subcommand module reads and writes the SAME session, and ESM import
+// bindings are read-only for the importer, so the state has to live behind
+// an object for a command in another file to be able to update it.
+export const session: {
+  client: CdpClient | null;
+  sessionId: string;
+  targetId: string;
+  port: number;
+  refs: Map<string, ElementRef>;
+  /** Saved parent sessionId when inside an iframe — restored by `frame main`. */
+  parentSessionId: string;
+} = {
+  client: null,
+  sessionId: '',
+  targetId: '',
+  port: DEFAULT_PORT,
+  refs: new Map(),
+  parentSessionId: '',
+};
+
+export async function getBrowser() {
+  return import('../index.js');
+}
+
+// Best-effort cleanup on Ctrl-C / kill so a launched Chrome doesn't linger as
+// an orphan process when a command is interrupted mid-flight (e.g. during a
+// long-running wait/eval that CdpClient.send()'s own timeout hasn't tripped
+// yet).
+//
+// This module is imported for EVERY `monomind` CLI invocation (commands/
+// index.ts statically imports browse.ts, which imports this file) — not just
+// browse commands — so the handler is only *registered* once a browser
+// session is actually launched here (see ensureSignalCleanupHandlers(),
+// called from the `open` action below), not at module load. Registering
+// unconditionally at import time would call process.exit() on Ctrl-C for
+// every unrelated monomind command (e.g. a long-running `org run` daemon),
+// pre-empting whatever other SIGINT/SIGTERM handling that process needs.
+const SIGNAL_EXIT_CODES: Record<'SIGINT' | 'SIGTERM', number> = { SIGINT: 130, SIGTERM: 143 };
+let _signalHandlersRegistered = false;
+export function ensureSignalCleanupHandlers(): void {
+  if (_signalHandlersRegistered) return;
+  _signalHandlersRegistered = true;
+  for (const sig of ['SIGINT', 'SIGTERM'] as const) {
+    process.on(sig, () => {
+      void (async () => {
+        try {
+          const browser = await getBrowser();
+          if (session.client) {
+            await browser.closeBrowser(session.client, session.port);
+          } else {
+            const pid = browser.getLaunchedPid(session.port);
+            if (pid !== undefined) {
+              try {
+                process.kill(pid, 'SIGKILL');
+              } catch {
+                /* already exited */
+              }
+            }
+          }
+        } catch {
+          // best-effort — never block process exit on cleanup failure
+        }
+      })().finally(() => process.exit(SIGNAL_EXIT_CODES[sig]));
+    });
+  }
+}
+
+// Each CLI invocation is a fresh process, so this module's `session.port` variable
+// is always freshly initialized to DEFAULT_PORT — a `--port 9333` passed to
+// an earlier `open` command has no effect on this process's own default.
+// Resolve the persisted "active port" (written by `open --port N`, read via
+// ref-cache.ts's saveActivePort/loadActivePort) so subsequent commands
+// attach to the browser the user actually opened instead of silently
+// launching/attaching to a second, unrelated Chrome instance on 9222.
+export async function resolveDefaultPort(
+  browser: Awaited<ReturnType<typeof getBrowser>>,
+): Promise<number> {
+  const persisted = await browser.loadActivePortInfo();
+  if (!persisted) return DEFAULT_PORT;
+  if (!persisted.launched) {
+    // connect-origin port: the browser belongs to someone else. If it died,
+    // relaunching our own headless Chrome on that port would squat the
+    // user's debug port and silently swap which browser commands act on —
+    // fail loudly instead.
+    try {
+      await fetch(`http://127.0.0.1:${persisted.port}/json/version`, {
+        signal: AbortSignal.timeout(1500),
+      });
+    } catch {
+      await browser.clearActivePort();
+      throw new Error(
+        `Connected browser on port ${persisted.port} is gone — re-run \`connect\` (or \`open\` to launch a fresh one).`,
+      );
+    }
+  }
+  return persisted.port;
+}
+
+export async function ensureConnected(port: number, targetId?: string) {
+  const browser = await getBrowser();
+  if (!session.client?.isConnected()) {
+    if (session.client && session.sessionId) {
+      browser.teardownRouteInterception(session.sessionId);
+      browser.stopRequestCapture(session.sessionId);
+      browser.teardownDialogHandling(session.sessionId);
+      browser.teardownConsoleCapture(session.sessionId);
+      session.client.close();
+    }
+    const effectivePort = port === DEFAULT_PORT ? await resolveDefaultPort(browser) : port;
+    session.port = await browser.launchBrowser({ port: effectivePort, headless: true });
+    const conn = await browser.connectToTarget(session.port, targetId);
+    session.client = conn.client;
+    session.sessionId = conn.sessionId;
+    session.targetId = conn.target.id;
+    session.parentSessionId = '';
+    session.refs = new Map();
+    await hydrateRefsFromCache(browser, session.targetId, conn.target.url);
+  }
+  return { client: session.client!, sessionId: session.sessionId, targetId: session.targetId };
+}
+
+// Each CLI invocation is a fresh process, so the in-memory session.refs Map built by
+// a prior `snapshot` command is gone by the time a later `find`/`click`/etc.
+// command runs. Rehydrate it from the on-disk ref cache (written by
+// captureSnapshot call sites below) so refs resolved by a previous process
+// remain usable. Falls back silently to an empty Map if no cache exists.
+//
+// The cached `url` field (captured at snapshot time) is compared against the
+// browser's CURRENT url (`currentUrl`, from the just-fetched target info).
+// A stale `backendDOMNodeId` can still successfully resolve via
+// DOM.getBoxModel even after a same-tab SPA navigation or DOM mutation
+// changed what's actually at those coordinates — so a mismatch here means
+// EVERY ref in the cache is potentially pointing at the wrong element. We
+// hard-invalidate (skip hydration entirely, so any @eN lookup fails loudly
+// via resolveRef's "not found" error) rather than the weaker 30s time-based
+// staleness check below, which only warns.
+export async function hydrateRefsFromCache(
+  browser: Awaited<ReturnType<typeof getBrowser>>,
+  targetId: string,
+  currentUrl: string,
+): Promise<void> {
+  const cached = await browser.loadRefCache(targetId);
+  if (!cached) return;
+  if (currentUrl && cached.url && currentUrl !== cached.url) {
+    output.printError(
+      `Stale references — page has navigated (cache: ${cached.url} → current: ${currentUrl}). Re-run snapshot before using @eN refs.`,
+    );
+    return; // leave session.refs empty — do not attempt to resolve refs against a different page
+  }
+  session.refs = cached.refs;
+  if (cached.stale) {
+    output.printWarning(
+      `AX ref cache is ${Math.round(cached.ageMs / 1000)}s old — page may have changed since the last snapshot; re-run snapshot if refs don't resolve as expected`,
+    );
+  }
+}
+
+// URL patterns that signal an unambiguous login/auth wall.
+// Excludes 'auth', 'oauth', 'sso', 'saml' — their callback/ACS/token paths
+// (/auth/callback, /sso/callback, /saml/acs) are completion endpoints, not walls.
+// DOM detection (password field, CAPTCHA widgets) handles SSO/SAML login pages.
+const ATTENTION_URL_RE =
+  /\/(login|log-in|signin|sign-in|captcha|mfa|2fa|account\/login|accounts\/login|session\/new|users\/sign_in)(?:[/?#]|$)/i;
+
+export async function detectAttentionNeeded(
+  client: CdpClient,
+  sessionId: string,
+  url: string,
+): Promise<'login' | 'captcha' | null> {
+  if (ATTENTION_URL_RE.test(url)) return 'login';
+  try {
+    const hasPassword = await client
+      .send<{ result: { value: boolean } }>(
+        'Runtime.evaluate',
+        {
+          expression: '!!document.querySelector("input[type=password]")',
+          returnByValue: true,
+        },
+        sessionId,
+      )
+      .then((r) => r.result?.value === true)
+      .catch(() => false);
+    if (hasPassword) return 'login';
+
+    const hasCaptcha = await client
+      .send<{ result: { value: boolean } }>(
+        'Runtime.evaluate',
+        {
+          expression:
+            '!!(document.querySelector("iframe[src*=recaptcha]") || document.querySelector("iframe[src*=hcaptcha]") || document.querySelector(".g-recaptcha") || document.querySelector(".h-captcha") || document.querySelector("[data-sitekey]"))',
+          returnByValue: true,
+        },
+        sessionId,
+      )
+      .then((r) => r.result?.value === true)
+      .catch(() => false);
+    if (hasCaptcha) return 'captcha';
+  } catch {
+    /* ignore CDP errors */
+  }
+  return null;
+}
+
+export function waitForEnter(): Promise<void> {
+  if (!process.stdin.isTTY) {
+    // Non-interactive context (MCP server, piped input, CI) — cannot safely read stdin.
+    // Auto-continue after a short grace period so automation isn't blocked.
+    output.printWarning(
+      'Non-interactive mode: auto-continuing in 30s. Switch to headed manually if needed.',
+    );
+    return new Promise((resolve) => setTimeout(resolve, 30_000));
+  }
+  return new Promise((resolve) => {
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    const onData = () => {
+      process.stdin.pause();
+      process.stdin.off('data', onData);
+      resolve();
+    };
+    process.stdin.once('data', onData);
+  });
+}
+
+export async function switchToHeaded(url: string, port: number): Promise<void> {
+  const browser = await getBrowser();
+
+  // Snapshot cookies from current headless session before closing
+  let savedCookies: unknown[] = [];
+  if (session.client && session.sessionId) {
+    try {
+      savedCookies = await browser.getCookies(session.client, session.sessionId);
+    } catch {
+      /* ignore */
+    }
+    browser.teardownRouteInterception(session.sessionId);
+    browser.stopRequestCapture(session.sessionId);
+    browser.teardownDialogHandling(session.sessionId);
+    browser.teardownConsoleCapture(session.sessionId);
+    session.client.close();
+    session.client = null;
+    session.sessionId = '';
+    session.parentSessionId = '';
+    session.targetId = '';
+  }
+
+  // Launch headed on a neighbouring port to avoid collision
+  const headedPort = port + 10;
+  try {
+    await browser.launchBrowser({ port: headedPort, headless: false });
+  } catch (err) {
+    // Headed launch failed (no display, locked down env). Restore headless and rethrow.
+    session.port = await browser.launchBrowser({ port, headless: true });
+    const fallback = await browser.connectToTarget(session.port);
+    session.client = fallback.client;
+    session.sessionId = fallback.sessionId;
+    session.targetId = fallback.target.id;
+    session.refs = new Map();
+    throw new Error(
+      `Cannot open headed browser: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  const conn = await browser.connectToTarget(headedPort);
+  session.client = conn.client;
+  session.sessionId = conn.sessionId;
+  session.targetId = conn.target.id;
+  session.refs = new Map();
+
+  if (savedCookies.length) {
+    try {
+      await browser.setCookies(
+        session.client,
+        session.sessionId,
+        savedCookies as Parameters<typeof browser.setCookies>[2],
+      );
+    } catch {
+      /* ignore */
+    }
+  }
+  await browser.openUrl(session.client, session.sessionId, url);
+
+  output.printInfo(
+    'Browser window opened. Complete the required action (login / CAPTCHA), then press Enter to continue in headless mode...',
+  );
+  await waitForEnter();
+
+  // Capture post-auth cookies
+  const authCookies = await browser
+    .getCookies(session.client, session.sessionId)
+    .catch(() => [] as unknown[]);
+  const authLocalStorage = await browser
+    .getLocalStorage(session.client, session.sessionId)
+    .catch(() => ({}) as Record<string, string>);
+
+  // Close headed session — actually terminate the underlying Chrome process
+  // (Browser.close CDP command, PID-kill fallback), not just our CDP client
+  // connection, so the visible authenticated window doesn't linger forever.
+  browser.teardownRouteInterception(session.sessionId);
+  browser.stopRequestCapture(session.sessionId);
+  browser.teardownDialogHandling(session.sessionId);
+  browser.teardownConsoleCapture(session.sessionId);
+  await browser.closeBrowser(session.client, headedPort);
+  session.client.close();
+  session.client = null;
+  session.sessionId = '';
+  session.parentSessionId = '';
+  session.targetId = '';
+
+  // Relaunch headless and restore session
+  session.port = await browser.launchBrowser({ port, headless: true });
+  const headlessConn = await browser.connectToTarget(session.port);
+  session.client = headlessConn.client;
+  session.sessionId = headlessConn.sessionId;
+  session.targetId = headlessConn.target.id;
+  session.refs = new Map();
+
+  if (authCookies.length) {
+    try {
+      await browser.setCookies(
+        session.client,
+        session.sessionId,
+        authCookies as Parameters<typeof browser.setCookies>[2],
+      );
+    } catch {
+      /* ignore */
+    }
+  }
+  if (authLocalStorage && Object.keys(authLocalStorage).length) {
+    try {
+      await browser.setLocalStorage(session.client, session.sessionId, authLocalStorage);
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+// Cap on printed output so a command cannot flood a terminal or an agent's
+// context with a whole page. 0 disables truncation.
+export const DEFAULT_EVAL_MAX_OUTPUT = 50_000;
+
+export function truncateForOutput(text: string, maxOutput: number): string {
+  if (!(maxOutput > 0) || text.length <= maxOutput) return text;
+  return `${text.slice(0, maxOutput)}\n[... truncated at ${maxOutput} chars]`;
+}
+
+/**
+ * Sanitize an image-format flag. The host CLI (monomind) defines a GLOBAL
+ * --format flag for output shaping (text|json|table, default 'text') that
+ * leaks into subcommand flags — so ctx.flags.format arrives as 'text' even
+ * when the user never passed it, and Chrome rejects it with
+ * "CDP error -32602: Invalid image format". Only trust values that are real
+ * image formats; otherwise fall back to the subcommand's own default.
+ */
+export function imageFormat<T extends string>(
+  value: unknown,
+  allowed: readonly T[],
+  fallback: T,
+): T {
+  return allowed.includes(value as T) ? (value as T) : fallback;
+}
+
+export function print(msg: string) {
+  process.stdout.write(`${msg}\n`);
+}
+
+export async function resolveElementObjectId(
+  client: import('../index.js').CdpClient,
+  sessionId: string,
+  refs: Map<string, import('../index.js').ElementRef>,
+  refOrSelector: string,
+): Promise<string> {
+  const browser = await getBrowser();
+  if (refOrSelector.startsWith('@') || /^e\d+$/.test(refOrSelector)) {
+    const key = refOrSelector.startsWith('@') ? refOrSelector.slice(1) : refOrSelector;
+    const ref = await browser.resolveRef(client, sessionId, refs, key);
+    const objectId = await browser.getObjectIdForRef(client, sessionId, ref);
+    if (!objectId) throw new Error(`Element @${key} not found in DOM`);
+    return objectId;
+  }
+  // CSS selector path
+  const res = await client.send<{ result: { objectId?: string; subtype?: string } }>(
+    'Runtime.evaluate',
+    {
+      expression: `document.querySelector(${JSON.stringify(refOrSelector)})`,
+      returnByValue: false,
+    },
+    sessionId,
+  );
+  if (!res.result?.objectId || res.result?.subtype === 'null')
+    throw new Error(`Selector not found: ${refOrSelector}`);
+  return res.result.objectId;
+}

package/src/report/a11y.ts

@@ -0,0 +1,242 @@
+/**
+ * Accessibility rules computed from the CDP accessibility tree.
+ *
+ * Deliberate scope limit: colour contrast is NOT computed here. Contrast
+ * needs resolved foreground/background pixels or computed styles, and the AX
+ * tree carries neither — guessing it would produce confident nonsense. The
+ * report says so explicitly instead.
+ *
+ * Every rule is a pure function of a node array, so the fixtures in the tests
+ * are just hand-written AX trees.
+ */
+
+import type { A11yFinding, AxNode, FocusCandidate } from './types.js';
+
+/** Roles whose whole purpose is to be activated — a nameless one is unusable. */
+const COMMAND_ROLES = new Set([
+  'button',
+  'link',
+  'menuitem',
+  'menuitemcheckbox',
+  'menuitemradio',
+  'tab',
+  'switch',
+  'treeitem',
+]);
+
+/** Roles that take user input and therefore need a programmatic label. */
+const FORM_FIELD_ROLES = new Set([
+  'textbox',
+  'searchbox',
+  'combobox',
+  'listbox',
+  'checkbox',
+  'radio',
+  'slider',
+  'spinbutton',
+]);
+
+const IMAGE_ROLES = new Set(['image', 'img']);
+
+/** Natively focusable tags — a negative tabindex on these removes them from the tab order. */
+const NATIVELY_FOCUSABLE = new Set(['a', 'button', 'input', 'select', 'textarea', 'summary']);
+
+function strValue(v: unknown): string {
+  return typeof v === 'string' ? v : v == null ? '' : String(v);
+}
+
+function roleOf(node: AxNode): string {
+  return strValue(node.role?.value).toLowerCase();
+}
+
+function nameOf(node: AxNode): string {
+  return strValue(node.name?.value).trim();
+}
+
+function propOf(node: AxNode, name: string): unknown {
+  return node.properties?.find((p) => p.name === name)?.value?.value;
+}
+
+function locatorFor(node: AxNode, locators?: Map<number, string>): string {
+  if (node.backendDOMNodeId !== undefined) {
+    const found = locators?.get(node.backendDOMNodeId);
+    if (found) return found;
+  }
+  return `ax-node:${node.nodeId}`;
+}
+
+/**
+ * Depth-first document order. `Accessibility.getFullAXTree` usually returns
+ * nodes pre-ordered already, but heading-order is the one rule where a
+ * reordered array would silently produce wrong findings, so we walk childIds
+ * ourselves. Nodes unreachable from a root are appended in array order rather
+ * than dropped.
+ */
+export function orderNodes(nodes: AxNode[]): AxNode[] {
+  const byId = new Map<string, AxNode>();
+  for (const n of nodes) byId.set(String(n.nodeId), n);
+
+  const ids = new Set(byId.keys());
+  const roots = nodes.filter((n) => n.parentId === undefined || !ids.has(String(n.parentId)));
+
+  const seen = new Set<string>();
+  const ordered: AxNode[] = [];
+  const visit = (node: AxNode): void => {
+    const id = String(node.nodeId);
+    if (seen.has(id)) return;
+    seen.add(id);
+    ordered.push(node);
+    for (const childId of node.childIds ?? []) {
+      const child = byId.get(String(childId));
+      if (child) visit(child);
+    }
+  };
+  for (const root of roots) visit(root);
+  for (const node of nodes) if (!seen.has(String(node.nodeId))) ordered.push(node);
+  return ordered;
+}
+
+/**
+ * Nameless controls, images without alt text, and unlabelled form fields.
+ *
+ * `ignored` nodes are skipped: that is how `<img alt="">` correctly escapes
+ * the image rule — a deliberately decorative image is dropped from the AX
+ * tree, while `<img>` with no alt attribute at all stays in it with an empty
+ * name, which is the bug we want to report.
+ */
+export function findNamingIssues(nodes: AxNode[], locators?: Map<number, string>): A11yFinding[] {
+  const findings: A11yFinding[] = [];
+  for (const node of nodes) {
+    if (node.ignored) continue;
+    const role = roleOf(node);
+    if (!role) continue;
+    const name = nameOf(node);
+    if (name) continue;
+
+    if (FORM_FIELD_ROLES.has(role)) {
+      findings.push({
+        rule: 'form-field-no-label',
+        impact: 'error',
+        role,
+        name: null,
+        locator: locatorFor(node, locators),
+        detail: `${role} has no accessible name — no <label>, aria-label or aria-labelledby resolves to one`,
+      });
+      continue;
+    }
+
+    if (COMMAND_ROLES.has(role)) {
+      findings.push({
+        rule: 'unlabelled-control',
+        impact: 'error',
+        role,
+        name: null,
+        locator: locatorFor(node, locators),
+        detail: `${role} has no accessible name — a screen reader announces it as just "${role}"`,
+      });
+      continue;
+    }
+
+    if (IMAGE_ROLES.has(role)) {
+      findings.push({
+        rule: 'image-missing-alt',
+        impact: 'error',
+        role,
+        name: null,
+        locator: locatorFor(node, locators),
+        detail: 'image has no alt text (use alt="" if it is purely decorative)',
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * Headings that skip a level (h1 -> h3), plus a document whose first heading
+ * is not h1. Both break the outline screen-reader users navigate by.
+ */
+export function findHeadingIssues(nodes: AxNode[], locators?: Map<number, string>): A11yFinding[] {
+  const findings: A11yFinding[] = [];
+  let previous: number | null = null;
+
+  for (const node of orderNodes(nodes)) {
+    if (node.ignored) continue;
+    if (roleOf(node) !== 'heading') continue;
+    const raw = propOf(node, 'level');
+    const level = typeof raw === 'number' ? raw : Number.parseInt(strValue(raw), 10);
+    if (!Number.isFinite(level) || level < 1) continue;
+
+    const name = nameOf(node);
+    if (previous === null) {
+      if (level > 1) {
+        findings.push({
+          rule: 'heading-order-jump',
+          impact: 'warning',
+          role: 'heading',
+          name: name || null,
+          locator: locatorFor(node, locators),
+          detail: `document outline starts at h${level} — the first heading should be h1`,
+        });
+      }
+    } else if (level > previous + 1) {
+      findings.push({
+        rule: 'heading-order-jump',
+        impact: 'warning',
+        role: 'heading',
+        name: name || null,
+        locator: locatorFor(node, locators),
+        detail: `heading level jumps h${previous} -> h${level}`,
+      });
+    }
+    previous = level;
+  }
+  return findings;
+}
+
+/**
+ * Interactive elements pulled out of the keyboard tab order by a negative
+ * tabindex. They stay clickable with a mouse and stay in the AX tree, so
+ * nothing else in this file can see them — the candidates come from a DOM
+ * sweep in collect.ts.
+ */
+export function findFocusOrderIssues(candidates: FocusCandidate[]): A11yFinding[] {
+  const findings: A11yFinding[] = [];
+  for (const c of candidates) {
+    if (c.tabindex >= 0) continue;
+    const interactive = NATIVELY_FOCUSABLE.has(c.tag.toLowerCase()) || c.role !== '';
+    if (!interactive) continue;
+    findings.push({
+      rule: 'negative-tabindex',
+      impact: 'warning',
+      role: c.role || c.tag.toLowerCase(),
+      name: c.name,
+      locator: c.locator,
+      detail: `<${c.tag.toLowerCase()}> has tabindex="${c.tabindex}" — mouse users can reach it, keyboard users cannot`,
+    });
+  }
+  return findings;
+}
+
+export interface A11yInput {
+  nodes: AxNode[];
+  focusCandidates?: FocusCandidate[];
+  locators?: Map<number, string>;
+}
+
+export function runA11yRules({ nodes, focusCandidates = [], locators }: A11yInput): A11yFinding[] {
+  return [
+    ...findNamingIssues(nodes, locators),
+    ...findHeadingIssues(nodes, locators),
+    ...findFocusOrderIssues(focusCandidates),
+  ];
+}
+
+export function countA11y(findings: A11yFinding[]): { errors: number; warnings: number } {
+  let errors = 0;
+  let warnings = 0;
+  for (const f of findings) {
+    if (f.impact === 'error') errors++;
+    else warnings++;
+  }
+  return { errors, warnings };
+}