@crouton-kit/capture 1.3.6 → 1.3.8

package/src/session/commands.ts

@@ -1,6 +1,5 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import * as os from 'os';
 import { spawn } from 'child_process';
 import {
   createHarRecording,
@@ -13,8 +12,15 @@ import {
   clearActiveSession,
 } from '../session-context.js';
 import { expandEqualsFlags } from '../cdp/args.js';
-
-const CAPTURE_ROOT = path.join(os.tmpdir(), 'capture-sessions');
+import { startBridge, stopBridge } from '../cdp/bridge/spawn.js';
+import {
+  CAPTURE_ROOT,
+  FILE_MODE,
+  ensurePrivateDir,
+  writeJsonPrivate,
+  type SnapMeta,
+  type RecMeta,
+} from './artifacts.js';
 
 interface LogPid {
   pid: number;
@@ -31,6 +37,9 @@ interface Session {
   targetId: string | null;
   stepCount: number;
   logPids: LogPid[];
+  /** Set when started with --hold: one CDP browser connection held open for the session. */
+  bridgeSocket: string | null;
+  bridgePid: number | null;
 }
 
 interface BundleManifest {
@@ -44,12 +53,90 @@ interface BundleManifest {
   a11y: Array<{ name: string; path: string }>;
   logs: Array<{ name: string; path: string; lines: number }>;
   other: Array<{ name: string; path: string }>;
+  /** `measure snap` artifacts collected from `measure/snaps/{id}/meta.json`. */
+  snaps: Array<{ id: string; path: string; url: string | null; viewport: string | null; settled: boolean; capturedAt: string }>;
+  /** `motion rec` artifacts collected from `motion/recs/{id}/meta.json`. */
+  recs: Array<{ id: string; path: string; action: string | null; frames: number; durationMs: number; state: string }>;
 }
 
 function sessionDir(id: string): string {
   return path.join(CAPTURE_ROOT, id);
 }
 
+/** One-shot artifact session outside an active session — see `createOneshotSession`. */
+export interface OneshotSession {
+  /** `oneshot-{id}`; also the dir name under `CAPTURE_ROOT`. */
+  id: string;
+  /** `{CAPTURE_ROOT}/oneshot-{id}` */
+  dir: string;
+  kind: 'measure' | 'motion';
+  /** `{dir}/measure/snaps` or `{dir}/motion/recs`, already created private. */
+  artifactsDir: string;
+}
+
+/**
+ * Creates the ephemeral artifact dir a URL-target `measure`/`motion` leaf
+ * writes into when there is no active session: `oneshot-{id}/measure/snaps`
+ * or `oneshot-{id}/motion/recs` under `CAPTURE_ROOT`. Holds only the one
+ * subtree the caller needs — no HAR, no held bridge, no `.session.json` —
+ * and is never registered as the active session. It is not bundled/torn
+ * down by `session stop`; it accumulates under `/tmp` the same as any other
+ * session dir until the OS reaps `/tmp`.
+ */
+export function createOneshotSession(kind: 'measure' | 'motion'): OneshotSession {
+  const id = `oneshot-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  const dir = sessionDir(id);
+  const artifactsDir = kind === 'measure'
+    ? path.join(dir, 'measure', 'snaps')
+    : path.join(dir, 'motion', 'recs');
+  ensurePrivateDir(artifactsDir);
+  return { id, dir, kind, artifactsDir };
+}
+
+/** Reads one `measure/snaps/{id}/meta.json` and shapes it into a manifest `snaps[]` entry. */
+function readSnapMeta(snapDir: string, fallbackId: string): BundleManifest['snaps'][number] {
+  const meta = JSON.parse(fs.readFileSync(path.join(snapDir, 'meta.json'), 'utf-8')) as Partial<SnapMeta>;
+  return {
+    id: meta.id ?? fallbackId,
+    path: snapDir,
+    url: meta.url ?? null,
+    viewport: meta.viewport ?? null,
+    settled: meta.settled ?? false,
+    capturedAt: meta.capturedAt ?? '',
+  };
+}
+
+/** Reads one `motion/recs/{id}/meta.json` and shapes it into a manifest `recs[]` entry. */
+function readRecMeta(recDir: string, fallbackId: string): BundleManifest['recs'][number] {
+  const meta = JSON.parse(fs.readFileSync(path.join(recDir, 'meta.json'), 'utf-8')) as Partial<RecMeta>;
+  return {
+    id: meta.id ?? fallbackId,
+    path: recDir,
+    action: meta.action ?? null,
+    frames: meta.frames ?? 0,
+    durationMs: meta.durationMs ?? 0,
+    state: meta.state ?? 'unknown',
+  };
+}
+
+/** Collects finalized snapshots under `{session.dir}/measure/snaps/{id}/meta.json`. */
+function collectSnaps(dir: string): BundleManifest['snaps'] {
+  const snapsRoot = path.join(dir, 'measure', 'snaps');
+  if (!fs.existsSync(snapsRoot)) return [];
+  return fs.readdirSync(snapsRoot)
+    .filter((name) => fs.existsSync(path.join(snapsRoot, name, 'meta.json')))
+    .map((name) => readSnapMeta(path.join(snapsRoot, name), name));
+}
+
+/** Collects finalized recordings under `{session.dir}/motion/recs/{id}/meta.json`. */
+function collectRecs(dir: string): BundleManifest['recs'] {
+  const recsRoot = path.join(dir, 'motion', 'recs');
+  if (!fs.existsSync(recsRoot)) return [];
+  return fs.readdirSync(recsRoot)
+    .filter((name) => fs.existsSync(path.join(recsRoot, name, 'meta.json')))
+    .map((name) => readRecMeta(path.join(recsRoot, name), name));
+}
+
 function sessionMetaPath(id: string): string {
   return path.join(sessionDir(id), '.session.json');
 }
@@ -90,10 +177,12 @@ 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)
+  start [--url <url>] [--hold]    Start a session (opens tab, records HAR, sets active context)
+                                   --hold keeps one CDP browser connection open for the session
   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
+  view  <id> [--filter section]   View bundle manifest; section = screenshots|har|a11y|logs|measure|motion
+                                   measure -> manifest.snaps, motion -> manifest.recs
 
 Why sessions: once started, every subsequent capture command auto-fills
 --target (the tab) and --har (the recording). No manual flag threading.
@@ -110,6 +199,17 @@ Typical flow:
   3. capture session stop <session-id>
   4. capture session view <session-id>
 
+--hold: keeps one CDP browser connection open for the session's lifetime, so
+browser-level state (Browser.grantPermissions, ServiceWorker.enable, ...)
+survives across separate commands instead of reverting the instant each
+command's own connection closes. Use it together with \`capture cdp --browser\`:
+
+  capture session start --url http://localhost:3000 --hold
+  capture cdp Browser.grantPermissions --browser --params '{"origin":"http://localhost:3000","permissions":["notifications"]}'
+  capture cdp ServiceWorker.enable --browser --target <pageTabId>
+  capture cdp ServiceWorker.deliverPushMessage --browser --target <pageTabId> --params '{...}'
+  capture session stop <session-id>   # also tears down the held connection
+
 Related:  capture log <path> [--name label]   Tail a log into the active session
 See also: capture --help                      Full command list`);
 }
@@ -121,17 +221,20 @@ See also: capture --help                      Full command list`);
 async function start(rawArgs: string[]): Promise<void> {
   const args = expandEqualsFlags(rawArgs);
   let url: string | null = null;
+  let hold = false;
 
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--url' && args[i + 1]) {
       url = args[++i];
+    } else if (args[i] === '--hold') {
+      hold = true;
     }
   }
 
   const id = generateId();
   const dir = sessionDir(id);
-  fs.mkdirSync(path.join(dir, 'shots'), { recursive: true });
-  fs.mkdirSync(path.join(dir, 'a11y'), { recursive: true });
+  ensurePrivateDir(path.join(dir, 'shots'));
+  ensurePrivateDir(path.join(dir, 'a11y'));
 
   // Start HAR recording directly
   let harId: string | null = null;
@@ -145,11 +248,15 @@ async function start(rawArgs: string[]): Promise<void> {
   // Open tab if URL provided. Fail fast if the new target cannot attach.
   let targetId: string | null = null;
   let pageLoadTimedOut = false;
+  let cdpPort: number | null = null;
+  if (url || hold) {
+    const { detectCdpPort } = await import('../cdp.js');
+    cdpPort = await detectCdpPort();
+  }
   if (url) {
     try {
-      const { detectCdpPort, openTab, CDPClient } = await import('../cdp.js');
-      const port = await detectCdpPort();
-      const tab = await openTab(port, url);
+      const { openTab, CDPClient } = await import('../cdp.js');
+      const tab = await openTab(cdpPort!, url);
       targetId = tab.id;
 
       if (!targetId) {
@@ -188,6 +295,29 @@ async function start(rawArgs: string[]): Promise<void> {
     }
   }
 
+  // Hold a CDP browser connection open for the session's lifetime so
+  // browser-level state (permission grants, ServiceWorker enablement)
+  // survives across separate `capture` commands instead of reverting the
+  // instant each command's own connection closes.
+  let bridgeSocket: string | null = null;
+  let bridgePid: number | null = null;
+  if (hold) {
+    try {
+      const bridge = await startBridge(dir, cdpPort!);
+      bridgeSocket = bridge.socketPath;
+      bridgePid = bridge.pid;
+    } catch (err) {
+      if (harId) {
+        try {
+          deleteHarRecording(harId);
+        } catch {
+          /* best effort */
+        }
+      }
+      throw err;
+    }
+  }
+
   const session: Session = {
     id,
     dir,
@@ -197,8 +327,10 @@ async function start(rawArgs: string[]): Promise<void> {
     targetId,
     stepCount: 0,
     logPids: [],
+    bridgeSocket,
+    bridgePid,
   };
-  fs.writeFileSync(sessionMetaPath(id), JSON.stringify(session, null, 2));
+  writeJsonPrivate(sessionMetaPath(id), session);
 
   // Set as active session for auto-defaults
   setActiveSession({
@@ -207,6 +339,7 @@ async function start(rawArgs: string[]): Promise<void> {
     harId,
     targetId,
     stepCount: 0,
+    bridgeSocket,
   });
 
   // Output for agent consumption
@@ -218,6 +351,7 @@ async function start(rawArgs: string[]): Promise<void> {
     pageLoadTimedOut,
     shotsDir: path.join(dir, 'shots'),
     a11yDir: path.join(dir, 'a11y'),
+    held: hold,
   };
   console.log(JSON.stringify(result, null, 2));
 
@@ -229,6 +363,9 @@ async function start(rawArgs: string[]): Promise<void> {
       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.`);
     }
   }
+  if (hold) {
+    console.error(`CDP bridge held (pid ${bridgePid}) — browser-level state now survives across commands via: capture cdp <Method> --browser [--params '<json>']`);
+  }
   console.error(`\nWhen done: capture session stop ${id}`);
 }
 
@@ -269,10 +406,11 @@ export function logCommand(rawArgs: string[]): void {
   name = name ?? path.basename(resolved, path.extname(resolved));
 
   const logsDir = path.join(session.dir, 'logs');
-  fs.mkdirSync(logsDir, { recursive: true });
+  ensurePrivateDir(logsDir);
 
   const destPath = path.join(logsDir, `${name}.log`);
-  const outFd = fs.openSync(destPath, 'a');
+  const outFd = fs.openSync(destPath, 'a', FILE_MODE);
+  fs.chmodSync(destPath, FILE_MODE);
 
   const child = spawn(
     'sh',
@@ -284,7 +422,7 @@ export function logCommand(rawArgs: string[]): void {
 
   const pid = child.pid!;
   session.logPids.push({ pid, name, sourcePath: resolved });
-  fs.writeFileSync(sessionMetaPath(session.id), JSON.stringify(session, null, 2));
+  writeJsonPrivate(sessionMetaPath(session.id), session);
 
   console.log(JSON.stringify({ name, sourcePath: resolved, destPath, pid }, null, 2));
 }
@@ -309,6 +447,12 @@ async function stop(args: string[]): Promise<void> {
     await new Promise((r) => setTimeout(r, 200));
   }
 
+  // Tear down the held CDP bridge, if any — releases the browser-level
+  // connection (and any grants/target-enablement it was keeping alive).
+  if (session.bridgePid || session.bridgeSocket) {
+    stopBridge(session.bridgePid, session.bridgeSocket);
+  }
+
   // Collect screenshots
   const shotsDir = path.join(session.dir, 'shots');
   const screenshots = fs.existsSync(shotsDir)
@@ -332,7 +476,7 @@ async function stop(args: string[]): Promise<void> {
       const harData = readHarRecording(session.harId);
       if (harData) {
         const harPath = path.join(session.dir, 'har.json');
-        fs.writeFileSync(harPath, JSON.stringify(harData, null, 2));
+        writeJsonPrivate(harPath, harData);
         har = { id: session.harId, path: harPath, entryCount: harData.log.entries.length };
         // Clean up the HAR recording
         try { deleteHarRecording(session.harId); } catch { /* best effort */ }
@@ -355,9 +499,13 @@ async function stop(args: string[]): Promise<void> {
         })
     : [];
 
+  // Collect measure snapshots and motion recordings
+  const snaps = collectSnaps(session.dir);
+  const recs = collectRecs(session.dir);
+
   // 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 knownDirs = new Set(['shots', 'a11y', 'logs', 'measure', 'motion']);
+  const knownFiles = new Set(['.session.json', 'har.json', 'bundle.json', 'bridge.sock']);
   const other = fs.readdirSync(session.dir)
     .filter((f) => !knownDirs.has(f) && !knownFiles.has(f))
     .map((f) => ({ name: f, path: path.join(session.dir, f) }));
@@ -376,10 +524,12 @@ async function stop(args: string[]): Promise<void> {
     a11y,
     logs,
     other,
+    snaps,
+    recs,
   };
 
   const bundlePath = path.join(session.dir, 'bundle.json');
-  fs.writeFileSync(bundlePath, JSON.stringify(manifest, null, 2));
+  writeJsonPrivate(bundlePath, manifest);
 
   console.log(JSON.stringify({
     bundlePath,
@@ -390,6 +540,8 @@ async function stop(args: string[]): Promise<void> {
       a11ySnapshots: a11y.length,
       logFiles: logs.length,
       otherFiles: other.length,
+      snaps: snaps.length,
+      recs: recs.length,
     },
   }, null, 2));
 
@@ -414,11 +566,21 @@ function list(): void {
   console.log(JSON.stringify(sessions, null, 2));
 }
 
+// `session view --filter <name>` reads a manifest section by the same key
+// name for most sections (screenshots|har|a11y|logs|other), but `measure`
+// and `motion` are the query-facing filter names for the `snaps`/`recs`
+// manifest keys (matching the `measure`/`motion` command branches, not the
+// artifact-file naming), so they need an explicit alias.
+const VIEW_FILTER_ALIASES: Record<string, keyof BundleManifest> = {
+  measure: 'snaps',
+  motion: 'recs',
+};
+
 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]');
+    console.error('Usage: capture session view <session-id> [--filter screenshots|har|a11y|logs|other|measure|motion]');
     process.exit(1);
   }
 
@@ -434,7 +596,8 @@ function view(rawArgs: string[]): void {
 
   const filter = args.find((_, i) => args[i - 1] === '--filter');
   if (filter) {
-    const section = manifest[filter as keyof BundleManifest];
+    const key = VIEW_FILTER_ALIASES[filter] ?? (filter as keyof BundleManifest);
+    const section = manifest[key];
     console.log(JSON.stringify(section, null, 2));
   } else {
     console.log(JSON.stringify(manifest, null, 2));

package/src/session-context.ts

@@ -2,16 +2,33 @@
  * Session Context — persists active session state so CDP commands
  * can auto-fill --target, --har, and --out without manual threading.
  *
- * State is written to /tmp/capture-sessions/.active (JSON).
+ * 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.
  */
 
 import * as fs from 'fs';
 import * as path from 'path';
-import * as os from 'os';
+import { CAPTURE_ROOT } from './session/artifacts.js';
 
-const CAPTURE_ROOT = path.join(os.tmpdir(), 'capture-sessions');
-const ACTIVE_PATH = path.join(CAPTURE_ROOT, '.active');
+/**
+ * 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';
+}
+
+function getActivePath(): string {
+  return path.join(CAPTURE_ROOT, `.active-${activeScopeKey()}`);
+}
 
 export interface ActiveSessionState {
   sessionId: string;
@@ -19,12 +36,22 @@ export interface ActiveSessionState {
   harId: string | null;
   targetId: string | null;
   stepCount: number;
+  /** Unix socket of the session's held CDP bridge (`session start --hold`), if any. */
+  bridgeSocket?: string | 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}.
+   */
+  activeRecId?: string | null;
 }
 
 export function getActiveSession(): ActiveSessionState | null {
   try {
-    if (!fs.existsSync(ACTIVE_PATH)) return null;
-    const state = JSON.parse(fs.readFileSync(ACTIVE_PATH, 'utf-8')) as ActiveSessionState;
+    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();
@@ -38,12 +65,12 @@ export function getActiveSession(): ActiveSessionState | null {
 
 export function setActiveSession(state: ActiveSessionState): void {
   fs.mkdirSync(CAPTURE_ROOT, { recursive: true });
-  fs.writeFileSync(ACTIVE_PATH, JSON.stringify(state, null, 2));
+  fs.writeFileSync(getActivePath(), JSON.stringify(state, null, 2));
 }
 
 export function clearActiveSession(): void {
   try {
-    fs.unlinkSync(ACTIVE_PATH);
+    fs.unlinkSync(getActivePath());
   } catch {
     // Already gone
   }
@@ -57,6 +84,21 @@ export function updateActiveSession(patch: Partial<ActiveSessionState>): ActiveS
   return updated;
 }
 
+/** Records `recId` as the active session's live recording. */
+export function setActiveRecId(recId: string): ActiveSessionState | null {
+  return updateActiveSession({ activeRecId: recId });
+}
+
+/** Clears the active session's live-recording pointer (on `rec --stop` / stale reap). */
+export function clearActiveRecId(): ActiveSessionState | null {
+  return updateActiveSession({ activeRecId: null });
+}
+
+/** Reads the active session's live recording id, or `null` if none. */
+export function getActiveRecId(): string | null {
+  return getActiveSession()?.activeRecId ?? null;
+}
+
 function sanitizeLabel(label: string): string {
   return label
     .toLowerCase()