browser-debugger-cli 0.7.1 → 0.8.0

package/dist/ipc/protocol/commands.d.ts

@@ -1,24 +1,32 @@
 /**
- * Worker Command Schemas
+ * Session Command Schemas
  *
- * Defines the request/response schemas for commands sent to the worker process.
+ * Defines the request/response schemas for commands executed by the daemon's session.
  * Each command has a request schema (input) and response data schema (output).
  */
-import type { PageState, SessionActivity } from '../../ipc/session/types.js';
+import type { HintDetails } from '../../errors/notices.js';
+import type { ClickResult, FillResult, ListenersResult, PressKeyResult, RawFormData, ScrollResult, SubmitResult } from './domTypes.js';
+import type { PageState, SessionActivity } from '../session/types.js';
 import type { NetworkRequest } from '../../types.js';
 /**
- * Worker peek command request schema.
+ * Session peek command request schema.
  */
-export interface WorkerPeekCommand {
+export interface SessionPeekCommand {
     /** Number of recent items to return. */
     lastN?: number;
     /** Offset from the end (for pagination). Default: 0 (most recent). */
     offset?: number;
+    /** Return items of one kind only (the other list is empty; totals are always set). */
+    only?: PeekSection;
+    /** Include request/response headers in network items (for header filters). */
+    withHeaders?: boolean;
 }
+/** Data kinds returned by peek. */
+export type PeekSection = 'network' | 'console';
 /**
- * Worker peek command response data.
+ * Session peek command response data.
  */
-export interface WorkerPeekData {
+export interface SessionPeekData {
     version: string;
     startTime: number;
     duration: number;
@@ -34,34 +42,46 @@ export interface WorkerPeekData {
         url: string;
         status?: number;
         mimeType?: string;
+        resourceType?: string;
+        /** Bytes transferred (for the SIZE column) */
+        encodedDataLength?: number;
+        /** Failure reason for failed requests */
+        errorText?: string;
+        /** Milliseconds from start to last byte, failure or redirect (absent while pending) */
+        duration?: number;
     }>;
     console: Array<{
+        index?: number;
         timestamp: number;
         type: string;
         text: string;
+        /** Browser subsystem of a browser message (`network`, `security`, ...) */
+        source?: string;
     }>;
+    /** Navigation id of the page currently loaded. */
+    currentNavigationId: number;
     /** Total number of network requests (for pagination). */
-    totalNetwork?: number;
+    totalNetwork: number;
     /** Total number of console messages (for pagination). */
-    totalConsole?: number;
+    totalConsole: number;
     /** Whether there are more network items available. */
     hasMoreNetwork?: boolean;
     /** Whether there are more console items available. */
     hasMoreConsole?: boolean;
 }
 /**
- * Worker details command request schema.
+ * Session details command request schema.
  */
-export interface WorkerDetailsCommand {
+export interface SessionDetailsCommand {
     /** Type of item to get details for. */
     itemType: 'network' | 'console';
     /** Unique identifier of the item. */
     id: string;
 }
 /**
- * Worker details command response data.
+ * Session details command response data.
  */
-export interface WorkerDetailsData {
+export interface SessionDetailsData {
     /** The requested item (network request or console message). */
     item: unknown;
 }
@@ -80,17 +100,17 @@ export interface CdpCallCommand {
 export interface CdpCallData {
     /** Result from CDP method call. */
     result: unknown;
-    /** Optional hint for more efficient alternative command. */
-    hint?: string;
+    /** Structured hint suggesting a more efficient alternative. UI formats at boundary. */
+    hint?: HintDetails;
 }
 /**
- * Worker status command request schema (no parameters required).
+ * Session status command request schema (no parameters required).
  */
-export type WorkerStatusCommand = Record<string, unknown>;
+export type SessionStatusCommand = Record<string, unknown>;
 /**
- * Worker status command response data.
+ * Session status command response data.
  */
-export interface WorkerStatusData {
+export interface SessionStatusData {
     startTime: number;
     duration: number;
     target: PageState;
@@ -100,29 +120,29 @@ export interface WorkerStatusData {
     navigationId: number;
 }
 /**
- * Worker HAR data command request schema (no parameters required).
+ * Session HAR data command request schema (no parameters required).
  */
-export type WorkerHARDataCommand = Record<string, unknown>;
+export type SessionHARDataCommand = Record<string, unknown>;
 /**
- * Worker HAR data command response data.
+ * Session HAR data command response data.
  */
-export interface WorkerHARDataData {
+export interface SessionHARDataData {
     /** All collected network requests for HAR export. */
     requests: NetworkRequest[];
 }
 /**
- * Worker network headers command request schema.
+ * Session network headers command request schema.
  */
-export interface WorkerNetworkHeadersCommand {
+export interface SessionNetworkHeadersCommand {
     /** Optional request ID to get headers from. Defaults to main page navigation. */
     id?: string;
     /** Optional header name to filter results. Case-insensitive. */
     headerName?: string;
 }
 /**
- * Worker network headers command response data.
+ * Session network headers command response data.
  */
-export interface WorkerNetworkHeadersData {
+export interface SessionNetworkHeadersData {
     /** URL of the request. */
     url: string;
     /** Request ID for correlation with peek output. */
@@ -132,6 +152,137 @@ export interface WorkerNetworkHeadersData {
     /** Response headers. */
     responseHeaders: Record<string, string>;
 }
+/**
+ * dom_eval: evaluate a JavaScript expression in the page and return its value.
+ */
+export interface DomEvalCommand {
+    script: string;
+    /** Iframe to evaluate in: index, name/id attribute, or URL substring */
+    frame?: string;
+}
+export interface DomEvalData {
+    /** JSON value, or a readable description for values JSON cannot represent */
+    value: unknown;
+    /** JavaScript type of the result */
+    type: string;
+    /** Object subtype (node, date, array, ...) */
+    subtype?: string;
+    /** URL of the iframe the script ran in (with `frame`) */
+    frame?: string;
+}
+/** An iframe of the page, as listed by `bdg dom frames` */
+export interface DomFrame {
+    /** 0-based position: depth-first, out-of-process frames after in-process siblings */
+    index: number;
+    /** Frame URL */
+    url: string;
+    /** Frame name (`name` attribute or `window.name`) */
+    name?: string;
+    /** `id` attribute of the iframe element */
+    id?: string;
+    /** Security origin */
+    origin: string;
+    /** Origin differs from the page's */
+    crossOrigin: boolean;
+    /** Runs in its own renderer process (site isolation) */
+    outOfProcess: boolean;
+}
+/**
+ * dom_frames: list the page's iframes (including nested and out-of-process ones).
+ */
+export type DomFramesCommand = Record<string, never>;
+export interface DomFramesData {
+    frames: DomFrame[];
+}
+/**
+ * dom_fill: fill a form field, optionally waiting for network stability after.
+ */
+export interface DomFillCommand {
+    selector: string;
+    /** CLI working directory (file inputs: relative paths) */
+    cwd?: string;
+    value: string;
+    index?: number;
+    /** Exact element from the query cache (overrides selector/index) */
+    backendNodeId?: number;
+    blur?: boolean;
+    wait?: boolean;
+}
+export type DomFillData = FillResult;
+/**
+ * dom_click: click an element, optionally waiting for stability after.
+ */
+export interface DomClickCommand {
+    selector: string;
+    index?: number;
+    /** Exact element from the query cache (overrides selector/index) */
+    backendNodeId?: number;
+    wait?: boolean;
+    /** Double or right click, or only hover (default: click) */
+    action?: 'click' | 'double' | 'right' | 'hover';
+}
+export type DomClickData = ClickResult;
+/**
+ * dom_submit: submit a form with smart waiting (navigation / network idle).
+ */
+export interface DomSubmitCommand {
+    selector: string;
+    index?: number;
+    /** Exact element from the query cache (overrides selector/index) */
+    backendNodeId?: number;
+    waitNavigation?: boolean;
+    waitNetwork?: number;
+    timeout?: number;
+}
+export type DomSubmitData = SubmitResult;
+/**
+ * dom_press_key: dispatch a key event on an element.
+ */
+export interface DomPressKeyCommand {
+    selector: string;
+    key: string;
+    index?: number;
+    /** Exact element from the query cache (overrides selector/index) */
+    backendNodeId?: number;
+    times?: number;
+    modifiers?: string;
+    wait?: boolean;
+}
+export type DomPressKeyData = PressKeyResult;
+/**
+ * dom_scroll: scroll the page or an element into view.
+ */
+export interface DomScrollCommand {
+    selector?: string;
+    index?: number;
+    /** Exact element from the query cache (overrides selector/index) */
+    backendNodeId?: number;
+    down?: number;
+    up?: number;
+    left?: number;
+    right?: number;
+    top?: boolean;
+    bottom?: boolean;
+    wait?: boolean;
+}
+export type DomScrollData = ScrollResult;
+/**
+ * dom_listeners: list the event listeners that run for an element.
+ */
+export interface DomListenersCommand {
+    selector: string;
+    index?: number;
+    /** Exact element from the query cache (overrides selector/index) */
+    backendNodeId?: number;
+    /** Only these event types (default: all) */
+    types?: string[];
+}
+export type DomListenersData = ListenersResult;
+/**
+ * dom_form_discover: run the form discovery script and return raw form data.
+ */
+export type DomFormDiscoverCommand = Record<string, never>;
+export type DomFormDiscoverData = RawFormData;
 /**
  * Command definition structure.
  */
@@ -143,43 +294,53 @@ type CommandDef<TReq, TRes> = {
  * Shape of the command registry.
  */
 export type RegistryShape = {
-    worker_peek: CommandDef<WorkerPeekCommand, WorkerPeekData>;
-    worker_details: CommandDef<WorkerDetailsCommand, WorkerDetailsData>;
-    worker_status: CommandDef<WorkerStatusCommand, WorkerStatusData>;
-    worker_har_data: CommandDef<WorkerHARDataCommand, WorkerHARDataData>;
-    worker_network_headers: CommandDef<WorkerNetworkHeadersCommand, WorkerNetworkHeadersData>;
+    session_peek: CommandDef<SessionPeekCommand, SessionPeekData>;
+    session_details: CommandDef<SessionDetailsCommand, SessionDetailsData>;
+    session_status: CommandDef<SessionStatusCommand, SessionStatusData>;
+    session_har_data: CommandDef<SessionHARDataCommand, SessionHARDataData>;
+    session_network_headers: CommandDef<SessionNetworkHeadersCommand, SessionNetworkHeadersData>;
     cdp_call: CommandDef<CdpCallCommand, CdpCallData>;
+    dom_eval: CommandDef<DomEvalCommand, DomEvalData>;
+    dom_frames: CommandDef<DomFramesCommand, DomFramesData>;
+    dom_fill: CommandDef<DomFillCommand, DomFillData>;
+    dom_click: CommandDef<DomClickCommand, DomClickData>;
+    dom_submit: CommandDef<DomSubmitCommand, DomSubmitData>;
+    dom_press_key: CommandDef<DomPressKeyCommand, DomPressKeyData>;
+    dom_scroll: CommandDef<DomScrollCommand, DomScrollData>;
+    dom_form_discover: CommandDef<DomFormDiscoverCommand, DomFormDiscoverData>;
+    dom_listeners: CommandDef<DomListenersCommand, DomListenersData>;
+    page_navigate: CommandDef<PageNavigateCommand, PageNavigationResult>;
 };
+/** What `bdg page` does */
+export type PageAction = 'navigate' | 'reload' | 'back' | 'forward';
+/** Result of a page navigation */
+export interface PageNavigationResult {
+    /** What was done */
+    action: PageAction;
+    /** URL of the page afterwards (the requested URL with --no-wait) */
+    url: string;
+    /** Title of the page afterwards */
+    title: string;
+    /** HTTP status of the new document, when one was loaded */
+    status?: number;
+    /** Something worth knowing: an HTTP error, a download, a page still loading */
+    warning?: string;
+}
 /**
- * Central registry of all worker commands.
+ * page_navigate: navigate, reload, or go back/forward, then wait for the page.
+ */
+export interface PageNavigateCommand {
+    action: PageAction;
+    /** URL to load (navigate) */
+    url?: string;
+    /** Wait for the page to load (default: true) */
+    wait?: boolean;
+}
+/**
+ * Central registry of all session commands.
  * Maps command names to their request/response schemas.
  */
-export declare const COMMANDS: {
-    readonly worker_peek: {
-        readonly requestSchema: WorkerPeekCommand;
-        readonly responseSchema: WorkerPeekData;
-    };
-    readonly worker_details: {
-        readonly requestSchema: WorkerDetailsCommand;
-        readonly responseSchema: WorkerDetailsData;
-    };
-    readonly worker_status: {
-        readonly requestSchema: WorkerStatusCommand;
-        readonly responseSchema: WorkerStatusData;
-    };
-    readonly worker_har_data: {
-        readonly requestSchema: WorkerHARDataCommand;
-        readonly responseSchema: WorkerHARDataData;
-    };
-    readonly worker_network_headers: {
-        readonly requestSchema: WorkerNetworkHeadersCommand;
-        readonly responseSchema: WorkerNetworkHeadersData;
-    };
-    readonly cdp_call: {
-        readonly requestSchema: CdpCallCommand;
-        readonly responseSchema: CdpCallData;
-    };
-};
+export declare const COMMANDS: RegistryShape;
 /**
  * All registered command schemas.
  */

package/dist/ipc/protocol/commands.js

@@ -1,31 +1,37 @@
 /**
- * Worker Command Schemas
+ * Session Command Schemas
  *
- * Defines the request/response schemas for commands sent to the worker process.
+ * Defines the request/response schemas for commands executed by the daemon's session.
  * Each command has a request schema (input) and response data schema (output).
  */
 /**
- * Central registry of all worker commands.
+ * Creates a phantom command definition that carries request/response types only.
+ *
+ * @returns Empty schema objects typed as the inferred request and response
+ */
+function defineCommand() {
+    return { requestSchema: {}, responseSchema: {} };
+}
+/**
+ * Central registry of all session commands.
  * Maps command names to their request/response schemas.
  */
 export const COMMANDS = {
-    worker_peek: { requestSchema: {}, responseSchema: {} },
-    worker_details: {
-        requestSchema: {},
-        responseSchema: {},
-    },
-    worker_status: {
-        requestSchema: {},
-        responseSchema: {},
-    },
-    worker_har_data: {
-        requestSchema: {},
-        responseSchema: {},
-    },
-    worker_network_headers: {
-        requestSchema: {},
-        responseSchema: {},
-    },
-    cdp_call: { requestSchema: {}, responseSchema: {} },
+    session_peek: defineCommand(),
+    session_details: defineCommand(),
+    session_status: defineCommand(),
+    session_har_data: defineCommand(),
+    session_network_headers: defineCommand(),
+    cdp_call: defineCommand(),
+    dom_eval: defineCommand(),
+    dom_frames: defineCommand(),
+    dom_fill: defineCommand(),
+    dom_click: defineCommand(),
+    dom_submit: defineCommand(),
+    dom_press_key: defineCommand(),
+    dom_scroll: defineCommand(),
+    page_navigate: defineCommand(),
+    dom_form_discover: defineCommand(),
+    dom_listeners: defineCommand(),
 };
 //# sourceMappingURL=commands.js.map

package/dist/ipc/protocol/domTypes.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Protocol-owned DTOs for DOM command results.
+ *
+ * These interfaces describe the shape of data the daemon returns over IPC.
+ * Runtime implementations must produce values conforming to these shapes;
+ * CLI commands and IPC transport consume them directly. Keeping the contract
+ * here lets runtime and transport evolve independently.
+ */
+import type { FormStep, FieldOption } from '../../types.js';
+/**
+ * A JavaScript dialog (alert, confirm, prompt, beforeunload) that bdg accepted
+ * while a command ran.
+ */
+export interface DialogInfo {
+    /** Dialog type: alert, confirm, prompt or beforeunload */
+    type: string;
+    /** Text the page showed */
+    message: string;
+}
+/**
+ * Result of filling an element.
+ */
+export interface FillResult {
+    success: boolean;
+    error?: string;
+    selector?: string;
+    value?: string;
+    elementType?: string;
+    inputType?: string | null;
+    checked?: boolean;
+    suggestion?: string;
+    /** Set when the target is a file input (filled through CDP instead) */
+    fileInput?: boolean;
+    /** Something the page will likely object to (e.g. a value above max) */
+    warning?: string;
+    /** Elements the selector matched */
+    matchCount?: number;
+    exitCode?: number;
+    /** Dialogs accepted while the command ran */
+    dialogs?: DialogInfo[];
+}
+/**
+ * Result of clicking an element.
+ */
+export interface ClickResult {
+    success: boolean;
+    error?: string;
+    selector?: string;
+    elementType?: string;
+    matchCount?: number;
+    selectedIndex?: number;
+    requestedIndex?: number;
+    suggestion?: string;
+    /** How the click was performed: real mouse events, or el.click() fallback */
+    method?: 'mouse' | 'dom';
+    /** What was done: click, double (click), right (click) or hover */
+    action?: 'click' | 'double' | 'right' | 'hover';
+    /** Exit code for a failure */
+    exitCode?: number;
+    /** Why the DOM fallback was used (element covered or without size) */
+    warning?: string;
+    /** Dialogs accepted while the command ran */
+    dialogs?: DialogInfo[];
+}
+/**
+ * Result of pressing a key on an element.
+ */
+export interface PressKeyResult {
+    success: boolean;
+    error?: string;
+    selector?: string;
+    key?: string;
+    times?: number;
+    /** Modifier keys held, e.g. ["Ctrl", "Shift"] */
+    modifiers?: string[];
+    elementType?: string | undefined;
+    suggestion?: string;
+    exitCode?: number;
+    /** Elements the selector matched */
+    matchCount?: number;
+    /** Set when the selector matched several elements */
+    warning?: string;
+    /** Dialogs accepted while the command ran */
+    dialogs?: DialogInfo[];
+}
+/**
+ * Result of a scroll operation.
+ */
+export interface ScrollResult {
+    success: boolean;
+    error?: string;
+    suggestion?: string;
+    exitCode?: number;
+    scrollType: 'element' | 'position' | 'offset';
+    selector?: string;
+    scrolledTo?: {
+        x: number;
+        y: number;
+    };
+    scrolledBy?: {
+        x: number;
+        y: number;
+    };
+    viewportSize?: {
+        width: number;
+        height: number;
+    };
+    pageSize?: {
+        width: number;
+        height: number;
+    };
+    /** Elements the selector matched */
+    matchCount?: number;
+    /** Set when the selector matched several elements */
+    warning?: string;
+}
+/**
+ * Result of submitting a form.
+ */
+export interface SubmitResult {
+    success: boolean;
+    error?: string;
+    selector?: string;
+    clicked?: boolean;
+    networkRequests?: number;
+    navigationOccurred?: boolean;
+    waitTimeMs?: number;
+    suggestion?: string;
+    exitCode?: number;
+    /** Dialogs accepted while the command ran */
+    dialogs?: DialogInfo[];
+}
+/** Where an event listener is attached, seen from the inspected element. */
+export type ListenerPlacement = 'target' | 'ancestor' | 'document' | 'window';
+/** The function an event listener calls. */
+export interface ListenerHandler {
+    /** Function name (`Function.name`; empty when anonymous) */
+    name: string;
+    /** Start of the function source, on one line */
+    preview: string;
+    /** Script that defines the handler (CDP script id) */
+    scriptId: string;
+    /** 0-based line in the script */
+    lineNumber: number;
+    /** 0-based column in the script */
+    columnNumber: number;
+}
+/** An event listener that runs for events on the inspected element. */
+export interface ElementListener {
+    /** Event type, e.g. `click` */
+    type: string;
+    /** Where the listener is attached */
+    on: ListenerPlacement;
+    /** The node or object it is attached to, e.g. `div#root.app` */
+    node: string;
+    useCapture: boolean;
+    passive: boolean;
+    once: boolean;
+    handler: ListenerHandler;
+}
+/**
+ * Event listeners of an element, its ancestors, its document and window,
+ * grouped by event type, nearest first.
+ */
+export interface ListenersResult {
+    /** Always true: failures are reported as errors */
+    success: true;
+    /** Selector the element was found with */
+    selector?: string;
+    /** Index among the selector's matches (or in the cached query) */
+    index?: number;
+    /** The inspected element, e.g. `button#save` */
+    element: string;
+    listeners: ElementListener[];
+    /** Elements the selector matched */
+    matchCount?: number;
+    /** Set when several elements matched and no --index was given */
+    warning?: string;
+}
+/**
+ * Raw form data returned from the page-context form-discovery script.
+ */
+export interface RawFormData {
+    forms: RawForm[];
+    /** Same-origin iframes holding form fields, when the main document has none */
+    frameForms?: Array<{
+        url: string;
+    }>;
+}
+export interface RawForm {
+    index: number;
+    name: string | null;
+    action: string | null;
+    method: string;
+    step: FormStep | null;
+    relevanceScore: number;
+    inIframe: boolean;
+    iframeUrl?: string;
+    crossOrigin?: boolean;
+    fields: RawField[];
+    buttons: RawButton[];
+}
+export interface RawField {
+    index: number;
+    formIndex: number;
+    selector: string;
+    type: string;
+    inputType?: string;
+    label: string;
+    name: string | null;
+    placeholder?: string;
+    required: boolean;
+    disabled: boolean;
+    readOnly: boolean;
+    hidden: boolean;
+    native: boolean;
+    value: string | boolean | string[];
+    checked?: boolean;
+    validationMessage?: string;
+    isValid: boolean;
+    /** Only the "required but empty" constraint fails */
+    valueMissing?: boolean;
+    ariaInvalid?: boolean;
+    hasErrorClass?: boolean;
+    siblingErrorText?: string;
+    options?: FieldOption[];
+}
+export interface RawButton {
+    index: number;
+    selector: string;
+    label: string;
+    type: string;
+    disabled: boolean;
+    isPrimary: boolean;
+}
+//# sourceMappingURL=domTypes.d.ts.map

package/dist/ipc/protocol/domTypes.js

@@ -0,0 +1,10 @@
+/**
+ * Protocol-owned DTOs for DOM command results.
+ *
+ * These interfaces describe the shape of data the daemon returns over IPC.
+ * Runtime implementations must produce values conforming to these shapes;
+ * CLI commands and IPC transport consume them directly. Keeping the contract
+ * here lets runtime and transport evolve independently.
+ */
+export {};
+//# sourceMappingURL=domTypes.js.map