observability-toolkit 1.8.2 → 1.8.5

package/dist/lib/circuit-breaker.test.js

@@ -0,0 +1,263 @@
+import { describe, it, before, after, beforeEach } from 'node:test';
+import * as assert from 'node:assert';
+import { CircuitBreaker } from './circuit-breaker.js';
+describe('CircuitBreaker', () => {
+    describe('initial state', () => {
+        it('should start in closed state', () => {
+            const breaker = new CircuitBreaker();
+            assert.strictEqual(breaker.getState(), 'closed');
+            assert.strictEqual(breaker.getFailureCount(), 0);
+        });
+        it('should allow requests when closed', () => {
+            const breaker = new CircuitBreaker();
+            assert.strictEqual(breaker.canRequest(), true);
+        });
+    });
+    describe('failure handling', () => {
+        it('should track consecutive failures', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3 });
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getFailureCount(), 1);
+            assert.strictEqual(breaker.getState(), 'closed');
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getFailureCount(), 2);
+            assert.strictEqual(breaker.getState(), 'closed');
+        });
+        it('should open after maxFailures consecutive failures', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3 });
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getState(), 'open');
+            assert.strictEqual(breaker.getFailureCount(), 3);
+        });
+        it('should reject requests when open', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3 });
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            assert.strictEqual(breaker.canRequest(), false);
+        });
+    });
+    describe('success handling', () => {
+        it('should reset failure count on success', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3 });
+            breaker.recordFailure();
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getFailureCount(), 2);
+            breaker.recordSuccess();
+            assert.strictEqual(breaker.getFailureCount(), 0);
+            assert.strictEqual(breaker.getState(), 'closed');
+        });
+        it('should stay closed after partial failures followed by success', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3 });
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordSuccess();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            // Should still be closed (only 2 consecutive failures)
+            assert.strictEqual(breaker.getState(), 'closed');
+        });
+    });
+    describe('half-open state', () => {
+        let originalDateNow;
+        let currentTime;
+        before(() => {
+            originalDateNow = Date.now;
+        });
+        beforeEach(() => {
+            currentTime = 1000000;
+            Date.now = () => currentTime;
+        });
+        after(() => {
+            Date.now = originalDateNow;
+        });
+        it('should transition to half-open after reset timeout', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: 60000 });
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getState(), 'open');
+            // Advance time past reset period
+            currentTime += 61000;
+            // Should transition to half-open and allow request
+            assert.strictEqual(breaker.canRequest(), true);
+            assert.strictEqual(breaker.getState(), 'half-open');
+        });
+        it('should close on success in half-open state', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: 60000 });
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            // Advance time and allow half-open
+            currentTime += 61000;
+            breaker.canRequest();
+            assert.strictEqual(breaker.getState(), 'half-open');
+            // Success should close the circuit
+            breaker.recordSuccess();
+            assert.strictEqual(breaker.getState(), 'closed');
+            assert.strictEqual(breaker.getFailureCount(), 0);
+        });
+        it('should reopen on failure in half-open state', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: 60000 });
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            // Advance time and allow half-open
+            currentTime += 61000;
+            breaker.canRequest();
+            assert.strictEqual(breaker.getState(), 'half-open');
+            // Failure should reopen
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getState(), 'open');
+        });
+        it('should not allow request before reset timeout', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: 60000 });
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getState(), 'open');
+            // Advance time but not past reset period
+            currentTime += 30000;
+            assert.strictEqual(breaker.canRequest(), false);
+            assert.strictEqual(breaker.getState(), 'open');
+        });
+    });
+    describe('reset', () => {
+        it('should reset to initial state', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3 });
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getState(), 'open');
+            // Reset
+            breaker.reset();
+            assert.strictEqual(breaker.getState(), 'closed');
+            assert.strictEqual(breaker.getFailureCount(), 0);
+            assert.strictEqual(breaker.canRequest(), true);
+        });
+        it('should reset halfOpenRequestInFlight flag', () => {
+            const originalDateNow = Date.now;
+            let currentTime = 1000000;
+            Date.now = () => currentTime;
+            try {
+                const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: 60000 });
+                // Open and transition to half-open
+                breaker.recordFailure();
+                breaker.recordFailure();
+                breaker.recordFailure();
+                currentTime += 61000;
+                breaker.canRequest();
+                // Flag should be set
+                assert.strictEqual(breaker.isHalfOpenRequestInFlight(), true);
+                // Reset should clear it
+                breaker.reset();
+                assert.strictEqual(breaker.isHalfOpenRequestInFlight(), false);
+            }
+            finally {
+                Date.now = originalDateNow;
+            }
+        });
+    });
+    describe('half-open race condition prevention (H2)', () => {
+        let originalDateNow;
+        let currentTime;
+        before(() => {
+            originalDateNow = Date.now;
+        });
+        beforeEach(() => {
+            currentTime = 1000000;
+            Date.now = () => currentTime;
+        });
+        after(() => {
+            Date.now = originalDateNow;
+        });
+        it('should only allow one request through during half-open state', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: 60000 });
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            // Advance time past reset period
+            currentTime += 61000;
+            // First request should be allowed (transitions to half-open)
+            assert.strictEqual(breaker.canRequest(), true);
+            assert.strictEqual(breaker.getState(), 'half-open');
+            assert.strictEqual(breaker.isHalfOpenRequestInFlight(), true);
+            // Second concurrent request should be rejected
+            assert.strictEqual(breaker.canRequest(), false);
+            assert.strictEqual(breaker.getState(), 'half-open');
+        });
+        it('should clear halfOpenRequestInFlight on success', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: 60000 });
+            // Open and transition to half-open
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            currentTime += 61000;
+            breaker.canRequest();
+            assert.strictEqual(breaker.isHalfOpenRequestInFlight(), true);
+            // Success should clear the flag
+            breaker.recordSuccess();
+            assert.strictEqual(breaker.isHalfOpenRequestInFlight(), false);
+            assert.strictEqual(breaker.getState(), 'closed');
+        });
+        it('should clear halfOpenRequestInFlight on failure', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: 60000 });
+            // Open and transition to half-open
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            currentTime += 61000;
+            breaker.canRequest();
+            assert.strictEqual(breaker.isHalfOpenRequestInFlight(), true);
+            // Failure should clear the flag
+            breaker.recordFailure();
+            assert.strictEqual(breaker.isHalfOpenRequestInFlight(), false);
+            assert.strictEqual(breaker.getState(), 'open');
+        });
+        it('should allow next request after half-open failure and timeout', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 3, resetMs: 60000 });
+            // Open the circuit
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            // First half-open attempt
+            currentTime += 61000;
+            assert.strictEqual(breaker.canRequest(), true);
+            breaker.recordFailure();
+            // Should be open again
+            assert.strictEqual(breaker.getState(), 'open');
+            // Wait for another reset period
+            currentTime += 61000;
+            // Should allow another half-open request
+            assert.strictEqual(breaker.canRequest(), true);
+            assert.strictEqual(breaker.getState(), 'half-open');
+        });
+    });
+    describe('configuration', () => {
+        it('should use custom maxFailures', () => {
+            const breaker = new CircuitBreaker({ maxFailures: 5 });
+            breaker.recordFailure();
+            breaker.recordFailure();
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getState(), 'closed');
+            breaker.recordFailure();
+            breaker.recordFailure();
+            assert.strictEqual(breaker.getState(), 'open');
+        });
+        it('should use custom name in logging', () => {
+            const breaker = new CircuitBreaker({ name: 'test-breaker' });
+            // Name is used internally for logging, verify it doesn't throw
+            breaker.recordFailure();
+            breaker.recordSuccess();
+        });
+    });
+});
+//# sourceMappingURL=circuit-breaker.test.js.map

package/dist/lib/circuit-breaker.test.js.map

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

package/dist/lib/constants-symlink.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Symlink protection TOCTOU tests (A2 Category 3)
+ *
+ * Tests the atomic path checking and symlink protection in getTelemetryDirectories.
+ * Verifies protection against:
+ * - Symlink swap attacks (TOCTOU)
+ * - Broken symlinks
+ * - Circular symlink chains
+ * - Symlinks escaping allowed directories
+ */
+export {};
+//# sourceMappingURL=constants-symlink.test.d.ts.map

package/dist/lib/constants-symlink.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants-symlink.test.d.ts","sourceRoot":"","sources":["../../src/lib/constants-symlink.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/lib/constants-symlink.test.js

@@ -0,0 +1,357 @@
+/**
+ * Symlink protection TOCTOU tests (A2 Category 3)
+ *
+ * Tests the atomic path checking and symlink protection in getTelemetryDirectories.
+ * Verifies protection against:
+ * - Symlink swap attacks (TOCTOU)
+ * - Broken symlinks
+ * - Circular symlink chains
+ * - Symlinks escaping allowed directories
+ */
+import { describe, it, before, after, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { mkdirSync, rmdirSync, symlinkSync, unlinkSync, existsSync, realpathSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { tmpdir } from 'os';
+import { getTelemetryDirectories } from './constants.js';
+import { createSymlinkTestDir, createCircularSymlinks, createBrokenSymlink, createSymlinkChain, } from '../test-helpers/race-condition-helpers.js';
+describe('symlink protection TOCTOU tests', () => {
+    let testBaseDir;
+    const cleanupFns = [];
+    before(() => {
+        testBaseDir = join(tmpdir(), `symlink-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        mkdirSync(testBaseDir, { recursive: true });
+    });
+    after(() => {
+        // Clean up any remaining resources
+        for (const cleanup of cleanupFns) {
+            try {
+                cleanup();
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+        }
+        // Remove test directory
+        try {
+            rmdirSync(testBaseDir, { recursive: true });
+        }
+        catch {
+            // Ignore
+        }
+    });
+    afterEach(() => {
+        // Run and clear cleanup functions after each test
+        while (cleanupFns.length > 0) {
+            const cleanup = cleanupFns.pop();
+            try {
+                cleanup?.();
+            }
+            catch {
+                // Ignore
+            }
+        }
+    });
+    describe('basic symlink handling', () => {
+        it('should follow valid symlinks to directories', () => {
+            const { symlinkPath, targetPath, cleanup } = createSymlinkTestDir(testBaseDir, 'valid');
+            cleanupFns.push(cleanup);
+            // Create a .claude/telemetry structure
+            const telemetryTarget = join(testBaseDir, 'telemetry-target');
+            mkdirSync(telemetryTarget, { recursive: true });
+            cleanupFns.push(() => rmdirSync(telemetryTarget));
+            // Verify the symlink exists and points to a directory
+            assert.ok(existsSync(symlinkPath), 'Symlink should exist');
+            const realPath = realpathSync(symlinkPath);
+            // On macOS, /tmp is a symlink to /private/tmp, so we compare resolved paths
+            const resolvedTarget = realpathSync(targetPath);
+            assert.strictEqual(realPath, resolvedTarget, 'Should resolve to target');
+        });
+        it('should handle non-symlink directories', () => {
+            const dirPath = join(testBaseDir, 'regular-dir');
+            mkdirSync(dirPath, { recursive: true });
+            cleanupFns.push(() => rmdirSync(dirPath));
+            assert.ok(existsSync(dirPath), 'Directory should exist');
+            const realPath = realpathSync(dirPath);
+            // Compare with resolved path (handles /tmp -> /private/tmp on macOS)
+            const resolvedDir = realpathSync(resolve(dirPath));
+            assert.strictEqual(realPath, resolvedDir, 'Should resolve to itself');
+        });
+    });
+    describe('broken symlink handling', () => {
+        it('should handle symlink with non-existent target', () => {
+            const { symlinkPath, cleanup } = createBrokenSymlink(testBaseDir, 'broken');
+            cleanupFns.push(cleanup);
+            // realpathSync should throw for broken symlinks
+            assert.throws(() => realpathSync(symlinkPath), /ENOENT/, 'Should throw ENOENT for broken symlink');
+        });
+        it('should gracefully handle broken symlink in telemetry path check', () => {
+            // Create a working directory with a broken .claude/telemetry symlink
+            const workDir = join(testBaseDir, 'work-broken');
+            const claudeDir = join(workDir, '.claude');
+            mkdirSync(claudeDir, { recursive: true });
+            cleanupFns.push(() => rmdirSync(claudeDir, { recursive: true }));
+            const telemetryLink = join(claudeDir, 'telemetry');
+            const nonExistent = join(testBaseDir, 'does-not-exist-' + Date.now());
+            symlinkSync(nonExistent, telemetryLink);
+            cleanupFns.push(() => {
+                try {
+                    unlinkSync(telemetryLink);
+                }
+                catch {
+                    // Ignore
+                }
+            });
+            // getTelemetryDirectories should not include broken symlinks
+            const dirs = getTelemetryDirectories(workDir);
+            const hasLocal = dirs.some(d => d.source === 'local' && d.path.includes(workDir));
+            assert.ok(!hasLocal, 'Should not include broken symlinks');
+        });
+    });
+    describe('circular symlink detection', () => {
+        it('should handle circular symlink chains (ELOOP)', () => {
+            const { paths, cleanup } = createCircularSymlinks(testBaseDir, 'circ');
+            cleanupFns.push(cleanup);
+            // realpathSync should throw ELOOP for circular symlinks
+            for (const p of paths) {
+                assert.throws(() => realpathSync(p), /ELOOP/, `Should throw ELOOP for circular path: ${p}`);
+            }
+        });
+    });
+    describe('symlink chain resolution', () => {
+        it('should follow symlink chains to final target', () => {
+            const { startPath, endPath, cleanup } = createSymlinkChain(testBaseDir, 'chain', 3);
+            cleanupFns.push(cleanup);
+            const resolved = realpathSync(startPath);
+            // Compare with resolved endPath (handles /tmp -> /private/tmp on macOS)
+            const resolvedEnd = realpathSync(endPath);
+            assert.strictEqual(resolved, resolvedEnd, 'Should resolve through chain to final target');
+        });
+        it('should handle deep symlink chains', () => {
+            const { startPath, endPath, cleanup } = createSymlinkChain(testBaseDir, 'deep', 10);
+            cleanupFns.push(cleanup);
+            const resolved = realpathSync(startPath);
+            // Compare with resolved endPath
+            const resolvedEnd = realpathSync(endPath);
+            assert.strictEqual(resolved, resolvedEnd, 'Should resolve deep chains');
+        });
+    });
+    describe('symlink escape prevention', () => {
+        it('should reject symlinks pointing outside allowed directories', () => {
+            const workDir = join(testBaseDir, 'work-escape');
+            const claudeDir = join(workDir, '.claude');
+            mkdirSync(claudeDir, { recursive: true });
+            cleanupFns.push(() => rmdirSync(claudeDir, { recursive: true }));
+            // Create telemetry symlink pointing to /tmp (outside workDir and ~/.claude)
+            const telemetryLink = join(claudeDir, 'telemetry');
+            const escapePath = '/tmp';
+            try {
+                symlinkSync(escapePath, telemetryLink);
+                cleanupFns.push(() => {
+                    try {
+                        unlinkSync(telemetryLink);
+                    }
+                    catch {
+                        // Ignore
+                    }
+                });
+            }
+            catch {
+                // Skip test if we can't create symlink
+                return;
+            }
+            // Capture console.warn to verify security warning
+            const originalWarn = console.warn;
+            let warnCalled = false;
+            let warnMessage = '';
+            console.warn = (msg) => {
+                warnCalled = true;
+                warnMessage = msg;
+            };
+            try {
+                const dirs = getTelemetryDirectories(workDir);
+                // Should not include the escape symlink
+                const hasEscape = dirs.some(d => d.path === '/tmp' || d.path.startsWith('/tmp/'));
+                assert.ok(!hasEscape, 'Should not include symlink escaping to /tmp');
+                // Should have logged security warning
+                assert.ok(warnCalled, 'Should log security warning');
+                assert.ok(warnMessage.includes('[SECURITY]'), 'Warning should be marked as security');
+            }
+            finally {
+                console.warn = originalWarn;
+            }
+        });
+        it('should allow symlinks within the working directory', () => {
+            const workDir = join(testBaseDir, 'work-internal');
+            const claudeDir = join(workDir, '.claude');
+            const targetDir = join(workDir, 'actual-telemetry');
+            mkdirSync(claudeDir, { recursive: true });
+            mkdirSync(targetDir, { recursive: true });
+            cleanupFns.push(() => {
+                rmdirSync(claudeDir, { recursive: true });
+                rmdirSync(targetDir);
+            });
+            const telemetryLink = join(claudeDir, 'telemetry');
+            symlinkSync(targetDir, telemetryLink);
+            cleanupFns.push(() => {
+                try {
+                    unlinkSync(telemetryLink);
+                }
+                catch {
+                    // Ignore
+                }
+            });
+            const dirs = getTelemetryDirectories(workDir);
+            const hasLocal = dirs.some(d => d.source === 'local');
+            assert.ok(hasLocal, 'Should include symlinks within working directory');
+        });
+    });
+    describe('TOCTOU race condition resistance', () => {
+        it('should use atomic path checking to prevent symlink swap', () => {
+            // This test verifies the atomicPathCheck function behavior
+            const target1 = join(testBaseDir, 'swap-target-1');
+            const target2 = join(testBaseDir, 'swap-target-2');
+            const workDir = join(testBaseDir, 'work-swap');
+            const claudeDir = join(workDir, '.claude');
+            const telemetryLink = join(claudeDir, 'telemetry');
+            mkdirSync(target1, { recursive: true });
+            mkdirSync(target2, { recursive: true });
+            mkdirSync(claudeDir, { recursive: true });
+            cleanupFns.push(() => {
+                rmdirSync(target1);
+                rmdirSync(target2);
+                rmdirSync(claudeDir, { recursive: true });
+            });
+            // Create initial symlink
+            symlinkSync(target1, telemetryLink);
+            cleanupFns.push(() => {
+                try {
+                    unlinkSync(telemetryLink);
+                }
+                catch {
+                    // Ignore
+                }
+            });
+            // First call should see target1
+            const dirs1 = getTelemetryDirectories(workDir);
+            const localDir1 = dirs1.find(d => d.source === 'local');
+            // Now swap the symlink
+            unlinkSync(telemetryLink);
+            symlinkSync(target2, telemetryLink);
+            // Second call should see target2
+            const dirs2 = getTelemetryDirectories(workDir);
+            const localDir2 = dirs2.find(d => d.source === 'local');
+            // Verify the resolved paths are different
+            if (localDir1 && localDir2) {
+                assert.notStrictEqual(localDir1.path, localDir2.path, 'Should detect changed symlink target');
+            }
+        });
+        it('should handle rapid symlink creation and deletion', async () => {
+            const workDir = join(testBaseDir, 'work-rapid');
+            const claudeDir = join(workDir, '.claude');
+            const targetDir = join(workDir, 'rapid-target');
+            const telemetryLink = join(claudeDir, 'telemetry');
+            mkdirSync(claudeDir, { recursive: true });
+            mkdirSync(targetDir, { recursive: true });
+            cleanupFns.push(() => {
+                rmdirSync(claudeDir, { recursive: true });
+                rmdirSync(targetDir);
+            });
+            // Rapidly create and delete symlink while querying
+            let successCount = 0;
+            let emptyCount = 0;
+            for (let i = 0; i < 10; i++) {
+                // Create symlink
+                try {
+                    symlinkSync(targetDir, telemetryLink);
+                }
+                catch {
+                    // May already exist
+                }
+                const dirs = getTelemetryDirectories(workDir);
+                if (dirs.some(d => d.source === 'local')) {
+                    successCount++;
+                }
+                else {
+                    emptyCount++;
+                }
+                // Delete symlink
+                try {
+                    unlinkSync(telemetryLink);
+                }
+                catch {
+                    // May already be deleted
+                }
+            }
+            // Test should complete without crashes
+            assert.ok(successCount + emptyCount === 10, 'Should handle all iterations without crashing');
+        });
+    });
+    describe('file descriptor verification', () => {
+        it('should reject file paths (non-directories)', () => {
+            const workDir = join(testBaseDir, 'work-file');
+            const claudeDir = join(workDir, '.claude');
+            mkdirSync(claudeDir, { recursive: true });
+            cleanupFns.push(() => {
+                try {
+                    rmdirSync(claudeDir, { recursive: true });
+                }
+                catch {
+                    // Ignore
+                }
+            });
+            // Create a file instead of directory at telemetry path
+            const telemetryPath = join(claudeDir, 'telemetry');
+            writeFileSync(telemetryPath, 'not a directory');
+            cleanupFns.push(() => {
+                try {
+                    unlinkSync(telemetryPath);
+                }
+                catch {
+                    // Ignore
+                }
+            });
+            const dirs = getTelemetryDirectories(workDir);
+            const hasLocal = dirs.some(d => d.source === 'local' && d.path.includes('telemetry'));
+            assert.ok(!hasLocal, 'Should not include files (only directories)');
+        });
+    });
+    describe('symlink target validation', () => {
+        it('should validate symlink points to directory not file', () => {
+            const workDir = join(testBaseDir, 'work-file-target');
+            const claudeDir = join(workDir, '.claude');
+            const filePath = join(testBaseDir, 'target-file.txt');
+            mkdirSync(claudeDir, { recursive: true });
+            writeFileSync(filePath, 'content');
+            cleanupFns.push(() => {
+                try {
+                    rmdirSync(claudeDir, { recursive: true });
+                }
+                catch {
+                    // Ignore
+                }
+                try {
+                    unlinkSync(filePath);
+                }
+                catch {
+                    // Ignore
+                }
+            });
+            // Create symlink to file
+            const telemetryLink = join(claudeDir, 'telemetry');
+            symlinkSync(filePath, telemetryLink);
+            cleanupFns.push(() => {
+                try {
+                    unlinkSync(telemetryLink);
+                }
+                catch {
+                    // Ignore
+                }
+            });
+            const dirs = getTelemetryDirectories(workDir);
+            const hasLocal = dirs.some(d => d.source === 'local');
+            assert.ok(!hasLocal, 'Should not include symlinks to files');
+        });
+    });
+});
+//# sourceMappingURL=constants-symlink.test.js.map