browser-debugger-cli 0.7.2 → 0.9.0

package/dist/ui/messages/validation.js

@@ -3,56 +3,51 @@
  *
  * User-facing messages for input validation failures across commands.
  */
-import { joinLines } from '../../ui/formatting.js';
+import { joinLines } from '../formatting.js';
 /**
- * Generate invalid integer error message with context.
+ * Describe an integer range for error messages.
  *
- * @param fieldName - Name of the field being validated
- * @param value - The invalid value provided
- * @param options - Optional range and example information
- * @returns Formatted error message with suggestions
- *
- * @example
- * ```typescript
- * // Basic usage
- * throw new Error(invalidIntegerError('timeout', 'abc'));
- *
- * // With range
- * throw new Error(invalidIntegerError('timeout', 'abc', { min: 1, max: 3600 }));
- *
- * // With example
- * throw new Error(invalidIntegerError('port', 'xyz', { min: 1024, max: 65535, exampleValue: 9222 }));
- * ```
+ * @param options - Range bounds
+ * @returns e.g. "Valid range: 1 to 65535", or undefined without bounds
  */
-export function invalidIntegerError(fieldName, value, options) {
-    const header = `Error: Invalid ${fieldName}: "${value}" is not a valid integer`;
-    let rangeInfo;
-    if (options?.min !== undefined && options?.max !== undefined) {
-        rangeInfo = `Valid range: ${options.min} to ${options.max}`;
-    }
-    else if (options?.min !== undefined) {
-        rangeInfo = `Must be at least ${options.min}`;
+function describeRange(options) {
+    if (options?.min !== undefined && options.max !== undefined) {
+        return `Valid range: ${options.min} to ${options.max}`;
     }
-    else if (options?.max !== undefined) {
-        rangeInfo = `Must be at most ${options.max}`;
-    }
-    const example = options?.exampleValue ?? options?.min ?? 30;
-    return joinLines(header, rangeInfo, '', `Example: --${fieldName} ${example}`);
+    if (options?.min !== undefined)
+        return `Must be at least ${options.min}`;
+    if (options?.max !== undefined)
+        return `Must be at most ${options.max}`;
+    return undefined;
 }
 /**
- * Generate invalid range error message for --last option.
+ * Generate error message for a value that is not an integer.
  *
- * @param min - Minimum allowed value
- * @param max - Maximum allowed value
+ * @param value - The invalid value provided
+ * @param options - Allowed range, shown when known
+ * @param name - Option name, e.g. "--port" (defaults to "value")
  * @returns Formatted error message
  *
  * @example
  * ```typescript
- * throw new Error(invalidLastRangeError(0, 10000));
- * // "--last must be between 0 and 10000"
+ * invalidIntegerError('abc', { min: 1, max: 3600 });
+ * // 'Invalid value: "abc" is not an integer\nValid range: 1 to 3600'
+ * invalidIntegerError('abc', { min: 1, max: 65535 }, '--port');
+ * // 'Invalid --port: "abc" is not an integer\nValid range: 1 to 65535'
  * ```
  */
-export function invalidLastRangeError(min = 0, max = 10000) {
-    return `--last must be between ${min} and ${max}`;
+export function invalidIntegerError(value, options, name = 'value') {
+    return joinLines(`Invalid ${name}: "${value}" is not an integer`, describeRange(options));
+}
+/**
+ * Generate error message for an integer outside the allowed range.
+ *
+ * @param value - The out-of-range value provided
+ * @param options - Allowed range
+ * @param name - Option name, e.g. "--port" (defaults to "value")
+ * @returns Formatted error message
+ */
+export function integerOutOfRangeError(value, options, name = 'value') {
+    return joinLines(`Invalid ${name}: ${value} is out of range`, describeRange(options));
 }
 //# sourceMappingURL=validation.js.map

package/dist/utils/async.d.ts

@@ -7,4 +7,12 @@
  * @param ms - Milliseconds to delay
  */
 export declare function delay(ms: number): Promise<void>;
+/**
+ * Wait for a promise, giving up after a time; the timer is cleared either way.
+ *
+ * @param promise - Work to wait for
+ * @param ms - Milliseconds to wait at most
+ * @returns The promise's result, or undefined when the time ran out first
+ */
+export declare function raceTimeout<T>(promise: Promise<T>, ms: number): Promise<T | undefined>;
 //# sourceMappingURL=async.d.ts.map

package/dist/utils/async.js

@@ -9,4 +9,23 @@
 export function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Wait for a promise, giving up after a time; the timer is cleared either way.
+ *
+ * @param promise - Work to wait for
+ * @param ms - Milliseconds to wait at most
+ * @returns The promise's result, or undefined when the time ran out first
+ */
+export async function raceTimeout(promise, ms) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(undefined), ms);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 //# sourceMappingURL=async.js.map

package/dist/utils/atomicFile.js

@@ -1,7 +1,7 @@
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import { createLogger } from '../ui/logging/index.js';
-import { getErrorMessage } from '../utils/errors.js';
+import { getErrorMessage } from './errors.js';
 const log = createLogger('atomic-file');
 /**
  * Atomic file operations using tmp-file-then-rename pattern.

package/dist/utils/decisionTrees.js

@@ -152,7 +152,7 @@ export const DECISION_TREES = {
                 noAction: 'next',
             },
             {
-                question: 'Ready to end session and save output?',
+                question: 'Ready to end session?',
                 yesCommand: 'stop',
                 noAction: 'next',
             },

package/dist/utils/errorMapping.js

@@ -10,7 +10,7 @@
  * consistent, maintainable error handling.
  */
 import { IPCErrorCode } from '../ipc/index.js';
-import { EXIT_CODES } from '../utils/exitCodes.js';
+import { EXIT_CODES } from './exitCodes.js';
 /**
  * Map IPC error codes to semantic exit codes.
  *
@@ -29,14 +29,22 @@ export function getExitCodeForIPCError(errorCode) {
             return EXIT_CODES.RESOURCE_NOT_FOUND;
         case IPCErrorCode.SESSION_ALREADY_RUNNING:
             return EXIT_CODES.RESOURCE_ALREADY_EXISTS;
+        case IPCErrorCode.SESSION_TARGET_MISMATCH:
+            return EXIT_CODES.RESOURCE_CONFLICT;
         case IPCErrorCode.CHROME_LAUNCH_FAILED:
             return EXIT_CODES.CHROME_LAUNCH_FAILURE;
         case IPCErrorCode.CDP_TIMEOUT:
             return EXIT_CODES.CDP_TIMEOUT;
         case IPCErrorCode.SESSION_KILL_FAILED:
             return EXIT_CODES.SESSION_FILE_ERROR;
-        case IPCErrorCode.WORKER_START_FAILED:
-            return EXIT_CODES.CDP_CONNECTION_FAILURE;
+        case IPCErrorCode.NAVIGATION_FAILED:
+            return EXIT_CODES.INVALID_URL;
+        case IPCErrorCode.SESSION_START_FAILED:
+            return EXIT_CODES.SESSION_START_FAILURE;
+        case IPCErrorCode.SESSION_START_CANCELLED:
+            return EXIT_CODES.RESOURCE_CONFLICT;
+        case IPCErrorCode.SESSION_SHUTTING_DOWN:
+            return EXIT_CODES.RESOURCE_BUSY;
         case IPCErrorCode.DAEMON_ERROR:
             return EXIT_CODES.SOFTWARE_ERROR;
         case undefined:
@@ -47,7 +55,7 @@ export function getExitCodeForIPCError(errorCode) {
  * Check if error indicates socket connection failure (daemon not running).
  */
 function isSocketConnectionError(lowerMessage) {
-    return lowerMessage.includes('enoent') || lowerMessage.includes('econnrefused');
+    return /ipc .+ connection error|\bconnect (enoent|econnrefused)\b/.test(lowerMessage);
 }
 /**
  * Map connection error messages to semantic exit codes.
@@ -76,6 +84,9 @@ export function getExitCodeForConnectionError(errorMessage) {
     if (lowerMessage.includes('no active session')) {
         return EXIT_CODES.RESOURCE_NOT_FOUND;
     }
+    if (lowerMessage.includes('still starting')) {
+        return EXIT_CODES.RESOURCE_BUSY;
+    }
     if (lowerMessage.includes('timeout')) {
         return EXIT_CODES.CDP_TIMEOUT;
     }

package/dist/utils/errors.d.ts

@@ -25,4 +25,17 @@
  * ```
  */
 export declare function getErrorMessage(error: unknown): string;
+/**
+ * Read the semantic exit code carried by an error, if any.
+ *
+ * Error classes across bdg (CommandError, IPCError, DaemonError, ...) expose a
+ * numeric `exitCode`. Only integers in 1..255 are trusted, so a foreign error
+ * carrying `exitCode: 0` (or garbage) can never turn a failure into success.
+ * Anything else gets the fallback.
+ *
+ * @param error - Caught error
+ * @param fallback - Exit code when the error carries none
+ * @returns Exit code
+ */
+export declare function getErrorExitCode(error: unknown, fallback: number): number;
 //# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.js

@@ -30,4 +30,25 @@ export function getErrorMessage(error) {
     }
     return String(error);
 }
+/**
+ * Read the semantic exit code carried by an error, if any.
+ *
+ * Error classes across bdg (CommandError, IPCError, DaemonError, ...) expose a
+ * numeric `exitCode`. Only integers in 1..255 are trusted, so a foreign error
+ * carrying `exitCode: 0` (or garbage) can never turn a failure into success.
+ * Anything else gets the fallback.
+ *
+ * @param error - Caught error
+ * @param fallback - Exit code when the error carries none
+ * @returns Exit code
+ */
+export function getErrorExitCode(error, fallback) {
+    if (error instanceof Error && 'exitCode' in error) {
+        const code = error.exitCode;
+        if (typeof code === 'number' && Number.isInteger(code) && code >= 1 && code <= 255) {
+            return code;
+        }
+    }
+    return fallback;
+}
 //# sourceMappingURL=errors.js.map

package/dist/utils/exitCodes.d.ts

@@ -44,13 +44,18 @@ export declare const EXIT_CODES: {
     readonly STALE_CACHE: 87;
     readonly NO_FORMS_FOUND: 88;
     readonly FORM_IN_IFRAME: 89;
+    readonly RESOURCE_CONFLICT: 90;
+    readonly SCRIPT_ERROR: 91;
     readonly CHROME_LAUNCH_FAILURE: 100;
     readonly CDP_CONNECTION_FAILURE: 101;
     readonly CDP_TIMEOUT: 102;
     readonly SESSION_FILE_ERROR: 103;
     readonly UNHANDLED_EXCEPTION: 104;
     readonly SIGNAL_HANDLER_ERROR: 105;
+    readonly SESSION_START_FAILURE: 106;
     readonly SOFTWARE_ERROR: 110;
+    readonly INTERRUPTED: 130;
+    readonly TERMINATED: 143;
 };
 /**
  * Exit code registry entry with code, name, and description.

package/dist/utils/exitCodes.js

@@ -44,13 +44,18 @@ export const EXIT_CODES = {
     STALE_CACHE: 87,
     NO_FORMS_FOUND: 88,
     FORM_IN_IFRAME: 89,
+    RESOURCE_CONFLICT: 90,
+    SCRIPT_ERROR: 91,
     CHROME_LAUNCH_FAILURE: 100,
     CDP_CONNECTION_FAILURE: 101,
     CDP_TIMEOUT: 102,
     SESSION_FILE_ERROR: 103,
     UNHANDLED_EXCEPTION: 104,
     SIGNAL_HANDLER_ERROR: 105,
+    SESSION_START_FAILURE: 106,
     SOFTWARE_ERROR: 110,
+    INTERRUPTED: 130,
+    TERMINATED: 143,
 };
 /**
  * Exit code registry - provides documentation for all exit codes.
@@ -93,7 +98,7 @@ export const EXIT_CODE_REGISTRY = [
     {
         code: EXIT_CODES.RESOURCE_BUSY,
         name: 'RESOURCE_BUSY',
-        description: 'Resource is locked or busy',
+        description: 'Resource is locked or busy (e.g., a session still shutting down)',
     },
     {
         code: EXIT_CODES.DAEMON_ALREADY_RUNNING,
@@ -115,6 +120,16 @@ export const EXIT_CODE_REGISTRY = [
         name: 'FORM_IN_IFRAME',
         description: 'Form is inside an iframe (cross-origin or same-origin)',
     },
+    {
+        code: EXIT_CODES.RESOURCE_CONFLICT,
+        name: 'RESOURCE_CONFLICT',
+        description: 'Request conflicts with current state (e.g., session attached to different target, start cancelled by bdg stop)',
+    },
+    {
+        code: EXIT_CODES.SCRIPT_ERROR,
+        name: 'SCRIPT_ERROR',
+        description: 'The JavaScript passed to bdg dom eval threw an exception',
+    },
     {
         code: EXIT_CODES.CHROME_LAUNCH_FAILURE,
         name: 'CHROME_LAUNCH_FAILURE',
@@ -125,7 +140,11 @@ export const EXIT_CODE_REGISTRY = [
         name: 'CDP_CONNECTION_FAILURE',
         description: 'Failed to connect to Chrome DevTools Protocol',
     },
-    { code: EXIT_CODES.CDP_TIMEOUT, name: 'CDP_TIMEOUT', description: 'CDP operation timed out' },
+    {
+        code: EXIT_CODES.CDP_TIMEOUT,
+        name: 'CDP_TIMEOUT',
+        description: 'CDP operation timed out, or the session did not respond',
+    },
     {
         code: EXIT_CODES.SESSION_FILE_ERROR,
         name: 'SESSION_FILE_ERROR',
@@ -141,10 +160,25 @@ export const EXIT_CODE_REGISTRY = [
         name: 'SIGNAL_HANDLER_ERROR',
         description: 'Signal handler error',
     },
+    {
+        code: EXIT_CODES.SESSION_START_FAILURE,
+        name: 'SESSION_START_FAILURE',
+        description: 'Session failed to start (Chrome launch or CDP connection)',
+    },
     {
         code: EXIT_CODES.SOFTWARE_ERROR,
         name: 'SOFTWARE_ERROR',
         description: 'Generic software error (use specific codes when possible)',
     },
+    {
+        code: EXIT_CODES.INTERRUPTED,
+        name: 'INTERRUPTED',
+        description: 'Interrupted by Ctrl-C (128 + SIGINT); a start in progress is cancelled',
+    },
+    {
+        code: EXIT_CODES.TERMINATED,
+        name: 'TERMINATED',
+        description: 'Stopped by SIGTERM (128 + 15); a start in progress is cancelled',
+    },
 ];
 //# sourceMappingURL=exitCodes.js.map

package/dist/utils/http.d.ts

@@ -1,5 +1,16 @@
-import type { CDPTarget } from '../types';
+import type { CDPTarget } from '../types.js';
 import type { Logger } from '../ui/logging/index.js';
+/**
+ * Options for CDP HTTP target fetch.
+ */
+export interface FetchCDPTargetsOptions {
+    /** Host to reach Chrome on (defaults to HTTP_LOCALHOST). */
+    host?: string;
+    /** Request timeout in milliseconds (defaults to CDP_HTTP_TIMEOUT_MS). */
+    timeoutMs?: number;
+    /** Use HTTPS (Chrome behind a TLS proxy, reached via a `wss:` URL). */
+    secure?: boolean;
+}
 /**
  * Fetch CDP targets from Chrome's HTTP API.
  *
@@ -9,15 +20,46 @@ import type { Logger } from '../ui/logging/index.js';
  *
  * @param port - Chrome debugging port (defaults to centralized DEFAULT_CDP_PORT)
  * @param logger - Optional logger for debug output
+ * @param options - Optional host override and custom timeout (for liveness probes against remote Chrome)
  * @returns Promise resolving to array of CDP targets, or empty array on error
  *
  * @remarks
- * - Uses HTTP_LOCALHOST constant for consistent host addressing
+ * - Uses HTTP_LOCALHOST constant by default for host addressing
  * - Returns empty array on HTTP errors, but logs details for debugging
- * - 5-second timeout prevents hanging when Chrome is unreachable
+ * - Default 5-second timeout; override via `options.timeoutMs` for fast probes
  * - Network errors are logged to help diagnose Chrome connectivity issues
  */
-export declare function fetchCDPTargets(port?: number, logger?: Logger): Promise<CDPTarget[]>;
+export declare function fetchCDPTargets(port?: number, logger?: Logger, options?: FetchCDPTargetsOptions): Promise<CDPTarget[]>;
+/**
+ * What answers on a DevTools HTTP endpoint: a Chrome (with its browser-level
+ * WebSocket URL), an HTTP server that is not DevTools, or nothing.
+ */
+export type DevToolsProbe = {
+    kind: 'devtools';
+    wsUrl: string;
+} | {
+    kind: 'not-devtools';
+} | {
+    kind: 'unreachable';
+};
+/**
+ * Ask an endpoint for its DevTools version (`/json/version`).
+ *
+ * @param port - Chrome debugging port
+ * @param logger - Optional logger for debug output
+ * @param options - Host and HTTPS
+ * @returns What answered
+ */
+export declare function probeDevToolsEndpoint(port: number, logger?: Logger, options?: Pick<FetchCDPTargetsOptions, 'host' | 'secure'>): Promise<DevToolsProbe>;
+/**
+ * The browser-level DevTools WebSocket URL of a Chrome (`/json/version`).
+ *
+ * @param port - Chrome debugging port
+ * @param logger - Optional logger for debug output
+ * @param options - Host and HTTPS
+ * @returns The URL, or null if no Chrome answered
+ */
+export declare function fetchBrowserWsUrl(port: number, logger?: Logger, options?: Pick<FetchCDPTargetsOptions, 'host' | 'secure'>): Promise<string | null>;
 /**
  * Fetch specific CDP target by ID from Chrome's HTTP API.
  *
@@ -36,4 +78,14 @@ export declare function fetchCDPTargets(port?: number, logger?: Logger): Promise
  * - Inherits timeout and error logging from fetchCDPTargets
  */
 export declare function fetchCDPTargetById(targetId: string, port?: number, logger?: Logger): Promise<CDPTarget | null>;
+/**
+ * Open a new blank page in a Chrome reached over its DevTools HTTP endpoint.
+ *
+ * @param host - Chrome host
+ * @param port - Chrome debugging port
+ * @param logger - Optional logger for debug output
+ * @param options - `secure`: use HTTPS
+ * @returns The new page target, or null if Chrome could not be reached
+ */
+export declare function createPageTarget(host: string, port: number, logger?: Logger, options?: Pick<FetchCDPTargetsOptions, 'secure'>): Promise<CDPTarget | null>;
 //# sourceMappingURL=http.d.ts.map

package/dist/utils/http.js

@@ -1,4 +1,5 @@
 import { DEFAULT_CDP_PORT, HTTP_LOCALHOST } from '../constants.js';
+import { getErrorMessage } from './errors.js';
 /**
  * Timeout for CDP HTTP requests in milliseconds.
  *
@@ -15,19 +16,22 @@ const CDP_HTTP_TIMEOUT_MS = 5000;
  *
  * @param port - Chrome debugging port (defaults to centralized DEFAULT_CDP_PORT)
  * @param logger - Optional logger for debug output
+ * @param options - Optional host override and custom timeout (for liveness probes against remote Chrome)
  * @returns Promise resolving to array of CDP targets, or empty array on error
  *
  * @remarks
- * - Uses HTTP_LOCALHOST constant for consistent host addressing
+ * - Uses HTTP_LOCALHOST constant by default for host addressing
  * - Returns empty array on HTTP errors, but logs details for debugging
- * - 5-second timeout prevents hanging when Chrome is unreachable
+ * - Default 5-second timeout; override via `options.timeoutMs` for fast probes
  * - Network errors are logged to help diagnose Chrome connectivity issues
  */
-export async function fetchCDPTargets(port = DEFAULT_CDP_PORT, logger) {
-    const url = `http://${HTTP_LOCALHOST}:${port}/json/list`;
+export async function fetchCDPTargets(port = DEFAULT_CDP_PORT, logger, options) {
+    const host = options?.host ?? HTTP_LOCALHOST;
+    const timeoutMs = options?.timeoutMs ?? CDP_HTTP_TIMEOUT_MS;
+    const url = `${options?.secure ? 'https' : 'http'}://${host}:${port}/json/list`;
     try {
         const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), CDP_HTTP_TIMEOUT_MS);
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
         try {
             const response = await fetch(url, { signal: controller.signal });
             clearTimeout(timeoutId);
@@ -49,7 +53,7 @@ export async function fetchCDPTargets(port = DEFAULT_CDP_PORT, logger) {
     catch (error) {
         if (error instanceof Error) {
             if (error.name === 'AbortError') {
-                logger?.debug(`CDP HTTP request timeout after ${CDP_HTTP_TIMEOUT_MS}ms (${url})`);
+                logger?.debug(`CDP HTTP request timeout after ${timeoutMs}ms (${url})`);
             }
             else {
                 logger?.debug(`CDP HTTP request error: ${error.message} (${url})`);
@@ -58,6 +62,47 @@ export async function fetchCDPTargets(port = DEFAULT_CDP_PORT, logger) {
         return [];
     }
 }
+/**
+ * Ask an endpoint for its DevTools version (`/json/version`).
+ *
+ * @param port - Chrome debugging port
+ * @param logger - Optional logger for debug output
+ * @param options - Host and HTTPS
+ * @returns What answered
+ */
+export async function probeDevToolsEndpoint(port, logger, options) {
+    const url = `${options?.secure ? 'https' : 'http'}://${options?.host ?? HTTP_LOCALHOST}:${port}/json/version`;
+    let response;
+    try {
+        response = await fetch(url, { signal: AbortSignal.timeout(CDP_HTTP_TIMEOUT_MS) });
+    }
+    catch (error) {
+        logger?.debug(`Chrome version request failed: ${getErrorMessage(error)} (${url})`);
+        return { kind: 'unreachable' };
+    }
+    try {
+        const data = (await response.json());
+        const wsUrl = data?.webSocketDebuggerUrl;
+        if (response.ok && typeof wsUrl === 'string')
+            return { kind: 'devtools', wsUrl };
+    }
+    catch (error) {
+        logger?.debug(`Chrome version response is not JSON: ${getErrorMessage(error)} (${url})`);
+    }
+    return { kind: 'not-devtools' };
+}
+/**
+ * The browser-level DevTools WebSocket URL of a Chrome (`/json/version`).
+ *
+ * @param port - Chrome debugging port
+ * @param logger - Optional logger for debug output
+ * @param options - Host and HTTPS
+ * @returns The URL, or null if no Chrome answered
+ */
+export async function fetchBrowserWsUrl(port, logger, options) {
+    const probe = await probeDevToolsEndpoint(port, logger, options);
+    return probe.kind === 'devtools' ? probe.wsUrl : null;
+}
 /**
  * Fetch specific CDP target by ID from Chrome's HTTP API.
  *
@@ -79,4 +124,31 @@ export async function fetchCDPTargetById(targetId, port = DEFAULT_CDP_PORT, logg
     const targets = await fetchCDPTargets(port, logger);
     return targets.find((t) => t.id === targetId) ?? null;
 }
+/**
+ * Open a new blank page in a Chrome reached over its DevTools HTTP endpoint.
+ *
+ * @param host - Chrome host
+ * @param port - Chrome debugging port
+ * @param logger - Optional logger for debug output
+ * @param options - `secure`: use HTTPS
+ * @returns The new page target, or null if Chrome could not be reached
+ */
+export async function createPageTarget(host, port, logger, options) {
+    const url = `${options?.secure ? 'https' : 'http'}://${host}:${port}/json/new?about:blank`;
+    try {
+        const response = await fetch(url, {
+            method: 'PUT',
+            signal: AbortSignal.timeout(CDP_HTTP_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            logger?.debug(`Opening a page failed: ${response.status} (${url})`);
+            return null;
+        }
+        return (await response.json());
+    }
+    catch (error) {
+        logger?.debug(`Opening a page failed: ${getErrorMessage(error)} (${url})`);
+        return null;
+    }
+}
 //# sourceMappingURL=http.js.map

package/dist/utils/packageRoot.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Package root resolution.
+ *
+ * Paths to package files (package.json, dist/daemon.js) are resolved from the
+ * package root rather than relative to the calling module, so they stay
+ * correct whether the code runs from tsc output, the bundled CLI, or source.
+ */
+/** Absolute path of the bdg package root. */
+export declare const PACKAGE_ROOT: string;
+/** Absolute path of the daemon entry script. */
+export declare const DAEMON_SCRIPT_PATH: string;
+//# sourceMappingURL=packageRoot.d.ts.map

package/dist/utils/packageRoot.js

@@ -0,0 +1,33 @@
+/**
+ * Package root resolution.
+ *
+ * Paths to package files (package.json, dist/daemon.js) are resolved from the
+ * package root rather than relative to the calling module, so they stay
+ * correct whether the code runs from tsc output, the bundled CLI, or source.
+ */
+import { existsSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+/**
+ * Walk up from a directory to the nearest one containing package.json.
+ *
+ * @param startDir - Directory to start searching from
+ * @returns Absolute path of the package root
+ * @throws Error when no package.json exists in any ancestor
+ */
+function findPackageRoot(startDir) {
+    let dir = startDir;
+    while (!existsSync(join(dir, 'package.json'))) {
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new Error(`package.json not found above ${startDir}`);
+        }
+        dir = parent;
+    }
+    return dir;
+}
+/** Absolute path of the bdg package root. */
+export const PACKAGE_ROOT = findPackageRoot(dirname(fileURLToPath(import.meta.url)));
+/** Absolute path of the daemon entry script. */
+export const DAEMON_SCRIPT_PATH = join(PACKAGE_ROOT, 'dist', 'daemon.js');
+//# sourceMappingURL=packageRoot.js.map

package/dist/utils/process.d.ts

@@ -42,4 +42,14 @@ export declare function isProcessAlive(pid: number): boolean;
  * ```
  */
 export declare function killChromeProcess(pid: number, signal?: NodeJS.Signals): void;
+/**
+ * Read a process's full command line.
+ *
+ * Uses `/proc/<pid>/cmdline` where available (Linux, including minimal
+ * containers whose BusyBox `ps` lacks `-o`/`-p`), and `ps` elsewhere (macOS).
+ *
+ * @param pid - Process ID
+ * @returns Command line, or null if unavailable (process gone, or unsupported platform)
+ */
+export declare function getProcessCommand(pid: number): string | null;
 //# sourceMappingURL=process.d.ts.map