agent-dbg 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3:*)",
+      "Bash(npx tsx:*)",
+      "Bash(bun run build:*)",
+      "Bash(timeout 15 ./dist/ndbg launch tsx:*)",
+      "Bash(echo:*)",
+      "Bash(timeout:*)",
+      "Bash(./dist/ndbg stop:*)",
+      "Bash(npm install:*)",
+      "Bash(tsx:*)",
+      "Bash(./dist/ndbg state:*)",
+      "Bash(./dist/ndbg:*)",
+      "Bash(bun test:*)",
+      "Bash(bun:*)",
+      "Bash(grep:*)",
+      "Bash(npm view:*)"
+    ]
+  }
+}

package/.claude/skills/ndbg-debugger/ndbg-debugger/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: ndbg-debugger
+description: >
+  Debug Node.js/TypeScript/JavaScript applications using the ndbg CLI debugger.
+  Use when: (1) investigating runtime bugs by stepping through code, (2) inspecting
+  variable values at specific execution points, (3) setting breakpoints and conditional
+  breakpoints, (4) evaluating expressions in a paused context, (5) hot-patching code
+  without restarting, (6) debugging test failures by attaching to a running process,
+  (7) any task where understanding runtime behavior requires a debugger.
+  Triggers: "debug this", "set a breakpoint", "step through", "inspect variables",
+  "why is this value wrong", "trace execution", "attach debugger", "runtime error".
+---
+
+# ndbg Debugger
+
+`ndbg` is a CLI debugger for Node.js wrapping the V8 Inspector (CDP). It uses short `@refs` for all entities -- use them instead of long IDs.
+
+## Core Debug Loop
+
+```bash
+# 1. Launch with breakpoint at first line
+ndbg launch --brk node app.js
+
+# 2. Set breakpoints at suspicious locations
+ndbg break src/handler.ts:42
+ndbg break src/utils.ts:15 --condition "count > 10"
+
+# 3. Run to breakpoint
+ndbg continue
+
+# 4. Inspect state (shows location, source, locals, stack)
+ndbg state
+
+# 5. Drill into values
+ndbg props @v1              # expand object
+ndbg props @v1 --depth 3    # expand nested 3 levels
+ndbg eval "items.filter(x => x.active)"
+
+# 6. Fix and verify
+ndbg set count 0            # change variable
+ndbg hotpatch src/utils.js  # live-edit (reads file from disk)
+ndbg continue               # verify fix
+```
+
+## Debugging Strategies
+
+### Bug investigation -- narrow down with breakpoints
+```bash
+ndbg launch --brk node app.js
+ndbg break src/api.ts:50                    # suspect line
+ndbg break src/api.ts:60 --condition "!user" # conditional
+ndbg continue
+ndbg vars                                    # check locals
+ndbg eval "JSON.stringify(req.body)"         # inspect deeply
+ndbg step over                               # advance one line
+ndbg state                                   # see new state
+```
+
+### Attach to running/test process
+```bash
+# Start node with inspector
+node --inspect app.js
+# Or attach by PID
+ndbg attach 12345
+ndbg state
+```
+
+### Trace execution flow with logpoints (no pause)
+```bash
+ndbg logpoint src/auth.ts:20 "login attempt: ${username}"
+ndbg logpoint src/auth.ts:45 "auth result: ${result}"
+ndbg continue
+ndbg console    # see logged output
+```
+
+### Exception debugging
+```bash
+ndbg catch uncaught          # pause on uncaught exceptions
+ndbg continue                # runs until exception
+ndbg state                   # see where it threw
+ndbg eval "err.message"      # inspect the error
+ndbg stack                   # full call stack
+```
+
+### TypeScript source map support
+ndbg automatically resolves `.ts` paths via source maps. Set breakpoints using `.ts` paths, see `.ts` source in output. Use `--generated` to see compiled `.js` if needed.
+
+## Ref System
+
+Every output assigns short refs. Use them everywhere:
+- `@v1..@vN` -- variables: `ndbg props @v1`, `ndbg set @v2 true`
+- `@f0..@fN` -- stack frames: `ndbg eval --frame @f1 "this"`
+- `BP#1..N` -- breakpoints: `ndbg break-rm BP#1`, `ndbg break-toggle BP#1`
+- `LP#1..N` -- logpoints: `ndbg break-rm LP#1`
+
+Refs `@v`/`@f` reset on each pause. `BP#`/`LP#` persist until removed.
+
+## Key Flags
+
+- `--json` -- machine-readable JSON output on any command
+- `--session NAME` -- target a specific session (default: "default")
+- `--generated` -- bypass source maps, show compiled JS (on state/source/stack)
+
+## Command Reference
+
+See [references/commands.md](references/commands.md) for full command details and options.
+
+## Tips
+
+- `ndbg state` after stepping always shows location + source + locals -- usually enough context
+- `ndbg state -c` for source only, `-v` for vars only, `-s` for stack only -- save tokens
+- `ndbg eval` supports `await` -- useful for async inspection
+- `ndbg blackbox "node_modules/**"` -- skip stepping into dependencies
+- `ndbg hotpatch file` reads the file from disk -- edit the file first, then hotpatch
+- Execution commands (`continue`, `step`, `pause`, `run-to`) auto-return status
+- `ndbg stop` kills the debugged process and daemon

package/.claude/skills/ndbg-debugger/ndbg-debugger/references/commands.md

@@ -0,0 +1,173 @@
+# ndbg Command Reference
+
+## Table of Contents
+- [Session](#session)
+- [Execution](#execution)
+- [Inspection](#inspection)
+- [Breakpoints](#breakpoints)
+- [Mutation](#mutation)
+- [Blackboxing](#blackboxing)
+- [Source Maps](#source-maps)
+- [Global Flags](#global-flags)
+
+## Session
+
+```bash
+ndbg launch [--brk] <command...>     # Start + attach debugger (--brk pauses at first line)
+ndbg attach <pid|ws-url|port>        # Attach to running process
+ndbg stop                            # Kill process + daemon
+ndbg sessions [--cleanup]            # List active sessions
+ndbg status                          # Session info (pid, state, pause location)
+```
+
+## Execution
+
+All execution commands automatically return session status (state + pause info).
+
+```bash
+ndbg continue                        # Resume to next breakpoint or completion
+ndbg step [over|into|out]            # Step one statement (default: over)
+ndbg run-to <file>:<line>            # Continue to specific location
+ndbg pause                           # Interrupt running process
+ndbg restart-frame [@fN]             # Re-execute frame from beginning
+```
+
+## Inspection
+
+### state -- composite snapshot
+```bash
+ndbg state                           # Full snapshot: location, source, locals, stack, breakpoints
+ndbg state -v                        # Locals only
+ndbg state -s                        # Stack only
+ndbg state -c                        # Source code only
+ndbg state -b                        # Breakpoints only
+ndbg state --depth 3                 # Expand object values to depth 3
+ndbg state --lines 10                # Show 10 lines of source context
+ndbg state --frame @f1               # Inspect a different stack frame
+ndbg state --all-scopes              # Include closure scope variables
+ndbg state --compact                 # Compact output
+ndbg state --generated               # Show compiled JS paths instead of TS
+```
+
+### vars -- local variables
+```bash
+ndbg vars                            # All locals in current frame
+ndbg vars name1 name2                # Filter specific variables
+ndbg vars --frame @f1                # Variables from a different frame
+ndbg vars --all-scopes               # Include closure scope
+```
+
+### stack -- call stack
+```bash
+ndbg stack                           # Full call stack
+ndbg stack --async-depth 5           # Include async frames
+ndbg stack --generated               # Show compiled JS paths
+```
+
+### eval -- evaluate expression
+```bash
+ndbg eval <expression>               # Evaluate in current frame
+ndbg eval "await fetchUser(id)"      # Await supported
+ndbg eval --frame @f1 "this"         # Evaluate in different frame
+ndbg eval --silent "setup()"         # No output (side effects only)
+ndbg eval --side-effect-free "x + 1" # Abort if side effects detected
+ndbg eval --timeout 5000 "slowFn()"  # Custom timeout in ms
+```
+
+### props -- expand object
+```bash
+ndbg props @v1                       # Expand object properties
+ndbg props @v1 --depth 3             # Nested expansion
+ndbg props @v1 --own                 # Own properties only
+ndbg props @v1 --private             # Include private fields
+ndbg props @v1 --internal            # Include internal slots
+```
+
+### source -- view source code
+```bash
+ndbg source                          # Source around current line
+ndbg source --lines 20               # 20 lines of context
+ndbg source --file src/app.ts        # Source of a specific file
+ndbg source --all                    # Entire file
+ndbg source --generated              # Show compiled JS
+```
+
+### Other inspection
+```bash
+ndbg search "query"                  # Search loaded scripts
+ndbg search "pattern" --regex        # Regex search
+ndbg search "text" --case-sensitive  # Case-sensitive search
+ndbg search "text" --file <id>       # Search in specific script
+ndbg scripts                         # List loaded scripts
+ndbg scripts --filter "src/"         # Filter by pattern
+ndbg console                         # Show console output
+ndbg console --since 5               # Last 5 messages
+ndbg console --level error           # Filter by level
+ndbg console --clear                 # Clear console buffer
+ndbg exceptions                      # Show captured exceptions
+ndbg exceptions --since 3            # Last 3 exceptions
+```
+
+## Breakpoints
+
+```bash
+ndbg break <file>:<line>             # Set breakpoint
+ndbg break src/app.ts:42 --condition "x > 10"  # Conditional
+ndbg break src/app.ts:42 --hit-count 5         # Break on Nth hit
+ndbg break src/app.ts:42 --continue            # Log but don't pause
+ndbg break --pattern "handler":15              # Regex URL match
+ndbg break-rm BP#1                   # Remove specific breakpoint
+ndbg break-rm all                    # Remove all breakpoints
+ndbg break-ls                        # List all breakpoints
+ndbg break-toggle BP#1               # Disable/enable one breakpoint
+ndbg break-toggle all                # Disable/enable all
+ndbg breakable src/app.ts:10-50      # List valid breakpoint locations
+ndbg logpoint src/app.ts:20 "x=${x}" # Log without pausing
+ndbg logpoint src/app.ts:20 "x=${x}" --condition "x > 0"
+ndbg catch all                       # Pause on all exceptions
+ndbg catch uncaught                  # Pause on uncaught only
+ndbg catch none                      # Don't pause on exceptions
+```
+
+## Mutation
+
+```bash
+ndbg set <@ref|name> <value>         # Change variable value
+ndbg set count 0                     # By name
+ndbg set @v2 true                    # By ref
+ndbg set-return "newValue"           # Change return value (at return point)
+ndbg hotpatch <file>                 # Live-edit script from disk
+ndbg hotpatch <file> --dry-run       # Preview without applying
+```
+
+## Blackboxing
+
+Skip stepping into matching scripts (useful for node_modules).
+
+```bash
+ndbg blackbox "node_modules/**"      # Add pattern
+ndbg blackbox "lib/**" "vendor/**"   # Multiple patterns
+ndbg blackbox-ls                     # List patterns
+ndbg blackbox-rm "node_modules/**"   # Remove specific pattern
+ndbg blackbox-rm all                 # Remove all patterns
+```
+
+## Source Maps
+
+ndbg auto-detects source maps from `Debugger.scriptParsed` events. TypeScript `.ts` paths work transparently for breakpoints and display.
+
+```bash
+ndbg sourcemap                       # List all loaded source maps
+ndbg sourcemap src/app.ts            # Info for specific file
+ndbg sourcemap --disable             # Disable resolution globally
+```
+
+## Global Flags
+
+```bash
+--session NAME                       # Target session (default: "default")
+--json                               # JSON output
+--color                              # Enable ANSI colors
+--help-agent                         # LLM-optimized reference card
+--help                               # Human help
+```

package/CLAUDE.md

@@ -0,0 +1,43 @@
+# ndbg — Node.js Debugger CLI for AI Agents
+
+## Project Overview
+CLI debugger for Node.js built with Bun, optimized for AI agent consumption.
+See `ndbg-spec.md` for full specification, `PROGRESS.md` for implementation status.
+
+## Tech Stack
+- **Runtime**: Bun (compiled to standalone binary via `bun build --compile`)
+- **Language**: TypeScript (strict mode)
+- **Linting/Formatting**: Biome
+- **Testing**: bun:test
+- **Validation**: Zod v4 (mini)
+- **Dependencies**: Minimal — leverage Bun built-ins (WebSocket, test runner, file I/O)
+
+## Project Structure
+```
+src/
+  cli/          # CLI argument parsing, command routing
+  daemon/       # Background daemon process, Unix socket server
+  cdp/          # Chrome DevTools Protocol WebSocket client
+  refs/         # @ref system (mapping short refs to V8 IDs)
+  formatter/    # Output formatting (variables, source, stack traces)
+  commands/     # Command implementations (break, step, eval, etc.)
+  protocol/     # CLI-to-daemon JSON protocol types
+tests/
+  unit/         # Unit tests
+  integration/  # Integration tests
+  fixtures/     # Test fixture scripts
+```
+
+## Commands
+- `bun run dev` — run in development
+- `bun test` — run all tests
+- `bun run build` — compile standalone binary
+- `bun run lint` — lint with biome
+- `bun run format` — format with biome
+
+## Guidelines
+- Use Bun APIs over Node.js equivalents (WebSocket, Bun.serve, Bun.$, etc.)
+- No ANSI colors by default (token efficiency for AI agents)
+- Every error should suggest the next valid command
+- Keep output compact — one entity per line where possible
+- Use @refs for all inspectable entities in output

package/PROGRESS.md

@@ -0,0 +1,261 @@
+# ndbg Development Progress
+
+> Status legend: `[ ]` Not started | `[~]` In progress | `[x]` Done | `[-]` Blocked
+
+---
+
+## Phase 0 — Project Setup
+
+- [x] Initialize Bun project with TypeScript `bun init`
+- [x] Set up project structure (src/, tests/, fixtures/)
+- [x] Configure `bun build --compile` for standalone binary
+- [x] Set up test framework (bun:test)
+- [x] Set up CLI argument parser (command + subcommands + flags)
+- [x] Configure linting / formatting
+
+---
+
+## Phase 1 — Core Infrastructure
+
+### 1.1 Daemon Architecture
+
+- [x] Daemon process spawning and backgrounding
+- [x] Unix socket server (listen on `$XDG_RUNTIME_DIR/ndbg/<session>.sock`)
+- [x] CLI-to-daemon request/response protocol (newline-delimited JSON)
+- [x] Daemon auto-termination on process exit
+- [x] Daemon idle timeout (configurable, default 300s)
+- [x] Lock file to prevent duplicate daemons per session
+- [x] Crash recovery: detect dead socket, suggest `ndbg attach`
+
+### 1.2 CDP (Chrome DevTools Protocol) Connection
+
+- [x] WebSocket client to V8 inspector (`ws://127.0.0.1:<port>`)
+- [x] CDP message send/receive with request ID tracking
+- [x] CDP event subscription and dispatching
+- [x] Enable required CDP domains (Debugger, Runtime, Profiler, HeapProfiler)
+- [x] `Runtime.runIfWaitingForDebugger` on attach
+
+### 1.3 @ref System
+
+- [x] Ref table data structure (map short refs to V8 remote object IDs)
+- [x] `@v` refs — variable/value refs (regenerated on each pause)
+- [x] `@f` refs — stack frame refs (regenerated on each pause)
+- [x] `@o` refs — expanded object refs (append-only, persist across pauses)
+- [x] `BP#` refs — breakpoint refs (persist until removed)
+- [x] `LP#` refs — logpoint refs (persist until removed)
+- [x] `HS#` refs — heap snapshot refs (persist until session ends)
+- [x] Ref resolution: resolve `@ref` in CLI arguments to V8 IDs
+- [x] `ndbg gc-refs` — clear accumulated `@o` refs
+
+### 1.4 Output Formatter
+
+- [x] Variable formatting (Objects, Arrays, Functions, Promises, Errors, Buffers, Map, Set)
+- [x] Smart truncation (~80 chars per value)
+- [x] Source code display (line numbers, `→` current line, `●` breakpoint markers)
+- [x] Stack trace display (`@f` refs, async gap markers, blackboxed frame collapsing)
+- [x] Error output with actionable suggestions (`→ Try: ...`)
+- [x] `--color` flag for ANSI terminal colors
+- [x] `--json` flag for JSON output mode
+- [x] Truncation hints (`... (ndbg props @oN for more)`)
+
+---
+
+## Phase 2 — Session Management
+
+- [x] `ndbg launch [--brk] [--session NAME] <command...>` — spawn + attach
+- [x] `ndbg launch --brk` — spawn with `--inspect-brk`, pause on first line
+- [x] `ndbg launch --port PORT` — use specific inspector port
+- [x] `ndbg launch --timeout SECS` — configure daemon idle timeout
+- [x] `ndbg attach <pid | ws-url | port>` — attach to running process
+- [x] `ndbg stop [--session NAME]` — kill process + daemon
+- [x] `ndbg sessions` — list active sessions (PID, status, name)
+- [x] `ndbg sessions --cleanup` — kill orphaned daemons
+- [x] `ndbg status` — session info (PID, pause state, breakpoints, memory, uptime)
+- [x] Multi-session support (`--session NAME` on any command)
+
+---
+
+## Phase 3 — State Snapshot
+
+- [x] `ndbg state` — full state snapshot (source + locals + stack + breakpoints)
+- [x] State filtering: `-v` / `--vars` (locals only)
+- [x] State filtering: `-s` / `--stack` (stack trace only)
+- [x] State filtering: `-b` / `--breakpoints` (breakpoints/logpoints only)
+- [x] State filtering: `-c` / `--code` (source context only)
+- [x] `--compact` flag — one-line-per-section summary
+- [x] `--depth N` — object expansion depth (default: 1)
+- [x] `--lines N` — source context lines (default: 3)
+- [x] `--frame @fN` — state from perspective of frame N
+- [x] `--all-scopes` — include closure and global scope
+- [x] `--json` — full state as JSON
+- [x] Auto-state return after execution commands (continue, step, etc.)
+
+---
+
+## Phase 4 — Breakpoints
+
+- [x] `ndbg break <file>:<line>` — set breakpoint (`Debugger.setBreakpointByUrl`)
+- [x] `ndbg break --condition <expr>` — conditional breakpoint
+- [x] `ndbg break --hit-count <n>` — pause on Nth hit
+- [x] `ndbg break --continue` — set breakpoint + immediately continue
+- [ ] `ndbg break --log <template>` — shortcut to logpoint
+- [x] `ndbg break --pattern <urlRegex>:<line>` — regex pattern breakpoint
+- [ ] `ndbg break-fn <expr>` — breakpoint on function call
+- [ ] `ndbg break-on-load [--sourcemap]` — break on new script parse
+- [x] `ndbg break-rm <BP# | LP# | all>` — remove breakpoints
+- [x] `ndbg break-ls` — list all breakpoints/logpoints with locations and conditions
+- [x] `ndbg break-toggle [BP# | all]` — enable/disable breakpoints
+- [x] `ndbg breakable <file>:<start>-<end>` — list valid breakpoint locations
+- [x] `ndbg logpoint <file>:<line> <template>` — set logpoint (no pause)
+- [ ] Logpoint `--max <n>` — auto-pause after N emissions (default: 100)
+- [x] Logpoint `--condition <expr>` — conditional logpoint
+- [x] `ndbg catch [all | uncaught | caught | none]` — pause-on-exception config
+
+---
+
+## Phase 5 — Execution Control
+
+- [x] `ndbg continue` — resume execution (+ auto-state return)
+- [x] `ndbg step over` — step one statement over (default)
+- [x] `ndbg step into` — step into function call
+- [x] `ndbg step out` — step out of current function
+- [ ] `ndbg step into --break-on-async` — pause on first async task
+- [ ] `ndbg step --skip <pattern>` — inline blackboxing during step
+- [x] `ndbg run-to <file>:<line>` — continue to location (no persistent breakpoint)
+- [x] `ndbg restart-frame [@fN]` — re-execute frame from beginning
+- [x] `ndbg pause` — interrupt running process
+- [ ] `ndbg kill-execution` — terminate JS execution, keep session alive
+
+---
+
+## Phase 6 — Inspection
+
+- [x] `ndbg vars [name1, name2, ...]` — show local variables with `@v` refs
+- [x] `ndbg stack [--async-depth N]` — show call stack with `@f` refs
+- [x] `ndbg eval <expression>` — evaluate in current frame context
+- [x] `ndbg eval` with `await` support (CDP `awaitPromise`)
+- [x] `ndbg eval` with `@ref` interpolation
+- [x] `ndbg eval --frame @fN` — evaluate in specific frame
+- [x] `ndbg eval --silent` — suppress exception reporting
+- [x] `ndbg eval --timeout MS` — kill after N ms (default: 5000)
+- [x] `ndbg eval --side-effect-free` — throw on side effects
+- [x] `ndbg props <@ref>` — expand object properties (returns `@o` refs)
+- [x] `ndbg props --own` — only own properties
+- [x] `ndbg props --depth N` — recursive expansion
+- [x] `ndbg props --private` — include private fields
+- [x] `ndbg props --internal` — V8 internal properties (`[[PromiseState]]`)
+- [ ] `ndbg instances <expression>` — find all live instances of prototype
+- [ ] `ndbg globals` — list global let/const/class declarations
+- [x] `ndbg source [--lines N] [--file <path>] [--all]` — show source code
+- [x] `ndbg search <query> [--regex] [--case-sensitive] [--file <id>]` — search scripts
+- [x] `ndbg scripts [--filter <pattern>]` — list loaded scripts
+- [x] `ndbg console [--follow] [--since N] [--level] [--clear]` — console output
+- [x] `ndbg exceptions [--follow] [--since N]` — captured exceptions
+
+---
+
+## Phase 7 — Mutation
+
+- [x] `ndbg set <@vRef | varName> <value>` — change variable value
+- [x] `ndbg set-return <value>` — change return value (at return point)
+- [x] `ndbg hotpatch <file>` — live-edit script source (`Debugger.setScriptSource`)
+- [x] `ndbg hotpatch --dry-run` — check without applying
+
+---
+
+## Phase 8 — Blackboxing
+
+- [x] `ndbg blackbox <pattern...>` — skip stepping into matching scripts
+- [x] `ndbg blackbox-ls` — list current patterns
+- [x] `ndbg blackbox-rm <pattern | all>` — remove patterns
+
+---
+
+## Phase 9 — Source Map Support
+
+- [x] Fetch and cache source maps from `Debugger.scriptParsed` events
+- [x] Resolve `.ts` locations to `.js` for breakpoint setting
+- [x] Display source-mapped paths in all output (stack traces, source, breakpoints)
+- [x] Show original source (TypeScript) in `ndbg source`
+- [x] Graceful fallback when no source map exists
+- [x] `ndbg sourcemap <file>` — show source map info
+- [x] `ndbg sourcemap --disable` — disable resolution globally
+- [x] `--generated` flag — bypass source map resolution per-command (state, source, stack)
+
+---
+
+## Phase 10 — CPU Profiling
+
+- [ ] `ndbg cpu start [--interval <us>]` — start V8 CPU profiler
+- [ ] `ndbg cpu stop [--top N]` — stop profiling + report (function, file:line, self%, total%, deopt)
+- [ ] Save full profile to file for external tools
+- [ ] `ndbg coverage start [--detailed]` — start code coverage
+- [ ] `ndbg coverage stop [--file] [--uncovered]` — stop + report
+
+---
+
+## Phase 11 — Memory / Heap
+
+- [ ] `ndbg heap usage` — quick heap statistics
+- [ ] `ndbg heap snapshot [--tag <name>]` — full heap snapshot (assigns `HS#` ref)
+- [ ] `ndbg heap diff <HS#a> <HS#b> [--top N]` — compare snapshots
+- [ ] `ndbg heap sample start [--interval] [--include-gc]` — sampling profiler
+- [ ] `ndbg heap sample stop [--top N]` — stop sampling + report
+- [ ] `ndbg heap track start` — allocation tracking (timeline)
+- [ ] `ndbg heap track stop` — stop tracking + report
+- [ ] `ndbg heap inspect <heapObjectId>` — get runtime ref from snapshot node
+- [ ] `ndbg gc` — force garbage collection
+
+---
+
+## Phase 12 — Advanced / Utility
+
+- [ ] `ndbg inject-hook <name>` — create runtime binding (`__ndbg_<name>()`)
+- [ ] `ndbg hooks [--follow]` — view hook invocations
+- [ ] `ndbg contexts` — list V8 execution contexts
+- [ ] `ndbg async-depth <N>` — set async call stack depth
+- [ ] `ndbg config [key] [value]` — get/set daemon configuration
+- [ ] `ndbg gc-refs` — clear `@o` refs to free memory
+- [ ] `ndbg --help-agent` — compact LLM-optimized reference card
+
+---
+
+## Phase 13 — Distribution & Integration
+
+- [ ] `bun build --compile` producing standalone binaries (linux-x64, darwin-arm64, etc.)
+- [ ] npm package (`npx ndbg` support)
+- [ ] SKILL.md for Claude Code agent integration
+- [ ] `--help-agent` output matching spec reference card
+- [ ] GitHub releases with prebuilt binaries
+
+---
+
+## Phase 14 — Testing
+
+### Unit Tests
+
+- [ ] Ref system: creation, resolution, lifecycle, collision handling
+- [ ] Output formatters: variable formatting, truncation, source display
+- [ ] Source map resolution: .ts → .js mapping, inline source maps, missing maps
+- [ ] Command argument parsing
+
+### Integration Tests
+
+- [ ] Launch + attach + breakpoint + step + inspect + stop lifecycle
+- [ ] Conditional breakpoints with expression evaluation
+- [ ] Logpoint emission and flood throttling
+- [ ] Source map resolution end-to-end (TypeScript project)
+- [ ] Hotpatch: edit, verify, dry-run, blocked scenarios
+- [ ] Multi-session: two concurrent debug sessions
+- [ ] Heap snapshot, diff, sampling
+- [ ] CPU profiling and coverage collection
+- [ ] Daemon crash recovery and orphan cleanup
+
+### Agent Simulation Tests
+
+- [ ] Race condition debugging scenario (bash script)
+- [ ] Circular dependency tracing scenario
+- [ ] Memory leak detection scenario
+- [ ] Metric: total tool calls needed
+- [ ] Metric: total tokens in output
+- [ ] Metric: success rate vs MCP-based debuggers

package/README.md

@@ -0,0 +1,67 @@
+# ndbg
+
+Node.js debugger CLI built for AI agents. Fast, token-efficient, no fluff.
+
+**Why?** Agents waste tokens on print-debugging. A real debugger gives precise state inspection in minimal output — variables, stack, breakpoints — all via short `@ref` handles.
+
+## Install
+
+Requires [Bun](https://bun.sh).
+
+```bash
+bunx ndbg
+```
+
+## Setup
+
+```bash
+git clone <repo> && cd ndbg
+bun install
+bun run build    # -> dist/ndbg
+```
+
+## Usage
+
+```bash
+ndbg launch --brk node app.js
+# Session "default" started (pid 12345)
+# Paused at app.js:1:1
+
+ndbg break src/handler.ts:42
+# BP#1 src/handler.ts:42
+
+ndbg continue
+# Paused at src/handler.ts:42:5 (breakpoint)
+
+ndbg vars
+# @v1  x      42
+# @v2  name   "alice"
+# @v3  opts   {timeout: 3000}
+
+ndbg props @v3
+# @o1  timeout  3000
+
+ndbg eval "x + 1"
+# 43
+
+ndbg step over
+# Paused at src/handler.ts:43:5 (step)
+
+ndbg set @v1 100
+# @v1 changed to 100
+
+ndbg stop
+```
+
+## Commands
+
+| Category | Commands |
+|---|---|
+| Session | `launch`, `attach`, `stop`, `status`, `sessions` |
+| Execution | `continue`, `step [over\|into\|out]`, `pause`, `run-to`, `restart-frame` |
+| Inspection | `state`, `vars`, `stack`, `eval`, `props`, `source`, `scripts`, `search`, `console`, `exceptions` |
+| Breakpoints | `break`, `break-rm`, `break-ls`, `break-toggle`, `breakable`, `logpoint`, `catch` |
+| Mutation | `set`, `set-return`, `hotpatch` |
+| Blackbox | `blackbox`, `blackbox-ls`, `blackbox-rm` |
+
+Run `ndbg --help` or `ndbg --help-agent` for the full reference.