browser-debugger-cli 0.8.0 → 0.10.0

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.
  */
 /**
@@ -17,18 +18,91 @@ declare const SESSION_FILES: {
     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.
  *

package/dist/session/paths.js

@@ -2,11 +2,14 @@
  * 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.
@@ -21,20 +24,123 @@ const SESSION_FILES = {
     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.
  *
@@ -48,7 +154,7 @@ export function getSessionDir() {
  * ```
  */
 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/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,13 +38,20 @@ 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

package/dist/session/port.js

@@ -3,14 +3,15 @@
  *
  * 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 { CommandError } from '../errors/index.js';
-import { ensureSessionDir, getSessionFilePath } from './paths.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.
@@ -20,7 +21,7 @@ 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, including one
- * listening on all interfaces).
+ * listening on all interfaces or on ::1 only).
  *
  * @param port - Port number to check
  * @returns Promise resolving to true if port is available
@@ -40,20 +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 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);
+    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.
@@ -61,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.
@@ -91,34 +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)
  *
- * This provides session isolation: different BDG_SESSION_DIR values
- * will automatically use different ports.
+ * 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: 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
+        if (getSessionName() === null)
+            return explicitPort;
+        return withPortLock((recordClaim) => {
+            writeSessionPort(explicitPort);
+            recordClaim(explicitPort);
+            return Promise.resolve(explicitPort);
+        });
     }
-    // Find a new available port
-    const newPort = await findAvailablePort();
-    writeSessionPort(newPort);
-    return newPort;
+    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