browser-debugger-cli 0.7.1 → 0.8.0

package/dist/commands/shared/startHelpers.d.ts

@@ -4,20 +4,17 @@
  * Command-specific logic for the `bdg start` command.
  * Handles IPC communication with daemon to start browser sessions.
  */
-import type { SessionStartOptions } from '../../commands/shared/optionTypes.js';
+import type { SessionStartOptions } from './optionTypes.js';
 import type { TelemetryType } from '../../types.js';
 /**
- * Start a session via the daemon using IPC.
+ * Start a session via the daemon and report the result.
  *
- * This replaces the in-process sessionController.startSession() by:
- * 1. Sending a start_session_request to the daemon
- * 2. Waiting for the worker to launch and report readiness
- * 3. Outputting metadata about the running session
- * 4. Keeping the process alive while the session runs
+ * Spawns the daemon if needed, sends `start_session_request`, then prints the
+ * result as a JSON envelope (`--json`) or human-readable text, and exits.
  *
  * @param url - Target URL to navigate to
  * @param options - Session configuration options
  * @param telemetry - Array of telemetry types to enable
  */
-export declare function startSessionViaDaemon(url: string, options: SessionStartOptions, telemetry: TelemetryType[]): Promise<void>;
+export declare function startSessionViaDaemon(url: string, options: SessionStartOptions, telemetry: TelemetryType[]): Promise<never>;
 //# sourceMappingURL=startHelpers.d.ts.map

package/dist/commands/shared/startHelpers.js

@@ -4,31 +4,101 @@
  * Command-specific logic for the `bdg start` command.
  * Handles IPC communication with daemon to start browser sessions.
  */
-import { landingPage } from '../../commands/shared/landingPage.js';
+import { timeoutError } from './CommandRunner.js';
+import { landingPage } from './landingPage.js';
+import { DaemonError, SessionDirError } from '../../daemon/errors.js';
+import { launchDaemon } from '../../daemon/launcher.js';
+import { LAUNCHED_CHROME_DESCRIPTION, sessionAlreadyRunningError, ALREADY_RUNNING_SUGGESTION, sessionTargetMismatchError, daemonNotRunningError, invalidResponseError, genericError, } from '../../errors/messages.js';
 import { startSession as sendStartSessionRequest } from '../../ipc/client.js';
-import { IPCErrorCode } from '../../ipc/index.js';
+import { IPCErrorCode, } from '../../ipc/index.js';
+import { IPCTimeoutError } from '../../ipc/transport/index.js';
 import { isConnectionError } from '../../ipc/utils/errors.js';
+import { OutputBuilder, buildSuccessResponse } from '../../ui/OutputBuilder.js';
+import { escapeControlChars, joinLines } from '../../ui/formatting.js';
 import { createLogger } from '../../ui/logging/index.js';
-import { sessionAlreadyRunningError, daemonNotRunningError, invalidResponseError, genericError, } from '../../ui/messages/errors.js';
+import { startNotices } from '../../ui/messages/session.js';
+import { delay } from '../../utils/async.js';
 import { getExitCodeForIPCError } from '../../utils/errorMapping.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { filterDefined } from '../../utils/objects.js';
 const log = createLogger('bdg');
 /**
- * Start a session via the daemon using IPC.
+ * Start a session via the daemon and report the result.
  *
- * This replaces the in-process sessionController.startSession() by:
- * 1. Sending a start_session_request to the daemon
- * 2. Waiting for the worker to launch and report readiness
- * 3. Outputting metadata about the running session
- * 4. Keeping the process alive while the session runs
+ * Spawns the daemon if needed, sends `start_session_request`, then prints the
+ * result as a JSON envelope (`--json`) or human-readable text, and exits.
  *
  * @param url - Target URL to navigate to
  * @param options - Session configuration options
  * @param telemetry - Array of telemetry types to enable
  */
 export async function startSessionViaDaemon(url, options, telemetry) {
+    process.once('SIGINT', () => reportStartOutcome(interruptedOutcome('SIGINT'), options));
+    process.once('SIGTERM', () => reportStartOutcome(interruptedOutcome('SIGTERM'), options));
+    let outcome = await requestSession(url, options, telemetry);
+    const deadline = Date.now() + SHUTDOWN_WAIT_MS;
+    while (isShuttingDown(outcome) && Date.now() < deadline) {
+        await delay(SHUTDOWN_POLL_MS);
+        outcome = await requestSession(url, options, telemetry);
+    }
+    reportStartOutcome(outcome, options);
+}
+/**
+ * The outcome of a start interrupted with Ctrl-C (the daemon notices the
+ * closed connection and cancels the start).
+ *
+ * @param signal - The signal that stopped the start
+ * @returns Failed start outcome (exit 130)
+ */
+function interruptedOutcome(signal) {
+    const message = `Start cancelled (${signal === 'SIGINT' ? 'interrupted' : 'terminated'})`;
+    const exitCode = signal === 'SIGINT' ? EXIT_CODES.INTERRUPTED : EXIT_CODES.TERMINATED;
+    return { ok: false, error: message, human: message, exitCode };
+}
+/** How long a new start waits for the previous session to finish shutting down */
+const SHUTDOWN_WAIT_MS = 15000;
+/** Interval between start attempts while the previous session shuts down */
+const SHUTDOWN_POLL_MS = 200;
+/**
+ * Whether the start failed only because the previous session is still
+ * shutting down (e.g. `bdg stop` was just run), or its daemon exited while
+ * answering: the start is retried until the old daemon is gone and a new one
+ * can be launched.
+ *
+ * @param outcome - Start outcome
+ * @returns True if waiting and retrying can succeed
+ */
+function isShuttingDown(outcome) {
+    return (!outcome.ok &&
+        (outcome.retryable === true || outcome.errorCode === IPCErrorCode.SESSION_SHUTTING_DOWN));
+}
+/**
+ * Launch the daemon if needed and ask it to start a session.
+ *
+ * @param url - Target URL
+ * @param options - Session options
+ * @param telemetry - Telemetry types
+ * @returns Start outcome
+ */
+async function requestSession(url, options, telemetry) {
+    try {
+        await launchDaemon();
+    }
+    catch (error) {
+        if (error instanceof SessionDirError) {
+            return {
+                ok: false,
+                error: error.message,
+                human: joinLines(genericError(error.message), error.suggestion),
+                exitCode: error.exitCode,
+                details: { suggestion: error.suggestion },
+            };
+        }
+        const message = `Failed to start daemon: ${getErrorMessage(error)}`;
+        const exitCode = error instanceof DaemonError ? error.exitCode : EXIT_CODES.SOFTWARE_ERROR;
+        return { ok: false, error: message, human: genericError(message), exitCode };
+    }
     try {
         log.debug('Connecting to daemon...');
         const response = await sendStartSessionRequest(url, filterDefined({
@@ -42,40 +112,159 @@ export async function startSessionViaDaemon(url, options, telemetry) {
             chromeWsUrl: options.chromeWsUrl,
             chromeFlags: options.chromeFlags,
         }));
-        if (response.status === 'error') {
-            if (response.errorCode === IPCErrorCode.SESSION_ALREADY_RUNNING && response.existingSession) {
-                const { pid, targetUrl, duration } = response.existingSession;
-                const durationMs = duration ? duration * 1000 : 0;
-                console.error(sessionAlreadyRunningError(pid, durationMs, targetUrl));
-            }
-            else {
-                console.error(genericError(`Daemon error: ${response.message ?? 'Unknown error'}`));
-            }
-            process.exit(getExitCodeForIPCError(response.errorCode));
+        if (response.status === 'error')
+            return describeStartFailure(response, options);
+        if (!response.data) {
+            const message = 'Invalid response from daemon: missing data';
+            return {
+                ok: false,
+                error: message,
+                human: invalidResponseError('missing data'),
+                exitCode: EXIT_CODES.SOFTWARE_ERROR,
+            };
         }
-        const { data } = response;
-        if (!data) {
-            console.error(invalidResponseError('missing data'));
-            process.exit(EXIT_CODES.SOFTWARE_ERROR);
+        return { ok: true, data: response.data };
+    }
+    catch (error) {
+        if (error instanceof IPCTimeoutError) {
+            const timeout = timeoutError(error);
+            return {
+                ok: false,
+                error: timeout.message,
+                human: joinLines(genericError(timeout.message), String(timeout.metadata.suggestion)),
+                exitCode: timeout.exitCode,
+                details: { suggestion: timeout.metadata.suggestion },
+            };
         }
-        if (options.quiet) {
-            console.error(`Session started: ${data.targetUrl}`);
+        if (isConnectionError(error)) {
+            return {
+                ok: false,
+                error: 'No active session (daemon not running)',
+                human: daemonNotRunningError({ suggestStatus: true, suggestRetry: true }),
+                exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
+                retryable: true,
+            };
         }
-        else {
-            const landing = landingPage({
-                url: data.targetUrl,
+        const message = getErrorMessage(error);
+        return {
+            ok: false,
+            error: message,
+            human: genericError(message),
+            exitCode: EXIT_CODES.SOFTWARE_ERROR,
+        };
+    }
+}
+/**
+ * The existing session without its `duration` (seconds), which is reported
+ * as `durationMs` like every other duration.
+ *
+ * @param existing - Existing session from the daemon
+ * @returns The other fields
+ */
+function omitDuration(existing) {
+    const { duration: _duration, ...rest } = existing;
+    return rest;
+}
+/**
+ * Describe an error response to `start_session_request`.
+ *
+ * @param response - Error response from the daemon
+ * @param options - Session options (for target-mismatch wording)
+ * @returns Failed start outcome
+ */
+function describeStartFailure(response, options) {
+    const exitCode = response.exitCode ?? getExitCodeForIPCError(response.errorCode);
+    const existing = response.existingSession;
+    const details = filterDefined({
+        existingSession: existing && {
+            ...omitDuration(existing),
+            ...(existing.duration !== undefined && { durationMs: existing.duration * 1000 }),
+        },
+    });
+    if (response.errorCode === IPCErrorCode.SESSION_ALREADY_RUNNING && existing) {
+        const { pid, targetUrl, duration } = existing;
+        return {
+            ok: false,
+            error: response.message ?? 'Session already running',
+            human: sessionAlreadyRunningError(pid, duration ? duration * 1000 : 0, targetUrl),
+            exitCode,
+            errorCode: response.errorCode,
+            details: { ...details, suggestion: ALREADY_RUNNING_SUGGESTION },
+        };
+    }
+    if (response.errorCode === IPCErrorCode.SESSION_TARGET_MISMATCH) {
+        // Absent existingSession.targetUrl signals launched-mode current — the
+        // daemon omits it in that case to keep targetUrl URL-shaped for agents.
+        const current = response.existingSession?.targetUrl ?? LAUNCHED_CHROME_DESCRIPTION;
+        const requested = options.chromeWsUrl ?? LAUNCHED_CHROME_DESCRIPTION;
+        return {
+            ok: false,
+            error: response.message ?? 'Session target mismatch',
+            human: sessionTargetMismatchError(current, requested),
+            exitCode,
+            errorCode: response.errorCode,
+            details,
+        };
+    }
+    const message = response.message ?? 'Unknown error';
+    const [error = message, ...hint] = message.split('\n');
+    return {
+        ok: false,
+        error,
+        human: genericError(message),
+        exitCode,
+        errorCode: response.errorCode,
+        details: {
+            ...details,
+            ...(hint.join('\n').trim() && { suggestion: hint.join('\n').trim() }),
+        },
+    };
+}
+/**
+ * Print a start outcome and exit.
+ *
+ * @param outcome - Start outcome
+ * @param options - Session options (json/quiet)
+ */
+function reportStartOutcome(outcome, options) {
+    if (!outcome.ok) {
+        if (options.json) {
+            const envelope = OutputBuilder.buildJsonError(outcome.error, {
+                exitCode: outcome.exitCode,
+                ...outcome.details,
             });
-            console.error(landing);
+            console.log(JSON.stringify(envelope, null, 2));
         }
-        process.exit(0);
-    }
-    catch (error) {
-        if (isConnectionError(error)) {
-            console.error(daemonNotRunningError({ suggestStatus: true, suggestRetry: true }));
-            process.exit(EXIT_CODES.RESOURCE_NOT_FOUND);
+        else {
+            console.error(escapeControlChars(outcome.human));
         }
-        console.error(genericError(getErrorMessage(error)));
-        process.exit(EXIT_CODES.SOFTWARE_ERROR);
+        process.exit(outcome.exitCode);
+    }
+    const { data } = outcome;
+    const autoStopAt = options.timeout !== undefined ? new Date(Date.now() + options.timeout * 1000) : undefined;
+    if (options.json) {
+        const result = {
+            targetUrl: data.targetUrl,
+            ...(data.targetTitle !== undefined && { targetTitle: data.targetTitle }),
+            ...(data.documentStatus !== undefined && { documentStatus: data.documentStatus }),
+            port: data.port,
+            ...(data.chromePid > 0 ? { chromePid: data.chromePid } : { externalChrome: true }),
+            daemonPid: data.daemonPid,
+            ...(autoStopAt && { autoStopAt: autoStopAt.toISOString() }),
+        };
+        console.log(JSON.stringify(buildSuccessResponse(result), null, 2));
+    }
+    else {
+        const page = {
+            url: data.targetUrl,
+            ...(data.documentStatus !== undefined && { documentStatus: data.documentStatus }),
+            ...(autoStopAt && { autoStopAt }),
+        };
+        const text = options.quiet
+            ? [`Session started: ${data.targetUrl}`, ...startNotices(page)].join('\n')
+            : landingPage(page);
+        console.error(escapeControlChars(text));
     }
+    process.exit(EXIT_CODES.SUCCESS);
 }
 //# sourceMappingURL=startHelpers.js.map

package/dist/commands/shared/validation.d.ts

@@ -2,11 +2,14 @@
  * Validation layer for command options.
  */
 import type { Protocol } from '../../connection/typed-cdp.js';
+import type { ConsoleLevel } from '../../types.js';
 export interface ValidationRule<T> {
     validate: (value: unknown) => T;
     errorMessage?: (value: unknown) => string;
 }
 export interface IntegerRuleOptions {
+    /** Option name shown in error messages (e.g. "--port") */
+    name?: string;
     min?: number;
     max?: number;
     default?: number;
@@ -14,5 +17,44 @@ export interface IntegerRuleOptions {
     allowZeroForAll?: boolean;
 }
 export declare function positiveIntRule(options?: IntegerRuleOptions): ValidationRule<number>;
+/**
+ * Build a Commander option parser for strict integers.
+ *
+ * Replaces bare `parseInt` (which yields NaN for "abc", accepts "5px", and
+ * receives the previous value as radix). Invalid input becomes a Commander
+ * usage error, reported with exit code 81.
+ *
+ * @param min - Inclusive lower bound
+ * @param max - Inclusive upper bound
+ * @returns Parser for `.option(flags, description, parser)`
+ */
+export declare function integerOption(min?: number, max?: number): (value: string) => number;
+/** Largest `--last` window (the daemon returns at most this many items) */
+export declare const MAX_LAST_ITEMS = 10000;
+/**
+ * Commander parser for `--format`: case-insensitive, `jpg` means `jpeg`.
+ *
+ * @param value - Raw option value
+ * @returns Normalized format
+ * @throws InvalidArgumentError (exit 81) for other formats
+ */
+export declare function screenshotFormatOption(value: string): 'png' | 'jpeg';
+/**
+ * Commander parser for `console --level`: case-insensitive, with aliases.
+ *
+ * @param value - Raw option value
+ * @returns Console level
+ * @throws InvalidArgumentError (exit 81) with a did-you-mean
+ */
+export declare function consoleLevelOption(value: string): ConsoleLevel;
+/**
+ * Commander parser for `dom listeners --type`: comma-separated event types
+ * (case-sensitive, like `addEventListener`).
+ *
+ * @param value - Raw option value, e.g. "click,keydown"
+ * @returns Event types
+ * @throws InvalidArgumentError (exit 81) when no type is given
+ */
+export declare function eventTypesOption(value: string): string[];
 export declare function resourceTypeRule(): ValidationRule<Protocol.Network.ResourceType[]>;
 //# sourceMappingURL=validation.d.ts.map

package/dist/commands/shared/validation.js

@@ -1,8 +1,10 @@
 /**
  * Validation layer for command options.
  */
-import { CommandError } from '../../ui/errors/index.js';
-import { invalidIntegerError } from '../../ui/messages/validation.js';
+import { InvalidArgumentError } from 'commander';
+import { resourceTypeFromName } from '../../constants.js';
+import { CommandError } from '../../errors/index.js';
+import { integerOutOfRangeError, invalidIntegerError } from '../../ui/messages/validation.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { findSimilar } from '../../utils/suggestions.js';
 const VALID_RESOURCE_TYPES = [
@@ -38,16 +40,8 @@ function buildRangeSuggestion(min, max) {
 function throwValidationError(message, suggestion) {
     throw new CommandError(message, { suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
-function buildErrorOptions(min, max) {
-    const opts = {};
-    if (min !== undefined)
-        opts.min = min;
-    if (max !== undefined)
-        opts.max = max;
-    return opts;
-}
 function parseInteger(value, options) {
-    const { min, max, default: defaultValue, required = true, allowZeroForAll = false } = options;
+    const { name, min, max, default: defaultValue, required = true, allowZeroForAll = false, } = options;
     if (value === undefined || value === null) {
         if (defaultValue !== undefined)
             return defaultValue;
@@ -58,19 +52,18 @@ function parseInteger(value, options) {
     if (typeof value !== 'string' && typeof value !== 'number') {
         throwValidationError(`Value must be a number, got ${typeof value}`, 'Provide a numeric value');
     }
-    const parsed = parseInt(String(value).trim(), 10);
-    const rangeSuggestion = buildRangeSuggestion(min, max);
-    const errorOptions = buildErrorOptions(min, max);
-    if (isNaN(parsed)) {
-        throwValidationError(invalidIntegerError('value', String(value), errorOptions), rangeSuggestion);
+    const text = String(value).trim();
+    const rangeSuggestion = allowZeroForAll
+        ? `Use 0 for all, or a value between ${min ?? 1} and ${max ?? 'any'}`
+        : buildRangeSuggestion(min, max);
+    if (!/^[+-]?\d+$/.test(text)) {
+        throwValidationError(invalidIntegerError(text, {}, name), rangeSuggestion);
     }
+    const parsed = Number(text);
     if (parsed === 0 && allowZeroForAll)
         return 0;
-    if (min !== undefined && parsed < min) {
-        throwValidationError(invalidIntegerError('value', String(value), errorOptions), rangeSuggestion);
-    }
-    if (max !== undefined && parsed > max) {
-        throwValidationError(invalidIntegerError('value', String(value), errorOptions), rangeSuggestion);
+    if ((min !== undefined && parsed < min) || (max !== undefined && parsed > max)) {
+        throwValidationError(integerOutOfRangeError(text, {}, name), rangeSuggestion);
     }
     return parsed;
 }
@@ -79,6 +72,91 @@ export function positiveIntRule(options = {}) {
         validate: (value) => parseInteger(value, options),
     };
 }
+/**
+ * Build a Commander option parser for strict integers.
+ *
+ * Replaces bare `parseInt` (which yields NaN for "abc", accepts "5px", and
+ * receives the previous value as radix). Invalid input becomes a Commander
+ * usage error, reported with exit code 81.
+ *
+ * @param min - Inclusive lower bound
+ * @param max - Inclusive upper bound
+ * @returns Parser for `.option(flags, description, parser)`
+ */
+export function integerOption(min, max) {
+    return (value) => {
+        const text = value.trim();
+        const parsed = Number(text);
+        const outOfRange = (min !== undefined && parsed < min) || (max !== undefined && parsed > max);
+        if (!/^[+-]?\d+$/.test(text)) {
+            throw new InvalidArgumentError(`Expected an integer. ${buildRangeSuggestion(min, max)}`);
+        }
+        if (outOfRange) {
+            throw new InvalidArgumentError(`${text} is out of range. ${buildRangeSuggestion(min, max)}`);
+        }
+        return parsed;
+    };
+}
+/** Largest `--last` window (the daemon returns at most this many items) */
+export const MAX_LAST_ITEMS = 10000;
+/** Image formats Chrome can capture, by the names users write */
+const SCREENSHOT_FORMATS = {
+    png: 'png',
+    jpeg: 'jpeg',
+    jpg: 'jpeg',
+};
+/**
+ * Commander parser for `--format`: case-insensitive, `jpg` means `jpeg`.
+ *
+ * @param value - Raw option value
+ * @returns Normalized format
+ * @throws InvalidArgumentError (exit 81) for other formats
+ */
+export function screenshotFormatOption(value) {
+    const format = SCREENSHOT_FORMATS[value.trim().toLowerCase()];
+    if (format)
+        return format;
+    const similar = findSimilar(value.toLowerCase(), Object.keys(SCREENSHOT_FORMATS));
+    throw new InvalidArgumentError(`Use png or jpeg${similar.length ? ` (did you mean ${similar[0]}?)` : ''}.`);
+}
+/** Console levels by the names users write (`log` is shown under info) */
+const CONSOLE_LEVELS = {
+    error: 'error',
+    warning: 'warning',
+    warn: 'warning',
+    info: 'info',
+    log: 'info',
+    debug: 'debug',
+    verbose: 'debug',
+};
+/**
+ * Commander parser for `console --level`: case-insensitive, with aliases.
+ *
+ * @param value - Raw option value
+ * @returns Console level
+ * @throws InvalidArgumentError (exit 81) with a did-you-mean
+ */
+export function consoleLevelOption(value) {
+    const level = CONSOLE_LEVELS[value.trim().toLowerCase()];
+    if (level)
+        return level;
+    const similar = findSimilar(value.toLowerCase(), Object.keys(CONSOLE_LEVELS));
+    throw new InvalidArgumentError(`Use error, warning, info (or log) or debug${similar.length ? ` (did you mean ${similar[0]}?)` : ''}.`);
+}
+/**
+ * Commander parser for `dom listeners --type`: comma-separated event types
+ * (case-sensitive, like `addEventListener`).
+ *
+ * @param value - Raw option value, e.g. "click,keydown"
+ * @returns Event types
+ * @throws InvalidArgumentError (exit 81) when no type is given
+ */
+export function eventTypesOption(value) {
+    const types = parseCommaSeparated(value);
+    if (types.length > 0)
+        return types;
+    throw new InvalidArgumentError('Give at least one event type, e.g. click or click,keydown.');
+}
 function parseCommaSeparated(value) {
     return value
         .split(',')
@@ -86,7 +164,8 @@ function parseCommaSeparated(value) {
         .filter((t) => t.length > 0);
 }
 function normalizeResourceType(type) {
-    return VALID_RESOURCE_TYPES.find((valid) => valid.toLowerCase() === type.toLowerCase());
+    const name = resourceTypeFromName(type) ?? type;
+    return VALID_RESOURCE_TYPES.find((valid) => valid.toLowerCase() === name.toLowerCase());
 }
 function validateResourceTypes(types) {
     const normalized = [];

package/dist/commands/start.d.ts

@@ -1,4 +1,31 @@
-import type { Command } from 'commander';
+import { type Command } from 'commander';
+/**
+ * Expand a leading `~/` in a path to the user's home directory.
+ * Chrome itself does not expand `~`, so bdg normalizes it for users.
+ */
+export declare function expandHome(value: string): string;
+/**
+ * Extract `--user-data-dir` from a flags array.
+ *
+ * Supports both `--user-data-dir=<path>` and `--user-data-dir <path>` forms.
+ * When found, returns the path (with `~/` expanded) and the remaining flags
+ * with every matching entry removed, so callers can avoid passing the same
+ * switch to Chrome twice.
+ */
+export declare function extractUserDataDirFromFlags(flags: string[]): {
+    userDataDir: string | undefined;
+    rest: string[];
+};
+/**
+ * Reject a subcommand typed without its group (`bdg query x` for
+ * `bdg dom query x`) before Commander reads it as a start URL with extra
+ * arguments.
+ *
+ * @param program - Root command with all commands registered
+ * @param argv - Process arguments
+ * @throws CommandError (81) naming the full command
+ */
+export declare function assertNotGroupSubcommand(program: Command, argv: string[]): void;
 /**
  * Register the start command
  *