agent-dbg 0.1.8 → 0.2.0

package/src/daemon/session.ts

@@ -6,8 +6,10 @@ import type { RemoteObject } from "../formatter/values.ts";
 import { formatValue } from "../formatter/values.ts";
 import { RefTable } from "../refs/ref-table.ts";
 import { SourceMapResolver } from "../sourcemap/resolver.ts";
+import { createAdapter } from "./adapters/index.ts";
 import { DaemonLogger } from "./logger.ts";
 import { ensureSocketDir, getDaemonLogPath, getLogPath } from "./paths.ts";
+import type { RuntimeAdapter } from "./runtime-adapter.ts";
 import {
 	addBlackbox as addBlackboxImpl,
 	listBlackbox as listBlackboxImpl,
@@ -134,7 +136,9 @@ export interface SessionStatus {
 	scriptCount: number;
 }
 
-const INSPECTOR_URL_REGEX = /Debugger listening on (wss?:\/\/\S+)/;
+// Node.js: "Debugger listening on ws://..."
+// Bun:     "  ws://localhost:PORT/ID" (on its own indented line)
+const INSPECTOR_URL_REGEX = /(?:Debugger listening on\s+)?(wss?:\/\/\S+)/;
 const INSPECTOR_TIMEOUT_MS = 5_000;
 
 export class DebugSession {
@@ -157,6 +161,7 @@ export class DebugSession {
 		new Map();
 	launchCommand: string[] | null = null;
 	launchOptions: { brk?: boolean; port?: number } | null = null;
+	adapter: RuntimeAdapter;
 	cdpLogger: CdpLogger;
 	daemonLogger: DaemonLogger;
 
@@ -165,6 +170,13 @@ export class DebugSession {
 		ensureSocketDir();
 		this.cdpLogger = new CdpLogger(getLogPath(session));
 		this.daemonLogger = options?.daemonLogger ?? new DaemonLogger(getDaemonLogPath(session));
+		// Default to NodeAdapter; overridden in launch() when command is known
+		this.adapter = createAdapter(["node"]);
+	}
+
+	/** Detected runtime name — delegates to the adapter */
+	get runtime(): "node" | "bun" | "unknown" {
+		return this.adapter.name;
 	}
 
 	// ── Session lifecycle ─────────────────────────────────────────────
@@ -183,15 +195,19 @@ export class DebugSession {
 
 		this.launchCommand = command;
 		this.launchOptions = options;
+		this.adapter = createAdapter(command);
 
 		const brk = options.brk ?? true;
 		const port = options.port ?? 0;
+
+		// Both Bun and Node.js support --inspect-brk (Bun also has --inspect-wait
+		// but --inspect-brk works better for our pause strategy)
 		const inspectFlag = brk ? `--inspect-brk=${port}` : `--inspect=${port}`;
 
 		// Build the args: inject inspect flag after the runtime (first element)
-		const runtime = command[0] as string;
+		const runtimeBin = command[0] as string;
 		const rest = command.slice(1);
-		const spawnArgs = [runtime, inspectFlag, ...rest];
+		const spawnArgs = [runtimeBin, inspectFlag, ...rest];
 
 		const proc = Bun.spawn(spawnArgs, {
 			stdin: "ignore",
@@ -236,7 +252,23 @@ export class DebugSession {
 		};
 
 		if (this.pauseInfo) {
-			result.pauseInfo = this.pauseInfo;
+			// Source-map translate for display
+			const translated = { ...this.pauseInfo };
+			if (translated.scriptId && translated.line !== undefined) {
+				const resolved = this.resolveOriginalLocation(
+					translated.scriptId,
+					translated.line + 1, // pauseInfo.line is 0-based
+					translated.column ?? 0,
+				);
+				if (resolved) {
+					translated.url = resolved.url;
+					translated.line = resolved.line - 1;
+					if (resolved.column !== undefined) {
+						translated.column = resolved.column - 1;
+					}
+				}
+			}
+			result.pauseInfo = translated;
 		}
 
 		return result;
@@ -652,21 +684,16 @@ export class DebugSession {
 			const settle = () => {
 				if (settled) return;
 				settled = true;
-				clearTimeout(timer);
 				clearInterval(pollTimer);
-				this.cdp?.off("Debugger.paused", handler);
 				this.onProcessExit = null;
 				resolve();
 			};
 
-			const timer = setTimeout(() => {
-				// Don't reject — the process is still running, just not paused yet
-				settle();
-			}, timeoutMs);
-
-			const handler = () => {
-				settle();
-			};
+			// Use waitFor for the event subscription + timeout
+			this.cdp
+				?.waitFor("Debugger.paused", { timeoutMs })
+				.then(() => settle())
+				.catch(() => settle()); // timeout — don't reject, just settle
 
 			// Poll as a fallback in case the event/callback is missed
 			// (e.g., process exits and monitorProcessExit runs before
@@ -677,7 +704,6 @@ export class DebugSession {
 				}
 			}, 100);
 
-			this.cdp?.on("Debugger.paused", handler);
 			// Also resolve if the process exits during execution
 			this.onProcessExit = settle;
 		});
@@ -724,32 +750,7 @@ export class DebugSession {
 	// ── Private helpers ───────────────────────────────────────────────
 
 	private async waitForBrkPause(): Promise<void> {
-		// Give the Debugger.paused event a moment to arrive (older Node.js)
-		if (!this.isPaused()) {
-			await Bun.sleep(100);
-		}
-		// On Node.js v24+, --inspect-brk does not emit Debugger.paused when the
-		// debugger connects after the process is already paused. We request an
-		// explicit pause and then signal Runtime.runIfWaitingForDebugger so the
-		// process starts execution and immediately hits our pause request.
-		if (!this.isPaused() && this.cdp) {
-			await this.cdp.send("Debugger.pause");
-			await this.cdp.send("Runtime.runIfWaitingForDebugger");
-			const deadline = Date.now() + 2_000;
-			while (!this.isPaused() && Date.now() < deadline) {
-				await Bun.sleep(50);
-			}
-		}
-		// On Node.js v24+, the initial --inspect-brk pause lands in an internal
-		// bootstrap module (node:internal/...) rather than the user script.
-		// Resume past internal pauses until we reach user code.
-		let skips = 0;
-		while (this.isPaused() && this.cdp && this.pauseInfo?.url?.startsWith("node:") && skips < 5) {
-			skips++;
-			const waiter = this.createPauseWaiter(5_000);
-			await this.cdp.send("Debugger.resume");
-			await waiter;
-		}
+		return this.adapter.waitForBrkPause(this);
 	}
 
 	private async connectCdp(wsUrl: string): Promise<void> {
@@ -761,13 +762,14 @@ export class DebugSession {
 		// Set up event handlers before enabling domains so we don't miss any events
 		this.setupCdpEventHandlers(cdp);
 
+		// Runtime-specific pre-enable hook (e.g. Bun needs Inspector.enable first)
+		await this.adapter.preEnable(cdp);
+
 		await cdp.enableDomains();
 
 		// Re-apply blackbox patterns if any exist
 		if (this.blackboxPatterns.length > 0) {
-			await cdp.send("Debugger.setBlackboxPatterns", {
-				patterns: this.blackboxPatterns,
-			});
+			await this.adapter.setBlackboxPatterns(cdp, this.blackboxPatterns);
 		}
 
 		// Update state to running if not already paused

package/src/formatter/source.ts

@@ -66,8 +66,12 @@ export function formatSource(lines: SourceLine[]): string {
 
 		// Add column indicator under current line
 		if (line.isCurrent && trimmed.caretOffset !== undefined && trimmed.caretOffset >= 0) {
-			const gutterWidth = numWidth + 4; // marker(2) + space(1) + numWidth + │(1)
-			result.push(`${" ".repeat(gutterWidth)}${" ".repeat(trimmed.caretOffset)}^`);
+			const gutter = " ".repeat(numWidth + 4); // marker(2) + space(1) + numWidth + │(1)
+			// Preserve tabs from source so ^ aligns in terminal
+			const indent = trimmed.text
+				.slice(0, trimmed.caretOffset)
+				.replace(/[^\t]/g, " ");
+			result.push(`${gutter}${indent}^`);
 		}
 	}
 	return result.join("\n");

package/tests/fixtures/bun-simple.js

@@ -0,0 +1,12 @@
+// Simple test fixture for Bun debugging
+debugger; // Should trigger a pause
+
+function greet(name) {
+	const message = `Hello, ${name}!`;
+	console.log(message);
+	return message;
+}
+
+const x = 42;
+const greeting = greet("Bun");
+console.log("x =", x);

package/tests/integration/bun-launch.test.ts

@@ -0,0 +1,135 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { DebugSession } from "../../src/daemon/session.ts";
+
+function waitForState(
+	session: DebugSession,
+	target: "paused" | "running" | "idle",
+	timeoutMs = 5_000,
+): Promise<void> {
+	return new Promise((resolve, reject) => {
+		if (session.state === target) return resolve();
+		const deadline = Date.now() + timeoutMs;
+		const timer = setInterval(() => {
+			if (session.state === target) {
+				clearInterval(timer);
+				resolve();
+			} else if (Date.now() > deadline) {
+				clearInterval(timer);
+				reject(new Error(`Timed out waiting for state=${target}, current=${session.state}`));
+			}
+		}, 50);
+	});
+}
+
+describe("Bun debugging", () => {
+	let session: DebugSession;
+
+	afterEach(async () => {
+		if (session) {
+			await session.stop().catch(() => {});
+		}
+	});
+
+	test("launches and pauses with --inspect-brk", async () => {
+		session = new DebugSession("bun-test-launch");
+		const result = await session.launch(["bun", "tests/fixtures/simple-app.js"], { brk: true });
+
+		expect(result.paused).toBe(true);
+		expect(result.pid).toBeGreaterThan(0);
+		expect(result.wsUrl).toContain("ws://");
+		expect(session.state).toBe("paused");
+		expect(session.runtime).toBe("bun");
+	});
+
+	test("detects bun runtime", async () => {
+		session = new DebugSession("bun-test-detect");
+		await session.launch(["bun", "tests/fixtures/simple-app.js"], { brk: true });
+		expect(session.runtime).toBe("bun");
+	});
+
+	test("state includes source-mapped location", async () => {
+		session = new DebugSession("bun-test-state");
+		await session.launch(["bun", "tests/fixtures/simple-app.js"], { brk: true });
+		await Bun.sleep(200); // Wait for source maps to load
+
+		const state = await session.buildState({ code: true, stack: true });
+		expect(state.status).toBe("paused");
+		// Source-mapped location should point to original source
+		expect(state.location?.url).toContain("simple-app.js");
+		expect(state.location?.line).toBe(38); // const counter = new Counter(10)
+		expect(state.source?.lines?.some((l) => l.current)).toBe(true);
+	});
+
+	test("eval works in paused context", async () => {
+		session = new DebugSession("bun-test-eval");
+		await session.launch(["bun", "tests/fixtures/simple-app.js"], { brk: true });
+
+		const r1 = await session.eval("1+1");
+		expect(r1.value).toBe("2");
+
+		const r2 = await session.eval("typeof Bun");
+		expect(r2.value).toBe('"object"');
+	});
+
+	test("breakpoint by scriptId hits", async () => {
+		session = new DebugSession("bun-test-bp");
+		await session.launch(["bun", "tests/fixtures/simple-app.js"], { brk: true });
+		await Bun.sleep(200); // Wait for source maps
+
+		// Set breakpoint inside greet function (original line 6)
+		const bp = await session.setBreakpoint("tests/fixtures/simple-app.js", 6);
+		expect(bp.ref).toMatch(/^BP#/);
+
+		// Continue — should hit breakpoint
+		await session.continue();
+		await waitForState(session, "paused");
+
+		expect(session.state).toBe("paused");
+		expect(session.pauseInfo?.reason).toBe("Breakpoint");
+	});
+
+	test("step over works", async () => {
+		session = new DebugSession("bun-test-step");
+		await session.launch(["bun", "tests/fixtures/simple-app.js"], { brk: true });
+
+		const initialLine = session.pauseInfo?.line;
+		await session.step("over");
+		expect(session.state).toBe("paused");
+		// Should have advanced at least one line
+		expect(session.pauseInfo?.line).not.toBe(initialLine);
+	});
+
+	test("step into enters function", async () => {
+		session = new DebugSession("bun-test-step-into");
+		await session.launch(["bun", "tests/fixtures/simple-app.js"], { brk: true });
+
+		// Step over to reach line 30 (greet call) then step into
+		await session.step("over"); // past const counter
+		await session.step("into"); // into greet("World")
+
+		expect(session.state).toBe("paused");
+		// Should be inside greet function
+		const stack = session.getStack({});
+		expect(stack[0]?.functionName).toBe("greet");
+	});
+
+	test("scripts list includes user script", async () => {
+		session = new DebugSession("bun-test-scripts");
+		await session.launch(["bun", "tests/fixtures/simple-app.js"], { brk: true });
+
+		const scripts = session.getScripts();
+		const userScript = scripts.find((s) => s.url.includes("simple-app.js"));
+		expect(userScript).toBeDefined();
+	});
+
+	test("continue resumes execution", async () => {
+		session = new DebugSession("bun-test-continue");
+		await session.launch(["bun", "tests/fixtures/simple-app.js"], { brk: true });
+
+		// Set a breakpoint so continue stops again (otherwise continue() waits for next pause indefinitely)
+		await session.setBreakpoint("tests/fixtures/simple-app.js", 6);
+		await session.continue();
+		expect(session.state).toBe("paused");
+		expect(session.pauseInfo?.reason).toBe("Breakpoint");
+	});
+});

package/tests/unit/cdp-client.test.ts

@@ -356,7 +356,7 @@ describe("CdpClient", () => {
 	});
 
 	describe("enableDomains", () => {
-		test("sends enable for all four domains", async () => {
+		test("sends enable for required and optional domains", async () => {
 			const c = client!;
 			const sentMethods: string[] = [];
 			const originalSend = c["ws"].send.bind(c["ws"]);
@@ -364,24 +364,52 @@ describe("CdpClient", () => {
 				if (typeof data === "string") {
 					const parsed = JSON.parse(data);
 					sentMethods.push(parsed.method);
+					// Auto-respond with success
+					setTimeout(() => {
+						c.handleMessage(JSON.stringify({ id: parsed.id, result: {} }));
+					}, 0);
 				}
 				return originalSend(data as string);
 			};
 
-			const promise = c.enableDomains();
-
-			// Respond to all four
-			c.handleMessage(JSON.stringify({ id: 1, result: {} }));
-			c.handleMessage(JSON.stringify({ id: 2, result: {} }));
-			c.handleMessage(JSON.stringify({ id: 3, result: {} }));
-			c.handleMessage(JSON.stringify({ id: 4, result: {} }));
-
-			await promise;
+			await c.enableDomains();
 
 			expect(sentMethods).toContain("Debugger.enable");
 			expect(sentMethods).toContain("Runtime.enable");
 			expect(sentMethods).toContain("Profiler.enable");
 			expect(sentMethods).toContain("HeapProfiler.enable");
+			expect(c.enabledDomains.has("Debugger")).toBe(true);
+			expect(c.enabledDomains.has("Runtime")).toBe(true);
+			expect(c.enabledDomains.has("Profiler")).toBe(true);
+			expect(c.enabledDomains.has("HeapProfiler")).toBe(true);
+		});
+
+		test("tracks which optional domains succeed", async () => {
+			const c = client!;
+			const originalSend = c["ws"].send.bind(c["ws"]);
+			c["ws"].send = (data: unknown) => {
+				if (typeof data === "string") {
+					const parsed = JSON.parse(data);
+					setTimeout(() => {
+						if (parsed.method === "Profiler.enable" || parsed.method === "HeapProfiler.enable") {
+							// Simulate Bun: optional domains fail
+							c.handleMessage(
+								JSON.stringify({ id: parsed.id, error: { code: -32601, message: "not found" } }),
+							);
+						} else {
+							c.handleMessage(JSON.stringify({ id: parsed.id, result: {} }));
+						}
+					}, 0);
+				}
+				return originalSend(data as string);
+			};
+
+			await c.enableDomains();
+
+			expect(c.enabledDomains.has("Debugger")).toBe(true);
+			expect(c.enabledDomains.has("Runtime")).toBe(true);
+			expect(c.enabledDomains.has("Profiler")).toBe(false);
+			expect(c.enabledDomains.has("HeapProfiler")).toBe(false);
 		});
 	});
 
@@ -406,6 +434,102 @@ describe("CdpClient", () => {
 		});
 	});
 
+	describe("waitFor", () => {
+		test("resolves with event params when event fires", async () => {
+			const c = client!;
+			const promise = c.waitFor("Debugger.paused", { timeoutMs: 1_000 });
+
+			c.handleMessage(
+				JSON.stringify({
+					method: "Debugger.paused",
+					params: { reason: "other", callFrames: [] },
+				}),
+			);
+
+			const result = await promise;
+			expect(result).toEqual({ reason: "other", callFrames: [] });
+		});
+
+		test("rejects on timeout", async () => {
+			const c = client!;
+			const promise = c.waitFor("Debugger.paused", { timeoutMs: 50 });
+
+			await expect(promise).rejects.toThrow("waitFor timed out: Debugger.paused");
+		});
+
+		test("filter skips non-matching events", async () => {
+			const c = client!;
+			const promise = c.waitFor("Debugger.paused", {
+				timeoutMs: 1_000,
+				filter: (p) => p.reason === "step",
+			});
+
+			// This one should be skipped
+			c.handleMessage(
+				JSON.stringify({
+					method: "Debugger.paused",
+					params: { reason: "other", callFrames: [] },
+				}),
+			);
+
+			// This one should match
+			c.handleMessage(
+				JSON.stringify({
+					method: "Debugger.paused",
+					params: { reason: "step", callFrames: [] },
+				}),
+			);
+
+			const result = await promise;
+			expect(result).toEqual({ reason: "step", callFrames: [] });
+		});
+
+		test("cleans up listener after resolving", async () => {
+			const c = client!;
+			const promise = c.waitFor("Debugger.paused", { timeoutMs: 1_000 });
+
+			c.handleMessage(
+				JSON.stringify({
+					method: "Debugger.paused",
+					params: { reason: "other", callFrames: [] },
+				}),
+			);
+
+			await promise;
+
+			// Listener should be cleaned up
+			expect(c["listeners"].get("Debugger.paused")?.size ?? 0).toBe(0);
+		});
+
+		test("cleans up listener after timeout", async () => {
+			const c = client!;
+			const promise = c.waitFor("Debugger.paused", { timeoutMs: 50 });
+
+			try {
+				await promise;
+			} catch {
+				// expected
+			}
+
+			expect(c["listeners"].get("Debugger.paused")?.size ?? 0).toBe(0);
+		});
+
+		test("works with untyped events", async () => {
+			const c = client!;
+			const promise = c.waitFor("Inspector.initialized", { timeoutMs: 1_000 });
+
+			c.handleMessage(
+				JSON.stringify({
+					method: "Inspector.initialized",
+					params: {},
+				}),
+			);
+
+			const result = await promise;
+			expect(result).toEqual({});
+		});
+	});
+
 	describe("malformed messages", () => {
 		test("invalid JSON is silently ignored", () => {
 			const c = client!;

package/tests/unit/jsc-client.test.ts

@@ -0,0 +1,165 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { CdpClient } from "../../src/cdp/client.ts";
+import { JscClient } from "../../src/cdp/jsc-client.ts";
+
+let server: ReturnType<typeof Bun.serve> | null = null;
+let cdp: CdpClient | null = null;
+let jsc: JscClient | null = null;
+
+async function createTestClient(): Promise<{ cdp: CdpClient; jsc: JscClient }> {
+	server = Bun.serve({
+		port: 0,
+		fetch(req, srv) {
+			if (srv.upgrade(req, { data: undefined })) {
+				return undefined;
+			}
+			return new Response("Not found", { status: 404 });
+		},
+		websocket: {
+			message() {},
+		},
+	});
+	const port = server.port;
+	const c = await CdpClient.connect(`ws://127.0.0.1:${port}`);
+	return { cdp: c, jsc: new JscClient(c) };
+}
+
+beforeEach(async () => {
+	const clients = await createTestClient();
+	cdp = clients.cdp;
+	jsc = clients.jsc;
+});
+
+afterEach(() => {
+	if (cdp?.connected) {
+		cdp.disconnect();
+	}
+	cdp = null;
+	jsc = null;
+	if (server) {
+		server.stop(true);
+		server = null;
+	}
+});
+
+describe("JscClient", () => {
+	test("send routes through cdp.sendRaw", async () => {
+		const j = jsc!;
+		const c = cdp!;
+
+		const sentMethods: string[] = [];
+		const originalSend = c["ws"].send.bind(c["ws"]);
+		c["ws"].send = (data: unknown) => {
+			if (typeof data === "string") {
+				const parsed = JSON.parse(data);
+				sentMethods.push(parsed.method);
+			}
+			return originalSend(data as string);
+		};
+
+		const promise = j.send("Inspector.enable");
+		c.handleMessage(JSON.stringify({ id: 1, result: {} }));
+		await promise;
+
+		expect(sentMethods).toEqual(["Inspector.enable"]);
+	});
+
+	test("send with params passes them through", async () => {
+		const j = jsc!;
+		const c = cdp!;
+
+		const sentParams: unknown[] = [];
+		const originalSend = c["ws"].send.bind(c["ws"]);
+		c["ws"].send = (data: unknown) => {
+			if (typeof data === "string") {
+				const parsed = JSON.parse(data);
+				sentParams.push(parsed.params);
+			}
+			return originalSend(data as string);
+		};
+
+		const promise = j.send("Debugger.setBreakpointsActive", { active: true });
+		c.handleMessage(JSON.stringify({ id: 1, result: {} }));
+		await promise;
+
+		expect(sentParams[0]).toEqual({ active: true });
+	});
+
+	test("send returns typed result", async () => {
+		const j = jsc!;
+		const c = cdp!;
+
+		const promise = j.send("Debugger.setBreakpointByUrl", {
+			urlRegex: "test\\.js$",
+			lineNumber: 1,
+		});
+
+		c.handleMessage(
+			JSON.stringify({
+				id: 1,
+				result: {
+					breakpointId: "bp-1",
+					locations: [{ scriptId: "1", lineNumber: 1 }],
+				},
+			}),
+		);
+
+		const result = await promise;
+		expect(result.breakpointId).toBe("bp-1");
+		expect(result.locations).toHaveLength(1);
+	});
+
+	test("exposes cdp property for shared commands", () => {
+		const j = jsc!;
+		expect(j.cdp).toBe(cdp!);
+	});
+
+	test("connected delegates to cdp", () => {
+		const j = jsc!;
+		expect(j.connected).toBe(true);
+		j.disconnect();
+		expect(j.connected).toBe(false);
+	});
+
+	test("on/off delegate to cdp", () => {
+		const j = jsc!;
+		const c = cdp!;
+
+		const results: unknown[] = [];
+		const handler = (params: unknown) => results.push(params);
+
+		j.on("Debugger.paused", handler);
+		c.handleMessage(
+			JSON.stringify({
+				method: "Debugger.paused",
+				params: { reason: "breakpoint" },
+			}),
+		);
+		expect(results).toHaveLength(1);
+
+		j.off("Debugger.paused", handler);
+		c.handleMessage(
+			JSON.stringify({
+				method: "Debugger.paused",
+				params: { reason: "step" },
+			}),
+		);
+		expect(results).toHaveLength(1); // no new event
+	});
+
+	test("waitFor delegates to cdp", async () => {
+		const j = jsc!;
+		const c = cdp!;
+
+		const promise = j.waitFor("Debugger.paused", { timeoutMs: 1_000 });
+		c.handleMessage(
+			JSON.stringify({
+				method: "Debugger.paused",
+				params: { reason: "Breakpoint", callFrames: [] },
+			}),
+		);
+
+		const result = await promise;
+		expect(result).toEqual({ reason: "Breakpoint", callFrames: [] });
+	});
+});