@crouton-kit/capture 1.3.14 → 1.3.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.3.14",
+  "version": "1.3.16",
   "description": "Browser automation and UI validation via CDP — session-based screenshots, HAR, a11y, click/type, and JS exec",
   "bin": {
     "capture": "./bin/capture"

package/src/cdp/args.ts

@@ -60,7 +60,7 @@ function validateKnownLeaf(command: string, positional: readonly string[]): void
   const branches: Record<string, readonly string[]> = {
     session: ['start', 'stop', 'list', 'view', 'har', 'log'],
     page: ['click', 'type', 'scroll', 'navigate', 'exec', 'shot', 'elements'],
-    tab: ['list', 'open', 'reset', 'network'],
+    tab: ['list', 'open', 'close', 'reset', 'network'],
     measure: ['snap', 'check', 'diff', 'census', 'explain', 'sweep', 'map'],
     motion: ['rec', 'mask', 'timeline', 'jank', 'response'],
     lib: ['list', 'search', 'show', 'read'],
@@ -179,9 +179,12 @@ export function validateCliInvocation(parsed: ParsedArgs): void {
           throw invalidInput('motion rec lifecycle flags cannot be combined with one-shot flags.');
         }
       } else {
-        requireCount(values, 1, 1, 'motion rec');
+        // The URL is optional: omitting it records the active session tab
+        // (enforced downstream once session state is known — this pure
+        // validator only bounds cardinality at 0..1 and checks a supplied URL).
+        requireCount(values, 0, 1, 'motion rec');
         if (!parsed.do) throw invalidInput('motion rec one-shot requires --do.');
-        assertParseableUrl(values[0], 'recording URL');
+        if (values[0] !== undefined) assertParseableUrl(values[0], 'recording URL');
         parseDoAction(parsed.do);
       }
       if (parsed.viewport !== undefined) {
@@ -213,7 +216,7 @@ export function parseCliSyntax(argv: string[]): ParsedArgs {
     const next = rest[i + 1];
     if (VALUE_FLAGS.has(arg)) valueFor(arg, next);
 
-    if (arg === '--port') { parsed.port = integer(valueFor(arg, next), '--port', 1, 65535); i++; }
+    if (arg === '--port') { parsed.port = integer(valueFor(arg, next), '--port', 1, 65535); parsed.portSource = 'flag'; i++; }
     else if (arg === '--out') { parsed.out = valueFor(arg, next); i++; }
     else if (arg === '--json') parsed.json = true;
     else if (arg === '--duration') { parsed.duration = durationMs(valueFor(arg, next)); i++; }
@@ -313,10 +316,11 @@ export function resolveCliContext(parsed: ParsedArgs): ParsedArgs {
     // A session target is inseparable from the endpoint that created it.
     // Prefer that endpoint over ambient CDP_PORT, but retain an explicit
     // --port override for deliberate multi-browser work.
-    if (parsed.port === undefined && session.port !== undefined && session.port !== null) parsed.port = session.port;
+    if (parsed.port === undefined && session.port !== undefined && session.port !== null) { parsed.port = session.port; parsed.portSource = 'session'; }
   }
   if (parsed.port === undefined && process.env.CDP_PORT !== undefined) {
     parsed.port = integer(process.env.CDP_PORT, 'CDP_PORT', 1, 65535);
+    parsed.portSource = 'env';
   }
   // Preserve historical stale-index cleanup once endpoint validation has
   // succeeded; only the malformed-env throw path deliberately leaves it alone.

package/src/cdp/commands/cdp.ts

@@ -56,7 +56,8 @@ Input:
   --params <json>              JSON-encoded params object for the method. Spec deviation: params stay inline JSON (no file indirection) — raw CDP params are small protocol-defined objects.
   --wait-event <Domain.event>  wait for (and return) the next occurrence of a protocol event; combinable with a method (the method is sent first) or usable alone.
   --browser                    route through the held connection (session start --hold) instead of a one-shot page websocket. Connection-scoped state (permission grants, domain enables) reverts the instant its connection closes — it survives across commands only inside a held session.
-  --target <id>                with --browser: attach a flattened CDP session on the held connection to this target (for target-scoped domains); without --browser: the page target to run against. 8-char id prefix accepted.
+  --port <port>                CDP endpoint. An explicit flag selects that endpoint even when an active session holds another browser connection.
+  --target <id>                with --browser: attach a flattened CDP session on the held connection to this target (for target-scoped domains), including an already-open tab adopted by \`session start --hold\` without --url; without --browser: the page target to run against. 8-char id prefix accepted.
   --timeout <ms>               event-wait timeout (default ${DEFAULT_TIMEOUT_MS}ms).
 
 Output:
@@ -220,8 +221,10 @@ export async function runBrowserScope(
 ): Promise<void> {
   const flagTarget = parsed.targetSource === 'flag' ? parsed.target : undefined;
   const session = getActiveSession();
-  if (session?.bridgeSocket && fs.existsSync(session.bridgeSocket)) {
-    const resp = await deps.sendBridgeRequest(session.bridgeSocket, {
+  const bridgeSocket = session?.bridgeSocket;
+  const heldBridgeActive = Boolean(bridgeSocket && fs.existsSync(bridgeSocket));
+  if (parsed.portSource !== 'flag' && bridgeSocket && heldBridgeActive) {
+    const resp = await deps.sendBridgeRequest(bridgeSocket, {
       method,
       params,
       targetId: flagTarget,
@@ -247,9 +250,14 @@ export async function runBrowserScope(
   }
 
   // In-flight diagnostic (stderr): the one-shot connection semantics fact.
+  const connectionReason = parsed.portSource === 'flag'
+    ? heldBridgeActive
+      ? `Using explicitly selected CDP port ${parsed.port} instead of the active session bridge`
+      : `Using explicitly selected CDP port ${parsed.port}`
+    : 'No held session bridge active';
   console.error(
-    'No held session bridge active \u2014 this one-shot connection closes when the command exits, ' +
-      'so any browser-level grant or target enablement made here reverts immediately after.',
+    `${connectionReason} — this one-shot connection closes when the command exits, ` +
+    'so any browser-level grant or target enablement made here reverts immediately after.',
   );
 
   const port = parsed.port ?? (await deps.detectCdpPort());

package/src/cdp/commands/tab/close.ts

@@ -0,0 +1,98 @@
+import { captureError, invalidInput } from '../../../errors.js';
+import { detectCdpPort } from '../../detect.js';
+import { closeTarget, findTabById } from '../../targets.js';
+import { getActiveSession } from '../../../session-context.js';
+import { withSessionScopeLifecycle } from '../../../session/coordinator.js';
+import { type CDPTarget, type ParsedArgs } from '../../types.js';
+import {
+  data,
+  emitResult,
+  fact,
+  line,
+  text,
+  type RenderableResult,
+} from '../../../output/render.js';
+
+const USAGE = `capture tab close — close one explicitly identified background browser tab.
+
+input:
+  <target>        required — full tab target id or an unambiguous 8-character prefix
+  --port <port>   CDP endpoint (default: the auto-discovered preferred endpoint)
+
+output: <tab-closed port=… target=…> — the closed tab's full target id and last observed URL.
+effects: closes exactly one page tab. Refuses unless any active session's background-tab ownership is known, and never closes that session's tab; reset or stop the session first.`;
+
+export function buildTabClosedResult(tab: CDPTarget, port: number): RenderableResult {
+  return {
+    tag: 'tab-closed',
+    attrs: { port, target: tab.id },
+    summary: line(text`tab `, data(tab.id.slice(0, 8)), text` closed: `, data(tab.url, 300)),
+  };
+}
+
+export async function cmdTabClose(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  const target = parsed.positional[0];
+  if (!target) {
+    throw invalidInput('received: no target; expected: capture tab close <target> [--port <port>].', 'missing_argument');
+  }
+  if (target.length < 8) {
+    throw invalidInput(`received: target ${target}; expected: a full target id or an unambiguous prefix of at least 8 characters.`, 'target_prefix_too_short');
+  }
+
+  let port: number;
+  try {
+    port = parsed.port ?? await detectCdpPort();
+  } catch {
+    throw captureError(
+      'world',
+      'no_cdp_endpoint',
+      'received: no --port, and no CDP endpoint was discovered on localhost; expected: a running CDP-enabled browser (or an explicit --port <port>). capture tab list probes every localhost CDP endpoint.',
+    );
+  }
+
+  const tab = await withSessionScopeLifecycle(async () => {
+    let resolved: CDPTarget | null;
+    try {
+      resolved = await findTabById(port, target);
+    } catch (error) {
+      throw captureError('precondition', 'target_unavailable', `received: target ${target} on port ${port}; expected: one unambiguous page-tab target id. ${error instanceof Error ? error.message : String(error)}`, error);
+    }
+    if (!resolved || resolved.type !== 'page') {
+      throw captureError(
+        'precondition',
+        'target_unavailable',
+        `received: target ${target} on port ${port}; expected: one existing page-tab target id (8-character prefix accepted). capture tab list shows available tabs.`,
+      );
+    }
+
+    const active = getActiveSession();
+    if (active && !active.targetId) {
+      throw captureError(
+        'precondition',
+        'active_session_target_unknown',
+        `session ${active.sessionId} has not established its target yet, so capture tab close cannot prove ${resolved.id} is a background tab. Target the session with a page command first, or stop the session with capture session stop ${active.sessionId}.`,
+      );
+    }
+    if (active?.targetId === resolved.id) {
+      throw captureError(
+        'precondition',
+        'active_session_target',
+        `target ${resolved.id} is the active session ${active.sessionId}'s tab; capture tab close never leaves an active session pointing at a closed target. Use capture tab reset <url> to replace it or capture session stop ${active.sessionId} first.`,
+      );
+    }
+
+    try {
+      await closeTarget(port, resolved.id);
+    } catch (error) {
+      throw captureError('world', 'close_failed', `closing target ${resolved.id} on port ${port} failed: ${error instanceof Error ? error.message : String(error)}`, error);
+    }
+    return resolved;
+  });
+
+  emitResult(buildTabClosedResult(tab, port), { json: parsed.json });
+}

package/src/cdp/commands/tab/index.ts

@@ -12,14 +12,15 @@ import { invalidInput } from '../../../errors.js';
 import { type ParsedArgs } from '../../types.js';
 import { cmdTabList } from './list.js';
 import { cmdTabOpen } from './open.js';
+import { cmdTabClose } from './close.js';
 import { cmdTabReset } from './reset.js';
 import { cmdTabNetwork } from './network.js';
 
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="tab">
-tab and connection plumbing — endpoint/tab discovery, open/reset tabs, connection-level network emulation
-use when finding a CDP endpoint or tab, opening/replacing a tab, or toggling connectivity; \`tab list\` is the probe for a running browser
-  list · open · reset · network — \`capture tab -h\`
+tab and connection plumbing — endpoint/tab discovery, lifecycle, connection-level network emulation
+use when finding a CDP endpoint or tab, opening/closing/replacing a tab, or toggling connectivity; \`tab list\` is the probe for a running browser
+  list · open · close · reset · network — \`capture tab -h\`
 </command>`;
 
 export const TAB_USAGE = `capture tab — tab and connection plumbing: discovery, lifecycle, network emulation.
@@ -32,6 +33,7 @@ the session's {target, port} pair together.
 
 <subcommand name="list" args="[--port <port>]" whenToUse="discover CDP endpoints and the tabs open on them"/>
 <subcommand name="open" args="<url> [--new] [--port <port>]" whenToUse="open a URL and get its tab id"/>
+<subcommand name="close" args="<target> [--port <port>]" whenToUse="close one explicitly identified background tab"/>
 <subcommand name="reset" args="<url> [--port <port>]" whenToUse="abandon a stuck tab and open a fresh one (refuses while a recording is active; reaps dead recorder handles; updates the active session's {target, port} together)"/>
 <subcommand name="network" args="<offline|online>" whenToUse="toggle connection-level network emulation for a tab"/>
 
@@ -46,6 +48,8 @@ export async function tabMain(parsed: ParsedArgs, args: string[]): Promise<void>
       return cmdTabList(rest, args);
     case 'open':
       return cmdTabOpen(rest, args);
+    case 'close':
+      return cmdTabClose(rest, args);
     case 'reset':
       return cmdTabReset(rest, args);
     case 'network':

package/src/cdp/commands/tab/reset.ts

@@ -22,6 +22,7 @@ import { getActiveSession, updateSessionState } from '../../../session-context.j
 import {
   admitSessionOperation,
   withSessionLifecycle,
+  withSessionScopeLifecycle,
   scanRecorderHandles,
   clearDanglingRecorderPointer,
   type LifecycleSeams,
@@ -123,38 +124,40 @@ export async function cmdTabReset(parsed: ParsedArgs, _args: string[]): Promise<
   const url = parsed.positional[0];
   if (!url) throw invalidInput('received: no URL; expected: capture tab reset <url> [--port <port>].', 'missing_argument');
 
-  const session = getActiveSession();
-  if (!session) {
-    let port: number;
-    try {
-      port = parsed.port ?? (await deps.detectCdpPort());
-    } catch {
-      throw captureError('world', 'no_cdp_endpoint', 'received: no --port, and no CDP endpoint was discovered on localhost; expected: a running CDP-enabled browser (or an explicit --port <port>).');
-    }
-    const tab = await openTabOrThrow(port, url);
-    await boundedLoadWait(tab);
-    emitResult(buildTabResetResult(tab, port, false), { json: parsed.json });
-    return;
-  }
-
-  const op = await admitSessionOperation(session.dir);
-  try {
-    const result = await withSessionLifecycle(session.dir, async () => {
-      const fresh = getActiveSession();
-      if (!fresh || fresh.dir !== session.dir) throw captureError('precondition', 'session_unavailable', 'The active capture session is no longer available.');
-      const scan = scanRecorderHandles(session.dir, deps.lifecycle);
-      if (scan.some(h => h.classification === 'unknown')) throw captureError('world', 'recorder_liveness_unknown', 'Cannot determine recorder liveness; refusing to reset.');
-      if (scan.some(h => h.classification === 'malformed')) throw captureError('precondition', 'recorder_unavailable', 'A malformed recorder handle exists on this session; resolve it before resetting.');
-      if (scan.some(h => h.classification === 'live')) throw captureError('precondition', 'recorder_active', 'A recording is active on this session; stop it first: `capture motion rec --stop`. Reset never rebinds a live recorder.');
-      await clearDanglingRecorderPointer(session.dir, scan);
-      const port = fresh.port ?? parsed.port ?? (await deps.detectCdpPort());
+  return withSessionScopeLifecycle(async () => {
+    const session = getActiveSession();
+    if (!session) {
+      let port: number;
+      try {
+        port = parsed.port ?? (await deps.detectCdpPort());
+      } catch {
+        throw captureError('world', 'no_cdp_endpoint', 'received: no --port, and no CDP endpoint was discovered on localhost; expected: a running CDP-enabled browser (or an explicit --port <port>).');
+      }
       const tab = await openTabOrThrow(port, url);
       await boundedLoadWait(tab);
-      await updateSessionState(session.dir, { targetId: tab.id, port });
-      return buildTabResetResult(tab, port, true);
-    }, deps.lifecycle);
-    emitResult(result, { json: parsed.json });
-  } finally {
-    await op.release();
-  }
+      emitResult(buildTabResetResult(tab, port, false), { json: parsed.json });
+      return;
+    }
+
+    const op = await admitSessionOperation(session.dir);
+    try {
+      const result = await withSessionLifecycle(session.dir, async () => {
+        const fresh = getActiveSession();
+        if (!fresh || fresh.dir !== session.dir) throw captureError('precondition', 'session_unavailable', 'The active capture session is no longer available.');
+        const scan = scanRecorderHandles(session.dir, deps.lifecycle);
+        if (scan.some(h => h.classification === 'unknown')) throw captureError('world', 'recorder_liveness_unknown', 'Cannot determine recorder liveness; refusing to reset.');
+        if (scan.some(h => h.classification === 'malformed')) throw captureError('precondition', 'recorder_unavailable', 'A malformed recorder handle exists on this session; resolve it before resetting.');
+        if (scan.some(h => h.classification === 'live')) throw captureError('precondition', 'recorder_active', 'A recording is active on this session; stop it first: `capture motion rec --stop`. Reset never rebinds a live recorder.');
+        await clearDanglingRecorderPointer(session.dir, scan);
+        const port = fresh.port ?? parsed.port ?? (await deps.detectCdpPort());
+        const tab = await openTabOrThrow(port, url);
+        await boundedLoadWait(tab);
+        await updateSessionState(session.dir, { targetId: tab.id, port });
+        return buildTabResetResult(tab, port, true);
+      }, deps.lifecycle);
+      emitResult(result, { json: parsed.json });
+    } finally {
+      await op.release();
+    }
+  });
 }

package/src/cdp/connection.ts

@@ -10,6 +10,7 @@ import {
   appendToHarRecording as appendToHar,
 } from '../har-manager.js';
 import { getActiveSession, updateActiveSession, type ActiveSessionState } from '../session-context.js';
+import { withSessionScopeLifecycle } from '../session/coordinator.js';
 import { RecorderHeldClient, isRecorderHeldClient } from './recorder-client.js';
 import { recDirFor, readRecorderJson } from './motion/recorder.js';
 import { captureError, invalidInput } from '../errors.js';
@@ -35,6 +36,7 @@ function getPortFromWebSocketDebuggerUrl(url?: string): number | null {
 export interface ConnectionSeams {
   getActiveSession: () => ActiveSessionState | null;
   updateActiveSession: (patch: Partial<ActiveSessionState>) => Promise<ActiveSessionState | null>;
+  withSessionScopeLifecycle: <T>(action: () => Promise<T>) => Promise<T>;
   resolveTab: (parsed: ParsedArgs) => Promise<{ port: number; tab: CDPTarget } | null>;
   createClient: (wsUrl: string) => CDPClient;
   appendHar: typeof appendToHar;
@@ -58,6 +60,7 @@ function defaultResolveTab(parsed: ParsedArgs): Promise<{ port: number; tab: CDP
 let seams: ConnectionSeams = {
   getActiveSession: () => getActiveSession(),
   updateActiveSession,
+  withSessionScopeLifecycle,
   resolveTab: defaultResolveTab,
   createClient: (wsUrl) => new CDPClient(wsUrl),
   appendHar: appendToHar,
@@ -232,10 +235,16 @@ export async function connectForCommand(
   // endpoint precedence already resolved before this leaf ran.
   const port = resolved?.port ?? getPortFromWebSocketDebuggerUrl(tab.webSocketDebuggerUrl);
 
-  // Lazy target establishment: publish `{targetId, port}` as one atomic pair
-  // through U03's metadata helper so a subsequent command finds both together.
+  // Lazy target establishment shares the scope lifecycle boundary with tab
+  // close and session start/stop. Re-read under that boundary so a stale
+  // pre-resolution snapshot cannot repoint a replacement session.
   if (activeSession && !activeSession.targetId) {
-    await seams.updateActiveSession({ targetId: tab.id, port: port ?? null });
+    await seams.withSessionScopeLifecycle(async () => {
+      const current = seams.getActiveSession();
+      if (current?.sessionId === activeSession.sessionId && !current.targetId) {
+        await seams.updateActiveSession({ targetId: tab.id, port: port ?? null });
+      }
+    });
   }
 
   console.error(

package/src/cdp/types.ts

@@ -10,6 +10,11 @@ export interface ParsedArgs {
   command: string;
   positional: string[];
   port?: number;
+  /** Where `port` was assigned from: an actual `--port` flag, active-session
+   * fallback, or the ambient `CDP_PORT` env var. Browser-scope CDP uses a
+   * held session bridge unless this is `'flag'`, which explicitly selects a
+   * different browser endpoint. */
+  portSource?: 'flag' | 'session' | 'env';
   out?: string;
   json?: boolean;
   duration?: number;

package/src/output/render.ts

@@ -54,6 +54,7 @@ export const RESULT_TAGS = [
   'screenshot',
   'tabs',
   'tab-opened',
+  'tab-closed',
   'tab-reset',
   'network',
   'cdp-result',

package/src/session/commands.ts

@@ -38,7 +38,6 @@ import {
 import {
   CAPTURE_ROOT,
   MAX_LOG_LABEL_BYTES,
-  acquirePrivateLock,
   ensurePrivateDir,
   rejectLogLabel,
   writeJsonPrivate,
@@ -47,7 +46,7 @@ import {
   type SnapMeta,
   type RecMeta,
 } from './artifacts.js';
-import { beginSessionStop, admitSessionOperation, withSessionLifecycle } from './coordinator.js';
+import { beginSessionStop, admitSessionOperation, withSessionLifecycle, withSessionScopeLifecycle } from './coordinator.js';
 import { parseStatusFilter, type StatusPredicate } from './har-filter.js';
 
 type Session = ActiveSessionState;
@@ -151,22 +150,6 @@ function sessionDir(id: string): string {
   return path.join(CAPTURE_ROOT, id);
 }
 
-function lifecycleScopeLockPath(): string {
-  return path.join(CAPTURE_ROOT, `.session-lifecycle-${process.env.CRTR_NODE_ID ?? 'default'}`);
-}
-
-async function withLifecycleCoordinator<T>(action: () => Promise<T>): Promise<T> {
-  const handle = await acquirePrivateLock(lifecycleScopeLockPath(), {
-    acquireTimeoutMs: 120_000,
-    leaseMs: 1_000,
-  });
-  try {
-    return await action();
-  } finally {
-    handle.release();
-  }
-}
-
 function isSessionStopped(session: Session): boolean {
   return Boolean(session.stoppedAt) || fs.existsSync(path.join(session.dir, 'bundle.json'));
 }
@@ -336,6 +319,8 @@ input:
   --hold         Hold one CDP browser connection open for the session's
                  lifetime, so browser-level state (permission grants,
                  ServiceWorker enablement) survives across separate commands.
+                 With no --url, later --target <existing-id> commands adopt
+                 an already-open tab without creating a new one.
   --port <n>     CDP port to attach to; default is auto-detected across localhost.
 
 Output:
@@ -567,7 +552,7 @@ async function start(parsed: ParsedArgs): Promise<void> {
 
   if (rejectSurplusPositionals(parsed, 'start', 0, 'capture session start [--url <url>] [--hold]')) return;
 
-  return withLifecycleCoordinator(async () => {
+  return withSessionScopeLifecycle(async () => {
     const active = getActiveSession();
     if (active && !isSessionStopped(active)) {
       emitResult({
@@ -1075,7 +1060,7 @@ async function stop(parsed: ParsedArgs): Promise<void> {
     return;
   }
 
-  return withLifecycleCoordinator(async () => {
+  return withSessionScopeLifecycle(async () => {
     let session: Session;
     try {
       session = readSession(id);

package/src/session/coordinator.ts

@@ -3,6 +3,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { captureError } from '../errors.js';
 import {
+  CAPTURE_ROOT,
   acquirePrivateLock,
   assertUnderCaptureRoot,
   readPrivateFile,
@@ -34,6 +35,23 @@ export interface SessionStopAdmission {
   finish(success: boolean): Promise<void>;
 }
 
+function scopeLifecycleLockPath(): string {
+  return path.join(CAPTURE_ROOT, `.session-lifecycle-${process.env.CRTR_NODE_ID ?? 'default'}`);
+}
+
+/** Serializes active-session publication, teardown, and target ownership changes for one capture scope. */
+export async function withSessionScopeLifecycle<T>(action: () => Promise<T>): Promise<T> {
+  const lock = await acquirePrivateLock(scopeLifecycleLockPath(), {
+    acquireTimeoutMs: 120_000,
+    leaseMs: 1_000,
+  });
+  try {
+    return await action();
+  } finally {
+    lock.release();
+  }
+}
+
 function statePath(sessionDir: string): string {
   return path.join(assertUnderCaptureRoot(sessionDir), '.operations.json');
 }