browser-debugger-cli 0.7.1 → 0.8.0

package/dist/commands/shared/commonOptions.js

@@ -22,4 +22,16 @@ import { Option } from 'commander';
 export function jsonOption() {
     return new Option('-j, --json', 'Output as JSON').default(false);
 }
+/**
+ * `--network` together with `--console` asks for both sections, which is what
+ * neither flag shows; clear both so the output is not empty.
+ *
+ * @param options - Parsed `peek`/`tail` options (changed in place)
+ */
+export function showBothSectionsWhenBothRequested(options) {
+    if (options.network && options.console) {
+        options.network = false;
+        options.console = false;
+    }
+}
 //# sourceMappingURL=commonOptions.js.map

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

@@ -19,9 +19,18 @@ export interface DaemonErrorResult {
     /** Exit code to use if exiting */
     exitCode?: number;
 }
+/**
+ * Record that a follow-mode refresh reached the session, so a later loss is
+ * reported (once) and retried, not treated as "no session to follow".
+ */
+export declare function noteFollowConnected(): void;
 /**
  * Handle daemon connection errors with consistent formatting and behavior.
  *
+ * Outside follow mode the command exits. In follow mode, a session that never
+ * answered exits too (there is nothing to follow, exit 83); a session that
+ * goes away is reported once and retried until a new one starts.
+ *
  * @param error - Error message to display
  * @param options - Error handling options
  * @returns Result indicating whether to exit

package/dist/commands/shared/daemonErrorHandler.js

@@ -1,32 +1,52 @@
 /**
  * Shared utilities for handling daemon connection errors in commands.
  */
+import { sessionUnavailableSuggestion } from '../../errors/messages.js';
+import { genericError } from '../../errors/messages.js';
 import { OutputBuilder } from '../../ui/OutputBuilder.js';
-import { genericError } from '../../ui/messages/errors.js';
 import { connectionLostRetryMessage, connectionLostStopHintMessage, } from '../../ui/messages/preview.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
+/** Follow-mode state: whether a session ever answered, and whether its loss was reported */
+const followState = { connected: false, lossReported: false };
+/**
+ * Record that a follow-mode refresh reached the session, so a later loss is
+ * reported (once) and retried, not treated as "no session to follow".
+ */
+export function noteFollowConnected() {
+    followState.connected = true;
+    followState.lossReported = false;
+}
 /**
  * Handle daemon connection errors with consistent formatting and behavior.
  *
+ * Outside follow mode the command exits. In follow mode, a session that never
+ * answered exits too (there is nothing to follow, exit 83); a session that
+ * goes away is reported once and retried until a new one starts.
+ *
  * @param error - Error message to display
  * @param options - Error handling options
  * @returns Result indicating whether to exit
  */
 export function handleDaemonConnectionError(error, options) {
     const { json = false, follow = false, retryIntervalMs = 1000, exitCode = EXIT_CODES.RESOURCE_NOT_FOUND, } = options;
-    const retryMessage = retryIntervalMs >= 1000 ? `${retryIntervalMs / 1000}s` : `${retryIntervalMs}ms`;
-    const timestamp = new Date().toISOString();
-    if (json) {
-        console.log(JSON.stringify(OutputBuilder.buildJsonError(error, { exitCode }), null, 2));
-    }
-    else {
-        console.error(genericError(error));
+    const exits = !follow || !followState.connected;
+    if (exits || !followState.lossReported) {
+        if (json) {
+            const suggestion = exits ? sessionUnavailableSuggestion(exitCode) : undefined;
+            console.log(JSON.stringify(OutputBuilder.buildJsonError(error, { exitCode, ...(suggestion && { suggestion }) }), null, 2));
+        }
+        else {
+            console.error(genericError(error));
+        }
     }
-    if (!follow) {
+    if (exits)
         return { shouldExit: true, exitCode };
+    if (!followState.lossReported) {
+        const retryMessage = retryIntervalMs >= 1000 ? `${retryIntervalMs / 1000}s` : `${retryIntervalMs}ms`;
+        console.error(connectionLostRetryMessage(new Date().toISOString(), retryMessage));
+        console.error(connectionLostStopHintMessage());
+        followState.lossReported = true;
     }
-    console.error(connectionLostRetryMessage(timestamp, retryMessage));
-    console.error(connectionLostStopHintMessage());
     return { shouldExit: false };
 }
 //# sourceMappingURL=daemonErrorHandler.js.map

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

@@ -1,6 +1,7 @@
 /**
  * Shared data fetching utilities for commands that query daemon state.
  */
+import type { PeekSection } from '../../ipc/protocol/commands.js';
 import type { BdgOutput, ConsoleMessage, NetworkRequest } from '../../types.js';
 export type FetchSuccess<T> = {
     success: true;
@@ -10,6 +11,8 @@ export type FetchError = {
     success: false;
     error: string;
     exitCode: number;
+    /** What the user can do about it (default: start a session) */
+    suggestion?: string;
 };
 export type FetchResult<T> = FetchSuccess<T> | FetchError;
 interface PreviewData {
@@ -17,26 +20,46 @@ interface PreviewData {
     network: NetworkRequest[];
     console: ConsoleMessage[];
 }
+/** What to fetch from the daemon's preview. */
+export interface PreviewQuery {
+    /** Most recent items per section (0 = all; default: daemon default) */
+    lastN?: number;
+    /** Only network or only console items */
+    only?: PeekSection;
+    /** Include request/response headers in network items */
+    withHeaders?: boolean;
+}
 /**
  * Fetch raw preview output from daemon.
+ *
+ * @param query - Window, section and header options
+ * @returns Preview output or a fetch error
  */
-export declare function fetchPreviewOutput(lastN?: number): Promise<FetchResult<BdgOutput>>;
+export declare function fetchPreviewOutput(query?: PreviewQuery): Promise<FetchResult<BdgOutput>>;
 /**
  * Fetch preview data with parsed network and console arrays.
+ *
+ * @param query - Window, section and header options
+ * @returns Preview data or a fetch error
  */
-export declare function fetchPreviewData(lastN?: number): Promise<FetchResult<PreviewData>>;
-/**
- * Fetch network requests from daemon.
- */
-export declare function fetchNetworkRequests(): Promise<FetchResult<NetworkRequest[]>>;
+export declare function fetchPreviewData(query?: PreviewQuery): Promise<FetchResult<PreviewData>>;
 /**
- * Fetch console messages 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 declare function fetchConsoleMessages(): Promise<FetchResult<ConsoleMessage[]>>;
+export declare function fetchNetworkRequests(withHeaders?: boolean): Promise<FetchResult<NetworkRequest[]>>;
 /**
- * Create error result for daemon not running.
+ * Fetch all console messages from daemon.
+ *
+ * @returns Messages (with their session-wide index) and the navigation id of
+ *   the page currently loaded
  */
-export declare function createDaemonNotRunningError(): FetchError;
+export declare function fetchConsoleMessages(): Promise<FetchResult<{
+    messages: ConsoleMessage[];
+    currentNavigationId: number | undefined;
+}>>;
 interface ErrorResult {
     success: false;
     error: string;

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 { STOP_MESSAGES } from '../../ui/messages/session.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: STOP_MESSAGES.DAEMON_NOT_RUNNING,
+            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

@@ -14,8 +14,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 +24,6 @@ export interface FollowModeOptions {
  * - First refresh call (awaited)
  * - Periodic interval-based refresh
  * - SIGINT handler for graceful shutdown
- * - Optional EPIPE handling for piped output
  *
  * @param refreshFn - Async function to call on each refresh cycle
  * @param options - Configuration options for follow mode

package/dist/commands/shared/followMode.js

@@ -4,6 +4,8 @@
  * Provides a unified pattern for commands that continuously poll
  * and display updates (like tail -f behavior).
  */
+import { genericError } from '../../errors/messages.js';
+import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /**
  * Sets up follow mode with periodic refresh and graceful shutdown.
@@ -14,7 +16,6 @@ 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
  *
  * @param refreshFn - Async function to call on each refresh cycle
  * @param options - Configuration options for follow mode
@@ -35,24 +36,18 @@ 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;
     console.error(startMessage());
     await refreshFn();
     const intervalId = setInterval(() => {
-        void refreshFn();
+        refreshFn().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 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,39 @@
+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 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);
+    }
+    console.error(genericError(error instanceof Error ? error.message : String(error)));
+    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+}
+//# sourceMappingURL=handleValidationError.js.map

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

@@ -23,6 +23,8 @@
 export interface BaseOptions {
     /** Output as JSON instead of human-readable format */
     json?: boolean;
+    /** Hide tips and hints (`-q`, accepted by every command) */
+    quiet?: boolean;
 }
 /**
  * Options for commands with verbose output.
@@ -109,14 +111,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.
  */
@@ -148,7 +142,17 @@ export type DomGetCommandOptions = BaseOptions & RawOptions & SelectionOptions;
 /** 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 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 +170,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,6 +214,13 @@ 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) */
+    type?: string[];
+}
 /** Options for A11y tree command */
 export type A11yTreeCommandOptions = BaseOptions;
 /** Options for A11y query command */
@@ -229,11 +243,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,14 +264,14 @@ 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;
 }
@@ -281,8 +303,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 +322,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