browser-debugger-cli 0.7.2 → 0.9.0

package/dist/session/paths.js

@@ -2,41 +2,145 @@
  * 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.
  */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { createLogger, logDebugError } from '../ui/logging/index.js';
+const log = createLogger('session');
 /**
  * Session file paths relative to ~/.bdg/
  * 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';
+/** Environment variable holding the selected session name (set by `--session`) */
+export const SESSION_NAME_ENV = 'BDG_SESSION';
+/** Subdirectory of the base session directory that holds named sessions */
+const NAMED_SESSIONS_DIR = 'sessions';
+/** Longest Unix socket path (sun_path is 104 bytes on macOS, 108 on Linux, NUL included) */
+export const MAX_SOCKET_PATH_BYTES = process.platform === 'darwin' ? 103 : 107;
 /**
- * Get the session directory path (~/.bdg)
+ * 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 const MAX_DAEMON_SOCKET_PATH_BYTES = MAX_SOCKET_PATH_BYTES - '.9999999'.length;
+/**
+ * Files a running session keeps in its directory; left behind (stale) when
+ * its daemon dies without tearing down.
+ */
+export const SESSION_STATE_FILES = [
+    'DAEMON_PID',
+    'DAEMON_SOCKET',
+    'CHROME_PID',
+    'METADATA',
+];
+/**
+ * Get the base session directory: `$BDG_SESSION_DIR`, else `~/.bdg`.
  *
- * Uses os.homedir() dynamically to support test environment variable changes.
+ * 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 session directory
+ * @returns Full path to the base session directory
  */
-export function getSessionDir() {
+export function getSessionBaseDir() {
     const override = process.env[SESSION_DIR_OVERRIDE_ENV];
     if (override && override.trim().length > 0) {
         return path.isAbsolute(override) ? override : path.resolve(override);
     }
     return path.join(os.homedir(), '.bdg');
 }
+/**
+ * The selected session name (`--session` / `BDG_SESSION`), lower-cased:
+ * session names are case-insensitive.
+ *
+ * @returns Session name, or null for the default session
+ */
+export function getSessionName() {
+    const name = process.env[SESSION_NAME_ENV]?.trim();
+    if (!name)
+        return null;
+    return name.toLowerCase();
+}
+/**
+ * Directory of a named session.
+ *
+ * @param name - Session name
+ * @returns `<base>/sessions/<name>`
+ */
+export function getNamedSessionDir(name) {
+    return path.join(getSessionBaseDir(), NAMED_SESSIONS_DIR, name);
+}
+/**
+ * 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 the session directory
+ */
+export function getSessionDir() {
+    const name = getSessionName();
+    return name === null ? getSessionBaseDir() : getNamedSessionDir(name);
+}
+/**
+ * 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 function listSessionDirs() {
+    const namedRoot = path.join(getSessionBaseDir(), NAMED_SESSIONS_DIR);
+    let names = [];
+    try {
+        names = fs
+            .readdirSync(namedRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch (error) {
+        logDebugError(log, `list ${namedRoot}`, error);
+    }
+    return [
+        { name: null, dir: getSessionBaseDir() },
+        ...names.map((name) => ({ name, dir: path.join(namedRoot, name) })),
+    ];
+}
+/**
+ * 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 function sessionOfDir(dir) {
+    const parent = path.dirname(dir);
+    if (path.basename(parent) === NAMED_SESSIONS_DIR) {
+        return { name: path.basename(dir), baseDir: path.dirname(parent) };
+    }
+    return { name: null, baseDir: dir };
+}
+/**
+ * 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 function sessionFilePathIn(dir, fileType) {
+    return path.join(dir, SESSION_FILES[fileType]);
+}
 /**
  * Get the path to a session file by type.
  *
@@ -45,12 +149,12 @@ export function getSessionDir() {
  *
  * @example
  * ```typescript
- * getSessionFilePath('PID')        // → ~/.bdg/session.pid
+ * getSessionFilePath('METADATA')   // → ~/.bdg/session.meta.json
  * getSessionFilePath('DAEMON_PID') // → ~/.bdg/daemon.pid
  * ```
  */
 export function getSessionFilePath(fileType) {
-    return path.join(getSessionDir(), SESSION_FILES[fileType]);
+    return sessionFilePathIn(getSessionDir(), fileType);
 }
 /**
  * Get the path to the daemon's Unix domain socket.

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

@@ -3,8 +3,25 @@
  *
  * Handles automatic port selection and persistence for session isolation.
  * Each session directory can have its own persistent port, enabling multiple
- * concurrent bdg sessions with different BDG_SESSION_DIR values.
+ * concurrent bdg sessions (named sessions or different BDG_SESSION_DIR values).
  */
+/**
+ * First port tried for this session: the default session starts at
+ * DEFAULT_CDP_PORT, named sessions one above so they leave it to the default
+ * session.
+ *
+ * @returns First candidate port
+ */
+export declare function firstCandidatePort(): number;
+/**
+ * Find an available port starting from a given port.
+ *
+ * @param startPort - Port to start scanning from
+ * @param claimed - Ports to skip (claimed by other sessions)
+ * @returns Promise resolving to an available port
+ * @throws CommandError if no available port found in range
+ */
+export declare function findAvailablePort(startPort?: number, claimed?: ReadonlySet<number>): Promise<number>;
 /**
  * Read the saved port from the session directory.
  *
@@ -21,21 +38,23 @@ export declare function writeSessionPort(port: number): void;
  * Get or allocate a port for this session.
  *
  * Logic:
- * 1. If a port is explicitly provided, use it (user override)
- * 2. Check if there's a saved port in the session directory
- * 3. If saved port exists and is available, reuse it (session stability)
- * 4. Otherwise, find a new available port and save it
+ * 1. If a port is explicitly provided, use it (user override; a named session
+ *    saves and claims it under the lock so other sessions skip it)
+ * 2. Otherwise, under a lock shared by all sessions on the machine (any
+ *    BDG_SESSION_DIR), reuse the saved port if it is free and no other
+ *    running session claims it (session stability)
+ * 3. Otherwise, take the first free, unclaimed port from
+ *    {@link firstCandidatePort} upwards and save it (the claim)
+ *
+ * The claim is also recorded in the machine-wide registry (under the lock),
+ * so sessions of other base directories skip it too.
  *
- * This provides session isolation: different BDG_SESSION_DIR values
- * will automatically use different ports.
+ * This provides session isolation: named sessions and different
+ * BDG_SESSION_DIR values automatically use different ports, even when they
+ * start at the same time.
  *
  * @param explicitPort - User-provided port (takes precedence)
  * @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

@@ -3,12 +3,16 @@
  *
  * Handles automatic port selection and persistence for session isolation.
  * Each session directory can have its own persistent port, enabling multiple
- * concurrent bdg sessions with different BDG_SESSION_DIR values.
+ * concurrent bdg sessions (named sessions or different BDG_SESSION_DIR values).
  */
 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, getSessionName } from './paths.js';
+import { portsClaimedByOtherSessions, readPortFile, withPortLock } from './portClaims.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 +20,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 or on ::1 only).
  *
  * @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', () => {
@@ -34,21 +41,31 @@ async function isPortAvailable(port) {
         });
     });
 }
+/**
+ * First port tried for this session: the default session starts at
+ * DEFAULT_CDP_PORT, named sessions one above so they leave it to the default
+ * session.
+ *
+ * @returns First candidate port
+ */
+export function firstCandidatePort() {
+    return getSessionName() === null ? PORT_RANGE_START : PORT_RANGE_START + 1;
+}
 /**
  * Find an available port starting from a given port.
  *
  * @param startPort - Port to start scanning from
+ * @param claimed - Ports to skip (claimed by other sessions)
  * @returns Promise resolving to an available port
- * @throws Error if no available port found in range
+ * @throws CommandError if no available port found in range
  */
-async function findAvailablePort(startPort = PORT_RANGE_START) {
+export async function findAvailablePort(startPort = PORT_RANGE_START, claimed = new Set()) {
     for (let port = startPort; port <= PORT_RANGE_END; port++) {
-        if (await isPortAvailable(port)) {
+        if (!claimed.has(port) && (await isPortAvailable(port))) {
             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 ${startPort}-${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.
@@ -56,21 +73,8 @@ async function findAvailablePort(startPort = PORT_RANGE_START) {
  * @returns Saved port number or null if not found/invalid
  */
 export function readSessionPort() {
-    try {
-        const portPath = getSessionFilePath('PORT');
-        if (!fs.existsSync(portPath)) {
-            return null;
-        }
-        const content = fs.readFileSync(portPath, 'utf-8').trim();
-        const port = parseInt(content, 10);
-        if (isNaN(port) || port < 1 || port > 65535) {
-            return null;
-        }
-        return port;
-    }
-    catch {
-        return null;
-    }
+    const portPath = getSessionFilePath('PORT');
+    return fs.existsSync(portPath) ? readPortFile(portPath) : null;
 }
 /**
  * Save the port to the session directory.
@@ -86,49 +90,42 @@ export function writeSessionPort(port) {
  * Get or allocate a port for this session.
  *
  * Logic:
- * 1. If a port is explicitly provided, use it (user override)
- * 2. Check if there's a saved port in the session directory
- * 3. If saved port exists and is available, reuse it (session stability)
- * 4. Otherwise, find a new available port and save it
+ * 1. If a port is explicitly provided, use it (user override; a named session
+ *    saves and claims it under the lock so other sessions skip it)
+ * 2. Otherwise, under a lock shared by all sessions on the machine (any
+ *    BDG_SESSION_DIR), reuse the saved port if it is free and no other
+ *    running session claims it (session stability)
+ * 3. Otherwise, take the first free, unclaimed port from
+ *    {@link firstCandidatePort} upwards and save it (the claim)
+ *
+ * The claim is also recorded in the machine-wide registry (under the lock),
+ * so sessions of other base directories skip it too.
  *
- * This provides session isolation: different BDG_SESSION_DIR values
- * will automatically use different ports.
+ * This provides session isolation: named sessions and different
+ * BDG_SESSION_DIR values automatically use different ports, even when they
+ * start at the same time.
  *
  * @param explicitPort - User-provided port (takes precedence)
  * @returns Promise resolving to the port to use
  */
 export async function getSessionPort(explicitPort) {
-    // User explicitly specified a port - use it directly
     if (explicitPort !== undefined && explicitPort !== null) {
-        return explicitPort;
-    }
-    // Check for saved session port
-    const savedPort = readSessionPort();
-    if (savedPort !== null) {
-        // Verify the saved port is still available
-        if (await isPortAvailable(savedPort)) {
-            return savedPort;
-        }
-        // Saved port is in use by another process, need to find a new one
-    }
-    // Find a new available port
-    const newPort = await findAvailablePort();
-    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
+        if (getSessionName() === null)
+            return explicitPort;
+        return withPortLock((recordClaim) => {
+            writeSessionPort(explicitPort);
+            recordClaim(explicitPort);
+            return Promise.resolve(explicitPort);
+        });
     }
+    return withPortLock(async (recordClaim) => {
+        const claimed = portsClaimedByOtherSessions();
+        const savedPort = readSessionPort();
+        const reuse = savedPort !== null && !claimed.has(savedPort) && (await isPortAvailable(savedPort));
+        const port = reuse ? savedPort : await findAvailablePort(firstCandidatePort(), claimed);
+        writeSessionPort(port);
+        recordClaim(port);
+        return port;
+    });
 }
 //# sourceMappingURL=port.js.map

package/dist/session/portClaims.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Port claims across concurrent sessions.
+ *
+ * Sessions started at the same time must not pick the same CDP port: Chrome
+ * binds it only after the choice is made. A session claims its port by
+ * writing `port.txt` while holding a lock; a running session's claim is
+ * skipped by the others.
+ *
+ * Ports belong to the machine, not to a session directory, so the lock and a
+ * registry of claiming session directories live in one directory per user
+ * under the OS temp directory: sessions of different `BDG_SESSION_DIR`s see
+ * each other's claims too. That directory is used only if it is a real
+ * directory owned by the user that nobody else can write to; otherwise the
+ * lock falls back to the base session directory and only that directory's
+ * claims are seen (the launched Chrome's identity is still checked).
+ */
+/** Records a port claim; a no-op when the registry cannot be used safely */
+export type RecordPortClaim = (port: number) => void;
+/**
+ * Read a port number from a `port.txt` file.
+ *
+ * @param portPath - File path
+ * @returns Port, or null if missing or invalid
+ */
+export declare function readPortFile(portPath: string): number | null;
+/**
+ * Directory holding the port lock and the claims registry, shared by every
+ * session of the user on this machine.
+ *
+ * @returns `$BDG_PORT_REGISTRY_DIR`, else `<os temp dir>/bdg-ports-<uid>`
+ */
+export declare function getPortRegistryDir(): string;
+/**
+ * Whether a path is a directory the current user can trust: a real directory
+ * (not a symlink), owned by the user, not writable by group or others.
+ *
+ * @param dir - Directory
+ * @returns Why it cannot be trusted, or null if it can
+ */
+export declare function untrustedDirReason(dir: string): string | null;
+/**
+ * Session directories other than the selected one that bdg knows of: those of
+ * this base directory, and those of any base directory found in the
+ * machine-wide registry. They need not hold a running session.
+ *
+ * @returns Session directories
+ */
+export declare function otherSessionDirs(): string[];
+/**
+ * Ports claimed by other sessions that are running or starting (their daemon
+ * socket exists), see {@link otherSessionDirs}.
+ *
+ * @returns Claimed ports
+ */
+export declare function portsClaimedByOtherSessions(): Set<number>;
+/**
+ * Run port selection under the lock shared by all sessions of the user on
+ * this machine (in the trusted registry directory; else in the base session
+ * directory). If the lock cannot be taken in time, the selection runs anyway.
+ *
+ * @param select - Chooses the port; gets a function recording the claim in
+ *   the registry, a no-op without the registry lock
+ * @returns The chosen port
+ */
+export declare function withPortLock(select: (recordClaim: RecordPortClaim) => Promise<number>): Promise<number>;
+//# sourceMappingURL=portClaims.d.ts.map