browser-debugger-cli 0.7.2 → 0.9.0

package/dist/session/cleanup/staleSession.js

@@ -0,0 +1,135 @@
+/**
+ * Cleanup of state left behind by a daemon that died without tearing down.
+ *
+ * A healthy daemon removes its own files on exit. These helpers only matter
+ * after a crash or SIGKILL. Processes are signalled only after their command
+ * line confirms they are what the PID file claims, so a reused PID can never
+ * get an unrelated process killed.
+ */
+import { chromeSessionMarkerFlag } from '../../connection/launcher/flagsBuilder.js';
+import { QueryCacheManager } from '../QueryCacheManager.js';
+import { clearChromePid, readChromePid } from '../chrome.js';
+import { probeDaemonSocket } from '../daemonSocket.js';
+import { getSessionDir, getSessionFilePath, sessionFilePathIn } from '../paths.js';
+import { readPidFromFile } from '../pid.js';
+import { createLogger, logDebugError } from '../../ui/logging/index.js';
+import { delay } from '../../utils/async.js';
+import { safeRemoveFile } from '../../utils/file.js';
+import { DAEMON_SCRIPT_PATH } from '../../utils/packageRoot.js';
+import { getProcessCommand, isProcessAlive, killChromeProcess } from '../../utils/process.js';
+const log = createLogger('cleanup');
+/**
+ * Check whether a process command line contains an exact argument.
+ *
+ * @param command - Full command line
+ * @param arg - Argument to look for
+ * @returns True if `arg` appears as a whole space-delimited argument
+ */
+function hasArgument(command, arg) {
+    if (!command)
+        return false;
+    return command.includes(`${arg} `) || command.endsWith(arg);
+}
+/**
+ * Remove per-session files (metadata, query cache).
+ *
+ * Called by the daemon when its session ends, and by `bdg cleanup`.
+ */
+export function removeSessionFiles() {
+    safeRemoveFile(getSessionFilePath('METADATA'), 'metadata file', log);
+    void QueryCacheManager.getInstance()
+        .clear()
+        .catch((error) => logDebugError(log, 'clear query cache', error));
+}
+/**
+ * Remove daemon and session files if no daemon is listening.
+ *
+ * @returns True if a stale daemon socket was found and cleaned up
+ */
+export async function removeStaleDaemonFiles() {
+    const probe = await probeDaemonSocket();
+    if (probe === 'alive')
+        return false;
+    safeRemoveFile(getSessionFilePath('DAEMON_SOCKET'), 'daemon socket', log);
+    safeRemoveFile(getSessionFilePath('DAEMON_PID'), 'daemon PID file', log);
+    removeSessionFiles();
+    return probe === 'stale';
+}
+/**
+ * The Chrome recorded in chrome.pid, if it is still running and still the
+ * Chrome bdg launched for this session directory (verified by its marker
+ * flag). A PID that now belongs to another process is dropped.
+ *
+ * @returns Chrome PID, or null
+ */
+export function findOrphanedChrome() {
+    const chromePid = readChromePid();
+    if (!chromePid)
+        return null;
+    if (isSessionChrome(chromePid, getSessionDir()))
+        return chromePid;
+    log.debug(`PID ${chromePid} is no longer a bdg Chrome; dropping chrome.pid`);
+    clearChromePid();
+    return null;
+}
+/**
+ * Whether a process is the Chrome bdg launched for a session directory: its
+ * command line carries the directory's marker flag.
+ *
+ * @param pid - Process ID
+ * @param sessionDir - Session directory
+ * @returns True for that session's Chrome
+ */
+export function isSessionChrome(pid, sessionDir) {
+    return hasArgument(getProcessCommand(pid), chromeSessionMarkerFlag(sessionDir));
+}
+/**
+ * Kill the Chrome recorded in chrome.pid, if it is still the Chrome bdg launched
+ * for this session directory (verified by its marker flag).
+ *
+ * @returns True if a Chrome process was killed
+ */
+export function killOrphanedChrome() {
+    const chromePid = findOrphanedChrome();
+    if (!chromePid)
+        return false;
+    log.info(`Killing orphaned Chrome (PID ${chromePid})`);
+    try {
+        killChromeProcess(chromePid, 'SIGKILL');
+    }
+    catch (error) {
+        logDebugError(log, `kill Chrome ${chromePid}`, error);
+    }
+    clearChromePid();
+    return true;
+}
+/** How long to wait for a killed orphaned Chrome to exit (and free its port) */
+const ORPHAN_EXIT_WAIT_MS = 5000;
+/**
+ * Kill an orphaned Chrome (see {@link killOrphanedChrome}) and wait until it
+ * has exited, so its debugging port is free for the next launch.
+ *
+ * @returns True if a Chrome process was killed
+ */
+export async function reapOrphanedChrome() {
+    const chromePid = findOrphanedChrome();
+    if (!killOrphanedChrome() || chromePid === null)
+        return false;
+    const deadline = Date.now() + ORPHAN_EXIT_WAIT_MS;
+    while (isProcessAlive(chromePid) && Date.now() < deadline)
+        await delay(50);
+    return true;
+}
+/**
+ * Read the PID of a live bdg daemon from daemon.pid.
+ *
+ * @param dir - Session directory (defaults to the selected session's)
+ * @returns Daemon PID if the process is alive and is a bdg daemon, else null
+ */
+export function readLiveDaemonPid(dir = getSessionDir()) {
+    const pid = readPidFromFile(sessionFilePathIn(dir, 'DAEMON_PID'));
+    if (!pid || !isProcessAlive(pid))
+        return null;
+    return hasArgument(getProcessCommand(pid), DAEMON_SCRIPT_PATH) ? pid : null;
+}
+//# sourceMappingURL=staleSession.js.map

package/dist/session/cleanup/userCommands.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Cleanup behind the user-facing `bdg cleanup` command.
+ */
+/**
+ * Options for session cleanup.
+ */
+export interface SessionCleanupOptions {
+    /** Kill a running (possibly hung) daemon before cleaning */
+    force?: boolean | undefined;
+    /** Also remove the legacy session.json output file */
+    removeOutput?: boolean | undefined;
+}
+/**
+ * Result of session cleanup.
+ */
+export interface SessionCleanupResult {
+    cleaned: {
+        session: boolean;
+        chrome: boolean;
+        daemons: boolean;
+        output: boolean;
+    };
+    warnings: string[];
+}
+/**
+ * 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 declare function performSessionCleanup(options: SessionCleanupOptions): Promise<SessionCleanupResult>;
+//# sourceMappingURL=userCommands.d.ts.map

package/dist/session/cleanup/userCommands.js

@@ -0,0 +1,93 @@
+/**
+ * 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 { SESSION_STATE_FILES, 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,
+    };
+}
+/**
+ * How many session files exist.
+ *
+ * @returns Number of existing session files
+ */
+function countSessionFiles() {
+    return SESSION_STATE_FILES.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 { ColorScheme, TelemetryType, ViewportSize } from '../types.js';
 /**
  * Session metadata stored in ~/.bdg/session.meta.json
  */
@@ -16,6 +16,12 @@ export interface SessionMetadata {
     targetId?: string | undefined;
     webSocketDebuggerUrl?: string | undefined;
     activeTelemetry?: TelemetryType[] | undefined;
+    /** When `--timeout` stops the session (epoch ms) */
+    autoStopAt?: number | undefined;
+    /** Viewport the page is emulated at (`--viewport`) */
+    viewport?: ViewportSize | undefined;
+    /** `prefers-color-scheme` the page is emulated with (`--color-scheme`) */
+    colorScheme?: ColorScheme | undefined;
 }
 /**
  * Options for reading session metadata.

package/dist/session/metadata.js

@@ -6,6 +6,7 @@
  */
 import * as fs from 'fs';
 import { createLogger } from '../ui/logging/index.js';
+import { sessionCommand } from '../ui/messages/sessionCommand.js';
 import { AtomicFileWriter } from '../utils/atomicFile.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { getSessionFilePath, ensureSessionDir } from './paths.js';
@@ -20,7 +21,7 @@ const log = createLogger('session');
 function handleCorruptedMetadata(metaPath, error, options) {
     if (options?.warnOnCorruption) {
         log.info(`Session metadata corrupted (cannot read details): ${getErrorMessage(error)}`);
-        log.info('Troubleshooting: Run "bdg cleanup" to remove corrupted files');
+        log.info(`Troubleshooting: Run "${sessionCommand('bdg cleanup')}" to remove corrupted files`);
     }
     if (options?.selfHealOnCorruption) {
         try {

package/dist/session/paths.d.ts

@@ -2,6 +2,7 @@
  * Session path generation and management.
  *
  * Centralized path generation for all session-related files in ~/.bdg/
+ * (or `~/.bdg/sessions/<name>/` for a named session).
  * WHY: Single source of truth for file locations prevents path inconsistencies.
  */
 /**
@@ -9,28 +10,99 @@
  * 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";
 };
+/** Environment variable holding the selected session name (set by `--session`) */
+export declare const SESSION_NAME_ENV = "BDG_SESSION";
+/** Longest Unix socket path (sun_path is 104 bytes on macOS, 108 on Linux, NUL included) */
+export declare const MAX_SOCKET_PATH_BYTES: number;
+/**
+ * Longest public daemon socket path: the daemon first listens on
+ * `<path>.<pid>` and then links it into place, so the pid suffix (up to 7
+ * digits) must fit too.
+ */
+export declare const MAX_DAEMON_SOCKET_PATH_BYTES: number;
+/**
+ * A session directory: the default session (`name` null) or a named one.
+ */
+export interface SessionDirEntry {
+    /** Session name, or null for the default session */
+    name: string | null;
+    /** Absolute session directory */
+    dir: string;
+}
 /**
  * Session file type for type-safe path generation
  */
 export type SessionFileType = keyof typeof SESSION_FILES;
 /**
- * Get the session directory path (~/.bdg)
+ * Files a running session keeps in its directory; left behind (stale) when
+ * its daemon dies without tearing down.
+ */
+export declare const SESSION_STATE_FILES: readonly ["DAEMON_PID", "DAEMON_SOCKET", "CHROME_PID", "METADATA"];
+/**
+ * Get the base session directory: `$BDG_SESSION_DIR`, else `~/.bdg`.
+ *
+ * It is the default session's directory and holds named sessions under
+ * `sessions/<name>/`. Uses os.homedir() dynamically to support test
+ * environment variable changes.
+ *
+ * @returns Full path to the base session directory
+ */
+export declare function getSessionBaseDir(): string;
+/**
+ * The selected session name (`--session` / `BDG_SESSION`), lower-cased:
+ * session names are case-insensitive.
+ *
+ * @returns Session name, or null for the default session
+ */
+export declare function getSessionName(): string | null;
+/**
+ * Directory of a named session.
  *
- * Uses os.homedir() dynamically to support test environment variable changes.
+ * @param name - Session name
+ * @returns `<base>/sessions/<name>`
+ */
+export declare function getNamedSessionDir(name: string): string;
+/**
+ * Get the directory of the selected session: the base directory for the
+ * default session, `<base>/sessions/<name>` for a named one.
  *
- * @returns Full path to session directory
+ * @returns Full path to the session directory
  */
 export declare function getSessionDir(): string;
+/**
+ * Every session directory on disk: the default one, then named sessions
+ * sorted by name. Directories need not hold a running session.
+ *
+ * @returns Session directory entries
+ */
+export declare function listSessionDirs(): SessionDirEntry[];
+/**
+ * Which session a directory holds, from its location: `<base>/sessions/<name>`
+ * is a named session, any other directory a default session (its own base).
+ *
+ * @param dir - Absolute session directory
+ * @returns Session name (null for a default session) and base directory
+ */
+export declare function sessionOfDir(dir: string): {
+    name: string | null;
+    baseDir: string;
+};
+/**
+ * Path of a session file in a given session directory.
+ *
+ * @param dir - Session directory
+ * @param fileType - The type of session file
+ * @returns Full path to the file
+ */
+export declare function sessionFilePathIn(dir: string, fileType: SessionFileType): string;
 /**
  * Get the path to a session file by type.
  *
@@ -39,7 +111,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
  * ```
  */