browser-debugger-cli 0.7.1 → 0.8.0

package/dist/daemon/errors.d.ts

@@ -1,7 +1,7 @@
 /**
  * Daemon layer error classes.
  *
- * Provides structured error handling for daemon, worker, and configuration errors.
+ * Provides structured error handling for daemon and configuration errors.
  */
 /**
  * Base class for all daemon-related errors.
@@ -11,27 +11,10 @@ export declare class DaemonError extends Error {
     readonly code?: string;
     constructor(message: string, code?: string, exitCode?: number);
 }
-/**
- * Worker process error.
- *
- * Thrown when worker process fails to start, crashes, or has runtime issues.
- *
- * @example
- * ```typescript
- * throw new WorkerError(
- *   'Worker failed to start within timeout',
- *   'WORKER_START_TIMEOUT'
- * );
- * ```
- */
-export declare class WorkerError extends DaemonError {
-    readonly name = "WorkerError";
-    constructor(message: string, code?: string);
-}
 /**
  * Configuration error.
  *
- * Thrown when worker configuration is invalid or missing required fields.
+ * Thrown when session configuration is invalid or missing required fields.
  *
  * @example
  * ```typescript
@@ -62,4 +45,17 @@ export declare class DaemonStartupError extends DaemonError {
     readonly name = "DaemonStartupError";
     constructor(message: string, code?: string);
 }
+/**
+ * The session directory cannot hold the daemon's files.
+ */
+export declare class SessionDirError extends DaemonError {
+    readonly suggestion: string;
+    readonly name = "SessionDirError";
+    /**
+     * @param message - What is wrong with the directory
+     * @param suggestion - How to fix it
+     * @param exitCode - 82 for permissions, 103 otherwise
+     */
+    constructor(message: string, suggestion: string, exitCode?: number);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/daemon/errors.js

@@ -1,7 +1,7 @@
 /**
  * Daemon layer error classes.
  *
- * Provides structured error handling for daemon, worker, and configuration errors.
+ * Provides structured error handling for daemon and configuration errors.
  */
 import { EXIT_CODES } from '../utils/exitCodes.js';
 /**
@@ -22,29 +22,10 @@ export class DaemonError extends Error {
         }
     }
 }
-/**
- * Worker process error.
- *
- * Thrown when worker process fails to start, crashes, or has runtime issues.
- *
- * @example
- * ```typescript
- * throw new WorkerError(
- *   'Worker failed to start within timeout',
- *   'WORKER_START_TIMEOUT'
- * );
- * ```
- */
-export class WorkerError extends DaemonError {
-    name = 'WorkerError';
-    constructor(message, code) {
-        super(message, code, EXIT_CODES.SOFTWARE_ERROR);
-    }
-}
 /**
  * Configuration error.
  *
- * Thrown when worker configuration is invalid or missing required fields.
+ * Thrown when session configuration is invalid or missing required fields.
  *
  * @example
  * ```typescript
@@ -79,4 +60,20 @@ export class DaemonStartupError extends DaemonError {
         super(message, code, EXIT_CODES.SOFTWARE_ERROR);
     }
 }
+/**
+ * The session directory cannot hold the daemon's files.
+ */
+export class SessionDirError extends DaemonError {
+    suggestion;
+    name = 'SessionDirError';
+    /**
+     * @param message - What is wrong with the directory
+     * @param suggestion - How to fix it
+     * @param exitCode - 82 for permissions, 103 otherwise
+     */
+    constructor(message, suggestion, exitCode = EXIT_CODES.SESSION_FILE_ERROR) {
+        super(message, 'SESSION_DIR_UNUSABLE', exitCode);
+        this.suggestion = suggestion;
+    }
+}
 //# sourceMappingURL=errors.js.map

package/dist/daemon/ipcServer.d.ts

@@ -1,59 +1,73 @@
 /**
  * Daemon IPC Server
  *
- * Coordinates socket server, worker manager, and request/response handlers.
- * Responsibilities:
- * - Socket lifecycle management
- * - Message routing
- * - Delegation to specialized handlers
+ * Listens on the daemon Unix socket, parses JSONL requests and routes them to
+ * the {@link SessionController}. The daemon hosts exactly one session and shuts
+ * itself down when that session ends.
  */
 /**
- * Simple JSONL IPC server for daemon communication.
+ * IPC Server for the daemon process.
  */
 export declare class IPCServer {
     private readonly startTime;
     private readonly socketServer;
-    private readonly workerManager;
-    private readonly pendingRequests;
-    private readonly sessionService;
-    private readonly requestHandlers;
-    private readonly responseHandler;
+    private readonly controller;
+    private shuttingDown;
+    private idleTimer;
+    private inFlightRequests;
     constructor();
     /**
-     * Send a JSONL response to client socket.
+     * Start the server and write the daemon PID file.
      */
-    private sendResponse;
+    start(): Promise<void>;
     /**
-     * Start the IPC server on Unix domain socket.
+     * Stop the session (if any) and the server, then exit the process.
+     *
+     * Used by signal handlers. Idempotent.
      */
-    start(): Promise<void>;
+    shutdown(): Promise<void>;
     /**
-     * Handle new client connection.
+     * Stop the server and remove the socket and PID files, if they are still this daemon's.
+     *
+     * Never throws; safe to call before start() or more than once.
      */
-    private handleConnection;
+    stop(): Promise<void>;
     /**
-     * Handle incoming JSONL message - route to appropriate handler.
+     * Stop accepting clients and exit shortly after, so in-flight responses flush.
      */
-    private handleMessage;
+    private scheduleShutdown;
     /**
-     * Stop the IPC server and cleanup.
+     * Wait until requests already being handled have been answered.
+     *
+     * E.g. a `stop` that aborts a launching session must still get its response
+     * after the failed launch has triggered shutdown.
      */
-    stop(): Promise<void>;
+    private waitForInFlightRequests;
     /**
-     * Write daemon PID to file for tracking.
+     * Wire up JSONL parsing for a client connection.
      *
-     * Uses AtomicFileWriter to prevent corruption from crashes during write,
-     * ensuring daemon.pid is never left in a truncated/corrupt state that
-     * would cause parseInt errors during cleanup.
+     * @param socket - Client socket
      */
-    private writePidFile;
+    private handleConnection;
+    /**
+     * Parse, route and answer one request line.
+     *
+     * @param socket - Client socket
+     * @param line - Raw JSONL frame
+     * @param disconnected - Aborted when the client disconnects
+     */
+    private handleMessage;
     /**
-     * Check if daemon is already running.
+     * Dispatch a validated message to the controller.
+     *
+     * @param message - Client request
+     * @param disconnected - Aborted when the client disconnects
+     * @returns Response to send, or null for messages that need no reply
      */
-    static isRunning(): boolean;
+    private route;
     /**
-     * Get socket path for client connections.
+     * Write the daemon PID file (informational; liveness is checked via the socket).
      */
-    static getSocketPath(): string;
+    private writePidFile;
 }
 //# sourceMappingURL=ipcServer.d.ts.map

package/dist/daemon/ipcServer.js

@@ -1,29 +1,38 @@
 /**
  * Daemon IPC Server
  *
- * Coordinates socket server, worker manager, and request/response handlers.
- * Responsibilities:
- * - Socket lifecycle management
- * - Message routing
- * - Delegation to specialized handlers
+ * Listens on the daemon Unix socket, parses JSONL requests and routes them to
+ * the {@link SessionController}. The daemon hosts exactly one session and shuts
+ * itself down when that session ends.
  */
 import { unlinkSync } from 'fs';
-import { PendingRequestManager } from '../daemon/handlers/pendingRequests.js';
-import { RequestHandlers } from '../daemon/handlers/requestHandlers.js';
-import { ResponseHandler } from '../daemon/handlers/responseHandler.js';
-import { SocketServer } from '../daemon/server/SocketServer.js';
-import { WorkerManager } from '../daemon/server/WorkerManager.js';
-import { SessionService } from '../daemon/services/SessionService.js';
+import { SessionController } from './SessionController.js';
+import { SocketServer } from './server/SocketServer.js';
 import { isCommandRequest } from '../ipc/index.js';
-import { releaseDaemonLock } from '../session/lock.js';
-import { ensureSessionDir, getSessionFilePath, getDaemonSocketPath } from '../session/paths.js';
-import { readPidFromFile } from '../session/pid.js';
+import { JSONLBuffer, toJSONLFrame } from '../ipc/transport/jsonl.js';
+import { ensureSessionDir, getSessionFilePath } from '../session/paths.js';
+import { readDaemonPid } from '../session/pid.js';
 import { createLogger } from '../ui/logging/index.js';
+import { delay } from '../utils/async.js';
 import { AtomicFileWriter } from '../utils/atomicFile.js';
 import { getErrorMessage } from '../utils/errors.js';
 const log = createLogger('daemon');
+/** Delay before exiting after a session ends, so the final response flushes. */
+const SHUTDOWN_DELAY_MS = 100;
+/** Upper bound on waiting for in-flight requests during shutdown. */
+const IN_FLIGHT_WAIT_MS = 30000;
+const IN_FLIGHT_POLL_MS = 50;
+/**
+ * How long a freshly started daemon waits for a session before exiting. The
+ * client that spawned it sends its start request within milliseconds; the
+ * wait only matters when that client was interrupted before sending it.
+ */
+const IDLE_SHUTDOWN_MS = 3000;
 /**
  * Type guard to validate parsed JSON has expected message structure.
+ *
+ * @param obj - Parsed JSON value
+ * @returns True if the value looks like an IPC message
  */
 function isValidIPCMessage(obj) {
     if (typeof obj !== 'object' || obj === null) {
@@ -32,175 +41,198 @@ function isValidIPCMessage(obj) {
     return 'type' in obj && typeof obj.type === 'string' && 'sessionId' in obj;
 }
 /**
- * Simple JSONL IPC server for daemon communication.
+ * IPC Server for the daemon process.
  */
 export class IPCServer {
     startTime = Date.now();
     socketServer = new SocketServer();
-    workerManager = new WorkerManager();
-    pendingRequests = new PendingRequestManager();
-    sessionService = new SessionService();
-    requestHandlers;
-    responseHandler;
+    controller;
+    shuttingDown = false;
+    idleTimer = null;
+    inFlightRequests = 0;
     constructor() {
-        this.requestHandlers = new RequestHandlers(this.workerManager, this.pendingRequests, this.sessionService, (socket, response) => this.sendResponse(socket, response), this.startTime);
-        this.responseHandler = new ResponseHandler(this.pendingRequests, this.sessionService, (socket, response) => this.sendResponse(socket, response));
-        this.workerManager.on('message', (message) => this.responseHandler.handleWorkerResponse(message));
-        this.workerManager.on('exit', (code, signal) => this.responseHandler.handleWorkerExit(code, signal));
-    }
-    /**
-     * Send a JSONL response to client socket.
-     */
-    sendResponse(socket, response) {
-        socket.write(JSON.stringify(response) + '\n');
+        this.controller = new SessionController(this.startTime, getSessionFilePath('DAEMON_SOCKET'), () => this.scheduleShutdown());
     }
     /**
-     * Start the IPC server on Unix domain socket.
+     * Start the server and write the daemon PID file.
      */
     async start() {
         ensureSessionDir();
         const socketPath = getSessionFilePath('DAEMON_SOCKET');
         await this.socketServer.start(socketPath, (socket) => this.handleConnection(socket));
         this.writePidFile();
+        this.idleTimer = setTimeout(() => {
+            if (this.controller.isIdle()) {
+                log.info('No session started, shutting down idle daemon');
+                this.scheduleShutdown();
+            }
+        }, IDLE_SHUTDOWN_MS);
+    }
+    /**
+     * Stop the session (if any) and the server, then exit the process.
+     *
+     * Used by signal handlers. Idempotent.
+     */
+    async shutdown() {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        await this.controller.stopActiveSession();
+        await this.waitForInFlightRequests();
+        await delay(SHUTDOWN_DELAY_MS);
+        await this.stop();
+        process.exit(0);
     }
     /**
-     * Handle new client connection.
+     * Stop the server and remove the socket and PID files, if they are still this daemon's.
+     *
+     * Never throws; safe to call before start() or more than once.
+     */
+    async stop() {
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        await this.socketServer.stop();
+        if (readDaemonPid() !== process.pid)
+            return;
+        try {
+            unlinkSync(getSessionFilePath('DAEMON_PID'));
+        }
+        catch (error) {
+            log.debug(`Failed to remove daemon PID file: ${getErrorMessage(error)}`);
+        }
+    }
+    /**
+     * Stop accepting clients and exit shortly after, so in-flight responses flush.
+     */
+    scheduleShutdown() {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        this.controller.refuseNewSessions();
+        this.socketServer.unpublish();
+        void (async () => {
+            await this.waitForInFlightRequests();
+            await this.controller.stopActiveSession();
+            await delay(SHUTDOWN_DELAY_MS);
+            log.info('Session ended, shutting down daemon');
+            await this.stop();
+            process.exit(0);
+        })();
+    }
+    /**
+     * Wait until requests already being handled have been answered.
+     *
+     * E.g. a `stop` that aborts a launching session must still get its response
+     * after the failed launch has triggered shutdown.
+     */
+    async waitForInFlightRequests() {
+        const deadline = Date.now() + IN_FLIGHT_WAIT_MS;
+        while (this.inFlightRequests > 0 && Date.now() < deadline) {
+            await delay(IN_FLIGHT_POLL_MS);
+        }
+    }
+    /**
+     * Wire up JSONL parsing for a client connection.
+     *
+     * @param socket - Client socket
      */
     handleConnection(socket) {
         log.debug('Client connected');
-        let buffer = '';
+        const buffer = new JSONLBuffer();
+        const disconnected = new AbortController();
+        socket.on('close', () => disconnected.abort());
         socket.on('data', (chunk) => {
-            buffer += chunk.toString('utf-8');
-            const lines = buffer.split('\n');
-            buffer = lines.pop() ?? ''; // Keep incomplete line in buffer
-            for (const line of lines) {
-                if (line.trim()) {
-                    this.handleMessage(socket, line);
+            try {
+                for (const line of buffer.process(chunk.toString('utf-8'))) {
+                    void this.handleMessage(socket, line, disconnected.signal);
                 }
             }
-        });
-        socket.on('end', () => {
-            log.debug('Client disconnected');
+            catch (error) {
+                log.info(`Dropping client connection: ${getErrorMessage(error)}`);
+                socket.destroy();
+            }
         });
         socket.on('error', (err) => {
             log.debug(`Socket error: ${getErrorMessage(err)}`);
         });
     }
     /**
-     * Handle incoming JSONL message - route to appropriate handler.
+     * Parse, route and answer one request line.
+     *
+     * @param socket - Client socket
+     * @param line - Raw JSONL frame
+     * @param disconnected - Aborted when the client disconnects
      */
-    handleMessage(socket, line) {
-        log.debug(`Raw frame: ${line}`);
+    async handleMessage(socket, line, disconnected) {
+        let message;
         try {
-            const parsed = JSON.parse(line);
-            if (!isValidIPCMessage(parsed)) {
-                log.debug(`Invalid message structure: missing 'type' or 'sessionId' field`);
-                return;
-            }
-            const message = parsed;
-            if (isCommandRequest(message.type)) {
-                this.requestHandlers.handleCommandRequest(socket, message);
-                return;
-            }
-            if (message.type.endsWith('_response')) {
-                log.debug(`Unexpected response message from client: ${message.type}`);
-                return;
-            }
-            switch (message.type) {
-                case 'handshake_request':
-                    this.requestHandlers.handleHandshake(socket, message);
-                    break;
-                case 'status_request':
-                    this.requestHandlers.handleStatusRequest(socket, message);
-                    break;
-                case 'peek_request':
-                    this.requestHandlers.handlePeekRequest(socket, message);
-                    break;
-                case 'har_data_request':
-                    this.requestHandlers.handleHARDataRequest(socket, message);
-                    break;
-                case 'start_session_request':
-                    void this.requestHandlers.handleStartSessionRequest(socket, message);
-                    break;
-                case 'stop_session_request':
-                    this.requestHandlers.handleStopSessionRequest(socket, message);
-                    break;
-                case 'handshake_response':
-                case 'status_response':
-                case 'peek_response':
-                case 'har_data_response':
-                case 'start_session_response':
-                case 'stop_session_response':
-                    log.debug(`Unexpected response message received: ${message.type}`);
-                    break;
-            }
+            message = JSON.parse(line);
         }
         catch (error) {
             log.debug(`Failed to parse IPC message: ${getErrorMessage(error)}`);
+            return;
         }
-    }
-    /**
-     * Stop the IPC server and cleanup.
-     */
-    async stop() {
-        await this.socketServer.stop();
-        this.workerManager.dispose();
-        const socketPath = getSessionFilePath('DAEMON_SOCKET');
-        try {
-            unlinkSync(socketPath);
-        }
-        catch (error) {
-            log.debug(`Failed to remove socket file: ${getErrorMessage(error)}`);
+        if (!isValidIPCMessage(message)) {
+            log.debug(`Invalid message structure: missing 'type' or 'sessionId' field`);
+            return;
         }
-        const pidPath = getSessionFilePath('DAEMON_PID');
+        this.inFlightRequests++;
         try {
-            unlinkSync(pidPath);
+            const response = await this.route(message, disconnected);
+            if (response !== null && !socket.destroyed) {
+                socket.write(toJSONLFrame(response));
+            }
         }
-        catch (error) {
-            log.debug(`Failed to remove PID file: ${getErrorMessage(error)}`);
+        finally {
+            this.inFlightRequests--;
         }
     }
     /**
-     * Write daemon PID to file for tracking.
+     * Dispatch a validated message to the controller.
      *
-     * Uses AtomicFileWriter to prevent corruption from crashes during write,
-     * ensuring daemon.pid is never left in a truncated/corrupt state that
-     * would cause parseInt errors during cleanup.
+     * @param message - Client request
+     * @param disconnected - Aborted when the client disconnects
+     * @returns Response to send, or null for messages that need no reply
      */
-    writePidFile() {
-        const pidPath = getSessionFilePath('DAEMON_PID');
-        try {
-            AtomicFileWriter.writeSync(pidPath, process.pid.toString(), { encoding: 'utf-8' });
-            releaseDaemonLock(); // Release lock after PID is written (P0 Fix #1)
-            console.error(`[daemon] PID file written: ${pidPath}`);
+    async route(message, disconnected) {
+        if (isCommandRequest(message.type)) {
+            return this.controller.command(message);
         }
-        catch (error) {
-            console.error('[daemon] Failed to write PID file:', error);
+        switch (message.type) {
+            case 'handshake_request':
+                return this.controller.handshake(message);
+            case 'status_request':
+                return this.controller.status(message);
+            case 'peek_request':
+                return this.controller.peek(message);
+            case 'har_data_request':
+                return this.controller.harData(message);
+            case 'start_session_request':
+                return this.controller.startSession(message, disconnected);
+            case 'stop_session_request':
+                return this.controller.stopSession(message);
+            case 'handshake_response':
+            case 'status_response':
+            case 'peek_response':
+            case 'har_data_response':
+            case 'start_session_response':
+            case 'stop_session_response':
+                log.debug(`Unexpected response message from client: ${message.type}`);
+                return null;
         }
     }
     /**
-     * Check if daemon is already running.
+     * Write the daemon PID file (informational; liveness is checked via the socket).
      */
-    static isRunning() {
+    writePidFile() {
         const pidPath = getSessionFilePath('DAEMON_PID');
-        const pid = readPidFromFile(pidPath);
-        if (pid === null) {
-            return false;
-        }
         try {
-            process.kill(pid, 0);
-            return true;
+            AtomicFileWriter.writeSync(pidPath, process.pid.toString(), { encoding: 'utf-8' });
+            log.info(`PID file written: ${pidPath}`);
         }
         catch (error) {
-            log.debug(`Process ${pid} not alive: ${getErrorMessage(error)}`);
-            return false;
+            log.info(`Failed to write PID file: ${getErrorMessage(error)}`);
         }
     }
-    /**
-     * Get socket path for client connections.
-     */
-    static getSocketPath() {
-        return getDaemonSocketPath();
-    }
 }
 //# sourceMappingURL=ipcServer.js.map

package/dist/daemon/launcher.d.ts

@@ -1,31 +1,23 @@
 /**
- * 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 type { ChildProcess } from 'child_process';
 /**
- * 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 declare function launchDaemon(): Promise<ChildProcess>;
+export declare function launchDaemon(): Promise<void>;
 /**
- * Check if the daemon is currently running.
+ * Check that the session directory can hold the daemon's files before
+ * spawning it (otherwise the daemon dies and only its log says why).
  *
- * @returns True if daemon is running, false otherwise
+ * @throws SessionDirError (103) for a file or a too-long path, (82) when not writable
  */
-export declare function isDaemonRunning(): boolean;
+export declare function assertUsableSessionDir(): void;
 //# sourceMappingURL=launcher.d.ts.map