agent-dbg 0.1.0

package/tests/integration/inspection.test.ts

@@ -0,0 +1,311 @@
+import { describe, expect, test } from "bun:test";
+import { DebugSession } from "../../src/daemon/session.ts";
+
+/**
+ * Polls until the session reaches the expected state, or times out.
+ */
+async function waitForState(
+	session: DebugSession,
+	state: "idle" | "running" | "paused",
+	timeoutMs = 5000,
+): Promise<void> {
+	const deadline = Date.now() + timeoutMs;
+	while (session.sessionState !== state && Date.now() < deadline) {
+		await Bun.sleep(50);
+	}
+}
+
+/**
+ * Launch and advance to the debugger statement in inspect-app.js (line 7).
+ */
+async function launchAndPauseAtDebugger(sessionName: string): Promise<DebugSession> {
+	const session = new DebugSession(sessionName);
+	await session.launch(["node", "tests/fixtures/inspect-app.js"], {
+		brk: true,
+	});
+	await waitForState(session, "paused");
+
+	// Continue past initial brk pause to the `debugger;` statement
+	await session.continue();
+	await waitForState(session, "paused");
+
+	return session;
+}
+
+describe("Inspection: eval", () => {
+	test("eval evaluates a simple expression", async () => {
+		const session = await launchAndPauseAtDebugger("test-eval-simple");
+		try {
+			expect(session.sessionState).toBe("paused");
+
+			const result = await session.eval("1 + 2");
+			expect(result.ref).toMatch(/^@v/);
+			expect(result.type).toBe("number");
+			expect(result.value).toBe("3");
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("eval accesses local variables", async () => {
+		const session = await launchAndPauseAtDebugger("test-eval-locals");
+		try {
+			const result = await session.eval("num");
+			expect(result.ref).toMatch(/^@v/);
+			expect(result.type).toBe("number");
+			expect(result.value).toBe("123");
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("eval accesses object properties", async () => {
+		const session = await launchAndPauseAtDebugger("test-eval-obj-prop");
+		try {
+			const result = await session.eval("obj.name");
+			expect(result.ref).toMatch(/^@v/);
+			expect(result.type).toBe("string");
+			expect(result.value).toContain("test");
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("eval with string concatenation", async () => {
+		const session = await launchAndPauseAtDebugger("test-eval-concat");
+		try {
+			const result = await session.eval("str + ' world'");
+			expect(result.type).toBe("string");
+			expect(result.value).toContain("hello world");
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("eval returns object with objectId", async () => {
+		const session = await launchAndPauseAtDebugger("test-eval-object");
+		try {
+			const result = await session.eval("obj");
+			expect(result.ref).toMatch(/^@v/);
+			expect(result.type).toBe("object");
+			expect(result.objectId).toBeDefined();
+			expect(result.value).toContain("name");
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("eval syntax error throws", async () => {
+		const session = await launchAndPauseAtDebugger("test-eval-syntax-err");
+		try {
+			await expect(session.eval("if (")).rejects.toThrow();
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("eval throws when not paused", async () => {
+		const session = new DebugSession("test-eval-not-paused");
+		try {
+			await session.launch(["node", "-e", "setInterval(() => {}, 100)"], { brk: false });
+			expect(session.sessionState).toBe("running");
+
+			await expect(session.eval("1 + 1")).rejects.toThrow("not paused");
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("eval with @ref interpolation", async () => {
+		const session = await launchAndPauseAtDebugger("test-eval-ref-interp");
+		try {
+			// First get vars to establish refs
+			const vars = await session.getVars();
+			const objVar = vars.find((v) => v.name === "obj");
+			expect(objVar).toBeDefined();
+
+			if (objVar) {
+				// Use the ref in an expression
+				const result = await session.eval(`${objVar.ref}.count`);
+				expect(result.type).toBe("number");
+				expect(result.value).toBe("42");
+			}
+		} finally {
+			await session.stop();
+		}
+	});
+});
+
+describe("Inspection: vars", () => {
+	test("getVars returns local variables with refs", async () => {
+		const session = await launchAndPauseAtDebugger("test-vars-basic");
+		try {
+			const vars = await session.getVars();
+
+			expect(vars.length).toBeGreaterThan(0);
+
+			// Check that expected variables are present
+			const names = vars.map((v) => v.name);
+			expect(names).toContain("obj");
+			expect(names).toContain("arr");
+			expect(names).toContain("str");
+			expect(names).toContain("num");
+
+			// Each variable should have a ref
+			for (const v of vars) {
+				expect(v.ref).toMatch(/^@v/);
+				expect(v.type).toBeDefined();
+				expect(v.value).toBeDefined();
+			}
+
+			// Check specific values
+			const numVar = vars.find((v) => v.name === "num");
+			expect(numVar?.type).toBe("number");
+			expect(numVar?.value).toBe("123");
+
+			const strVar = vars.find((v) => v.name === "str");
+			expect(strVar?.type).toBe("string");
+			expect(strVar?.value).toContain("hello");
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("getVars with name filter", async () => {
+		const session = await launchAndPauseAtDebugger("test-vars-filter");
+		try {
+			const vars = await session.getVars({ names: ["num", "str"] });
+
+			expect(vars.length).toBe(2);
+			const names = vars.map((v) => v.name);
+			expect(names).toContain("num");
+			expect(names).toContain("str");
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("getVars throws when not paused", async () => {
+		const session = new DebugSession("test-vars-not-paused");
+		try {
+			await session.launch(["node", "-e", "setInterval(() => {}, 100)"], { brk: false });
+			expect(session.sessionState).toBe("running");
+
+			await expect(session.getVars()).rejects.toThrow("not paused");
+		} finally {
+			await session.stop();
+		}
+	});
+});
+
+describe("Inspection: props", () => {
+	test("getProps expands an object", async () => {
+		const session = await launchAndPauseAtDebugger("test-props-basic");
+		try {
+			// First get vars to get a ref for obj
+			const vars = await session.getVars();
+			const objVar = vars.find((v) => v.name === "obj");
+			expect(objVar).toBeDefined();
+
+			if (objVar) {
+				const props = await session.getProps(objVar.ref);
+
+				expect(props.length).toBeGreaterThan(0);
+
+				const propNames = props.map((p) => p.name);
+				expect(propNames).toContain("name");
+				expect(propNames).toContain("count");
+				expect(propNames).toContain("nested");
+
+				// Check property values
+				const nameProp = props.find((p) => p.name === "name");
+				expect(nameProp?.type).toBe("string");
+				expect(nameProp?.value).toContain("test");
+
+				const countProp = props.find((p) => p.name === "count");
+				expect(countProp?.type).toBe("number");
+				expect(countProp?.value).toBe("42");
+
+				// nested should be an object with a ref
+				const nestedProp = props.find((p) => p.name === "nested");
+				expect(nestedProp?.type).toBe("object");
+				expect(nestedProp?.ref).toMatch(/^@o/);
+			}
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("getProps assigns @o refs for object-type properties", async () => {
+		const session = await launchAndPauseAtDebugger("test-props-orefs");
+		try {
+			const vars = await session.getVars();
+			const objVar = vars.find((v) => v.name === "obj");
+			expect(objVar).toBeDefined();
+
+			if (objVar) {
+				const props = await session.getProps(objVar.ref);
+
+				// nested is an object, should have @o ref
+				const nestedProp = props.find((p) => p.name === "nested");
+				expect(nestedProp?.ref).toMatch(/^@o/);
+
+				// Primitive properties may or may not have refs depending on V8
+				// but object-type ones definitely should
+				if (nestedProp?.ref) {
+					// Can expand the nested object further
+					const nestedProps = await session.getProps(nestedProp.ref);
+					const deepProp = nestedProps.find((p) => p.name === "deep");
+					expect(deepProp).toBeDefined();
+					expect(deepProp?.value).toBe("true");
+				}
+			}
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("getProps expands an array", async () => {
+		const session = await launchAndPauseAtDebugger("test-props-array");
+		try {
+			const vars = await session.getVars();
+			const arrVar = vars.find((v) => v.name === "arr");
+			expect(arrVar).toBeDefined();
+
+			if (arrVar) {
+				const props = await session.getProps(arrVar.ref);
+				expect(props.length).toBeGreaterThan(0);
+
+				// Array should have numeric indices
+				const zeroProp = props.find((p) => p.name === "0");
+				expect(zeroProp?.value).toBe("1");
+			}
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("getProps on unknown ref throws", async () => {
+		const session = await launchAndPauseAtDebugger("test-props-unknown");
+		try {
+			await expect(session.getProps("@v999")).rejects.toThrow("Unknown ref");
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("getProps on primitive ref throws gracefully", async () => {
+		const session = await launchAndPauseAtDebugger("test-props-primitive");
+		try {
+			const vars = await session.getVars();
+			const numVar = vars.find((v) => v.name === "num");
+			expect(numVar).toBeDefined();
+
+			if (numVar) {
+				await expect(session.getProps(numVar.ref)).rejects.toThrow("primitive");
+			}
+		} finally {
+			await session.stop();
+		}
+	});
+});

package/tests/integration/mutation.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, test } from "bun:test";
+import { DebugSession } from "../../src/daemon/session.ts";
+
+/**
+ * Polls until the session reaches the expected state, or times out.
+ */
+async function waitForState(
+	session: DebugSession,
+	state: "idle" | "running" | "paused",
+	timeoutMs = 5000,
+): Promise<void> {
+	const deadline = Date.now() + timeoutMs;
+	while (session.sessionState !== state && Date.now() < deadline) {
+		await Bun.sleep(50);
+	}
+}
+
+/**
+ * Launch and advance to the debugger statement in mutation-app.js (line 7).
+ */
+async function launchAndPauseAtDebugger(sessionName: string): Promise<DebugSession> {
+	const session = new DebugSession(sessionName);
+	await session.launch(["node", "tests/fixtures/mutation-app.js"], {
+		brk: true,
+	});
+	await waitForState(session, "paused");
+
+	// Continue past initial brk pause to the `debugger;` statement
+	await session.continue();
+	await waitForState(session, "paused");
+
+	return session;
+}
+
+describe("Mutation: setVariable", () => {
+	test("set variable changes value", async () => {
+		const session = await launchAndPauseAtDebugger("test-set-var");
+		try {
+			expect(session.sessionState).toBe("paused");
+
+			// Set counter to 42
+			const result = await session.setVariable("counter", "42");
+			expect(result.name).toBe("counter");
+			expect(result.newValue).toBe("42");
+			expect(result.type).toBe("number");
+
+			// Verify the value was actually changed
+			const evalResult = await session.eval("counter");
+			expect(evalResult.value).toBe("42");
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("set variable returns old value", async () => {
+		const session = await launchAndPauseAtDebugger("test-set-var-old");
+		try {
+			const result = await session.setVariable("counter", "99");
+			expect(result.oldValue).toBe("0");
+			expect(result.newValue).toBe("99");
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("set variable throws when not paused", async () => {
+		const session = new DebugSession("test-set-var-not-paused");
+		try {
+			await session.launch(["node", "-e", "setInterval(() => {}, 100)"], { brk: false });
+			expect(session.sessionState).toBe("running");
+
+			await expect(session.setVariable("x", "1")).rejects.toThrow("not paused");
+		} finally {
+			await session.stop();
+		}
+	});
+});
+
+describe("Mutation: setReturnValue", () => {
+	test("set-return changes return value", async () => {
+		const session = await launchAndPauseAtDebugger("test-set-return");
+		try {
+			expect(session.sessionState).toBe("paused");
+
+			// We are paused at `debugger;` (line 7).
+			// Step into goes to `const result = increment();` (line 8).
+			await session.step("into");
+			await waitForState(session, "paused");
+
+			// Step into enters the `increment` function body.
+			await session.step("into");
+			await waitForState(session, "paused");
+
+			// Step over `counter++` to reach `return counter;`
+			await session.step("over");
+			await waitForState(session, "paused");
+
+			// Step over the return statement -- this evaluates `return counter`
+			// and pauses at the return point (frame about to pop).
+			await session.step("over");
+			await waitForState(session, "paused");
+
+			// Now at return position, set the return value to 99
+			const result = await session.setReturnValue("99");
+			expect(result.value).toBe("99");
+			expect(result.type).toBe("number");
+		} finally {
+			await session.stop();
+		}
+	});
+});
+
+describe("Mutation: hotpatch", () => {
+	test("hotpatch replaces script source", async () => {
+		const session = await launchAndPauseAtDebugger("test-hotpatch");
+		try {
+			expect(session.sessionState).toBe("paused");
+
+			// Get the current source
+			const source = await session.getSource({ file: "mutation-app.js", all: true });
+			expect(source.url).toContain("mutation-app.js");
+
+			// Build modified source: change the increment function to add 10 instead of 1
+			const originalText = source.lines.map((l) => l.text).join("\n");
+			const modifiedSource = originalText.replace("counter++", "counter += 10");
+
+			// Apply hotpatch
+			const result = await session.hotpatch("mutation-app.js", modifiedSource);
+			expect(result.status).toBeDefined();
+
+			// Verify the modified function by checking the updated source
+			const newSource = await session.getSource({ file: "mutation-app.js", all: true });
+			const newText = newSource.lines.map((l) => l.text).join("\n");
+			expect(newText).toContain("counter += 10");
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("hotpatch dry-run does not modify source", async () => {
+		const session = await launchAndPauseAtDebugger("test-hotpatch-dry");
+		try {
+			expect(session.sessionState).toBe("paused");
+
+			// Get the current source
+			const source = await session.getSource({ file: "mutation-app.js", all: true });
+			const originalText = source.lines.map((l) => l.text).join("\n");
+
+			// Build modified source
+			const modifiedSource = originalText.replace("counter++", "counter += 100");
+
+			// Apply hotpatch with dryRun
+			const result = await session.hotpatch("mutation-app.js", modifiedSource, {
+				dryRun: true,
+			});
+			expect(result.status).toBeDefined();
+
+			// Verify the source was NOT changed
+			const afterSource = await session.getSource({ file: "mutation-app.js", all: true });
+			const afterText = afterSource.lines.map((l) => l.text).join("\n");
+			expect(afterText).not.toContain("counter += 100");
+			expect(afterText).toContain("counter++");
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("hotpatch throws for unknown file", async () => {
+		const session = await launchAndPauseAtDebugger("test-hotpatch-unknown");
+		try {
+			await expect(session.hotpatch("nonexistent-file.js", "// new source")).rejects.toThrow(
+				"No loaded script",
+			);
+		} finally {
+			await session.stop();
+		}
+	});
+});

package/tests/integration/session.test.ts

@@ -0,0 +1,223 @@
+import { describe, expect, test } from "bun:test";
+import { DebugSession } from "../../src/daemon/session.ts";
+
+/**
+ * Polls until the session reaches the expected state, or times out.
+ * This is needed because Debugger.paused events arrive asynchronously
+ * over WebSocket and may not have been processed when launch() returns.
+ */
+async function waitForState(
+	session: DebugSession,
+	state: "idle" | "running" | "paused",
+	timeoutMs = 2000,
+): Promise<void> {
+	const deadline = Date.now() + timeoutMs;
+	while (session.sessionState !== state && Date.now() < deadline) {
+		await Bun.sleep(50);
+	}
+}
+
+/**
+ * Reads stderr from a spawned process until it finds the inspector URL line.
+ * Returns the accumulated stderr output.
+ */
+async function readStderrUntilInspector(stderr: ReadableStream<Uint8Array>): Promise<string> {
+	const reader = stderr.getReader();
+	const decoder = new TextDecoder();
+	let output = "";
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			output += decoder.decode(value, { stream: true });
+			if (output.includes("Debugger listening on")) break;
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	return output;
+}
+
+describe("DebugSession integration", () => {
+	test("launch with brk pauses at first line", async () => {
+		const session = new DebugSession("test-launch");
+		try {
+			const result = await session.launch(["node", "tests/fixtures/simple-app.js"], {
+				brk: true,
+			});
+			// Allow time for the Debugger.paused event to arrive via WebSocket
+			await waitForState(session, "paused");
+
+			expect(result.pid).toBeGreaterThan(0);
+			expect(result.wsUrl).toMatch(/^ws:\/\//);
+			expect(session.sessionState).toBe("paused");
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("launch without brk starts running", async () => {
+		const session = new DebugSession("test-nobrk");
+		try {
+			const result = await session.launch(["node", "-e", "setTimeout(() => {}, 30000)"], {
+				brk: false,
+			});
+			expect(result.pid).toBeGreaterThan(0);
+			expect(result.paused).toBe(false);
+			expect(session.sessionState).toBe("running");
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("getStatus returns correct info after launch", async () => {
+		const session = new DebugSession("test-status");
+		try {
+			await session.launch(["node", "tests/fixtures/simple-app.js"], { brk: true });
+			// Allow time for the Debugger.paused event to arrive via WebSocket
+			await waitForState(session, "paused");
+
+			const status = session.getStatus();
+			expect(status.session).toBe("test-status");
+			expect(status.state).toBe("paused");
+			expect(status.pid).toBeGreaterThan(0);
+			expect(status.wsUrl).toBeDefined();
+			expect(status.uptime).toBeGreaterThanOrEqual(0);
+			expect(status.scriptCount).toBeGreaterThan(0);
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("stop disconnects and kills process", async () => {
+		const session = new DebugSession("test-stop");
+		const result = await session.launch(["node", "-e", "setTimeout(() => {}, 30000)"], {
+			brk: true,
+		});
+		const pid = result.pid;
+
+		await session.stop();
+
+		expect(session.sessionState).toBe("idle");
+		expect(session.cdp).toBeNull();
+		expect(session.targetPid).toBeNull();
+
+		// Verify process is actually dead (give it a moment)
+		await Bun.sleep(100);
+		let alive = false;
+		try {
+			process.kill(pid, 0);
+			alive = true;
+		} catch {
+			alive = false;
+		}
+		expect(alive).toBe(false);
+	});
+
+	test("attach connects to running inspector", async () => {
+		// Start a node process with --inspect manually
+		const proc = Bun.spawn(["node", "--inspect=0", "-e", "setTimeout(() => {}, 30000)"], {
+			stdin: "ignore",
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+
+		try {
+			const stderr = await readStderrUntilInspector(proc.stderr);
+			const match = /Debugger listening on (ws:\/\/\S+)/.exec(stderr);
+			expect(match).not.toBeNull();
+			const wsUrl = match?.[1] ?? "";
+			expect(wsUrl).toMatch(/^ws:\/\//);
+
+			const session = new DebugSession("test-attach");
+			try {
+				const result = await session.attach(wsUrl);
+				expect(result.wsUrl).toBe(wsUrl);
+				expect(session.sessionState).toBe("running");
+			} finally {
+				await session.stop();
+			}
+		} finally {
+			proc.kill();
+		}
+	});
+
+	test("attach by port discovers ws URL", async () => {
+		// Start node with --inspect=0 to get a random port
+		const proc = Bun.spawn(["node", "--inspect=0", "-e", "setTimeout(() => {}, 30000)"], {
+			stdin: "ignore",
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+
+		try {
+			const stderr = await readStderrUntilInspector(proc.stderr);
+			const match = /ws:\/\/127\.0\.0\.1:(\d+)\//.exec(stderr);
+			expect(match).not.toBeNull();
+			const port = match?.[1] ?? "";
+			expect(port).toMatch(/^\d+$/);
+
+			const session = new DebugSession("test-attach-port");
+			try {
+				const result = await session.attach(port);
+				expect(result.wsUrl).toMatch(/^ws:\/\//);
+			} finally {
+				await session.stop();
+			}
+		} finally {
+			proc.kill();
+		}
+	});
+
+	test("launching twice throws error", async () => {
+		const session = new DebugSession("test-double");
+		try {
+			await session.launch(["node", "-e", "setTimeout(() => {}, 30000)"], { brk: true });
+			await expect(
+				session.launch(["node", "-e", "setTimeout(() => {}, 30000)"], { brk: true }),
+			).rejects.toThrow("already has an active");
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("CDP connection is functional after launch", async () => {
+		const session = new DebugSession("test-cdp");
+		try {
+			await session.launch(["node", "-e", "debugger; setTimeout(() => {}, 30000)"], {
+				brk: true,
+			});
+			// Allow time for the Debugger.paused event to arrive via WebSocket
+			await waitForState(session, "paused");
+
+			// CDP should be connected
+			expect(session.cdp).not.toBeNull();
+			const cdp = session.cdp;
+			expect(cdp?.connected).toBe(true);
+
+			// Should be able to send CDP commands
+			const result = await cdp?.send("Runtime.evaluate", {
+				expression: "1 + 1",
+			});
+			const evalResult = result as { result: { value: number } };
+			expect(evalResult.result.value).toBe(2);
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("scripts are tracked after launch", async () => {
+		const session = new DebugSession("test-scripts");
+		try {
+			await session.launch(["node", "tests/fixtures/simple-app.js"], { brk: true });
+			// Allow time for script parsed events to arrive
+			await waitForState(session, "paused");
+
+			const status = session.getStatus();
+			// There should be several scripts loaded (at minimum the main script and node internals)
+			expect(status.scriptCount).toBeGreaterThan(0);
+		} finally {
+			await session.stop();
+		}
+	});
+});