debug-run 0.1.0 → 0.5.2

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/.prettierignore

@@ -0,0 +1,4 @@
+dist/
+node_modules/
+samples/
+*.md