browser-debugger-cli 0.7.1 → 0.8.0

package/dist/daemon/launcher.js

@@ -1,132 +1,125 @@
 /**
- * Daemon Launcher - Spawns and manages the daemon process
+ * Daemon launcher.
  *
- * This module handles:
- * - Spawning the daemon worker process
- * - Waiting for the handshake to complete
- * - Capturing daemon logs
- * - Ensuring only one daemon runs at a time
+ * Spawns the daemon process for `bdg <url>` and waits until its socket accepts
+ * connections. Single-instance enforcement lives in the daemon itself (see
+ * SocketServer), so concurrent launches are safe: a losing daemon exits and
+ * the CLI talks to the winner.
  */
 import { spawn } from 'child_process';
 import fs from 'fs';
-import { dirname, join } from 'path';
-import { fileURLToPath } from 'url';
-import { DaemonStartupError } from '../daemon/errors.js';
-import { cleanupStaleSession } from '../session/cleanup.js';
-import { acquireDaemonLock, releaseDaemonLock } from '../session/lock.js';
+import { join } from 'path';
+import { DaemonStartupError, SessionDirError } from './errors.js';
+import { sessionDirIsFileError, sessionDirNotWritableError, socketPathTooLongError, } from '../errors/messages.js';
+import { isDaemonAlive } from '../session/daemonSocket.js';
 import { ensureSessionDir, getSessionDir, getSessionFilePath } from '../session/paths.js';
 import { createLogger } from '../ui/logging/index.js';
 import { delay } from '../utils/async.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
-import { isProcessAlive } from '../utils/process.js';
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+import { DAEMON_SCRIPT_PATH } from '../utils/packageRoot.js';
 const log = createLogger('launcher');
+const DAEMON_READY_TIMEOUT_MS = 5000;
+const DAEMON_READY_POLL_MS = 20;
 /**
- * Launch the daemon worker process.
+ * Ensure a daemon is running, spawning one if needed.
  *
- * This function:
- * 1. Acquires daemon lock atomically (prevents concurrent daemon starts)
- * 2. Cleans up any stale session files
- * 3. Checks if a daemon is already running
- * 4. Spawns the daemon worker
- * 5. Waits for it to become ready
- *
- * @returns The spawned child process
- * @throws Error if daemon fails to start or is already running
+ * @throws DaemonStartupError if the daemon script is missing or the daemon
+ *   does not accept connections in time
  */
 export async function launchDaemon() {
-    log.debug('Acquiring daemon lock...');
-    if (!acquireDaemonLock()) {
-        const error = new Error('Daemon startup already in progress. Wait a moment and try again.');
-        error.code = 'DAEMON_STARTUP_IN_PROGRESS';
-        error.exitCode = EXIT_CODES.DAEMON_ALREADY_RUNNING;
-        throw error;
+    if (await isDaemonAlive()) {
+        log.debug('Daemon already running');
+        return;
+    }
+    if (!fs.existsSync(DAEMON_SCRIPT_PATH)) {
+        throw new DaemonStartupError(`Daemon script not found at ${DAEMON_SCRIPT_PATH}. Did you run 'npm run build'?`, 'DAEMON_SCRIPT_NOT_FOUND');
+    }
+    assertUsableSessionDir();
+    const logPath = join(getSessionDir(), 'daemon.log');
+    rotateLog(logPath);
+    const logFd = fs.openSync(logPath, 'a');
+    log.debug(`Starting daemon: ${DAEMON_SCRIPT_PATH}`);
+    const daemon = spawn(process.execPath, [DAEMON_SCRIPT_PATH], {
+        detached: true,
+        stdio: ['ignore', logFd, logFd],
+    });
+    fs.closeSync(logFd);
+    let exited = false;
+    daemon.once('exit', () => {
+        exited = true;
+    });
+    daemon.unref();
+    await waitForDaemonReady(() => exited);
+}
+/** Longest Unix socket path (sun_path is 104 bytes on macOS, 108 on Linux, NUL included) */
+const MAX_SOCKET_PATH = process.platform === 'darwin' ? 103 : 107;
+/**
+ * Check that the session directory can hold the daemon's files before
+ * spawning it (otherwise the daemon dies and only its log says why).
+ *
+ * @throws SessionDirError (103) for a file or a too-long path, (82) when not writable
+ */
+export function assertUsableSessionDir() {
+    const dir = getSessionDir();
+    const fail = (err, exitCode) => {
+        throw new SessionDirError(err.message, err.suggestion, exitCode);
+    };
+    if (fs.existsSync(dir) && !fs.statSync(dir).isDirectory())
+        fail(sessionDirIsFileError(dir));
+    const socketPath = getSessionFilePath('DAEMON_SOCKET');
+    if (Buffer.byteLength(socketPath) > MAX_SOCKET_PATH) {
+        fail(socketPathTooLongError(socketPath, MAX_SOCKET_PATH));
     }
     try {
-        log.debug('Checking for stale session files...');
-        const cleaned = cleanupStaleSession();
-        if (cleaned) {
-            log.debug('Cleaned up stale session files');
-        }
-        const daemonPidPath = getSessionFilePath('DAEMON_PID');
-        if (fs.existsSync(daemonPidPath)) {
-            try {
-                const pidStr = fs.readFileSync(daemonPidPath, 'utf-8').trim();
-                const pid = parseInt(pidStr, 10);
-                if (!isNaN(pid) && isProcessAlive(pid)) {
-                    const error = new Error(`Daemon already running (PID ${pid}). Use 'bdg stop' to stop it.`);
-                    error.code = 'DAEMON_ALREADY_RUNNING';
-                    error.exitCode = EXIT_CODES.DAEMON_ALREADY_RUNNING;
-                    throw error;
-                }
-            }
-            catch (error) {
-                if (error instanceof Error &&
-                    'code' in error &&
-                    error.code === 'DAEMON_ALREADY_RUNNING') {
-                    throw error;
-                }
-            }
-        }
-        const daemonScriptPath = join(__dirname, '..', 'daemon.js');
-        if (!fs.existsSync(daemonScriptPath)) {
-            throw new DaemonStartupError(`Daemon script not found at ${daemonScriptPath}. Did you run 'npm run build'?`, 'DAEMON_SCRIPT_NOT_FOUND');
-        }
-        log.debug(`Starting daemon: ${daemonScriptPath}`);
-        // Ensure session directory exists and create log file for daemon output
         ensureSessionDir();
-        const logPath = join(getSessionDir(), 'daemon.log');
-        const logFd = fs.openSync(logPath, 'a');
-        const daemon = spawn(process.execPath, [daemonScriptPath], {
-            detached: true,
-            stdio: ['ignore', logFd, logFd], // Redirect stdout/stderr to log file
-            env: {
-                ...process.env,
-                BDG_DAEMON: '1', // Mark as daemon worker
-            },
-        });
-        // Close the fd in the parent process (child has its own copy)
-        fs.closeSync(logFd);
-        daemon.unref();
-        log.debug('Waiting for daemon to be ready...');
-        const socketPath = getSessionFilePath('DAEMON_SOCKET');
-        const maxWaitMs = 5000;
-        const startTime = Date.now();
-        while (Date.now() - startTime < maxWaitMs) {
-            if (fs.existsSync(socketPath)) {
-                log.debug('Daemon is ready');
-                return daemon;
-            }
-            await delay(100);
-        }
-        daemon.kill();
-        throw new DaemonStartupError('Daemon failed to start within 5 seconds', 'DAEMON_START_TIMEOUT');
+        fs.accessSync(dir, fs.constants.W_OK);
     }
     catch (error) {
-        releaseDaemonLock();
-        throw error;
+        const code = error.code;
+        const denied = code === 'EACCES' || code === 'EPERM' || code === 'EROFS';
+        fail(sessionDirNotWritableError(dir, code ?? getErrorMessage(error)), denied ? EXIT_CODES.PERMISSION_DENIED : EXIT_CODES.SESSION_FILE_ERROR);
     }
 }
+/** Size above which the daemon log is rotated when a daemon starts */
+const MAX_LOG_BYTES = 5 * 1024 * 1024;
 /**
- * Check if the daemon is currently running.
+ * Keep the daemon log from growing without bound: a log over
+ * {@link MAX_LOG_BYTES} becomes `daemon.log.1` (replacing an older one).
  *
- * @returns True if daemon is running, false otherwise
+ * @param logPath - Path of the daemon log
  */
-export function isDaemonRunning() {
-    const daemonPidPath = getSessionFilePath('DAEMON_PID');
-    if (!fs.existsSync(daemonPidPath)) {
-        return false;
-    }
+function rotateLog(logPath) {
     try {
-        const pidStr = fs.readFileSync(daemonPidPath, 'utf-8').trim();
-        const pid = parseInt(pidStr, 10);
-        return !isNaN(pid) && isProcessAlive(pid);
+        if (fs.statSync(logPath).size > MAX_LOG_BYTES) {
+            fs.renameSync(logPath, `${logPath}.1`);
+        }
     }
     catch (error) {
-        log.debug(`Failed to read daemon PID file: ${getErrorMessage(error)}`);
-        return false;
+        log.debug(`Daemon log not rotated: ${getErrorMessage(error)}`);
+    }
+}
+/**
+ * Poll the daemon socket until it accepts connections.
+ *
+ * A spawned daemon that exits early may have lost a single-instance race to
+ * another daemon; in that case the winner's socket satisfies the wait.
+ *
+ * @param hasExited - Whether the spawned daemon process has exited
+ * @throws DaemonStartupError if no daemon becomes reachable in time
+ */
+async function waitForDaemonReady(hasExited) {
+    const deadline = Date.now() + DAEMON_READY_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (await isDaemonAlive()) {
+            log.debug('Daemon is ready');
+            return;
+        }
+        if (hasExited() && !(await isDaemonAlive())) {
+            throw new DaemonStartupError(`Daemon exited during startup. See ${join(getSessionDir(), 'daemon.log')}`, 'DAEMON_EXITED');
+        }
+        await delay(DAEMON_READY_POLL_MS);
     }
+    throw new DaemonStartupError(`Daemon failed to start within ${DAEMON_READY_TIMEOUT_MS / 1000} seconds`, 'DAEMON_START_TIMEOUT');
 }
 //# sourceMappingURL=launcher.js.map

package/dist/daemon/messages.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Debug and diagnostic messages for the daemon process.
+ *
+ * User-facing debug output for internal operations. Context prefixes
+ * (e.g., [daemon], [session]) are added by the logger, not here.
+ *
+ * WHY: Avoids duplicate prefixes when used with createLogger().
+ */
+/**
+ * Generate telemetry module activation message.
+ *
+ * @param collectorName - Name of telemetry module being activated
+ * @returns Formatted debug message
+ */
+export declare function sessionActivatingCollector(collectorName: string): string;
+/**
+ * Generate all telemetry modules activated message.
+ *
+ * @param telemetry - Array of activated telemetry module names
+ * @returns Formatted debug message
+ */
+export declare function sessionCollectorsActivated(telemetry: string[]): string;
+/**
+ * Generate exiting due to Chrome connection loss message.
+ *
+ * @returns Formatted debug message
+ */
+export declare function sessionEndingConnectionLoss(): string;
+//# sourceMappingURL=messages.d.ts.map

package/dist/daemon/messages.js

@@ -0,0 +1,35 @@
+/**
+ * Debug and diagnostic messages for the daemon process.
+ *
+ * User-facing debug output for internal operations. Context prefixes
+ * (e.g., [daemon], [session]) are added by the logger, not here.
+ *
+ * WHY: Avoids duplicate prefixes when used with createLogger().
+ */
+/**
+ * Generate telemetry module activation message.
+ *
+ * @param collectorName - Name of telemetry module being activated
+ * @returns Formatted debug message
+ */
+export function sessionActivatingCollector(collectorName) {
+    return `Activating ${collectorName} telemetry`;
+}
+/**
+ * Generate all telemetry modules activated message.
+ *
+ * @param telemetry - Array of activated telemetry module names
+ * @returns Formatted debug message
+ */
+export function sessionCollectorsActivated(telemetry) {
+    return `All telemetry modules activated: ${telemetry.join(', ')}`;
+}
+/**
+ * Generate exiting due to Chrome connection loss message.
+ *
+ * @returns Formatted debug message
+ */
+export function sessionEndingConnectionLoss() {
+    return 'Ending session due to Chrome connection loss';
+}
+//# sourceMappingURL=messages.js.map

package/dist/daemon/patternDefinitions.d.ts

@@ -27,7 +27,7 @@ export declare const PATTERNS: PatternDefinition[];
 /**
  * Find patterns matching a CDP method.
  *
- * @param method - CDP method name (e.g., "Runtime.evaluate")
+ * @param method - CDP method name, matched case-insensitively (e.g., "Runtime.evaluate")
  * @returns Matching pattern definitions
  */
 export declare function findPatternsForMethod(method: string): PatternDefinition[];

package/dist/daemon/patternDefinitions.js

@@ -45,10 +45,11 @@ export const PATTERNS = [
 /**
  * Find patterns matching a CDP method.
  *
- * @param method - CDP method name (e.g., "Runtime.evaluate")
+ * @param method - CDP method name, matched case-insensitively (e.g., "Runtime.evaluate")
  * @returns Matching pattern definitions
  */
 export function findPatternsForMethod(method) {
-    return PATTERNS.filter((p) => p.cdpMethods.includes(method));
+    const normalized = method.toLowerCase();
+    return PATTERNS.filter((p) => p.cdpMethods.some((m) => m.toLowerCase() === normalized));
 }
 //# sourceMappingURL=patternDefinitions.js.map

package/dist/daemon/patternDetector.d.ts

@@ -11,50 +11,34 @@ import { type PatternDefinition } from './patternDefinitions.js';
 export interface PatternDetectionResult {
     /** Whether a hint should be shown */
     shouldShow: boolean;
-    /** Pattern that was detected */
+    /** Pattern whose hint should be shown */
     pattern?: PatternDefinition;
-    /** How many times this hint has been shown */
-    shownCount?: number;
 }
 /**
  * Pattern detector for tracking CDP usage and suggesting alternatives.
  *
- * Maintains state for pattern occurrence counts and hint display limits.
- * Designed to provide helpful guidance without overwhelming users.
+ * Counts calls per pattern, so related methods (e.g. `Network.getCookies` and
+ * `Network.getAllCookies`) share one count. Once a pattern reaches its threshold
+ * its hint is shown at most `MAX_HINTS_PER_PATTERN` times. When several patterns
+ * qualify, the one with the highest threshold wins as the most specific signal.
  */
 export declare class PatternDetector {
-    private readonly methodCounts;
+    private static readonly MAX_HINTS_PER_PATTERN;
+    private readonly patternCounts;
     private readonly hintShownCounts;
-    private readonly maxHintsPerPattern;
     /**
      * Track a CDP command execution.
      *
-     * Records the command and checks if any patterns are triggered.
-     * Returns detection result indicating if a hint should be shown.
-     *
-     * @param method - CDP method that was executed (e.g., "Runtime.evaluate")
-     * @returns Detection result with hint information
+     * @param method - CDP method that was executed (case-insensitive, e.g. "Runtime.evaluate")
+     * @returns Detection result indicating whether a hint should be shown
      */
     trackCommand(method: string): PatternDetectionResult;
     /**
-     * Reset all pattern tracking state.
-     *
-     * Useful for testing or when starting a fresh analysis.
-     */
-    reset(): void;
-    /**
-     * Get current method count for a specific CDP method.
-     *
-     * @param method - CDP method name
-     * @returns Number of times method has been called
-     */
-    getMethodCount(method: string): number;
-    /**
-     * Get hint shown count for a specific pattern.
+     * Check whether a pattern's hint is still under its display limit.
      *
-     * @param patternName - Pattern identifier
-     * @returns Number of times hint has been shown for this pattern
+     * @param pattern - Pattern to check
+     * @returns True if the hint may be shown again
      */
-    getHintShownCount(patternName: string): number;
+    private canShowHint;
 }
 //# sourceMappingURL=patternDetector.d.ts.map

package/dist/daemon/patternDetector.js

@@ -8,67 +8,46 @@ import { findPatternsForMethod } from './patternDefinitions.js';
 /**
  * Pattern detector for tracking CDP usage and suggesting alternatives.
  *
- * Maintains state for pattern occurrence counts and hint display limits.
- * Designed to provide helpful guidance without overwhelming users.
+ * Counts calls per pattern, so related methods (e.g. `Network.getCookies` and
+ * `Network.getAllCookies`) share one count. Once a pattern reaches its threshold
+ * its hint is shown at most `MAX_HINTS_PER_PATTERN` times. When several patterns
+ * qualify, the one with the highest threshold wins as the most specific signal.
  */
 export class PatternDetector {
-    methodCounts = new Map();
+    static MAX_HINTS_PER_PATTERN = 3;
+    patternCounts = new Map();
     hintShownCounts = new Map();
-    maxHintsPerPattern = 3;
     /**
      * Track a CDP command execution.
      *
-     * Records the command and checks if any patterns are triggered.
-     * Returns detection result indicating if a hint should be shown.
-     *
-     * @param method - CDP method that was executed (e.g., "Runtime.evaluate")
-     * @returns Detection result with hint information
+     * @param method - CDP method that was executed (case-insensitive, e.g. "Runtime.evaluate")
+     * @returns Detection result indicating whether a hint should be shown
      */
     trackCommand(method) {
-        const currentCount = (this.methodCounts.get(method) ?? 0) + 1;
-        this.methodCounts.set(method, currentCount);
-        const matchingPatterns = findPatternsForMethod(method);
-        for (const pattern of matchingPatterns) {
-            if (currentCount >= pattern.threshold) {
-                const shownCount = this.hintShownCounts.get(pattern.name) ?? 0;
-                if (shownCount < this.maxHintsPerPattern) {
-                    this.hintShownCounts.set(pattern.name, shownCount + 1);
-                    return {
-                        shouldShow: true,
-                        pattern,
-                        shownCount: shownCount + 1,
-                    };
-                }
+        let selected;
+        for (const pattern of findPatternsForMethod(method)) {
+            const count = (this.patternCounts.get(pattern.name) ?? 0) + 1;
+            this.patternCounts.set(pattern.name, count);
+            if (count < pattern.threshold || !this.canShowHint(pattern))
+                continue;
+            if (!selected || pattern.threshold > selected.threshold) {
+                selected = pattern;
             }
         }
-        return { shouldShow: false };
-    }
-    /**
-     * Reset all pattern tracking state.
-     *
-     * Useful for testing or when starting a fresh analysis.
-     */
-    reset() {
-        this.methodCounts.clear();
-        this.hintShownCounts.clear();
-    }
-    /**
-     * Get current method count for a specific CDP method.
-     *
-     * @param method - CDP method name
-     * @returns Number of times method has been called
-     */
-    getMethodCount(method) {
-        return this.methodCounts.get(method) ?? 0;
+        if (!selected) {
+            return { shouldShow: false };
+        }
+        this.hintShownCounts.set(selected.name, (this.hintShownCounts.get(selected.name) ?? 0) + 1);
+        return { shouldShow: true, pattern: selected };
     }
     /**
-     * Get hint shown count for a specific pattern.
+     * Check whether a pattern's hint is still under its display limit.
      *
-     * @param patternName - Pattern identifier
-     * @returns Number of times hint has been shown for this pattern
+     * @param pattern - Pattern to check
+     * @returns True if the hint may be shown again
      */
-    getHintShownCount(patternName) {
-        return this.hintShownCounts.get(patternName) ?? 0;
+    canShowHint(pattern) {
+        return (this.hintShownCounts.get(pattern.name) ?? 0) < PatternDetector.MAX_HINTS_PER_PATTERN;
     }
 }
 //# sourceMappingURL=patternDetector.js.map

package/dist/daemon/server/SocketServer.d.ts

@@ -1,22 +1,76 @@
 import { type Socket } from 'net';
 export type ConnectionHandler = (socket: Socket) => void;
+/** Error code thrown when another daemon already owns the socket path. */
+export declare const DAEMON_ALREADY_RUNNING_CODE = "DAEMON_ALREADY_RUNNING";
 /**
  * Thin wrapper around Node's net.Server that centralizes socket lifecycle
  * management (setup, connection tracking, teardown).
+ *
+ * Claims the socket path exclusively: the server listens on a private
+ * temporary path and then hard-links it to the public path. `link()` fails
+ * with EEXIST if the path exists, so two daemons can never both own it.
+ * On shutdown the public path is removed only if it still refers to our
+ * socket inode.
  */
 export declare class SocketServer {
     private server;
     private readonly sockets;
     private socketPath;
+    private socketInode;
     private readonly log;
     /**
      * Start listening on the provided Unix domain socket path.
+     *
+     * @param socketPath - Public socket path to claim
+     * @param handler - Connection handler
+     * @throws DaemonError with code DAEMON_ALREADY_RUNNING if a live daemon owns the path
      */
     start(socketPath: string, handler: ConnectionHandler): Promise<void>;
     /**
-     * Stop the server and clean up the socket file.
+     * Remove the public socket file so no new clients can connect, while
+     * keeping existing connections open to flush their final responses.
+     */
+    unpublish(): void;
+    /**
+     * Check that a path still refers to the socket this server claimed.
+     *
+     * Guards against removing another daemon's socket if ours was replaced
+     * (e.g. two daemons racing to replace the same stale socket file).
+     *
+     * @param path - Public socket path
+     * @returns True if the path is our socket inode
+     */
+    private ownsPath;
+    /**
+     * Unpublish the socket, drop all connections and close the server.
      */
     stop(): Promise<void>;
-    private cleanupStaleSocket;
+    /**
+     * Listen on a socket path.
+     *
+     * @param path - Socket path
+     * @param handler - Connection handler
+     */
+    private listen;
+    /**
+     * Atomically publish the listening socket at the public path.
+     *
+     * A stale socket file (nothing listening) is removed and the claim retried once.
+     *
+     * @param privatePath - Path the server is listening on
+     * @param socketPath - Public path to claim
+     * @throws DaemonError if a live daemon already owns the public path
+     */
+    private claim;
+    /**
+     * Close the underlying server if it is open.
+     */
+    private closeServer;
+    /**
+     * Remove a file, ignoring errors.
+     *
+     * @param path - File path
+     */
+    private removeFile;
 }
 //# sourceMappingURL=SocketServer.d.ts.map