@crouton-kit/capture 1.3.3 → 1.3.5

package/src/session/commands.ts

@@ -0,0 +1,385 @@
+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 {
+  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}`);
+}
+
+export 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));
+  }
+}
+
+export 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`);
+  }
+}

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);
+}