@monoes/monobrowse 1.0.13 → 1.0.14

package/src/cli/commands-page.ts

@@ -0,0 +1,420 @@
+/**
+ * Reading the page — accessibility snapshots, page/element properties, and
+ * diffing one snapshot against another.
+ *
+ * `snapshot` is what mints the `@eN` refs every element command resolves
+ * against; `get` reads url/title/text/html/box/attributes back out.
+ */
+
+import { output } from './output.js';
+import { ensureConnected, getBrowser, print, session, truncateForOutput } from './session.js';
+import type { Command, CommandContext, CommandResult } from './types.js';
+
+export const snapshotCommand: Command = {
+  name: 'snapshot',
+  description: 'Capture accessibility snapshot with ref-based element handles (@e1, @e2, ...)',
+  options: [
+    {
+      name: 'interactive',
+      short: 'i',
+      type: 'boolean',
+      description: 'Interactive elements only (93% token reduction)',
+      default: false,
+    },
+    {
+      name: 'compact',
+      short: 'c',
+      type: 'boolean',
+      description: 'Compact output format',
+      default: false,
+    },
+    { name: 'json', type: 'boolean', description: 'Output as JSON', default: false },
+    { name: 'depth', short: 'd', type: 'number', description: 'Max depth of AX tree to show' },
+    {
+      name: 'selector',
+      short: 's',
+      type: 'string',
+      description: 'Scope snapshot to a CSS selector',
+    },
+    {
+      name: 'save',
+      type: 'string',
+      description: 'Save snapshot text to file (baseline for --diff)',
+    },
+    {
+      name: 'diff',
+      type: 'string',
+      description: 'Compare current snapshot against a saved baseline file',
+    },
+    {
+      name: 'content-boundaries',
+      type: 'boolean',
+      description: 'Wrap output in sentinel markers to prevent page-content injection attacks',
+      default: false,
+    },
+    {
+      name: 'max-output',
+      type: 'number',
+      description:
+        'Truncate output to N characters (prevents context window blowout on large pages)',
+    },
+  ],
+  action: async (ctx: CommandContext): Promise<CommandResult> => {
+    const { client, sessionId } = await ensureConnected(session.port);
+    const browser = await getBrowser();
+
+    const result = await browser.captureSnapshot(client, sessionId, {
+      interactiveOnly: ctx.flags.interactive as boolean,
+      compact: ctx.flags.compact as boolean,
+      maxDepth: ctx.flags.depth as number | undefined,
+      selector: ctx.flags.selector as string | undefined,
+    });
+
+    session.refs = result.refs;
+    await browser.saveRefCache(session.targetId, result.url, session.refs);
+
+    const applyOutputLimits = (text: string): string => {
+      const maxOutput = ctx.flags['max-output'] as number | undefined;
+      let out = maxOutput ? truncateForOutput(text, maxOutput) : text;
+      if (ctx.flags['content-boundaries']) {
+        const nonce = Math.random().toString(36).slice(2, 10);
+        out = `MONOMIND_PAGE_CONTENT nonce=${nonce} origin=${result.url}\n${out}\nEND_MONOMIND_PAGE_CONTENT nonce=${nonce}`;
+      }
+      return out;
+    };
+
+    // --save: write snapshot text to baseline file
+    if (ctx.flags.save) {
+      const { writeFile, mkdir } = await import('node:fs/promises');
+      const { dirname } = await import('node:path');
+      const savePath = ctx.flags.save as string;
+      await mkdir(dirname(savePath), { recursive: true }).catch(() => {});
+      await writeFile(savePath, result.text, 'utf8');
+      output.printSuccess(`Snapshot saved to: ${savePath}`);
+      return { success: true, data: { path: savePath } };
+    }
+
+    // --diff: compare against baseline file
+    if (ctx.flags.diff) {
+      const { readFile } = await import('node:fs/promises');
+      const baselinePath = ctx.flags.diff as string;
+      let baseline: string;
+      try {
+        baseline = await readFile(baselinePath, 'utf8');
+      } catch {
+        throw new Error(`Baseline not found: ${baselinePath}. Run snapshot --save first.`);
+      }
+      const currentLines = result.text.split('\n');
+      const baselineLines = baseline.split('\n');
+      const added: string[] = [],
+        removed: string[] = [];
+      const baseSet = new Set(baselineLines);
+      const curSet = new Set(currentLines);
+      for (const l of currentLines) if (!baseSet.has(l)) added.push(l);
+      for (const l of baselineLines) if (!curSet.has(l)) removed.push(l);
+      const changed = added.length > 0 || removed.length > 0;
+      if (ctx.flags.json) {
+        print(
+          JSON.stringify({
+            changed,
+            additions: added.length,
+            removals: removed.length,
+            added,
+            removed,
+          }),
+        );
+      } else {
+        if (!changed) {
+          output.printSuccess('No snapshot changes detected');
+        } else {
+          output.printWarning(`Snapshot changed: +${added.length} lines, -${removed.length} lines`);
+          for (const l of added) print(`\x1b[32m+ ${l}\x1b[0m`);
+          for (const l of removed) print(`\x1b[31m- ${l}\x1b[0m`);
+        }
+      }
+      return {
+        success: true,
+        data: { changed, additions: added.length, removals: removed.length },
+      };
+    }
+
+    if (ctx.flags.json) {
+      const refsObj = Object.fromEntries([...result.refs.entries()].map(([k, v]) => [k, v]));
+      print(
+        JSON.stringify({
+          url: result.url,
+          title: result.title,
+          refs: refsObj,
+          snapshot: result.text,
+        }),
+      );
+    } else {
+      print(`[${result.title}] ${result.url}\n`);
+      print(applyOutputLimits(result.text));
+    }
+
+    return { success: true, data: result };
+  },
+};
+
+export const getCommand: Command = {
+  name: 'get',
+  description:
+    'Get page info. Usage: monomind browse get url|title|text|html|value|attr|count|box|styles [@ref] [attrName]',
+  options: [{ name: 'json', type: 'boolean', description: 'Output as JSON', default: false }],
+  action: async (ctx: CommandContext): Promise<CommandResult> => {
+    const { client, sessionId } = await ensureConnected(session.port);
+    const browser = await getBrowser();
+
+    const what = ctx.args[0] as string;
+    if (!what)
+      throw new Error('Usage: monomind browse get url|title|text|html|value|attr|count|box|styles');
+
+    let value: unknown;
+
+    switch (what) {
+      case 'url':
+        value = await browser.getCurrentUrl(client, sessionId);
+        break;
+      case 'title':
+        value = await browser.getCurrentTitle(client, sessionId);
+        break;
+      case 'text': {
+        const refArg = ctx.args[1] as string | undefined;
+        if (refArg) {
+          const refKey = refArg.startsWith('@') ? refArg.slice(1) : refArg;
+          const ref = session.refs.get(refKey);
+          if (!ref) throw new Error(`Ref @${refKey} not found`);
+          const objectId = await browser.getObjectIdForRef(client, sessionId, ref);
+          if (!objectId) throw new Error('Element not in DOM');
+          const result = await client.send<{ result: { value?: string } }>(
+            'Runtime.callFunctionOn',
+            {
+              functionDeclaration:
+                'function() { return this.innerText || this.textContent || ""; }',
+              objectId,
+              returnByValue: true,
+            },
+            sessionId,
+          );
+          value = result.result?.value ?? '';
+        } else {
+          value = (await browser.evaluateJs(
+            client,
+            sessionId,
+            'document.body?.innerText ?? ""',
+          )) as string;
+        }
+        break;
+      }
+      case 'html':
+        value = (await browser.evaluateJs(
+          client,
+          sessionId,
+          'document.documentElement.outerHTML',
+        )) as string;
+        break;
+      case 'value': {
+        const refArg = ctx.args[1] as string;
+        if (!refArg) throw new Error('Usage: monomind browse get value @ref');
+        const refKey = refArg.startsWith('@') ? refArg.slice(1) : refArg;
+        const ref = session.refs.get(refKey);
+        if (!ref) throw new Error(`Ref @${refKey} not found`);
+        const objectId = await browser.getObjectIdForRef(client, sessionId, ref);
+        if (!objectId) throw new Error('Element not in DOM');
+        const r = await client.send<{ result: { value?: string } }>(
+          'Runtime.callFunctionOn',
+          {
+            functionDeclaration: 'function() { return this.value ?? null; }',
+            objectId,
+            returnByValue: true,
+          },
+          sessionId,
+        );
+        value = r.result?.value ?? null;
+        break;
+      }
+      case 'attr': {
+        const refArg = ctx.args[1] as string;
+        const attrName = ctx.args[2] as string;
+        if (!refArg || !attrName)
+          throw new Error('Usage: monomind browse get attr @ref <attrName>');
+        const refKey = refArg.startsWith('@') ? refArg.slice(1) : refArg;
+        const ref = session.refs.get(refKey);
+        if (!ref) throw new Error(`Ref @${refKey} not found`);
+        const objectId = await browser.getObjectIdForRef(client, sessionId, ref);
+        if (!objectId) throw new Error('Element not in DOM');
+        const r = await client.send<{ result: { value?: string } }>(
+          'Runtime.callFunctionOn',
+          {
+            functionDeclaration: `function() { return this.getAttribute(${JSON.stringify(attrName)}); }`,
+            objectId,
+            returnByValue: true,
+          },
+          sessionId,
+        );
+        value = r.result?.value ?? null;
+        break;
+      }
+      case 'count': {
+        const selector = ctx.args[1] as string;
+        if (!selector) throw new Error('Usage: monomind browse get count <cssSelector>');
+        value = await browser.evaluateJs(
+          client,
+          sessionId,
+          `document.querySelectorAll(${JSON.stringify(selector)}).length`,
+        );
+        break;
+      }
+      case 'box': {
+        const refArg = ctx.args[1] as string;
+        if (!refArg) throw new Error('Usage: monomind browse get box @ref');
+        const refKey = refArg.startsWith('@') ? refArg.slice(1) : refArg;
+        const ref = session.refs.get(refKey);
+        if (!ref) throw new Error(`Ref @${refKey} not found`);
+        const center = await browser.getElementBox(client, sessionId, ref);
+        value = deriveBoxOutput(center);
+        break;
+      }
+      case 'styles': {
+        const refArg = ctx.args[1] as string;
+        if (!refArg) throw new Error('Usage: monomind browse get styles @ref');
+        const refKey = refArg.startsWith('@') ? refArg.slice(1) : refArg;
+        const ref = session.refs.get(refKey);
+        if (!ref) throw new Error(`Ref @${refKey} not found`);
+        const objectId = await browser.getObjectIdForRef(client, sessionId, ref);
+        if (!objectId) throw new Error('Element not in DOM');
+        const r = await client.send<{ result: { value?: string } }>(
+          'Runtime.callFunctionOn',
+          {
+            functionDeclaration:
+              'function() { const s = window.getComputedStyle(this); return JSON.stringify(Object.fromEntries([...s].map(k => [k, s.getPropertyValue(k)]))); }',
+            objectId,
+            returnByValue: true,
+          },
+          sessionId,
+        );
+        try {
+          value = JSON.parse(r.result?.value ?? '{}');
+        } catch {
+          value = {};
+        }
+        break;
+      }
+      default:
+        throw new Error(`Unknown: ${what}. Use: url|title|text|html|value|attr|count|box|styles`);
+    }
+
+    if (ctx.flags.json) {
+      print(JSON.stringify({ data: { [what]: value } }));
+    } else {
+      print(typeof value === 'object' ? JSON.stringify(value, null, 2) : String(value ?? ''));
+    }
+
+    return { success: true, data: { [what]: value } };
+  },
+};
+
+export function deriveBoxOutput(
+  center: { x: number; y: number; width: number; height: number } | null,
+): {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  centerX: number;
+  centerY: number;
+} | null {
+  if (!center) return null;
+  return {
+    x: center.x - center.width / 2,
+    y: center.y - center.height / 2,
+    width: center.width,
+    height: center.height,
+    centerX: center.x,
+    centerY: center.y,
+  };
+}
+
+export const diffCommand: Command = {
+  name: 'diff',
+  description:
+    'Compare two URLs or snapshots. Usage: monomind browse diff url <url1> <url2> [--interactive] [--json]',
+  options: [
+    {
+      name: 'interactive',
+      short: 'i',
+      type: 'boolean',
+      description: 'Snapshot interactive elements only',
+      default: false,
+    },
+    { name: 'json', type: 'boolean', description: 'Output as JSON', default: false },
+  ],
+  action: async (ctx: CommandContext): Promise<CommandResult> => {
+    const { client, sessionId } = await ensureConnected(session.port);
+    const browser = await getBrowser();
+    const subAction = ctx.args[0] as string;
+
+    if (subAction === 'url') {
+      const url1 = ctx.args[1] as string;
+      const url2 = ctx.args[2] as string;
+      if (!url1 || !url2) throw new Error('Usage: monomind browse diff url <url1> <url2>');
+
+      // Capture snapshot at url1
+      await browser.openUrl(client, sessionId, url1);
+      await browser.waitFor(client, sessionId, { load: 'load', timeout: 15000 });
+      const snap1 = await browser.captureSnapshot(client, sessionId, {
+        interactiveOnly: ctx.flags.interactive as boolean,
+      });
+
+      // Capture snapshot at url2
+      await browser.openUrl(client, sessionId, url2);
+      await browser.waitFor(client, sessionId, { load: 'load', timeout: 15000 });
+      const snap2 = await browser.captureSnapshot(client, sessionId, {
+        interactiveOnly: ctx.flags.interactive as boolean,
+      });
+
+      session.refs = snap2.refs;
+      await browser.saveRefCache(session.targetId, snap2.url, session.refs);
+
+      // Text diff
+      const lines1 = snap1.text.split('\n');
+      const lines2 = snap2.text.split('\n');
+      const set1 = new Set(lines1);
+      const set2 = new Set(lines2);
+      const onlyIn1: string[] = lines1.filter((l) => !set2.has(l));
+      const onlyIn2: string[] = lines2.filter((l) => !set1.has(l));
+      const changed = onlyIn1.length > 0 || onlyIn2.length > 0;
+
+      if (ctx.flags.json) {
+        print(
+          JSON.stringify({
+            changed,
+            url1,
+            url2,
+            onlyIn1,
+            onlyIn2,
+            additions: onlyIn2.length,
+            removals: onlyIn1.length,
+          }),
+        );
+      } else {
+        if (!changed) {
+          output.printSuccess(`No differences between ${url1} and ${url2}`);
+        } else {
+          output.printWarning(
+            `Diff: ${url1} vs ${url2} — +${onlyIn2.length} lines, -${onlyIn1.length} lines`,
+          );
+          for (const l of onlyIn1) print(`\x1b[31m- ${l}\x1b[0m`);
+          for (const l of onlyIn2) print(`\x1b[32m+ ${l}\x1b[0m`);
+        }
+      }
+      return {
+        success: true,
+        data: { changed, url1, url2, additions: onlyIn2.length, removals: onlyIn1.length },
+      };
+    }
+
+    throw new Error('Usage: monomind browse diff url <url1> <url2>');
+  },
+};

package/src/cli/commands-report.ts

@@ -0,0 +1,275 @@
+/**
+ * `report` — one command that opens a page, runs the checks (console errors,
+ * failed requests, Web Vitals against budgets, accessibility), writes an HTML
+ * report and returns a pass/fail verdict.
+ */
+
+import { output } from './output.js';
+import { ensureConnected, getBrowser, print, session } from './session.js';
+import type { Command, CommandContext, CommandResult } from './types.js';
+
+export const reportCommand: Command = {
+  name: 'report',
+  description:
+    'Test a page and write one self-contained HTML report + sibling JSON. Usage: monomind browse report <url>',
+  options: [
+    { name: 'out', short: 'o', type: 'string', description: 'Output .html path, or a directory' },
+    {
+      name: 'budget',
+      short: 'b',
+      type: 'string',
+      description: 'Budget JSON file path, or inline JSON',
+    },
+    {
+      name: 'devices',
+      short: 'd',
+      type: 'string',
+      description: 'Comma-separated device names for the screenshot matrix',
+    },
+    {
+      name: 'wait',
+      short: 'w',
+      type: 'string',
+      description: 'Extra settle step: a CSS selector to wait for, or milliseconds',
+    },
+    { name: 'json', type: 'boolean', description: 'Output as JSON', default: false },
+    {
+      name: 'full-page',
+      type: 'boolean',
+      description: 'Full-page screenshot (--no-full-page for viewport only)',
+      default: true,
+    },
+    {
+      name: 'vitals-wait',
+      type: 'number',
+      description: 'Milliseconds to let the web-vitals observers run',
+      default: 2500,
+    },
+    {
+      name: 'timeout',
+      type: 'number',
+      description: 'Milliseconds to wait for the page to go network-idle',
+      default: 20000,
+    },
+    {
+      name: 'keep-open',
+      type: 'boolean',
+      description: 'Leave the browser running after the report',
+      default: false,
+    },
+    {
+      name: 'repeat',
+      type: 'number',
+      description: 'Run the URL N times and report per-check flake rates (RIG-14)',
+    },
+    {
+      name: 'record',
+      type: 'boolean',
+      description: 'Record frames for the evidence timeline even when the run passes',
+      default: false,
+    },
+    {
+      name: 'history',
+      type: 'boolean',
+      description: 'Print the stored run history for this URL instead of running it',
+      default: false,
+    },
+    {
+      name: 'save',
+      type: 'boolean',
+      description: 'Save this run to the history store (--no-save to skip)',
+      default: true,
+    },
+    {
+      name: 'history-max',
+      type: 'number',
+      description: 'Runs kept per URL before the oldest are pruned (default 20)',
+    },
+    {
+      name: 'trend-window',
+      type: 'number',
+      description: 'Prior runs charted in the trend section (default 10)',
+    },
+  ],
+  examples: [
+    { command: 'monomind browse report https://example.com', description: 'Report with defaults' },
+    {
+      command: 'monomind browse report https://example.com --repeat 5',
+      description: 'Run five times and report flake rates',
+    },
+    {
+      command: 'monomind browse report https://example.com --history',
+      description: 'Show the stored run history for a URL',
+    },
+    {
+      command: 'monomind browse report https://example.com --record',
+      description: 'Attach a frame-by-frame evidence timeline',
+    },
+    {
+      command: 'monomind browse report https://example.com --out ./reports/home.html',
+      description: 'Choose the output path',
+    },
+    {
+      command: 'monomind browse report https://example.com --budget \'{"lcp":4000}\'',
+      description: 'Relax a budget inline',
+    },
+    {
+      command: 'monomind browse report https://example.com --devices "iPhone 14,iPad"',
+      description: 'Add a device screenshot matrix',
+    },
+  ],
+  action: async (ctx: CommandContext): Promise<CommandResult> => {
+    const url = ctx.args[0] as string;
+    if (!url) throw new Error('URL required. Usage: monomind browse report <url>');
+
+    // Imported lazily for the same reason getBrowser() is: this module loads
+    // on every CLI invocation, and nothing but `report` needs the renderer.
+    const { runReport, runReportRepeated, readHistory } = await import('../report/index.js');
+
+    // --history is a read of the store, so it deliberately never launches a
+    // browser — `report --history` must work offline and on a dead site.
+    if (ctx.flags.history) {
+      const { dir, runs } = await readHistory(url);
+      if (ctx.flags.json) {
+        print(JSON.stringify({ data: { dir, runs } }, null, 2));
+      } else if (!runs.length) {
+        output.printWarning(`No stored runs for ${url}`);
+        print(`Looked in: ${dir}`);
+      } else {
+        print(`${runs.length} run(s) for ${url}`);
+        print(`Stored in: ${dir}`);
+        for (const run of runs) {
+          const lcp = run.vitals.lcp === undefined ? '—' : `${Math.round(run.vitals.lcp)}ms`;
+          print(
+            `  ${run.capturedAt}  ${run.verdict.toUpperCase().padEnd(4)}  ` +
+              `LCP ${lcp.padStart(7)}  ${run.counts.consoleErrors} console errors  ` +
+              `${run.counts.failedRequests} failed requests  ${run.counts.a11yErrors} a11y errors`,
+          );
+        }
+      }
+      return { success: true, data: { dir, runs } };
+    }
+
+    const repeatRaw = ctx.flags.repeat as number | undefined;
+    const repeat =
+      typeof repeatRaw === 'number' && Number.isFinite(repeatRaw) && repeatRaw > 1
+        ? Math.floor(repeatRaw)
+        : undefined;
+
+    const { client, sessionId } = await ensureConnected(session.port);
+    const browser = await getBrowser();
+
+    const rawDevices = ctx.flags.devices;
+    const devices =
+      typeof rawDevices === 'string'
+        ? rawDevices
+            .split(',')
+            .map((d) => d.trim())
+            .filter(Boolean)
+        : undefined;
+
+    const runOptions = {
+      url,
+      out: ctx.flags.out as string | undefined,
+      budget: ctx.flags.budget as string | undefined,
+      devices,
+      wait: ctx.flags.wait as string | undefined,
+      vitalsWaitMs: ctx.flags['vitals-wait'] as number | undefined,
+      loadTimeoutMs: ctx.flags.timeout as number | undefined,
+      fullPage: ctx.flags['full-page'] !== false,
+      cwd: ctx.cwd,
+      // A failing run records its own evidence without being asked; --record
+      // is for when you want the timeline from a run that passes.
+      record: ctx.flags.record === true,
+      history: ctx.flags.save !== false,
+      historyMax: ctx.flags['history-max'] as number | undefined,
+      trendWindow: ctx.flags['trend-window'] as number | undefined,
+    };
+
+    let result:
+      | Awaited<ReturnType<typeof runReport>>
+      | Awaited<ReturnType<typeof runReportRepeated>>;
+    try {
+      result = repeat
+        ? await runReportRepeated(client, sessionId, { ...runOptions, repeat })
+        : await runReport(client, sessionId, runOptions);
+    } finally {
+      // A report is a one-shot command — CI should not be left with an
+      // orphan Chrome. Only close a browser THIS process launched: an
+      // attached one belongs to the user's own `open`/`connect` session.
+      if (!ctx.flags['keep-open'] && browser.getLaunchedPid(session.port) !== undefined) {
+        browser.stopRequestCapture(sessionId);
+        browser.teardownConsoleCapture(sessionId);
+        try {
+          await browser.closeBrowser(client, session.port);
+        } catch {
+          /* best-effort */
+        }
+        session.client = null;
+        session.sessionId = '';
+        session.targetId = '';
+        session.refs = new Map();
+        await browser.clearActivePort();
+        await browser.clearRefCache();
+      }
+    }
+
+    const { report, htmlPath, jsonPath, summary, historyDir } = result;
+    const { flake } = result;
+    // With --repeat the flake verdict governs: a check that failed 2 of 5
+    // runs must not exit 0 just because the last run happened to be green.
+    const passed = flake ? flake.verdict === 'pass' : report.verdict === 'pass';
+
+    if (ctx.flags.json) {
+      const { toJsonReport } = await import('../report/index.js');
+      print(
+        JSON.stringify(
+          { data: { ...toJsonReport(report), flake, htmlPath, jsonPath, historyDir } },
+          null,
+          2,
+        ),
+      );
+    } else {
+      if (passed) output.printSuccess(summary);
+      else output.printError(summary);
+      if (flake) {
+        print(`    ${flake.confidenceNote}`);
+        for (const check of flake.checks.filter((c) => !c.stable)) {
+          print(`    ${check.label}: failed ${check.failed} of ${check.runs} runs`);
+        }
+        for (const signal of flake.signals.slice(0, 5)) {
+          print(
+            `    ${signal.kind} "${signal.signature}" in ${signal.runs} of ${signal.total} runs`,
+          );
+        }
+      }
+      for (const failure of report.failures) {
+        print(`    ${failure.budget}: expected ${failure.expected}, got ${failure.actual}`);
+        if (failure.detail) print(`      ${failure.detail}`);
+      }
+      for (const headline of report.trend?.headlines ?? []) output.printWarning(headline);
+      if (report.diff?.structure) {
+        const d = report.diff.structure;
+        print(
+          `    vs previous run: ${d.gained.length} gained, ${d.lost.length} lost, ${d.renamed.length} renamed`,
+        );
+      }
+      if (report.diff?.pixels?.comparable) {
+        print(
+          `    vs previous run: ${report.diff.pixels.changedPercent.toFixed(2)}% of pixels changed`,
+        );
+      }
+      for (const note of report.notes) output.printWarning(note);
+      print(`Report: ${htmlPath}`);
+      print(`JSON:   ${jsonPath}`);
+      if (historyDir) print(`History: ${historyDir}`);
+    }
+
+    // Non-zero exit is the point of RIG-06 — CI and agents gate on it.
+    return {
+      success: passed,
+      exitCode: passed ? 0 : 1,
+      data: { htmlPath, jsonPath, report, flake },
+    };
+  },
+};