@crouton-kit/capture 1.3.7 → 1.3.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.3.7",
+  "version": "1.3.9",
   "description": "Browser automation and UI validation via CDP — session-based screenshots, HAR, a11y, click/type, and JS exec",
   "bin": {
     "capture": "./bin/capture"
@@ -10,9 +10,12 @@
     "src"
   ],
   "scripts": {
-    "build": "esbuild src/capture.ts --bundle --platform=node --format=cjs --outfile=bin/capture --external:esbuild '--banner:js=#!/usr/bin/env node' \"--define:globalThis.__CAPTURE_VERSION__=\\\"$npm_package_version\\\"\" && chmod +x bin/capture",
+    "build": "node scripts/build.mjs",
+    "check:bin": "node scripts/build.mjs --check",
     "dev": "tsx src/capture.ts",
-    "test": "node --import tsx --test test/*.test.ts"
+    "test": "node scripts/test.mjs",
+    "test:live": "node scripts/test.mjs --live",
+    "test:install-chrome": "npx --yes @puppeteer/browsers install chrome-headless-shell@143.0.7499.40"
   },
   "repository": {
     "type": "git",
@@ -33,6 +36,7 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/pngjs": "^6.0.5",
     "@types/ws": "^8.18.1",
     "esbuild": "^0.24.0",
     "tsx": "^4",
@@ -40,6 +44,8 @@
     "zod": "^4.3.5"
   },
   "dependencies": {
+    "pixelmatch": "7.2.0",
+    "pngjs": "7.0.0",
     "ws": "^8.19.0"
   }
 }

package/src/capture.ts

@@ -1,180 +1,103 @@
 /**
- * Capture — unified CLI for session management and CDP browser automation.
+ * capture — browser automation and UI measurement over CDP.
  *
- * Session commands (namespaced):
- *   capture session start [--url <url>]
- *   capture session stop <session-id>
- *   capture session list
- *   capture session view <session-id> [--filter screenshots|har|a11y]
- *   capture log <path> [--name label]
- *
- * CDP commands (top-level):
- *   capture detect              Detect CDP port
- *   capture exec <code>         Execute JS in a tab
- *   capture list                List browser tabs
- *   capture open <url>          Open URL in browser
- *   capture screenshot          Capture screenshot
- *   capture a11y                Get accessibility tree
- *   capture record              Passive HAR recording
- *   capture navigate <url>      Navigate + record HAR
- *   capture har create|read|delete  Manage HAR recordings
+ * Root router: seven visible roots (session, page, tab, measure, motion,
+ * cdp, lib) plus the hidden `__bridge-serve` and `__log-tail-serve`
+ * internals, all dispatched below. Root help is assembled from each branch's exported
+ * `COMMAND_BLOCK` — the parent walks its children, it never hardcodes a
+ * child's description. An unknown first token is a structured
+ * `<error code="unknown_command">` (exit 1), never help text.
  */
 
-import * as fs from "fs";
-import * as path from "path";
-import { cdpMain } from "./cdp.js";
-import { sessionMain, logCommand } from "./session/commands.js";
+import * as fs from 'fs';
+import * as path from 'path';
+import { cdpMain } from './cdp.js';
+import { captureError, failureResult } from './errors.js';
+import { emitResult } from './output/render.js';
+import { COMMAND_BLOCK as SESSION_BLOCK } from './session/commands.js';
+import { COMMAND_BLOCK as PAGE_BLOCK } from './cdp/commands/page/index.js';
+import { COMMAND_BLOCK as TAB_BLOCK } from './cdp/commands/tab/index.js';
+import { COMMAND_BLOCK as MEASURE_BLOCK } from './cdp/commands/measure/index.js';
+import { COMMAND_BLOCK as MOTION_BLOCK } from './cdp/commands/motion/index.js';
+import { COMMAND_BLOCK as CDP_BLOCK } from './cdp/commands/cdp.js';
+import { COMMAND_BLOCK as LIB_BLOCK } from './cdp/commands/lib.js';
+
+/** The seven visible root children, in help order. */
+const ROOTS = ['session', 'page', 'tab', 'measure', 'motion', 'cdp', 'lib'] as const;
+
+const ROOT_BLOCKS = [
+  SESSION_BLOCK,
+  PAGE_BLOCK,
+  TAB_BLOCK,
+  MEASURE_BLOCK,
+  MOTION_BLOCK,
+  CDP_BLOCK,
+  LIB_BLOCK,
+] as const;
+
+function rootHelp(): string {
+  return `capture — browser automation and UI measurement over CDP.
+
+${ROOT_BLOCKS.join('\n\n')}
+
+I/O contract: flags and positionals on input; one rendered prose block on
+stdout. --json mirrors the same result as JSON, but the rendered block is
+the contract. stderr carries in-flight diagnostics only.
+
+A CDP-enabled browser must be running; \`capture tab list\` is the probe.
+CDP_PORT / CDP_TARGET pin the browser + tab for orchestrators — precedence:
+explicit flag > active session > env.`;
+}
 
-// ============================================================================
-// CLI
-// ============================================================================
+function printVersion(): void {
+  // Version is injected at build time via esbuild's --define flag.
+  // Falls back to reading package.json at runtime if not injected.
+  const declared = (globalThis as { __CAPTURE_VERSION__?: string }).__CAPTURE_VERSION__;
+  if (declared) {
+    console.log(declared);
+    return;
+  }
+  try {
+    const pkgPath = path.resolve(__dirname, '..', 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) as { version: string };
+    console.log(pkg.version);
+  } catch {
+    console.log('unknown');
+  }
+}
 
 async function main(): Promise<void> {
-  const [command, ...args] = process.argv.slice(2);
+  const [command] = process.argv.slice(2);
 
-  if (command === "--version" || command === "-v" || command === "version") {
-    // Version is injected at build time via esbuild's --define flag.
-    // Falls back to reading package.json at runtime if not injected.
-    const declared = (globalThis as { __CAPTURE_VERSION__?: string }).__CAPTURE_VERSION__;
-    if (declared) {
-      console.log(declared);
-      return;
-    }
-    try {
-      const pkgPath = path.resolve(__dirname, "..", "package.json");
-      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as { version: string };
-      console.log(pkg.version);
-    } catch {
-      console.log("unknown");
-    }
+  if (command === '--version') {
+    printVersion();
     return;
   }
 
-  switch (command) {
-    case "session":
-      return sessionMain(args);
-
-    case "log":
-      return logCommand(args);
-
-    // CDP commands — delegate to cdp.ts
-    case "detect":
-    case "exec":
-    case "open":
-    case "reset-tab":
-    case "screenshot":
-    case "click":
-    case "type":
-    case "a11y":
-    case "record":
-    case "navigate":
-    case "har":
-    case "lib":
-    case "network":
-    case "list":
-    case "cdp":
-    case "__bridge-serve":
-      return cdpMain();
-
-    default:
-      console.log(`Capture — browser automation over CDP for validating UI features.
-
-Most tasks start with a session. Once a session is active, every command
-auto-fills --target (the tab) and --har (the recording) — don't thread
-those flags yourself.
-
-TYPICAL WORKFLOW
-
-  1. Start a session (opens tab, starts HAR, marks it active):
-       capture session start --url http://localhost:3000
-
-  2. Interact — no --target / --har needed:
-       capture a11y --interactive           See what's on the page
-       capture click "Sign in"              Click by accessible name (auto-screenshots)
-       capture type "hi@me.com" --into "Email"
-       capture screenshot                   Save current state
-       capture navigate https://...         Navigate within the session
-       capture exec "document.title"        Run JS (expressions, return, await)
-       capture har read --filter-url /api   Inspect recorded traffic
-
-  3. Bundle and inspect:
-       capture session stop  <session-id>
-       capture session view  <session-id>
-
-SESSION COMMANDS
-
-  session start [--url <url>]              Start a session
-  session stop  <session-id>               Finalize and bundle artifacts
-  session list                             List active and stopped sessions
-  session view  <id> [--filter section]    section = screenshots|har|a11y|logs
-  log <path> [--name label]                Tail a log file into the active session
-
-INTERACTION COMMANDS (work inside or outside a session)
-
-  a11y [--interactive] [--json]            Accessibility tree (use this first to see elements)
-  click "name" [--role <role>]             Click by accessible name
-  type "text" [--into "Field"]             Type into focused element or named field
-  screenshot [--out <path>] [--full-page]  Screenshot (viewport: desktop|desktop-wide|tablet|mobile)
-  exec <code>  |  exec --file <path>       Evaluate JS; expressions, return, and await are supported
-  navigate <url> [--settle <ms>]           Navigate the current tab + record HAR
-
-DIAGNOSTICS & ONE-OFFS (no session needed)
-
-  detect                                   Find running CDP endpoints
-  list                                     List open tabs across endpoints
-  open <url> [--new]                       Open a URL, return its tab id
-  reset-tab <url>                          Abandon a stuck tab, open fresh (updates session)
-  record [--duration <secs>]               Passive HAR recording; parallel-safe capture
-  network <offline|online>                 Toggle connectivity for a tab
-  har create | read [id] | delete <id>     Manage standalone HAR recordings
-
-RAW CDP ESCAPE HATCH
-
-  cdp <Domain.method> [--params json]      Send any CDP command capture doesn't wrap
-                      [--browser]          Target the browser connection (Browser.*, ServiceWorker.*)
-                      [--wait-event name]  Wait for a CDP event, e.g. after ServiceWorker.enable
-
-  Browser-level state (permission grants, ServiceWorker enablement) reverts
-  the instant its connection closes. session start --hold keeps ONE browser
-  connection open across commands so that state survives between them:
-
-    capture session start --url http://localhost:3000 --hold
-    capture cdp Browser.grantPermissions --browser --params '{"origin":"...","permissions":["notifications"]}'
-    capture cdp ServiceWorker.enable --browser --target <pageTabId>
-    capture cdp ServiceWorker.deliverPushMessage --browser --target <pageTabId> --params '{...}'
-    capture session stop <session-id>
-
-  capture cdp --help                       Full reference
-
-LIBRARY (vault libs — dev checkout only)
-
-  lib list                                 List available libs
-  lib search "<query>" [--limit N]          Fuzzy-search functions across libs
-  lib show <name>                          Lib + function summaries
-  lib read <name> [fn…]                    Full input/output schemas (+ .ts source path)
-  exec "import {fn} from 'libs/<name>'; return await fn({…})"   Run a lib in the active tab
-
-TARGETING (only when NOT in a session, or picking a parallel tab)
-
-  CDP_PORT / CDP_TARGET  Orchestrators can pin the active browser + tab
-  --target <tabId>       Exact id; a prefix of 8 chars is enough (preferred, parallel-safe)
-  --url <pattern>        Fuzzy URL match against open tabs
-                         NOTE: on \`session start\`, --url is a URL to OPEN, not a pattern.
-
-HELP
+  if (command === undefined || command === '-h') {
+    console.log(rootHelp());
+    return;
+  }
 
-  capture <command> --help       Per-command usage, e.g. capture click --help, capture har --help
-  capture --version              Print version
+  if (command === '__log-tail-serve') {
+    // Internal self-spawn target for `session log`'s detached tailer worker.
+    // Not a visible root: absent from ROOTS, help, and every COMMAND_BLOCK.
+    const { runLogTailer } = await import('./session/log-tailer.js');
+    return runLogTailer(process.argv.slice(3));
+  }
 
-PREREQ — a browser with CDP must be running:
-  Arc                 enabled by default
-  Chrome / Chromium   --remote-debugging-port=9222
-  Electron apps       CDP exposed automatically
-  Verify with:        capture detect`);
+  if ((ROOTS as readonly string[]).includes(command) || command === '__bridge-serve') {
+    return cdpMain();
   }
+
+  throw captureError(
+    'invocation',
+    'unknown_command',
+    `Unknown command ${command}; expected one of the seven roots: session, page, tab, measure, motion, cdp, lib.`,
+  );
 }
 
-main().catch((err) => {
-  console.error(err.message);
-  process.exit(1);
+main().catch((error) => {
+  emitResult(failureResult(error), { json: process.argv.includes('--json') });
+  process.exitCode = 1;
 });

package/src/cdp/a11y.ts

@@ -1,4 +1,5 @@
-import { type CDPClient } from './client.js';
+import { captureError } from '../errors.js';
+import { withScopeSerialization } from './scope-lock.js';
 
 export const INTERACTIVE_ROLES = new Set([
   'button',
@@ -49,12 +50,18 @@ export function flattenA11yTree(
   return lines;
 }
 
-interface AXNode {
+export interface AccessibilityClient {
+  send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+
+/** The fields consumed from a node returned by `Accessibility.getFullAXTree`. */
+export interface FullAXNode {
   nodeId: string;
+  backendDOMNodeId?: number;
+  ignored?: boolean;
   role?: { value: string };
   name?: { value: string };
   childIds?: string[];
-  properties?: Array<{ name: string; value: { value: unknown } }>;
 }
 
 export interface A11yNode {
@@ -63,23 +70,115 @@ export interface A11yNode {
   children: A11yNode[];
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isAxStringValue(value: unknown): value is { value: string } {
+  return isRecord(value) && typeof value.value === 'string';
+}
+
+function isFullAXNode(value: unknown): value is FullAXNode {
+  if (!isRecord(value) || typeof value.nodeId !== 'string') return false;
+  if (
+    value.backendDOMNodeId !== undefined &&
+    (!Number.isSafeInteger(value.backendDOMNodeId) || (value.backendDOMNodeId as number) < 0)
+  ) return false;
+  if (value.ignored !== undefined && typeof value.ignored !== 'boolean') return false;
+  if (value.role !== undefined && !isAxStringValue(value.role)) return false;
+  if (value.name !== undefined && !isAxStringValue(value.name)) return false;
+  if (
+    value.childIds !== undefined &&
+    (!Array.isArray(value.childIds) || !value.childIds.every((id) => typeof id === 'string'))
+  ) return false;
+  return true;
+}
+
+/**
+ * Reads one complete AX tree with call-scoped Accessibility ownership.
+ *
+ * The Accessibility domain's enabled state lives on the connection: a direct
+ * connection's state dies with its own websocket session, but the
+ * recorder-held connection is shared across commands (its bridge handles
+ * each CDP request independently — it serializes nothing), so the entire
+ * enable→read→disable scope serializes under the owning session's
+ * `.ax-scope.lock` (`withScopeSerialization`) when the client is the
+ * recorder-held adapter — otherwise a concurrent routed caller could
+ * disable this read's domain mid-flight.
+ */
+export async function readFullAXTree(client: AccessibilityClient): Promise<FullAXNode[]> {
+  return withScopeSerialization(client, 'ax', 'full AX tree read', () => axScopedRead(client));
+}
+
+/**
+ * The one Accessibility state transaction: enable → read → disable.
+ * Claiming ownership before awaiting `Accessibility.enable` matters because a
+ * lost response does not prove the browser rejected the enable request. The
+ * matching disable therefore always runs, without touching the DOM domain.
+ * A disable failure prevents success — alone it throws a typed cleanup
+ * failure; paired with a primary failure it throws an `AggregateError`
+ * preserving both facts.
+ */
+async function axScopedRead(client: AccessibilityClient): Promise<FullAXNode[]> {
+  let primaryFailed = false;
+  let primaryError: unknown;
+  let ownsAccessibility = false;
+
+  try {
+    ownsAccessibility = true;
+    await client.send('Accessibility.enable');
+    const response = await client.send('Accessibility.getFullAXTree');
+    const nodes = isRecord(response) ? response.nodes : undefined;
+    if (!Array.isArray(nodes) || !nodes.every(isFullAXNode)) {
+      throw captureError(
+        'world',
+        'malformed_protocol',
+        'Accessibility.getFullAXTree returned a malformed nodes payload.',
+        { method: 'Accessibility.getFullAXTree', response },
+      );
+    }
+    return nodes;
+  } catch (error) {
+    primaryFailed = true;
+    primaryError = error;
+    throw error;
+  } finally {
+    if (ownsAccessibility) {
+      try {
+        await client.send('Accessibility.disable');
+      } catch (error) {
+        const cleanupError = captureError(
+          'cleanup',
+          'accessibility_cleanup_failed',
+          'Accessibility.disable failed after a full AX tree read.',
+          error,
+        );
+        if (primaryFailed) {
+          throw new AggregateError(
+            [primaryError, cleanupError],
+            'The full AX tree read failed and Accessibility cleanup also failed.',
+            { cause: primaryError },
+          );
+        }
+        throw cleanupError;
+      }
+    }
+  }
+}
+
 export async function getAccessibilityTree(
-  client: CDPClient,
+  client: AccessibilityClient,
 ): Promise<A11yNode[]> {
-  await client.send('Accessibility.enable');
-  const result = (await client.send('Accessibility.getFullAXTree')) as {
-    nodes: AXNode[];
-  };
-  await client.send('Accessibility.disable');
-
-  const nodeMap = new Map<string, AXNode>();
-  for (const node of result.nodes) {
+  const nodes = await readFullAXTree(client);
+
+  const nodeMap = new Map<string, FullAXNode>();
+  for (const node of nodes) {
     nodeMap.set(node.nodeId, node);
   }
 
   const SKIP_ROLES = new Set(['none', 'generic', 'InlineTextBox']);
 
-  function buildNode(node: AXNode): A11yNode[] {
+  function buildNode(node: FullAXNode): A11yNode[] {
     const role = node.role?.value ?? '';
     const childNodes = (node.childIds ?? []).flatMap((id) => {
       const child = nodeMap.get(id);
@@ -99,6 +198,6 @@ export async function getAccessibilityTree(
     ];
   }
 
-  const root = result.nodes[0];
+  const root = nodes[0];
   return root ? buildNode(root) : [];
 }