@crouton-kit/capture 1.3.4 → 1.3.6

package/src/session/commands.ts

@@ -12,6 +12,7 @@ import {
   setActiveSession,
   clearActiveSession,
 } from '../session-context.js';
+import { expandEqualsFlags } from '../cdp/args.js';
 
 const CAPTURE_ROOT = path.join(os.tmpdir(), 'capture-sessions');
 
@@ -65,11 +66,60 @@ function generateId(): string {
   return `cap-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
 }
 
+function hasHelpFlag(args: string[]): boolean {
+  return args.some((arg) => arg === '-h' || arg === '--help');
+}
+
+export async function waitForPageLoad(
+  client: { waitReady(): Promise<void>; send(method: string, params?: Record<string, unknown>): Promise<unknown>; on(event: string, handler: (params: unknown) => void): void; },
+  timeoutMs: number,
+): Promise<boolean> {
+  await client.waitReady();
+  await client.send('Page.enable');
+
+  return await new Promise<boolean>((resolve) => {
+    const timer = setTimeout(() => resolve(true), timeoutMs);
+    client.on('Page.loadEventFired', () => {
+      clearTimeout(timer);
+      resolve(false);
+    });
+  });
+}
+
+function printSessionHelp(): void {
+  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`);
+}
+
 // ============================================================================
 // Session Commands
 // ============================================================================
 
-async function start(args: string[]): Promise<void> {
+async function start(rawArgs: string[]): Promise<void> {
+  const args = expandEqualsFlags(rawArgs);
   let url: string | null = null;
 
   for (let i = 0; i < args.length; i++) {
@@ -92,16 +142,49 @@ async function start(args: string[]): Promise<void> {
     console.error(`Warning: could not start HAR recording: ${err instanceof Error ? err.message : err}`);
   }
 
-  // Open tab if URL provided
+  // Open tab if URL provided. Fail fast if the new target cannot attach.
   let targetId: string | null = null;
+  let pageLoadTimedOut = false;
   if (url) {
     try {
-      const { detectCdpPort, navigateAndWait } = await import('../cdp.js');
+      const { detectCdpPort, openTab, CDPClient } = await import('../cdp.js');
       const port = await detectCdpPort();
-      const tab = await navigateAndWait(port, url);
+      const tab = await openTab(port, url);
       targetId = tab.id;
+
+      if (!targetId) {
+        throw new Error(
+          `capture session start could not attach to ${url}. Reuse an existing tab with --target.`,
+        );
+      }
+      if (!tab.webSocketDebuggerUrl) {
+        throw new Error(
+          `capture session start could not attach to ${url}: missing WebSocket debugger URL. Reuse an existing tab with --target.`,
+        );
+      }
+
+      const client = new CDPClient(tab.webSocketDebuggerUrl);
+      try {
+        try {
+          await client.send('Runtime.enable', {}, 5_000);
+        } catch (err) {
+          throw new Error(
+            `capture session start could not attach to ${url}: ${err instanceof Error ? err.message : err}. Reuse an existing tab with --target.`,
+          );
+        }
+        pageLoadTimedOut = await waitForPageLoad(client, 10_000);
+      } finally {
+        client.close();
+      }
     } catch (err) {
-      console.error(`Warning: could not open tab: ${err instanceof Error ? err.message : err}`);
+      if (harId) {
+        try {
+          deleteHarRecording(harId);
+        } catch {
+          /* best effort */
+        }
+      }
+      throw err;
     }
   }
 
@@ -132,6 +215,7 @@ async function start(args: string[]): Promise<void> {
     bundleDir: dir,
     harId,
     targetId,
+    pageLoadTimedOut,
     shotsDir: path.join(dir, 'shots'),
     a11yDir: path.join(dir, 'a11y'),
   };
@@ -141,11 +225,20 @@ async function start(args: string[]): Promise<void> {
   console.error(`\nCapture session started: ${id}`);
   if (targetId) {
     console.error(`Tab opened — session context active. No need to pass --target or --har.`);
+    if (pageLoadTimedOut) {
+      console.error(`Page load timed out, but the session is attached to target ${targetId.slice(0, 8)}. Use \`capture exec --target ${targetId.slice(0, 8)}\` or \`capture list\` if you need to recover it.`);
+    }
   }
   console.error(`\nWhen done: capture session stop ${id}`);
 }
 
-export function logCommand(args: string[]): void {
+export function logCommand(rawArgs: string[]): void {
+  const args = expandEqualsFlags(rawArgs);
+  if (hasHelpFlag(args)) {
+    console.log('Usage: capture log <path> [--name label] [--session <id>]');
+    return;
+  }
+
   const sourcePath = args[0];
   if (!sourcePath) {
     console.error('Usage: capture log <path> [--name label] [--session <id>]');
@@ -321,7 +414,8 @@ function list(): void {
   console.log(JSON.stringify(sessions, null, 2));
 }
 
-function view(args: string[]): void {
+function view(rawArgs: string[]): void {
+  const args = expandEqualsFlags(rawArgs);
   const id = args[0];
   if (!id) {
     console.error('Usage: capture session view <session-id> [--filter screenshots|har|a11y]');
@@ -350,36 +444,17 @@ function view(args: string[]): void {
 export async function sessionMain(args: string[]): Promise<void> {
   const [subcommand, ...rest] = args;
 
+  if (!subcommand || hasHelpFlag(args)) {
+    printSessionHelp();
+    return;
+  }
+
   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`);
+      printSessionHelp();
   }
 }

package/src/vault/bundle.ts

@@ -0,0 +1,205 @@
+/**
+ * vault/bundle — the import-driven exec engine.
+ *
+ * Ports the bundling mechanism of northlight's
+ * `apps/core/src/tool-registry/lib/bundle-agent-code.ts`, DROPPING the telemetry
+ * envelope (no `__vallumStartCall`, no `__snapshot`, no `borgEnabled`). When
+ * `capture exec` is handed code containing leading static imports, this turns it
+ * into a single self-contained IIFE: the user's `libs/<name>` imports are
+ * resolved to the forked vault source, esbuild bundles the whole tree on the
+ * fly, and the result is a string the exec path evals over CDP.
+ *
+ * No top-level `esbuild` import — it is loaded lazily via `loadEsbuild()` so the
+ * published package (no esbuild) never crashes at startup.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { Plugin, BuildResult, Message } from "esbuild";
+import {
+  isValidLibName,
+  loadEsbuild,
+  unknownLibMsg,
+  vaultLibsDir,
+  vaultRepoRoot,
+} from "./paths.js";
+
+// Sentinel the post-bundle return-insert anchors on. esbuild with minify:false
+// never renames top-level identifiers, and no first-party lib references
+// __CAPTURE_*, so this literal survives bundling intact and uniquely (the same
+// invariant core relies on for __VALLUM_USER_PROMISE).
+const SENTINEL = "__CAPTURE_RESULT";
+
+// Matches a leading run of static import statements (plus any leading comments)
+// per statement: leading ws/comments, then `import` through its single
+// module-specifier string and optional `;`. A normal import has exactly one
+// string literal (the specifier), so this is unambiguous. Ported from
+// bundle-agent-code.ts, with one addition: the `(?!\s*\()` lookahead so a
+// leading dynamic `import(...)` CALL is NOT misclassified as a static import
+// statement (it would otherwise be hoisted and the body run detached, silently
+// returning undefined). Dynamic `import(...)` anywhere in the body is untouched.
+const IMPORT_STMT_RE =
+  /^\s*(?:(?:\/\/[^\n]*|\/\*[\s\S]*?\*\/)\s*)*import\b(?!\s*\()[^'"`]*?(['"])(?:[^'"`\\]|\\.)*\1[^\n;]*;?/;
+
+function splitLeadingImports(code: string): { imports: string; body: string } {
+  const imports: string[] = [];
+  let body = code;
+  for (;;) {
+    const m = IMPORT_STMT_RE.exec(body);
+    if (!m) break;
+    imports.push(m[0]);
+    body = body.slice(m[0].length);
+  }
+  return { imports: imports.join(""), body };
+}
+
+/**
+ * True iff `code` contains ≥1 leading static `import` statement. This is the
+ * trigger exec.ts uses to preserve the no-import fast path: plain exec has no
+ * top-level import, so esbuild never runs for it.
+ */
+export function hasImports(code: string): boolean {
+  return splitLeadingImports(code).imports.length > 0;
+}
+
+// Matches a `libs/<name>` module specifier inside a string literal.
+const LIB_SPECIFIER_RE = /(['"])libs\/((?:[^'"\\]|\\.)*)\1/g;
+
+// Validate every `libs/<name>` specifier up front. esbuild with treeShaking:true
+// drops an UNUSED import before its resolver ever runs, so a bogus-lib import
+// whose binding is unreferenced would otherwise bundle silently; this guarantees
+// the `Unknown lib` error deterministically, and before esbuild is even loaded
+// (fail fast, before any CDP). Mirrors vaultResolver's existence check exactly.
+function preflightLibs(imports: string): void {
+  const libs = vaultLibsDir();
+  LIB_SPECIFIER_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = LIB_SPECIFIER_RE.exec(imports)) !== null) {
+    const name = m[2];
+    if (!isValidLibName(name) || !fs.existsSync(path.join(libs, name, "index.ts"))) {
+      throw new Error(unknownLibMsg(name));
+    }
+  }
+}
+
+// Hoist the imports to module top level (so esbuild resolves & tree-shakes them)
+// and wrap the body in a result-capturing async IIFE bound to the sentinel. The
+// trailing `.then()` is a preserved no-op call → DCE-safe anchor for the
+// post-bundle return insert (a bare `__CAPTURE_RESULT;` statement can be dropped
+// by tree-shaking; a call survives).
+function buildEntry(code: string): string {
+  const { imports, body } = splitLeadingImports(code);
+  const expr = body.trim().replace(/;+\s*$/, "");
+  return [
+    imports,
+    `const ${SENTINEL} = (async () => { ${expr} })();`,
+    `${SENTINEL}.then();`,
+  ].join("\n");
+}
+
+// Maps the two bare specifier shapes (`@vallum/_runtime`, `libs/<name>`) to
+// absolute source paths in the DEFAULT `file` namespace — no custom namespace,
+// no onLoad. esbuild then natively resolves each file's own relative imports
+// (`./context`, `./messages/send`) and npm imports (`zod`) off disk, pulling the
+// whole nested source tree in for free.
+function vaultResolver(): Plugin {
+  const libs = vaultLibsDir();
+  const runtime = path.join(libs, "_runtime", "index.ts");
+  return {
+    name: "vault",
+    setup(build) {
+      build.onResolve({ filter: /^@vallum\/_runtime$/ }, () => ({
+        path: runtime,
+      }));
+      build.onResolve({ filter: /^libs\// }, (args) => {
+        const name = args.path.slice("libs/".length);
+        if (!isValidLibName(name)) {
+          return { errors: [{ text: unknownLibMsg(name) }] };
+        }
+        const entry = path.join(libs, name, "index.ts");
+        return fs.existsSync(entry)
+          ? { path: entry }
+          : { errors: [{ text: unknownLibMsg(name) }] };
+      });
+    },
+  };
+}
+
+async function runEsbuild(entry: string): Promise<BuildResult<{ write: false }>> {
+  const esbuild = await loadEsbuild();
+  const opts = {
+    stdin: {
+      contents: entry,
+      resolveDir: vaultRepoRoot(),
+      loader: "ts" as const,
+      sourcefile: "exec.ts",
+    },
+    plugins: [vaultResolver()],
+    bundle: true,
+    write: false as const,
+    format: "iife" as const,
+    target: "es2020",
+    platform: "browser" as const,
+    treeShaking: true,
+    minify: false,
+    logLevel: "silent" as const,
+  };
+  try {
+    return await esbuild.build(opts);
+  } catch (error) {
+    // esbuild's background process can crash, making all future calls fail with
+    // "The service is no longer running". stop() forces a fresh process; retry once.
+    if (
+      error instanceof Error &&
+      error.message.includes("service is no longer running")
+    ) {
+      esbuild.stop();
+      return await esbuild.build(opts);
+    }
+    throw error;
+  }
+}
+
+// The only post-bundle edit: esbuild's iife wrapper `(() => { … })()` has no
+// return, so the script completion value is undefined. Insert `return ` before
+// the last `__CAPTURE_RESULT.then(` so the IIFE returns the user's promise.
+function applyReturnInsert(bundled: string): string {
+  const anchor = `${SENTINEL}.then(`;
+  const i = bundled.lastIndexOf(anchor);
+  return i === -1 ? bundled : bundled.slice(0, i) + "return " + bundled.slice(i);
+}
+
+function formatBuildErrors(errors: Message[]): string {
+  return errors
+    .map((e) => {
+      const l = e.location;
+      const loc = l ? ` (${l.file}:${l.line}:${l.column})` : "";
+      return `${e.text}${loc}`;
+    })
+    .join("\n");
+}
+
+/**
+ * Bundle import-bearing exec code into a complete IIFE string that returns the
+ * user's promise. Throws an Error whose message formats esbuild's `errors[]`
+ * (text + file:line:col) on a build/resolve failure — exec.ts prints it and
+ * exits before opening a CDP connection.
+ */
+export async function bundleExec(code: string): Promise<string> {
+  preflightLibs(splitLeadingImports(code).imports);
+  const entry = buildEntry(code);
+  let result: BuildResult<{ write: false }>;
+  try {
+    result = await runEsbuild(entry);
+  } catch (error) {
+    const errs = (error as { errors?: Message[] })?.errors;
+    if (Array.isArray(errs) && errs.length > 0) {
+      throw new Error(formatBuildErrors(errs));
+    }
+    throw error;
+  }
+  if (!result.outputFiles || result.outputFiles.length === 0) {
+    throw new Error("esbuild produced no output");
+  }
+  return applyReturnInsert(result.outputFiles[0].text);
+}

package/src/vault/docs.ts

@@ -0,0 +1,224 @@
+/**
+ * vault/docs — on-demand library doc generation + sha-keyed cache.
+ *
+ * Reimplements vault's `generateDocs` (northlight-vault
+ * lib-pipeline/build/build-libs.ts:138-184) in-process, dropping the
+ * manifest/sha/scripts half: for a lib we esbuild-bundle its `schemas.ts` to a
+ * self-contained CJS string (zod inlined from node_modules by `bundle:true`),
+ * evaluate it in-memory, then convert each function's Zod input/output to JSON
+ * Schema (Zod-4-native `toJSONSchema()`, with the `void` special-case ported
+ * verbatim). Results are cached gitignored under `vault/.cache/docs/<svc>.json`
+ * with an embedded `_srcSha` = sha256(schemas.ts); a stale/missing sha rebuilds.
+ *
+ * Nothing here imports `esbuild` at the top level — it is loaded lazily via
+ * `loadEsbuild()` so the published package (no `vault/`, no `esbuild`) degrades
+ * to a single `DEV_ONLY_MSG` instead of crashing.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { createHash } from "crypto";
+import {
+  vaultLibsDir,
+  vaultRepoRoot,
+  listLibs,
+  loadEsbuild,
+  isValidLibName,
+  unknownLibMsg,
+} from "./paths.js";
+
+/** A single library function's doc entry (input/output are JSON Schema). */
+export interface LibraryDocFunction {
+  name: string;
+  description: string;
+  notes?: string;
+  input: unknown;
+  output: unknown;
+}
+
+/** A library's generated doc — same shape `nl lib read --json` returns. */
+export interface LibraryDoc {
+  /** `@vallum/<svc>` */
+  library: string;
+  description: string;
+  notes?: string;
+  loginUrl?: string;
+  /** `'public' | 'chat' | 'hidden'` (default `'public'`). */
+  visibility: string;
+  functions: LibraryDocFunction[];
+}
+
+/** Shape of each entry in a lib's `schemas.ts` exported `allSchemas` array. */
+interface FunctionSchema {
+  name: string;
+  description: string;
+  notes?: string;
+  input: unknown;
+  output: unknown;
+}
+
+/** Mirrors `nl lib`'s agent-visible filter (vault-client.service.ts:49). */
+const AGENT_VISIBLE_VISIBILITIES = new Set(["public", "chat"]);
+
+/** True iff a doc is agent-visible (visibility ∈ {public, chat}). */
+export function isAgentVisible(doc: LibraryDoc): boolean {
+  return AGENT_VISIBLE_VISIBILITIES.has(doc.visibility);
+}
+
+/**
+ * A `require` for the in-memory CJS eval below. zod is inlined by `bundle:true`
+ * so this is never actually hit — it's passed defensively. Ambient `require` is
+ * available under both the built CJS bin (native) and tsx-ESM (injected into a
+ * real module). We avoid `createRequire(import.meta.url)` because `import.meta`
+ * is empty under the CJS bin build (esbuild) and would throw at module load.
+ */
+declare const require: ((id: string) => unknown) | undefined;
+const cjsRequire = (id: string): unknown => {
+  if (typeof require === "function") return require(id);
+  throw new Error(`cannot require('${id}') — unavailable in this runtime`);
+};
+
+function cacheDir(): string {
+  return path.join(vaultRepoRoot(), ".cache", "docs");
+}
+
+function schemasPathFor(svc: string): string {
+  return path.join(vaultLibsDir(), svc, "schemas.ts");
+}
+
+function srcSha(svc: string): string {
+  return createHash("sha256")
+    .update(fs.readFileSync(schemasPathFor(svc), "utf8"))
+    .digest("hex");
+}
+
+/**
+ * Zod → JSON Schema, porting build-libs.ts:155-173 verbatim. `z.void()` has no
+ * JSON-Schema representation, so it maps to `{type:'null'}` (carrying its
+ * description if present); everything else uses Zod 4's `toJSONSchema()`.
+ */
+function toJsonSchema(zodSchema: unknown): unknown {
+  const s = zodSchema as {
+    _zod?: { def?: { type?: string } };
+    description?: string;
+    toJSONSchema?: () => unknown;
+  };
+  if (s?._zod?.def?.type === "void") {
+    const desc = s.description;
+    return desc ? { type: "null", description: desc } : { type: "null" };
+  }
+  if (!s?.toJSONSchema) {
+    throw new Error(
+      "Schema missing toJSONSchema method - ensure Zod 4+ is installed",
+    );
+  }
+  return s.toJSONSchema();
+}
+
+/**
+ * Build one lib's doc from source: esbuild-bundle its `schemas.ts` to a
+ * self-contained CJS string, eval it in-memory, assemble the `LibraryDoc`.
+ */
+async function buildDoc(svc: string): Promise<LibraryDoc> {
+  const esbuild = await loadEsbuild();
+  const result = await esbuild.build({
+    entryPoints: [schemasPathFor(svc)],
+    bundle: true,
+    write: false,
+    format: "cjs",
+    platform: "node",
+    target: "es2020",
+    logLevel: "silent",
+  });
+  const text = result.outputFiles?.[0]?.text;
+  if (!text) throw new Error(`esbuild produced no output for ${svc}/schemas.ts`);
+
+  // In-memory CJS eval (no temp file). zod is inlined by bundle:true, so the
+  // `require` arg is never actually hit — passed defensively for any edge.
+  const mod = { exports: {} as Record<string, unknown> };
+  new Function("module", "exports", "require", text)(
+    mod,
+    mod.exports,
+    cjsRequire,
+  );
+  const x = mod.exports as {
+    allSchemas?: FunctionSchema[];
+    libraryDescription?: string;
+    libraryNotes?: string;
+    loginUrl?: string;
+    libraryVisibility?: string;
+  };
+
+  const allSchemas = x.allSchemas ?? [];
+  const doc: LibraryDoc = {
+    library: `@vallum/${svc}`,
+    description: x.libraryDescription ?? `${svc} service library`,
+    visibility: x.libraryVisibility ?? "public",
+    functions: allSchemas.map((schema) => ({
+      name: schema.name,
+      description: schema.description,
+      ...(schema.notes ? { notes: schema.notes } : {}),
+      input: toJsonSchema(schema.input),
+      output: toJsonSchema(schema.output),
+    })),
+  };
+  if (x.libraryNotes) doc.notes = x.libraryNotes;
+  if (x.loginUrl) doc.loginUrl = x.loginUrl;
+  return doc;
+}
+
+/**
+ * Get one lib's doc — reads the sha-valid cache if present, else (re)builds and
+ * writes it. May read ANY present lib (no visibility filter); used by
+ * `lib read`. Throws `Unknown lib …` if the named lib has no `schemas.ts`.
+ */
+export async function getDoc(name: string): Promise<LibraryDoc> {
+  if (!isValidLibName(name) || !fs.existsSync(schemasPathFor(name))) {
+    throw new Error(unknownLibMsg(name));
+  }
+  const sha = srcSha(name);
+  const cacheFile = path.join(cacheDir(), `${name}.json`);
+  if (fs.existsSync(cacheFile)) {
+    try {
+      const cached = JSON.parse(fs.readFileSync(cacheFile, "utf8")) as
+        & LibraryDoc
+        & { _srcSha?: string };
+      if (cached._srcSha === sha) {
+        delete cached._srcSha;
+        return cached;
+      }
+    } catch {
+      // corrupt/unreadable cache → fall through and rebuild
+    }
+  }
+  const doc = await buildDoc(name);
+  fs.mkdirSync(cacheDir(), { recursive: true });
+  fs.writeFileSync(
+    cacheFile,
+    JSON.stringify({ ...doc, _srcSha: sha }, null, 2),
+  );
+  return doc;
+}
+
+/**
+ * All agent-visible libs' docs (visibility ∈ {public, chat}). Lazily builds any
+ * missing/stale doc, then filters by visibility. A lib whose `schemas.ts` fails
+ * to build is skipped with a stderr warning rather than failing the whole list.
+ * Used by `lib list`/`search`/`show`.
+ */
+export async function listDocs(): Promise<LibraryDoc[]> {
+  const out: LibraryDoc[] = [];
+  for (const name of listLibs()) {
+    let doc: LibraryDoc;
+    try {
+      doc = await getDoc(name);
+    } catch (e) {
+      console.error(
+        `WARN: skipping lib "${name}" — ${(e as Error).message}`,
+      );
+      continue;
+    }
+    if (isAgentVisible(doc)) out.push(doc);
+  }
+  return out;
+}