browser-debugger-cli 0.3.0 → 0.6.0

package/README.md

@@ -5,7 +5,23 @@
 [![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.
+Chrome DevTools Protocol in your terminal. Self-documenting CDP access with discovery, search, and introspection. Perfect for AI agents and developers who want direct browser control without the framework overhead.
+
+## Why This Exists
+Puppeteer is great but heavy. CDP is powerful but raw. This tool sits in between: direct protocol access with session management and a few helpful wrappers. No abstractions hiding what's actually happening.
+Built for debugging web apps and scripting browser automation without spinning up a full testing framework.
+
+## Current State
+
+**Raw [CDP](https://chromedevtools.github.io/devtools-protocol/) access is complete.** All 300+ protocol methods work now. This makes it immediately useful for AI agents and developers comfortable with CDP.
+
+**Human-friendly wrappers are in progress.** Commands like `bdg dom query` and `bdg peek` are being added for common operations. For now, most automation work happens through `bdg cdp` and Unix pipes.
+
+## Demo
+
+[![asciicast](https://asciinema.org/a/RE6Iup9sB1iSWBK0wgUUn3bBl.svg)](https://asciinema.org/a/RE6Iup9sB1iSWBK0wgUUn3bBl)
+
+*Watch bdg scrape GitHub trending pages and extract repository data in real-time using DOM queries and CDP.*
 
 ## Installation
 
@@ -13,178 +29,219 @@ DevTools telemetry in your terminal. For humans and agents. Direct WebSocket to
 npm install -g browser-debugger-cli@alpha
 ```
 
+**Platform Support:**
+- ✅ macOS and Linux (native support)
+- ✅ Windows via WSL (Windows Subsystem for Linux)
+- ❌ PowerShell and Git Bash on Windows (not yet supported)
+
+The CLI uses Unix domain sockets for inter-process communication. Windows users should run bdg inside WSL for full compatibility.
+
 ## Quick Start
 
 ```bash
-# Start session (opens example.com in Chrome)
+# Start a session
 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
+# Discover what's available
+bdg cdp --list                    # List all 53 domains
+bdg cdp Network --list            # List Network methods
+bdg cdp --search cookie           # Search by keyword
 
-# Execute raw CDP commands
+# Run any CDP command
+bdg cdp Network.getCookies
 bdg cdp Runtime.evaluate --params '{"expression":"document.title","returnByValue":true}'
-# { "result": { "type": "string", "value": "Example Domain" } }
 
-bdg cdp Network.getCookies
-# { "cookies": [...] }
+# Check what's running
+bdg status
 
-# Stop session
+# Done
 bdg stop
 ```
 
-## How It Works
+## What You Can Do
 
-`bdg` is built on a **layered architecture** — raw CDP access with human-friendly wrappers on top.
+### Discover CDP Commands (53 Domains, 300+ Methods)
 
-### Layer 1: Raw CDP Access ✅
+Built-in introspection helps you find what you need without reading docs:
 
-Direct access to **60+ domains, 300+ methods** from [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/):
+```bash
+# What can I do with this browser?
+bdg cdp --list
+# Returns: 53 domains (Network, DOM, Page, Runtime, Storage, etc.)
+
+# What Network operations exist?
+bdg cdp Network --list
+# Returns: 39 methods with descriptions and parameter counts
+
+# How do I use this method?
+bdg cdp Network.getCookies --describe
+# Returns: Full schema with parameters, types, examples
+
+# Find cookie-related methods
+bdg cdp --search cookie
+# Returns: 14 methods across domains (Network.getCookies, Storage.getCookies, etc.)
+```
+
+All discovery commands output JSON for easy parsing. Perfect for AI agents building automation on the fly.
+
+### Run Any CDP Command
+
+All 300+ methods from [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) work out of the box:
 
 ```bash
-# Execute any CDP method
-bdg cdp Network.getCookies
-bdg cdp Runtime.evaluate --params '{"expression":"document.title","returnByValue":true}'
-bdg cdp Performance.getMetrics
+# Get cookies and filter with jq
+bdg cdp Network.getCookies | jq '.cookies[] | select(.httpOnly)'
+
+# Execute JavaScript in the page
+bdg cdp Runtime.evaluate --params '{"expression":"document.querySelectorAll(\"a\").length","returnByValue":true}'
+
+# Monitor memory usage
+bdg cdp Performance.getMetrics | jq '.metrics[] | select(.name == "JSHeapUsedSize")'
 
-# Pipe to jq for filtering
-bdg cdp Network.getCookies | jq '.cookies[] | select(.name == "session")'
+# Capture a screenshot
+bdg cdp Page.captureScreenshot | jq -r '.data' | base64 -d > screenshot.png
 ```
 
-**Why raw CDP first?**
-- ✅ Zero abstraction overhead — direct WebSocket to Chrome
-- ✅ Full protocol power — all CDP methods work immediately
-- ✅ Future-proof — new CDP features work without code changes
-- ✅ Agent-friendly — structured input/output, composable with Unix tools
+The daemon keeps a WebSocket open to Chrome, so commands run immediately against the live session.
 
-### Layer 2: Human-Friendly Wrappers 🚧
+### Pipe Everything
 
-Building ergonomic commands on top of raw CDP for common workflows:
+Output is JSON by default. Use it with `jq`, `grep`, `awk` - whatever works:
 
 ```bash
-# Session management
-bdg status          # Check active session
-bdg stop            # Stop session gracefully
-bdg cleanup         # Clean up stale sessions
-
-# Data inspection
-bdg peek            # Quick preview of collected data
-bdg peek --follow   # Live updates every second
-bdg details         # Full details for specific items
-bdg dom query       # Query DOM elements
-bdg dom eval        # Execute JavaScript in browser context
-bdg dom highlight   # Highlight elements visually
-bdg dom get         # Get full HTML for elements
+# Find all failed network requests
+bdg peek --network --json | jq '.data.network[] | select(.status >= 400)'
+
+# Extract every link on the page
+bdg cdp Runtime.evaluate --params '{
+  "expression": "Array.from(document.querySelectorAll(\"a\")).map(a => ({text: a.textContent.trim(), href: a.href}))",
+  "returnByValue": true
+}' | jq '.result.value'
+
+# Count console errors
+bdg peek --console --json | jq '[.data.console[] | select(.level == "error")] | length'
 ```
 
-**Progressive disclosure**: Start with raw CDP power, add convenience wrappers for common patterns.
+### For AI Agents
 
-**Why CLI over protocol servers?**
-- **Token efficiency**: CDP is in the model's training data (~3k tokens for patterns vs. 5-10k for MCP server definitions)
-- **Composability**: Unix pipes with `jq`, `grep`, `awk` — tools models already know
-- **Transparent errors**: See exactly what failed, no protocol layers hiding issues
-- **Real-time evolution**: Update patterns anytime, no server redeployment
+**Self-documenting CDP discovery** - agents can explore 300+ browser capabilities without external docs:
 
-## Available Commands
+```bash
+# Agent discovers what's possible
+bdg cdp --list                           # 53 domains available
+bdg cdp --search screenshot              # Find relevant methods
+bdg cdp Page.captureScreenshot --describe # Learn parameters
+bdg cdp Page.captureScreenshot --params '{"format":"png"}' # Execute
 
-### Raw CDP Access
+# All commands return structured JSON for easy parsing
+```
+
+**Why this matters for agents:**
+- No need to memorize CDP docs (1000+ pages)
+- Discover → Learn → Execute in one tool
+- Search by keyword (`--search`)
+- Case-insensitive execution (forgiving for LLM outputs)
+- Semantic exit codes for error handling
+
+Claude skill included at `.claude/skills/bdg/` with working automation patterns:
+
+- Common CDP workflows (scraping, polling, navigation)
+- Exit codes and error handling
+- Troubleshooting reference
 
-Full Chrome DevTools Protocol access via `bdg cdp` command – **any CDP method works**:
+The `--help --json` flag outputs the complete CLI schema for programmatic discovery:
 
 ```bash
-# 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"
+bdg --help --json | jq '.command.subcommands[].name'
+bdg --help --json | jq '.exitCodes'
 ```
 
-**60+ domains, 300+ methods** from the [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) are available.
+### Debug Live Apps
 
-### Session Management
+Point at localhost, monitor what's happening:
 
 ```bash
-# Start session
-bdg example.com             # Opens Chrome with daemon in background
+bdg localhost:3000 --headless
+bdg tail --console          # Stream console output
+bdg tail --network          # Watch requests in real-time
+```
 
-# Check if session is active
-bdg status                  # Show session info
-bdg status --verbose        # Include Chrome diagnostics
+Helpful for catching issues during development without opening DevTools.
 
-# Stop session
-bdg stop                    # Gracefully stop daemon and close Chrome
+### Automate Browser Tasks
 
-# Clean up stale sessions
-bdg cleanup                 # Remove stale session files
-bdg cleanup --force         # Force cleanup even if session appears active
+Poll for elements, click buttons, extract data:
+
+```bash
+# Wait for an element to appear
+while ! bdg cdp Runtime.evaluate --params '{"expression":"document.querySelector(\"#target\") !== null","returnByValue":true}' | jq -e '.result.value'; do
+  sleep 0.5
+done
+
+# Click it
+bdg cdp Runtime.evaluate --params '{"expression":"document.querySelector(\"#target\").click()"}'
+
+# Get the result
+bdg cdp Runtime.evaluate --params '{"expression":"document.querySelector(\".result\").textContent","returnByValue":true}'
 ```
 
-## Technical Overview
+Check `.claude/skills/bdg/WORKFLOWS.md` for more complete examples (GitHub scraper, form automation, etc).
 
-`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.
+## Session Management
 
-**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
+Sessions persist until you stop them. Chrome stays open, data keeps collecting:
 
-**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
+```bash
+bdg example.com          # Opens Chrome, starts daemon
+bdg status               # Check what's running
+bdg status --verbose     # Show Chrome process details
+bdg stop                 # Kill everything
+bdg cleanup              # Remove stale files
+```
 
-## Contributing
+## Helper Commands
 
-Contributions welcome! But honestly, I'd just be happy if you give it a try.
+A few convenience wrappers for common operations. Most work still happens through `bdg cdp`:
+
+```bash
+# Query DOM
+bdg dom query "button.primary"      # Find elements
+bdg dom get "button.primary"        # Get HTML
+bdg dom eval "document.title"       # Run JavaScript
+bdg dom highlight ".navbar"         # Visual debugging
+
+# Inspect collected data
+bdg peek                 # Quick snapshot
+bdg peek --network       # Just network data
+bdg tail                 # Stream like tail -f
+```
+
+## Page Readiness
+
+By default, `bdg` waits for pages to fully load using three signals:
+
+1. Browser's `window.onload` fires
+2. Network goes quiet (200ms without new requests)
+3. DOM stops changing (300ms without mutations)
+
+Catches server-rendered HTML, client hydration, and lazy-loaded content. Works with Next.js, React, Vue, whatever. Times out after 5 seconds if something hangs.
+
+Skip it with `--no-wait` if you want immediate connection.
+
+## Architecture
+
+Three processes:
+
+- **CLI** talks to daemon via Unix socket
+- **Daemon** manages Chrome and routes commands
+- **Worker** holds the WebSocket to CDP
+
+Chrome stays running between commands. No startup cost for each operation.
+
+## Contributing
 
-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)).
+If you use this and something breaks, [open an issue](https://github.com/szymdzum/browser-debugger-cli/issues/new). If you have ideas, start a [discussion](https://github.com/szymdzum/browser-debugger-cli/discussions). PRs welcome.
 
 ## License
 
-MIT – see [LICENSE](LICENSE) for details.
+MIT

package/dist/__tests__/smoke/error-handling.smoke.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Error handling smoke tests.
+ *
+ * Tests error paths and user-facing error messages.
+ * WHY: Errors are high-risk areas - tests ensure helpful messages and proper exit codes.
+ */
+export {};
+//# sourceMappingURL=error-handling.smoke.test.d.ts.map

package/dist/__tests__/smoke/error-handling.smoke.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handling.smoke.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/smoke/error-handling.smoke.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/__tests__/smoke/error-handling.smoke.test.js

@@ -0,0 +1,95 @@
+/**
+ * Error handling smoke tests.
+ *
+ * Tests error paths and user-facing error messages.
+ * WHY: Errors are high-risk areas - tests ensure helpful messages and proper exit codes.
+ */
+import * as assert from 'node:assert/strict';
+import { describe, it, afterEach } from 'node:test';
+import { runCommand } from '../../__testutils__/commandRunner.js';
+import { cleanupAllSessions, isDaemonRunning, killDaemon, waitForDaemon, } from '../../__testutils__/daemonHelpers.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+void describe('Error Handling Smoke Tests', () => {
+    afterEach(async () => {
+        // Cleanup after each test (no beforeEach needed if this works properly)
+        await cleanupAllSessions();
+    });
+    void it('should fail with helpful message when daemon not running', async () => {
+        // Try to peek without daemon running
+        // Note: peek auto-starts daemon, so it returns 83 after starting daemon
+        const result = await runCommand('peek', [], { timeout: 5000 });
+        // Should fail with resource not found (no session)
+        assert.equal(result.exitCode, EXIT_CODES.RESOURCE_NOT_FOUND);
+        // Should provide helpful error message about no session
+        assert.ok(/no.*session|session.*not.*found/i.test(result.stderr));
+    });
+    void it('should fail with helpful message when trying to stop without session', async () => {
+        // Try to stop without session
+        const result = await runCommand('stop', [], { timeout: 5000 });
+        // Should fail
+        assert.notEqual(result.exitCode, 0);
+        // Should provide helpful error message
+        assert.ok(result.stderr.includes('daemon'));
+    });
+    void it('should handle daemon crash during session', async () => {
+        // Start session with unique port
+        await runCommand('http://example.com', ['--port', '9230', '--headless'], { timeout: 10000 });
+        await waitForDaemon(5000);
+        // Kill daemon forcefully (simulate crash)
+        await killDaemon('SIGKILL');
+        // Wait for process to fully die
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        // Try to peek (should fail)
+        const peekResult = await runCommand('peek', [], { timeout: 5000 });
+        // Should fail
+        assert.notEqual(peekResult.exitCode, 0);
+        // Should provide helpful error message
+        assert.ok(peekResult.stderr.includes('daemon'));
+        // Daemon should not be running
+        assert.equal(isDaemonRunning(), false);
+    });
+    void it('should provide helpful error when Chrome fails to launch', async () => {
+        // Try to start with invalid Chrome path and unique port
+        const result = await runCommand('http://example.com', ['--port', '9231', '--headless'], {
+            timeout: 10000,
+            env: {
+                CHROME_PATH: '/nonexistent/chrome',
+            },
+        });
+        // Should fail (exit code 104 is acceptable for worker errors)
+        assert.notEqual(result.exitCode, 0);
+        // Should provide helpful error message mentioning Chrome
+        assert.ok(/chrome|browser|launch|binary/i.test(result.stderr));
+    });
+    void it('should cleanup stale sessions automatically', async () => {
+        // Start session with unique port
+        await runCommand('http://example.com', ['--port', '9232', '--headless'], { timeout: 10000 });
+        await waitForDaemon(5000);
+        // Kill daemon without cleanup (simulate crash)
+        await killDaemon('SIGKILL');
+        // Kill Chrome on port 9232 (simulating what happens when daemon crashes)
+        try {
+            const { execSync } = await import('child_process');
+            execSync(`lsof -ti:9232 | xargs kill -9 2>/dev/null || true`, { stdio: 'ignore' });
+        }
+        catch {
+            // Ignore errors if no process on port
+        }
+        // Wait for processes to fully die and port to be released
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        // Try to start new session (should cleanup stale and succeed)
+        const result = await runCommand('http://example.com', ['--port', '9232', '--headless'], {
+            timeout: 10000,
+        });
+        // Should succeed after cleanup
+        if (result.exitCode !== 0) {
+            console.error('Exit code:', result.exitCode);
+            console.error('Stderr:', result.stderr);
+            console.error('Stdout:', result.stdout);
+        }
+        assert.equal(result.exitCode, 0);
+        // New daemon should be running
+        assert.equal(isDaemonRunning(), true);
+    });
+});
+//# sourceMappingURL=error-handling.smoke.test.js.map

package/dist/__tests__/smoke/error-handling.smoke.test.js.map

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

package/dist/__tests__/smoke/session-lifecycle.smoke.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Session lifecycle smoke tests.
+ *
+ * Tests the complete user flow: start → collect data → stop → verify output.
+ * WHY: Highest-risk path with 0% coverage despite being critical user flow.
+ */
+export {};
+//# sourceMappingURL=session-lifecycle.smoke.test.d.ts.map

package/dist/__tests__/smoke/session-lifecycle.smoke.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-lifecycle.smoke.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/smoke/session-lifecycle.smoke.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/__tests__/smoke/session-lifecycle.smoke.test.js

@@ -0,0 +1,109 @@
+/**
+ * Session lifecycle smoke tests.
+ *
+ * Tests the complete user flow: start → collect data → stop → verify output.
+ * WHY: Highest-risk path with 0% coverage despite being critical user flow.
+ */
+import * as assert from 'node:assert/strict';
+import { describe, it, afterEach } from 'node:test';
+import { runCommand, runCommandJSON } from '../../__testutils__/commandRunner.js';
+import { cleanupAllSessions, isDaemonRunning, isSessionActive, readSessionOutput, waitForDaemon, } from '../../__testutils__/daemonHelpers.js';
+void describe('Session Lifecycle Smoke Tests', () => {
+    afterEach(async () => {
+        // Cleanup after each test (no beforeEach needed if this works properly)
+        await cleanupAllSessions();
+    });
+    void it('should start session and create daemon', async () => {
+        // Start session with a simple URL using a unique port to avoid conflicts
+        const result = await runCommand('http://example.com', ['--port', '9223', '--headless'], {
+            timeout: 10000,
+        });
+        // Should succeed
+        assert.equal(result.exitCode, 0);
+        // Daemon should be running
+        assert.equal(isDaemonRunning(), true);
+        // Session should be active
+        assert.equal(isSessionActive(), true);
+    });
+    void it('should collect data during session', async () => {
+        // Start session with unique port
+        const startResult = await runCommand('http://example.com', ['--port', '9224', '--headless'], {
+            timeout: 10000,
+        });
+        assert.equal(startResult.exitCode, 0, `Session start failed: ${startResult.stderr}`);
+        // Wait for daemon to be ready
+        await waitForDaemon(5000);
+        // Give Chrome time to navigate and collect some data
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        // Peek at collected data
+        const peekResult = await runCommandJSON('peek', [
+            '--json',
+        ]);
+        // Should have collected some data
+        assert.ok(peekResult);
+        assert.ok(typeof peekResult === 'object');
+        assert.ok('preview' in peekResult);
+        assert.ok('data' in peekResult.preview);
+        // Stop session to clean up
+        const stopResult = await runCommand('stop', [], { timeout: 10000 });
+        assert.equal(stopResult.exitCode, 0, `Stop failed: ${stopResult.stderr}`);
+    });
+    void it('should write output on stop', async () => {
+        // Start session with unique port
+        const startResult = await runCommand('http://example.com', ['--port', '9225', '--headless'], {
+            timeout: 10000,
+        });
+        assert.equal(startResult.exitCode, 0, `Session start failed: ${startResult.stderr}`);
+        await waitForDaemon(5000);
+        // Give Chrome time to collect data
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        // Stop session
+        const stopResult = await runCommand('stop', [], { timeout: 10000 });
+        // Should succeed
+        assert.equal(stopResult.exitCode, 0, `Stop failed: ${stopResult.stderr}`);
+        // Give filesystem time to write the file (increased for test stability)
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        // Output file should exist
+        const output = readSessionOutput();
+        assert.ok(output, 'Session output file should exist after stop');
+        assert.ok(typeof output === 'object');
+        // Output should have expected structure
+        assert.ok('version' in output);
+        assert.ok('success' in output);
+        assert.equal(output.success, true);
+        assert.ok('timestamp' in output);
+        assert.ok('data' in output);
+        assert.ok('target' in output);
+    });
+    void it('should cleanup daemon on stop', async () => {
+        // Start session with unique port
+        await runCommand('http://example.com', ['--port', '9226', '--headless'], { timeout: 10000 });
+        await waitForDaemon(5000);
+        // Stop session
+        await runCommand('stop', [], { timeout: 10000 });
+        // Wait for cleanup
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        // Daemon should no longer be running
+        assert.equal(isDaemonRunning(), false);
+        // Session should no longer be active
+        assert.equal(isSessionActive(), false);
+    });
+    void it('should handle concurrent session attempts gracefully', async () => {
+        // Start first session with unique port
+        const firstResult = await runCommand('http://example.com', ['--port', '9227', '--headless'], {
+            timeout: 10000,
+        });
+        assert.equal(firstResult.exitCode, 0, `First session start failed: ${firstResult.stderr}`);
+        await waitForDaemon(5000);
+        // Try to start second session (should fail)
+        const secondResult = await runCommand('http://another.com', ['--port', '9228', '--headless'], {
+            timeout: 10000,
+        });
+        // Should fail with daemon already running error
+        assert.notEqual(secondResult.exitCode, 0);
+        assert.ok(secondResult.stderr.includes('daemon') || secondResult.stderr.includes('already'), `Expected error about daemon, got: ${secondResult.stderr}`);
+        // First session should still be running
+        assert.equal(isDaemonRunning(), true);
+    });
+});
+//# sourceMappingURL=session-lifecycle.smoke.test.js.map

package/dist/__tests__/smoke/session-lifecycle.smoke.test.js.map

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