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

package/dist/utils/__tests__/filters.unit.test.js

@@ -0,0 +1,239 @@
+import * as assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { matchesWildcard, shouldFetchBody, shouldExcludeUrl, shouldExcludeDomain, shouldExcludeConsoleMessage, DEFAULT_SKIP_BODY_PATTERNS, DEFAULT_EXCLUDED_DOMAINS, DEFAULT_EXCLUDED_CONSOLE_PATTERNS, } from '../filters.js';
+void describe('filters - matchesWildcard', () => {
+    void it('should match exact strings', () => {
+        assert.equal(matchesWildcard('api.example.com', 'api.example.com'), true);
+        assert.equal(matchesWildcard('api.example.com/users', 'api.example.com/users'), true);
+        assert.equal(matchesWildcard('api.example.com', 'cdn.example.com'), false);
+    });
+    void it('should match wildcards at start', () => {
+        assert.equal(matchesWildcard('logo.png', '*.png'), true);
+        assert.equal(matchesWildcard('images/logo.png', '*.png'), true);
+        assert.equal(matchesWildcard('logo.jpg', '*.png'), false);
+    });
+    void it('should match wildcards at end', () => {
+        assert.equal(matchesWildcard('api.example.com', 'api.*'), true);
+        assert.equal(matchesWildcard('api.test.com', 'api.*'), true);
+        assert.equal(matchesWildcard('cdn.example.com', 'api.*'), false);
+    });
+    void it('should match wildcards in middle', () => {
+        assert.equal(matchesWildcard('analytics.google.com', '*analytics*'), true);
+        assert.equal(matchesWildcard('google-analytics.com', '*analytics*'), true);
+        assert.equal(matchesWildcard('example.com/api/users', '*/api/*'), true);
+        assert.equal(matchesWildcard('example.com/v1/data', '*/api/*'), false);
+    });
+    void it('should be case-insensitive', () => {
+        assert.equal(matchesWildcard('API.EXAMPLE.COM', 'api.example.com'), true);
+        assert.equal(matchesWildcard('api.example.com', 'API.EXAMPLE.COM'), true);
+        assert.equal(matchesWildcard('Logo.PNG', '*.png'), true);
+    });
+    void it('should match multiple wildcards', () => {
+        assert.equal(matchesWildcard('api.example.com/users', '*api*/*'), true);
+        assert.equal(matchesWildcard('example.com/api/users', '*/api/*'), true);
+        assert.equal(matchesWildcard('example.com/v1/data', '*example*/v1/*'), true);
+    });
+    void it('should match empty pattern', () => {
+        assert.equal(matchesWildcard('anything', ''), false);
+        assert.equal(matchesWildcard('', ''), true);
+    });
+    void it('should match just wildcard', () => {
+        assert.equal(matchesWildcard('anything', '*'), true);
+        assert.equal(matchesWildcard('', '*'), true);
+    });
+});
+void describe('filters - shouldFetchBody', () => {
+    void it('should fetch bodies by default', () => {
+        assert.equal(shouldFetchBody('https://api.example.com/users', 'application/json'), true);
+        assert.equal(shouldFetchBody('https://example.com/app.js', 'application/javascript'), true);
+    });
+    void it('should skip bodies matching DEFAULT_SKIP_BODY_PATTERNS', () => {
+        // Images
+        assert.equal(shouldFetchBody('https://example.com/logo.png', 'image/png'), false);
+        assert.equal(shouldFetchBody('https://example.com/photo.jpg', 'image/jpeg'), false);
+        assert.equal(shouldFetchBody('https://example.com/icon.svg', 'image/svg+xml'), false);
+        // Fonts
+        assert.equal(shouldFetchBody('https://example.com/font.woff2', 'font/woff2'), false);
+        assert.equal(shouldFetchBody('https://example.com/font.ttf', 'font/ttf'), false);
+        // CSS
+        assert.equal(shouldFetchBody('https://example.com/styles.css', 'text/css'), false);
+        // Source maps
+        assert.equal(shouldFetchBody('https://example.com/app.js.map', 'application/json'), false);
+        assert.equal(shouldFetchBody('https://example.com/styles.css.map', 'application/json'), false);
+    });
+    void it('should respect includePatterns (trumps exclude and defaults)', () => {
+        const options = {
+            includePatterns: ['*/api/*'],
+            excludePatterns: ['*example.com*'],
+        };
+        // Include pattern matches, so fetch despite exclude pattern
+        assert.equal(shouldFetchBody('https://example.com/api/users', 'application/json', options), true);
+        // Include pattern matches, so fetch despite default skip pattern
+        const optionsWithImage = {
+            includePatterns: ['*.png'],
+        };
+        assert.equal(shouldFetchBody('https://example.com/logo.png', 'image/png', optionsWithImage), true);
+    });
+    void it('should treat includePatterns as whitelist (skip non-matching URLs)', () => {
+        const options = {
+            includePatterns: ['*/api/*', '*/graphql'],
+        };
+        // Matches include pattern → fetch
+        assert.equal(shouldFetchBody('https://example.com/api/users', 'application/json', options), true);
+        assert.equal(shouldFetchBody('https://example.com/graphql', 'application/json', options), true);
+        // Doesn't match include pattern → skip (whitelist mode)
+        assert.equal(shouldFetchBody('https://example.com/app.js', 'application/javascript', options), false);
+        assert.equal(shouldFetchBody('https://example.com/index.html', 'text/html', options), false);
+        assert.equal(shouldFetchBody('https://example.com/data.json', 'application/json', options), false);
+    });
+    void it('should respect excludePatterns', () => {
+        const options = {
+            excludePatterns: ['*tracking*', '*analytics*'],
+        };
+        assert.equal(shouldFetchBody('https://tracking.example.com/collect', 'application/json', options), false);
+        assert.equal(shouldFetchBody('https://analytics.example.com/event', 'application/json', options), false);
+        assert.equal(shouldFetchBody('https://api.example.com/users', 'application/json', options), true);
+    });
+    void it('should respect fetchAllBodies flag', () => {
+        const options = {
+            fetchAllBodies: true,
+        };
+        // Fetch even images when fetchAllBodies is true
+        assert.equal(shouldFetchBody('https://example.com/logo.png', 'image/png', options), true);
+        assert.equal(shouldFetchBody('https://example.com/styles.css', 'text/css', options), true);
+        assert.equal(shouldFetchBody('https://example.com/app.js.map', 'application/json', options), true);
+    });
+    void it('should combine patterns with correct precedence: include > exclude > fetchAllBodies > defaults', () => {
+        // Include trumps everything
+        assert.equal(shouldFetchBody('https://example.com/logo.png', 'image/png', {
+            includePatterns: ['*.png'],
+            excludePatterns: ['*example.com*'],
+            fetchAllBodies: false,
+        }), true);
+        // Exclude trumps fetchAllBodies and defaults
+        assert.equal(shouldFetchBody('https://tracking.com/pixel.png', 'image/png', {
+            excludePatterns: ['*tracking*'],
+            fetchAllBodies: true,
+        }), false);
+        // fetchAllBodies trumps defaults
+        assert.equal(shouldFetchBody('https://example.com/logo.png', 'image/png', {
+            fetchAllBodies: true,
+        }), true);
+        // Defaults apply when no options
+        assert.equal(shouldFetchBody('https://example.com/logo.png', 'image/png'), false);
+    });
+});
+void describe('filters - shouldExcludeUrl', () => {
+    void it('should not exclude by default', () => {
+        assert.equal(shouldExcludeUrl('https://api.example.com/users'), false);
+        assert.equal(shouldExcludeUrl('https://example.com/logo.png'), false);
+    });
+    void it('should respect includePatterns (trumps exclude)', () => {
+        const options = {
+            includePatterns: ['api.example.com'],
+            excludePatterns: ['*example.com*'],
+        };
+        // Include pattern matches, so don't exclude despite exclude pattern
+        assert.equal(shouldExcludeUrl('https://api.example.com/users', options), false);
+        // Exclude pattern matches but no include match (includePatterns act as whitelist)
+        assert.equal(shouldExcludeUrl('https://cdn.example.com/logo.png', options), true);
+        // Neither pattern matches (includePatterns act as whitelist, so exclude)
+        assert.equal(shouldExcludeUrl('https://other.com/data', options), true);
+    });
+    void it('should respect excludePatterns', () => {
+        const options = {
+            excludePatterns: ['*analytics*', '*tracking*', '*ads*'],
+        };
+        assert.equal(shouldExcludeUrl('https://analytics.google.com/collect', options), true);
+        assert.equal(shouldExcludeUrl('https://tracking.example.com/pixel', options), true);
+        assert.equal(shouldExcludeUrl('https://ads.example.com/banner', options), true);
+        assert.equal(shouldExcludeUrl('https://api.example.com/users', options), false);
+    });
+    void it('should match bare hostname patterns without requiring wildcards', () => {
+        const options = {
+            includePatterns: ['api.example.com'],
+        };
+        // Should match all URLs on api.example.com regardless of path
+        assert.equal(shouldExcludeUrl('https://api.example.com/users', options), false);
+        assert.equal(shouldExcludeUrl('https://api.example.com/posts', options), false);
+        assert.equal(shouldExcludeUrl('https://api.example.com/', options), false);
+        // Should not match other hosts
+        assert.equal(shouldExcludeUrl('https://cdn.example.com/users', options), true);
+    });
+});
+void describe('filters - shouldExcludeDomain', () => {
+    void it('should not exclude by default when includeAll is true', () => {
+        assert.equal(shouldExcludeDomain('https://analytics.google.com/collect', true), false);
+        assert.equal(shouldExcludeDomain('https://facebook.com/tracking', true), false);
+    });
+    void it('should exclude DEFAULT_EXCLUDED_DOMAINS', () => {
+        // Sample from DEFAULT_EXCLUDED_DOMAINS
+        assert.equal(shouldExcludeDomain('https://analytics.google.com/collect'), true);
+        assert.equal(shouldExcludeDomain('https://googletagmanager.com/gtm.js'), true);
+        assert.equal(shouldExcludeDomain('https://facebook.com/tracking'), true);
+        assert.equal(shouldExcludeDomain('https://doubleclick.net/ads'), true);
+        assert.equal(shouldExcludeDomain('https://fullstory.com/rec'), true);
+    });
+    void it('should not exclude non-tracking domains', () => {
+        assert.equal(shouldExcludeDomain('https://api.example.com/users'), false);
+        assert.equal(shouldExcludeDomain('https://cdn.example.com/app.js'), false);
+        assert.equal(shouldExcludeDomain('https://example.com/'), false);
+    });
+    void it('should handle subdomains correctly', () => {
+        // Should match if domain is contained in hostname
+        assert.equal(shouldExcludeDomain('https://www.analytics.google.com/collect'), true);
+        assert.equal(shouldExcludeDomain('https://subdomain.facebook.com/pixel'), true);
+    });
+});
+void describe('filters - shouldExcludeConsoleMessage', () => {
+    void it('should not exclude by default when includeAll is true', () => {
+        assert.equal(shouldExcludeConsoleMessage('webpack-dev-server: Hot Module Replacement', 'log', true), false);
+        assert.equal(shouldExcludeConsoleMessage('[HMR] Waiting for update signal', 'log', true), false);
+    });
+    void it('should exclude DEFAULT_EXCLUDED_CONSOLE_PATTERNS', () => {
+        assert.equal(shouldExcludeConsoleMessage('webpack-dev-server: Hot Module Replacement', 'log'), true);
+        assert.equal(shouldExcludeConsoleMessage('[HMR] Waiting for update signal from WDS...', 'log'), true);
+        assert.equal(shouldExcludeConsoleMessage('[WDS] Live Reloading enabled.', 'log'), true);
+        assert.equal(shouldExcludeConsoleMessage('Download the React DevTools for a better development experience', 'log'), true);
+    });
+    void it('should exclude group message types', () => {
+        assert.equal(shouldExcludeConsoleMessage('Some group', 'startGroupCollapsed'), true);
+        assert.equal(shouldExcludeConsoleMessage('', 'endGroup'), true);
+        assert.equal(shouldExcludeConsoleMessage('Normal log', 'log'), false);
+    });
+    void it('should not exclude non-dev-server messages', () => {
+        assert.equal(shouldExcludeConsoleMessage('User clicked button', 'log'), false);
+        assert.equal(shouldExcludeConsoleMessage('API request failed', 'error'), false);
+        assert.equal(shouldExcludeConsoleMessage('Error: Invalid input', 'error'), false);
+    });
+    void it('should be case-insensitive', () => {
+        assert.equal(shouldExcludeConsoleMessage('WEBPACK-DEV-SERVER: Hot Module Replacement', 'log'), true);
+        assert.equal(shouldExcludeConsoleMessage('[hmr] waiting for update signal', 'log'), true);
+    });
+});
+void describe('filters - constants', () => {
+    void it('DEFAULT_SKIP_BODY_PATTERNS should include common asset patterns', () => {
+        // Verify key patterns exist
+        assert.ok(DEFAULT_SKIP_BODY_PATTERNS.includes('*.png'));
+        assert.ok(DEFAULT_SKIP_BODY_PATTERNS.includes('*.jpg'));
+        assert.ok(DEFAULT_SKIP_BODY_PATTERNS.includes('*.woff2'));
+        assert.ok(DEFAULT_SKIP_BODY_PATTERNS.includes('*.css'));
+        assert.ok(DEFAULT_SKIP_BODY_PATTERNS.includes('*.map'));
+        assert.ok(DEFAULT_SKIP_BODY_PATTERNS.includes('*.js.map'));
+        assert.ok(DEFAULT_SKIP_BODY_PATTERNS.includes('*.css.map'));
+    });
+    void it('DEFAULT_EXCLUDED_DOMAINS should include common tracking domains', () => {
+        // Verify key domains exist
+        assert.ok(DEFAULT_EXCLUDED_DOMAINS.includes('analytics.google.com'));
+        assert.ok(DEFAULT_EXCLUDED_DOMAINS.includes('googletagmanager.com'));
+        assert.ok(DEFAULT_EXCLUDED_DOMAINS.includes('facebook.com'));
+        assert.ok(DEFAULT_EXCLUDED_DOMAINS.includes('doubleclick.net'));
+    });
+    void it('DEFAULT_EXCLUDED_CONSOLE_PATTERNS should include dev server noise', () => {
+        // Verify key patterns exist
+        assert.ok(DEFAULT_EXCLUDED_CONSOLE_PATTERNS.includes('webpack-dev-server'));
+        assert.ok(DEFAULT_EXCLUDED_CONSOLE_PATTERNS.includes('[HMR]'));
+        assert.ok(DEFAULT_EXCLUDED_CONSOLE_PATTERNS.includes('[WDS]'));
+    });
+});
+//# sourceMappingURL=filters.unit.test.js.map

package/dist/utils/__tests__/filters.unit.test.js.map

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

package/dist/utils/__tests__/session.contract.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=session.contract.test.d.ts.map

package/dist/utils/__tests__/session.contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.contract.test.d.ts","sourceRoot":"","sources":["../../../src/utils/__tests__/session.contract.test.ts"],"names":[],"mappings":""}

package/dist/utils/__tests__/session.contract.test.js

@@ -0,0 +1,234 @@
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, it } from 'node:test';
+import { mockProcessAlive, restoreProcessAlive } from '../../__testutils__/testProcess.js';
+import { cleanupStaleSession } from '../../session/cleanup.js';
+import { acquireSessionLock, releaseSessionLock } from '../../session/lock.js';
+import { writeSessionMetadata } from '../../session/metadata.js';
+import { getSessionFilePath } from '../../session/paths.js';
+import { readPid, writePid } from '../../session/pid.js';
+import { isProcessAlive } from '../../session/process.js';
+/**
+ * Session Utilities Contract Tests
+ *
+ * Week 1 Note: Using real temp directories instead of FakeFileSystem
+ * because mocking built-in Node modules is complex. This still validates
+ * the contracts while keeping tests simple and fast.
+ */
+void describe('Session Utilities Contract Tests', () => {
+    let tmpDir;
+    let originalHome;
+    let originalUserProfile;
+    let originalProcessPid;
+    beforeEach(() => {
+        // Create temp directory for each test
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bdg-test-'));
+        // Mock process.pid for predictable tests
+        originalProcessPid = process.pid;
+        Object.defineProperty(process, 'pid', {
+            value: 12345,
+            writable: true,
+            configurable: true,
+        });
+        // Override HOME environment variable to point to temp directory
+        // os.homedir() uses this on Unix systems
+        originalHome = process.env['HOME'];
+        originalUserProfile = process.env['USERPROFILE'];
+        process.env['HOME'] = tmpDir;
+        if (process.platform === 'win32') {
+            process.env['USERPROFILE'] = tmpDir;
+        }
+    });
+    afterEach(() => {
+        // Restore process.pid
+        Object.defineProperty(process, 'pid', {
+            value: originalProcessPid,
+            writable: true,
+            configurable: true,
+        });
+        // Restore process.kill mock
+        restoreProcessAlive();
+        // Restore HOME environment variable
+        process.env['HOME'] = originalHome;
+        if (process.platform === 'win32') {
+            process.env['USERPROFILE'] = originalUserProfile;
+        }
+        // ⚠️ CRITICAL: Clean up temp directory
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    void describe('PID Management', () => {
+        void it('should write PID to file with correct content', () => {
+            writePid(12345);
+            const pidPath = getSessionFilePath('PID');
+            const content = fs.readFileSync(pidPath, 'utf-8');
+            assert.equal(content, '12345');
+        });
+        void it('should read PID from existing file', () => {
+            writePid(67890);
+            const pid = readPid();
+            assert.equal(pid, 67890);
+        });
+        void it('should return null when PID file does not exist', () => {
+            // Ensure PID file doesn't exist (cleanup from previous test)
+            const pidPath = getSessionFilePath('PID');
+            if (fs.existsSync(pidPath)) {
+                fs.unlinkSync(pidPath);
+            }
+            const pid = readPid();
+            assert.equal(pid, null);
+        });
+    });
+    void describe('Lock Management', () => {
+        void it('should create lock file with current process PID', () => {
+            const acquired = acquireSessionLock();
+            assert.equal(acquired, true);
+            const lockPath = getSessionFilePath('LOCK');
+            const content = fs.readFileSync(lockPath, 'utf-8');
+            assert.equal(content, '12345'); // process.pid from beforeEach
+        });
+        void it('should return false if lock is held by alive process', () => {
+            // Setup: Create lock file held by alive process
+            const lockPath = getSessionFilePath('LOCK');
+            const sessionDir = path.join(tmpDir, '.bdg');
+            fs.mkdirSync(sessionDir, { recursive: true });
+            fs.writeFileSync(lockPath, '99999');
+            // Mock process 99999 as alive
+            mockProcessAlive([99999]);
+            // Act
+            const acquired = acquireSessionLock();
+            // Assert
+            assert.equal(acquired, false);
+        });
+        void it('should remove stale lock and acquire if holder PID is dead', () => {
+            // Setup: Create lock file held by dead process
+            const lockPath = getSessionFilePath('LOCK');
+            const sessionDir = path.join(tmpDir, '.bdg');
+            fs.mkdirSync(sessionDir, { recursive: true });
+            fs.writeFileSync(lockPath, '88888');
+            // Mock process 88888 as dead (not in alive list)
+            mockProcessAlive([]);
+            // Act
+            const acquired = acquireSessionLock();
+            // Assert
+            assert.equal(acquired, true, 'Should acquire lock after removing stale one');
+            const newContent = fs.readFileSync(lockPath, 'utf-8');
+            assert.equal(newContent, '12345', 'Should write current PID');
+        });
+        void it('should remove lock file when released', () => {
+            // Setup: Acquire lock first
+            acquireSessionLock();
+            const lockPath = getSessionFilePath('LOCK');
+            assert.equal(fs.existsSync(lockPath), true, 'Lock file should exist');
+            // Act
+            releaseSessionLock();
+            // Assert
+            assert.equal(fs.existsSync(lockPath), false, 'Lock file should be removed');
+        });
+        void it('should handle concurrent acquisition via exclusive create flag', () => {
+            // Setup: Acquire lock first
+            acquireSessionLock();
+            // Mock current process as alive
+            mockProcessAlive([12345]);
+            // Act: Try to acquire again from same process (simulates race condition)
+            const secondAttempt = acquireSessionLock();
+            // Assert: Should fail because file exists and process is alive
+            assert.equal(secondAttempt, false, 'Should not acquire lock twice');
+        });
+    });
+    void describe('Process Alive Checks', () => {
+        void it('should return true for alive process', () => {
+            mockProcessAlive([12345, 67890]);
+            assert.equal(isProcessAlive(12345), true);
+            assert.equal(isProcessAlive(67890), true);
+        });
+        void it('should return false for dead process', () => {
+            mockProcessAlive([12345]);
+            assert.equal(isProcessAlive(99999), false);
+        });
+    });
+    void describe('Stale Session Cleanup', () => {
+        void it('should remove stale session files when process is dead', () => {
+            // Setup: Create stale session files
+            const sessionDir = path.join(tmpDir, '.bdg');
+            fs.mkdirSync(sessionDir, { recursive: true });
+            writePid(88888);
+            writeSessionMetadata({
+                bdgPid: 88888,
+                chromePid: 77777,
+                startTime: Date.now(),
+                port: 9222,
+            });
+            fs.writeFileSync(getSessionFilePath('DAEMON_PID'), '66666');
+            fs.writeFileSync(getSessionFilePath('DAEMON_SOCKET'), '');
+            // Mock all processes as dead
+            mockProcessAlive([]);
+            // Act
+            const cleaned = cleanupStaleSession();
+            // Assert
+            assert.equal(cleaned, true, 'Should return true when cleanup was performed');
+            assert.equal(fs.existsSync(getSessionFilePath('PID')), false, 'PID file should be removed');
+            assert.equal(fs.existsSync(getSessionFilePath('DAEMON_PID')), false, 'Daemon PID should be removed');
+            assert.equal(fs.existsSync(getSessionFilePath('DAEMON_SOCKET')), false, 'Daemon socket should be removed');
+        });
+        void it('should not remove files when session process is alive', () => {
+            // Setup: Create session files with alive process
+            const sessionDir = path.join(tmpDir, '.bdg');
+            fs.mkdirSync(sessionDir, { recursive: true });
+            writePid(88888);
+            writeSessionMetadata({
+                bdgPid: 88888,
+                chromePid: 77777,
+                startTime: Date.now(),
+                port: 9222,
+            });
+            // Mock process 88888 as alive
+            mockProcessAlive([88888]);
+            // Act
+            const cleaned = cleanupStaleSession();
+            // Assert
+            assert.equal(cleaned, false, 'Should return false when session is active');
+            assert.equal(fs.existsSync(getSessionFilePath('PID')), true, 'PID file should still exist');
+        });
+        void it('should not remove files when daemon process is alive', () => {
+            // Setup: Create session files with dead session but alive daemon
+            const sessionDir = path.join(tmpDir, '.bdg');
+            fs.mkdirSync(sessionDir, { recursive: true });
+            writePid(88888);
+            fs.writeFileSync(getSessionFilePath('DAEMON_PID'), '66666');
+            // Mock only daemon as alive (session process is dead)
+            mockProcessAlive([66666]);
+            // Act
+            const cleaned = cleanupStaleSession();
+            // Assert
+            assert.equal(cleaned, false, 'Should return false when daemon is still alive');
+            assert.equal(fs.existsSync(getSessionFilePath('PID')), true, 'PID file should still exist');
+            assert.equal(fs.existsSync(getSessionFilePath('DAEMON_PID')), true, 'Daemon PID should still exist');
+        });
+        void it('should cleanup daemon artifacts when daemon process is dead', () => {
+            // Setup: Create daemon files with dead process
+            const sessionDir = path.join(tmpDir, '.bdg');
+            fs.mkdirSync(sessionDir, { recursive: true });
+            fs.writeFileSync(getSessionFilePath('DAEMON_PID'), '66666');
+            fs.writeFileSync(getSessionFilePath('DAEMON_SOCKET'), '');
+            // Mock process as dead
+            mockProcessAlive([]);
+            // Act
+            const cleaned = cleanupStaleSession();
+            // Assert
+            assert.equal(cleaned, true, 'Should cleanup when daemon is dead');
+            assert.equal(fs.existsSync(getSessionFilePath('DAEMON_PID')), false, 'Daemon PID should be removed');
+            assert.equal(fs.existsSync(getSessionFilePath('DAEMON_SOCKET')), false, 'Daemon socket should be removed');
+        });
+        void it('should handle missing files gracefully', () => {
+            // Setup: No files exist
+            mockProcessAlive([]);
+            // Act - should not throw
+            const cleaned = cleanupStaleSession();
+            // Assert
+            assert.equal(cleaned, true, 'Should succeed even with no files');
+        });
+    });
+});
+//# sourceMappingURL=session.contract.test.js.map

package/dist/utils/__tests__/session.contract.test.js.map

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

package/dist/utils/atomicFile.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Atomic file operations using tmp-file-then-rename pattern.
+ *
+ * Provides safe file writing that prevents corruption from interrupted writes
+ * or concurrent access by using a temporary file and atomic rename operation.
+ */
+export declare class AtomicFileWriter {
+    /**
+     * Write data to a file atomically (synchronous).
+     *
+     * Creates a temporary file, writes the data, then atomically renames it to the target path.
+     * This ensures the target file is never in a partially written state.
+     *
+     * @param filePath - Target file path
+     * @param data - Data to write
+     * @param options - Write options
+     * @throws Error if write operation fails
+     */
+    static writeSync(filePath: string, data: string, options?: {
+        encoding?: BufferEncoding;
+    }): void;
+    /**
+     * Write data to a file atomically (asynchronous).
+     *
+     * Creates a temporary file, writes the data, then atomically renames it to the target path.
+     * This ensures the target file is never in a partially written state.
+     *
+     * @param filePath - Target file path
+     * @param data - Data to write
+     * @param options - Write options
+     * @returns Promise that resolves when write completes
+     * @throws Error if write operation fails
+     */
+    static writeAsync(filePath: string, data: string, options?: {
+        encoding?: BufferEncoding;
+    }): Promise<void>;
+}
+//# sourceMappingURL=atomicFile.d.ts.map

package/dist/utils/atomicFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomicFile.d.ts","sourceRoot":"","sources":["../../src/utils/atomicFile.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,SAAS,CACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAO,GAC1C,IAAI;IAoBP;;;;;;;;;;;OAWG;WACU,UAAU,CACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAO,GAC1C,OAAO,CAAC,IAAI,CAAC;CAmBjB"}

package/dist/utils/atomicFile.js

@@ -0,0 +1,71 @@
+import * as fs from 'fs';
+/**
+ * Atomic file operations using tmp-file-then-rename pattern.
+ *
+ * Provides safe file writing that prevents corruption from interrupted writes
+ * or concurrent access by using a temporary file and atomic rename operation.
+ */
+export class AtomicFileWriter {
+    /**
+     * Write data to a file atomically (synchronous).
+     *
+     * Creates a temporary file, writes the data, then atomically renames it to the target path.
+     * This ensures the target file is never in a partially written state.
+     *
+     * @param filePath - Target file path
+     * @param data - Data to write
+     * @param options - Write options
+     * @throws Error if write operation fails
+     */
+    static writeSync(filePath, data, options = {}) {
+        const tmpPath = filePath + '.tmp';
+        try {
+            // Write to temporary file first
+            fs.writeFileSync(tmpPath, data, { encoding: options.encoding ?? 'utf-8' });
+            // Atomically rename to target path
+            fs.renameSync(tmpPath, filePath);
+        }
+        catch (error) {
+            // Clean up temporary file on error
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            throw error;
+        }
+    }
+    /**
+     * Write data to a file atomically (asynchronous).
+     *
+     * Creates a temporary file, writes the data, then atomically renames it to the target path.
+     * This ensures the target file is never in a partially written state.
+     *
+     * @param filePath - Target file path
+     * @param data - Data to write
+     * @param options - Write options
+     * @returns Promise that resolves when write completes
+     * @throws Error if write operation fails
+     */
+    static async writeAsync(filePath, data, options = {}) {
+        const tmpPath = filePath + '.tmp';
+        try {
+            // Write to temporary file first
+            await fs.promises.writeFile(tmpPath, data, { encoding: options.encoding ?? 'utf-8' });
+            // Atomically rename to target path
+            await fs.promises.rename(tmpPath, filePath);
+        }
+        catch (error) {
+            // Clean up temporary file on error
+            try {
+                await fs.promises.unlink(tmpPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=atomicFile.js.map

package/dist/utils/atomicFile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomicFile.js","sourceRoot":"","sources":["../../src/utils/atomicFile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAEzB;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IAC3B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,SAAS,CACd,QAAgB,EAChB,IAAY,EACZ,UAAyC,EAAE;QAE3C,MAAM,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;QAElC,IAAI,CAAC;YACH,gCAAgC;YAChC,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,OAAO,EAAE,CAAC,CAAC;YAE3E,mCAAmC;YACnC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACnC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,mCAAmC;YACnC,IAAI,CAAC;gBACH,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YACzB,CAAC;YAAC,MAAM,CAAC;gBACP,wBAAwB;YAC1B,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,KAAK,CAAC,UAAU,CACrB,QAAgB,EAChB,IAAY,EACZ,UAAyC,EAAE;QAE3C,MAAM,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;QAElC,IAAI,CAAC;YACH,gCAAgC;YAChC,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,OAAO,EAAE,CAAC,CAAC;YAEtF,mCAAmC;YACnC,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,mCAAmC;YACnC,IAAI,CAAC;gBACH,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACpC,CAAC;YAAC,MAAM,CAAC;gBACP,wBAAwB;YAC1B,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}