debug-toolkit 0.4.0 → 0.4.2
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/README.md +76 -0
- package/dist/index.js +0 -0
- package/package.json +7 -2
package/README.md
CHANGED
|
@@ -7,6 +7,82 @@ npx debug-toolkit demo # see it work (no AI needed)
|
|
|
7
7
|
npx debug-toolkit init # install in your project
|
|
8
8
|
```
|
|
9
9
|
|
|
10
|
+
## See It Work
|
|
11
|
+
|
|
12
|
+
Run `npx debug-toolkit demo` — creates a temp project with a real bug, walks through the full debug loop, no AI needed:
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
━━━ Step 1: debug_investigate ━━━
|
|
16
|
+
tool: debug_investigate
|
|
17
|
+
✓ Error type: TypeError — type
|
|
18
|
+
✓ Source: src/api.ts:8
|
|
19
|
+
>> 8 | const names = users.map(u => u.name); // BUG: users can be undefined
|
|
20
|
+
✓ Suggestion: Check for null/undefined values being accessed as objects
|
|
21
|
+
|
|
22
|
+
━━━ Step 2: debug_instrument ━━━
|
|
23
|
+
tool: debug_instrument
|
|
24
|
+
✓ Marker: DBG_001
|
|
25
|
+
✓ Hypothesis: "getUsers() returns undefined"
|
|
26
|
+
|
|
27
|
+
━━━ Step 3: debug_capture ━━━
|
|
28
|
+
tool: debug_capture
|
|
29
|
+
✓ Tagged output: [DBG_001] users = undefined
|
|
30
|
+
✓ Hypothesis confirmed → CONFIRMED
|
|
31
|
+
|
|
32
|
+
━━━ Step 5: debug_verify ━━━
|
|
33
|
+
✓ Exit code: 0 ✓ Errors: 0 ✓ Verdict: PASSED
|
|
34
|
+
|
|
35
|
+
━━━ Step 6: debug_cleanup ━━━
|
|
36
|
+
✓ Diagnosis saved to memory
|
|
37
|
+
✓ Causal chain: src/api.ts (error) → src/db.ts (cause)
|
|
38
|
+
|
|
39
|
+
━━━ Step 7: debug_recall (new session, same error) ━━━
|
|
40
|
+
✓ Past diagnosis found: 67% relevance
|
|
41
|
+
✓ Root cause: getUsers() returns undefined when db not connected
|
|
42
|
+
✓ Look at: src/db.ts (not src/api.ts)
|
|
43
|
+
→ Agent can skip investigation entirely and apply the known fix!
|
|
44
|
+
|
|
45
|
+
━━━ Step 8: debug_patterns ━━━
|
|
46
|
+
[WARNING] TypeError has occurred 4 times in src/api.ts
|
|
47
|
+
[WARNING] Possible regression: was fixed before but reappeared
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
<details>
|
|
51
|
+
<summary>Full demo output (value report)</summary>
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
┌─────────────────────────────────────────────────────────┐
|
|
55
|
+
│ VALUE REPORT │
|
|
56
|
+
└─────────────────────────────────────────────────────────┘
|
|
57
|
+
What the agent gathered in one debug session:
|
|
58
|
+
|
|
59
|
+
✓ Error classification TypeError, type error, severity high
|
|
60
|
+
✓ Source code at crash Exact line with surrounding context
|
|
61
|
+
✓ Git context Branch, commit, recent changes
|
|
62
|
+
✓ Runtime environment Node version, frameworks, env vars (redacted)
|
|
63
|
+
✓ Instrumented values users = undefined (tagged, linked to hypothesis)
|
|
64
|
+
✓ Verification result Exit code 0, 0 errors
|
|
65
|
+
✓ Causal chain error in api.ts caused by bug in db.ts
|
|
66
|
+
✓ Diagnosis persisted Searchable in future sessions
|
|
67
|
+
✓ Git SHA tagged Staleness detection for future recall
|
|
68
|
+
✓ Pattern detection Recurring errors, hot files, regressions
|
|
69
|
+
|
|
70
|
+
Data points collected: 17
|
|
71
|
+
Time elapsed: 2.9s
|
|
72
|
+
Memory entries: 4
|
|
73
|
+
Patterns detected: 5
|
|
74
|
+
|
|
75
|
+
Without debug-toolkit:
|
|
76
|
+
User pastes error → agent guesses fix → repeat 5-8 times
|
|
77
|
+
Typical: 8-12 conversation turns, no learning
|
|
78
|
+
|
|
79
|
+
With debug-toolkit:
|
|
80
|
+
investigate → instrument → capture → fix → verify → cleanup
|
|
81
|
+
1-2 turns with full context. Diagnosis saved for next time.
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
</details>
|
|
85
|
+
|
|
10
86
|
## The Problem
|
|
11
87
|
|
|
12
88
|
When an AI agent hits a bug, it reads code and guesses a fix. You run it, paste the error back, the agent guesses again. Repeat 5-8 times.
|
package/dist/index.js
CHANGED
|
File without changes
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "debug-toolkit",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.2",
|
|
4
4
|
"description": "Closed-loop debugging toolkit for AI coding agents",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -16,7 +16,12 @@
|
|
|
16
16
|
"hooks",
|
|
17
17
|
"SKILL.md"
|
|
18
18
|
],
|
|
19
|
-
"keywords": [
|
|
19
|
+
"keywords": [
|
|
20
|
+
"debugging",
|
|
21
|
+
"ai",
|
|
22
|
+
"mcp",
|
|
23
|
+
"developer-tools"
|
|
24
|
+
],
|
|
20
25
|
"license": "MIT",
|
|
21
26
|
"dependencies": {
|
|
22
27
|
"@modelcontextprotocol/sdk": "^1.12.1",
|