agent-dbg 0.1.0 → 0.1.2

package/src/formatter/variables.ts

@@ -2,9 +2,22 @@ export interface Variable {
 	ref: string;
 	name: string;
 	value: string;
+	scope?: string;
 }
 
-export function formatVariables(vars: Variable[]): string {
+const SCOPE_LABELS: Record<string, string> = {
+	local: "Locals",
+	module: "Module",
+	closure: "Closure",
+	block: "Block",
+	catch: "Catch",
+	script: "Script",
+	eval: "Eval",
+	with: "With",
+	"wasm-expression-stack": "WASM Stack",
+};
+
+function formatGroup(vars: Variable[]): string {
 	if (vars.length === 0) return "";
 
 	const maxRefLen = Math.max(...vars.map((v) => v.ref.length));
@@ -18,3 +31,37 @@ export function formatVariables(vars: Variable[]): string {
 		})
 		.join("\n");
 }
+
+export function formatVariables(vars: Variable[]): string {
+	if (vars.length === 0) return "";
+
+	// Collect unique scopes in order of appearance
+	const scopeOrder: string[] = [];
+	const groups = new Map<string, Variable[]>();
+	for (const v of vars) {
+		const scope = v.scope ?? "local";
+		let group = groups.get(scope);
+		if (!group) {
+			group = [];
+			scopeOrder.push(scope);
+			groups.set(scope, group);
+		}
+		group.push(v);
+	}
+
+	// Single scope: no header needed
+	if (scopeOrder.length === 1) {
+		return formatGroup(vars);
+	}
+
+	// Multiple scopes: group with headers
+	const sections: string[] = [];
+	for (const scope of scopeOrder) {
+		const group = groups.get(scope);
+		if (!group || group.length === 0) continue;
+		const label = SCOPE_LABELS[scope] ?? scope;
+		sections.push(`${label}:\n${formatGroup(group)}`);
+	}
+
+	return sections.join("\n\n");
+}

package/src/main.ts

@@ -6,6 +6,7 @@ if (process.argv.includes("--daemon")) {
 	await import("./commands/launch.ts");
 	await import("./commands/attach.ts");
 	await import("./commands/stop.ts");
+	await import("./commands/restart.ts");
 	await import("./commands/sessions.ts");
 	await import("./commands/status.ts");
 	await import("./commands/state.ts");
@@ -37,6 +38,7 @@ if (process.argv.includes("--daemon")) {
 	await import("./commands/breakable.ts");
 	await import("./commands/restart-frame.ts");
 	await import("./commands/sourcemap.ts");
+	await import("./commands/logs.ts");
 	const { parseArgs, run } = await import("./cli/parser.ts");
 
 	const args = parseArgs(process.argv.slice(2));

package/src/protocol/messages.ts

@@ -254,6 +254,8 @@ const SourcemapRequest = z.object({
 
 const SourcemapDisableRequest = z.object({ cmd: z.literal("sourcemap-disable") });
 
+const RestartRequest = z.object({ cmd: z.literal("restart") });
+
 const StopRequest = z.object({ cmd: z.literal("stop") });
 
 // ── Union of all requests (discriminated on cmd) ───────────────────
@@ -291,6 +293,7 @@ export const DaemonRequestSchema = z.union([
 	BreakToggleRequest,
 	BreakableRequest,
 	RestartFrameRequest,
+	RestartRequest,
 	SourcemapRequest,
 	SourcemapDisableRequest,
 	StopRequest,

package/tests/fixtures/async-app.js

@@ -1,4 +1,4 @@
-// Test fixture with async patterns for ndbg integration tests
+// Test fixture with async patterns for agent-dbg integration tests
 // Launch with: node --inspect-brk tests/fixtures/async-app.js
 
 async function delay(ms) {

package/tests/fixtures/error-app.js

@@ -1,4 +1,4 @@
-// Test fixture with errors for ndbg integration tests
+// Test fixture with errors for agent-dbg integration tests
 // Launch with: node --inspect-brk tests/fixtures/error-app.js
 
 function riskyOperation(input) {

package/tests/fixtures/simple-app.js

@@ -1,4 +1,4 @@
-// Simple test fixture for ndbg integration tests
+// Simple test fixture for agent-dbg integration tests
 // Launch with: node --inspect-brk tests/fixtures/simple-app.js
 
 function greet(name) {

package/tests/fixtures/ts-app/src/app.ts

@@ -6,6 +6,10 @@ interface Person {
 
 function greet(person: Person): string {
 	const message: string = `Hello, ${person.name}! Age: ${person.age}`;
+	if (person.name === "Alice") {
+		const a = 1;
+		return "Hello, Alice!";
+	}
 	return message;
 }
 

package/tests/integration/state.test.ts

@@ -47,7 +47,7 @@ describe("buildState integration", () => {
 			expect(firstFrame?.line).toBeGreaterThan(0);
 
 			// Locals should be present (may be empty at entry point, but the array should exist)
-			expect(snapshot.locals).toBeDefined();
+			expect(snapshot.vars).toBeDefined();
 
 			// Breakpoint count should be present
 			expect(snapshot.breakpointCount).toBeDefined();
@@ -69,7 +69,7 @@ describe("buildState integration", () => {
 			expect(snapshot.status).toBe("running");
 			// When running, no source/locals/stack should be present
 			expect(snapshot.source).toBeUndefined();
-			expect(snapshot.locals).toBeUndefined();
+			expect(snapshot.vars).toBeUndefined();
 			expect(snapshot.stack).toBeUndefined();
 		} finally {
 			await session.stop();
@@ -88,7 +88,7 @@ describe("buildState integration", () => {
 
 			expect(snapshot.status).toBe("paused");
 			// Locals should be present
-			expect(snapshot.locals).toBeDefined();
+			expect(snapshot.vars).toBeDefined();
 			// Source and stack should NOT be present (filtered out)
 			expect(snapshot.source).toBeUndefined();
 			expect(snapshot.stack).toBeUndefined();
@@ -114,7 +114,7 @@ describe("buildState integration", () => {
 			expect(snapshot.stack?.length).toBeGreaterThan(0);
 			// Source, locals, and breakpoints should NOT be present (filtered out)
 			expect(snapshot.source).toBeUndefined();
-			expect(snapshot.locals).toBeUndefined();
+			expect(snapshot.vars).toBeUndefined();
 			expect(snapshot.breakpointCount).toBeUndefined();
 		} finally {
 			await session.stop();
@@ -136,7 +136,7 @@ describe("buildState integration", () => {
 			expect(snapshot.source).toBeDefined();
 			expect(snapshot.source?.lines.length).toBeGreaterThan(0);
 			// Locals, stack, and breakpoints should NOT be present (filtered out)
-			expect(snapshot.locals).toBeUndefined();
+			expect(snapshot.vars).toBeUndefined();
 			expect(snapshot.stack).toBeUndefined();
 			expect(snapshot.breakpointCount).toBeUndefined();
 		} finally {
@@ -161,8 +161,8 @@ describe("buildState integration", () => {
 			const snapshot = await session.buildState();
 
 			// Check that variable refs are assigned
-			if (snapshot.locals && snapshot.locals.length > 0) {
-				const firstLocal = snapshot.locals[0];
+			if (snapshot.vars && snapshot.vars.length > 0) {
+				const firstLocal = snapshot.vars[0];
 				expect(firstLocal?.ref).toMatch(/^@v\d+$/);
 				expect(firstLocal?.name).toBeDefined();
 				expect(firstLocal?.value).toBeDefined();

package/tests/unit/daemon.test.ts

@@ -10,7 +10,7 @@ import {
 import { DaemonServer } from "../../src/daemon/server.ts";
 
 // Use a short test directory to stay within macOS 104-char Unix socket path limit
-const TEST_SOCKET_DIR = `/tmp/ndbg-t${process.pid}`;
+const TEST_SOCKET_DIR = `/tmp/agent-dbg-t${process.pid}`;
 
 let originalEnv: string | undefined;
 let testCounter = 0;

package/tests/unit/formatter.test.ts

@@ -646,21 +646,25 @@ describe("formatError", () => {
 		const result = formatError(
 			"Cannot set breakpoint at src/queue/processor.ts:46 \u2014 no breakable location",
 			["Nearest valid lines: 45, 47"],
-			"ndbg break src/queue/processor.ts:47",
+			"agent-dbg break src/queue/processor.ts:47",
 		);
 		const lines = result.split("\n");
 		expect(lines).toHaveLength(3);
 		expect(lines[0]).toContain("\u2717");
 		expect(lines[1]).toBe("  Nearest valid lines: 45, 47");
-		expect(lines[2]).toBe("  \u2192 Try: ndbg break src/queue/processor.ts:47");
+		expect(lines[2]).toBe("  \u2192 Try: agent-dbg break src/queue/processor.ts:47");
 	});
 
 	test("formats error without details but with suggestion", () => {
-		const result = formatError("No active session", undefined, "ndbg launch --brk node app.js");
+		const result = formatError(
+			"No active session",
+			undefined,
+			"agent-dbg launch --brk node app.js",
+		);
 		const lines = result.split("\n");
 		expect(lines).toHaveLength(2);
 		expect(lines[0]).toBe("\u2717 No active session");
-		expect(lines[1]).toBe("  \u2192 Try: ndbg launch --brk node app.js");
+		expect(lines[1]).toBe("  \u2192 Try: agent-dbg launch --brk node app.js");
 	});
 });
 

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

@@ -1,116 +0,0 @@
----
-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

@@ -1,173 +0,0 @@
-# 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
-```