browser-debugger-cli 0.7.2 → 0.9.0

package/dist/commands/shared/dataFetcher.js

@@ -1,19 +1,51 @@
 /**
  * Shared data fetching utilities for commands that query daemon state.
  */
+import { sessionNotRespondingError, sessionUnavailableSuggestion } from '../../errors/messages.js';
 import { getPeek } from '../../ipc/client.js';
 import { validateIPCResponse } from '../../ipc/index.js';
+import { IPCConnectionError, IPCEarlyCloseError, IPCTimeoutError, } from '../../ipc/transport/IPCError.js';
+import { isConnectionError } from '../../ipc/utils/errors.js';
 import { createLogger } from '../../ui/logging/index.js';
+import { noActiveSessionMessage } from '../../ui/messages/sessionCommand.js';
 import { getExitCodeForConnectionError } from '../../utils/errorMapping.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 const log = createLogger('fetcher');
 /**
  * Fetch raw preview output from daemon.
+ *
+ * @param query - Window, section and header options
+ * @returns Preview output or a fetch error
  */
-export async function fetchPreviewOutput(lastN) {
-    log.debug(`Fetching preview output${lastN !== undefined ? ` (lastN: ${lastN})` : ''}`);
-    const response = await getPeek(lastN !== undefined ? { lastN } : undefined);
+export async function fetchPreviewOutput(query = {}) {
+    log.debug(`Fetching preview output ${JSON.stringify(query)}`);
+    let response;
+    try {
+        response = await getPeek(query);
+    }
+    catch (error) {
+        if (error instanceof IPCTimeoutError) {
+            const err = sessionNotRespondingError(error.timeoutMs / 1000);
+            return {
+                success: false,
+                error: err.message,
+                exitCode: EXIT_CODES.CDP_TIMEOUT,
+                suggestion: err.suggestion,
+            };
+        }
+        const gone = error instanceof IPCConnectionError ||
+            error instanceof IPCEarlyCloseError ||
+            isConnectionError(error);
+        if (!gone)
+            throw error;
+        log.debug(`Daemon unreachable: ${getErrorMessage(error)}`);
+        return {
+            success: false,
+            error: noActiveSessionMessage(),
+            exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
+        };
+    }
     try {
         validateIPCResponse(response);
     }
@@ -37,9 +69,12 @@ export async function fetchPreviewOutput(lastN) {
 }
 /**
  * Fetch preview data with parsed network and console arrays.
+ *
+ * @param query - Window, section and header options
+ * @returns Preview data or a fetch error
  */
-export async function fetchPreviewData(lastN) {
-    const result = await fetchPreviewOutput(lastN);
+export async function fetchPreviewData(query = {}) {
+    const result = await fetchPreviewOutput(query);
     if (!result.success)
         return result;
     return {
@@ -52,31 +87,33 @@ export async function fetchPreviewData(lastN) {
     };
 }
 /**
- * Fetch network requests from daemon.
+ * Fetch all captured network requests from daemon.
+ *
+ * @param withHeaders - Include request/response headers (needed by header filters)
+ * @returns Requests or a fetch error
  */
-export async function fetchNetworkRequests() {
-    const result = await fetchPreviewData();
+export async function fetchNetworkRequests(withHeaders = false) {
+    const result = await fetchPreviewData({ lastN: 0, only: 'network', withHeaders });
     if (!result.success)
         return result;
     return { success: true, data: result.data.network };
 }
 /**
- * Fetch console messages from daemon.
+ * Fetch all console messages from daemon.
+ *
+ * @returns Messages (with their session-wide index) and the navigation id of
+ *   the page currently loaded
  */
 export async function fetchConsoleMessages() {
-    const result = await fetchPreviewData(0);
+    const result = await fetchPreviewData({ lastN: 0, only: 'console' });
     if (!result.success)
         return result;
-    return { success: true, data: result.data.console };
-}
-/**
- * Create error result for daemon not running.
- */
-export function createDaemonNotRunningError() {
     return {
-        success: false,
-        error: 'Daemon not running',
-        exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
+        success: true,
+        data: {
+            messages: result.data.console,
+            currentNavigationId: result.data.output.currentNavigationId,
+        },
     };
 }
 /**
@@ -87,7 +124,7 @@ export function createDaemonNotRunningError() {
  * @param suggestion - Suggestion text for the user
  * @returns Error result object
  */
-export function createErrorResult(error, exitCode, suggestion = 'Start a session with: bdg <url>') {
+export function createErrorResult(error, exitCode, suggestion = sessionUnavailableSuggestion(exitCode)) {
     return {
         success: false,
         error,

package/dist/commands/shared/followMode.d.ts

@@ -4,6 +4,25 @@
  * Provides a unified pattern for commands that continuously poll
  * and display updates (like tail -f behavior).
  */
+/** What a refresh asks for: nothing to keep following, or the exit code to stop with */
+export type FollowPoll = {
+    exitCode: number;
+} | undefined;
+/**
+ * Report a failed fetch in follow mode: a lost connection is reported and
+ * retried while the session was seen before, otherwise follow mode stops.
+ *
+ * @param failure - The fetch's error and exit code
+ * @param options - JSON output and the retry interval shown
+ * @returns The exit code to stop with, or undefined to keep following
+ */
+export declare function followFetchFailure(failure: {
+    error: string;
+    exitCode?: number | undefined;
+}, options: {
+    json?: boolean | undefined;
+    retryIntervalMs: number;
+}): FollowPoll;
 /**
  * Options for configuring follow mode behavior.
  */
@@ -14,8 +33,6 @@ export interface FollowModeOptions {
     stopMessage: () => string;
     /** Polling interval in milliseconds (default: 1000) */
     intervalMs?: number;
-    /** Handle EPIPE errors gracefully (for piped output) */
-    handleEpipe?: boolean;
 }
 /**
  * Sets up follow mode with periodic refresh and graceful shutdown.
@@ -26,7 +43,7 @@ export interface FollowModeOptions {
  * - First refresh call (awaited)
  * - Periodic interval-based refresh
  * - SIGINT handler for graceful shutdown
- * - Optional EPIPE handling for piped output
+ * - Stopping with the exit code a refresh returns (e.g. the session is gone)
  *
  * @param refreshFn - Async function to call on each refresh cycle
  * @param options - Configuration options for follow mode
@@ -46,5 +63,5 @@ export interface FollowModeOptions {
  * );
  * ```
  */
-export declare function setupFollowMode(refreshFn: () => Promise<void>, options: FollowModeOptions): Promise<void>;
+export declare function setupFollowMode(refreshFn: () => Promise<FollowPoll>, options: FollowModeOptions): Promise<void>;
 //# sourceMappingURL=followMode.d.ts.map

package/dist/commands/shared/followMode.js

@@ -4,7 +4,29 @@
  * Provides a unified pattern for commands that continuously poll
  * and display updates (like tail -f behavior).
  */
+import { handleDaemonConnectionError } from './daemonErrorHandler.js';
+import { genericError } from '../../errors/messages.js';
+import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
+/**
+ * Report a failed fetch in follow mode: a lost connection is reported and
+ * retried while the session was seen before, otherwise follow mode stops.
+ *
+ * @param failure - The fetch's error and exit code
+ * @param options - JSON output and the retry interval shown
+ * @returns The exit code to stop with, or undefined to keep following
+ */
+export function followFetchFailure(failure, options) {
+    const result = handleDaemonConnectionError(failure.error, {
+        json: options.json,
+        follow: true,
+        retryIntervalMs: options.retryIntervalMs,
+        exitCode: failure.exitCode,
+    });
+    return result.shouldExit
+        ? { exitCode: result.exitCode ?? EXIT_CODES.RESOURCE_NOT_FOUND }
+        : undefined;
+}
 /**
  * Sets up follow mode with periodic refresh and graceful shutdown.
  *
@@ -14,7 +36,7 @@ import { EXIT_CODES } from '../../utils/exitCodes.js';
  * - First refresh call (awaited)
  * - Periodic interval-based refresh
  * - SIGINT handler for graceful shutdown
- * - Optional EPIPE handling for piped output
+ * - Stopping with the exit code a refresh returns (e.g. the session is gone)
  *
  * @param refreshFn - Async function to call on each refresh cycle
  * @param options - Configuration options for follow mode
@@ -35,24 +57,24 @@ import { EXIT_CODES } from '../../utils/exitCodes.js';
  * ```
  */
 export async function setupFollowMode(refreshFn, options) {
-    const { startMessage, stopMessage, intervalMs = 1000, handleEpipe = false } = options;
+    const { startMessage, stopMessage, intervalMs = 1000 } = options;
+    const stopIfAsked = (poll) => {
+        if (poll)
+            process.exit(poll.exitCode);
+    };
     console.error(startMessage());
-    await refreshFn();
+    stopIfAsked(await refreshFn());
     const intervalId = setInterval(() => {
-        void refreshFn();
+        refreshFn()
+            .then(stopIfAsked)
+            .catch((error) => {
+            console.error(genericError(getErrorMessage(error)));
+        });
     }, intervalMs);
     process.on('SIGINT', () => {
         clearInterval(intervalId);
         console.error(stopMessage());
         process.exit(EXIT_CODES.SUCCESS);
     });
-    if (handleEpipe) {
-        process.stdout.on('error', (err) => {
-            if (err.code === 'EPIPE') {
-                clearInterval(intervalId);
-                process.exit(EXIT_CODES.SUCCESS);
-            }
-        });
-    }
 }
 //# sourceMappingURL=followMode.js.map

package/dist/commands/shared/handleValidationError.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Print a validation error in the format matching the command's output mode
+ * and exit with the appropriate code.
+ *
+ * For `CommandError`, emits either a JSON envelope (when `json=true`) or
+ * a human-readable message + suggestion, then exits with the error's own
+ * exit code. For anything else, prints the message (as an envelope with
+ * `--json`) and exits with `INVALID_ARGUMENTS`.
+ *
+ * @param error - Error thrown from validation code
+ * @param json - Whether the caller is in `--json` output mode
+ */
+export declare function handleValidationError(error: unknown, json: boolean): never;
+//# sourceMappingURL=handleValidationError.d.ts.map

package/dist/commands/shared/handleValidationError.js

@@ -0,0 +1,48 @@
+import { CommandError } from '../../errors/index.js';
+import { genericError } from '../../errors/messages.js';
+import { OutputBuilder } from '../../ui/OutputBuilder.js';
+import { escapeControlChars } from '../../ui/formatting.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+/**
+ * Print a validation error in the format matching the command's output mode
+ * and exit with the appropriate code.
+ *
+ * For `CommandError`, emits either a JSON envelope (when `json=true`) or
+ * a human-readable message + suggestion, then exits with the error's own
+ * exit code. For anything else, prints the message (as an envelope with
+ * `--json`) and exits with `INVALID_ARGUMENTS`.
+ *
+ * @param error - Error thrown from validation code
+ * @param json - Whether the caller is in `--json` output mode
+ */
+export function handleValidationError(error, json) {
+    if (error instanceof CommandError) {
+        if (json) {
+            const errorOptions = {
+                exitCode: error.exitCode,
+            };
+            if (error.metadata.suggestion) {
+                errorOptions.suggestion = error.metadata.suggestion;
+            }
+            console.log(JSON.stringify(OutputBuilder.buildJsonError(error.message, errorOptions), null, 2));
+        }
+        else {
+            console.error(genericError(error.message));
+            if (error.metadata.suggestion)
+                console.error(escapeControlChars(error.metadata.suggestion));
+        }
+        process.exit(error.exitCode);
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (json) {
+        const envelope = OutputBuilder.buildJsonError(message, {
+            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+        });
+        console.log(JSON.stringify(envelope, null, 2));
+    }
+    else {
+        console.error(genericError(message));
+    }
+    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+}
+//# sourceMappingURL=handleValidationError.js.map

package/dist/commands/shared/optionTypes.d.ts

@@ -23,6 +23,10 @@
 export interface BaseOptions {
     /** Output as JSON instead of human-readable format */
     json?: boolean;
+    /** Hide tips and hints (`-q`, accepted by every command) */
+    quiet?: boolean;
+    /** Named session to act on (`--session`, accepted by every command) */
+    session?: string;
 }
 /**
  * Options for commands with verbose output.
@@ -56,6 +60,8 @@ export interface CleanupOptions {
     removeOutput?: boolean;
     /** Aggressive cleanup - kill all Chrome processes */
     aggressive?: boolean;
+    /** Also delete the named session's directory (profile, logs, port) */
+    purge?: boolean;
 }
 /**
  * Options for commands with raw output mode.
@@ -109,14 +115,6 @@ export interface KeyPressOptions {
     /** Key modifiers (ctrl, alt, shift, meta) */
     modifiers?: string;
 }
-/**
- * Options for port configuration.
- * Commander passes port as string from CLI.
- */
-export interface PortOptions {
-    /** CDP port number (string from CLI) */
-    port?: string;
-}
 /**
  * Options for CDP command operations.
  */
@@ -144,11 +142,26 @@ export type DetailsCommandOptions = BaseOptions & {
 /** Options for DOM query command */
 export type DomQueryCommandOptions = BaseOptions;
 /** Options for DOM get command */
-export type DomGetCommandOptions = BaseOptions & RawOptions & SelectionOptions;
+export type DomGetCommandOptions = BaseOptions & RawOptions & SelectionOptions & {
+    /** All of the element's text instead of its first 500 characters (semantic output) */
+    full?: boolean;
+    /** Which match of the selector (0-based); `--nth` is its alias */
+    index?: number;
+};
 /** Options for DOM screenshot command */
 export type DomScreenshotCommandOptions = BaseOptions & ScreenshotOptions;
 /** Options for DOM eval command */
-export type DomEvalCommandOptions = BaseOptions & PortOptions;
+export interface DomEvalCommandOptions extends BaseOptions {
+    /** Iframe to evaluate in: index, name/id attribute, or part of the name, id or URL */
+    frame?: string;
+}
+/** Options for DOM frames command */
+export type DomFramesCommandOptions = BaseOptions;
+/** Options for DOM form command */
+export interface FormCommandOptions extends BaseOptions {
+    all?: boolean;
+    brief?: boolean;
+}
 /**
  * Options for fill command.
  * Note: Commander parses --no-blur and --no-wait as boolean flags.
@@ -166,18 +179,21 @@ export interface FillCommandOptions extends BaseOptions, IndexOptions {
 export interface ClickCommandOptions extends BaseOptions, IndexOptions {
     /** Wait for stability after click (--no-wait sets to false) */
     wait: boolean;
+    /** Double-click */
+    double?: boolean;
+    /** Right-click */
+    right?: boolean;
 }
 /**
  * Options for submit command.
- * Note: waitNetwork and timeout come as strings from Commander.
  */
 export interface SubmitCommandOptions extends BaseOptions, IndexOptions {
     /** Wait for navigation to complete */
     waitNavigation?: boolean;
-    /** Wait for network idle (milliseconds as string) */
-    waitNetwork: string;
-    /** Timeout (milliseconds as string) */
-    timeout: string;
+    /** Wait for network idle (milliseconds) */
+    waitNetwork: number;
+    /** Timeout (milliseconds) */
+    timeout: number;
 }
 /**
  * Options for pressKey command.
@@ -207,10 +223,39 @@ export interface ScrollCommandOptions extends BaseOptions, IndexOptions {
     /** Wait for stability after scroll (--no-wait sets to false) */
     wait: boolean;
 }
+/**
+ * Options for `dom listeners`.
+ */
+export interface ListenersCommandOptions extends BaseOptions, IndexOptions {
+    /** Only these event types (from --type, comma-separated, repeatable) */
+    type?: string[];
+    /** List every listener of framework roots */
+    all?: boolean;
+}
+/**
+ * Options for `dom layout`.
+ */
+export type LayoutCommandOptions = BaseOptions & IndexOptions;
+/** Options for `bdg dom wait` */
+export interface WaitCommandOptions extends BaseOptions {
+    /** Text a match must contain */
+    text?: string;
+    /** Wait for the matches to be gone */
+    gone?: boolean;
+    /** Only count visible matches */
+    visible?: boolean;
+    /** Wait for document.readyState to be complete */
+    load?: boolean;
+    /** Give up after this many milliseconds */
+    timeout: number;
+}
 /** Options for A11y tree command */
 export type A11yTreeCommandOptions = BaseOptions;
 /** Options for A11y query command */
-export type A11yQueryCommandOptions = BaseOptions;
+export interface A11yQueryCommandOptions extends BaseOptions {
+    /** Matches to list (0 = all) */
+    limit?: number;
+}
 /** Options for A11y describe command */
 export type A11yDescribeCommandOptions = BaseOptions;
 /** Options for CDP command */
@@ -229,11 +274,19 @@ export type NetworkHeadersCommandOptions = BaseOptions & {
 };
 /**
  * Options for session start command.
- * Used by startSessionViaDaemon in startHelpers.ts.
+ *
+ * CLI-layer shape: fields are "required-with-undefined" (`| undefined`) to
+ * match what Commander parsing produces. Maps to the canonical
+ * `SessionOptions` (IPC shape) via `filterDefined` in
+ * `startSessionViaDaemon`, which strips undefined keys.
+ *
+ * Kept as its own interface (not `extends SessionOptions`) because
+ * `exactOptionalPropertyTypes: true` treats `?: T` and `: T | undefined` as
+ * incompatible assignability-wise, and the CLI produces the latter.
  */
 export interface SessionStartOptions {
-    /** CDP port number */
-    port: number;
+    /** CDP port number (undefined = auto-select) */
+    port: number | undefined;
     /** Auto-stop timeout in seconds */
     timeout: number | undefined;
     /** Custom Chrome user data directory */
@@ -242,19 +295,23 @@ export interface SessionStartOptions {
     includeAll: boolean;
     /** Maximum response body size in MB */
     maxBodySize: number | undefined;
-    /** Use compact JSON output */
-    compact: boolean;
     /** Launch Chrome in headless mode */
     headless: boolean;
     /** Connect to existing Chrome instance via WebSocket URL */
     chromeWsUrl: string | undefined;
     /** Quiet mode - minimal output for AI agents */
     quiet: boolean;
+    /** Print the result as a JSON envelope */
+    json?: boolean | undefined;
     /** Custom Chrome flags (e.g., ['--ignore-certificate-errors']) */
     chromeFlags: string[] | undefined;
+    /** Viewport size to emulate (`--viewport`) */
+    viewport?: ViewportSize | undefined;
+    /** `prefers-color-scheme` to emulate (`--color-scheme`) */
+    colorScheme?: ColorScheme | undefined;
 }
 export type { ConsoleLevel } from '../../types.js';
-import type { ConsoleLevel } from '../../types.js';
+import type { ColorScheme, ConsoleLevel, ViewportSize } from '../../types.js';
 /**
  * Options for console command.
  * Supports smart summary (default), list view (--list), and streaming (--follow).
@@ -281,8 +338,6 @@ export interface PreviewDisplayOptions {
     network?: boolean;
     /** Show only console messages */
     console?: boolean;
-    /** Show DOM/A11y tree data */
-    dom?: boolean;
     /** Use verbose output with full URLs and formatting */
     verbose?: boolean;
     /** Watch for updates (like tail -f) */
@@ -302,7 +357,7 @@ export interface PeekCommandOptions extends BaseOptions, PreviewDisplayOptions {
  * Options for tail command.
  * Includes preview options plus last count and update interval.
  */
-export interface TailCommandOptions extends BaseOptions, Omit<PreviewDisplayOptions, 'dom' | 'follow'> {
+export interface TailCommandOptions extends BaseOptions, Omit<PreviewDisplayOptions, 'follow'> {
     /** Show last N items (string from CLI, default: 10) */
     last?: string;
     /** Update interval in milliseconds (string from CLI, default: 1000) */

package/dist/commands/shared/outputFile.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Writing files the user asked for (screenshots, HAR exports), with errors
+ * that name their path and say what is wrong with it.
+ */
+import { CommandError } from '../../errors/index.js';
+/**
+ * A file-system error as a user-facing error about the given path.
+ *
+ * @param filePath - Path the user gave
+ * @param error - Error from the file system
+ * @param extension - Extension of the file kind, for the example
+ * @returns Command error (81 bad path, 82 not permitted, 103 disk problem)
+ */
+export declare function outputPathError(filePath: string, error: unknown, extension?: string): CommandError;
+/**
+ * Reject an empty path or one that names a directory.
+ *
+ * @param filePath - Path the user gave
+ * @param extension - Extension of the file kind, for examples in errors
+ * @throws CommandError (81) when the path cannot be a file
+ */
+export declare function assertFilePath(filePath: string, extension?: string): void;
+/**
+ * Write a file atomically, creating its directory if needed.
+ *
+ * @param filePath - Path the user gave
+ * @param data - File contents
+ * @param extension - Extension of the file kind, for examples in errors
+ * @returns Absolute path written
+ * @throws CommandError naming the path when it cannot be written
+ */
+export declare function writeOutputFile(filePath: string, data: string | Buffer, extension?: string): Promise<string>;
+//# sourceMappingURL=outputFile.d.ts.map

package/dist/commands/shared/outputFile.js

@@ -0,0 +1,78 @@
+/**
+ * Writing files the user asked for (screenshots, HAR exports), with errors
+ * that name their path and say what is wrong with it.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { CommandError } from '../../errors/index.js';
+import { emptyOutputPathError, outputFileError } from '../../errors/messages.js';
+import { AtomicFileWriter } from '../../utils/atomicFile.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+/** What went wrong with a path, by error code */
+const PATH_PROBLEMS = {
+    EACCES: { reason: 'permission denied', exitCode: EXIT_CODES.PERMISSION_DENIED },
+    EPERM: { reason: 'operation not permitted', exitCode: EXIT_CODES.PERMISSION_DENIED },
+    EROFS: { reason: 'read-only file system', exitCode: EXIT_CODES.PERMISSION_DENIED },
+    EISDIR: { reason: 'it is a directory', exitCode: EXIT_CODES.INVALID_ARGUMENTS },
+    ENOTDIR: { reason: 'a part of the path is a file', exitCode: EXIT_CODES.INVALID_ARGUMENTS },
+    EEXIST: { reason: 'a part of the path is a file', exitCode: EXIT_CODES.INVALID_ARGUMENTS },
+    ENAMETOOLONG: { reason: 'the name is too long', exitCode: EXIT_CODES.INVALID_ARGUMENTS },
+    ENOENT: { reason: 'the directory cannot be created', exitCode: EXIT_CODES.INVALID_ARGUMENTS },
+    ENOSPC: { reason: 'no space left on the device', exitCode: EXIT_CODES.SESSION_FILE_ERROR },
+};
+/**
+ * A file-system error as a user-facing error about the given path.
+ *
+ * @param filePath - Path the user gave
+ * @param error - Error from the file system
+ * @param extension - Extension of the file kind, for the example
+ * @returns Command error (81 bad path, 82 not permitted, 103 disk problem)
+ */
+export function outputPathError(filePath, error, extension) {
+    const code = error.code ?? '';
+    const problem = PATH_PROBLEMS[code];
+    const reason = problem?.reason ?? (error instanceof Error ? error.message : String(error));
+    const err = outputFileError(filePath, reason, extension);
+    return new CommandError(err.message, { suggestion: err.suggestion }, problem?.exitCode ?? EXIT_CODES.SESSION_FILE_ERROR);
+}
+/**
+ * Reject an empty path or one that names a directory.
+ *
+ * @param filePath - Path the user gave
+ * @param extension - Extension of the file kind, for examples in errors
+ * @throws CommandError (81) when the path cannot be a file
+ */
+export function assertFilePath(filePath, extension) {
+    if (!filePath.trim()) {
+        const err = emptyOutputPathError(extension);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
+        throw outputPathError(filePath, Object.assign(new Error('directory'), { code: 'EISDIR' }), extension);
+    }
+}
+/**
+ * Write a file atomically, creating its directory if needed.
+ *
+ * @param filePath - Path the user gave
+ * @param data - File contents
+ * @param extension - Extension of the file kind, for examples in errors
+ * @returns Absolute path written
+ * @throws CommandError naming the path when it cannot be written
+ */
+export async function writeOutputFile(filePath, data, extension) {
+    assertFilePath(filePath, extension);
+    const absolutePath = path.resolve(filePath);
+    try {
+        fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+        if (typeof data === 'string')
+            await AtomicFileWriter.writeAsync(absolutePath, data);
+        else
+            await AtomicFileWriter.writeBufferAsync(absolutePath, data);
+    }
+    catch (error) {
+        throw outputPathError(filePath, error, extension);
+    }
+    return absolutePath;
+}
+//# sourceMappingURL=outputFile.js.map

package/dist/commands/shared/startHelpers.d.ts

@@ -4,20 +4,17 @@
  * Command-specific logic for the `bdg start` command.
  * Handles IPC communication with daemon to start browser sessions.
  */
-import type { SessionStartOptions } from '../../commands/shared/optionTypes.js';
+import type { SessionStartOptions } from './optionTypes.js';
 import type { TelemetryType } from '../../types.js';
 /**
- * Start a session via the daemon using IPC.
+ * Start a session via the daemon and report the result.
  *
- * This replaces the in-process sessionController.startSession() by:
- * 1. Sending a start_session_request to the daemon
- * 2. Waiting for the worker to launch and report readiness
- * 3. Outputting metadata about the running session
- * 4. Keeping the process alive while the session runs
+ * Spawns the daemon if needed, sends `start_session_request`, then prints the
+ * result as a JSON envelope (`--json`) or human-readable text, and exits.
  *
  * @param url - Target URL to navigate to
  * @param options - Session configuration options
  * @param telemetry - Array of telemetry types to enable
  */
-export declare function startSessionViaDaemon(url: string, options: SessionStartOptions, telemetry: TelemetryType[]): Promise<void>;
+export declare function startSessionViaDaemon(url: string, options: SessionStartOptions, telemetry: TelemetryType[]): Promise<never>;
 //# sourceMappingURL=startHelpers.d.ts.map