browser-debugger-cli 0.7.2 → 0.9.0

package/dist/session/portClaims.js

@@ -0,0 +1,284 @@
+/**
+ * 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).
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { getSessionBaseDir, getSessionDir, listSessionDirs, sessionFilePathIn, } from './paths.js';
+import { createLogger, logDebugError } from '../ui/logging/index.js';
+import { delay } from '../utils/async.js';
+const log = createLogger('session');
+/** Lock file guarding port selection, in the port registry (or base session) directory */
+const PORT_LOCK_FILE = 'port.lock';
+/** Subdirectory of the port registry: one file per claimed port, holding the claiming session directory */
+const CLAIMS_DIR = 'claims';
+/** Overrides the port registry directory (tests) */
+const PORT_REGISTRY_DIR_ENV = 'BDG_PORT_REGISTRY_DIR';
+/** How long to wait for the lock before choosing a port without it */
+const LOCK_WAIT_MS = 5000;
+/** Lock age after which its holder is assumed dead */
+const STALE_LOCK_MS = 10000;
+const LOCK_POLL_MS = 25;
+/** Permission bits that let other users write */
+const GROUP_OTHER_WRITE = 0o022;
+/**
+ * Read a port number from a `port.txt` file.
+ *
+ * @param portPath - File path
+ * @returns Port, or null if missing or invalid
+ */
+export function readPortFile(portPath) {
+    try {
+        const port = parseInt(fs.readFileSync(portPath, 'utf-8').trim(), 10);
+        return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : null;
+    }
+    catch (error) {
+        logDebugError(log, `read ${portPath}`, error);
+        return 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 function getPortRegistryDir() {
+    const override = process.env[PORT_REGISTRY_DIR_ENV]?.trim();
+    if (override)
+        return path.resolve(override);
+    const uid = process.getuid?.();
+    return path.join(os.tmpdir(), uid === undefined ? 'bdg-ports' : `bdg-ports-${uid}`);
+}
+/**
+ * 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 function untrustedDirReason(dir) {
+    const stat = fs.lstatSync(dir);
+    if (!stat.isDirectory())
+        return 'not a directory';
+    const uid = process.getuid?.();
+    if (uid !== undefined && stat.uid !== uid)
+        return `owned by uid ${stat.uid}`;
+    if (process.platform !== 'win32' && (stat.mode & GROUP_OTHER_WRITE) !== 0) {
+        return `writable by others (mode ${(stat.mode & 0o777).toString(8)})`;
+    }
+    return null;
+}
+/**
+ * The port registry directory, created (mode 0700) if missing, if it can be
+ * trusted (see {@link untrustedDirReason}).
+ *
+ * @param create - Create the directory (and its claims subdirectory) if missing
+ * @returns The directory, or null if it is missing or untrusted
+ */
+function trustedRegistryDir(create) {
+    const dir = getPortRegistryDir();
+    try {
+        if (create) {
+            fs.mkdirSync(path.dirname(dir), { recursive: true });
+            fs.mkdirSync(path.join(dir, CLAIMS_DIR), { recursive: true, mode: 0o700 });
+        }
+        if (!fs.existsSync(dir))
+            return null;
+        const reason = untrustedDirReason(dir) ?? untrustedDirReason(path.join(dir, CLAIMS_DIR));
+        if (reason === null)
+            return dir;
+        log.info(`Not using the port registry ${dir} (${reason}); port claims are per directory`);
+    }
+    catch (error) {
+        logDebugError(log, `use the port registry ${dir}`, error);
+    }
+    return null;
+}
+/**
+ * Record in the registry that this session directory claims a port. Written
+ * to a new temporary file that is renamed into place, so no symlink is
+ * followed. The claim holds while that session runs and its `port.txt` names
+ * the port; it needs no removal.
+ *
+ * @param registryDir - Trusted registry directory
+ * @param port - Claimed port
+ */
+function writePortClaim(registryDir, port) {
+    const claimPath = path.join(registryDir, CLAIMS_DIR, String(port));
+    const tempPath = `${claimPath}.${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(tempPath, getSessionDir(), { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+        fs.renameSync(tempPath, claimPath);
+    }
+    catch (error) {
+        logDebugError(log, `record the claim of port ${port}`, error);
+        fs.rmSync(tempPath, { force: true });
+    }
+}
+/**
+ * Session directories in the registry (any base directory).
+ *
+ * @returns Claiming session directories; none if the registry is untrusted
+ */
+function registeredSessionDirs() {
+    const registryDir = trustedRegistryDir(false);
+    if (registryDir === null)
+        return [];
+    const claimsDir = path.join(registryDir, CLAIMS_DIR);
+    try {
+        return fs
+            .readdirSync(claimsDir)
+            .filter((file) => /^\d+$/.test(file))
+            .map((file) => readClaim(path.join(claimsDir, file)))
+            .filter((dir) => dir !== null);
+    }
+    catch (error) {
+        logDebugError(log, `list ${claimsDir}`, error);
+        return [];
+    }
+}
+/**
+ * Read the session directory of one claim.
+ *
+ * @param claimPath - Claim file
+ * @returns Absolute session directory, or null if unreadable or partly written
+ */
+function readClaim(claimPath) {
+    try {
+        const dir = fs.readFileSync(claimPath, 'utf8').trim();
+        return path.isAbsolute(dir) ? dir : null;
+    }
+    catch (error) {
+        logDebugError(log, `read ${claimPath}`, error);
+        return 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 function otherSessionDirs() {
+    const ownDir = getSessionDir();
+    const dirs = new Set([...listSessionDirs().map(({ dir }) => dir), ...registeredSessionDirs()]);
+    return [...dirs].filter((dir) => dir !== ownDir);
+}
+/**
+ * Ports claimed by other sessions that are running or starting (their daemon
+ * socket exists), see {@link otherSessionDirs}.
+ *
+ * @returns Claimed ports
+ */
+export function portsClaimedByOtherSessions() {
+    const ports = otherSessionDirs()
+        .filter((dir) => fs.existsSync(sessionFilePathIn(dir, 'DAEMON_SOCKET')))
+        .map((dir) => readPortFile(sessionFilePathIn(dir, 'PORT')));
+    return new Set(ports.filter((port) => port !== null));
+}
+/**
+ * Take the port-selection lock.
+ *
+ * @param lockPath - Lock file path
+ * @param token - Written into the lock so only its owner removes it
+ * @returns True if the lock was taken; false after {@link LOCK_WAIT_MS} or
+ *   when the lock file cannot be created
+ */
+async function acquireLock(lockPath, token) {
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    while (Date.now() < deadline) {
+        try {
+            fs.writeFileSync(lockPath, token, { flag: 'wx' });
+            return true;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST') {
+                logDebugError(log, 'take the port lock', error);
+                return false;
+            }
+            removeStaleLock(lockPath);
+            await delay(LOCK_POLL_MS);
+        }
+    }
+    return false;
+}
+/**
+ * Remove a lock left by a process that died while holding it. The lock is
+ * moved aside first (only one waiter's rename succeeds); if another process
+ * took a fresh lock in the meantime, that one is put back.
+ *
+ * @param lockPath - Lock file path
+ */
+function removeStaleLock(lockPath) {
+    try {
+        if (Date.now() - fs.statSync(lockPath).mtimeMs <= STALE_LOCK_MS)
+            return;
+        const staleOwner = fs.readFileSync(lockPath, 'utf8');
+        const moved = `${lockPath}.${process.pid}.stale`;
+        fs.renameSync(lockPath, moved);
+        if (fs.readFileSync(moved, 'utf8') !== staleOwner)
+            fs.linkSync(moved, lockPath);
+        fs.rmSync(moved, { force: true });
+    }
+    catch (error) {
+        logDebugError(log, 'check the port lock', error);
+    }
+}
+/**
+ * Release the lock if it is still ours (it may have been taken over as stale).
+ *
+ * @param lockPath - Lock file path
+ * @param token - The token written when the lock was taken
+ */
+function releaseLock(lockPath, token) {
+    try {
+        if (fs.readFileSync(lockPath, 'utf8') === token)
+            fs.rmSync(lockPath, { force: true });
+    }
+    catch (error) {
+        logDebugError(log, 'release the port lock', error);
+    }
+}
+/**
+ * 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 async function withPortLock(select) {
+    const registryDir = trustedRegistryDir(true);
+    const lockDir = registryDir ?? getSessionBaseDir();
+    fs.mkdirSync(lockDir, { recursive: true });
+    const lockPath = path.join(lockDir, PORT_LOCK_FILE);
+    const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const locked = await acquireLock(lockPath, token);
+    if (!locked)
+        log.debug('Port lock busy; choosing a port without it');
+    const recordClaim = locked && registryDir !== null ? (port) => writePortClaim(registryDir, port) : () => { };
+    try {
+        return await select(recordClaim);
+    }
+    finally {
+        if (locked)
+            releaseLock(lockPath, token);
+    }
+}
+//# sourceMappingURL=portClaims.js.map

package/dist/session/sessionList.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Sessions across the default and named session directories (`bdg sessions`):
+ * running ones, and ones whose daemon died and left a Chrome or files behind.
+ */
+import type { StatusResponseData } from '../ipc/session/queries.js';
+import { type SocketProbeResult } from './daemonSocket.js';
+import { type SessionDirEntry } from './paths.js';
+/**
+ * State of a session: its daemon runs (`active`, `starting`, `ending`,
+ * `unresponsive`), or died and left its Chrome running (`crashed`) or only
+ * files (`stale`).
+ */
+export type RunningSessionState = 'active' | 'starting' | 'ending' | 'unresponsive' | 'crashed' | 'stale';
+/**
+ * One session in the list.
+ */
+export interface RunningSessionInfo {
+    /** Session name, or null for the default session */
+    name: string | null;
+    state: RunningSessionState;
+    /** Current page URL (or the URL being opened while starting) */
+    url?: string;
+    /** CDP port */
+    port?: number;
+    daemonPid?: number;
+    /** Chrome launched by bdg (absent for an attached Chrome) */
+    chromePid?: number;
+    /** Command that cleans up a crashed or stale session */
+    cleanup?: string;
+}
+/**
+ * Summarize a daemon's status response.
+ *
+ * @param name - Session name
+ * @param data - Status data
+ * @returns Session info
+ */
+export declare function toRunningSession(name: string | null, data: StatusResponseData): RunningSessionInfo;
+/**
+ * A session whose daemon is gone: `crashed` while the Chrome bdg launched for
+ * it still runs, `stale` when only its files are left. Nothing is changed on
+ * disk; `cleanup` names the command that removes them.
+ *
+ * @param entry - Session directory
+ * @param probe - Result of probing its daemon socket
+ * @returns Session info, or null when the directory holds no session state
+ */
+export declare function describeLeftovers({ name, dir }: SessionDirEntry, probe: SocketProbeResult): RunningSessionInfo | null;
+/**
+ * Every session: the default one first, then named sessions by name. Includes
+ * crashed and stale sessions, and directories `--session` cannot reach, so
+ * their leftovers can be cleaned up. A directory differing only in case
+ * (`ALPHA`) that `--session alpha` reaches is listed once, as `alpha`.
+ *
+ * @returns Sessions
+ */
+export declare function listRunningSessions(): Promise<RunningSessionInfo[]>;
+//# sourceMappingURL=sessionList.d.ts.map

package/dist/session/sessionList.js

@@ -0,0 +1,199 @@
+/**
+ * Sessions across the default and named session directories (`bdg sessions`):
+ * running ones, and ones whose daemon died and left a Chrome or files behind.
+ */
+import * as fs from 'fs';
+import { getStatus } from '../ipc/client.js';
+import { isSessionChrome, readLiveDaemonPid } from './cleanup/staleSession.js';
+import { probeDaemonSocket } from './daemonSocket.js';
+import { SESSION_STATE_FILES, getNamedSessionDir, listSessionDirs, sessionFilePathIn, } from './paths.js';
+import { readPidFromFile } from './pid.js';
+import { readPortFile } from './portClaims.js';
+import { isValidSessionName, normalizeSessionName } from './sessionName.js';
+import { createLogger, logDebugError } from '../ui/logging/index.js';
+import { removeDirCommand, sessionCommand } from '../ui/messages/sessionCommand.js';
+import { isProcessAlive } from '../utils/process.js';
+const log = createLogger('session');
+/**
+ * Summarize a daemon's status response.
+ *
+ * @param name - Session name
+ * @param data - Status data
+ * @returns Session info
+ */
+export function toRunningSession(name, data) {
+    const meta = data.sessionMetadata;
+    const state = meta ? 'active' : data.ending ? 'ending' : 'starting';
+    const url = data.pageState?.url ?? data.starting?.url;
+    return {
+        name,
+        state,
+        ...(url !== undefined && { url }),
+        ...(meta && { port: meta.port }),
+        daemonPid: data.daemonPid,
+        ...(meta?.chromePid && { chromePid: meta.chromePid }),
+    };
+}
+/**
+ * Describe the session of a directory: a running daemon, or what a dead
+ * one left behind.
+ *
+ * @param entry - Session directory
+ * @returns Session info, or null when there is no session
+ */
+async function describeSession(entry) {
+    const { name, dir } = entry;
+    const socketPath = sessionFilePathIn(dir, 'DAEMON_SOCKET');
+    const probe = await probeDaemonSocket(socketPath);
+    if (probe !== 'alive')
+        return describeWithoutSocket(entry, probe);
+    try {
+        const response = await getStatus(socketPath);
+        if (response.status === 'ok' && response.data)
+            return toRunningSession(name, response.data);
+    }
+    catch (error) {
+        logDebugError(log, `get status of ${dir}`, error);
+    }
+    return { name, state: 'unresponsive' };
+}
+/**
+ * A session whose daemon socket does not answer: `starting` while its daemon
+ * (from daemon.pid, verified by command line) runs but has not bound the
+ * socket yet, otherwise see {@link describeLeftovers}.
+ *
+ * @param entry - Session directory
+ * @param probe - Result of probing its daemon socket
+ * @returns Session info, or null when the directory holds no session state
+ */
+function describeWithoutSocket(entry, probe) {
+    const daemonPid = readLiveDaemonPid(entry.dir);
+    if (daemonPid !== null)
+        return { name: entry.name, state: 'starting', daemonPid };
+    return describeLeftovers(entry, probe);
+}
+/**
+ * A session whose daemon is gone: `crashed` while the Chrome bdg launched for
+ * it still runs, `stale` when only its files are left. Nothing is changed on
+ * disk; `cleanup` names the command that removes them.
+ *
+ * @param entry - Session directory
+ * @param probe - Result of probing its daemon socket
+ * @returns Session info, or null when the directory holds no session state
+ */
+export function describeLeftovers({ name, dir }, probe) {
+    const chromePid = readPidFromFile(sessionFilePathIn(dir, 'CHROME_PID'));
+    const orphan = chromePid !== null && isProcessAlive(chromePid) && isSessionChrome(chromePid, dir);
+    const leftover = probe === 'stale' ||
+        SESSION_STATE_FILES.some((type) => fs.existsSync(sessionFilePathIn(dir, type)));
+    if (!orphan && !leftover)
+        return null;
+    const port = leftoverPort(dir);
+    return {
+        name,
+        state: orphan ? 'crashed' : 'stale',
+        ...(port !== null && { port }),
+        ...(orphan && { chromePid }),
+        cleanup: sessionCommand('bdg cleanup', name),
+    };
+}
+/**
+ * The port a dead session used: from its metadata, else its `port.txt`.
+ *
+ * @param dir - Session directory
+ * @returns Port, or null if unknown
+ */
+function leftoverPort(dir) {
+    try {
+        const meta = JSON.parse(fs.readFileSync(sessionFilePathIn(dir, 'METADATA'), 'utf8'));
+        if (typeof meta.port === 'number')
+            return meta.port;
+    }
+    catch (error) {
+        logDebugError(log, `read the metadata in ${dir}`, error);
+    }
+    return readPortFile(sessionFilePathIn(dir, 'PORT'));
+}
+/**
+ * Whether a directory entry is a session `--session` can select: the
+ * default session, or a valid lower-case name.
+ *
+ * @param entry - Session directory
+ * @returns True if selectable
+ */
+function isSelectable({ name }) {
+    return name === null || (isValidSessionName(name) && name === normalizeSessionName(name));
+}
+/**
+ * Whether two paths are the same directory (same inode and device), e.g.
+ * `sessions/ALPHA` and `sessions/alpha` on a case-insensitive file system.
+ *
+ * @param a - First path
+ * @param b - Second path
+ * @returns True if both exist and are the same directory
+ */
+function isSameDir(a, b) {
+    try {
+        const first = fs.statSync(a);
+        const second = fs.statSync(b);
+        return first.ino === second.ino && first.dev === second.dev;
+    }
+    catch (error) {
+        logDebugError(log, `compare ${a} with ${b}`, error);
+        return false;
+    }
+}
+/**
+ * The session `--session` reaches in a directory: the entry itself when its
+ * name is selectable, the lower-cased session when the name differs only in
+ * case and `--session <lower-case>` resolves to this very directory (a
+ * case-insensitive file system), else null.
+ *
+ * @param entry - Session directory
+ * @returns Selectable entry, or null
+ */
+function selectableEntry(entry) {
+    if (isSelectable(entry) || entry.name === null)
+        return entry;
+    const lower = normalizeSessionName(entry.name);
+    if (!isValidSessionName(lower))
+        return null;
+    return isSameDir(entry.dir, getNamedSessionDir(lower)) ? { name: lower, dir: entry.dir } : null;
+}
+/**
+ * A directory `--session` cannot reach (e.g. `--json`, or `ALPHA` on a
+ * case-sensitive file system, made by an earlier build): described like any
+ * session while its daemon answers, otherwise `stale` with the command that
+ * removes it by hand.
+ *
+ * @param entry - Session directory
+ * @returns Session info
+ */
+async function describeUnselectable(entry) {
+    const socketPath = sessionFilePathIn(entry.dir, 'DAEMON_SOCKET');
+    if ((await probeDaemonSocket(socketPath)) === 'alive')
+        return describeSession(entry);
+    return { name: entry.name, state: 'stale', cleanup: removeDirCommand(entry.dir) };
+}
+/**
+ * Every session: the default one first, then named sessions by name. Includes
+ * crashed and stale sessions, and directories `--session` cannot reach, so
+ * their leftovers can be cleaned up. A directory differing only in case
+ * (`ALPHA`) that `--session alpha` reaches is listed once, as `alpha`.
+ *
+ * @returns Sessions
+ */
+export async function listRunningSessions() {
+    const listed = new Set();
+    const sessions = await Promise.all(listSessionDirs().map((entry) => {
+        const selectable = selectableEntry(entry);
+        if (selectable === null)
+            return describeUnselectable(entry);
+        if (listed.has(selectable.name))
+            return Promise.resolve(null);
+        listed.add(selectable.name);
+        return describeSession(selectable);
+    }));
+    return sessions.filter((session) => session !== null);
+}
+//# sourceMappingURL=sessionList.js.map

package/dist/session/sessionName.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Named sessions (`--session <name>` / `BDG_SESSION`).
+ *
+ * A named session lives in `<base>/sessions/<name>/` with its own daemon,
+ * socket, Chrome and port, so several agents can run bdg side by side.
+ * Names are case-insensitive: they are lower-cased when selected, so `ALPHA`
+ * and `alpha` are the same session (and directory) on every file system.
+ */
+/** Longest session name */
+export declare const MAX_SESSION_NAME_LENGTH = 40;
+/**
+ * Whether a name has the allowed characters and length (case-insensitive).
+ *
+ * @param name - Session name
+ * @returns True for a valid name
+ */
+export declare function isValidSessionName(name: string): boolean;
+/**
+ * The canonical form of a session name: lower case.
+ *
+ * @param name - Session name as given
+ * @returns Lower-cased name
+ */
+export declare function normalizeSessionName(name: string): string;
+/**
+ * Check a session name: allowed characters, length, and a daemon socket path
+ * the OS accepts. When even the shortest name would make the socket path too
+ * long, the base directory is blamed instead of the name.
+ *
+ * @param name - Session name
+ * @throws CommandError (81) for an invalid name or a too-long socket path
+ */
+export declare function validateSessionName(name: string): void;
+/**
+ * Select the session the command acts on.
+ *
+ * `--session` wins over `BDG_SESSION`; the choice is stored in `BDG_SESSION`
+ * so the rest of the process (and a daemon it spawns) resolves the same
+ * session directory. The name is stored lower-cased. An empty `BDG_SESSION`
+ * means the default session.
+ *
+ * @param optionValue - Value of `--session`, if given
+ * @throws CommandError (81) for an invalid name
+ */
+export declare function selectSession(optionValue: string | undefined): void;
+//# sourceMappingURL=sessionName.d.ts.map

package/dist/session/sessionName.js

@@ -0,0 +1,97 @@
+/**
+ * Named sessions (`--session <name>` / `BDG_SESSION`).
+ *
+ * A named session lives in `<base>/sessions/<name>/` with its own daemon,
+ * socket, Chrome and port, so several agents can run bdg side by side.
+ * Names are case-insensitive: they are lower-cased when selected, so `ALPHA`
+ * and `alpha` are the same session (and directory) on every file system.
+ */
+import { CommandError } from '../errors/index.js';
+import { invalidSessionNameError, sessionNameSocketTooLongError, socketPathTooLongError, } from '../errors/messages.js';
+import { MAX_DAEMON_SOCKET_PATH_BYTES, SESSION_NAME_ENV, getNamedSessionDir, sessionFilePathIn, } from './paths.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
+/** Longest session name */
+export const MAX_SESSION_NAME_LENGTH = 40;
+/**
+ * Characters allowed in a session name: a letter or digit first (so a name
+ * never looks like an option), then letters, digits, `-` or `_`.
+ */
+const SESSION_NAME_PATTERN = new RegExp(`^[A-Za-z0-9][A-Za-z0-9_-]{0,${MAX_SESSION_NAME_LENGTH - 1}}$`);
+/**
+ * Whether a name has the allowed characters and length (case-insensitive).
+ *
+ * @param name - Session name
+ * @returns True for a valid name
+ */
+export function isValidSessionName(name) {
+    return SESSION_NAME_PATTERN.test(name);
+}
+/**
+ * The canonical form of a session name: lower case.
+ *
+ * @param name - Session name as given
+ * @returns Lower-cased name
+ */
+export function normalizeSessionName(name) {
+    return name.toLowerCase();
+}
+/**
+ * Check a session name: allowed characters, length, and a daemon socket path
+ * the OS accepts. When even the shortest name would make the socket path too
+ * long, the base directory is blamed instead of the name.
+ *
+ * @param name - Session name
+ * @throws CommandError (81) for an invalid name or a too-long socket path
+ */
+export function validateSessionName(name) {
+    if (!isValidSessionName(name)) {
+        throwInvalid(invalidSessionNameError(name, MAX_SESSION_NAME_LENGTH));
+    }
+    const shortest = namedSocketPath('a');
+    if (Buffer.byteLength(shortest) > MAX_DAEMON_SOCKET_PATH_BYTES) {
+        throwInvalid(socketPathTooLongError(shortest, MAX_DAEMON_SOCKET_PATH_BYTES));
+    }
+    const socketPath = namedSocketPath(name);
+    if (Buffer.byteLength(socketPath) > MAX_DAEMON_SOCKET_PATH_BYTES) {
+        throwInvalid(sessionNameSocketTooLongError(name, socketPath, MAX_DAEMON_SOCKET_PATH_BYTES));
+    }
+}
+/**
+ * Daemon socket path of a named session.
+ *
+ * @param name - Session name
+ * @returns Socket path
+ */
+function namedSocketPath(name) {
+    return sessionFilePathIn(getNamedSessionDir(name), 'DAEMON_SOCKET');
+}
+/**
+ * Throw an invalid-arguments error (81).
+ *
+ * @param err - Message and suggestion
+ * @throws CommandError always
+ */
+function throwInvalid(err) {
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
+/**
+ * Select the session the command acts on.
+ *
+ * `--session` wins over `BDG_SESSION`; the choice is stored in `BDG_SESSION`
+ * so the rest of the process (and a daemon it spawns) resolves the same
+ * session directory. The name is stored lower-cased. An empty `BDG_SESSION`
+ * means the default session.
+ *
+ * @param optionValue - Value of `--session`, if given
+ * @throws CommandError (81) for an invalid name
+ */
+export function selectSession(optionValue) {
+    const name = optionValue ?? process.env[SESSION_NAME_ENV]?.trim();
+    if (name === undefined || (optionValue === undefined && name === '')) {
+        delete process.env[SESSION_NAME_ENV];
+        return;
+    }
+    validateSessionName(name);
+    process.env[SESSION_NAME_ENV] = normalizeSessionName(name);
+}
+//# sourceMappingURL=sessionName.js.map