@crouton-kit/capture 1.3.4 → 1.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.3.4",
+  "version": "1.3.6",
   "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

@@ -69,6 +69,7 @@ async function main(): Promise<void> {
     case "record":
     case "navigate":
     case "har":
+    case "lib":
     case "network":
     case "list":
       return cdpMain();
@@ -91,7 +92,7 @@ TYPICAL WORKFLOW
        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 (supports await)
+       capture exec "document.title"        Run JS (expressions, return, await)
        capture har read --filter-url /api   Inspect recorded traffic
 
   3. Bundle and inspect:
@@ -112,7 +113,7 @@ INTERACTION COMMANDS (work inside or outside a session)
   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; await is supported
+  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)
@@ -125,11 +126,20 @@ 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)
-  --url <pattern>    Fuzzy URL match against open tabs
-                     NOTE: on \`session start\`, --url is a URL to OPEN, not a pattern.
+  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
 

package/src/cdp/args.ts

@@ -1,14 +1,33 @@
 import { type ParsedArgs } from './types.js';
 import { getActiveSession } from '../session-context.js';
 
+// Every flag below is matched as `--flag` followed by a separate `next`
+// token (space-separated). To accept the equally-common `--flag=value` form
+// without duplicating every branch, split any `--flag=value` token into two
+// tokens up front so the rest of the parser only ever has to handle one
+// convention.
+export function expandEqualsFlags(argv: string[]): string[] {
+  const out: string[] = [];
+  for (const arg of argv) {
+    if (arg.startsWith('--') && arg.includes('=')) {
+      const eq = arg.indexOf('=');
+      out.push(arg.slice(0, eq), arg.slice(eq + 1));
+    } else {
+      out.push(arg);
+    }
+  }
+  return out;
+}
+
 export function parseCliArgs(argv: string[]): ParsedArgs {
   const command = argv[0] ?? '';
+  const rest = expandEqualsFlags(argv.slice(1));
   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];
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    const next = rest[i + 1];
 
     if (arg === '--port' && next) {
       parsed.port = parseInt(next, 10);
@@ -44,6 +63,9 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
     } else if (arg === '--target' && next) {
       parsed.target = next;
       i++;
+    } else if (arg === '--url' && next) {
+      parsed.url = next;
+      i++;
     } else if (arg === '--role' && next) {
       parsed.role = next;
       i++;
@@ -83,7 +105,15 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
   }
 
   // Fill gaps from environment variables (set by pipeline orchestrators)
-  if (!parsed.target && process.env.CDP_TARGET) {
+  if (!parsed.port && process.env.CDP_PORT) {
+    const envPort = Number.parseInt(process.env.CDP_PORT, 10);
+    if (Number.isNaN(envPort)) {
+      console.error(`Invalid CDP_PORT: ${process.env.CDP_PORT}`);
+      process.exit(1);
+    }
+    parsed.port = envPort;
+  }
+  if (!parsed.target && !parsed.url && process.env.CDP_TARGET) {
     parsed.target = process.env.CDP_TARGET;
   }
   if (!parsed.har && process.env.CDP_HAR_ID) {
@@ -94,7 +124,9 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
   const session = getActiveSession();
   if (session) {
     if (!parsed.har && session.harId) parsed.har = session.harId;
-    if (!parsed.target && session.targetId) parsed.target = session.targetId;
+    // An explicit --url picks a different (parallel) tab than the session's
+    // own — don't let the session's targetId clobber that choice.
+    if (!parsed.target && !parsed.url && session.targetId) parsed.target = session.targetId;
   }
 
   return parsed as ParsedArgs;

package/src/cdp/commands/exec.ts

@@ -1,19 +1,24 @@
 import * as fs from 'fs';
 import { withConnection } from '../connection.js';
+import { buildExecExpression } from '../exec-expression.js';
 import { HARRecorder } from '../har-recorder.js';
 import { writeHarAndPrintSummary } from '../har-output.js';
 import { type ParsedArgs } from '../types.js';
+import { hasImports, bundleExec } from '../../vault/bundle.js';
 
 export async function cmdExec(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (parsed.help) {
     console.log(
       'Usage: capture exec <code> [--target <id>] [--record] [--file <path>] [--har <id>]\n\n' +
-        'Execute JavaScript in a browser tab. Supports await (wrapped in async IIFE).\n\n' +
+        'Execute JavaScript in a browser tab. Plain expressions run directly; statement bodies can use top-level return/await and are wrapped in an async IIFE.\n\n' +
         'Examples:\n' +
         '  capture exec "document.title" --target <id>\n' +
-        '  capture exec "await fetch(\'/api/data\').then(r=>r.json())" --target <id>\n' +
+        '  capture exec "return document.title" --target <id>\n' +
+        '  capture exec "return await fetch(\'/api/data\').then(r=>r.json())" --target <id>\n' +
         '  capture exec "document.querySelector(\'.btn\').click()" --target <id>\n' +
-        '  capture exec --file /tmp/scrape.js --target <id> --record',
+        '  capture exec --file /tmp/scrape.js --target <id> --record\n\n' +
+        'Import vault libs (dev checkout only): static imports first, then your code.\n' +
+        '  capture exec "import {searchEmails} from \'libs/gmail\'; const ctx = await getContext(); return await searchEmails({ ...ctx, query: \'invoice\' })"',
     );
     process.exit(0);
   }
@@ -26,8 +31,13 @@ export async function cmdExec(parsed: ParsedArgs, _args: string[]): Promise<void
       console.error(
         'ERROR: Missing code to execute.\n\n' +
           'Usage: capture exec <code> [--target <id>] [--record] [--file <path>]\n\n' +
+          'Supported shapes:\n' +
+          '  document.title\n' +
+          '  return document.title\n' +
+          '  const r = await fetch(\'/api/data\'); return await r.json()\n\n' +
           'Examples:\n' +
           '  capture exec "document.title" --target <id>\n' +
+          '  capture exec "return document.title" --target <id>\n' +
           '  capture exec "document.querySelector(\'.btn\').click()" --target <id>\n' +
           '  capture exec --file /tmp/scrape.js --target <id> --record',
       );
@@ -35,6 +45,19 @@ export async function cmdExec(parsed: ParsedArgs, _args: string[]): Promise<void
     }
   }
 
+  // Import-driven exec: if the code has leading static imports, bundle the
+  // forked vault libs on the fly (esbuild) BEFORE opening a tab — fail fast,
+  // no wasted CDP connection. Plain exec (no imports) skips this entirely.
+  let prebuilt: string | undefined;
+  if (hasImports(code)) {
+    try {
+      prebuilt = await bundleExec(code);
+    } catch (e) {
+      console.error(`ERROR: ${(e as Error).message}`);
+      process.exit(1);
+    }
+  }
+
   await withConnection(
     parsed,
     async (client) => {
@@ -47,13 +70,11 @@ export async function cmdExec(parsed: ParsedArgs, _args: string[]): Promise<void
         await standaloneRecorder.start();
       }
 
-      // Smart wrapping: only use async IIFE when code contains `await`.
-      // Without wrapping, Runtime.evaluate returns the completion value
-      // of the last expression, handling multi-statement code naturally.
-      const needsAsyncWrap = /\bawait\b/.test(code);
-      const expression = needsAsyncWrap
-        ? `(async () => { ${code} })()`
-        : code;
+      // A prebuilt bundle is already a complete IIFE returning the user's
+      // promise. Otherwise fall back to the exec expression wrapper: bare
+      // expressions run directly, while snippets containing top-level `return`
+      // or `await` are wrapped in an async IIFE.
+      const expression = buildExecExpression(code, prebuilt);
 
       const evalResult = (await client.send('Runtime.evaluate', {
         expression,

package/src/cdp/commands/lib.ts

@@ -0,0 +1,356 @@
+/**
+ * `capture lib <list|search|show|read>` — search the forked vault libs.
+ *
+ * Pure local reads, NO CDP connection. Mirrors `nl lib`
+ * (northlight apps/core/src/cli/families/lib/lib-cli.provider.ts): same search
+ * scoring and the discover→schema→run loop, sourced from on-demand doc-gen
+ * (`../../vault/docs.ts`) + sha cache. Output contract (capture convention):
+ * the machine result → stdout `JSON.stringify(x, null, 2)`; next-step hints →
+ * stderr. Every object naming a lib/function carries `srcPath` = the absolute
+ * path to that lib's `.ts` source — the agent's pointer to rebuild on the fly.
+ */
+
+import * as path from "path";
+import { type ParsedArgs } from "../types.js";
+import { vaultLibsDir, listLibs } from "../../vault/paths.js";
+import {
+  getDoc,
+  listDocs,
+  isAgentVisible,
+  type LibraryDoc,
+} from "../../vault/docs.js";
+
+const USAGE =
+  "Usage: capture lib <list|search|show|read> [options]\n\n" +
+  "  list                          List available libs (name, fn count, description, srcPath)\n" +
+  '  search "<query>" [--limit N]  Fuzzy-search functions across all libs (ranked)\n' +
+  "  show <name>                   Lib + function summaries (no schemas)\n" +
+  "  read <name> [fn…]             Full input/output JSON schemas (+ .ts source path)\n\n" +
+  "Then run a lib in the active authenticated tab:\n" +
+  "  capture exec \"import {<fn>} from 'libs/<name>'; return await <fn>({…})\"\n\n" +
+  "Dev-checkout-only feature (requires vault/ source + esbuild).";
+
+// ─── scoring (ported verbatim from lib-cli.provider.ts:71-152) ───────────────
+
+const FUNCTION_NAME_EXACT = 100;
+const FUNCTION_NAME_PREFIX = 60;
+const FUNCTION_NAME_SUBSTRING = 40;
+const SERVICE_NAME_MATCH = 50;
+const FUNCTION_DESC_SUBSTRING = 20;
+const SERVICE_DESC_SUBSTRING = 10;
+
+function scoreToken(
+  token: string,
+  service: string,
+  fnName: string,
+  fnDesc: string,
+  serviceDesc: string,
+): { score: number; match: string } {
+  const q = token.toLowerCase();
+  const fn = fnName.toLowerCase();
+  const svc = service.toLowerCase();
+  const fnD = fnDesc.toLowerCase();
+  const svcD = serviceDesc.toLowerCase();
+
+  let score = 0;
+  let match = "";
+
+  if (fn === q) {
+    score += FUNCTION_NAME_EXACT;
+    match = "function-name (exact)";
+  } else if (fn.startsWith(q)) {
+    score += FUNCTION_NAME_PREFIX;
+    match = "function-name (prefix)";
+  } else if (fn.includes(q)) {
+    score += FUNCTION_NAME_SUBSTRING;
+    match = "function-name";
+  }
+
+  if (svc.includes(q)) {
+    score += SERVICE_NAME_MATCH;
+    if (!match) match = "service-name";
+  }
+
+  if (fnD.includes(q)) {
+    score += FUNCTION_DESC_SUBSTRING;
+    if (!match) match = "function-desc";
+  }
+
+  if (svcD.includes(q)) {
+    score += SERVICE_DESC_SUBSTRING;
+    if (!match) match = "service-desc";
+  }
+
+  return { score, match };
+}
+
+/**
+ * Every whitespace-separated token must contribute > 0 — without this,
+ * `lib search "send email"` would return everything matching "send" alone.
+ */
+function scoreHit(
+  query: string,
+  service: string,
+  fnName: string,
+  fnDesc: string,
+  serviceDesc: string,
+): { score: number; match: string } {
+  const tokens = query.split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) return { score: 0, match: "" };
+  if (tokens.length === 1) {
+    return scoreToken(tokens[0], service, fnName, fnDesc, serviceDesc);
+  }
+  let total = 0;
+  let bestScore = -1;
+  let bestMatch = "";
+  for (const token of tokens) {
+    const r = scoreToken(token, service, fnName, fnDesc, serviceDesc);
+    if (r.score === 0) return { score: 0, match: "" };
+    total += r.score;
+    if (r.score > bestScore) {
+      bestScore = r.score;
+      bestMatch = r.match;
+    }
+  }
+  return { score: total, match: bestMatch };
+}
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+const svcName = (doc: LibraryDoc): string =>
+  doc.library.replace(/^@vallum\//, "");
+
+const srcPathFor = (name: string): string =>
+  path.join(vaultLibsDir(), name, "index.ts");
+
+/** Resolve a user-supplied name against a candidate set: exact, then ci-prefix. */
+function resolveName(
+  query: string,
+  names: string[],
+): { name: string } | { error: string } {
+  if (names.includes(query)) return { name: query };
+  const lower = query.toLowerCase();
+  const prefix = names.filter((n) => n.toLowerCase().startsWith(lower));
+  if (prefix.length === 1) return { name: prefix[0] };
+  if (prefix.length > 1) {
+    return { error: `Ambiguous lib "${query}" — matches: ${prefix.join(", ")}` };
+  }
+  return { error: `Unknown lib "${query}". Available: ${names.join(", ")}` };
+}
+
+// ─── command ─────────────────────────────────────────────────────────────────
+
+export async function cmdLib(
+  parsed: ParsedArgs,
+  _args: string[],
+): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+
+  const sub = parsed.positional[0];
+
+  // ── lib list ──────────────────────────────────────────────────────────────
+  if (sub === "list") {
+    const docs = await listDocs();
+    const rows = docs.map((d) => {
+      const name = svcName(d);
+      return {
+        name,
+        functionCount: d.functions.length,
+        description: d.description,
+        srcPath: srcPathFor(name),
+      };
+    });
+    console.log(JSON.stringify(rows, null, 2));
+    console.error(
+      `\n${rows.length} libs. Next: capture lib show <name>  ·  capture lib read <name> <fn>`,
+    );
+    return;
+  }
+
+  // ── lib search ──────────────────────────────────────────────────────────────
+  if (sub === "search") {
+    const query = parsed.positional[1];
+    if (!query) {
+      console.error('Usage: capture lib search "<query>" [--limit N]');
+      process.exit(1);
+    }
+    const limit = Math.min(
+      typeof parsed.limit === "number" && parsed.limit > 0 ? parsed.limit : 20,
+      500,
+    );
+    const docs = await listDocs();
+    const hits: Array<{
+      service: string;
+      function: string;
+      match: string;
+      score: number;
+      description: string;
+      srcPath: string;
+    }> = [];
+    for (const d of docs) {
+      const service = svcName(d);
+      for (const fn of d.functions) {
+        const { score, match } = scoreHit(
+          query,
+          service,
+          fn.name,
+          fn.description ?? "",
+          d.description ?? "",
+        );
+        if (score > 0) {
+          hits.push({
+            service,
+            function: fn.name,
+            match,
+            score,
+            description: fn.description,
+            srcPath: srcPathFor(service),
+          });
+        }
+      }
+    }
+    hits.sort((a, b) => b.score - a.score);
+    const top = hits.slice(0, limit);
+    console.log(JSON.stringify(top, null, 2));
+    console.error(
+      `\n${hits.length} hit(s)${hits.length > limit ? ` (showing ${limit})` : ""}.` +
+        ` Next: capture lib read <service> <function>`,
+    );
+    return;
+  }
+
+  // ── lib show ──────────────────────────────────────────────────────────────
+  if (sub === "show") {
+    const name = parsed.positional[1];
+    if (!name) {
+      console.error("Usage: capture lib show <name>");
+      process.exit(1);
+    }
+    // Resolve + build ONLY the named lib (design §3.1: show is single-lib, not
+    // an all-lib bundle). Mirrors the read path; adds show's visibility filter
+    // (a present-but-non-visible lib is treated as Unknown).
+    const r = resolveName(name, listLibs());
+    if ("error" in r) {
+      console.error(r.error);
+      process.exit(1);
+    }
+    let doc: LibraryDoc;
+    try {
+      doc = await getDoc(r.name);
+    } catch (e) {
+      console.error((e as Error).message);
+      process.exit(1);
+    }
+    if (!isAgentVisible(doc)) {
+      console.error(
+        `Unknown lib "${name}". Available: ${listLibs().join(", ")}`,
+      );
+      process.exit(1);
+    }
+    const service = r.name;
+    const out = {
+      service,
+      description: doc.description,
+      ...(doc.loginUrl ? { loginUrl: doc.loginUrl } : {}),
+      ...(doc.notes ? { notes: doc.notes } : {}),
+      srcPath: srcPathFor(service),
+      functions: doc.functions.map((f) => ({
+        name: f.name,
+        description: f.description,
+      })),
+    };
+    console.log(JSON.stringify(out, null, 2));
+    console.error(
+      `\nSchemas required before exec — capture lib read ${service} <fn>`,
+    );
+    return;
+  }
+
+  // ── lib read ──────────────────────────────────────────────────────────────
+  if (sub === "read") {
+    const name = parsed.positional[1];
+    if (!name) {
+      console.error("Usage: capture lib read <name> [fn…]");
+      process.exit(1);
+    }
+    // `read` may read ANY present lib (no visibility filter).
+    const r = resolveName(name, listLibs());
+    if ("error" in r) {
+      console.error(r.error);
+      process.exit(1);
+    }
+    let doc: LibraryDoc;
+    try {
+      doc = await getDoc(r.name);
+    } catch (e) {
+      console.error((e as Error).message);
+      process.exit(1);
+    }
+    const service = svcName(doc);
+    const fns = parsed.positional.slice(2);
+
+    // No function names → summary fallback (show-style) + hint to name fns.
+    if (fns.length === 0) {
+      const out = {
+        service,
+        description: doc.description,
+        ...(doc.notes ? { notes: doc.notes } : {}),
+        srcPath: srcPathFor(service),
+        functions: doc.functions.map((f) => ({
+          name: f.name,
+          description: f.description,
+        })),
+      };
+      console.log(JSON.stringify(out, null, 2));
+      console.error(
+        `\nName functions to load schemas: capture lib read ${service} <fn> [fn…]`,
+      );
+      return;
+    }
+
+    const byName = new Map(doc.functions.map((f) => [f.name, f]));
+    const found: typeof doc.functions = [];
+    const missing: string[] = [];
+    for (const op of fns) {
+      const fn = byName.get(op);
+      if (fn) found.push(fn);
+      else missing.push(op);
+    }
+
+    if (found.length === 0) {
+      const available = doc.functions.map((f) => f.name).join(", ");
+      const label =
+        missing.length > 1
+          ? `Functions "${missing.join('", "')}"`
+          : `Function "${missing[0]}"`;
+      console.error(`${label} not in ${service}. Available: ${available}`);
+      process.exit(1);
+    }
+
+    const out = {
+      service,
+      srcPath: srcPathFor(service),
+      functions: found.map((f) => ({
+        name: f.name,
+        description: f.description,
+        ...(f.notes ? { notes: f.notes } : {}),
+        input: f.input,
+        output: f.output,
+      })),
+      ...(missing.length > 0 ? { missing } : {}),
+    };
+    console.log(JSON.stringify(out, null, 2));
+    const firstFn = found[0].name;
+    console.error(
+      `\nRun it: capture exec "import {${firstFn}} from 'libs/${service}'; return await ${firstFn}({…})"`,
+    );
+    return;
+  }
+
+  // ── lib (no/unknown subcommand) ─────────────────────────────────────────────
+  console.error(USAGE);
+  process.exit(1);
+}

package/src/cdp/commands/tabs.ts

@@ -1,4 +1,4 @@
-import { detectCdpPortsAsync, detectCdpPort, getDefaultBrowserId } from '../detect.js';
+import { detectCdpPortsAsync, detectCdpPort, getDefaultBrowserId, pickPreferredEndpoint } from '../detect.js';
 import { listTargets, openTab } from '../targets.js';
 import { navigateAndWait } from '../record.js';
 import { CDPClient } from '../client.js';
@@ -25,13 +25,7 @@ export async function cmdDetect(parsed: ParsedArgs, _args: string[]): Promise<vo
     );
     process.exit(1);
   }
-  const defaultBrowser = getDefaultBrowserId();
-  const preferred =
-    endpoints.find(
-      (p) => p.bundleId === defaultBrowser && !p.isElectron,
-    ) ??
-    endpoints.find((p) => !p.isElectron) ??
-    endpoints[0];
+  const preferred = pickPreferredEndpoint(endpoints, getDefaultBrowserId());
   console.log(
     JSON.stringify(
       {

package/src/cdp/commands/ui.ts

@@ -9,7 +9,7 @@ import { type ParsedArgs } from '../types.js';
 export async function cmdScreenshot(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (parsed.help) {
     console.log(
-      'Usage: capture screenshot [--target <id>] [--out <path>] [--viewport <preset>] [--height <px>] [--full-page]\n\n' +
+      'Usage: capture screenshot [--target <id> | --url <pattern>] [--out <path>] [--viewport <preset>] [--height <px>] [--full-page]\n\n' +
         'Capture a screenshot of the targeted tab. Saves to --out or auto-generates a path.\n\n' +
         'Options:\n' +
         '  --viewport <preset>  Viewport preset (default: desktop)\n' +