browser-debugger-cli 0.6.0 → 0.6.2

package/dist/utils/atomicFile.d.ts

@@ -2,14 +2,24 @@
  * Atomic file operations using tmp-file-then-rename pattern.
  *
  * Provides safe file writing that prevents corruption from interrupted writes
- * or concurrent access by using a temporary file and atomic rename operation.
+ * or concurrent access by using unique temporary files and atomic rename operation.
  */
 export declare class AtomicFileWriter {
+    /**
+     * Generate a unique temporary file path.
+     *
+     * Uses process PID and random UUID to ensure uniqueness across concurrent processes.
+     *
+     * @param filePath - Target file path
+     * @returns Unique temporary file path
+     */
+    private static getTempPath;
     /**
      * Write data to a file atomically (synchronous).
      *
-     * Creates a temporary file, writes the data, then atomically renames it to the target path.
-     * This ensures the target file is never in a partially written state.
+     * Creates a unique temporary file, writes the data, then atomically renames it to the target path.
+     * This ensures the target file is never in a partially written state and prevents corruption
+     * from concurrent writes by different processes.
      *
      * @param filePath - Target file path
      * @param data - Data to write
@@ -22,8 +32,9 @@ export declare class AtomicFileWriter {
     /**
      * Write data to a file atomically (asynchronous).
      *
-     * Creates a temporary file, writes the data, then atomically renames it to the target path.
-     * This ensures the target file is never in a partially written state.
+     * Creates a unique temporary file, writes the data, then atomically renames it to the target path.
+     * This ensures the target file is never in a partially written state and prevents corruption
+     * from concurrent writes by different processes.
      *
      * @param filePath - Target file path
      * @param data - Data to write
@@ -34,5 +45,20 @@ export declare class AtomicFileWriter {
     static writeAsync(filePath: string, data: string, options?: {
         encoding?: BufferEncoding;
     }): Promise<void>;
+    /**
+     * Write binary data (Buffer) to a file atomically (asynchronous).
+     *
+     * Creates a unique temporary file, writes the binary data, then atomically renames it to the target path.
+     * This ensures the target file is never in a partially written state and prevents corruption
+     * from concurrent writes by different processes.
+     *
+     * Useful for screenshots, images, and other binary file exports.
+     *
+     * @param filePath - Target file path
+     * @param buffer - Binary data to write
+     * @returns Promise that resolves when write completes
+     * @throws Error if write operation fails
+     */
+    static writeBufferAsync(filePath: string, buffer: Buffer): Promise<void>;
 }
 //# sourceMappingURL=atomicFile.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"atomicFile.d.ts","sourceRoot":"","sources":["../../src/utils/atomicFile.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,SAAS,CACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAO,GAC1C,IAAI;IAoBP;;;;;;;;;;;OAWG;WACU,UAAU,CACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAO,GAC1C,OAAO,CAAC,IAAI,CAAC;CAmBjB"}
+{"version":3,"file":"atomicFile.d.ts","sourceRoot":"","sources":["../../src/utils/atomicFile.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAK1B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,SAAS,CACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAO,GAC1C,IAAI;IAgBP;;;;;;;;;;;;OAYG;WACU,UAAU,CACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAO,GAC1C,OAAO,CAAC,IAAI,CAAC;IAgBhB;;;;;;;;;;;;;OAaG;WACU,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAe/E"}

package/dist/utils/atomicFile.js

@@ -1,16 +1,30 @@
+import * as crypto from 'crypto';
 import * as fs from 'fs';
 /**
  * Atomic file operations using tmp-file-then-rename pattern.
  *
  * Provides safe file writing that prevents corruption from interrupted writes
- * or concurrent access by using a temporary file and atomic rename operation.
+ * or concurrent access by using unique temporary files and atomic rename operation.
  */
 export class AtomicFileWriter {
+    /**
+     * Generate a unique temporary file path.
+     *
+     * Uses process PID and random UUID to ensure uniqueness across concurrent processes.
+     *
+     * @param filePath - Target file path
+     * @returns Unique temporary file path
+     */
+    static getTempPath(filePath) {
+        const uuid = crypto.randomUUID();
+        return `${filePath}.${process.pid}.${uuid}.tmp`;
+    }
     /**
      * Write data to a file atomically (synchronous).
      *
-     * Creates a temporary file, writes the data, then atomically renames it to the target path.
-     * This ensures the target file is never in a partially written state.
+     * Creates a unique temporary file, writes the data, then atomically renames it to the target path.
+     * This ensures the target file is never in a partially written state and prevents corruption
+     * from concurrent writes by different processes.
      *
      * @param filePath - Target file path
      * @param data - Data to write
@@ -18,15 +32,12 @@ export class AtomicFileWriter {
      * @throws Error if write operation fails
      */
     static writeSync(filePath, data, options = {}) {
-        const tmpPath = filePath + '.tmp';
+        const tmpPath = this.getTempPath(filePath);
         try {
-            // Write to temporary file first
             fs.writeFileSync(tmpPath, data, { encoding: options.encoding ?? 'utf-8' });
-            // Atomically rename to target path
             fs.renameSync(tmpPath, filePath);
         }
         catch (error) {
-            // Clean up temporary file on error
             try {
                 fs.unlinkSync(tmpPath);
             }
@@ -39,8 +50,9 @@ export class AtomicFileWriter {
     /**
      * Write data to a file atomically (asynchronous).
      *
-     * Creates a temporary file, writes the data, then atomically renames it to the target path.
-     * This ensures the target file is never in a partially written state.
+     * Creates a unique temporary file, writes the data, then atomically renames it to the target path.
+     * This ensures the target file is never in a partially written state and prevents corruption
+     * from concurrent writes by different processes.
      *
      * @param filePath - Target file path
      * @param data - Data to write
@@ -49,15 +61,42 @@ export class AtomicFileWriter {
      * @throws Error if write operation fails
      */
     static async writeAsync(filePath, data, options = {}) {
-        const tmpPath = filePath + '.tmp';
+        const tmpPath = this.getTempPath(filePath);
         try {
-            // Write to temporary file first
             await fs.promises.writeFile(tmpPath, data, { encoding: options.encoding ?? 'utf-8' });
-            // Atomically rename to target path
             await fs.promises.rename(tmpPath, filePath);
         }
         catch (error) {
-            // Clean up temporary file on error
+            try {
+                await fs.promises.unlink(tmpPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            throw error;
+        }
+    }
+    /**
+     * Write binary data (Buffer) to a file atomically (asynchronous).
+     *
+     * Creates a unique temporary file, writes the binary data, then atomically renames it to the target path.
+     * This ensures the target file is never in a partially written state and prevents corruption
+     * from concurrent writes by different processes.
+     *
+     * Useful for screenshots, images, and other binary file exports.
+     *
+     * @param filePath - Target file path
+     * @param buffer - Binary data to write
+     * @returns Promise that resolves when write completes
+     * @throws Error if write operation fails
+     */
+    static async writeBufferAsync(filePath, buffer) {
+        const tmpPath = this.getTempPath(filePath);
+        try {
+            await fs.promises.writeFile(tmpPath, buffer);
+            await fs.promises.rename(tmpPath, filePath);
+        }
+        catch (error) {
             try {
                 await fs.promises.unlink(tmpPath);
             }

package/dist/utils/atomicFile.js.map

@@ -1 +1 @@
-{"version":3,"file":"atomicFile.js","sourceRoot":"","sources":["../../src/utils/atomicFile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAEzB;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IAC3B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,SAAS,CACd,QAAgB,EAChB,IAAY,EACZ,UAAyC,EAAE;QAE3C,MAAM,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;QAElC,IAAI,CAAC;YACH,gCAAgC;YAChC,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,OAAO,EAAE,CAAC,CAAC;YAE3E,mCAAmC;YACnC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACnC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,mCAAmC;YACnC,IAAI,CAAC;gBACH,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YACzB,CAAC;YAAC,MAAM,CAAC;gBACP,wBAAwB;YAC1B,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,KAAK,CAAC,UAAU,CACrB,QAAgB,EAChB,IAAY,EACZ,UAAyC,EAAE;QAE3C,MAAM,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;QAElC,IAAI,CAAC;YACH,gCAAgC;YAChC,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,OAAO,EAAE,CAAC,CAAC;YAEtF,mCAAmC;YACnC,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,mCAAmC;YACnC,IAAI,CAAC;gBACH,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACpC,CAAC;YAAC,MAAM,CAAC;gBACP,wBAAwB;YAC1B,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"atomicFile.js","sourceRoot":"","sources":["../../src/utils/atomicFile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAEzB;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IAC3B;;;;;;;OAOG;IACK,MAAM,CAAC,WAAW,CAAC,QAAgB;QACzC,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;QACjC,OAAO,GAAG,QAAQ,IAAI,OAAO,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC;IAClD,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,SAAS,CACd,QAAgB,EAChB,IAAY,EACZ,UAAyC,EAAE;QAE3C,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAE3C,IAAI,CAAC;YACH,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,OAAO,EAAE,CAAC,CAAC;YAC3E,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACnC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC;gBACH,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YACzB,CAAC;YAAC,MAAM,CAAC;gBACP,wBAAwB;YAC1B,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,KAAK,CAAC,UAAU,CACrB,QAAgB,EAChB,IAAY,EACZ,UAAyC,EAAE;QAE3C,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAE3C,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,OAAO,EAAE,CAAC,CAAC;YACtF,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC;gBACH,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACpC,CAAC;YAAC,MAAM,CAAC;gBACP,wBAAwB;YAC1B,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,QAAgB,EAAE,MAAc;QAC5D,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAE3C,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC7C,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC;gBACH,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACpC,CAAC;YAAC,MAAM,CAAC;gBACP,wBAAwB;YAC1B,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

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"}