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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kumak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,11 @@
-# browser-debugger-cli
+# Browser Debugger CLI
 
-CLI tool for collecting browser telemetry (DOM, network, console) via Chrome DevTools Protocol.
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/szymdzum/browser-debugger-cli/pulls)
+[![CI](https://github.com/szymdzum/browser-debugger-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/szymdzum/browser-debugger-cli/actions/workflows/ci.yml)
+[![Security](https://github.com/szymdzum/browser-debugger-cli/actions/workflows/security.yml/badge.svg)](https://github.com/szymdzum/browser-debugger-cli/actions/workflows/security.yml)
+[![npm downloads](https://img.shields.io/npm/dt/browser-debugger-cli?color=blue)](https://www.npmjs.com/package/browser-debugger-cli)
+
+DevTools telemetry in your terminal. For humans and agents. Direct WebSocket to Chrome's debugging port. Stream DOM, network, and console data straight to stdout. Pipe it, grep it, feed it to agents for full context debugging.
 
 ## Installation
 
@@ -11,75 +16,185 @@ npm install -g browser-debugger-cli
 ## Quick Start
 
 ```bash
-# Just run bdg - it will auto-launch Chrome if needed
-bdg localhost:3000
-
-# Interact with the page, then press Ctrl+C
+# Start session (opens example.com in Chrome)
+bdg example.com
+
+# Daemon starts in background, Chrome opens
+# Session is active - you can now run commands
+
+# Check session status
+bdg status
+# Status: Active
+# Worker PID: 12345
+# Chrome PID: 67890
+# Target: http://example.com
+
+# Preview collected data
+bdg peek --last 5
+# NETWORK [0] GET http://example.com/ (200)
+# NETWORK [1] GET http://example.com/style.css (200)
+# ...
+
+# Execute raw CDP commands
+bdg cdp Runtime.evaluate --params '{"expression":"document.title","returnByValue":true}'
+# { "result": { "type": "string", "value": "Example Domain" } }
+
+# Stop session
+bdg stop
 ```
 
-JSON output with collected network requests, console logs, and DOM will be written to stdout.
+## Philosophy
+
+There's no good CLI for Chrome DevTools Protocol. MCP servers work (most of the time) but are token-heavy and monolithic. Puppeteer is for automation, not inspection. Lighthouse is single-purpose.
+
+`bdg` takes the Unix approach: small, composable commands that pipe with `jq` and `grep` tools models already know—without the token overhead.
+
+**Why CLI over protocol servers?**
+- **Token efficiency**: CDP is in the model's training data. A skill doc with usage
+  patterns? ~3k tokens. MCP server definitions? 5-10k before you invoke anything.
+- **Composability**: Pipe commands together. Each does one thing well.
+- **Transparent errors**: See exactly what failed. No protocol layers hiding the
+  issue.
+- **Real-time evolution**: Update usage patterns anytime. No server redeployment
+  needed.
+
+The vision: Terminal-native browser debugging that's as composable as `curl` and `jq`.
 
-### How It Works
+## Available Commands
 
-`bdg` automatically launches Chrome with debugging enabled if it's not already running. You can also manually start Chrome first if you prefer:
+### Raw CDP Access
+
+Full Chrome DevTools Protocol access via `bdg cdp` command – **any CDP method works**:
 
 ```bash
-# macOS
-/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
-  --remote-debugging-port=9222 \
-  --user-data-dir=/tmp/chrome-bdg
-
-# Linux
-google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-bdg
-
-# Windows
-"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
-  --remote-debugging-port=9222 ^
-  --user-data-dir=C:\temp\chrome-bdg
+# Get all cookies (raw CDP)
+bdg cdp Network.getCookies
+# {
+#   "cookies": [
+#     {
+#       "name": "session_id",
+#       "value": "1234567890abcdef",
+#       "domain": "example.com",
+#       "httpOnly": true,
+#       "secure": true,
+#       "sameSite": "Strict"
+#     }
+#   ]
+# }
+
+# Evaluate JavaScript
+bdg cdp Runtime.evaluate --params '{"expression":"document.title","returnByValue":true}'
+# {
+#   "result": {
+#     "type": "string",
+#     "value": "Example Domain"
+#   }
+# }
+
+# Get browser version
+bdg cdp Browser.getVersion
+# {
+#   "protocolVersion": "1.3",
+#   "product": "Chrome/142.0.7444.60",
+#   "jsVersion": "14.2.231.14"
+# }
+
+# Pipe to jq for filtering
+bdg cdp Network.getCookies | jq '.cookies[] | select(.name == "session_id") | .value'
+# "1234567890abcdef"
 ```
 
-If Chrome is already running with debugging enabled, `bdg` will detect and use the existing instance.
+**60+ domains, 300+ methods** from the [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) are available.
 
-## Usage
+### Session Management
 
 ```bash
-# Collect all telemetry (default)
-bdg localhost:3000
+# Check if session is active
+bdg status
+# Status: Active
+# Worker PID: 12345
+# Chrome PID: 67890
+# Target: http://example.com
+
+# Stop session
+bdg stop
+
+# Clean up stale sessions
+bdg cleanup
+bdg cleanup --force  # Force cleanup even if session appears active
+```
 
-# Collect specific data
-bdg dom localhost:3000
-bdg network localhost:3000
-bdg console localhost:3000
+### Live Data Inspection
 
-# Options
-bdg localhost:3000 --port 9223
-bdg localhost:3000 --timeout 30
+```bash
+# Preview collected data without stopping
+bdg peek
+bdg peek --last 10          # Show last 10 items
+bdg peek --network          # Only network requests
+bdg peek --console          # Only console logs
+bdg peek --follow           # Live updates every second
+bdg peek --json             # JSON output
+
+# Get detailed information
+bdg details network <requestId>    # Full request/response with bodies
+bdg details console <index>        # Full console message with args
 ```
 
-## Output
-
-```json
-{
-  "success": true,
-  "duration": 45230,
-  "target": { "url": "...", "title": "..." },
-  "data": {
-    "network": [...],
-    "console": [...],
-    "dom": {...}
-  }
-}
+### DOM Inspection
+
+```bash
+# Query DOM elements
+bdg dom query "document.title"
+bdg dom query ".error-message"
+
+# Get element by selector or index
+bdg dom get ".main-content"
+bdg dom get 0  # Get first element from cache
+
+# Evaluate JavaScript
+bdg dom eval "window.location.href"
+```
+
+### Network & Console Commands
+
+```bash
+# Inspect network state
+bdg network
+
+# Query console logs
+bdg console
+bdg console --json
 ```
 
-## Documentation
+## Technical Overview
+
+`bdg` runs a daemon that maintains a WebSocket connection to Chrome's debugging port.
+When you run commands like `bdg network` or `bdg console`, they communicate with the
+daemon via IPC, which forwards [Chrome DevTools
+Protocol](https://chromedevtools.github.io/devtools-protocol/) commands and streams
+responses back.
+
+**Architecture:**
+- **Daemon** – Background process managing Chrome connection lifecycle
+- **IPC** – Unix sockets for CLI ↔ daemon communication
+- **WebSocket** – Direct connection to Chrome's `--remote-debugging-port`
+- **CDP** – Native Chrome DevTools Protocol for all browser inspection
+
+**Benefits:**
+- Sessions persist across commands (Chrome stays open)
+- Live queries without stopping collection
+- No intermediate files data flows from Chrome to stdout
+- Real CDP with full protocol access
 
-See [CHROME_SETUP.md](./CHROME_SETUP.md) for Chrome configuration details.
+## Contributing
 
-## Requirements
+Contributions welcome! But honestly, I'd just be happy if you give it a try.
 
-- Node.js >= 18.0.0
-- Chrome/Chromium with remote debugging
+Let me know how you use it
+([discussions](https://github.com/szymdzum/browser-debugger-cli/discussions)), let me
+know what's broken
+([issues](https://github.com/szymdzum/browser-debugger-cli/issues/new)).
 
 ## License
 
-MIT
+MIT – see [LICENSE](LICENSE) for details.

package/dist/__testfixtures__/cdpMessages.d.ts

@@ -0,0 +1,43 @@
+/**
+ * cdpMessages - Sample CDP protocol messages for tests
+ *
+ * Provides realistic CDP message fixtures to keep tests concise and readable.
+ */
+import type { CDPMessage } from '@/types.js';
+/**
+ * Sample CDP request message
+ */
+export declare const CDP_REQUEST: CDPMessage;
+/**
+ * Sample CDP response message (success)
+ */
+export declare const CDP_RESPONSE_SUCCESS: CDPMessage;
+/**
+ * Sample CDP error response
+ */
+export declare const CDP_RESPONSE_ERROR: CDPMessage;
+/**
+ * Sample CDP event notification (no id)
+ */
+export declare const CDP_EVENT_NOTIFICATION: CDPMessage;
+/**
+ * Sample CDP event with session ID
+ */
+export declare const CDP_EVENT_WITH_SESSION: CDPMessage;
+/**
+ * Factory: Create a request message with custom ID
+ */
+export declare function createRequest(id: number, method: string, params?: unknown): CDPMessage;
+/**
+ * Factory: Create a success response
+ */
+export declare function createResponse(id: number, result: unknown): CDPMessage;
+/**
+ * Factory: Create an error response
+ */
+export declare function createErrorResponse(id: number, message: string, code?: number): CDPMessage;
+/**
+ * Factory: Create an event notification
+ */
+export declare function createEvent(method: string, params: unknown, sessionId?: string): CDPMessage;
+//# sourceMappingURL=cdpMessages.d.ts.map

package/dist/__testfixtures__/cdpMessages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdpMessages.d.ts","sourceRoot":"","sources":["../../src/__testfixtures__/cdpMessages.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,UAIzB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,UAclC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,UAMhC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,UAYpC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,UAYpC,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,UAAU,CAMtF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,UAAU,CAKtE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,SAAS,GAAG,UAAU,CAQ1F;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,CAS3F"}

package/dist/__testfixtures__/cdpMessages.js

@@ -0,0 +1,118 @@
+/**
+ * cdpMessages - Sample CDP protocol messages for tests
+ *
+ * Provides realistic CDP message fixtures to keep tests concise and readable.
+ */
+/**
+ * Sample CDP request message
+ */
+export const CDP_REQUEST = {
+    id: 1,
+    method: 'Target.getTargets',
+    params: {},
+};
+/**
+ * Sample CDP response message (success)
+ */
+export const CDP_RESPONSE_SUCCESS = {
+    id: 1,
+    result: {
+        targetInfos: [
+            {
+                targetId: 't1',
+                type: 'page',
+                title: 'Test Page',
+                url: 'http://localhost:3000',
+                attached: false,
+                canAccessOpener: false,
+            },
+        ],
+    },
+};
+/**
+ * Sample CDP error response
+ */
+export const CDP_RESPONSE_ERROR = {
+    id: 1,
+    error: {
+        code: -32601,
+        message: 'Method not found',
+    },
+};
+/**
+ * Sample CDP event notification (no id)
+ */
+export const CDP_EVENT_NOTIFICATION = {
+    method: 'Target.targetCreated',
+    params: {
+        targetInfo: {
+            targetId: 't2',
+            type: 'page',
+            title: 'New Page',
+            url: 'http://localhost:4000',
+            attached: false,
+            canAccessOpener: false,
+        },
+    },
+};
+/**
+ * Sample CDP event with session ID
+ */
+export const CDP_EVENT_WITH_SESSION = {
+    method: 'Page.frameNavigated',
+    params: {
+        frame: {
+            id: 'frame-1',
+            loaderId: 'loader-1',
+            url: 'http://localhost:3000/page',
+            securityOrigin: 'http://localhost:3000',
+            mimeType: 'text/html',
+        },
+    },
+    sessionId: 'session-abc123',
+};
+/**
+ * Factory: Create a request message with custom ID
+ */
+export function createRequest(id, method, params) {
+    return {
+        id,
+        method,
+        params: params ?? {},
+    };
+}
+/**
+ * Factory: Create a success response
+ */
+export function createResponse(id, result) {
+    return {
+        id,
+        result,
+    };
+}
+/**
+ * Factory: Create an error response
+ */
+export function createErrorResponse(id, message, code = -32603) {
+    return {
+        id,
+        error: {
+            code,
+            message,
+        },
+    };
+}
+/**
+ * Factory: Create an event notification
+ */
+export function createEvent(method, params, sessionId) {
+    const event = {
+        method,
+        params: params ?? {},
+    };
+    if (sessionId) {
+        event.sessionId = sessionId;
+    }
+    return event;
+}
+//# sourceMappingURL=cdpMessages.js.map

package/dist/__testfixtures__/cdpMessages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdpMessages.js","sourceRoot":"","sources":["../../src/__testfixtures__/cdpMessages.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAe;IACrC,EAAE,EAAE,CAAC;IACL,MAAM,EAAE,mBAAmB;IAC3B,MAAM,EAAE,EAAE;CACX,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAe;IAC9C,EAAE,EAAE,CAAC;IACL,MAAM,EAAE;QACN,WAAW,EAAE;YACX;gBACE,QAAQ,EAAE,IAAI;gBACd,IAAI,EAAE,MAAM;gBACZ,KAAK,EAAE,WAAW;gBAClB,GAAG,EAAE,uBAAuB;gBAC5B,QAAQ,EAAE,KAAK;gBACf,eAAe,EAAE,KAAK;aACvB;SACF;KACF;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAe;IAC5C,EAAE,EAAE,CAAC;IACL,KAAK,EAAE;QACL,IAAI,EAAE,CAAC,KAAK;QACZ,OAAO,EAAE,kBAAkB;KAC5B;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAe;IAChD,MAAM,EAAE,sBAAsB;IAC9B,MAAM,EAAE;QACN,UAAU,EAAE;YACV,QAAQ,EAAE,IAAI;YACd,IAAI,EAAE,MAAM;YACZ,KAAK,EAAE,UAAU;YACjB,GAAG,EAAE,uBAAuB;YAC5B,QAAQ,EAAE,KAAK;YACf,eAAe,EAAE,KAAK;SACvB;KACF;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAe;IAChD,MAAM,EAAE,qBAAqB;IAC7B,MAAM,EAAE;QACN,KAAK,EAAE;YACL,EAAE,EAAE,SAAS;YACb,QAAQ,EAAE,UAAU;YACpB,GAAG,EAAE,4BAA4B;YACjC,cAAc,EAAE,uBAAuB;YACvC,QAAQ,EAAE,WAAW;SACtB;KACF;IACD,SAAS,EAAE,gBAAgB;CAC5B,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,EAAU,EAAE,MAAc,EAAE,MAAgB;IACxE,OAAO;QACL,EAAE;QACF,MAAM;QACN,MAAM,EAAG,MAAkC,IAAI,EAAE;KAClD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,EAAU,EAAE,MAAe;IACxD,OAAO;QACL,EAAE;QACF,MAAM;KACP,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAU,EAAE,OAAe,EAAE,IAAI,GAAG,CAAC,KAAK;IAC5E,OAAO;QACL,EAAE;QACF,KAAK,EAAE;YACL,IAAI;YACJ,OAAO;SACR;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,MAAe,EAAE,SAAkB;IAC7E,MAAM,KAAK,GAAe;QACxB,MAAM;QACN,MAAM,EAAG,MAAkC,IAAI,EAAE;KAClD,CAAC;IACF,IAAI,SAAS,EAAE,CAAC;QACd,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;IAC9B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/__testfixtures__/connectionTargets.d.ts

@@ -0,0 +1,21 @@
+import type { CDPTarget } from '../types.js';
+/**
+ * Create a mock CDPTarget with default values and optional overrides.
+ *
+ * Provides consistent test data across connection module tests while allowing
+ * customization for specific test scenarios.
+ *
+ * @param overrides - Partial CDPTarget properties to override defaults
+ * @returns Complete CDPTarget object for testing
+ */
+export declare const createMockTarget: (overrides?: Partial<CDPTarget>) => CDPTarget;
+/**
+ * Standard list of mock targets for testing target discovery and matching.
+ *
+ * Includes common test scenarios:
+ * - Different URLs on same host (localhost:3000, localhost:3000/about)
+ * - Different hosts (example.com)
+ * - Different target types (page, background_page, service_worker)
+ */
+export declare const mockTargetList: CDPTarget[];
+//# sourceMappingURL=connectionTargets.d.ts.map

package/dist/__testfixtures__/connectionTargets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectionTargets.d.ts","sourceRoot":"","sources":["../../src/__testfixtures__/connectionTargets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,YAAW,OAAO,CAAC,SAAS,CAAM,KAAG,SAOpE,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,EAgCrC,CAAC"}

package/dist/__testfixtures__/connectionTargets.js

@@ -0,0 +1,59 @@
+/**
+ * Create a mock CDPTarget with default values and optional overrides.
+ *
+ * Provides consistent test data across connection module tests while allowing
+ * customization for specific test scenarios.
+ *
+ * @param overrides - Partial CDPTarget properties to override defaults
+ * @returns Complete CDPTarget object for testing
+ */
+export const createMockTarget = (overrides = {}) => ({
+    id: 'target-123',
+    type: 'page',
+    url: 'http://localhost:3000',
+    title: 'Test Page',
+    webSocketDebuggerUrl: 'ws://127.0.0.1:9222/devtools/page/target-123',
+    ...overrides,
+});
+/**
+ * Standard list of mock targets for testing target discovery and matching.
+ *
+ * Includes common test scenarios:
+ * - Different URLs on same host (localhost:3000, localhost:3000/about)
+ * - Different hosts (example.com)
+ * - Different target types (page, background_page, service_worker)
+ */
+export const mockTargetList = [
+    createMockTarget({
+        id: 'target-1',
+        url: 'http://localhost:3000',
+        title: 'Home Page',
+    }),
+    createMockTarget({
+        id: 'target-2',
+        url: 'http://localhost:3000/about',
+        title: 'About Page',
+        webSocketDebuggerUrl: 'ws://127.0.0.1:9222/devtools/page/target-2',
+    }),
+    createMockTarget({
+        id: 'target-3',
+        url: 'http://example.com',
+        title: 'Example Site',
+        webSocketDebuggerUrl: 'ws://127.0.0.1:9222/devtools/page/target-3',
+    }),
+    createMockTarget({
+        id: 'target-4',
+        type: 'background_page',
+        url: 'chrome-extension://abcdef/background.html',
+        title: 'Extension Background',
+        webSocketDebuggerUrl: 'ws://127.0.0.1:9222/devtools/page/target-4',
+    }),
+    createMockTarget({
+        id: 'target-5',
+        type: 'service_worker',
+        url: 'https://app.example.com/sw.js',
+        title: 'Service Worker',
+        webSocketDebuggerUrl: 'ws://127.0.0.1:9222/devtools/page/target-5',
+    }),
+];
+//# sourceMappingURL=connectionTargets.js.map

package/dist/__testfixtures__/connectionTargets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectionTargets.js","sourceRoot":"","sources":["../../src/__testfixtures__/connectionTargets.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,YAAgC,EAAE,EAAa,EAAE,CAAC,CAAC;IAClF,EAAE,EAAE,YAAY;IAChB,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,uBAAuB;IAC5B,KAAK,EAAE,WAAW;IAClB,oBAAoB,EAAE,8CAA8C;IACpE,GAAG,SAAS;CACb,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAgB;IACzC,gBAAgB,CAAC;QACf,EAAE,EAAE,UAAU;QACd,GAAG,EAAE,uBAAuB;QAC5B,KAAK,EAAE,WAAW;KACnB,CAAC;IACF,gBAAgB,CAAC;QACf,EAAE,EAAE,UAAU;QACd,GAAG,EAAE,6BAA6B;QAClC,KAAK,EAAE,YAAY;QACnB,oBAAoB,EAAE,4CAA4C;KACnE,CAAC;IACF,gBAAgB,CAAC;QACf,EAAE,EAAE,UAAU;QACd,GAAG,EAAE,oBAAoB;QACzB,KAAK,EAAE,cAAc;QACrB,oBAAoB,EAAE,4CAA4C;KACnE,CAAC;IACF,gBAAgB,CAAC;QACf,EAAE,EAAE,UAAU;QACd,IAAI,EAAE,iBAAiB;QACvB,GAAG,EAAE,2CAA2C;QAChD,KAAK,EAAE,sBAAsB;QAC7B,oBAAoB,EAAE,4CAA4C;KACnE,CAAC;IACF,gBAAgB,CAAC;QACf,EAAE,EAAE,UAAU;QACd,IAAI,EAAE,gBAAgB;QACtB,GAAG,EAAE,+BAA+B;QACpC,KAAK,EAAE,gBAAgB;QACvB,oBAAoB,EAAE,4CAA4C;KACnE,CAAC;CACH,CAAC"}

package/dist/__tests__/integration/session-files.integration.test.d.ts

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

package/dist/__tests__/integration/session-files.integration.test.d.ts.map

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

package/dist/__tests__/integration/session-files.integration.test.js

@@ -0,0 +1,66 @@
+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 { describe, it, beforeEach, afterEach } from 'node:test';
+/**
+ * Integration tests for session file operations using real filesystem
+ *
+ * These tests verify that atomic write patterns work correctly with actual
+ * file I/O, catching issues that in-memory fakes can't detect (permissions,
+ * platform quirks, race conditions).
+ */
+void describe('Session Files Integration Tests', () => {
+    let tmpDir;
+    beforeEach(() => {
+        // Create temporary directory for each test
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bdg-test-'));
+    });
+    afterEach(() => {
+        // ⚠️ CRITICAL: Clean up temp directory, even if test fails
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    void describe('Atomic Writes', () => {
+        void it('should prevent partial reads during writes (tmp file + rename pattern)', () => {
+            const filePath = path.join(tmpDir, 'test.txt');
+            const tmpPath = filePath + '.tmp';
+            const testData = 'complete data';
+            // Write to temp file first
+            fs.writeFileSync(tmpPath, testData, 'utf-8');
+            // At this point, final file doesn't exist yet
+            assert.equal(fs.existsSync(filePath), false, 'Final file should not exist before rename');
+            // Rename tmp to final (atomic operation on most filesystems)
+            fs.renameSync(tmpPath, filePath);
+            // Now read the final file
+            const readData = fs.readFileSync(filePath, 'utf-8');
+            assert.equal(readData, testData, 'Should read complete data');
+            // Tmp file should be gone
+            assert.equal(fs.existsSync(tmpPath), false, 'Temp file should be removed after rename');
+        });
+        void it('should handle exclusive file creation (wx flag)', () => {
+            const lockPath = path.join(tmpDir, 'session.lock');
+            // First write with wx should succeed
+            fs.writeFileSync(lockPath, '12345', { flag: 'wx' });
+            assert.equal(fs.existsSync(lockPath), true, 'Lock file should be created');
+            // Second write with wx should fail with EEXIST
+            assert.throws(() => fs.writeFileSync(lockPath, '67890', { flag: 'wx' }), (err) => {
+                return err instanceof Error && 'code' in err && err.code === 'EEXIST';
+            }, 'Should throw EEXIST when file already exists with wx flag');
+            // Original content should be unchanged
+            const content = fs.readFileSync(lockPath, 'utf-8');
+            assert.equal(content, '12345', 'Original content should be preserved');
+        });
+        void it('should verify temp directory cleanup happens even on assertion failure', () => {
+            // This test verifies our afterEach cleanup works
+            const testFile = path.join(tmpDir, 'verify-cleanup.txt');
+            fs.writeFileSync(testFile, 'test data');
+            assert.equal(fs.existsSync(testFile), true, 'File should exist during test');
+            // Store tmpDir path to verify it's cleaned up after test
+            const dirToCheck = tmpDir;
+            // Note: afterEach will run even if this test fails, cleaning up tmpDir
+            // We can't directly verify cleanup here, but this documents the pattern
+            assert.ok(dirToCheck.includes('bdg-test-'), 'Temp dir should have bdg-test prefix');
+        });
+    });
+});
+//# sourceMappingURL=session-files.integration.test.js.map

package/dist/__tests__/integration/session-files.integration.test.js.map

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