@crouton-kit/capture 1.3.4 → 1.3.5

package/package.json

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

@@ -69,6 +69,7 @@ async function main(): Promise<void> {
     case "record":
     case "navigate":
     case "har":
+    case "lib":
     case "network":
     case "list":
       return cdpMain();
@@ -125,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/commands/exec.ts

@@ -3,6 +3,7 @@ import { withConnection } from '../connection.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) {
@@ -13,7 +14,9 @@ export async function cmdExec(parsed: ParsedArgs, _args: string[]): Promise<void
         '  capture exec "document.title" --target <id>\n' +
         '  capture exec "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);
   }
@@ -35,6 +38,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 +63,15 @@ 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 existing smart wrap: async IIFE
+      // only when code contains `await`; bare code lets Runtime.evaluate return
+      // the last expression's completion value (multi-statement code works).
+      const expression = prebuilt
+        ? prebuilt
+        : /\bawait\b/.test(code)
+          ? `(async () => { ${code} })()`
+          : code;
 
       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/dispatch.ts

@@ -5,6 +5,7 @@ import { cmdExec } from './commands/exec.js';
 import { cmdScreenshot, cmdClick, cmdType, cmdA11y } from './commands/ui.js';
 import { cmdRecord, cmdNavigate, cmdNetwork } from './commands/traffic.js';
 import { cmdHar } from './commands/har.js';
+import { cmdLib } from './commands/lib.js';
 
 export async function cdpMain(): Promise<void> {
   const args = process.argv.slice(2);
@@ -24,6 +25,7 @@ export async function cdpMain(): Promise<void> {
     case 'navigate': return cmdNavigate(parsed, args);
     case 'network': return cmdNetwork(parsed, args);
     case 'har': return cmdHar(parsed, args);
+    case 'lib': return cmdLib(parsed, args);
     default:
       console.log(CDP_USAGE);
   }

package/src/cdp/usage.ts

@@ -17,6 +17,10 @@ Commands:
   har create          Create a HAR recording (returns id)
   har read [id]       Read accumulated HAR entries (id optional in active session)
   har delete <id>     Delete a HAR recording
+  lib list            List available vault libs (dev checkout only)
+  lib search "<q>"     Fuzzy-search lib functions [--limit N]
+  lib show <name>     Lib + function summaries
+  lib read <name> [fn…]  Full input/output schemas (+ .ts source path)
 
 Options:
   --port <port>       Override CDP port
@@ -59,4 +63,7 @@ Examples:
   capture har create
   capture exec "document.querySelector('form').submit()" --target <id> --har <id>
   capture har read <id>
+  capture lib search "search emails"
+  capture lib read gmail searchEmails
+  capture exec "import {searchEmails} from 'libs/gmail'; const ctx = await getContext(); return await searchEmails({ ...ctx, query: 'invoice' })"
 `;