browser-debugger-cli 0.7.2 → 0.9.0

package/dist/ipc/client.d.ts

@@ -5,7 +5,9 @@
  * Provides high-level functions for session lifecycle and queries.
  */
 import type { ClientResponse } from './protocol/index.js';
+import type { COMMANDS } from './protocol/index.js';
 import type { HandshakeResponse, HARDataResponse, PeekResponse, SessionOptions, StartSessionResponse, StatusResponse, StopSessionResponse } from './session/index.js';
+import type { NoType } from './utils/index.js';
 /**
  * Connect to the daemon and perform handshake.
  * Verifies daemon is running and ready to accept commands.
@@ -26,6 +28,7 @@ export declare function connectToDaemon(): Promise<HandshakeResponse>;
  * Request status information from the daemon.
  * Returns daemon state, session metadata, and activity metrics.
  *
+ * @param socketPath - Daemon socket to ask (default: the selected session's)
  * @returns Status response with daemon and session information
  * @throws Error if connection fails or times out
  *
@@ -38,7 +41,7 @@ export declare function connectToDaemon(): Promise<HandshakeResponse>;
  * }
  * ```
  */
-export declare function getStatus(): Promise<StatusResponse>;
+export declare function getStatus(socketPath?: string): Promise<StatusResponse>;
 /**
  * Request preview data from the daemon.
  * Returns snapshot of collected telemetry without stopping session.
@@ -64,6 +67,8 @@ export declare function getStatus(): Promise<StatusResponse>;
  */
 export declare function getPeek(options?: {
     lastN?: number;
+    only?: 'network' | 'console';
+    withHeaders?: boolean;
 }): Promise<PeekResponse>;
 /**
  * Request network data for HAR export from the daemon.
@@ -87,7 +92,7 @@ export declare function getHARData(): Promise<HARDataResponse>;
  *
  * @param url - Target URL to navigate to
  * @param options - Session configuration options
- * @returns Start session response with worker and Chrome PIDs
+ * @returns Start session response with daemon and Chrome PIDs
  * @throws Error if connection fails, session already running, or Chrome launch fails
  *
  * @example
@@ -98,14 +103,14 @@ export declare function getHARData(): Promise<HARDataResponse>;
  *   maxBodySize: 10
  * });
  * if (response.status === 'ok' && response.data) {
- *   console.log('Session started, worker PID:', response.data.workerPid);
+ *   console.log('Session started, daemon PID:', response.data.daemonPid);
  * }
  * ```
  */
 export declare function startSession(url: string, options?: SessionOptions): Promise<StartSessionResponse>;
 /**
  * Request session stop from the daemon.
- * Stops telemetry collection, closes Chrome, and writes output file.
+ * Stops telemetry collection and closes Chrome.
  *
  * @returns Stop session response with termination status
  * @throws Error if connection fails, times out, or no active session
@@ -136,7 +141,7 @@ export declare function stopSession(): Promise<StopSessionResponse>;
  * }
  * ```
  */
-export declare function getDetails(type: 'network' | 'console', id: string): Promise<ClientResponse<'worker_details'>>;
+export declare function getDetails(type: 'network' | 'console', id: string): Promise<ClientResponse<'session_details'>>;
 /**
  * Get headers for a network request.
  * Defaults to main document navigation if no ID specified.
@@ -166,15 +171,15 @@ export declare function getDetails(type: 'network' | 'console', id: string): Pro
 export declare function getNetworkHeaders(options?: {
     id?: string;
     headerName?: string;
-}): Promise<ClientResponse<'worker_network_headers'>>;
+}): Promise<ClientResponse<'session_network_headers'>>;
 /**
- * Execute arbitrary CDP method via the daemon's worker.
- * Forwards CDP commands to the worker's active CDP connection.
+ * Execute arbitrary CDP method via the daemon.
+ * Forwards CDP commands to the session's active CDP connection.
  *
  * @param method - CDP method name (e.g., 'Network.getCookies')
  * @param params - Optional method parameters
  * @returns Response with CDP method result
- * @throws Error if connection fails or CDP method fails
+ * @throws Error if connection fails; CommandError (102) when the page was busy and its scripts were terminated
  *
  * @example
  * ```typescript
@@ -185,4 +190,46 @@ export declare function getNetworkHeaders(options?: {
  * ```
  */
 export declare function callCDP(method: string, params?: Record<string, unknown>): Promise<ClientResponse<'cdp_call'>>;
+/**
+ * Evaluate a JavaScript expression in the active page (or one of its iframes) via the daemon.
+ */
+export declare function domEval(script: string, frame?: string): Promise<ClientResponse<'dom_eval'>>;
+/**
+ * List the page's iframes via the daemon.
+ */
+export declare function domFrames(): Promise<ClientResponse<'dom_frames'>>;
+/**
+ * Fill a form field. The session subscribes to CDP events and optionally waits for
+ * network stability — CLI never opens its own CDP connection.
+ */
+export declare function domFill(params: NoType<(typeof COMMANDS)['dom_fill']['requestSchema']>): Promise<ClientResponse<'dom_fill'>>;
+/** Click an element with optional post-action stability wait. */
+export declare function domClick(params: NoType<(typeof COMMANDS)['dom_click']['requestSchema']>): Promise<ClientResponse<'dom_click'>>;
+/** Submit a form with navigation/network-idle waiting. */
+export declare function domSubmit(params: NoType<(typeof COMMANDS)['dom_submit']['requestSchema']>): Promise<ClientResponse<'dom_submit'>>;
+/** Dispatch a key event on an element. */
+export declare function domPressKey(params: NoType<(typeof COMMANDS)['dom_press_key']['requestSchema']>): Promise<ClientResponse<'dom_press_key'>>;
+/** Scroll the page or an element into view. */
+export declare function domScroll(params: NoType<(typeof COMMANDS)['dom_scroll']['requestSchema']>): Promise<ClientResponse<'dom_scroll'>>;
+/**
+ * Navigate the page (navigate, reload, back, forward) and wait for it.
+ *
+ * @param params - Action, URL and wait flag
+ * @returns Where the page is now
+ */
+export declare function pageNavigate(params: NoType<(typeof COMMANDS)['page_navigate']['requestSchema']>): Promise<ClientResponse<'page_navigate'>>;
+/** Run form discovery and return the raw structured form data. */
+export declare function domFormDiscover(): Promise<ClientResponse<'dom_form_discover'>>;
+/** List the event listeners that run for an element. */
+export declare function domListeners(params: NoType<(typeof COMMANDS)['dom_listeners']['requestSchema']>): Promise<ClientResponse<'dom_listeners'>>;
+/** Positions, sizes and visibility of elements. */
+export declare function domLayout(params: NoType<(typeof COMMANDS)['dom_layout']['requestSchema']>): Promise<ClientResponse<'dom_layout'>>;
+/**
+ * Wait until elements appear, become visible, contain a text or are gone,
+ * and/or the page has loaded.
+ *
+ * @param params - Condition and timeout
+ * @returns What the page showed once the condition was met
+ */
+export declare function domWait(params: NoType<(typeof COMMANDS)['dom_wait']['requestSchema']>): Promise<ClientResponse<'dom_wait'>>;
 //# sourceMappingURL=client.d.ts.map

package/dist/ipc/client.js

@@ -4,6 +4,9 @@
  * Public API for communicating with the daemon via Unix socket.
  * Provides high-level functions for session lifecycle and queries.
  */
+import { getIPCRequestTimeout, getQuickIPCRequestTimeout } from '../constants.js';
+import { CommandError } from '../errors/index.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
 import { sendRequest } from './transport/index.js';
 import { withSession } from './utils/index.js';
 /**
@@ -23,12 +26,23 @@ import { withSession } from './utils/index.js';
  */
 export async function connectToDaemon() {
     const request = withSession({ type: 'handshake_request' });
-    return sendRequest(request, 'handshake', 'handshake_response');
+    return sendRequest(request, 'handshake', 'handshake_response', getQuickIPCRequestTimeout());
+}
+/**
+ * Make sure the daemon answers before sending a request that may take long
+ * (page work, start, stop): a frozen daemon fails after the quick timeout
+ * instead of the full one.
+ *
+ * @throws IPCTimeoutError (quick timeout) when the daemon does not answer
+ */
+async function assertResponsive() {
+    await connectToDaemon();
 }
 /**
  * Request status information from the daemon.
  * Returns daemon state, session metadata, and activity metrics.
  *
+ * @param socketPath - Daemon socket to ask (default: the selected session's)
  * @returns Status response with daemon and session information
  * @throws Error if connection fails or times out
  *
@@ -41,9 +55,9 @@ export async function connectToDaemon() {
  * }
  * ```
  */
-export async function getStatus() {
+export async function getStatus(socketPath) {
     const request = withSession({ type: 'status_request' });
-    return sendRequest(request, 'status', 'status_response');
+    return sendRequest(request, 'status', 'status_response', getQuickIPCRequestTimeout(), socketPath);
 }
 /**
  * Request preview data from the daemon.
@@ -72,8 +86,10 @@ export async function getPeek(options) {
     const request = withSession({
         type: 'peek_request',
         ...(options?.lastN !== undefined && { lastN: options.lastN }),
+        ...(options?.only && { only: options.only }),
+        ...(options?.withHeaders && { withHeaders: true }),
     });
-    return sendRequest(request, 'peek', 'peek_response');
+    return sendRequest(request, 'peek', 'peek_response', getQuickIPCRequestTimeout());
 }
 /**
  * Request network data for HAR export from the daemon.
@@ -92,6 +108,7 @@ export async function getPeek(options) {
  */
 export async function getHARData() {
     const request = withSession({ type: 'har_data_request' });
+    await assertResponsive();
     return sendRequest(request, 'HAR data', 'har_data_response');
 }
 /**
@@ -100,7 +117,7 @@ export async function getHARData() {
  *
  * @param url - Target URL to navigate to
  * @param options - Session configuration options
- * @returns Start session response with worker and Chrome PIDs
+ * @returns Start session response with daemon and Chrome PIDs
  * @throws Error if connection fails, session already running, or Chrome launch fails
  *
  * @example
@@ -111,7 +128,7 @@ export async function getHARData() {
  *   maxBodySize: 10
  * });
  * if (response.status === 'ok' && response.data) {
- *   console.log('Session started, worker PID:', response.data.workerPid);
+ *   console.log('Session started, daemon PID:', response.data.daemonPid);
  * }
  * ```
  */
@@ -129,13 +146,16 @@ export async function startSession(url, options) {
             headless: options.headless,
             chromeWsUrl: options.chromeWsUrl,
             chromeFlags: options.chromeFlags,
+            viewport: options.viewport,
+            colorScheme: options.colorScheme,
         }),
     });
+    await assertResponsive();
     return sendRequest(request, 'start session', 'start_session_response');
 }
 /**
  * Request session stop from the daemon.
- * Stops telemetry collection, closes Chrome, and writes output file.
+ * Stops telemetry collection and closes Chrome.
  *
  * @returns Stop session response with termination status
  * @throws Error if connection fails, times out, or no active session
@@ -150,24 +170,28 @@ export async function startSession(url, options) {
  */
 export async function stopSession() {
     const request = withSession({ type: 'stop_session_request' });
+    await assertResponsive();
     return sendRequest(request, 'stop session', 'stop_session_response');
 }
 /**
- * Send a command to the worker process.
- * Internal helper for worker commands (details, CDP calls).
+ * Send a command to the daemon's session.
+ * Internal helper for session commands (details, CDP calls).
  *
  * @param commandName - Name of the command to send
  * @param params - Command parameters (without type field)
- * @returns Command response from worker
+ * @param timeoutMs - How long to wait (default: IPC timeout; page work can take long)
+ * @returns Command response from the session
  * @throws Error if connection fails or command execution fails
  */
-async function sendCommand(commandName, params) {
+async function sendCommand(commandName, params, timeoutMs) {
     const request = {
         ...params,
         type: `${commandName}_request`,
         sessionId: withSession({ type: '' }).sessionId,
     };
-    return sendRequest(request, commandName, `${commandName}_response`);
+    if (timeoutMs === undefined || timeoutMs > getQuickIPCRequestTimeout())
+        await assertResponsive();
+    return sendRequest(request, commandName, `${commandName}_response`, timeoutMs);
 }
 /**
  * Get details for a specific network request or console message.
@@ -187,7 +211,7 @@ async function sendCommand(commandName, params) {
  * ```
  */
 export async function getDetails(type, id) {
-    return sendCommand('worker_details', { itemType: type, id });
+    return sendCommand('session_details', { itemType: type, id }, getQuickIPCRequestTimeout());
 }
 /**
  * Get headers for a network request.
@@ -216,19 +240,19 @@ export async function getDetails(type, id) {
  * ```
  */
 export async function getNetworkHeaders(options) {
-    return sendCommand('worker_network_headers', {
+    return sendCommand('session_network_headers', {
         ...(options?.id && { id: options.id }),
         ...(options?.headerName && { headerName: options.headerName }),
-    });
+    }, getQuickIPCRequestTimeout());
 }
 /**
- * Execute arbitrary CDP method via the daemon's worker.
- * Forwards CDP commands to the worker's active CDP connection.
+ * Execute arbitrary CDP method via the daemon.
+ * Forwards CDP commands to the session's active CDP connection.
  *
  * @param method - CDP method name (e.g., 'Network.getCookies')
  * @param params - Optional method parameters
  * @returns Response with CDP method result
- * @throws Error if connection fails or CDP method fails
+ * @throws Error if connection fails; CommandError (102) when the page was busy and its scripts were terminated
  *
  * @example
  * ```typescript
@@ -239,6 +263,78 @@ export async function getNetworkHeaders(options) {
  * ```
  */
 export async function callCDP(method, params) {
-    return sendCommand('cdp_call', { method, ...(params && { params }) });
+    const response = await sendCommand('cdp_call', { method, ...(params && { params }) });
+    if (response.status === 'error' && response.exitCode === EXIT_CODES.CDP_TIMEOUT) {
+        throw new CommandError(response.error ?? `${method} timed out`, response.suggestion ? { suggestion: response.suggestion } : {}, EXIT_CODES.CDP_TIMEOUT);
+    }
+    return response;
+}
+/**
+ * Evaluate a JavaScript expression in the active page (or one of its iframes) via the daemon.
+ */
+export async function domEval(script, frame) {
+    return sendCommand('dom_eval', { script, ...(frame !== undefined && { frame }) });
+}
+/**
+ * List the page's iframes via the daemon.
+ */
+export async function domFrames() {
+    return sendCommand('dom_frames', {});
+}
+/**
+ * Fill a form field. The session subscribes to CDP events and optionally waits for
+ * network stability — CLI never opens its own CDP connection.
+ */
+export async function domFill(params) {
+    return sendCommand('dom_fill', params);
+}
+/** Click an element with optional post-action stability wait. */
+export async function domClick(params) {
+    return sendCommand('dom_click', params);
+}
+/** Submit a form with navigation/network-idle waiting. */
+export async function domSubmit(params) {
+    return sendCommand('dom_submit', params);
+}
+/** Dispatch a key event on an element. */
+export async function domPressKey(params) {
+    return sendCommand('dom_press_key', params);
+}
+/** Scroll the page or an element into view. */
+export async function domScroll(params) {
+    return sendCommand('dom_scroll', params);
+}
+/**
+ * Navigate the page (navigate, reload, back, forward) and wait for it.
+ *
+ * @param params - Action, URL and wait flag
+ * @returns Where the page is now
+ */
+export async function pageNavigate(params) {
+    return sendCommand('page_navigate', params);
+}
+/** Run form discovery and return the raw structured form data. */
+export async function domFormDiscover() {
+    return sendCommand('dom_form_discover', {});
+}
+/** List the event listeners that run for an element. */
+export async function domListeners(params) {
+    return sendCommand('dom_listeners', params);
+}
+/** Positions, sizes and visibility of elements. */
+export async function domLayout(params) {
+    return sendCommand('dom_layout', params);
+}
+/** Time the client gives `dom wait` beyond its --timeout (the daemon reports the timeout first) */
+const WAIT_IPC_MARGIN_MS = 10_000;
+/**
+ * Wait until elements appear, become visible, contain a text or are gone,
+ * and/or the page has loaded.
+ *
+ * @param params - Condition and timeout
+ * @returns What the page showed once the condition was met
+ */
+export async function domWait(params) {
+    return sendCommand('dom_wait', params, Math.max(getIPCRequestTimeout(), params.timeout + WAIT_IPC_MARGIN_MS));
 }
 //# sourceMappingURL=client.js.map

package/dist/ipc/index.d.ts

@@ -1,12 +1,12 @@
 /**
  * IPC Module
  *
- * Public API for inter-process communication between CLI, daemon, and worker.
+ * Public API for inter-process communication between the CLI and the daemon.
  *
  * Organized into layers:
  * - Client API (high-level functions for CLI commands)
  * - Session messages (lifecycle and query types)
- * - Protocol (worker command schemas and type guards)
+ * - Protocol (session command schemas and type guards)
  * - Transport (low-level socket communication)
  * - Validation (response validation utilities)
  */

package/dist/ipc/index.js

@@ -1,12 +1,12 @@
 /**
  * IPC Module
  *
- * Public API for inter-process communication between CLI, daemon, and worker.
+ * Public API for inter-process communication between the CLI and the daemon.
  *
  * Organized into layers:
  * - Client API (high-level functions for CLI commands)
  * - Session messages (lifecycle and query types)
- * - Protocol (worker command schemas and type guards)
+ * - Protocol (session command schemas and type guards)
  * - Transport (low-level socket communication)
  * - Validation (response validation utilities)
  */