browser-debugger-cli 0.6.0 → 0.6.1

package/dist/utils/concurrency.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Custom concurrency limiter for controlling parallel async operations.
+ */
+/**
+ * Limits the number of concurrent async operations.
+ *
+ * @example
+ * ```typescript
+ * const limiter = new ConcurrencyLimiter(5);
+ * const results = await Promise.all(
+ *   tasks.map(task => limiter.run(() => performTask(task)))
+ * );
+ * ```
+ */
+export declare class ConcurrencyLimiter {
+    private readonly limit;
+    private running;
+    private queue;
+    /**
+     * Creates a new concurrency limiter.
+     *
+     * @param limit - Maximum number of concurrent operations
+     */
+    constructor(limit: number);
+    /**
+     * Executes an async function with concurrency control.
+     *
+     * @param fn - Async function to execute
+     * @returns Promise resolving to the function's result
+     *
+     * @example
+     * ```typescript
+     * const limiter = new ConcurrencyLimiter(3);
+     * const result = await limiter.run(async () => {
+     *   const response = await fetch(url);
+     *   return response.json();
+     * });
+     * ```
+     */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Gets the current number of running operations.
+     *
+     * @returns Number of currently executing operations
+     */
+    getRunningCount(): number;
+    /**
+     * Gets the current queue size.
+     *
+     * @returns Number of operations waiting to execute
+     */
+    getQueueSize(): number;
+}
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/utils/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../../src/utils/concurrency.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;GAUG;AACH,qBAAa,kBAAkB;IASjB,OAAO,CAAC,QAAQ,CAAC,KAAK;IARlC,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,KAAK,CAAyB;IAEtC;;;;OAIG;gBAC0B,KAAK,EAAE,MAAM;IAM1C;;;;;;;;;;;;;;OAcG;IACG,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAiB9C;;;;OAIG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;OAIG;IACH,YAAY,IAAI,MAAM;CAGvB"}

package/dist/utils/concurrency.js

@@ -0,0 +1,78 @@
+/**
+ * Custom concurrency limiter for controlling parallel async operations.
+ */
+/**
+ * Limits the number of concurrent async operations.
+ *
+ * @example
+ * ```typescript
+ * const limiter = new ConcurrencyLimiter(5);
+ * const results = await Promise.all(
+ *   tasks.map(task => limiter.run(() => performTask(task)))
+ * );
+ * ```
+ */
+export class ConcurrencyLimiter {
+    limit;
+    running = 0;
+    queue = [];
+    /**
+     * Creates a new concurrency limiter.
+     *
+     * @param limit - Maximum number of concurrent operations
+     */
+    constructor(limit) {
+        this.limit = limit;
+        if (limit < 1) {
+            throw new Error('Concurrency limit must be at least 1');
+        }
+    }
+    /**
+     * Executes an async function with concurrency control.
+     *
+     * @param fn - Async function to execute
+     * @returns Promise resolving to the function's result
+     *
+     * @example
+     * ```typescript
+     * const limiter = new ConcurrencyLimiter(3);
+     * const result = await limiter.run(async () => {
+     *   const response = await fetch(url);
+     *   return response.json();
+     * });
+     * ```
+     */
+    async run(fn) {
+        while (this.running >= this.limit) {
+            await new Promise((resolve) => this.queue.push(resolve));
+        }
+        this.running++;
+        try {
+            return await fn();
+        }
+        finally {
+            this.running--;
+            const next = this.queue.shift();
+            if (next) {
+                next();
+            }
+        }
+    }
+    /**
+     * Gets the current number of running operations.
+     *
+     * @returns Number of currently executing operations
+     */
+    getRunningCount() {
+        return this.running;
+    }
+    /**
+     * Gets the current queue size.
+     *
+     * @returns Number of operations waiting to execute
+     */
+    getQueueSize() {
+        return this.queue.length;
+    }
+}
+//# sourceMappingURL=concurrency.js.map

package/dist/utils/concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../../src/utils/concurrency.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,OAAO,kBAAkB;IASA;IARrB,OAAO,GAAG,CAAC,CAAC;IACZ,KAAK,GAAsB,EAAE,CAAC;IAEtC;;;;OAIG;IACH,YAA6B,KAAa;QAAb,UAAK,GAAL,KAAK,CAAQ;QACxC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,GAAG,CAAI,EAAoB;QAC/B,OAAO,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAClC,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QACjE,CAAC;QAED,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YAChC,IAAI,IAAI,EAAE,CAAC;gBACT,IAAI,EAAE,CAAC;YACT,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,eAAe;QACb,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;CACF"}

package/dist/utils/daemonErrors.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared utilities for handling daemon connection errors in commands.
+ *
+ * Provides consistent error handling for peek, tail, and other commands
+ * that communicate with the daemon via IPC.
+ */
+/**
+ * Options for daemon connection error handling.
+ */
+export interface DaemonErrorOptions {
+    /** Use JSON output format */
+    json?: boolean | undefined;
+    /** Follow/watch mode (don't exit, show retry message) */
+    follow?: boolean | undefined;
+    /** Retry interval in milliseconds (for display message) */
+    retryIntervalMs?: number | undefined;
+    /** Custom exit code (defaults to RESOURCE_NOT_FOUND) */
+    exitCode?: number | undefined;
+}
+/**
+ * Result of handling a daemon connection error.
+ */
+export interface DaemonErrorResult {
+    /** Whether the process should exit */
+    shouldExit: boolean;
+    /** Exit code to use if exiting */
+    exitCode?: number;
+}
+/**
+ * Handle daemon connection errors with consistent formatting and behavior.
+ *
+ * Formats and logs the error appropriately based on output mode.
+ * Returns whether the caller should exit and with what code.
+ *
+ * @param error - Error message to display
+ * @param options - Error handling options
+ * @returns Result indicating whether to exit
+ *
+ * @example
+ * ```typescript
+ * // One-time command
+ * const result = handleDaemonConnectionError('Daemon not running', {
+ *   json: options.json,
+ *   exitCode: EXIT_CODES.RESOURCE_NOT_FOUND
+ * });
+ * if (result.shouldExit) {
+ *   process.exit(result.exitCode);
+ * }
+ *
+ * // Follow mode (retries)
+ * handleDaemonConnectionError('Connection lost', {
+ *   json: options.json,
+ *   follow: true,
+ *   retryIntervalMs: 1000
+ * });
+ * // Returns { shouldExit: false }
+ * ```
+ */
+export declare function handleDaemonConnectionError(error: string, options: DaemonErrorOptions): DaemonErrorResult;
+//# sourceMappingURL=daemonErrors.d.ts.map

package/dist/utils/daemonErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemonErrors.d.ts","sourceRoot":"","sources":["../../src/utils/daemonErrors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,UAAU,EAAE,OAAO,CAAC;IACpB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,kBAAkB,GAC1B,iBAAiB,CA0BnB"}

package/dist/utils/daemonErrors.js

@@ -0,0 +1,58 @@
+/**
+ * Shared utilities for handling daemon connection errors in commands.
+ *
+ * Provides consistent error handling for peek, tail, and other commands
+ * that communicate with the daemon via IPC.
+ */
+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';
+/**
+ * Handle daemon connection errors with consistent formatting and behavior.
+ *
+ * Formats and logs the error appropriately based on output mode.
+ * Returns whether the caller should exit and with what code.
+ *
+ * @param error - Error message to display
+ * @param options - Error handling options
+ * @returns Result indicating whether to exit
+ *
+ * @example
+ * ```typescript
+ * // One-time command
+ * const result = handleDaemonConnectionError('Daemon not running', {
+ *   json: options.json,
+ *   exitCode: EXIT_CODES.RESOURCE_NOT_FOUND
+ * });
+ * if (result.shouldExit) {
+ *   process.exit(result.exitCode);
+ * }
+ *
+ * // Follow mode (retries)
+ * handleDaemonConnectionError('Connection lost', {
+ *   json: options.json,
+ *   follow: true,
+ *   retryIntervalMs: 1000
+ * });
+ * // Returns { shouldExit: false }
+ * ```
+ */
+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));
+    }
+    if (!follow) {
+        return { shouldExit: true, exitCode };
+    }
+    console.error(connectionLostRetryMessage(timestamp, retryMessage));
+    console.error(connectionLostStopHintMessage());
+    return { shouldExit: false };
+}
+//# sourceMappingURL=daemonErrors.js.map

package/dist/utils/daemonErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemonErrors.js","sourceRoot":"","sources":["../../src/utils/daemonErrors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,GAC9B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AA0BlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,2BAA2B,CACzC,KAAa,EACb,OAA2B;IAE3B,MAAM,EACJ,IAAI,GAAG,KAAK,EACZ,MAAM,GAAG,KAAK,EACd,eAAe,GAAG,IAAI,EACtB,QAAQ,GAAG,UAAU,CAAC,kBAAkB,GACzC,GAAG,OAAO,CAAC;IAEZ,MAAM,YAAY,GAChB,eAAe,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,eAAe,IAAI,CAAC;IAElF,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAE3C,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,cAAc,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1F,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IACrC,CAAC;IAED,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACxC,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,0BAA0B,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;IACnE,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AAC/B,CAAC"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Error handling utilities.
+ *
+ * Pure utility functions for error message extraction.
+ */
+/**
+ * Extract error message from unknown error type.
+ *
+ * Safely extracts error messages from various error types:
+ * - Error instances → error.message
+ * - Unknown types → String(error)
+ *
+ * Useful for error handling when error type is unknown.
+ *
+ * @param error - Error of unknown type
+ * @returns Error message string
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await someOperation();
+ * } catch (error) {
+ *   console.error(`Failed: ${getErrorMessage(error)}`);
+ * }
+ * ```
+ */
+export declare function getErrorMessage(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKtD"}

package/dist/utils/errors.js

@@ -0,0 +1,33 @@
+/**
+ * Error handling utilities.
+ *
+ * Pure utility functions for error message extraction.
+ */
+/**
+ * Extract error message from unknown error type.
+ *
+ * Safely extracts error messages from various error types:
+ * - Error instances → error.message
+ * - Unknown types → String(error)
+ *
+ * Useful for error handling when error type is unknown.
+ *
+ * @param error - Error of unknown type
+ * @returns Error message string
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await someOperation();
+ * } catch (error) {
+ *   console.error(`Failed: ${getErrorMessage(error)}`);
+ * }
+ * ```
+ */
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC"}

package/dist/utils/exitCodes.d.ts

@@ -1,32 +1,68 @@
 /**
  * Semantic exit codes for agent-friendly error handling.
  *
- * Based on Square Engineering's semantic exit code system:
- * - 0: Success
- * - 1: Generic failure (backward compatibility)
- * - 80-99: User errors (invalid input, permissions, resource issues)
- * - 100-119: Software errors (bugs, integration failures, timeouts)
+ * **STABILITY: These exit codes are part of bdg's stable public API.**
+ *
+ * Exit codes follow semantic ranges for predictable automation:
+ * - **0**: Success (command completed successfully)
+ * - **1**: Generic failure (backward compatibility, avoid in new code)
+ * - **80-99**: User errors (invalid input, permissions, resource issues)
+ * - **100-119**: Software errors (bugs, integration failures, timeouts)
+ *
+ * **Versioning guarantees:**
+ * - Exit code values are **stable** and will not change in minor versions
+ * - New exit codes may be added in minor versions (within existing ranges)
+ * - Existing codes will only be removed in major versions with deprecation notice
+ * - Exit code semantics (meaning) will remain consistent across versions
+ *
+ * **For automation users:**
+ * - Check specific exit codes (e.g., 83 for "resource not found")
+ * - Use ranges for category detection (80-99 = user error, 100-119 = software error)
+ * - Exit code 0 guarantees success, non-zero indicates failure
+ *
+ * **Migration policy:**
+ * - Deprecated codes will be documented in CHANGELOG.md with migration path
+ * - Deprecated codes will remain functional for at least one major version
  *
  * Reference: https://developer.squareup.com/blog/command-line-observability-with-semantic-exit-codes/
  */
 /**
  * Exit code constants following semantic ranges.
+ *
+ * **These values are stable API** - use confidently in automation scripts.
  */
 export declare const EXIT_CODES: {
+    /** Command completed successfully */
     readonly SUCCESS: 0;
+    /** Generic failure (use specific codes when possible) */
     readonly GENERIC_FAILURE: 1;
+    /** Invalid URL format or unreachable URL */
     readonly INVALID_URL: 80;
+    /** Invalid command-line arguments or options */
     readonly INVALID_ARGUMENTS: 81;
+    /** Insufficient permissions for operation */
     readonly PERMISSION_DENIED: 82;
+    /** Requested resource not found (session, file, etc.) */
     readonly RESOURCE_NOT_FOUND: 83;
+    /** Resource already exists (duplicate session, etc.) */
     readonly RESOURCE_ALREADY_EXISTS: 84;
+    /** Resource is locked or busy */
     readonly RESOURCE_BUSY: 85;
+    /** Daemon already running when trying to start */
     readonly DAEMON_ALREADY_RUNNING: 86;
+    /** Chrome browser failed to launch */
     readonly CHROME_LAUNCH_FAILURE: 100;
+    /** CDP connection failed */
     readonly CDP_CONNECTION_FAILURE: 101;
+    /** CDP operation timed out */
     readonly CDP_TIMEOUT: 102;
+    /** Session file read/write error */
     readonly SESSION_FILE_ERROR: 103;
+    /** Unhandled exception in code */
     readonly UNHANDLED_EXCEPTION: 104;
+    /** Signal handler error */
     readonly SIGNAL_HANDLER_ERROR: 105;
+    /** Generic software error (use specific codes when possible) */
+    readonly SOFTWARE_ERROR: 110;
 };
 //# sourceMappingURL=exitCodes.d.ts.map

package/dist/utils/exitCodes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exitCodes.d.ts","sourceRoot":"","sources":["../../src/utils/exitCodes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;CAuBb,CAAC"}
+{"version":3,"file":"exitCodes.d.ts","sourceRoot":"","sources":["../../src/utils/exitCodes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;GAIG;AACH,eAAO,MAAM,UAAU;IACrB,qCAAqC;;IAGrC,yDAAyD;;IAKzD,4CAA4C;;IAG5C,gDAAgD;;IAGhD,6CAA6C;;IAG7C,yDAAyD;;IAGzD,wDAAwD;;IAGxD,iCAAiC;;IAGjC,kDAAkD;;IAKlD,sCAAsC;;IAGtC,4BAA4B;;IAG5B,8BAA8B;;IAG9B,oCAAoC;;IAGpC,kCAAkC;;IAGlC,2BAA2B;;IAG3B,gEAAgE;;CAExD,CAAC"}

package/dist/utils/exitCodes.js

@@ -1,36 +1,70 @@
 /**
  * Semantic exit codes for agent-friendly error handling.
  *
- * Based on Square Engineering's semantic exit code system:
- * - 0: Success
- * - 1: Generic failure (backward compatibility)
- * - 80-99: User errors (invalid input, permissions, resource issues)
- * - 100-119: Software errors (bugs, integration failures, timeouts)
+ * **STABILITY: These exit codes are part of bdg's stable public API.**
+ *
+ * Exit codes follow semantic ranges for predictable automation:
+ * - **0**: Success (command completed successfully)
+ * - **1**: Generic failure (backward compatibility, avoid in new code)
+ * - **80-99**: User errors (invalid input, permissions, resource issues)
+ * - **100-119**: Software errors (bugs, integration failures, timeouts)
+ *
+ * **Versioning guarantees:**
+ * - Exit code values are **stable** and will not change in minor versions
+ * - New exit codes may be added in minor versions (within existing ranges)
+ * - Existing codes will only be removed in major versions with deprecation notice
+ * - Exit code semantics (meaning) will remain consistent across versions
+ *
+ * **For automation users:**
+ * - Check specific exit codes (e.g., 83 for "resource not found")
+ * - Use ranges for category detection (80-99 = user error, 100-119 = software error)
+ * - Exit code 0 guarantees success, non-zero indicates failure
+ *
+ * **Migration policy:**
+ * - Deprecated codes will be documented in CHANGELOG.md with migration path
+ * - Deprecated codes will remain functional for at least one major version
  *
  * Reference: https://developer.squareup.com/blog/command-line-observability-with-semantic-exit-codes/
  */
 /**
  * Exit code constants following semantic ranges.
+ *
+ * **These values are stable API** - use confidently in automation scripts.
  */
 export const EXIT_CODES = {
-    // Success
+    /** Command completed successfully */
     SUCCESS: 0,
-    // Generic failure (backward compatibility)
+    /** Generic failure (use specific codes when possible) */
     GENERIC_FAILURE: 1,
-    // User errors (80-99)
+    // User Errors (80-99): Issues caused by user input or environment
+    /** Invalid URL format or unreachable URL */
     INVALID_URL: 80,
+    /** Invalid command-line arguments or options */
     INVALID_ARGUMENTS: 81,
+    /** Insufficient permissions for operation */
     PERMISSION_DENIED: 82,
+    /** Requested resource not found (session, file, etc.) */
     RESOURCE_NOT_FOUND: 83,
+    /** Resource already exists (duplicate session, etc.) */
     RESOURCE_ALREADY_EXISTS: 84,
+    /** Resource is locked or busy */
     RESOURCE_BUSY: 85,
+    /** Daemon already running when trying to start */
     DAEMON_ALREADY_RUNNING: 86,
-    // Software/Integration errors (100-119)
+    // Software Errors (100-119): Internal failures or integration issues
+    /** Chrome browser failed to launch */
     CHROME_LAUNCH_FAILURE: 100,
+    /** CDP connection failed */
     CDP_CONNECTION_FAILURE: 101,
+    /** CDP operation timed out */
     CDP_TIMEOUT: 102,
+    /** Session file read/write error */
     SESSION_FILE_ERROR: 103,
+    /** Unhandled exception in code */
     UNHANDLED_EXCEPTION: 104,
+    /** Signal handler error */
     SIGNAL_HANDLER_ERROR: 105,
+    /** Generic software error (use specific codes when possible) */
+    SOFTWARE_ERROR: 110,
 };
 //# sourceMappingURL=exitCodes.js.map

package/dist/utils/exitCodes.js.map

@@ -1 +1 @@
-{"version":3,"file":"exitCodes.js","sourceRoot":"","sources":["../../src/utils/exitCodes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,UAAU;IACV,OAAO,EAAE,CAAC;IAEV,2CAA2C;IAC3C,eAAe,EAAE,CAAC;IAElB,sBAAsB;IACtB,WAAW,EAAE,EAAE;IACf,iBAAiB,EAAE,EAAE;IACrB,iBAAiB,EAAE,EAAE;IACrB,kBAAkB,EAAE,EAAE;IACtB,uBAAuB,EAAE,EAAE;IAC3B,aAAa,EAAE,EAAE;IACjB,sBAAsB,EAAE,EAAE;IAE1B,wCAAwC;IACxC,qBAAqB,EAAE,GAAG;IAC1B,sBAAsB,EAAE,GAAG;IAC3B,WAAW,EAAE,GAAG;IAChB,kBAAkB,EAAE,GAAG;IACvB,mBAAmB,EAAE,GAAG;IACxB,oBAAoB,EAAE,GAAG;CACjB,CAAC"}
+{"version":3,"file":"exitCodes.js","sourceRoot":"","sources":["../../src/utils/exitCodes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,qCAAqC;IACrC,OAAO,EAAE,CAAC;IAEV,yDAAyD;IACzD,eAAe,EAAE,CAAC;IAElB,kEAAkE;IAElE,4CAA4C;IAC5C,WAAW,EAAE,EAAE;IAEf,gDAAgD;IAChD,iBAAiB,EAAE,EAAE;IAErB,6CAA6C;IAC7C,iBAAiB,EAAE,EAAE;IAErB,yDAAyD;IACzD,kBAAkB,EAAE,EAAE;IAEtB,wDAAwD;IACxD,uBAAuB,EAAE,EAAE;IAE3B,iCAAiC;IACjC,aAAa,EAAE,EAAE;IAEjB,kDAAkD;IAClD,sBAAsB,EAAE,EAAE;IAE1B,qEAAqE;IAErE,sCAAsC;IACtC,qBAAqB,EAAE,GAAG;IAE1B,4BAA4B;IAC5B,sBAAsB,EAAE,GAAG;IAE3B,8BAA8B;IAC9B,WAAW,EAAE,GAAG;IAEhB,oCAAoC;IACpC,kBAAkB,EAAE,GAAG;IAEvB,kCAAkC;IAClC,mBAAmB,EAAE,GAAG;IAExB,2BAA2B;IAC3B,oBAAoB,EAAE,GAAG;IAEzB,gEAAgE;IAChE,cAAc,EAAE,GAAG;CACX,CAAC"}

package/dist/utils/http.d.ts

@@ -1,4 +1,5 @@
 import type { CDPTarget } from '../types';
+import type { Logger } from '../ui/logging/index.js';
 /**
  * Fetch CDP targets from Chrome's HTTP API.
  *
@@ -7,14 +8,16 @@ import type { CDPTarget } from '../types';
  * scattered across the codebase.
  *
  * @param port - Chrome debugging port (defaults to centralized DEFAULT_CDP_PORT)
+ * @param logger - Optional logger for debug output
  * @returns Promise resolving to array of CDP targets, or empty array on error
  *
  * @remarks
  * - Uses HTTP_LOCALHOST constant for consistent host addressing
- * - Returns empty array rather than throwing on HTTP errors for easier consumption
- * - Network errors are silently handled - callers should validate results
+ * - Returns empty array on HTTP errors, but logs details for debugging
+ * - 5-second timeout prevents hanging when Chrome is unreachable
+ * - Network errors are logged to help diagnose Chrome connectivity issues
  */
-export declare function fetchCDPTargets(port?: number): Promise<CDPTarget[]>;
+export declare function fetchCDPTargets(port?: number, logger?: Logger): Promise<CDPTarget[]>;
 /**
  * Fetch specific CDP target by ID from Chrome's HTTP API.
  *
@@ -23,12 +26,14 @@ export declare function fetchCDPTargets(port?: number): Promise<CDPTarget[]>;
  *
  * @param targetId - Target ID to search for
  * @param port - Chrome debugging port (defaults to centralized DEFAULT_CDP_PORT)
+ * @param logger - Optional logger for debug output
  * @returns Promise resolving to matching target, or null if not found/error
  *
  * @remarks
  * - Returns null rather than throwing on errors for easier consumption
  * - Searches all targets returned by Chrome's /json/list endpoint
  * - Uses shared fetchCDPTargets helper to avoid code duplication
+ * - Inherits timeout and error logging from fetchCDPTargets
  */
-export declare function fetchCDPTargetById(targetId: string, port?: number): Promise<CDPTarget | null>;
+export declare function fetchCDPTargetById(targetId: string, port?: number, logger?: Logger): Promise<CDPTarget | null>;
 //# sourceMappingURL=http.d.ts.map

package/dist/utils/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/utils/http.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,IAAI,GAAE,MAAyB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAU3F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,MAAyB,GAC9B,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAG3B"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/utils/http.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAUpD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CACnC,IAAI,GAAE,MAAyB,EAC/B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,SAAS,EAAE,CAAC,CAuCtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,MAAyB,EAC/B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAG3B"}

package/dist/utils/http.js

@@ -1,4 +1,11 @@
 import { DEFAULT_CDP_PORT, HTTP_LOCALHOST } from '../constants.js';
+/**
+ * Timeout for CDP HTTP requests in milliseconds.
+ *
+ * Chrome's HTTP API should respond quickly when running.
+ * A 5-second timeout helps detect when Chrome is not responding.
+ */
+const CDP_HTTP_TIMEOUT_MS = 5000;
 /**
  * Fetch CDP targets from Chrome's HTTP API.
  *
@@ -7,22 +14,47 @@ import { DEFAULT_CDP_PORT, HTTP_LOCALHOST } from '../constants.js';
  * scattered across the codebase.
  *
  * @param port - Chrome debugging port (defaults to centralized DEFAULT_CDP_PORT)
+ * @param logger - Optional logger for debug output
  * @returns Promise resolving to array of CDP targets, or empty array on error
  *
  * @remarks
  * - Uses HTTP_LOCALHOST constant for consistent host addressing
- * - Returns empty array rather than throwing on HTTP errors for easier consumption
- * - Network errors are silently handled - callers should validate results
+ * - Returns empty array on HTTP errors, but logs details for debugging
+ * - 5-second timeout prevents hanging when Chrome is unreachable
+ * - Network errors are logged to help diagnose Chrome connectivity issues
  */
-export async function fetchCDPTargets(port = DEFAULT_CDP_PORT) {
+export async function fetchCDPTargets(port = DEFAULT_CDP_PORT, logger) {
+    const url = `http://${HTTP_LOCALHOST}:${port}/json/list`;
     try {
-        const response = await fetch(`http://${HTTP_LOCALHOST}:${port}/json/list`);
-        if (!response.ok) {
-            return [];
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), CDP_HTTP_TIMEOUT_MS);
+        try {
+            const response = await fetch(url, { signal: controller.signal });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                logger?.debug(`CDP HTTP request failed: ${response.status} ${response.statusText} (${url})`);
+                return [];
+            }
+            const data = await response.json();
+            if (!Array.isArray(data)) {
+                logger?.debug(`CDP HTTP response is not an array (${url})`);
+                return [];
+            }
+            return data;
+        }
+        finally {
+            clearTimeout(timeoutId);
         }
-        return (await response.json());
     }
-    catch {
+    catch (error) {
+        if (error instanceof Error) {
+            if (error.name === 'AbortError') {
+                logger?.debug(`CDP HTTP request timeout after ${CDP_HTTP_TIMEOUT_MS}ms (${url})`);
+            }
+            else {
+                logger?.debug(`CDP HTTP request error: ${error.message} (${url})`);
+            }
+        }
         return [];
     }
 }
@@ -34,15 +66,17 @@ export async function fetchCDPTargets(port = DEFAULT_CDP_PORT) {
  *
  * @param targetId - Target ID to search for
  * @param port - Chrome debugging port (defaults to centralized DEFAULT_CDP_PORT)
+ * @param logger - Optional logger for debug output
  * @returns Promise resolving to matching target, or null if not found/error
  *
  * @remarks
  * - Returns null rather than throwing on errors for easier consumption
  * - Searches all targets returned by Chrome's /json/list endpoint
  * - Uses shared fetchCDPTargets helper to avoid code duplication
+ * - Inherits timeout and error logging from fetchCDPTargets
  */
-export async function fetchCDPTargetById(targetId, port = DEFAULT_CDP_PORT) {
-    const targets = await fetchCDPTargets(port);
+export async function fetchCDPTargetById(targetId, port = DEFAULT_CDP_PORT, logger) {
+    const targets = await fetchCDPTargets(port, logger);
     return targets.find((t) => t.id === targetId) ?? null;
 }
 //# sourceMappingURL=http.js.map

package/dist/utils/http.js.map

@@ -1 +1 @@
-{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/utils/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGlE;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAAe,gBAAgB;IACnE,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,UAAU,cAAc,IAAI,IAAI,YAAY,CAAC,CAAC;QAC3E,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAgB,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAgB,EAChB,OAAe,gBAAgB;IAE/B,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAC5C,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,IAAI,IAAI,CAAC;AACxD,CAAC"}
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/utils/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAIlE;;;;;GAKG;AACH,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAEjC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAe,gBAAgB,EAC/B,MAAe;IAEf,MAAM,GAAG,GAAG,UAAU,cAAc,IAAI,IAAI,YAAY,CAAC;IAEzD,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,mBAAmB,CAAC,CAAC;QAE5E,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;YACjE,YAAY,CAAC,SAAS,CAAC,CAAC;YAExB,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,EAAE,KAAK,CACX,4BAA4B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,KAAK,GAAG,GAAG,CAC9E,CAAC;gBACF,OAAO,EAAE,CAAC;YACZ,CAAC;YAED,MAAM,IAAI,GAAY,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YAE5C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzB,MAAM,EAAE,KAAK,CAAC,sCAAsC,GAAG,GAAG,CAAC,CAAC;gBAC5D,OAAO,EAAE,CAAC;YACZ,CAAC;YAED,OAAO,IAAmB,CAAC;QAC7B,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,SAAS,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBAChC,MAAM,EAAE,KAAK,CAAC,kCAAkC,mBAAmB,OAAO,GAAG,GAAG,CAAC,CAAC;YACpF,CAAC;iBAAM,CAAC;gBACN,MAAM,EAAE,KAAK,CAAC,2BAA2B,KAAK,CAAC,OAAO,KAAK,GAAG,GAAG,CAAC,CAAC;YACrE,CAAC;QACH,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAgB,EAChB,OAAe,gBAAgB,EAC/B,MAAe;IAEf,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,IAAI,IAAI,CAAC;AACxD,CAAC"}