browser-debugger-cli 0.7.2 → 0.9.0

package/dist/daemon/SessionController.js

@@ -0,0 +1,488 @@
+/**
+ * Daemon request handling for the single in-process session.
+ *
+ * Maps each client IPC request to a response object. Holds the current
+ * {@link Session} and asks the daemon to shut down when the session ends,
+ * since the daemon's lifetime is the session's lifetime.
+ */
+import { CDPConnectionError, CDPProtocolError, ChromeLaunchError, ConnectionError, } from '../connection/errors.js';
+import { Session, StartCancelledError } from './session/Session.js';
+import { detectTargetMismatch } from './session/targetMismatch.js';
+import { CommandError } from '../errors/index.js';
+import { LAUNCHED_CHROME_DESCRIPTION, cdpRequestRejectedError, sessionAlreadyRunningMessage, sessionEndedDuringCommandError, sessionUnavailableSuggestion, } from '../errors/messages.js';
+import { IPCErrorCode, } from '../ipc/index.js';
+import { clearLastSessionEnd, writeLastSessionEnd } from '../session/lastSession.js';
+import { createLogger } from '../ui/logging/index.js';
+import { formatChromeIssue } from '../ui/messages/chrome.js';
+import { noActiveSessionMessage } from '../ui/messages/sessionCommand.js';
+import { getErrorMessage } from '../utils/errors.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
+import { filterDefined } from '../utils/objects.js';
+const log = createLogger('daemon');
+/** Error for requests that need the session while `bdg <url>` is still starting it */
+const STARTING_ERROR = 'The session is still starting';
+const COMMAND_TIMEOUT_MS = 30000;
+const QUERY_TIMEOUT_MS = 5000;
+/** Time a `dom wait` gets beyond its own --timeout to report the timeout itself */
+const WAIT_COMMAND_MARGIN_MS = 5000;
+/**
+ * How long a session command may run: `dom wait` runs for its own
+ * --timeout, everything else gets {@link COMMAND_TIMEOUT_MS}.
+ *
+ * @param name - Command name
+ * @param params - Command parameters
+ * @returns Timeout in milliseconds
+ */
+function commandTimeoutMs(name, params) {
+    if (name !== 'dom_wait')
+        return COMMAND_TIMEOUT_MS;
+    const { timeout } = params;
+    return Math.max(COMMAND_TIMEOUT_MS, (timeout ?? 0) + WAIT_COMMAND_MARGIN_MS);
+}
+/**
+ * Run a promise with a timeout, clearing the timer either way.
+ *
+ * @param promise - Work to wait for
+ * @param timeoutMs - Timeout in milliseconds
+ * @param label - Operation name for the timeout message
+ * @returns The promise's result
+ * @throws Error when the timeout elapses first
+ */
+async function withTimeout(promise, timeoutMs, label) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timeout (${timeoutMs / 1000}s)`)), timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Describe a session start failure for the client.
+ *
+ * @param error - Error thrown while starting
+ * @returns Human-readable message
+ */
+function describeStartError(error) {
+    if (error instanceof ConnectionError && error.issue) {
+        return formatChromeIssue(error.issue);
+    }
+    if (error instanceof CommandError) {
+        const suggestion = error.metadata['suggestion'];
+        return typeof suggestion === 'string' ? `${error.message}\n${suggestion}` : error.message;
+    }
+    return getErrorMessage(error);
+}
+/**
+ * Error fields of a failed launch: cancelled by a stop, a start URL that could
+ * not be loaded, or a launch failure.
+ *
+ * @param error - Error the launch failed with
+ * @returns Message, IPC error code, and the exit code of a user-facing error
+ */
+function describeLaunchFailure(error) {
+    if (error instanceof StartCancelledError) {
+        return { message: error.message, errorCode: IPCErrorCode.SESSION_START_CANCELLED };
+    }
+    const navigationFailed = error instanceof CommandError && error.exitCode === EXIT_CODES.INVALID_URL;
+    return {
+        message: describeStartError(error),
+        errorCode: navigationFailed
+            ? IPCErrorCode.NAVIGATION_FAILED
+            : IPCErrorCode.SESSION_START_FAILED,
+        ...(error instanceof CommandError && !navigationFailed && { exitCode: error.exitCode }),
+        ...(error instanceof ChromeLaunchError && { exitCode: EXIT_CODES.CHROME_LAUNCH_FAILURE }),
+    };
+}
+/**
+ * Owns the daemon's session and answers client requests.
+ */
+export class SessionController {
+    daemonStartTime;
+    socketPath;
+    onSessionEnded;
+    session = null;
+    launching = null;
+    closing = false;
+    /**
+     * @param daemonStartTime - Daemon start timestamp (ms)
+     * @param socketPath - Daemon socket path, reported in status
+     * @param onSessionEnded - Called once the session has ended or failed to start
+     */
+    constructor(daemonStartTime, socketPath, onSessionEnded) {
+        this.daemonStartTime = daemonStartTime;
+        this.socketPath = socketPath;
+        this.onSessionEnded = onSessionEnded;
+    }
+    /**
+     * Whether no session is running or starting.
+     *
+     * @returns True if the daemon hosts nothing
+     */
+    isIdle() {
+        return !this.session && !this.launching;
+    }
+    /**
+     * Reject any further start requests (the daemon is shutting down).
+     */
+    refuseNewSessions() {
+        this.closing = true;
+    }
+    /**
+     * Stop the session if one is running or launching (used on daemon shutdown).
+     *
+     * @returns True if a session was stopped
+     */
+    async stopActiveSession() {
+        this.closing = true;
+        const launching = this.launching;
+        const session = this.session ?? launching?.session;
+        if (!session && !launching)
+            return false;
+        await session?.stop('normal');
+        await launching?.done;
+        await this.session?.stop('normal');
+        return true;
+    }
+    /**
+     * Error fields for a request that needs the session when there is none:
+     * still starting (85), or none at all.
+     *
+     * @returns Error message, plus exit code and suggestion while starting
+     */
+    noSessionError() {
+        if (!this.launching)
+            return { error: noActiveSessionMessage() };
+        return {
+            error: STARTING_ERROR,
+            exitCode: EXIT_CODES.RESOURCE_BUSY,
+            suggestion: sessionUnavailableSuggestion(EXIT_CODES.RESOURCE_BUSY),
+        };
+    }
+    /**
+     * Respond to a handshake.
+     *
+     * @param request - Handshake request
+     * @returns Handshake response
+     */
+    handshake(request) {
+        return {
+            type: 'handshake_response',
+            sessionId: request.sessionId,
+            status: 'ok',
+            message: 'Handshake successful',
+        };
+    }
+    /**
+     * Report daemon status, enriched with live session activity when available.
+     *
+     * @param request - Status request
+     * @returns Status response
+     */
+    async status(request) {
+        const data = {
+            daemonPid: process.pid,
+            daemonStartTime: this.daemonStartTime,
+            socketPath: this.socketPath,
+        };
+        const base = { type: 'status_response', sessionId: request.sessionId };
+        if (!this.session || this.session.stopRequested()) {
+            if (this.launching) {
+                data.starting = { url: this.launching.url, since: this.launching.since };
+            }
+            if (this.session || this.closing)
+                data.ending = true;
+            return { ...base, status: 'ok', data };
+        }
+        data.sessionPid = process.pid;
+        data.sessionMetadata = this.session.metadata();
+        try {
+            const live = await withTimeout(this.session.execute('session_status', {}), QUERY_TIMEOUT_MS, 'Status');
+            Object.assign(data, {
+                activity: live.activity,
+                pageState: live.target,
+                navigationId: live.navigationId,
+            });
+            return { ...base, status: 'ok', data };
+        }
+        catch (error) {
+            return { ...base, status: 'error', data, error: getErrorMessage(error) };
+        }
+    }
+    /**
+     * Return a preview of recent telemetry.
+     *
+     * @param request - Peek request
+     * @returns Peek response
+     */
+    async peek(request) {
+        const base = { type: 'peek_response', sessionId: request.sessionId };
+        if (!this.session) {
+            return { ...base, status: 'error', ...this.noSessionError() };
+        }
+        try {
+            const data = await withTimeout(this.session.execute('session_peek', {
+                lastN: request.lastN ?? 10,
+                ...(request.only && { only: request.only }),
+                ...(request.withHeaders && { withHeaders: true }),
+            }), QUERY_TIMEOUT_MS, 'Peek');
+            return {
+                ...base,
+                status: 'ok',
+                data: {
+                    sessionPid: process.pid,
+                    preview: {
+                        version: data.version,
+                        success: true,
+                        timestamp: new Date(data.startTime).toISOString(),
+                        duration: data.duration,
+                        target: data.target,
+                        data: { network: data.network, console: data.console },
+                        totals: { network: data.totalNetwork, console: data.totalConsole },
+                        currentNavigationId: data.currentNavigationId,
+                        partial: true,
+                    },
+                },
+            };
+        }
+        catch (error) {
+            return { ...base, status: 'error', error: getErrorMessage(error) };
+        }
+    }
+    /**
+     * Return all captured network requests for HAR export.
+     *
+     * @param request - HAR data request
+     * @returns HAR data response
+     */
+    async harData(request) {
+        const base = { type: 'har_data_response', sessionId: request.sessionId };
+        if (!this.session) {
+            return { ...base, status: 'error', ...this.noSessionError() };
+        }
+        try {
+            const data = await withTimeout(this.session.execute('session_har_data', {}), QUERY_TIMEOUT_MS, 'HAR data');
+            return { ...base, status: 'ok', data: { sessionPid: process.pid, requests: data.requests } };
+        }
+        catch (error) {
+            return { ...base, status: 'error', error: getErrorMessage(error) };
+        }
+    }
+    /**
+     * Execute a session command (dom_*, cdp_call, session_details, ...).
+     *
+     * @param request - Command request
+     * @returns Command response, forwarding exit code and suggestion on failure
+     */
+    async command(request) {
+        const name = request.type.slice(0, -'_request'.length);
+        const base = { type: `${name}_response`, sessionId: request.sessionId };
+        if (!this.session) {
+            return { ...base, status: 'error', ...this.noSessionError() };
+        }
+        const { sessionId: _sessionId, type: _type, ...params } = request;
+        try {
+            const execute = this.session.execute.bind(this.session);
+            const data = await withTimeout(execute(name, params), commandTimeoutMs(name, params), 'Command');
+            return { ...base, status: 'ok', data };
+        }
+        catch (error) {
+            return { ...base, status: 'error', ...describeCommandError(error) };
+        }
+    }
+    /**
+     * Start a session, or report the one already running.
+     *
+     * A start whose client disconnects (Ctrl-C) is abandoned: the session is
+     * stopped, whether it is still launching or has just started, since nobody
+     * learns that it exists.
+     *
+     * @param request - Start session request
+     * @param abandoned - Aborted when the requesting client disconnects
+     * @returns Start session response
+     */
+    async startSession(request, abandoned) {
+        const base = { type: 'start_session_response', sessionId: request.sessionId };
+        if (this.session || this.launching || this.closing) {
+            return { ...base, status: 'error', ...this.describeExistingSession(request) };
+        }
+        const launching = {
+            session: null,
+            done: Promise.resolve(),
+            url: request.url,
+            since: Date.now(),
+        };
+        clearLastSessionEnd();
+        const run = this.launchSession(request, (session) => {
+            launching.session = session;
+        });
+        launching.done = run;
+        this.launching = launching;
+        const stopAbandoned = () => {
+            log.info('Client disconnected during start; stopping the session');
+            void launching.session?.stop('normal');
+        };
+        abandoned?.addEventListener('abort', stopAbandoned, { once: true });
+        try {
+            const result = await run;
+            if (abandoned?.aborted)
+                await launching.session?.stop('normal');
+            return { ...base, ...result };
+        }
+        finally {
+            abandoned?.removeEventListener('abort', stopAbandoned);
+            this.launching = null;
+        }
+    }
+    /**
+     * Create and launch a session, mapping the outcome to response fields.
+     *
+     * @param request - Start session request
+     * @param onCreated - Receives the session before launch, so it can be stopped mid-launch
+     * @returns Status plus data or error fields for the start response
+     */
+    async launchSession(request, onCreated) {
+        const { type: _type, sessionId: _sessionId, url, ...options } = request;
+        try {
+            const session = Session.create(url, filterDefined(options), (reason) => this.handleSessionEnded(reason));
+            onCreated(session);
+            if (this.closing) {
+                throw new Error('Daemon is shutting down');
+            }
+            await session.launch();
+            this.session = session;
+            const info = session.info();
+            log.info(`Session started (Chrome PID ${info.chromePid}, port ${info.port})`);
+            return {
+                status: 'ok',
+                message: 'Session started successfully',
+                data: { daemonPid: process.pid, ...info },
+            };
+        }
+        catch (error) {
+            log.info(`Session start failed: ${getErrorMessage(error)}`);
+            this.closing = true;
+            setImmediate(() => this.onSessionEnded('crash'));
+            return { status: 'error', ...describeLaunchFailure(error) };
+        }
+    }
+    /**
+     * Stop the running session, or abort one that is still launching.
+     *
+     * @param request - Stop session request
+     * @returns Stop session response
+     */
+    async stopSession(request) {
+        const base = { type: 'stop_session_response', sessionId: request.sessionId };
+        const launching = this.session ? null : this.launching;
+        const session = this.session ?? launching?.session;
+        if (!session) {
+            return {
+                ...base,
+                status: 'error',
+                message: noActiveSessionMessage(),
+                errorCode: IPCErrorCode.NO_SESSION,
+            };
+        }
+        const { chromePid } = session.info();
+        await session.stop('normal');
+        await launching?.done;
+        return {
+            ...base,
+            status: 'ok',
+            message: 'Session stopped successfully',
+            ...(chromePid > 0 && { chromePid }),
+        };
+    }
+    /**
+     * React to the session ending (stop, crash, or timeout).
+     *
+     * @param reason - Why the session ended
+     */
+    handleSessionEnded(reason) {
+        log.info(`Session ended (reason: ${reason})`);
+        if (reason !== 'normal')
+            writeLastSessionEnd(reason);
+        this.session = null;
+        this.closing = true;
+        this.onSessionEnded(reason);
+    }
+    /**
+     * Build the error part of a start response when a session already exists.
+     *
+     * @param request - Start session request
+     * @returns Error message, code and existing-session details
+     */
+    describeExistingSession(request) {
+        const shuttingDown = this.closing || Boolean(this.session?.stopRequested());
+        if (!this.session || shuttingDown) {
+            return shuttingDown
+                ? {
+                    message: 'The previous session is still shutting down. Try again in a moment.',
+                    errorCode: IPCErrorCode.SESSION_SHUTTING_DOWN,
+                }
+                : {
+                    message: 'Session startup already in progress. Wait a moment and try again.',
+                    errorCode: IPCErrorCode.SESSION_ALREADY_RUNNING,
+                };
+        }
+        const metadata = this.session.metadata();
+        const { targetUrl } = this.session.info();
+        const existingSession = {
+            pid: process.pid,
+            startTime: metadata.startTime,
+            duration: Math.floor((Date.now() - metadata.startTime) / 1000),
+        };
+        const mismatch = detectTargetMismatch(request, metadata);
+        if (mismatch) {
+            const current = mismatch.current === LAUNCHED_CHROME_DESCRIPTION ? undefined : mismatch.current;
+            return {
+                message: `Active session is attached to ${mismatch.current}, not ${mismatch.requested}`,
+                errorCode: IPCErrorCode.SESSION_TARGET_MISMATCH,
+                existingSession: { ...existingSession, ...(current && { targetUrl: current }) },
+            };
+        }
+        return {
+            message: sessionAlreadyRunningMessage(process.pid),
+            errorCode: IPCErrorCode.SESSION_ALREADY_RUNNING,
+            existingSession: { ...existingSession, targetUrl },
+        };
+    }
+}
+/**
+ * Convert a command failure into response fields.
+ *
+ * @param error - Error thrown by the command handler
+ * @returns Error message plus exit code and suggestion when known
+ */
+function describeCommandError(error) {
+    if (error instanceof CDPProtocolError && error.isRequestError()) {
+        const err = cdpRequestRejectedError(error.message);
+        return {
+            error: err.message,
+            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+            suggestion: err.suggestion,
+        };
+    }
+    if (error instanceof CDPConnectionError) {
+        const err = sessionEndedDuringCommandError();
+        return {
+            error: err.message,
+            exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
+            suggestion: err.suggestion,
+        };
+    }
+    if (!(error instanceof CommandError)) {
+        return { error: getErrorMessage(error) };
+    }
+    const suggestion = error.metadata['suggestion'];
+    return {
+        error: error.message,
+        exitCode: error.exitCode,
+        ...(typeof suggestion === 'string' && { suggestion }),
+    };
+}
+//# sourceMappingURL=SessionController.js.map

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, 81 for a too-long path, 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, 81 for a too-long path, 103 otherwise
+     */
+    constructor(message, suggestion, exitCode = EXIT_CODES.SESSION_FILE_ERROR) {
+        super(message, 'SESSION_DIR_UNUSABLE', exitCode);
+        this.suggestion = suggestion;
+    }
+}
 //# sourceMappingURL=errors.js.map