@crouton-kit/capture 1.3.3 → 1.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "Browser automation and UI validation via CDP — session-based screenshots, HAR, a11y, click/type, and JS exec",
   "bin": {
     "capture": "./bin/capture"
@@ -10,7 +10,9 @@
     "src"
   ],
   "scripts": {
-    "build": "esbuild src/capture.ts --bundle --platform=node --format=cjs --outfile=bin/capture '--banner:js=#!/usr/bin/env node' \"--define:globalThis.__CAPTURE_VERSION__=\\\"$npm_package_version\\\"\" && chmod +x bin/capture"
+    "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",
+    "dev": "tsx src/capture.ts",
+    "test": "node --import tsx --test test/*.test.ts"
   },
   "repository": {
     "type": "git",
@@ -33,7 +35,9 @@
   "devDependencies": {
     "@types/ws": "^8.18.1",
     "esbuild": "^0.24.0",
-    "typescript": "^5.7.0"
+    "tsx": "^4",
+    "typescript": "^5.7.0",
+    "zod": "^4.3.5"
   },
   "dependencies": {
     "ws": "^8.19.0"

package/src/capture.ts

@@ -22,390 +22,8 @@
 
 import * as fs from "fs";
 import * as path from "path";
-import * as os from "os";
-import { spawn } from "child_process";
-import {
-  createHarRecording,
-  readHarRecording,
-  deleteHarRecording,
-} from "./har-manager.js";
 import { cdpMain } from "./cdp.js";
-import {
-  getActiveSession,
-  setActiveSession,
-  clearActiveSession,
-} from "./session-context.js";
-
-const CAPTURE_ROOT = path.join(os.tmpdir(), "capture-sessions");
-
-interface LogPid {
-  pid: number;
-  name: string;
-  sourcePath: string;
-}
-
-interface Session {
-  id: string;
-  dir: string;
-  harId: string | null;
-  startedAt: string;
-  url: string | null;
-  targetId: string | null;
-  stepCount: number;
-  logPids: LogPid[];
-}
-
-interface BundleManifest {
-  id: string;
-  startedAt: string;
-  stoppedAt: string;
-  duration: number;
-  url: string | null;
-  screenshots: Array<{ name: string; path: string }>;
-  har: { id: string; path: string; entryCount: number } | null;
-  a11y: Array<{ name: string; path: string }>;
-  logs: Array<{ name: string; path: string; lines: number }>;
-  other: Array<{ name: string; path: string }>;
-}
-
-function sessionDir(id: string): string {
-  return path.join(CAPTURE_ROOT, id);
-}
-
-function sessionMetaPath(id: string): string {
-  return path.join(sessionDir(id), ".session.json");
-}
-
-function readSession(id: string): Session {
-  const metaPath = sessionMetaPath(id);
-  if (!fs.existsSync(metaPath)) {
-    throw new Error(`No capture session found: ${id}`);
-  }
-  return JSON.parse(fs.readFileSync(metaPath, "utf-8")) as Session;
-}
-
-function generateId(): string {
-  return `cap-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
-}
-
-// ============================================================================
-// Session Commands
-// ============================================================================
-
-async function start(args: string[]): Promise<void> {
-  let url: string | null = null;
-
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--url" && args[i + 1]) {
-      url = args[++i];
-    }
-  }
-
-  const id = generateId();
-  const dir = sessionDir(id);
-  fs.mkdirSync(path.join(dir, "shots"), { recursive: true });
-  fs.mkdirSync(path.join(dir, "a11y"), { recursive: true });
-
-  // Start HAR recording directly
-  let harId: string | null = null;
-  try {
-    const harResult = createHarRecording();
-    harId = harResult.id;
-  } catch (err) {
-    console.error(`Warning: could not start HAR recording: ${err instanceof Error ? err.message : err}`);
-  }
-
-  // Open tab if URL provided
-  let targetId: string | null = null;
-  if (url) {
-    try {
-      const { detectCdpPort, navigateAndWait } = await import('./cdp.js');
-      const port = await detectCdpPort();
-      const tab = await navigateAndWait(port, url);
-      targetId = tab.id;
-    } catch (err) {
-      console.error(`Warning: could not open tab: ${err instanceof Error ? err.message : err}`);
-    }
-  }
-
-  const session: Session = {
-    id,
-    dir,
-    harId,
-    startedAt: new Date().toISOString(),
-    url,
-    targetId,
-    stepCount: 0,
-    logPids: [],
-  };
-  fs.writeFileSync(sessionMetaPath(id), JSON.stringify(session, null, 2));
-
-  // Set as active session for auto-defaults
-  setActiveSession({
-    sessionId: id,
-    dir,
-    harId,
-    targetId,
-    stepCount: 0,
-  });
-
-  // Output for agent consumption
-  const result = {
-    sessionId: id,
-    bundleDir: dir,
-    harId,
-    targetId,
-    shotsDir: path.join(dir, "shots"),
-    a11yDir: path.join(dir, "a11y"),
-  };
-  console.log(JSON.stringify(result, null, 2));
-
-  // Agent-friendly next steps on stderr
-  console.error(`\nCapture session started: ${id}`);
-  if (targetId) {
-    console.error(`Tab opened — session context active. No need to pass --target or --har.`);
-  }
-  console.error(`\nWhen done: capture session stop ${id}`);
-}
-
-function logCommand(args: string[]): void {
-  const sourcePath = args[0];
-  if (!sourcePath) {
-    console.error("Usage: capture log <path> [--name label] [--session <id>]");
-    process.exit(1);
-  }
-
-  const resolved = path.resolve(sourcePath);
-  if (!fs.existsSync(resolved)) {
-    throw new Error(`Log file not found: ${resolved}`);
-  }
-
-  let name: string | null = null;
-  let sessionId: string | null = null;
-  for (let i = 1; i < args.length; i++) {
-    if (args[i] === "--name" && args[i + 1]) name = args[++i];
-    if (args[i] === "--session" && args[i + 1]) sessionId = args[++i];
-  }
-
-  if (!sessionId) {
-    const active = getActiveSession();
-    if (!active) {
-      throw new Error("No active capture session. Start one or pass --session <id>.");
-    }
-    sessionId = active.sessionId;
-  }
-
-  const session = readSession(sessionId);
-  name = name ?? path.basename(resolved, path.extname(resolved));
-
-  const logsDir = path.join(session.dir, "logs");
-  fs.mkdirSync(logsDir, { recursive: true });
-
-  const destPath = path.join(logsDir, `${name}.log`);
-  const outFd = fs.openSync(destPath, "a");
-
-  const child = spawn(
-    "sh",
-    ["-c", `tail -f "${resolved}" | perl -MPOSIX -ne 'print strftime("%Y-%m-%dT%H:%M:%SZ",gmtime())." ".$_'`],
-    { detached: true, stdio: ["ignore", outFd, "ignore"] },
-  );
-  child.unref();
-  fs.closeSync(outFd);
-
-  const pid = child.pid!;
-  session.logPids.push({ pid, name, sourcePath: resolved });
-  fs.writeFileSync(sessionMetaPath(session.id), JSON.stringify(session, null, 2));
-
-  console.log(JSON.stringify({ name, sourcePath: resolved, destPath, pid }, null, 2));
-}
-
-async function stop(args: string[]): Promise<void> {
-  const id = args[0];
-  if (!id) {
-    console.error("Usage: capture session stop <session-id>");
-    process.exit(1);
-  }
-
-  const session = readSession(id);
-  const stoppedAt = new Date().toISOString();
-  const startMs = new Date(session.startedAt).getTime();
-  const duration = Date.now() - startMs;
-
-  // Kill log tailers
-  for (const lp of session.logPids ?? []) {
-    try { process.kill(-lp.pid, "SIGTERM"); } catch { /* already dead */ }
-  }
-  if (session.logPids?.length) {
-    await new Promise((r) => setTimeout(r, 200));
-  }
-
-  // Collect screenshots
-  const shotsDir = path.join(session.dir, "shots");
-  const screenshots = fs.existsSync(shotsDir)
-    ? fs.readdirSync(shotsDir)
-        .filter((f) => f.endsWith(".png") || f.endsWith(".jpg"))
-        .map((f) => ({ name: f, path: path.join(shotsDir, f) }))
-    : [];
-
-  // Collect a11y snapshots
-  const a11yDir = path.join(session.dir, "a11y");
-  const a11y = fs.existsSync(a11yDir)
-    ? fs.readdirSync(a11yDir)
-        .filter((f) => f.endsWith(".json") || f.endsWith(".txt"))
-        .map((f) => ({ name: f, path: path.join(a11yDir, f) }))
-    : [];
-
-  // Collect HAR directly from har-manager
-  let har: BundleManifest["har"] = null;
-  if (session.harId) {
-    try {
-      const harData = readHarRecording(session.harId);
-      if (harData) {
-        const harPath = path.join(session.dir, "har.json");
-        fs.writeFileSync(harPath, JSON.stringify(harData, null, 2));
-        har = { id: session.harId, path: harPath, entryCount: harData.log.entries.length };
-        // Clean up the HAR recording
-        try { deleteHarRecording(session.harId); } catch { /* best effort */ }
-      }
-    } catch (err) {
-      console.error(`Warning: could not read HAR: ${err instanceof Error ? err.message : err}`);
-    }
-  }
-
-  // Collect log files
-  const logsDir = path.join(session.dir, "logs");
-  const logs = fs.existsSync(logsDir)
-    ? fs.readdirSync(logsDir)
-        .filter((f) => f.endsWith(".log"))
-        .map((f) => {
-          const filePath = path.join(logsDir, f);
-          const content = fs.readFileSync(filePath, "utf-8");
-          const lines = content ? content.split("\n").filter(Boolean).length : 0;
-          return { name: f, path: filePath, lines };
-        })
-    : [];
-
-  // Collect anything else dropped in the session dir
-  const knownDirs = new Set(["shots", "a11y", "logs"]);
-  const knownFiles = new Set([".session.json", "har.json", "bundle.json"]);
-  const other = fs.readdirSync(session.dir)
-    .filter((f) => !knownDirs.has(f) && !knownFiles.has(f))
-    .map((f) => ({ name: f, path: path.join(session.dir, f) }));
-
-  // Clear active session context
-  clearActiveSession();
-
-  const manifest: BundleManifest = {
-    id: session.id,
-    startedAt: session.startedAt,
-    stoppedAt,
-    duration,
-    url: session.url,
-    screenshots,
-    har,
-    a11y,
-    logs,
-    other,
-  };
-
-  const bundlePath = path.join(session.dir, "bundle.json");
-  fs.writeFileSync(bundlePath, JSON.stringify(manifest, null, 2));
-
-  console.log(JSON.stringify({
-    bundlePath,
-    summary: {
-      duration,
-      screenshots: screenshots.length,
-      harEntries: har?.entryCount ?? 0,
-      a11ySnapshots: a11y.length,
-      logFiles: logs.length,
-      otherFiles: other.length,
-    },
-  }, null, 2));
-
-  console.error(`\nBundle written: ${bundlePath}`);
-  console.error(`Read it: capture session view ${id}`);
-}
-
-function list(): void {
-  if (!fs.existsSync(CAPTURE_ROOT)) {
-    console.log("[]");
-    return;
-  }
-
-  const sessions = fs.readdirSync(CAPTURE_ROOT)
-    .filter((d) => fs.existsSync(sessionMetaPath(d)))
-    .map((d) => {
-      const session = readSession(d);
-      const hasBundled = fs.existsSync(path.join(session.dir, "bundle.json"));
-      return { id: session.id, startedAt: session.startedAt, url: session.url, status: hasBundled ? "stopped" : "active" };
-    });
-
-  console.log(JSON.stringify(sessions, null, 2));
-}
-
-function view(args: string[]): void {
-  const id = args[0];
-  if (!id) {
-    console.error("Usage: capture session view <session-id> [--filter screenshots|har|a11y]");
-    process.exit(1);
-  }
-
-  const session = readSession(id);
-  const bundlePath = path.join(session.dir, "bundle.json");
-
-  if (!fs.existsSync(bundlePath)) {
-    console.error(`Session ${id} hasn't been stopped yet. Run: capture session stop ${id}`);
-    process.exit(1);
-  }
-
-  const manifest = JSON.parse(fs.readFileSync(bundlePath, "utf-8")) as BundleManifest;
-
-  const filter = args.find((_, i) => args[i - 1] === "--filter");
-  if (filter) {
-    const section = manifest[filter as keyof BundleManifest];
-    console.log(JSON.stringify(section, null, 2));
-  } else {
-    console.log(JSON.stringify(manifest, null, 2));
-  }
-}
-
-async function sessionMain(args: string[]): Promise<void> {
-  const [subcommand, ...rest] = args;
-
-  switch (subcommand) {
-    case "start": return start(rest);
-    case "stop": return stop(rest);
-    case "list": return list();
-    case "view": return view(rest);
-    default:
-      console.log(`capture session — manage capture sessions
-
-Sub-commands:
-  start [--url <url>]             Start a session (opens tab, records HAR, sets active context)
-  stop  <session-id>              Finalize and bundle artifacts (screenshots, HAR, a11y, logs)
-  list                            List active and stopped sessions
-  view  <id> [--filter section]   View bundle manifest; section = screenshots|har|a11y|logs
-
-Why sessions: once started, every subsequent capture command auto-fills
---target (the tab) and --har (the recording). No manual flag threading.
-
-Typical flow:
-  1. capture session start --url http://localhost:3000
-  2. Interact — no --target / --har needed:
-       capture a11y --interactive
-       capture click "Sign in"
-       capture type "hi@me.com" --into "Email"
-       capture screenshot
-       capture navigate https://app.example.com/dashboard
-       capture har read --filter-url /api
-  3. capture session stop <session-id>
-  4. capture session view <session-id>
-
-Related:  capture log <path> [--name label]   Tail a log into the active session
-See also: capture --help                      Full command list`);
-  }
-}
+import { sessionMain, logCommand } from "./session/commands.js";
 
 // ============================================================================
 // CLI
@@ -451,6 +69,7 @@ async function main(): Promise<void> {
     case "record":
     case "navigate":
     case "har":
+    case "lib":
     case "network":
     case "list":
       return cdpMain();
@@ -507,6 +126,14 @@ DIAGNOSTICS & ONE-OFFS (no session needed)
   network <offline|online>                 Toggle connectivity for a tab
   har create | read [id] | delete <id>     Manage standalone HAR recordings
 
+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)
 
   --target <tabId>   Exact id; a prefix of 8 chars is enough (preferred, parallel-safe)

package/src/cdp/a11y.ts

@@ -0,0 +1,104 @@
+import { type CDPClient } from './client.js';
+
+export const INTERACTIVE_ROLES = new Set([
+  'button',
+  'link',
+  'textbox',
+  'searchbox',
+  'combobox',
+  'checkbox',
+  'radio',
+  'menuitem',
+  'tab',
+  'switch',
+  'slider',
+  'spinbutton',
+  'option',
+  'menuitemcheckbox',
+  'menuitemradio',
+]);
+
+export function flattenA11yTree(
+  nodes: A11yNode[],
+  opts: { interactive?: boolean } = {},
+  depth = 0,
+): string[] {
+  const lines: string[] = [];
+
+  for (const node of nodes) {
+    // Filter to interactive roles if requested
+    if (opts.interactive && !INTERACTIVE_ROLES.has(node.role)) {
+      lines.push(...flattenA11yTree(node.children, opts, depth));
+      continue;
+    }
+
+    // Skip nodes without meaningful role or name
+    if (!node.role || node.role === 'StaticText') {
+      lines.push(...flattenA11yTree(node.children, opts, depth));
+      continue;
+    }
+
+    const indent = '  '.repeat(depth);
+    const nameStr = node.name ? ` "${node.name}"` : '';
+    lines.push(`${indent}${node.role}${nameStr}`);
+
+    // Recurse
+    lines.push(...flattenA11yTree(node.children, opts, depth + 1));
+  }
+
+  return lines;
+}
+
+interface AXNode {
+  nodeId: string;
+  role?: { value: string };
+  name?: { value: string };
+  childIds?: string[];
+  properties?: Array<{ name: string; value: { value: unknown } }>;
+}
+
+export interface A11yNode {
+  role: string;
+  name: string;
+  children: A11yNode[];
+}
+
+export async function getAccessibilityTree(
+  client: CDPClient,
+): 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) {
+    nodeMap.set(node.nodeId, node);
+  }
+
+  const SKIP_ROLES = new Set(['none', 'generic', 'InlineTextBox']);
+
+  function buildNode(node: AXNode): A11yNode[] {
+    const role = node.role?.value ?? '';
+    const childNodes = (node.childIds ?? []).flatMap((id) => {
+      const child = nodeMap.get(id);
+      return child ? buildNode(child) : [];
+    });
+
+    if (SKIP_ROLES.has(role)) {
+      return childNodes;
+    }
+
+    return [
+      {
+        role,
+        name: node.name?.value ?? '',
+        children: childNodes,
+      },
+    ];
+  }
+
+  const root = result.nodes[0];
+  return root ? buildNode(root) : [];
+}

package/src/cdp/args.ts

@@ -0,0 +1,101 @@
+import { type ParsedArgs } from './types.js';
+import { getActiveSession } from '../session-context.js';
+
+export function parseCliArgs(argv: string[]): ParsedArgs {
+  const command = argv[0] ?? '';
+  const positional: string[] = [];
+  const parsed: Partial<ParsedArgs> = { command, positional };
+
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+
+    if (arg === '--port' && next) {
+      parsed.port = parseInt(next, 10);
+      i++;
+    } else if (arg === '--out' && next) {
+      parsed.out = next;
+      i++;
+    } else if (arg === '--json') {
+      parsed.json = true;
+    } else if (arg === '--interactive') {
+      parsed.interactive = true;
+    } else if (arg === '--har-out' && next) {
+      parsed.harOut = next;
+      i++;
+    } else if (arg === '--record') {
+      parsed.record = true;
+    } else if (arg === '--duration' && next) {
+      parsed.duration = parseInt(next, 10);
+      i++;
+    } else if (arg === '--settle' && next) {
+      parsed.settle = parseInt(next, 10);
+      i++;
+    } else if (arg === '--file' && next) {
+      parsed.file = next;
+      i++;
+    } else if (arg === '--nested') {
+      parsed.nested = true;
+    } else if (arg === '--har' && next) {
+      parsed.har = next;
+      i++;
+    } else if (arg === '--new') {
+      parsed.new = true;
+    } else if (arg === '--target' && next) {
+      parsed.target = next;
+      i++;
+    } else if (arg === '--role' && next) {
+      parsed.role = next;
+      i++;
+    } else if (arg === '--into' && next) {
+      parsed.into = next;
+      i++;
+    } else if (arg === '--no-screenshot') {
+      parsed.noScreenshot = true;
+    } else if (arg === '--viewport' && next) {
+      parsed.viewport = next;
+      i++;
+    } else if (arg === '--full-page') {
+      parsed.fullPage = true;
+    } else if (arg === '--height' && next) {
+      parsed.height = parseInt(next, 10);
+      i++;
+    } else if (arg === '--filter-url' && next) {
+      parsed.filterUrl = next;
+      i++;
+    } else if (arg === '--filter-status' && next) {
+      parsed.filterStatus = next;
+      i++;
+    } else if (arg === '--filter-method' && next) {
+      parsed.filterMethod = next.toUpperCase();
+      i++;
+    } else if (arg === '--limit' && next) {
+      parsed.limit = parseInt(next, 10);
+      i++;
+    } else if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+    } else if (arg.startsWith('--')) {
+      console.error(`Unknown flag: ${arg}`);
+      process.exit(1);
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  // Fill gaps from environment variables (set by pipeline orchestrators)
+  if (!parsed.target && process.env.CDP_TARGET) {
+    parsed.target = process.env.CDP_TARGET;
+  }
+  if (!parsed.har && process.env.CDP_HAR_ID) {
+    parsed.har = process.env.CDP_HAR_ID;
+  }
+
+  // Fill remaining gaps from active session context (explicit flags always win)
+  const session = getActiveSession();
+  if (session) {
+    if (!parsed.har && session.harId) parsed.har = session.harId;
+    if (!parsed.target && session.targetId) parsed.target = session.targetId;
+  }
+
+  return parsed as ParsedArgs;
+}