debug-that 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +132 -0
- package/dist/main.js +14188 -0
- package/package.json +56 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Theodo Group
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# debug-that
|
|
2
|
+
|
|
3
|
+
Debugger CLI built for AI agents. Fast, token-efficient, no fluff.
|
|
4
|
+
|
|
5
|
+
**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.
|
|
6
|
+
|
|
7
|
+
Inspired by Vercel's [agent-browser](https://github.com/vercel-labs/agent-browser) CLI — the same `@ref` concept, applied to debugging instead of browsing.
|
|
8
|
+
|
|
9
|
+
## Supported Runtimes & Languages
|
|
10
|
+
|
|
11
|
+
| Runtime | Language | Status | Protocol |
|
|
12
|
+
|---------|----------|--------|----------|
|
|
13
|
+
| Node.js | JavaScript | Supported | V8 Inspector (CDP) |
|
|
14
|
+
| Node.js + tsx/ts-node | TypeScript | Supported | V8 Inspector (CDP) + Source Maps |
|
|
15
|
+
| Bun | JavaScript / TypeScript | Supported | WebKit Inspector (JSC) |
|
|
16
|
+
| LLDB | C / C++ / Rust / Swift | Supported | DAP (Debug Adapter Protocol) |
|
|
17
|
+
| Deno | JavaScript / TypeScript | Planned | V8 Inspector (CDP) |
|
|
18
|
+
| Python (debugpy) | Python | Planned | DAP |
|
|
19
|
+
| Go (delve) | Go | Planned | DAP |
|
|
20
|
+
| Java (JDWP) | Java / Kotlin | Planned | DAP |
|
|
21
|
+
|
|
22
|
+
dbg auto-detects the runtime from the launch command and uses the appropriate protocol adapter. For native languages, use `--runtime lldb` to select the DAP adapter.
|
|
23
|
+
|
|
24
|
+
## Install
|
|
25
|
+
|
|
26
|
+
Requires [Bun](https://bun.sh).
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
bun install --global debug-that
|
|
30
|
+
npx skills add theodo-group/debug-that # Install Claude Code skill
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Example
|
|
34
|
+
```bash
|
|
35
|
+
> dbg launch --brk tsx src/app.ts
|
|
36
|
+
Session "default" started (pid 70445)
|
|
37
|
+
Paused at ./src/app.ts:0:1
|
|
38
|
+
|
|
39
|
+
> dbg break src/app.ts:19
|
|
40
|
+
BP#1 set at src/app.ts:19
|
|
41
|
+
|
|
42
|
+
> dbg continue
|
|
43
|
+
Paused at ./src/app.ts:19:21 (other)
|
|
44
|
+
|
|
45
|
+
Source:
|
|
46
|
+
16|
|
|
47
|
+
17|const alice: Person = { name: "Alice", age: 30 };
|
|
48
|
+
18|const greeting: string = greet(alice);
|
|
49
|
+
> 19|const sum: number = add(2, 3);
|
|
50
|
+
^
|
|
51
|
+
20|console.log(greeting);
|
|
52
|
+
21|console.log("Sum:", sum);
|
|
53
|
+
22|
|
|
54
|
+
|
|
55
|
+
Locals:
|
|
56
|
+
@v1 greet Function greet(person)
|
|
57
|
+
@v2 add Function add(a,b)
|
|
58
|
+
@v3 alice Object { name: "Alice", age: 30 }
|
|
59
|
+
@v4 greeting "Hello, Alice! Age: 30"
|
|
60
|
+
|
|
61
|
+
Stack:
|
|
62
|
+
@f0 (anonymous) ./src/app.ts:19:21
|
|
63
|
+
@f1 run node:internal/modules/esm/module_job:413:25
|
|
64
|
+
|
|
65
|
+
Breakpoints: 1 active
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Usage
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
# Node.js
|
|
72
|
+
dbg launch --brk node app.js
|
|
73
|
+
|
|
74
|
+
# TypeScript (via tsx)
|
|
75
|
+
dbg launch --brk tsx src/app.ts
|
|
76
|
+
|
|
77
|
+
# Bun
|
|
78
|
+
dbg launch --brk bun app.ts
|
|
79
|
+
|
|
80
|
+
# C/C++ (via LLDB)
|
|
81
|
+
dbg launch --brk --runtime lldb ./my_program
|
|
82
|
+
|
|
83
|
+
# Attach to a running process (any runtime with --inspect)
|
|
84
|
+
dbg attach 9229
|
|
85
|
+
|
|
86
|
+
# Debug loop
|
|
87
|
+
dbg break src/handler.ts:42
|
|
88
|
+
dbg continue
|
|
89
|
+
dbg vars
|
|
90
|
+
dbg props @v3
|
|
91
|
+
dbg eval "x + 1"
|
|
92
|
+
dbg step over
|
|
93
|
+
dbg set @v1 100
|
|
94
|
+
dbg hotpatch src/handler.ts # live-edit from disk (JS/TS only)
|
|
95
|
+
dbg stop
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## Commands
|
|
99
|
+
|
|
100
|
+
| Category | Commands |
|
|
101
|
+
|---|---|
|
|
102
|
+
| Session | `launch`, `attach`, `stop`, `status`, `sessions` |
|
|
103
|
+
| Execution | `continue`, `step [over\|into\|out]`, `pause`, `run-to`, `restart-frame` |
|
|
104
|
+
| Inspection | `state`, `vars`, `stack`, `eval`, `props`, `source`, `scripts`, `search`, `console`, `exceptions` |
|
|
105
|
+
| Breakpoints | `break`, `break-rm`, `break-ls`, `break-toggle`, `breakable`, `logpoint`, `catch`, `break-fn` (DAP only) |
|
|
106
|
+
| Mutation | `set`, `set-return`, `hotpatch` |
|
|
107
|
+
| Blackbox | `blackbox`, `blackbox-ls`, `blackbox-rm` |
|
|
108
|
+
|
|
109
|
+
Run `dbg --help` or `dbg --help-agent` for the full reference.
|
|
110
|
+
|
|
111
|
+
## Architecture
|
|
112
|
+
|
|
113
|
+
```
|
|
114
|
+
CLI (stateless) --> Unix socket IPC --> Daemon (per session)
|
|
115
|
+
|
|
|
116
|
+
DebugSession / DapSession
|
|
117
|
+
/ \
|
|
118
|
+
CDP path (JS) DAP path (native)
|
|
119
|
+
| |
|
|
120
|
+
RuntimeAdapter DapClient
|
|
121
|
+
/ \ (stdin/stdout)
|
|
122
|
+
NodeAdapter BunAdapter |
|
|
123
|
+
(CDP/V8) (WebKit/JSC) lldb-dap / etc.
|
|
124
|
+
\ /
|
|
125
|
+
CdpClient (WebSocket)
|
|
126
|
+
|
|
|
127
|
+
V8/JSC Inspector
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
The daemon manages two session types:
|
|
131
|
+
- **DebugSession** (CDP) — for JavaScript runtimes (Node.js, Bun). Uses `RuntimeAdapter` to handle protocol differences between V8 and JSC.
|
|
132
|
+
- **DapSession** (DAP) — for native debuggers (LLDB, etc.). Communicates with a debug adapter over stdin/stdout using the Debug Adapter Protocol.
|