@crouton-kit/capture 1.3.8 → 1.3.9

package/src/cdp/commands/page/type.ts

@@ -0,0 +1,104 @@
+/**
+ * `page type <text> [--into <target>]` — type agent-supplied text into the
+ * focused element, or into exactly one live-resolved field (design D3).
+ *
+ * The block echoes the agent-supplied text (I-7); the screenshot label and
+ * any recorder landmark identify the FIELD (the action's target), matching
+ * `connection.ts`'s `deriveActionLabel` — the typed text is the action's
+ * payload and is echoed in the command's own result block.
+ */
+import { type ParsedArgs } from '../../types.js';
+import {
+  resolveLiveTarget,
+  typeText,
+  focusAndType,
+  type LiveClient,
+  type ClickDispatch,
+} from '../../../interact.js';
+import { emitResult, fact, lineList, type FactLine } from '../../../output/render.js';
+import {
+  pageInputDeps,
+  effectiveSettle,
+  emitInvalidInput,
+  emitResolutionError,
+} from './click.js';
+
+const USAGE = `capture page type <text> [--into <target>] — type text into the focused element or one resolved field
+
+input:
+  <text>            the text to insert (agent-supplied; echoed back in the result block)
+  --into <target>   focus this field first — resolved against the LIVE page: bare CSS selector, ax:<name> (case-insensitive substring), axid:<id>, backend:<id>; text: is not accepted; exactly one match required
+  --settle <ms>     network-settle window applied after typing (default: 500; 1500 with an active session; 0 disables)
+  --no-screenshot   skip the auto-screenshot
+output:
+  <typed> — the typed text, the resolved field identity (backend-node-id, role, name) and focus-click coordinates when --into was given, the measured settle (requested/waited), screenshot artifact path; --json mirrors the same fields
+effects:
+  dispatches a real focus click (when --into) followed by real text insertion; writes one screenshot into the active session's shots/ sequence unless --no-screenshot`;
+
+export async function cmdPageType(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+  const textArg = parsed.positional[0];
+  if (textArg === undefined || parsed.positional.length !== 1) {
+    return emitInvalidInput(
+      parsed,
+      'page type',
+      fact`received: ${parsed.positional.length} positional arguments; expected exactly one — the text to type (use --into <target> to focus a field first).`,
+    );
+  }
+
+  const deps = pageInputDeps();
+  const settle = effectiveSettle(parsed, { standalone: 500, session: 1500 });
+  // connection.ts derives the recorder landmark label from parsed.command —
+  // restoring the verb here is what engages deriveActionLabel's type-guard,
+  // so a routed type's landmark is `type:<field>` and NEVER the typed text
+  // (positional[0], which the generic label branch would otherwise use).
+  const { result: outcome, settle: settleFacts } = await deps.withPageAction(
+    { ...parsed, command: 'type' },
+    { settleMs: settle },
+    async (client) => {
+      const live = client as unknown as LiveClient;
+      let dispatch: ClickDispatch | null = null;
+      if (parsed.into) {
+        const resolved = await resolveLiveTarget(live, parsed.into);
+        if (!resolved.ok) return { failure: resolved } as const;
+        dispatch = await focusAndType(live, resolved, textArg);
+      } else {
+        await typeText(live, textArg);
+      }
+      // Screenshot label identifies the field, never the typed content.
+      const screenshot = await deps.autoScreenshot(client, 'type', parsed.into ?? 'focused element', parsed.noScreenshot);
+      return { dispatch, screenshot } as const;
+    },
+  );
+
+  if ('failure' in outcome) {
+    return emitResolutionError(parsed, 'page type', outcome.failure);
+  }
+
+  const { dispatch, screenshot } = outcome;
+  const rows: FactLine[] = [
+    dispatch
+      ? fact`typed "${textArg}" into ${dispatch.role ?? 'unknown'} "${dispatch.name ?? ''}" (backend:${dispatch.backendNodeId}), focus click at x=${dispatch.x} y=${dispatch.y}`
+      : fact`typed "${textArg}" into the focused element`,
+    fact`settle: requested ${settleFacts.requestedMs}ms, waited ${settleFacts.waitedMs}ms`,
+  ];
+  if (screenshot) rows.push(fact`screenshot: ${screenshot}`);
+
+  emitResult(
+    {
+      tag: 'typed',
+      attrs: dispatch
+        ? {
+            'backend-node-id': dispatch.backendNodeId,
+            role: dispatch.role ?? undefined,
+            name: dispatch.name ?? undefined,
+          }
+        : {},
+      summary: lineList(rows),
+    },
+    { json: parsed.json },
+  );
+}

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

@@ -0,0 +1,59 @@
+/**
+ * `capture tab` branch router — tab and connection plumbing: endpoint/tab
+ * discovery, tab lifecycle, connection-level network emulation.
+ *
+ * Shifts the consumed leaf token out of `parsed.positional` before handing
+ * off, so every leaf command still finds its own primary target (a URL, an
+ * offline/online token, ...) at `positional[0]` exactly as every other
+ * capture command does — leaf commands never need to know they're nested
+ * under a branch.
+ */
+import { invalidInput } from '../../../errors.js';
+import { type ParsedArgs } from '../../types.js';
+import { cmdTabList } from './list.js';
+import { cmdTabOpen } from './open.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\`
+</command>`;
+
+export const TAB_USAGE = `capture tab — tab and connection plumbing: discovery, lifecycle, network emulation.
+
+\`tab list\` with no --port performs full endpoint discovery and is the probe
+for whether a CDP-enabled browser is running at all. \`tab reset\` replaces a
+stuck tab with a fresh one; under an active session it refuses while a
+recording is active (stop it first), reaps dead recorder handles, and updates
+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="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"/>
+
+capture tab <leaf> -h    Per-leaf usage`;
+
+export async function tabMain(parsed: ParsedArgs, args: string[]): Promise<void> {
+  const leaf = parsed.positional[0];
+  const rest: ParsedArgs = { ...parsed, positional: parsed.positional.slice(1) };
+
+  switch (leaf) {
+    case 'list':
+      return cmdTabList(rest, args);
+    case 'open':
+      return cmdTabOpen(rest, args);
+    case 'reset':
+      return cmdTabReset(rest, args);
+    case 'network':
+      return cmdTabNetwork(rest, args);
+    case undefined:
+      console.log(TAB_USAGE);
+      return;
+    default:
+      throw invalidInput(`Unknown tab leaf: ${leaf}.`, 'unknown_command');
+  }
+}

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

@@ -0,0 +1,167 @@
+/**
+ * `capture tab list [--port <port>]` — CDP endpoint discovery and page-tab
+ * listing merged into one selection-shaped `<tabs>` block (D5: the old
+ * `detect` root command's discovery is the no-port default of listing tabs).
+ *
+ * A per-endpoint tab-fetch failure is reported as an `endpoints-unreachable`
+ * fact, never silently dropped (I-5). Every endpoint/page-derived string
+ * (titles, URLs, app names, target ids) flows through `data()`/`fact` (I-9).
+ */
+import {
+  detectCdpPortsAsync,
+  getDefaultBrowserId,
+  pickPreferredEndpoint,
+} from '../../detect.js';
+import { listTargets } from '../../targets.js';
+import { type ParsedArgs } from '../../types.js';
+import {
+  data,
+  emitResult,
+  fact,
+  line,
+  lineList,
+  text,
+  type FactLine,
+  type RenderableResult,
+} from '../../../output/render.js';
+
+const USAGE = `capture tab list — discover CDP endpoints and list the page tabs on each.
+
+input:
+  --port <port>   probe one endpoint only, instead of discovering every localhost CDP endpoint
+
+output: <tabs endpoints=… tabs=…> — one section per reachable endpoint (port, app, page-tab count, preferred marker) listing each page tab's target id (first 8 chars, enough for --target), title, and url; an endpoint that failed the tab fetch is an endpoints-unreachable fact, never a silent omission.
+effects: read-only — probes local CDP endpoints over HTTP/WebSocket; no page-observable writes.`;
+
+export interface TabRow {
+  id: string;
+  title: string;
+  url: string;
+}
+
+export interface EndpointTabs {
+  port: number;
+  /** Endpoint-derived app name (from its /json/version User-Agent) — untrusted. */
+  app?: string;
+  /** Marked on the endpoint auto-discovery would pick for port-less commands. */
+  preferred: boolean;
+  pages: TabRow[];
+}
+
+export interface UnreachableEndpoint {
+  port: number;
+  app?: string;
+  reason: string;
+}
+
+/** Pure `<tabs>` result builder — exported for tests. */
+export function buildTabsResult(
+  endpoints: readonly EndpointTabs[],
+  unreachable: readonly UnreachableEndpoint[],
+): RenderableResult {
+  const totalTabs = endpoints.reduce((n, ep) => n + ep.pages.length, 0);
+
+  let summary: FactLine =
+    endpoints.length === 0 && unreachable.length === 0
+      ? text`0 CDP endpoints found listening on localhost.`
+      : fact`${totalTabs} page tab(s) on ${endpoints.length} reachable CDP endpoint(s).`;
+  if (unreachable.length > 0) {
+    summary = line(summary, fact` ${unreachable.length} endpoint(s) unreachable.`);
+  }
+
+  const sections: FactLine[] = endpoints.map((ep) => {
+    const header = line(
+      text`port `,
+      data(ep.port),
+      ...(ep.app !== undefined ? [line(text` — `, data(ep.app, 80))] : []),
+      fact` — ${ep.pages.length} page tab(s)`,
+      ...(ep.preferred ? [text` [preferred]`] : []),
+    );
+    const rows = ep.pages.map((t) =>
+      line(text`  `, data(t.id.slice(0, 8)), text`  "`, data(t.title, 120), text`"  `, data(t.url, 300)),
+    );
+    return lineList([header, ...rows]);
+  });
+
+  if (unreachable.length > 0) {
+    sections.push(
+      lineList(
+        unreachable.map((u) =>
+          line(
+            text`endpoints-unreachable: port `,
+            data(u.port),
+            ...(u.app !== undefined ? [line(text` (`, data(u.app, 80), text`)`)] : []),
+            text` — `,
+            data(u.reason, 300),
+          ),
+        ),
+      ),
+    );
+  }
+
+  return {
+    tag: 'tabs',
+    attrs: {
+      endpoints: endpoints.length,
+      tabs: totalTabs,
+      ...(unreachable.length > 0 ? { unreachable: unreachable.length } : {}),
+    },
+    summary,
+    sections,
+  };
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+export async function cmdTabList(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  const reachable: EndpointTabs[] = [];
+  const unreachable: UnreachableEndpoint[] = [];
+
+  if (parsed.port) {
+    try {
+      const targets = await listTargets(parsed.port);
+      reachable.push({
+        port: parsed.port,
+        preferred: false,
+        pages: targets
+          .filter((t) => t.type === 'page')
+          .map((t) => ({ id: t.id, title: t.title, url: t.url })),
+      });
+    } catch (err) {
+      unreachable.push({ port: parsed.port, reason: errorMessage(err) });
+    }
+  } else {
+    const endpoints = await detectCdpPortsAsync();
+    const preferredPort =
+      endpoints.length > 0 ? pickPreferredEndpoint(endpoints, getDefaultBrowserId()).port : null;
+    await Promise.all(
+      endpoints.map(async (ep) => {
+        try {
+          const targets = await listTargets(ep.port);
+          reachable.push({
+            port: ep.port,
+            app: ep.app,
+            preferred: ep.port === preferredPort,
+            pages: targets
+              .filter((t) => t.type === 'page')
+              .map((t) => ({ id: t.id, title: t.title, url: t.url })),
+          });
+        } catch (err) {
+          unreachable.push({ port: ep.port, app: ep.app, reason: errorMessage(err) });
+        }
+      }),
+    );
+    // Parallel probes land in arrival order — sort for deterministic output.
+    reachable.sort((a, b) => a.port - b.port);
+    unreachable.sort((a, b) => a.port - b.port);
+  }
+
+  emitResult(buildTabsResult(reachable, unreachable), { json: parsed.json });
+}

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

@@ -0,0 +1,162 @@
+/**
+ * `capture tab network <offline|online>` — connection-level network
+ * emulation for the active session's held tab via
+ * `Network.emulateNetworkConditions`.
+ *
+ * Emulation is only meaningful while the CDP connection that applied it stays
+ * open, so this leaf refuses to run except against an active session that owns
+ * a live `session start --hold` bridge. It sends `Network.enable` +
+ * `Network.emulateNetworkConditions` through that exact bridge, scoped to the
+ * session's own target, and reports the truthful owner (`session-hold`) and the
+ * lifetime of the emulation — until a matching `online` or the session stops.
+ */
+import * as fs from 'node:fs';
+import { captureError } from '../../../errors.js';
+import { getActiveSession, setActiveNetworkOffline } from '../../../session-context.js';
+import { admitSessionOperation } from '../../../session/coordinator.js';
+import { sendBridgeRequest } from '../../bridge/client.js';
+import { type ParsedArgs } from '../../types.js';
+import {
+  emitResult,
+  fact,
+  text,
+  type RenderableResult,
+} from '../../../output/render.js';
+
+const USAGE = `capture tab network — toggle connection-level network emulation for the active session's held tab.
+
+input:
+  <offline|online>   required — offline blocks HTTP requests and drops WebSocket connections; online restores connectivity
+  --target <id>      optional — must equal the active session's target; --url is not accepted
+  --port <port>      optional — must equal the active session's port
+
+output: <network mode=… owner="session-hold"> — the emulation applied to the session's held tab, and how long it lasts.
+effects: page-observable — Network.emulateNetworkConditions is sent through the session's held CDP bridge and stays in effect on that tab until a matching \`capture tab network online\` or the session stops.
+requires: an active session with a live \`session start --hold\` bridge and a target; emulation lives only as long as that held connection.`;
+
+/**
+ * Pure `<network>` result builder — exported for tests. Reports the factual
+ * `session-hold` owner and the lifetime of the emulation; it never promises
+ * persistence beyond that owner.
+ */
+export function buildNetworkResult(mode: 'offline' | 'online', target?: string): RenderableResult {
+  const offline = mode === 'offline';
+  const attrs: Record<string, string> = { mode, owner: 'session-hold' };
+  if (target) attrs.target = target;
+  return {
+    tag: 'network',
+    attrs,
+    summary: offline
+      ? fact`network emulation applied to the session-hold tab ${target ?? ''}: offline — HTTP requests blocked, WebSocket connections drop. It is held on the session's bridge and lasts until \`capture tab network online\` or the session stops.`
+      : fact`network emulation on the session-hold tab ${target ?? ''}: online — connectivity restored; the held offline emulation is cleared.`,
+    ...(offline ? { followUp: text`capture tab network online` } : {}),
+  };
+}
+
+export async function cmdTabNetwork(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  const mode = parsed.positional[0];
+  if (mode !== 'offline' && mode !== 'online') {
+    throw captureError(
+      'invocation',
+      'invalid_argument',
+      `received: \`${mode ?? ''}\`; expected: capture tab network <offline|online>.`,
+    );
+  }
+
+  // `tab network` emulates on the active session's held tab; a caller-supplied
+  // URL target has no place here. Reject before touching session state.
+  if (parsed.url !== undefined) {
+    throw captureError(
+      'invocation',
+      'unsupported_flag',
+      'capture tab network does not accept --url; it emulates on the active session\'s held tab.',
+    );
+  }
+
+  const session = getActiveSession();
+  if (!session) {
+    throw captureError(
+      'precondition',
+      'no_active_session',
+      'capture tab network requires an active session; start one with `capture session start --hold`.',
+    );
+  }
+  if (!session.targetId) {
+    throw captureError(
+      'precondition',
+      'session_target_missing',
+      `session ${session.sessionId} has no target to emulate on; open one with \`capture session start --hold --url <url>\` or \`capture tab reset <url>\`.`,
+    );
+  }
+  if (!session.bridgeSocket || !fs.existsSync(session.bridgeSocket)) {
+    throw captureError(
+      'precondition',
+      'no_held_bridge',
+      `session ${session.sessionId} has no live held CDP bridge; network emulation only outlives a command when the session was started with \`session start --hold\`.`,
+    );
+  }
+  // The only target that can be emulated is the session's own. An explicit
+  // `--target` unequal to it is a mismatch; an equal one is accepted.
+  if (parsed.target !== undefined && parsed.target !== session.targetId) {
+    throw captureError(
+      'precondition',
+      'target_mismatch',
+      `received --target ${parsed.target}; capture tab network only emulates the active session's target ${session.targetId}.`,
+    );
+  }
+  // Likewise, an explicitly flagged port must be the session's own port. An
+  // equal port is accepted; a mismatch rejects before any bridge send (A4).
+  if (parsed.port !== undefined && parsed.port !== session.port) {
+    throw captureError(
+      'precondition',
+      'port_mismatch',
+      `received --port ${parsed.port}; capture tab network only emulates on the active session's port ${session.port ?? 'unknown'}.`,
+    );
+  }
+
+  const offline = mode === 'offline';
+  const socket = session.bridgeSocket;
+  const targetId = session.targetId;
+
+  const operation = await admitSessionOperation(session.dir);
+  try {
+    const enable = await sendBridgeRequest(socket, { method: 'Network.enable', targetId });
+    if (!enable.ok) {
+      throw captureError(
+        'world',
+        'bridge_error',
+        `Network.enable failed over the session's held bridge: ${enable.error || 'unknown bridge error'}`,
+      );
+    }
+    const emulate = await sendBridgeRequest(socket, {
+      method: 'Network.emulateNetworkConditions',
+      params: {
+        offline,
+        latency: offline ? -1 : 0,
+        downloadThroughput: offline ? 0 : -1,
+        uploadThroughput: offline ? 0 : -1,
+      },
+      targetId,
+    });
+    if (!emulate.ok) {
+      throw captureError(
+        'world',
+        'bridge_error',
+        `Network.emulateNetworkConditions failed over the session's held bridge: ${emulate.error || 'unknown bridge error'}`,
+      );
+    }
+    // Local-main session network retention: record the emulation on the
+    // active session so later independent command connections re-apply it
+    // (applyActiveSessionNetworkConditions in cdp/connection.ts).
+    await setActiveNetworkOffline(offline);
+  } finally {
+    await operation.release();
+  }
+
+  emitResult(buildNetworkResult(mode, targetId), { json: parsed.json });
+}

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

@@ -0,0 +1,90 @@
+/**
+ * `capture tab open <url> [--new] [--port <port>]` — open a URL in the
+ * browser (reusing a matching tab unless `--new`) and report the tab's
+ * identity as a `<tab-opened>` block. Page-derived title/url strings flow
+ * through `data()` (I-9).
+ */
+import { detectCdpPort } from '../../detect.js';
+import { captureError, invalidInput } from '../../../errors.js';
+import { navigateAndWait } from '../../record.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 open — open a URL in the browser and report the tab's target id.
+
+input:
+  <url>           required — the URL to open; an existing tab already at it is reused unless --new
+  --new           always create a fresh background tab instead of reusing a matching one
+  --port <port>   CDP endpoint (default: the auto-discovered preferred endpoint)
+
+output: <tab-opened port=… target=…> — the tab's target id (first 8 chars are enough for --target), title, and url.
+effects: opens (or reuses) a background browser tab and waits up to 10s for its load event.`;
+
+/** Pure `<tab-opened>` result builder — exported for tests. */
+export function buildTabOpenedResult(tab: CDPTarget, port: number): RenderableResult {
+  return {
+    tag: 'tab-opened',
+    attrs: { port, target: tab.id },
+    summary: line(
+      text`tab `,
+      data(tab.id.slice(0, 8)),
+      text`: "`,
+      data(tab.title, 120),
+      text`"  `,
+      data(tab.url, 300),
+    ),
+    followUp: line(
+      text`capture page shot --port `,
+      data(port),
+      text` --target `,
+      data(tab.id.slice(0, 8)),
+    ),
+  };
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+export async function cmdTabOpen(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  // Positional cardinality (exactly 1) is enforced by `validateCliInvocation`
+  // before dispatch reaches this leaf; this guard covers direct programmatic
+  // callers only. Failures cross the boundary as typed CaptureErrors —
+  // capture.ts is the sole renderer/exit-status owner.
+  const url = parsed.positional[0];
+  if (!url) {
+    throw invalidInput('received: no URL; expected: capture tab open <url> [--new] [--port <port>].', 'missing_argument');
+  }
+
+  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.',
+    );
+  }
+
+  let tab: CDPTarget;
+  try {
+    tab = await navigateAndWait(port, url, { forceNew: parsed.new });
+  } catch (err) {
+    throw captureError('world', 'open_failed', `received: \`${url}\`; opening it on port ${port} failed: ${errorMessage(err)}`, err);
+  }
+
+  emitResult(buildTabOpenedResult(tab, port), { json: parsed.json });
+}