browser-debugger-cli 0.0.1-alpha.0 → 0.1.0-alpha.1

package/dist/session/lock.js

@@ -0,0 +1,154 @@
+/**
+ * Session lock management for preventing concurrent sessions.
+ *
+ * Uses exclusive file creation (wx flag) with PID tracking for atomic lock acquisition.
+ * WHY: Prevents race conditions when multiple bdg processes try to start simultaneously.
+ */
+import * as fs from 'fs';
+import { getSessionFilePath, ensureSessionDir } from './paths.js';
+import { isProcessAlive } from './process.js';
+/**
+ * Acquire session lock atomically.
+ *
+ * Uses exclusive file creation (wx flag) to ensure only one session can run.
+ * If lock file exists but process is dead, automatically removes stale lock and retries.
+ *
+ * @returns True if lock was acquired, false if another session is running
+ *
+ * @example
+ * ```typescript
+ * if (!acquireSessionLock()) {
+ *   console.error('Another session is already running');
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export function acquireSessionLock() {
+    ensureSessionDir();
+    const lockPath = getSessionFilePath('LOCK');
+    try {
+        // 'wx' flag creates file exclusively - fails if exists
+        fs.writeFileSync(lockPath, process.pid.toString(), { flag: 'wx' });
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
+            // Lock file exists - check if process is still alive
+            try {
+                const lockPidStr = fs.readFileSync(lockPath, 'utf-8').trim();
+                const lockPid = parseInt(lockPidStr, 10);
+                if (!isNaN(lockPid) && isProcessAlive(lockPid)) {
+                    // Lock is held by active process
+                    return false;
+                }
+                else {
+                    // Stale lock file - remove it and try again
+                    fs.unlinkSync(lockPath);
+                    return acquireSessionLock();
+                }
+            }
+            catch {
+                // Can't read lock file - assume it's stale
+                try {
+                    fs.unlinkSync(lockPath);
+                    return acquireSessionLock();
+                }
+                catch {
+                    return false;
+                }
+            }
+        }
+        return false;
+    }
+}
+/**
+ * Release session lock.
+ *
+ * Removes the lock file to allow other sessions to start.
+ * Safe to call multiple times (idempotent).
+ */
+export function releaseSessionLock() {
+    const lockPath = getSessionFilePath('LOCK');
+    try {
+        if (fs.existsSync(lockPath)) {
+            fs.unlinkSync(lockPath);
+        }
+    }
+    catch {
+        // Ignore errors during cleanup
+    }
+}
+/**
+ * Acquire daemon lock atomically.
+ *
+ * Uses exclusive file creation (wx flag) to ensure only one daemon can start.
+ * If lock file exists but process is dead, automatically removes stale lock and retries.
+ *
+ * WHY: Prevents race condition where two concurrent bdg commands spawn 2 daemons.
+ *
+ * @returns True if lock was acquired, false if another daemon startup is in progress
+ *
+ * @example
+ * ```typescript
+ * if (!acquireDaemonLock()) {
+ *   console.error('Another daemon is starting up');
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export function acquireDaemonLock() {
+    ensureSessionDir();
+    const lockPath = getSessionFilePath('DAEMON_LOCK');
+    try {
+        // 'wx' flag creates file exclusively - fails if exists
+        fs.writeFileSync(lockPath, process.pid.toString(), { flag: 'wx' });
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
+            // Lock file exists - check if process is still alive
+            try {
+                const lockPidStr = fs.readFileSync(lockPath, 'utf-8').trim();
+                const lockPid = parseInt(lockPidStr, 10);
+                if (!isNaN(lockPid) && isProcessAlive(lockPid)) {
+                    // Lock is held by active process
+                    return false;
+                }
+                else {
+                    // Stale lock file - remove it and try again
+                    fs.unlinkSync(lockPath);
+                    return acquireDaemonLock();
+                }
+            }
+            catch {
+                // Can't read lock file - assume it's stale
+                try {
+                    fs.unlinkSync(lockPath);
+                    return acquireDaemonLock();
+                }
+                catch {
+                    return false;
+                }
+            }
+        }
+        return false;
+    }
+}
+/**
+ * Release daemon lock.
+ *
+ * Removes the daemon lock file to allow other daemon startups.
+ * Safe to call multiple times (idempotent).
+ */
+export function releaseDaemonLock() {
+    const lockPath = getSessionFilePath('DAEMON_LOCK');
+    try {
+        if (fs.existsSync(lockPath)) {
+            fs.unlinkSync(lockPath);
+        }
+    }
+    catch {
+        // Ignore errors during cleanup
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/session/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/session/lock.ts"],"names":[],"mappings":"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"}

package/dist/session/metadata.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Session metadata management.
+ *
+ * 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 { CollectorType } from '../types.js';
+/**
+ * Session metadata stored in ~/.bdg/session.meta.json
+ */
+export interface SessionMetadata {
+    bdgPid: number;
+    chromePid?: number | undefined;
+    startTime: number;
+    port: number;
+    targetId?: string | undefined;
+    webSocketDebuggerUrl?: string | undefined;
+    activeCollectors?: CollectorType[] | undefined;
+}
+/**
+ * Write session metadata atomically.
+ *
+ * Uses atomic write (tmp file + rename) to prevent corruption.
+ *
+ * @param metadata - Session metadata to write
+ *
+ * @example
+ * ```typescript
+ * writeSessionMetadata({
+ *   bdgPid: process.pid,
+ *   chromePid: 12345,
+ *   startTime: Date.now(),
+ *   port: 9222,
+ *   activeCollectors: ['network', 'console', 'dom']
+ * });
+ * ```
+ */
+export declare function writeSessionMetadata(metadata: SessionMetadata): void;
+/**
+ * Read session metadata.
+ *
+ * WHY: P1 Fix #2 - Now logs warnings when metadata is corrupted.
+ *
+ * @param options - Options for error handling
+ * @returns Session metadata if file exists and is valid, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const metadata = readSessionMetadata({ warnOnCorruption: true });
+ * if (metadata) {
+ *   console.log(`Session started at: ${new Date(metadata.startTime)}`);
+ *   console.log(`Chrome PID: ${metadata.chromePid}`);
+ * }
+ * ```
+ */
+export declare function readSessionMetadata(options?: {
+    warnOnCorruption?: boolean;
+}): SessionMetadata | null;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/session/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/session/metadata.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAS7C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,gBAAgB,CAAC,EAAE,aAAa,EAAE,GAAG,SAAS,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAIpE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE;IAC5C,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,eAAe,GAAG,IAAI,CAkBzB"}

package/dist/session/metadata.js

@@ -0,0 +1,71 @@
+/**
+ * Session metadata management.
+ *
+ * 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 * as fs from 'fs';
+import { AtomicFileWriter } from '../utils/atomicFile.js';
+import { getErrorMessage } from '../utils/errors.js';
+import { createLogger } from '../utils/logger.js';
+import { getSessionFilePath, ensureSessionDir } from './paths.js';
+const log = createLogger('session');
+/**
+ * Write session metadata atomically.
+ *
+ * Uses atomic write (tmp file + rename) to prevent corruption.
+ *
+ * @param metadata - Session metadata to write
+ *
+ * @example
+ * ```typescript
+ * writeSessionMetadata({
+ *   bdgPid: process.pid,
+ *   chromePid: 12345,
+ *   startTime: Date.now(),
+ *   port: 9222,
+ *   activeCollectors: ['network', 'console', 'dom']
+ * });
+ * ```
+ */
+export function writeSessionMetadata(metadata) {
+    ensureSessionDir();
+    const metaPath = getSessionFilePath('METADATA');
+    AtomicFileWriter.writeSync(metaPath, JSON.stringify(metadata, null, 2));
+}
+/**
+ * Read session metadata.
+ *
+ * WHY: P1 Fix #2 - Now logs warnings when metadata is corrupted.
+ *
+ * @param options - Options for error handling
+ * @returns Session metadata if file exists and is valid, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const metadata = readSessionMetadata({ warnOnCorruption: true });
+ * if (metadata) {
+ *   console.log(`Session started at: ${new Date(metadata.startTime)}`);
+ *   console.log(`Chrome PID: ${metadata.chromePid}`);
+ * }
+ * ```
+ */
+export function readSessionMetadata(options) {
+    const metaPath = getSessionFilePath('METADATA');
+    if (!fs.existsSync(metaPath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(metaPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        // P1 Fix #2: Warn when metadata is corrupted
+        if (options?.warnOnCorruption) {
+            log(`Session metadata corrupted (cannot read details): ${getErrorMessage(error)}`);
+            log('Troubleshooting: Run "bdg cleanup" to remove corrupted files');
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=metadata.js.map

package/dist/session/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../src/session/metadata.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAGzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAElE,MAAM,GAAG,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;AAepC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAyB;IAC5D,gBAAgB,EAAE,CAAC;IACnB,MAAM,QAAQ,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAChD,gBAAgB,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAEnC;IACC,MAAM,QAAQ,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAEhD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAoB,CAAC;IAChD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,6CAA6C;QAC7C,IAAI,OAAO,EAAE,gBAAgB,EAAE,CAAC;YAC9B,GAAG,CAAC,qDAAqD,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACnF,GAAG,CAAC,8DAA8D,CAAC,CAAC;QACtE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/session/output.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Session output file management.
+ *
+ * Handles writing final session output to disk.
+ * Note: Live preview/details now use IPC streaming instead of file writes.
+ */
+import type { BdgOutput } from '../types.js';
+/**
+ * Write session output to the final JSON file.
+ *
+ * This is written once at the end of a session.
+ * Note: Preview/details data is now accessed via IPC streaming during collection.
+ *
+ * @param output - The BdgOutput data to write
+ * @param compact - If true, use compact JSON format (no indentation)
+ */
+export declare function writeSessionOutput(output: BdgOutput, compact?: boolean): void;
+//# sourceMappingURL=output.d.ts.map

package/dist/session/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/session/output.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAKzC;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE,OAAe,GAAG,IAAI,CAKpF"}

package/dist/session/output.js

@@ -0,0 +1,24 @@
+/**
+ * Session output file management.
+ *
+ * Handles writing final session output to disk.
+ * Note: Live preview/details now use IPC streaming instead of file writes.
+ */
+import { AtomicFileWriter } from '../utils/atomicFile.js';
+import { getSessionFilePath, ensureSessionDir } from './paths.js';
+/**
+ * Write session output to the final JSON file.
+ *
+ * This is written once at the end of a session.
+ * Note: Preview/details data is now accessed via IPC streaming during collection.
+ *
+ * @param output - The BdgOutput data to write
+ * @param compact - If true, use compact JSON format (no indentation)
+ */
+export function writeSessionOutput(output, compact = false) {
+    ensureSessionDir();
+    const outputPath = getSessionFilePath('OUTPUT');
+    const jsonString = compact ? JSON.stringify(output) : JSON.stringify(output, null, 2);
+    AtomicFileWriter.writeSync(outputPath, jsonString);
+}
+//# sourceMappingURL=output.js.map

package/dist/session/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/session/output.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAiB,EAAE,UAAmB,KAAK;IAC5E,gBAAgB,EAAE,CAAC;IACnB,MAAM,UAAU,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACtF,gBAAgB,CAAC,SAAS,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;AACrD,CAAC"}

package/dist/session/paths.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Session path generation and management.
+ *
+ * Centralized path generation for all session-related files in ~/.bdg/
+ * WHY: Single source of truth for file locations prevents path inconsistencies.
+ */
+/**
+ * Session file paths relative to ~/.bdg/
+ * 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 DOM_QUERY_CACHE: "last-query.json";
+};
+/**
+ * Session file type for type-safe path generation
+ */
+export type SessionFileType = keyof typeof SESSION_FILES;
+/**
+ * Get the session directory path (~/.bdg)
+ *
+ * Uses os.homedir() dynamically to support test environment variable changes.
+ *
+ * @returns Full path to session directory
+ */
+export declare function getSessionDir(): string;
+/**
+ * Get the path to a session file by type.
+ *
+ * @param fileType - The type of session file
+ * @returns Full path to the session file
+ *
+ * @example
+ * ```typescript
+ * getSessionFilePath('PID')        // → ~/.bdg/session.pid
+ * getSessionFilePath('DAEMON_PID') // → ~/.bdg/daemon.pid
+ * ```
+ */
+export declare function getSessionFilePath(fileType: SessionFileType): string;
+/**
+ * Get the path to the worker Unix domain socket.
+ *
+ * WHY: Single canonical place for worker UDS path; predictable cleanup; avoids collisions.
+ *
+ * @param workerPid - Worker process ID
+ * @returns Full path to worker socket
+ */
+export declare function getWorkerSocketPath(workerPid: number): string;
+/**
+ * Get the path to the DOM query cache file.
+ *
+ * WHY: Stores last DOM query results for index-based element references.
+ *
+ * @returns Full path to DOM query cache file
+ */
+export declare function getDomQueryCachePath(): string;
+/**
+ * Ensure the session directory exists.
+ *
+ * Creates ~/.bdg/ if it doesn't exist. Safe to call multiple times (idempotent).
+ *
+ * @throws Error if directory creation fails due to permissions
+ */
+export declare function ensureSessionDir(): void;
+export {};
+//# sourceMappingURL=paths.d.ts.map

package/dist/session/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/session/paths.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;GAGG;AACH,QAAA,MAAM,aAAa;;;;;;;;;;CAUT,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,aAAa,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAEpE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAKvC"}

package/dist/session/paths.js

@@ -0,0 +1,84 @@
+/**
+ * Session path generation and management.
+ *
+ * Centralized path generation for all session-related files in ~/.bdg/
+ * 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';
+/**
+ * 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',
+    DOM_QUERY_CACHE: 'last-query.json',
+};
+/**
+ * Get the session directory path (~/.bdg)
+ *
+ * Uses os.homedir() dynamically to support test environment variable changes.
+ *
+ * @returns Full path to session directory
+ */
+export function getSessionDir() {
+    return path.join(os.homedir(), '.bdg');
+}
+/**
+ * Get the path to a session file by type.
+ *
+ * @param fileType - The type of session file
+ * @returns Full path to the session file
+ *
+ * @example
+ * ```typescript
+ * getSessionFilePath('PID')        // → ~/.bdg/session.pid
+ * getSessionFilePath('DAEMON_PID') // → ~/.bdg/daemon.pid
+ * ```
+ */
+export function getSessionFilePath(fileType) {
+    return path.join(getSessionDir(), SESSION_FILES[fileType]);
+}
+/**
+ * Get the path to the worker Unix domain socket.
+ *
+ * WHY: Single canonical place for worker UDS path; predictable cleanup; avoids collisions.
+ *
+ * @param workerPid - Worker process ID
+ * @returns Full path to worker socket
+ */
+export function getWorkerSocketPath(workerPid) {
+    return path.join(getSessionDir(), `worker.${workerPid}.sock`);
+}
+/**
+ * Get the path to the DOM query cache file.
+ *
+ * WHY: Stores last DOM query results for index-based element references.
+ *
+ * @returns Full path to DOM query cache file
+ */
+export function getDomQueryCachePath() {
+    return getSessionFilePath('DOM_QUERY_CACHE');
+}
+/**
+ * Ensure the session directory exists.
+ *
+ * Creates ~/.bdg/ if it doesn't exist. Safe to call multiple times (idempotent).
+ *
+ * @throws Error if directory creation fails due to permissions
+ */
+export function ensureSessionDir() {
+    const dir = getSessionDir();
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+//# sourceMappingURL=paths.js.map

package/dist/session/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/session/paths.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;GAGG;AACH,MAAM,aAAa,GAAG;IACpB,GAAG,EAAE,aAAa;IAClB,MAAM,EAAE,cAAc;IACtB,IAAI,EAAE,cAAc;IACpB,QAAQ,EAAE,mBAAmB;IAC7B,UAAU,EAAE,YAAY;IACxB,UAAU,EAAE,YAAY;IACxB,aAAa,EAAE,aAAa;IAC5B,WAAW,EAAE,aAAa;IAC1B,eAAe,EAAE,iBAAiB;CAC1B,CAAC;AAOX;;;;;;GAMG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAyB;IAC1D,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAiB;IACnD,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,UAAU,SAAS,OAAO,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,kBAAkB,CAAC,iBAAiB,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,GAAG,GAAG,aAAa,EAAE,CAAC;IAC5B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;AACH,CAAC"}

package/dist/session/pid.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Session PID file management.
+ *
+ * Handles reading/writing the main session PID file for tracking active sessions.
+ * WHY: Centralized PID operations prevent inconsistencies in session tracking.
+ */
+/**
+ * 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 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).
+ */
+export declare function cleanupPidFile(): void;
+//# sourceMappingURL=pid.d.ts.map

package/dist/session/pid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pid.d.ts","sourceRoot":"","sources":["../../src/session/pid.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAI1C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,IAAI,MAAM,GAAG,IAAI,CAmBvC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAUrC"}

package/dist/session/pid.js

@@ -0,0 +1,73 @@
+/**
+ * Session PID file management.
+ *
+ * Handles reading/writing the main session PID file for tracking active sessions.
+ * WHY: Centralized PID operations prevent inconsistencies in session tracking.
+ */
+import * as fs from 'fs';
+import { AtomicFileWriter } from '../utils/atomicFile.js';
+import { getSessionFilePath, ensureSessionDir } from './paths.js';
+/**
+ * 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.
+ *
+ * @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 function readPid() {
+    const pidPath = getSessionFilePath('PID');
+    if (!fs.existsSync(pidPath)) {
+        return null;
+    }
+    try {
+        const pidStr = fs.readFileSync(pidPath, 'utf-8').trim();
+        const pid = parseInt(pidStr, 10);
+        if (isNaN(pid)) {
+            return null;
+        }
+        return pid;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Remove the PID file.
+ *
+ * Safe to call multiple times (idempotent).
+ */
+export function cleanupPidFile() {
+    const pidPath = getSessionFilePath('PID');
+    if (fs.existsSync(pidPath)) {
+        try {
+            fs.unlinkSync(pidPath);
+        }
+        catch {
+            // Ignore errors during cleanup
+        }
+    }
+}
+//# sourceMappingURL=pid.js.map

package/dist/session/pid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pid.js","sourceRoot":"","sources":["../../src/session/pid.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAEzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAElE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,gBAAgB,EAAE,CAAC;IACnB,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC1C,gBAAgB,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,OAAO;IACrB,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAE1C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QACxD,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAEjC,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YACf,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAE1C,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACP,+BAA+B;QACjC,CAAC;IACH,CAAC;AACH,CAAC"}