browser-debugger-cli 0.3.0 → 0.5.1

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. Run any CDP command, pipe the output, build browser automation with tools you already know. Design to be agent friendly
+
+## 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,173 @@ 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
-
-# Execute raw CDP commands
+# Run any CDP command
 bdg cdp Runtime.evaluate --params '{"expression":"document.title","returnByValue":true}'
-# { "result": { "type": "string", "value": "Example Domain" } }
-
 bdg cdp Network.getCookies
-# { "cookies": [...] }
 
-# Stop session
+# Check what's running
+bdg status
+
+# Done
 bdg stop
 ```
 
-## How It Works
+## What You Can Do
+
+### Run Any CDP Command
+
+All 300+ methods from [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) work out of the box:
+
+```bash
+# 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")'
+
+# Capture a screenshot
+bdg cdp Page.captureScreenshot | jq -r '.data' | base64 -d > screenshot.png
+```
 
-`bdg` is built on a **layered architecture** — raw CDP access with human-friendly wrappers on top.
+The daemon keeps a WebSocket open to Chrome, so commands run immediately against the live session.
 
-### Layer 1: Raw CDP Access ✅
+### Pipe Everything
 
-Direct access to **60+ domains, 300+ methods** from [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/):
+Output is JSON by default. Use it with `jq`, `grep`, `awk` - whatever works:
 
 ```bash
-# Execute any CDP method
-bdg cdp Network.getCookies
-bdg cdp Runtime.evaluate --params '{"expression":"document.title","returnByValue":true}'
-bdg cdp Performance.getMetrics
+# Find all failed network requests
+bdg peek --network --json | jq '.data.network[] | select(.status >= 400)'
 
-# Pipe to jq for filtering
-bdg cdp Network.getCookies | jq '.cookies[] | select(.name == "session")'
+# 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'
 ```
 
-**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
+### For AI Agents
+
+Claude skill included at `.claude/skills/bdg/` with working automation patterns:
 
-### Layer 2: Human-Friendly Wrappers 🚧
+- Common CDP workflows (scraping, polling, navigation)
+- Exit codes and error handling
+- Troubleshooting reference
 
-Building ergonomic commands on top of raw CDP for common workflows:
+The `--help --json` flag outputs the complete CLI schema for programmatic discovery:
 
 ```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
+bdg --help --json | jq '.command.subcommands[].name'
+bdg --help --json | jq '.exitCodes'
 ```
 
-**Progressive disclosure**: Start with raw CDP power, add convenience wrappers for common patterns.
+Agents can figure out what commands exist and how to use them without hardcoded knowledge.
 
-**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
+### Debug Live Apps
 
-## Available Commands
+Point at localhost, monitor what's happening:
 
-### Raw CDP Access
+```bash
+bdg localhost:3000 --headless
+bdg tail --console          # Stream console output
+bdg tail --network          # Watch requests in real-time
+```
+
+Helpful for catching issues during development without opening DevTools.
+
+### Automate Browser Tasks
 
-Full Chrome DevTools Protocol access via `bdg cdp` command – **any CDP method works**:
+Poll for elements, click buttons, extract data:
 
 ```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"
+# 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}'
 ```
 
-**60+ domains, 300+ methods** from the [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) are available.
+Check `.claude/skills/bdg/WORKFLOWS.md` for more complete examples (GitHub scraper, form automation, etc).
+
+## Session Management
 
-### Session Management
+Sessions persist until you stop them. Chrome stays open, data keeps collecting:
 
 ```bash
-# Start session
-bdg example.com             # Opens Chrome with daemon in background
+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
+```
 
-# Check if session is active
-bdg status                  # Show session info
-bdg status --verbose        # Include Chrome diagnostics
+## Helper Commands
 
-# Stop session
-bdg stop                    # Gracefully stop daemon and close Chrome
+A few convenience wrappers for common operations. Most work still happens through `bdg cdp`:
 
-# Clean up stale sessions
-bdg cleanup                 # Remove stale session files
-bdg cleanup --force         # Force cleanup even if session appears active
+```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
 ```
 
-## Technical Overview
+## Page Readiness
 
-`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.
+By default, `bdg` waits for pages to fully load using three signals:
 
-**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
+1. Browser's `window.onload` fires
+2. Network goes quiet (200ms without new requests)
+3. DOM stops changing (300ms without mutations)
 
-**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
+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.
 
-## Contributing
+Skip it with `--no-wait` if you want immediate connection.
 
-Contributions welcome! But honestly, I'd just be happy if you give it a try.
+## 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,106 @@
+/**
+ * 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 invalid URL gracefully', async () => {
+        // Note: URL validation is permissive - "not-a-valid-url" becomes "http://not-a-valid-url/"
+        // This test verifies error handling, not URL validation
+        const result = await runCommand('http://example.com', ['--port', '9229', '--headless'], {
+            timeout: 10000,
+        });
+        // Should succeed (URL is valid, session starts)
+        assert.equal(result.exitCode, 0);
+        // Should provide session started message
+        assert.ok(/session started|target:/i.test(result.stderr));
+    });
+    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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"}

package/dist/__testutils__/commandRunner.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Command runner for smoke tests.
+ *
+ * Executes bdg CLI commands in a subprocess and captures output.
+ * WHY: Enables end-to-end testing of CLI commands without mocking.
+ */
+export interface CommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+}
+/**
+ * Run a bdg CLI command in a subprocess.
+ *
+ * @param command - Command name (e.g., 'start', 'stop', 'peek')
+ * @param args - Command arguments
+ * @param options - Execution options
+ * @returns Promise resolving to command result
+ *
+ * @example
+ * ```typescript
+ * const result = await runCommand('start', ['http://localhost:3000']);
+ * assert.equal(result.exitCode, 0);
+ * ```
+ */
+export declare function runCommand(command: string, args?: string[], options?: {
+    timeout?: number;
+    env?: Record<string, string>;
+}): Promise<CommandResult>;
+/**
+ * Run command and parse JSON output from stdout.
+ *
+ * @param command - Command name
+ * @param args - Command arguments
+ * @returns Parsed JSON output
+ *
+ * @example
+ * ```typescript
+ * const data = await runCommandJSON('peek');
+ * assert.ok(data.data.network.length > 0);
+ * ```
+ */
+export declare function runCommandJSON<T = unknown>(command: string, args?: string[]): Promise<T>;
+//# sourceMappingURL=commandRunner.d.ts.map

package/dist/__testutils__/commandRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandRunner.d.ts","sourceRoot":"","sources":["../../src/__testutils__/commandRunner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,EAAO,EACnB,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzB,GACL,OAAO,CAAC,aAAa,CAAC,CAiExB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAAC,CAAC,GAAG,OAAO,EAC9C,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,EAAO,GAClB,OAAO,CAAC,CAAC,CAAC,CAYZ"}