debug-run 0.5.1 → 0.5.2

package/.claude/skills/debug-run/DOTNET.md

@@ -0,0 +1,262 @@
+# .NET Debugging Guide
+
+This guide covers debugging .NET applications with debug-run using the vsdbg adapter.
+
+## Prerequisites
+
+### vsdbg Adapter
+
+The vsdbg adapter is automatically detected if you have the VS Code C# extension installed:
+
+```bash
+npx debug-run list-adapters
+# Should show: vsdbg - Status: installed (path)
+```
+
+If not installed, install the [C# extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp) in VS Code.
+
+### Alternative: netcoredbg
+
+Open-source alternative (less stable on some platforms):
+
+```bash
+npx debug-run install-adapter netcoredbg
+```
+
+## Build Your Application
+
+Before debugging, build your .NET application:
+
+```bash
+dotnet build
+```
+
+## Launch Mode (Debug New Process)
+
+### Basic Debugging
+
+```bash
+npx debug-run ./bin/Debug/net8.0/MyApp.dll \
+  -a vsdbg \
+  -b "src/Services/OrderService.cs:42" \
+  --pretty \
+  -t 30s
+```
+
+### With Expression Evaluation
+
+```bash
+npx debug-run ./bin/Debug/net8.0/MyApp.dll \
+  -a vsdbg \
+  -b "src/Services/OrderService.cs:42" \
+  -e "order.Total" \
+  -e "order.Items.Count" \
+  -e "this._inventory.Count" \
+  --pretty \
+  -t 30s
+```
+
+### With Assertions
+
+```bash
+npx debug-run ./bin/Debug/net8.0/MyApp.dll \
+  -a vsdbg \
+  -b "src/Services/OrderService.cs:42" \
+  --assert "order.Total >= 0" \
+  --assert "order.Items.Count > 0" \
+  --assert "this._inventory != null" \
+  --pretty \
+  -t 30s
+```
+
+### Exception Handling
+
+Break on all exceptions with chain flattening:
+
+```bash
+npx debug-run ./bin/Debug/net8.0/MyApp.dll \
+  -a vsdbg \
+  --break-on-exception all \
+  --pretty \
+  -t 30s
+```
+
+## Attach Mode (ASP.NET / Long-Running Services)
+
+For debugging running ASP.NET applications or services:
+
+### 1. Start Your Application
+
+```bash
+cd MyWebApi
+dotnet run
+# Note the process - find PID with: ps aux | grep dotnet
+```
+
+### 2. Attach debug-run
+
+```bash
+npx debug-run --attach --pid <PID> \
+  -a vsdbg \
+  -b "src/Controllers/OrderController.cs:28" \
+  -e "request.OrderId" \
+  --pretty \
+  -t 60s
+```
+
+### Important Notes for Attach Mode
+
+1. **Timing matters**: After `process_attached` event, wait 10-15 seconds before triggering the code path
+2. **Breakpoints start unverified**: `verified: false` is normal; they verify when the code path is hit
+3. **Process survives**: In attach mode, the debuggee keeps running after debug-run exits
+
+### Example: Debug ASP.NET Endpoint
+
+```bash
+# Terminal 1: Start the API
+cd samples/aspnet/SampleApi
+dotnet run  # Runs on http://localhost:5009
+
+# Terminal 2: Attach debugger
+npx debug-run --attach --pid $(pgrep -f SampleApi) \
+  -a vsdbg \
+  -b "samples/aspnet/SampleApi/Program.cs:16" \
+  --pretty \
+  -t 60s
+
+# Terminal 3: Trigger the endpoint
+curl http://localhost:5009/orders
+```
+
+## Test Debugging (NUnit, xUnit, MSTest)
+
+debug-run supports debugging .NET unit tests with automatic test runner orchestration:
+
+### Quick Start
+
+```bash
+# Build the test project first
+cd samples/nunit && dotnet build && cd ../..
+
+# Debug tests
+npx debug-run --test-project samples/nunit \
+  -b "samples/nunit/CalculatorTests.cs:57" \
+  --pretty \
+  -t 60s
+```
+
+### Filter Specific Tests
+
+```bash
+npx debug-run --test-project samples/nunit \
+  --test-filter "Add_TwoPositiveNumbers_ReturnsSum" \
+  -b "samples/nunit/CalculatorTests.cs:57" \
+  --pretty
+```
+
+### With Expression Evaluation
+
+```bash
+npx debug-run --test-project samples/nunit \
+  -b "samples/nunit/CalculatorTests.cs:57" \
+  -e "a" -e "b" -e "result" \
+  --pretty
+```
+
+### How It Works
+
+1. Launches `dotnet test --no-build` with `VSTEST_HOST_DEBUG=1`
+2. Parses the testhost PID from the output
+3. Automatically attaches the debugger to the testhost process
+4. Sets breakpoints and captures variables
+
+## Trace Mode
+
+Follow execution flow after hitting a breakpoint:
+
+```bash
+# Basic trace
+npx debug-run ./bin/Debug/net8.0/MyApp.dll \
+  -a vsdbg \
+  -b "src/Services/OrderService.cs:42" \
+  --trace \
+  --pretty
+
+# Trace into function calls
+npx debug-run ./bin/Debug/net8.0/MyApp.dll \
+  -a vsdbg \
+  -b "src/Services/OrderService.cs:42" \
+  --trace \
+  --trace-into \
+  --trace-limit 50 \
+  --pretty
+
+# Trace with variable diffing
+npx debug-run ./bin/Debug/net8.0/MyApp.dll \
+  -a vsdbg \
+  -b "src/Services/OrderService.cs:42" \
+  --trace \
+  --diff-vars \
+  --pretty
+```
+
+## Sample Application
+
+A sample .NET console application is included for testing:
+
+```bash
+# Build
+cd samples/dotnet && dotnet build && cd ../..
+
+# Debug
+npx debug-run ./samples/dotnet/bin/Debug/net8.0/SampleApp.dll \
+  -a vsdbg \
+  -b "samples/dotnet/Program.cs:67" \
+  --pretty \
+  -t 30s
+```
+
+### Good Breakpoint Locations
+
+| Line | Location | Description |
+|------|----------|-------------|
+| 67 | `ProcessOrder` | Inside order processing method |
+| 51 | `Main` | After configuration setup |
+| 78 | `CalculateDiscount` | Discount calculation logic |
+
+## Token Efficiency for .NET
+
+### Blocked Properties (Automatic)
+
+debug-run automatically filters verbose .NET reflection metadata:
+- `EqualityContract` - C# record equality (often 4KB+ of noise)
+- `CustomAttributes`, `DeclaredConstructors`, `DeclaredMethods`
+- `[More]`, `Raw View`, `Static members`, `Non-Public members`
+
+### Service Type Compaction
+
+Common service patterns are compacted by default:
+```json
+"_logger": { "type": "ILogger<OrderService>", "value": "{ILogger}" }
+"_repository": { "type": "OrderRepository", "value": "{Repository}" }
+```
+
+Override with `--expand-services` if you need full expansion.
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| vsdbg license warning | Informational only, can be ignored |
+| netcoredbg SIGSEGV | Use vsdbg instead (`-a vsdbg`) |
+| "Adapter not installed" | Install VS Code C# extension |
+| Breakpoint not verified | Wait longer after attach, or check file path |
+| Test not stopping | Ensure `--no-build` and build manually first |
+
+### Debug Adapter Communication
+
+Enable verbose DAP logging:
+
+```bash
+DEBUG_DAP=1 npx debug-run ./app.dll -a vsdbg -b "file.cs:10" --pretty
+```

package/.claude/skills/debug-run/PYTHON.md

@@ -0,0 +1,282 @@
+# Python Debugging Guide
+
+This guide covers debugging Python applications with debug-run using the debugpy adapter.
+
+## Prerequisites
+
+### debugpy Adapter
+
+The debugpy adapter is automatically detected from two sources:
+
+1. **VS Code Python Extension** (recommended) - debugpy is bundled with it
+2. **pip installation** - `pip install debugpy`
+
+Check availability:
+
+```bash
+npx debug-run list-adapters
+# Should show: debugpy - Status: installed (VS Code Python extension or pip)
+```
+
+### Installing debugpy
+
+**Option 1: VS Code Python Extension (Recommended)**
+- Install the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) in VS Code
+- debugpy is bundled automatically
+
+**Option 2: pip**
+```bash
+pip install debugpy
+# or
+pip3 install debugpy
+```
+
+## Launch Mode (Debug Python Script)
+
+### Basic Debugging
+
+```bash
+npx debug-run ./main.py \
+  -a python \
+  -b "src/processor.py:25" \
+  --pretty \
+  -t 30s
+```
+
+### With Expression Evaluation
+
+```bash
+npx debug-run ./main.py \
+  -a python \
+  -b "src/processor.py:42" \
+  -e "subtotal" \
+  -e "tax" \
+  -e "order.order_id" \
+  -e "len(order.items)" \
+  --pretty \
+  -t 30s
+```
+
+### With Assertions
+
+```bash
+npx debug-run ./main.py \
+  -a python \
+  -b "src/processor.py:42" \
+  --assert "subtotal >= 0" \
+  --assert "len(order.items) > 0" \
+  --assert "customer is not None" \
+  --pretty \
+  -t 30s
+```
+
+### Exception Handling
+
+Break on raised or uncaught exceptions:
+
+```bash
+# Break on all raised exceptions
+npx debug-run ./main.py \
+  -a python \
+  --break-on-exception raised \
+  --pretty \
+  -t 30s
+
+# Break on uncaught exceptions only
+npx debug-run ./main.py \
+  -a python \
+  --break-on-exception uncaught \
+  --pretty \
+  -t 30s
+```
+
+## Adapter Aliases
+
+Both `-a python` and `-a debugpy` work identically:
+
+```bash
+# These are equivalent
+npx debug-run ./main.py -a python -b "main.py:10" --pretty
+npx debug-run ./main.py -a debugpy -b "main.py:10" --pretty
+```
+
+## Sample Application
+
+A sample Python application is included for testing:
+
+```bash
+# Debug the sample app
+npx debug-run samples/python/sample_app.py \
+  -a python \
+  -b "samples/python/sample_app.py:185" \
+  --pretty \
+  -t 30s
+```
+
+### With Expression Evaluation
+
+```bash
+npx debug-run samples/python/sample_app.py \
+  -a python \
+  -b "samples/python/sample_app.py:188" \
+  -e "subtotal" \
+  -e "tax" \
+  -e "discount" \
+  -e "order.order_id" \
+  --pretty \
+  -t 30s
+```
+
+### Good Breakpoint Locations (Sample App)
+
+| Line | Location | Description |
+|------|----------|-------------|
+| 185 | `process_order` | After variable setup, before loyalty points |
+| 140 | `calculate_discount` | After discount rate calculation |
+| 298 | `main` | Before processing first order |
+| 178 | `process_order` | Inside inventory loop |
+
+## Trace Mode
+
+Follow execution flow after hitting a breakpoint:
+
+```bash
+# Basic trace
+npx debug-run ./main.py \
+  -a python \
+  -b "src/processor.py:25" \
+  --trace \
+  --pretty
+
+# Trace into function calls
+npx debug-run ./main.py \
+  -a python \
+  -b "src/processor.py:25" \
+  --trace \
+  --trace-into \
+  --trace-limit 50 \
+  --pretty
+
+# Trace with variable diffing
+npx debug-run ./main.py \
+  -a python \
+  -b "src/processor.py:25" \
+  --trace \
+  --diff-vars \
+  --pretty
+```
+
+## Python-Specific Notes
+
+### Breakpoint Timing
+
+Breakpoints are set AFTER launch for Python (debugpy's DAP flow differs from .NET). This is handled automatically by debug-run.
+
+### Dataclass Variables
+
+Python dataclasses show a `special variables` section in locals containing class metadata. This is normal debugpy behavior. The actual instance fields are shown alongside.
+
+```json
+{
+  "customer": {
+    "type": "Customer",
+    "value": {
+      "special variables": {...},  // Class metadata
+      "id": { "type": "str", "value": "CUST-001" },
+      "name": { "type": "str", "value": "Alice" },
+      "email": { "type": "str", "value": "alice@example.com" }
+    }
+  }
+}
+```
+
+### justMyCode
+
+By default, debug-run sets `justMyCode: false` to allow stepping into library code. The default Python debugger behavior only stops in user code.
+
+### Expression Syntax
+
+Use Python syntax for expressions:
+
+```bash
+# Python expressions
+-e "len(items)"
+-e "order.items[0].price"
+-e "sum(item.quantity for item in order.items)"
+-e "customer.loyalty_tier.value"
+```
+
+## Working with Virtual Environments
+
+If your project uses a virtual environment, activate it before running debug-run:
+
+```bash
+# Activate venv
+source .venv/bin/activate  # Linux/macOS
+# or
+.venv\Scripts\activate  # Windows
+
+# Then debug
+npx debug-run ./main.py -a python -b "main.py:10" --pretty
+```
+
+debug-run uses the active Python interpreter, which will have access to your virtual environment's packages.
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "debugpy not found" | Install VS Code Python extension or `pip install debugpy` |
+| "python not found" | Ensure Python 3 is in PATH (`python3 --version`) |
+| Variables show as "not defined" | Expression is evaluated BEFORE the line executes |
+| Breakpoint not hitting | Check file path is correct and line has executable code |
+| Timeout before breakpoint | Increase timeout with `-t 60s` or `-t 2m` |
+
+### Debug Adapter Communication
+
+Enable verbose DAP logging to troubleshoot:
+
+```bash
+DEBUG_DAP=1 npx debug-run ./main.py -a python -b "main.py:10" --pretty
+```
+
+### Verify debugpy Installation
+
+```bash
+# Check if debugpy is importable
+python3 -c "import debugpy; print(debugpy.__version__)"
+
+# Check adapter detection
+npx debug-run list-adapters
+```
+
+## Common Patterns
+
+### Debug a Flask/Django App
+
+```bash
+# Flask
+npx debug-run app.py \
+  -a python \
+  -b "app.py:25" \
+  --pretty \
+  -t 120s
+
+# Django (using manage.py)
+npx debug-run manage.py runserver \
+  -a python \
+  -b "myapp/views.py:42" \
+  --pretty \
+  -t 120s
+```
+
+### Debug with Arguments
+
+```bash
+npx debug-run ./script.py -- --input data.json --verbose \
+  -a python \
+  -b "script.py:15" \
+  --pretty
+```
+
+Arguments after `--` are passed to your Python script.

package/.claude/skills/debug-run/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: debug-run
+description: Programmatically debug code using debug-run CLI with DAP. Use when debugging .NET, Python, or JavaScript/TypeScript applications, setting breakpoints, capturing variables, evaluating expressions, or attaching to running processes.
+---
+
+# debug-run Debugging Skill
+
+Use the `debug-run` CLI tool to programmatically debug applications via the Debug Adapter Protocol (DAP). This skill enables you to set breakpoints, capture variable state, and evaluate expressions without interactive debugger sessions.
+
+## When to Use This Skill
+
+- Debugging .NET applications (using vsdbg adapter)
+- Debugging Python applications (using debugpy adapter)
+- Debugging JavaScript/TypeScript applications (using js-debug/node adapter)
+- Capturing runtime state at specific code locations
+- Evaluating expressions to inspect object properties
+- Attaching to running processes for live debugging
+
+## Prerequisites
+
+Ensure debug-run is installed in the project:
+
+```bash
+npm install  # in the debug-run directory
+```
+
+Check available adapters:
+
+```bash
+npx debug-run list-adapters
+```
+
+## Language-Specific Guides
+
+For detailed setup, examples, and troubleshooting for each language:
+
+- [.NET Debugging Guide](DOTNET.md) - vsdbg adapter, ASP.NET attach mode, NUnit test debugging
+- [Python Debugging Guide](PYTHON.md) - debugpy adapter, VS Code integration, sample app
+- [TypeScript/JavaScript Debugging Guide](TYPESCRIPT.md) - js-debug adapter, source maps, Node.js
+
+## Basic Usage
+
+```bash
+npx debug-run <program> -a <adapter> -b "<file:line>" [options]
+```
+
+### Quick Examples
+
+```bash
+# .NET
+npx debug-run ./bin/Debug/net8.0/MyApp.dll -a vsdbg -b "src/Service.cs:42" --pretty
+
+# Python
+npx debug-run ./main.py -a python -b "src/processor.py:25" --pretty
+
+# TypeScript/JavaScript
+npx debug-run ./dist/index.js -a node -b "src/index.ts:100" --pretty
+```
+
+## Options Reference
+
+### Core Options
+
+| Option | Description |
+|--------|-------------|
+| `-a, --adapter <name>` | Debug adapter: `vsdbg` (.NET), `python`/`debugpy` (Python), `node`/`js` (JS/TS) |
+| `-b, --breakpoint <loc>` | Breakpoint location as `file:line` (can specify multiple) |
+| `-e, --eval <expr>` | Expression to evaluate at breakpoints (can specify multiple) |
+| `--assert <expr>` | Invariant expression; halts on first violation (can specify multiple) |
+| `-t, --timeout <time>` | Timeout duration: `30s`, `2m`, `5m` (default: 60s) |
+| `--pretty` | Pretty-print JSON output |
+| `-o, --output <file>` | Write events to file instead of stdout |
+
+### Attach Mode
+
+| Option | Description |
+|--------|-------------|
+| `--attach` | Attach to running process instead of launching |
+| `--pid <id>` | Process ID for attach mode |
+
+### Trace Mode
+
+| Option | Description |
+|--------|-------------|
+| `--trace` | Enable trace mode - step through code after breakpoint |
+| `--trace-into` | Use stepIn instead of stepOver (follow into functions) |
+| `--trace-limit <N>` | Max steps in trace mode (default: 500) |
+| `--trace-until <expr>` | Stop trace when expression is truthy |
+| `--diff-vars` | Show only changed variables in trace steps |
+
+### Token Efficiency
+
+| Option | Description |
+|--------|-------------|
+| `--expand-services` | Fully expand service types (Logger, Repository, etc.) |
+| `--show-null-props` | Include null/undefined properties in output |
+| `--no-dedupe` | Disable content-based deduplication |
+
+### Event Filtering
+
+| Option | Description |
+|--------|-------------|
+| `--include <types...>` | Only emit these event types |
+| `--exclude <types...>` | Suppress these event types |
+
+### Exception Handling
+
+| Option | Description |
+|--------|-------------|
+| `--break-on-exception <filter>` | Break on exceptions: `all`, `uncaught`, `raised` |
+| `--no-flatten-exceptions` | Disable exception chain analysis |
+| `--exception-chain-depth <n>` | Max depth to traverse (default: 10) |
+
+## Assertions
+
+Use `--assert` to declare invariants. The debugger halts immediately when any assertion fails:
+
+```bash
+npx debug-run ./app.dll -a vsdbg \
+  -b "src/OrderService.cs:42" \
+  --assert "order.Total >= 0" \
+  --assert "order.Items.Count > 0" \
+  --pretty
+```
+
+Assertions are checked at every breakpoint hit, trace step, and regular step.
+
+## Trace Mode
+
+Trace mode automatically steps through code after hitting a breakpoint:
+
+```bash
+# Basic trace
+npx debug-run ./app.dll -a vsdbg -b "src/Service.cs:42" --trace --pretty
+
+# Trace into function calls with limit
+npx debug-run ./app.dll -a vsdbg -b "src/Service.cs:42" --trace --trace-into --trace-limit 100 --pretty
+
+# Trace until condition
+npx debug-run ./app.dll -a vsdbg -b "src/Service.cs:42" --trace --trace-until "total > 100" --pretty
+
+# Trace with variable diffing (shows only changes)
+npx debug-run ./app.dll -a vsdbg -b "src/Service.cs:42" --trace --diff-vars --pretty
+```
+
+## Output Format
+
+debug-run outputs NDJSON (newline-delimited JSON) events:
+
+### Event Types
+
+| Event | Description |
+|-------|-------------|
+| `session_start` | Debug session initialized |
+| `breakpoint_set` | Breakpoint configured (check `verified` field) |
+| `process_launched` | Debuggee process started |
+| `process_attached` | Attached to running process |
+| `breakpoint_hit` | Breakpoint was hit with locals and evaluations |
+| `assertion_failed` | Assertion violation with context |
+| `trace_started` | Trace mode began |
+| `trace_step` | Single trace step (with `changes` if `--diff-vars`) |
+| `trace_completed` | Trace finished |
+| `exception_thrown` | Exception occurred |
+| `program_output` | stdout/stderr from debuggee |
+| `process_exited` | Program terminated |
+| `session_end` | Summary with statistics |
+
+### breakpoint_hit Example
+
+```json
+{
+  "type": "breakpoint_hit",
+  "timestamp": "...",
+  "location": {
+    "file": "src/Services/OrderService.cs",
+    "line": 42,
+    "function": "ProcessOrder"
+  },
+  "stackTrace": [...],
+  "locals": {
+    "order": { "type": "Order", "value": {...} },
+    "this": {...}
+  },
+  "evaluations": {
+    "order.Total": { "result": "125.50" },
+    "order.Items.Count": { "result": "3" }
+  }
+}
+```
+
+## Token Efficiency
+
+debug-run includes automatic optimizations for enterprise applications:
+
+### Service Type Compaction (default)
+Types like `Logger`, `Repository`, `Service` are shown in compact form:
+```json
+"logger": { "type": "Logger", "value": "{Logger}" }
+```
+
+### Null Property Omission (default)
+Properties with null/undefined values are omitted.
+
+### Content-Based Deduplication (default)
+Repeated object content references the first occurrence:
+```json
+"loyaltyService._features": { "value": "[see: discountService._features]", "deduplicated": true }
+```
+
+## Best Practices
+
+1. **Use relative paths for breakpoints**: `-b "src/MyFile.cs:42"` not `-b "MyFile.cs:42"`
+
+2. **Expression timing**: Expressions evaluate BEFORE the breakpoint line executes. Variables assigned on that line will be null/unset.
+
+3. **Unverified breakpoints**: In attach mode, breakpoints start as `verified: false`. They verify when the code path is hit.
+
+4. **Long-running processes**: Use appropriate timeouts (`-t 5m`) and trigger the code path while debug-run is waiting.
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "Adapter not installed" | Run `list-adapters` to check available adapters |
+| Breakpoint not hitting | Verify path is relative to working directory and line has executable code |
+| Session timeout | Increase timeout with `-t 2m` or `-t 5m` |
+
+For language-specific troubleshooting, see the language guides linked above.

package/.claude/skills/debug-run/TYPESCRIPT.md

@@ -0,0 +1,378 @@
+# TypeScript/JavaScript Debugging Guide
+
+This guide covers debugging TypeScript and JavaScript applications with debug-run using the js-debug (Node.js) adapter.
+
+## Prerequisites
+
+### js-debug Adapter
+
+The js-debug adapter is detected from two sources:
+
+1. **VS Code js-debug extension** - Built into VS Code or install separately
+2. **Installed via debug-run** - `npx debug-run install-adapter node`
+
+Check availability:
+
+```bash
+npx debug-run list-adapters
+# Should show: node - Status: installed (path)
+```
+
+### Installing js-debug
+
+**Option 1: VS Code (Recommended)**
+- js-debug is built into VS Code
+- Or install the [JavaScript Debugger (Nightly)](https://marketplace.visualstudio.com/items?itemName=ms-vscode.js-debug-nightly) extension
+
+**Option 2: debug-run installer**
+```bash
+npx debug-run install-adapter node
+```
+
+### Node.js
+
+Ensure Node.js is installed:
+```bash
+node --version  # Should be v18+ recommended
+```
+
+## Build TypeScript Projects
+
+For TypeScript, compile to JavaScript first:
+
+```bash
+# Install dependencies and build
+npm install
+npm run build  # or: npx tsc
+```
+
+## Launch Mode (Debug JavaScript)
+
+### Basic Debugging
+
+```bash
+npx debug-run ./dist/index.js \
+  -a node \
+  -b "src/index.ts:42" \
+  --pretty \
+  -t 30s
+```
+
+Note: Set breakpoints using the **source TypeScript file path**, not the compiled JavaScript path. Source maps enable this mapping.
+
+### With Expression Evaluation
+
+```bash
+npx debug-run ./dist/index.js \
+  -a node \
+  -b "src/services/OrderService.ts:55" \
+  -e "order.total" \
+  -e "order.items.length" \
+  -e "this.config" \
+  --pretty \
+  -t 30s
+```
+
+### With Assertions
+
+```bash
+npx debug-run ./dist/index.js \
+  -a node \
+  -b "src/services/OrderService.ts:55" \
+  --assert "order.total >= 0" \
+  --assert "order.items.length > 0" \
+  --assert "this.inventory !== null" \
+  --pretty \
+  -t 30s
+```
+
+### Exception Handling
+
+Break on exceptions:
+
+```bash
+# Break on all exceptions
+npx debug-run ./dist/index.js \
+  -a node \
+  --break-on-exception all \
+  --pretty \
+  -t 30s
+
+# Break on uncaught exceptions only
+npx debug-run ./dist/index.js \
+  -a node \
+  --break-on-exception uncaught \
+  --pretty \
+  -t 30s
+```
+
+## Adapter Aliases
+
+Multiple aliases work for the Node.js adapter:
+
+```bash
+# These are all equivalent
+npx debug-run ./dist/index.js -a node -b "src/index.ts:10" --pretty
+npx debug-run ./dist/index.js -a nodejs -b "src/index.ts:10" --pretty
+npx debug-run ./dist/index.js -a js -b "src/index.ts:10" --pretty
+npx debug-run ./dist/index.js -a javascript -b "src/index.ts:10" --pretty
+```
+
+## Sample Application
+
+A sample TypeScript application is included for testing:
+
+```bash
+# Build the sample
+cd samples/typescript && npm install && npm run build && cd ../..
+
+# Debug
+npx debug-run samples/typescript/dist/index.js \
+  -a node \
+  -b "samples/typescript/src/index.ts:160" \
+  --pretty \
+  -t 30s
+```
+
+### With Expression Evaluation
+
+```bash
+npx debug-run samples/typescript/dist/index.js \
+  -a node \
+  -b "samples/typescript/src/index.ts:177" \
+  -e "subtotal" \
+  -e "tax" \
+  -e "discount" \
+  -e "order.orderId" \
+  --pretty \
+  -t 30s
+```
+
+### Good Breakpoint Locations (Sample App)
+
+| Line | Location | Description |
+|------|----------|-------------|
+| 160 | `processOrder` | Start of order processing method |
+| 177 | `processOrder` | After calculating subtotal, tax, discount |
+| 168 | `processOrder` | Inside inventory check loop |
+| 304 | `main` | Before processing first order |
+
+## Source Maps
+
+debug-run automatically uses source maps to map breakpoints from TypeScript source files to compiled JavaScript.
+
+### Requirements
+
+1. **Enable source maps in tsconfig.json**:
+```json
+{
+  "compilerOptions": {
+    "sourceMap": true,
+    "outDir": "./dist"
+  }
+}
+```
+
+2. **Set breakpoints using TypeScript paths**:
+```bash
+# Correct: Use .ts source file
+-b "src/services/OrderService.ts:42"
+
+# Incorrect: Don't use .js compiled file
+-b "dist/services/OrderService.js:42"
+```
+
+### How Source Maps Work
+
+When you compile TypeScript:
+- `src/index.ts` → `dist/index.js` + `dist/index.js.map`
+
+debug-run tells js-debug to:
+1. Run `dist/index.js`
+2. Use source maps to show original TypeScript
+3. Set breakpoints in TypeScript that map to correct JS locations
+
+## Trace Mode
+
+Follow execution flow after hitting a breakpoint:
+
+```bash
+# Basic trace
+npx debug-run ./dist/index.js \
+  -a node \
+  -b "src/index.ts:42" \
+  --trace \
+  --pretty
+
+# Trace into function calls
+npx debug-run ./dist/index.js \
+  -a node \
+  -b "src/index.ts:42" \
+  --trace \
+  --trace-into \
+  --trace-limit 50 \
+  --pretty
+
+# Trace with variable diffing
+npx debug-run ./dist/index.js \
+  -a node \
+  -b "src/index.ts:42" \
+  --trace \
+  --diff-vars \
+  --pretty
+```
+
+## JavaScript-Specific Notes
+
+### Provisional Breakpoints
+
+js-debug uses "provisional breakpoints" that start as unverified:
+```json
+{
+  "type": "breakpoint_set",
+  "verified": false,
+  "message": "breakpoint.provisionalBreakpoint"
+}
+```
+
+This is normal - breakpoints verify when the code is loaded.
+
+### Internal Code
+
+By default, debug-run configures js-debug to skip internal Node.js code:
+```json
+"skipFiles": ["<node_internals>/**"]
+```
+
+Stack traces may show `[Internal Code]` for Node.js internals.
+
+### Expression Syntax
+
+Use JavaScript syntax for expressions:
+
+```bash
+# JavaScript expressions
+-e "items.length"
+-e "order.items[0].price"
+-e "order.items.reduce((sum, item) => sum + item.quantity, 0)"
+-e "customer?.loyaltyTier ?? 'none'"
+```
+
+### this Context
+
+In class methods, `this` is automatically captured in locals:
+
+```json
+{
+  "locals": {
+    "this": {
+      "type": "OrderService",
+      "value": {
+        "config": {...},
+        "inventory": {...}
+      }
+    }
+  }
+}
+```
+
+## Debugging Plain JavaScript
+
+For plain JavaScript (no TypeScript):
+
+```bash
+npx debug-run ./index.js \
+  -a node \
+  -b "index.js:25" \
+  --pretty \
+  -t 30s
+```
+
+No build step needed - just point to the .js file directly.
+
+## Debugging ESM vs CommonJS
+
+debug-run works with both module systems:
+
+```bash
+# ESM (type: "module" in package.json)
+npx debug-run ./dist/index.js -a node -b "src/index.ts:10" --pretty
+
+# CommonJS
+npx debug-run ./dist/index.js -a node -b "src/index.ts:10" --pretty
+```
+
+The adapter auto-detects the module system.
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "Adapter not installed" | Run `npx debug-run install-adapter node` or install VS Code |
+| Breakpoint not hitting | Check source maps exist (`.js.map` files) |
+| Wrong line numbers | Rebuild TypeScript (`npm run build`) |
+| "Cannot find module" | Run `npm install` first |
+| Provisional breakpoint never verifies | Check file path matches source exactly |
+
+### Debug Adapter Communication
+
+Enable verbose DAP logging:
+
+```bash
+DEBUG_DAP=1 npx debug-run ./dist/index.js -a node -b "src/index.ts:10" --pretty
+```
+
+### Verify Source Maps
+
+Check that source maps are generated:
+```bash
+ls dist/*.js.map  # Should list .map files
+```
+
+Check tsconfig.json has `"sourceMap": true`.
+
+## Common Patterns
+
+### Debug with Arguments
+
+```bash
+npx debug-run ./dist/cli.js -- --input data.json --verbose \
+  -a node \
+  -b "src/cli.ts:15" \
+  --pretty
+```
+
+Arguments after `--` are passed to your script.
+
+### Debug Tests (Jest/Mocha)
+
+For test debugging, run the test file directly:
+
+```bash
+# Jest (compile first if TypeScript)
+npx debug-run ./node_modules/jest/bin/jest.js -- --runInBand tests/order.test.ts \
+  -a node \
+  -b "tests/order.test.ts:25" \
+  --pretty \
+  -t 60s
+
+# Mocha
+npx debug-run ./node_modules/mocha/bin/mocha.js -- dist/tests/**/*.js \
+  -a node \
+  -b "src/tests/order.test.ts:25" \
+  --pretty \
+  -t 60s
+```
+
+### Debug Express/Fastify Server
+
+```bash
+npx debug-run ./dist/server.js \
+  -a node \
+  -b "src/routes/orders.ts:42" \
+  --pretty \
+  -t 120s
+
+# In another terminal, trigger the endpoint:
+# curl http://localhost:3000/orders
+```

package/README.md

@@ -25,17 +25,38 @@ Agents can write and run code, but when something goes wrong, they're blind. The
 ## Installation
 
 ```bash
-# Clone and install
+# Install globally
+npm install -g debug-run
+
+# Or run directly with npx
+npx debug-run --help
+```
+
+### Claude Code Skill (Recommended)
+
+To enable Claude Code to use debug-run effectively, copy the skill to your skills directory:
+
+```bash
+# Create skills directory if it doesn't exist
+mkdir -p ~/.claude/skills
+
+# Copy the debug-run skill
+cp -r node_modules/debug-run/.claude/skills/debug-run ~/.claude/skills/
+```
+
+This installs the skill which teaches Claude how to use debug-run for debugging .NET, Python, and TypeScript applications. The skill includes:
+- `SKILL.md` - Main skill with options reference and best practices
+- `DOTNET.md` - .NET-specific guide (vsdbg, ASP.NET, NUnit)
+- `PYTHON.md` - Python-specific guide (debugpy)
+- `TYPESCRIPT.md` - TypeScript/JavaScript guide (js-debug)
+
+### Development Setup
+
+```bash
 git clone https://github.com/Chris-Cullins/debug-run.git
 cd debug-run
 npm install
-
-# Run via tsx (development)
-npx tsx ./src/index.ts --help
-
-# Or build and run
-npm run build
-node dist/index.js --help
+npx tsx ./src/index.ts --help  # run from source
 ```
 
 ## Quick Start
@@ -43,13 +64,13 @@ node dist/index.js --help
 ### List available adapters
 
 ```bash
-npx tsx ./src/index.ts list-adapters
+npx debug-run list-adapters
 ```
 
 ### Debug a .NET application
 
 ```bash
-npx tsx ./src/index.ts ./bin/Debug/net8.0/MyApp.dll \
+npx debug-run ./bin/Debug/net8.0/MyApp.dll \
   -a dotnet \
   -b "src/OrderService.cs:45" \
   --pretty
@@ -58,7 +79,7 @@ npx tsx ./src/index.ts ./bin/Debug/net8.0/MyApp.dll \
 ### Debug Python
 
 ```bash
-npx tsx ./src/index.ts ./main.py \
+npx debug-run ./main.py \
   -a python \
   -b "processor.py:123" \
   -e "data.count" \
@@ -68,7 +89,7 @@ npx tsx ./src/index.ts ./main.py \
 ### Debug Node.js
 
 ```bash
-npx tsx ./src/index.ts ./dist/index.js \
+npx debug-run ./dist/index.js \
   -a node \
   -b "src/handler.ts:30" \
   --pretty
@@ -182,7 +203,7 @@ debug-run outputs newline-delimited JSON (NDJSON) events:
 ### Checking adapter status
 
 ```bash
-$ npx tsx ./src/index.ts list-adapters
+$ npx debug-run list-adapters
 
 Available debug adapters:
 
@@ -208,7 +229,7 @@ Available debug adapters:
 ### Investigate a test failure
 
 ```bash
-npx tsx ./src/index.ts ./bin/Debug/net8.0/TestApp.dll \
+npx debug-run ./bin/Debug/net8.0/TestApp.dll \
   -a dotnet \
   -b "src/InventoryService.cs:34" \
   -e "requestedQuantity" \
@@ -219,7 +240,7 @@ npx tsx ./src/index.ts ./bin/Debug/net8.0/TestApp.dll \
 ### Step through code
 
 ```bash
-npx tsx ./src/index.ts ./app.dll \
+npx debug-run ./app.dll \
   -a dotnet \
   -b "src/PricingService.cs:45" \
   --steps 10 \
@@ -230,7 +251,7 @@ npx tsx ./src/index.ts ./app.dll \
 ### Break on exceptions
 
 ```bash
-npx tsx ./src/index.ts ./app.dll \
+npx debug-run ./app.dll \
   -a dotnet \
   --break-on-exception "all" \
   --pretty
@@ -239,7 +260,7 @@ npx tsx ./src/index.ts ./app.dll \
 ### Conditional breakpoint
 
 ```bash
-npx tsx ./src/index.ts ./app.dll \
+npx debug-run ./app.dll \
   -a dotnet \
   -b "src/OrderService.cs:67?order.Total > 1000" \
   --pretty
@@ -250,7 +271,7 @@ npx tsx ./src/index.ts ./app.dll \
 Declare invariants that must remain true. The debugger halts immediately when any assertion fails:
 
 ```bash
-npx tsx ./src/index.ts ./app.dll \
+npx debug-run ./app.dll \
   -a dotnet \
   -b "src/OrderService.cs:45" \
   --assert "order.Total >= 0" \
@@ -272,7 +293,7 @@ Assertions are checked at breakpoints, during stepping, and during trace mode.
 Automatically step through code after hitting a breakpoint:
 
 ```bash
-npx tsx ./src/index.ts ./app.dll \
+npx debug-run ./app.dll \
   -a dotnet \
   -b "src/OrderService.cs:45" \
   --trace \
@@ -295,7 +316,7 @@ import subprocess
 import json
 
 result = subprocess.run([
-    "npx", "tsx", "./src/index.ts",
+    "npx", "debug-run",
     "./bin/Debug/net8.0/MyApp.dll",
     "-a", "dotnet",
     "-b", "src/Service.cs:45",
@@ -316,7 +337,7 @@ for line in result.stdout.strip().split('\n'):
 # Install dependencies
 npm install
 
-# Run in development mode
+# Run from source
 npx tsx ./src/index.ts [args...]
 
 # Type check

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "debug-run",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "CLI tool enabling AI agents to programmatically debug code via DAP",
   "type": "module",
   "main": "dist/index.cjs",