browser-debugger-cli 0.7.1 → 0.8.0

package/dist/session/cleanup/userCommands.js

@@ -0,0 +1,95 @@
+/**
+ * Cleanup behind the user-facing `bdg cleanup` command.
+ */
+import * as fs from 'fs';
+import { killOrphanedChrome, readLiveDaemonPid, removeStaleDaemonFiles, } from './staleSession.js';
+import { isDaemonAlive } from '../daemonSocket.js';
+import { clearLastSessionEnd } from '../lastSession.js';
+import { getSessionFilePath } from '../paths.js';
+import { createLogger } from '../../ui/logging/index.js';
+import { getErrorMessage } from '../../utils/errors.js';
+const log = createLogger('cleanup');
+const DAEMON_EXIT_WAIT_MS = 2000;
+/**
+ * Clean up session state.
+ *
+ * With `force`, a live daemon is killed first (after verifying its command
+ * line). Then stale daemon files are removed and an orphaned bdg Chrome, if
+ * any, is killed.
+ *
+ * @param options - Cleanup options
+ * @returns What was cleaned, plus warnings
+ */
+export async function performSessionCleanup(options) {
+    const warnings = [];
+    const filesBefore = countSessionFiles();
+    const daemonKilled = options.force ? await killLiveDaemon(warnings) : false;
+    const session = await removeStaleDaemonFiles();
+    const chrome = killOrphanedChrome();
+    const output = options.removeOutput ? removeOutputFile(warnings) : false;
+    const filesRemoved = countSessionFiles() < filesBefore;
+    clearLastSessionEnd();
+    return {
+        cleaned: {
+            session: session || daemonKilled || filesRemoved,
+            chrome,
+            daemons: daemonKilled,
+            output,
+        },
+        warnings,
+    };
+}
+/** Files a session leaves behind (stale ones are what cleanup removes) */
+const SESSION_FILE_TYPES = ['DAEMON_PID', 'DAEMON_SOCKET', 'CHROME_PID', 'METADATA'];
+/**
+ * How many session files exist.
+ *
+ * @returns Number of existing session files
+ */
+function countSessionFiles() {
+    return SESSION_FILE_TYPES.filter((type) => fs.existsSync(getSessionFilePath(type))).length;
+}
+/**
+ * SIGKILL a live bdg daemon and wait briefly for its socket to go away.
+ *
+ * @param warnings - Collector for non-fatal problems
+ * @returns True if a daemon was killed
+ */
+async function killLiveDaemon(warnings) {
+    const pid = readLiveDaemonPid();
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 'SIGKILL');
+        log.info(`Killed daemon (PID ${pid})`);
+    }
+    catch (error) {
+        warnings.push(`Could not kill daemon ${pid}: ${getErrorMessage(error)}`);
+        return false;
+    }
+    const deadline = Date.now() + DAEMON_EXIT_WAIT_MS;
+    while (Date.now() < deadline && (await isDaemonAlive())) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return true;
+}
+/**
+ * Remove the legacy session.json output file.
+ *
+ * @param warnings - Collector for non-fatal problems
+ * @returns True if the file was removed
+ */
+function removeOutputFile(warnings) {
+    const outputPath = getSessionFilePath('OUTPUT');
+    if (!fs.existsSync(outputPath))
+        return false;
+    try {
+        fs.unlinkSync(outputPath);
+        return true;
+    }
+    catch (error) {
+        warnings.push(`Could not remove session.json: ${getErrorMessage(error)}`);
+        return false;
+    }
+}
+//# sourceMappingURL=userCommands.js.map

package/dist/session/daemonSocket.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Daemon liveness via its Unix socket.
+ *
+ * The socket is the single source of truth: if a connection succeeds the
+ * daemon is alive, if it is refused the socket file is stale. PID files are
+ * never used to decide liveness.
+ */
+/** Result of probing the daemon socket. */
+export type SocketProbeResult = 'alive' | 'stale' | 'absent';
+/**
+ * Probe a Unix socket path.
+ *
+ * @param socketPath - Socket path (defaults to the session's daemon socket)
+ * @param timeoutMs - Connection timeout
+ * @returns 'alive' if a server accepted the connection, 'absent' if there is no
+ *   socket file, 'stale' if the file exists but nothing is listening
+ */
+export declare function probeDaemonSocket(socketPath?: string, timeoutMs?: number): Promise<SocketProbeResult>;
+/**
+ * Check whether the daemon is accepting connections.
+ *
+ * @returns True if the daemon socket accepts a connection
+ */
+export declare function isDaemonAlive(): Promise<boolean>;
+//# sourceMappingURL=daemonSocket.d.ts.map

package/dist/session/daemonSocket.js

@@ -0,0 +1,40 @@
+/**
+ * Daemon liveness via its Unix socket.
+ *
+ * The socket is the single source of truth: if a connection succeeds the
+ * daemon is alive, if it is refused the socket file is stale. PID files are
+ * never used to decide liveness.
+ */
+import * as net from 'net';
+import { getSessionFilePath } from './paths.js';
+const PROBE_TIMEOUT_MS = 1000;
+/**
+ * Probe a Unix socket path.
+ *
+ * @param socketPath - Socket path (defaults to the session's daemon socket)
+ * @param timeoutMs - Connection timeout
+ * @returns 'alive' if a server accepted the connection, 'absent' if there is no
+ *   socket file, 'stale' if the file exists but nothing is listening
+ */
+export function probeDaemonSocket(socketPath = getSessionFilePath('DAEMON_SOCKET'), timeoutMs = PROBE_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        const socket = net.createConnection(socketPath);
+        const finish = (result) => {
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(result);
+        };
+        const timer = setTimeout(() => finish('stale'), timeoutMs);
+        socket.once('connect', () => finish('alive'));
+        socket.once('error', (error) => finish(error.code === 'ENOENT' ? 'absent' : 'stale'));
+    });
+}
+/**
+ * Check whether the daemon is accepting connections.
+ *
+ * @returns True if the daemon socket accepts a connection
+ */
+export async function isDaemonAlive() {
+    return (await probeDaemonSocket()) === 'alive';
+}
+//# sourceMappingURL=daemonSocket.js.map

package/dist/session/lastSession.d.ts

@@ -0,0 +1,29 @@
+/**
+ * How the last session ended, when it did not end by `bdg stop`: kept so
+ * `bdg status` can explain why there is no session any more.
+ */
+/** Why a session ended without `bdg stop` */
+export type UnexpectedEndReason = 'crash' | 'closed' | 'timeout';
+/** Record of the last session's unexpected end */
+export interface LastSessionEnd {
+    reason: UnexpectedEndReason;
+    /** Epoch ms */
+    endedAt: number;
+}
+/**
+ * Record how the session ended.
+ *
+ * @param reason - Why it ended
+ */
+export declare function writeLastSessionEnd(reason: UnexpectedEndReason): void;
+/**
+ * Forget the last session's end (a new session is starting, or `cleanup` ran).
+ */
+export declare function clearLastSessionEnd(): void;
+/**
+ * How the last session ended, if it ended unexpectedly.
+ *
+ * @returns The record, or null
+ */
+export declare function readLastSessionEnd(): LastSessionEnd | null;
+//# sourceMappingURL=lastSession.d.ts.map

package/dist/session/lastSession.js

@@ -0,0 +1,45 @@
+/**
+ * How the last session ended, when it did not end by `bdg stop`: kept so
+ * `bdg status` can explain why there is no session any more.
+ */
+import * as fs from 'fs';
+import { getSessionFilePath } from './paths.js';
+import { createLogger } from '../ui/logging/index.js';
+import { AtomicFileWriter } from '../utils/atomicFile.js';
+import { getErrorMessage } from '../utils/errors.js';
+const log = createLogger('session');
+/**
+ * Record how the session ended.
+ *
+ * @param reason - Why it ended
+ */
+export function writeLastSessionEnd(reason) {
+    try {
+        AtomicFileWriter.writeSync(getSessionFilePath('LAST_SESSION'), JSON.stringify({ reason, endedAt: Date.now() }));
+    }
+    catch (error) {
+        log.debug(`Could not record how the session ended: ${getErrorMessage(error)}`);
+    }
+}
+/**
+ * Forget the last session's end (a new session is starting, or `cleanup` ran).
+ */
+export function clearLastSessionEnd() {
+    fs.rmSync(getSessionFilePath('LAST_SESSION'), { force: true });
+}
+/**
+ * How the last session ended, if it ended unexpectedly.
+ *
+ * @returns The record, or null
+ */
+export function readLastSessionEnd() {
+    try {
+        const data = JSON.parse(fs.readFileSync(getSessionFilePath('LAST_SESSION'), 'utf8'));
+        return typeof data.endedAt === 'number' ? data : null;
+    }
+    catch (error) {
+        log.debug(`No record of the last session's end: ${getErrorMessage(error)}`);
+        return null;
+    }
+}
+//# sourceMappingURL=lastSession.js.map

package/dist/session/metadata.d.ts

@@ -4,7 +4,7 @@
  * Handles reading/writing session metadata (Chrome PID, CDP port, target info, etc).
  * WHY: Metadata persistence enables `bdg status` and other commands to inspect active sessions.
  */
-import type { TelemetryType } from '../types';
+import type { TelemetryType } from '../types.js';
 /**
  * Session metadata stored in ~/.bdg/session.meta.json
  */
@@ -16,6 +16,8 @@ export interface SessionMetadata {
     targetId?: string | undefined;
     webSocketDebuggerUrl?: string | undefined;
     activeTelemetry?: TelemetryType[] | undefined;
+    /** When `--timeout` stops the session (epoch ms) */
+    autoStopAt?: number | undefined;
 }
 /**
  * Options for reading session metadata.

package/dist/session/paths.d.ts

@@ -9,15 +9,13 @@
  * Centralized definition for all session-related files.
  */
 declare const SESSION_FILES: {
-    readonly PID: "session.pid";
     readonly OUTPUT: "session.json";
-    readonly LOCK: "session.lock";
     readonly METADATA: "session.meta.json";
     readonly CHROME_PID: "chrome.pid";
     readonly DAEMON_PID: "daemon.pid";
     readonly DAEMON_SOCKET: "daemon.sock";
-    readonly DAEMON_LOCK: "daemon.lock";
     readonly PORT: "port.txt";
+    readonly LAST_SESSION: "last-session.json";
 };
 /**
  * Session file type for type-safe path generation
@@ -39,7 +37,7 @@ export declare function getSessionDir(): string;
  *
  * @example
  * ```typescript
- * getSessionFilePath('PID')        // → ~/.bdg/session.pid
+ * getSessionFilePath('METADATA')   // → ~/.bdg/session.meta.json
  * getSessionFilePath('DAEMON_PID') // → ~/.bdg/daemon.pid
  * ```
  */

package/dist/session/paths.js

@@ -12,15 +12,13 @@ import * as path from 'path';
  * Centralized definition for all session-related files.
  */
 const SESSION_FILES = {
-    PID: 'session.pid',
     OUTPUT: 'session.json',
-    LOCK: 'session.lock',
     METADATA: 'session.meta.json',
     CHROME_PID: 'chrome.pid',
     DAEMON_PID: 'daemon.pid',
     DAEMON_SOCKET: 'daemon.sock',
-    DAEMON_LOCK: 'daemon.lock',
     PORT: 'port.txt',
+    LAST_SESSION: 'last-session.json',
 };
 const SESSION_DIR_OVERRIDE_ENV = 'BDG_SESSION_DIR';
 /**
@@ -45,7 +43,7 @@ export function getSessionDir() {
  *
  * @example
  * ```typescript
- * getSessionFilePath('PID')        // → ~/.bdg/session.pid
+ * getSessionFilePath('METADATA')   // → ~/.bdg/session.meta.json
  * getSessionFilePath('DAEMON_PID') // → ~/.bdg/daemon.pid
  * ```
  */

package/dist/session/pid.d.ts

@@ -1,55 +1,26 @@
 /**
- * Session PID file management.
+ * PID file reading.
  *
- * Handles reading/writing the main session PID file for tracking active sessions.
- * WHY: Centralized PID operations prevent inconsistencies in session tracking.
+ * PID files are informational only: liveness is decided by the daemon socket
+ * (see daemonSocket.ts). A PID read here must be verified (e.g. by command
+ * line) before it is used to signal a process.
  */
 /**
- * Read and parse a PID from a file.
+ * Read a positive integer PID from a file.
  *
  * @param filePath - Path to the PID file
- * @returns Parsed PID or null if file doesn't exist or contains invalid data
+ * @returns PID, or null if the file is missing or does not hold a positive integer
  *
  * @example
  * ```typescript
  * const daemonPid = readPidFromFile('/path/to/daemon.pid');
- * if (daemonPid && isProcessAlive(daemonPid)) {
- *   console.log('Daemon is running');
- * }
  * ```
  */
 export declare function readPidFromFile(filePath: string): number | null;
 /**
- * Write the current process PID to the session file atomically.
+ * Read the daemon PID file.
  *
- * Uses atomic write (tmp file + rename) to prevent corruption if process crashes.
- *
- * @param pid - Process ID to write
- *
- * @example
- * ```typescript
- * writePid(process.pid);
- * ```
- */
-export declare function writePid(pid: number): void;
-/**
- * Read the PID from the session file.
- *
- * @returns The PID if file exists and is valid, null otherwise
- *
- * @example
- * ```typescript
- * const sessionPid = readPid();
- * if (sessionPid && isProcessAlive(sessionPid)) {
- *   console.log('Session is running');
- * }
- * ```
- */
-export declare function readPid(): number | null;
-/**
- * Remove the PID file.
- *
- * Safe to call multiple times (idempotent).
+ * @returns Daemon PID, or null if unavailable
  */
-export declare function cleanupPidFile(): void;
+export declare function readDaemonPid(): number | null;
 //# sourceMappingURL=pid.d.ts.map

package/dist/session/pid.js

@@ -1,91 +1,41 @@
 /**
- * Session PID file management.
+ * PID file reading.
  *
- * Handles reading/writing the main session PID file for tracking active sessions.
- * WHY: Centralized PID operations prevent inconsistencies in session tracking.
+ * PID files are informational only: liveness is decided by the daemon socket
+ * (see daemonSocket.ts). A PID read here must be verified (e.g. by command
+ * line) before it is used to signal a process.
  */
 import * as fs from 'fs';
-import { createLogger } from '../ui/logging/index.js';
-import { AtomicFileWriter } from '../utils/atomicFile.js';
-import { getErrorMessage } from '../utils/errors.js';
-import { getSessionFilePath, ensureSessionDir } from './paths.js';
-const log = createLogger('session');
+import { getSessionFilePath } from './paths.js';
 /**
- * Read and parse a PID from a file.
+ * Read a positive integer PID from a file.
  *
  * @param filePath - Path to the PID file
- * @returns Parsed PID or null if file doesn't exist or contains invalid data
+ * @returns PID, or null if the file is missing or does not hold a positive integer
  *
  * @example
  * ```typescript
  * const daemonPid = readPidFromFile('/path/to/daemon.pid');
- * if (daemonPid && isProcessAlive(daemonPid)) {
- *   console.log('Daemon is running');
- * }
  * ```
  */
 export function readPidFromFile(filePath) {
-    if (!fs.existsSync(filePath)) {
-        return null;
-    }
     try {
         const pidStr = fs.readFileSync(filePath, 'utf-8').trim();
-        const pid = parseInt(pidStr, 10);
-        if (Number.isNaN(pid)) {
+        if (!/^\d+$/.test(pidStr))
             return null;
-        }
-        return pid;
+        const pid = Number(pidStr);
+        return pid > 0 ? pid : null;
     }
     catch {
         return null;
     }
 }
 /**
- * Write the current process PID to the session file atomically.
- *
- * Uses atomic write (tmp file + rename) to prevent corruption if process crashes.
- *
- * @param pid - Process ID to write
- *
- * @example
- * ```typescript
- * writePid(process.pid);
- * ```
- */
-export function writePid(pid) {
-    ensureSessionDir();
-    const pidPath = getSessionFilePath('PID');
-    AtomicFileWriter.writeSync(pidPath, pid.toString());
-}
-/**
- * Read the PID from the session file.
+ * Read the daemon PID file.
  *
- * @returns The PID if file exists and is valid, null otherwise
- *
- * @example
- * ```typescript
- * const sessionPid = readPid();
- * if (sessionPid && isProcessAlive(sessionPid)) {
- *   console.log('Session is running');
- * }
- * ```
+ * @returns Daemon PID, or null if unavailable
  */
-export function readPid() {
-    const pidPath = getSessionFilePath('PID');
-    return readPidFromFile(pidPath);
-}
-/**
- * Remove the PID file.
- *
- * Safe to call multiple times (idempotent).
- */
-export function cleanupPidFile() {
-    const pidPath = getSessionFilePath('PID');
-    try {
-        fs.rmSync(pidPath, { force: true });
-    }
-    catch (error) {
-        log.debug(`Failed to cleanup PID file: ${getErrorMessage(error)}`);
-    }
+export function readDaemonPid() {
+    return readPidFromFile(getSessionFilePath('DAEMON_PID'));
 }
 //# sourceMappingURL=pid.js.map

package/dist/session/port.d.ts

@@ -33,9 +33,4 @@ export declare function writeSessionPort(port: number): void;
  * @returns Promise resolving to the port to use
  */
 export declare function getSessionPort(explicitPort?: number | null): Promise<number>;
-/**
- * Clear the saved port from the session directory.
- * Called during session cleanup.
- */
-export declare function clearSessionPort(): void;
 //# sourceMappingURL=port.d.ts.map

package/dist/session/port.js

@@ -7,8 +7,11 @@
  */
 import * as fs from 'fs';
 import * as net from 'net';
+import { isPortAnswering } from '../connection/portReservation.js';
 import { DEFAULT_CDP_PORT } from '../constants.js';
-import { ensureSessionDir, getSessionFilePath } from '../session/paths.js';
+import { CommandError } from '../errors/index.js';
+import { ensureSessionDir, getSessionFilePath } from './paths.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
 /**
  * Port range for automatic selection.
  * Starting from DEFAULT_CDP_PORT, scan up to find available ports.
@@ -16,12 +19,15 @@ import { ensureSessionDir, getSessionFilePath } from '../session/paths.js';
 const PORT_RANGE_START = DEFAULT_CDP_PORT;
 const PORT_RANGE_END = 9322; // Allow 100 ports for concurrent sessions
 /**
- * Check if a port is available (not in use by any process).
+ * Check if a port is available (not in use by any process, including one
+ * listening on all interfaces).
  *
  * @param port - Port number to check
  * @returns Promise resolving to true if port is available
  */
 async function isPortAvailable(port) {
+    if (await isPortAnswering(port))
+        return false;
     return new Promise((resolve) => {
         const server = net.createServer();
         server.once('error', () => {
@@ -47,8 +53,7 @@ async function findAvailablePort(startPort = PORT_RANGE_START) {
             return port;
         }
     }
-    throw new Error(`No available port found in range ${PORT_RANGE_START}-${PORT_RANGE_END}. ` +
-        `Try stopping some bdg sessions or Chrome instances.`);
+    throw new CommandError(`No available port found in range ${PORT_RANGE_START}-${PORT_RANGE_END}.`, { suggestion: 'Stop some bdg sessions or Chrome instances and retry.' }, EXIT_CODES.SOFTWARE_ERROR);
 }
 /**
  * Read the saved port from the session directory.
@@ -116,19 +121,4 @@ export async function getSessionPort(explicitPort) {
     writeSessionPort(newPort);
     return newPort;
 }
-/**
- * Clear the saved port from the session directory.
- * Called during session cleanup.
- */
-export function clearSessionPort() {
-    try {
-        const portPath = getSessionFilePath('PORT');
-        if (fs.existsSync(portPath)) {
-            fs.unlinkSync(portPath);
-        }
-    }
-    catch {
-        // Ignore cleanup errors
-    }
-}
 //# sourceMappingURL=port.js.map

package/dist/telemetry/a11y.d.ts

@@ -1,9 +1,12 @@
 import type { Protocol } from '../connection/typed-cdp.js';
-import type { A11yNode, A11yTree, A11yQueryPattern, A11yQueryResult } from '../types.js';
+import type { A11yNode, A11yTree, A11yQueryPattern, A11yQueryResult, NodeRef } from '../types.js';
 /**
  * Builds accessibility tree from raw CDP nodes.
  *
  * Pure function that filters out ignored nodes and builds the tree structure.
+ * Children that are ignored are replaced by their own non-ignored children
+ * (as DevTools shows the tree), so every `childIds` entry is in `nodes`, and
+ * nodes are listed depth-first from the root (document order).
  * Separated from collectA11yTree for easier unit testing.
  *
  * @param rawNodes - Raw AXNode array from CDP
@@ -14,7 +17,7 @@ export declare function buildTreeFromRawNodes(rawNodes: Protocol.Accessibility.A
 /**
  * Collects the full accessibility tree from the page via IPC.
  *
- * Uses the worker's persistent CDP connection through callCDP for consistency
+ * Uses the session's persistent CDP connection through callCDP for consistency
  * with other DOM commands and to avoid connection conflicts.
  *
  * @returns Parsed and filtered accessibility tree
@@ -46,36 +49,39 @@ export declare function queryA11yTree(tree: A11yTree, pattern: A11yQueryPattern)
 /**
  * Parses query pattern string into A11yQueryPattern object.
  *
- * Supports format: "role:button name:Submit description:Main"
- * Also accepts = as separator: "role=button name=Submit"
- * Fields are separated by spaces, case-insensitive.
+ * Fields are `key:value` or `key=value`, separated by spaces or commas.
+ * Values may contain spaces (quote them if they contain `key:`-like text).
+ * Keys: role, name, description (desc). Case-insensitive.
  *
  * @param patternString - Query pattern string
  * @returns Parsed query pattern
+ * @throws CommandError (81) for unknown keys
  *
  * @example
  * ```typescript
- * parseQueryPattern('role:button name:Submit')
- * // => { role: 'button', name: 'Submit' }
- *
- * parseQueryPattern('role=heading')
- * // => { role: 'heading' }
- *
- * parseQueryPattern('name:Email')
- * // => { name: 'Email' }
+ * parseQueryPattern('role:button name:Submit')     // { role: 'button', name: 'Submit' }
+ * parseQueryPattern('role=link,name=Google Chrome') // { role: 'link', name: 'Google Chrome' }
+ * parseQueryPattern('name:"Sign in" role:button')  // { name: 'Sign in', role: 'button' }
  * ```
  */
 export declare function parseQueryPattern(patternString: string): A11yQueryPattern;
 /**
- * Resolve accessibility properties for a DOM node by CSS selector or nodeId via IPC.
+ * Resolve accessibility properties for a DOM node via IPC.
  *
- * Uses the worker's persistent CDP connection through callCDP for consistency.
- * Supports direct nodeId lookup (bypassing selector) for index-based access patterns.
+ * Uses the session's persistent CDP connection through callCDP for consistency.
+ * Selectors are resolved by the caller (see `resolveBackendNodeIds`), so they
+ * reach shadow roots and same-origin iframes like every other DOM command.
  *
- * @param selector - CSS selector (ignored if nodeId provided)
- * @param nodeId - Optional nodeId to use directly instead of querying by selector
+ * @param target - Node reference
  * @returns A11y node or null if not found
- * @throws Error if selector is invalid or element not found
  */
-export declare function resolveA11yNode(selector: string, nodeId?: number): Promise<A11yNode | null>;
+export declare function resolveA11yNode(target: NodeRef): Promise<A11yNode | null>;
+/**
+ * Why an element has no node in the accessibility tree (e.g. it is not
+ * rendered, aria-hidden, or a decorative image with `alt=""`).
+ *
+ * @param target - Node reference
+ * @returns Chrome's reasons in plain words (empty if unknown)
+ */
+export declare function a11yIgnoredReasons(target: NodeRef): Promise<string[]>;
 //# sourceMappingURL=a11y.d.ts.map