@crouton-kit/capture 1.3.8 → 1.3.10

package/src/session-context.ts

@@ -1,96 +1,318 @@
 /**
- * Session Context — persists active session state so CDP commands
- * can auto-fill --target, --har, and --out without manual threading.
+ * Session Context — persists active session state so CDP commands can target
+ * the session tab and write session-owned artifacts without manual threading.
  *
- * State is written to /tmp/capture-sessions/.active-<scope> (JSON), where
- * <scope> isolates concurrent callers (see activeScopeKey() below) so one
- * caller's `session start` never clobbers another's active pointer.
- * Stale sessions (dir deleted, crashed process) are cleaned up on read.
+ * A scoped, private active-index `.active-<scope>` only tracks the active
+ * session identity and directory; mutable/live state lives in the canonical
+ * per-session `.session.json` file under that directory.
  */
 
-import * as fs from 'fs';
-import * as path from 'path';
-import { CAPTURE_ROOT } from './session/artifacts.js';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  CAPTURE_ROOT,
+  acquirePrivateLock,
+  assertUnderCaptureRoot,
+  ensurePrivateDir,
+  parseRegisteredLogTailer,
+  readPrivateFile,
+  removeArtifactTree,
+  unlinkPrivateFile,
+  writeJsonPrivate,
+  type RecMeta,
+  type RegisteredLogTailer,
+  type SnapMeta,
+} from './session/artifacts.js';
 
-/**
- * The active-session pointer is scoped per caller so concurrent, unrelated
- * capture invocations never clobber one another's "active session" — e.g.
- * two crtr agent nodes each running `capture session start` in parallel.
- * When invoked from a crtr node, CRTR_NODE_ID scopes the pointer to that
- * node (stable across separate tool calls within the node's lifetime).
- * Outside crtr (a bare interactive terminal), there's no such identity, so
- * fall back to the single legacy pointer — the original single-user,
- * single-session-at-a-time contract still holds there.
- */
 function activeScopeKey(): string {
   return process.env.CRTR_NODE_ID ?? 'default';
 }
 
+export function activeSessionScopeKey(): string {
+  return activeScopeKey();
+}
+
 function getActivePath(): string {
   return path.join(CAPTURE_ROOT, `.active-${activeScopeKey()}`);
 }
 
+interface ActiveSessionIndex {
+  sessionId: string;
+  dir: string;
+}
+
+/** The sole authoritative mutable record stored in `<dir>/.session.json`. */
 export interface ActiveSessionState {
   sessionId: string;
   dir: string;
   harId: string | null;
+  startedAt?: string;
+  url?: string | null;
   targetId: string | null;
   stepCount: number;
+  /** Identity-bearing registered log tailer handles owned by this session. */
+  logPids?: RegisteredLogTailer[];
+  /**
+   * Optional CDP endpoint socket port used by this session.
+   * Session index files never keep this; it is only in `.session.json`.
+   */
+  port?: number | null;
   /** Unix socket of the session's held CDP bridge (`session start --hold`), if any. */
   bridgeSocket?: string | null;
+  /** Network.emulateNetworkConditions offline state for the session target. */
+  networkOffline?: boolean;
+  /** Child process id of the held CDP bridge, if any. */
+  bridgePid?: number | null;
   /**
-   * The id of the recording (`motion/recs/{recId}`) currently live under
-   * this session, if `motion rec --start` has armed one. Cleared by
-   * `motion rec --stop` (or a stale-recorder reap). See
-   * {@link setActiveRecId}/{@link clearActiveRecId}/{@link getActiveRecId}.
+   * The id of the recording (`motion/recs/{recId}`) currently live under this
+   * session, if `motion rec --start` has armed one.
    */
   activeRecId?: string | null;
+  /** Marker written after successful stop to keep stale active indices from blocking.
+   * It is not part of the active index; only read from `.session.json`.
+   */
+  stoppedAt?: string | null;
+  /** Optional per-session run-state marker used by later lifecycle units. */
+  stopping?: boolean;
+}
+
+function isIndex(value: unknown): value is ActiveSessionIndex {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return typeof record.sessionId === 'string' && typeof record.dir === 'string';
+}
+
+/** Directory-entry identity of the `.active-<scope>` pointer, for compare-clear. */
+interface ActiveEntryIdentity {
+  dev: string;
+  ino: string;
+}
+
+function statActiveEntry(): ActiveEntryIdentity | null {
+  try {
+    const stat = fs.lstatSync(getActivePath(), { bigint: true });
+    return { dev: stat.dev.toString(), ino: stat.ino.toString() };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+interface ActivePointer {
+  index: ActiveSessionIndex | null;
+  /** Identity of the exact entry this read observed; null when no entry existed. */
+  entry: ActiveEntryIdentity | null;
+}
+
+/**
+ * Reads the active pointer together with the identity of the directory entry
+ * it came from. The identity is captured BEFORE the content read, so a stale
+ * determination made from these bytes can only ever authorize clearing this
+ * exact inode — never a pointer published after it.
+ */
+function readActivePointer(): ActivePointer {
+  const entry = statActiveEntry();
+  if (!entry) return { index: null, entry: null };
+  try {
+    const raw = readPrivateFile(getActivePath()).toString('utf-8');
+    const parsed = JSON.parse(raw) as unknown;
+    if (!isIndex(parsed)) return { index: null, entry };
+    return { index: { sessionId: parsed.sessionId, dir: parsed.dir }, entry };
+  } catch {
+    return { index: null, entry };
+  }
+}
+
+function sessionMetaPath(sessionDir: string): string {
+  return path.join(sessionDir, '.session.json');
+}
+
+function sessionStateLockPath(sessionDir: string): string {
+  return path.join(assertUnderCaptureRoot(sessionDir), '.session-state.lock');
+}
+
+async function withSessionStateLock<T>(sessionDir: string, action: () => T): Promise<T> {
+  const lock = await acquirePrivateLock(sessionStateLockPath(sessionDir), {
+    acquireTimeoutMs: 30_000,
+    leaseMs: 500,
+  });
+  try {
+    return action();
+  } finally {
+    lock.release();
+  }
+}
+
+/** The one schema check for a persisted `.session.json` record. Exported so
+ * every session-record reader (here and `session/commands.ts`) validates the
+ * same shape instead of trusting parsed JSON structurally. */
+export function isActiveStateCandidate(value: unknown): value is ActiveSessionState {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  const nullableString = (field: unknown): boolean => field === undefined || field === null || typeof field === 'string';
+  const nullablePid = (field: unknown): boolean => field === undefined || field === null || (Number.isSafeInteger(field) && (field as number) > 0);
+  const validLogs = record.logPids === undefined
+    || (Array.isArray(record.logPids) && record.logPids.every(item => parseRegisteredLogTailer(item) !== undefined));
+  return typeof record.sessionId === 'string' && record.sessionId.length > 0
+    && typeof record.dir === 'string'
+    && (record.harId === null || typeof record.harId === 'string')
+    && nullableString(record.startedAt)
+    && nullableString(record.url)
+    && (record.targetId === null || typeof record.targetId === 'string')
+    && typeof record.stepCount === 'number'
+    && Number.isSafeInteger(record.stepCount)
+    && record.stepCount >= 0
+    && validLogs
+    && (record.port === undefined || record.port === null || (Number.isInteger(record.port) && (record.port as number) > 0 && (record.port as number) <= 65535))
+    && nullableString(record.bridgeSocket)
+    && nullablePid(record.bridgePid)
+    && nullableString(record.activeRecId)
+    && nullableString(record.stoppedAt)
+    && (record.stopping === undefined || typeof record.stopping === 'boolean');
 }
 
-export function getActiveSession(): ActiveSessionState | null {
+function clearActivePath(): void {
+  const activePath = getActivePath();
   try {
-    const activePath = getActivePath();
-    if (!fs.existsSync(activePath)) return null;
-    const state = JSON.parse(fs.readFileSync(activePath, 'utf-8')) as ActiveSessionState;
-    // Validate session dir still exists — clean up stale files
-    if (!fs.existsSync(state.dir)) {
-      clearActiveSession();
+    unlinkPrivateFile(activePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+    // A stale planted symlink is itself an index entry, never a target to follow.
+    try { removeArtifactTree(activePath); } catch { /* stale cleanup is best effort */ }
+  }
+}
+
+/**
+ * Compare-clear (A2/U03): removes the active pointer only while the directory
+ * entry is still the exact inode the deciding read observed. A concurrent
+ * `session start` publishes its pointer as a fresh inode via rename, so a
+ * pointer republished after that read is never unlinked by a slow stale-clean
+ * and the scope's one-live-session cardinality is preserved.
+ */
+function clearActiveEntry(expected: ActiveEntryIdentity | null): void {
+  if (!expected) return;
+  const current = statActiveEntry();
+  if (!current || current.dev !== expected.dev || current.ino !== expected.ino) return;
+  clearActivePath();
+}
+
+/**
+ * Reads active session metadata. Endpoint resolution uses `cleanStale: false`
+ * while it decides whether a malformed ambient CDP_PORT is relevant: that
+ * preserves a stale pointer for the invocation error path. Normal command
+ * consumers retain the default eager stale-index cleanup.
+ */
+export function getActiveSession({ cleanStale = true }: { cleanStale?: boolean } = {}): ActiveSessionState | null {
+  const pointer = readActivePointer();
+  const clean = (): void => { if (cleanStale) clearActiveEntry(pointer.entry); };
+  const index = pointer.index;
+  if (!index) {
+    clean();
+    return null;
+  }
+
+  try {
+    const sessionDir = assertUnderCaptureRoot(path.resolve(index.dir));
+    if (sessionDir !== index.dir) throw new Error('active session directory escaped capture root');
+
+    try {
+      readPrivateFile(path.join(sessionDir, 'bundle.json'));
+      clean();
       return null;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
     }
+
+    const raw = readPrivateFile(sessionMetaPath(sessionDir)).toString('utf-8');
+    const parsed = JSON.parse(raw) as unknown;
+    if (!isActiveStateCandidate(parsed)) {
+      clean();
+      return null;
+    }
+
+    const state = parsed as ActiveSessionState;
+    if (state.sessionId !== index.sessionId || state.dir !== sessionDir) {
+      clean();
+      return null;
+    }
+    if (state.stoppedAt) {
+      clean();
+      return null;
+    }
+
+    ensurePrivateDir(sessionDir);
     return state;
   } catch {
+    // Any malformed/corrupt pointer or metadata file is stale. Endpoint
+    // precedence may inspect it without mutation; all ordinary callers clean.
+    clean();
     return null;
   }
 }
 
-export function setActiveSession(state: ActiveSessionState): void {
-  fs.mkdirSync(CAPTURE_ROOT, { recursive: true });
-  fs.writeFileSync(getActivePath(), JSON.stringify(state, null, 2));
+export async function setActiveSession(state: ActiveSessionState): Promise<void> {
+  const sessionDir = ensurePrivateDir(state.dir);
+  const next: ActiveSessionState = {
+    ...state,
+    dir: path.resolve(sessionDir),
+    sessionId: state.sessionId,
+    harId: state.harId,
+    targetId: state.targetId,
+    stepCount: Number.isSafeInteger(state.stepCount) ? state.stepCount : 0,
+  };
+  const index: ActiveSessionIndex = { sessionId: next.sessionId, dir: next.dir };
+
+  await withSessionStateLock(next.dir, () => {
+    writeJsonPrivate(sessionMetaPath(next.dir), next);
+    writeJsonPrivate(getActivePath(), index);
+  });
 }
 
 export function clearActiveSession(): void {
-  try {
-    fs.unlinkSync(getActivePath());
-  } catch {
-    // Already gone
+  clearActivePath();
+}
+
+export function clearActiveSessionIf(sessionId: string): void {
+  const pointer = readActivePointer();
+  if (pointer.index?.sessionId === sessionId) {
+    clearActiveEntry(pointer.entry);
   }
 }
 
-export function updateActiveSession(patch: Partial<ActiveSessionState>): ActiveSessionState | null {
+async function mutateSessionState(
+  sessionDir: string,
+  mutate: (current: ActiveSessionState) => ActiveSessionState,
+): Promise<ActiveSessionState> {
+  const canonical = assertUnderCaptureRoot(sessionDir);
+  return withSessionStateLock(canonical, () => {
+    const metaPath = sessionMetaPath(canonical);
+    const current = JSON.parse(readPrivateFile(metaPath).toString('utf-8')) as unknown;
+    if (!isActiveStateCandidate(current) || current.dir !== canonical) throw new Error(`invalid session metadata: ${metaPath}`);
+    const next = mutate(current);
+    const updated = { ...next, dir: current.dir, sessionId: current.sessionId };
+    if (!isActiveStateCandidate(updated)) throw new Error(`invalid session metadata update: ${metaPath}`);
+    writeJsonPrivate(metaPath, updated);
+    return updated;
+  });
+}
+
+export function updateSessionState(sessionDir: string, patch: Partial<ActiveSessionState>): Promise<ActiveSessionState> {
+  return mutateSessionState(sessionDir, current => ({ ...current, ...patch }));
+}
+
+export async function updateActiveSession(patch: Partial<ActiveSessionState>): Promise<ActiveSessionState | null> {
   const current = getActiveSession();
   if (!current) return null;
-  const updated = { ...current, ...patch };
-  setActiveSession(updated);
-  return updated;
+  return updateSessionState(current.dir, patch);
 }
 
 /** Records `recId` as the active session's live recording. */
-export function setActiveRecId(recId: string): ActiveSessionState | null {
+export function setActiveRecId(recId: string): Promise<ActiveSessionState | null> {
   return updateActiveSession({ activeRecId: recId });
 }
 
 /** Clears the active session's live-recording pointer (on `rec --stop` / stale reap). */
-export function clearActiveRecId(): ActiveSessionState | null {
+export function clearActiveRecId(): Promise<ActiveSessionState | null> {
   return updateActiveSession({ activeRecId: null });
 }
 
@@ -99,6 +321,11 @@ export function getActiveRecId(): string | null {
   return getActiveSession()?.activeRecId ?? null;
 }
 
+/** Records the active session target's requested network emulation state. */
+export function setActiveNetworkOffline(offline: boolean): ActiveSessionState | null {
+  return updateActiveSession({ networkOffline: offline });
+}
+
 function sanitizeLabel(label: string): string {
   return label
     .toLowerCase()
@@ -112,16 +339,17 @@ function sanitizeLabel(label: string): string {
  * Format: {dir}/shots/{NN}-{action}-{sanitized-label}.png
  * Increments stepCount in the session state.
  */
-export function nextStepPath(action: string, label: string): string | null {
+export async function nextStepPath(action: string, label: string): Promise<string | null> {
   const session = getActiveSession();
   if (!session) return null;
 
-  const step = session.stepCount + 1;
-  const nn = String(step).padStart(2, '0');
+  const updated = await mutateSessionState(session.dir, current => ({
+    ...current,
+    stepCount: current.stepCount + 1,
+  }));
+  const nn = String(updated.stepCount).padStart(2, '0');
   const sanitized = sanitizeLabel(label);
-  const filename = `${nn}-${action}-${sanitized}.png`;
-  const shotPath = path.join(session.dir, 'shots', filename);
-
-  updateActiveSession({ stepCount: step });
-  return shotPath;
+  return path.join(updated.dir, 'shots', `${nn}-${action}-${sanitized}.png`);
 }
+
+export { type SnapMeta, type RecMeta };

package/src/vault/bundle.ts

@@ -1,13 +1,10 @@
 /**
- * vault/bundle — the import-driven exec engine.
+ * vault/bundle — the import-driven `page 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.
+ * When `capture page exec` receives 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 evaluates over CDP.
  *
  * No top-level `esbuild` import — it is loaded lazily via `loadEsbuild()` so the
  * published package (no esbuild) never crashes at startup.
@@ -23,6 +20,7 @@ import {
   vaultLibsDir,
   vaultRepoRoot,
 } from "./paths.js";
+import { buildExecExpression } from "../cdp/exec-expression.js";
 
 // Sentinel the post-bundle return-insert anchors on. esbuild with minify:false
 // never renames top-level identifiers, and no first-party lib references
@@ -82,17 +80,24 @@ function preflightLibs(imports: string): void {
   }
 }
 
-// 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).
+// Hoist the imports to module top level (so esbuild resolves & tree-shakes
+// them) and bind the post-import body's VALUE to the sentinel. The body's
+// semantics are owned by `buildExecExpression` — the same single authority
+// plain (import-free) exec uses — so a natural final expression, explicit
+// top-level return, top-level await, and a thrown exception behave
+// identically with and without imports. `Promise.resolve` normalizes the
+// built expression's value (a bare expression evaluates to a plain value,
+// the wrapped forms to a promise) so the trailing `.then()` — 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) — always exists. The inner parens keep a comma expression one
+// argument.
 function buildEntry(code: string): string {
   const { imports, body } = splitLeadingImports(code);
-  const expr = body.trim().replace(/;+\s*$/, "");
+  const expression = buildExecExpression(body);
   return [
     imports,
-    `const ${SENTINEL} = (async () => { ${expr} })();`,
+    `const ${SENTINEL} = Promise.resolve((${expression}));`,
     `${SENTINEL}.then();`,
   ].join("\n");
 }
@@ -163,10 +168,20 @@ async function runEsbuild(entry: string): Promise<BuildResult<{ write: false }>>
 // 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 {
+// The anchor is an invariant `buildEntry` establishes (the preserved `.then()`
+// call survives tree-shaking, and minify:false keeps the sentinel name), so a
+// missing anchor is a broken bundle — evaluating it would silently complete
+// with undefined instead of the code's value. Hard error, never a returnless
+// bundle. Exported for its focused test (test/bundle.test.ts).
+export 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);
+  if (i === -1) {
+    throw new Error(
+      `bundled exec output lost its ${SENTINEL}.then( return anchor — the bundle would complete with undefined instead of the code's value`,
+    );
+  }
+  return bundled.slice(0, i) + "return " + bundled.slice(i);
 }
 
 function formatBuildErrors(errors: Message[]): string {

package/src/cdp/commands/exec.ts

@@ -1,105 +0,0 @@
-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. 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 "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\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);
-  }
-  let code: string;
-  if (parsed.file) {
-    code = fs.readFileSync(parsed.file, 'utf-8');
-  } else {
-    code = parsed.positional[0];
-    if (!code) {
-      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',
-      );
-      process.exit(1);
-    }
-  }
-
-  // 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) => {
-      await client.send('Emulation.setFocusEmulationEnabled', { enabled: true });
-
-      // Standalone HAR recording (--record flag writes its own file)
-      let standaloneRecorder: HARRecorder | undefined;
-      if (parsed.record) {
-        standaloneRecorder = new HARRecorder(client);
-        await standaloneRecorder.start();
-      }
-
-      // 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,
-        awaitPromise: true,
-        returnByValue: true,
-      })) as {
-        result?: { value?: unknown };
-        exceptionDetails?: { exception?: { description?: string } };
-      };
-
-      if (standaloneRecorder) {
-        const har = await standaloneRecorder.finish();
-        writeHarAndPrintSummary(har, parsed.harOut);
-      }
-
-      if (evalResult.exceptionDetails) {
-        console.error(
-          `ERROR: ${evalResult.exceptionDetails.exception?.description ?? 'Unknown error'}`,
-        );
-        process.exit(1);
-      }
-
-      console.log(JSON.stringify(evalResult.result?.value));
-    },
-    { settle: 3000 },
-  );
-  return;
-}