agent-dbg 0.1.0

package/src/sourcemap/resolver.ts

@@ -0,0 +1,318 @@
+import { dirname, resolve } from "node:path";
+import {
+	generatedPositionFor,
+	LEAST_UPPER_BOUND,
+	originalPositionFor,
+	TraceMap,
+} from "@jridgewell/trace-mapping";
+
+export interface OriginalPosition {
+	source: string;
+	line: number;
+	column: number;
+	name: string | null;
+}
+
+export interface GeneratedPosition {
+	scriptId: string;
+	line: number;
+	column: number;
+}
+
+export interface SourceMapInfo {
+	scriptId: string;
+	generatedUrl: string;
+	mapUrl: string;
+	sources: string[];
+	hasSourcesContent: boolean;
+}
+
+interface LoadedMap {
+	traceMap: TraceMap;
+	scriptId: string;
+	generatedUrl: string;
+	mapUrl: string;
+	sources: string[];
+	resolvedSources: string[];
+	hasSourcesContent: boolean;
+}
+
+export class SourceMapResolver {
+	private maps: Map<string, LoadedMap> = new Map();
+	// Reverse lookup: resolved source path → { scriptId, sourceIndex }
+	private sourceIndex: Map<string, { scriptId: string; sourceIndex: number }> = new Map();
+	private disabled = false;
+
+	async loadSourceMap(scriptId: string, scriptUrl: string, sourceMapURL: string): Promise<boolean> {
+		if (this.disabled) return false;
+
+		try {
+			let rawMap: string;
+
+			if (sourceMapURL.startsWith("data:")) {
+				// Inline data: URI
+				const commaIndex = sourceMapURL.indexOf(",");
+				if (commaIndex === -1) return false;
+				const header = sourceMapURL.slice(0, commaIndex);
+				const data = sourceMapURL.slice(commaIndex + 1);
+
+				if (header.includes("base64")) {
+					rawMap = Buffer.from(data, "base64").toString("utf-8");
+				} else {
+					rawMap = decodeURIComponent(data);
+				}
+			} else {
+				// File-based source map — resolve relative to the script
+				let mapPath: string;
+				const scriptPath = scriptUrl.startsWith("file://") ? scriptUrl.slice(7) : scriptUrl;
+
+				if (sourceMapURL.startsWith("/")) {
+					mapPath = sourceMapURL;
+				} else {
+					mapPath = resolve(dirname(scriptPath), sourceMapURL);
+				}
+
+				const file = Bun.file(mapPath);
+				if (!(await file.exists())) return false;
+				rawMap = await file.text();
+			}
+
+			const parsed = JSON.parse(rawMap);
+			const traceMap = new TraceMap(parsed);
+
+			const sources: string[] = (traceMap.sources as string[]) ?? [];
+
+			// Resolve source paths relative to the script location
+			const scriptPath = scriptUrl.startsWith("file://") ? scriptUrl.slice(7) : scriptUrl;
+			const scriptDir = dirname(scriptPath);
+
+			const resolvedSources = sources.map((s) => {
+				if (s.startsWith("/")) return s;
+				return resolve(scriptDir, s);
+			});
+
+			const entry: LoadedMap = {
+				traceMap,
+				scriptId,
+				generatedUrl: scriptUrl,
+				mapUrl: sourceMapURL,
+				sources,
+				resolvedSources,
+				hasSourcesContent:
+					Array.isArray(traceMap.sourcesContent) && traceMap.sourcesContent.some((c) => c != null),
+			};
+
+			this.maps.set(scriptId, entry);
+
+			// Build reverse lookup for each source
+			for (let i = 0; i < sources.length; i++) {
+				const rawSource = sources[i];
+				const resolvedSource = resolvedSources[i];
+
+				if (rawSource) {
+					this.sourceIndex.set(rawSource, { scriptId, sourceIndex: i });
+				}
+				if (resolvedSource && resolvedSource !== rawSource) {
+					this.sourceIndex.set(resolvedSource, { scriptId, sourceIndex: i });
+				}
+			}
+
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	toOriginal(scriptId: string, line: number, column: number): OriginalPosition | null {
+		if (this.disabled) return null;
+
+		const entry = this.maps.get(scriptId);
+		if (!entry) return null;
+
+		const result = originalPositionFor(entry.traceMap, {
+			line,
+			column,
+		});
+
+		if (result.source == null) return null;
+
+		return {
+			source: result.source,
+			line: result.line ?? line,
+			column: result.column ?? column,
+			name: result.name,
+		};
+	}
+
+	toGenerated(source: string, line: number, column: number): GeneratedPosition | null {
+		if (this.disabled) return null;
+
+		// Try direct lookup first
+		const indexEntry = this.sourceIndex.get(source);
+		if (indexEntry) {
+			const entry = this.maps.get(indexEntry.scriptId);
+			if (entry) {
+				const sourceName = entry.sources[indexEntry.sourceIndex];
+				if (sourceName) {
+					const result = this.tryGeneratedPosition(entry.traceMap, sourceName, line, column);
+					if (result) {
+						return { scriptId: indexEntry.scriptId, ...result };
+					}
+				}
+			}
+		}
+
+		// Try suffix matching
+		const match = this.findScriptForSource(source);
+		if (match) {
+			const entry = this.maps.get(match.scriptId);
+			if (entry) {
+				// Find the matching source name in the map
+				for (const s of entry.sources) {
+					if (s && (s === source || s.endsWith(source) || source.endsWith(s))) {
+						const result = this.tryGeneratedPosition(entry.traceMap, s, line, column);
+						if (result) {
+							return { scriptId: match.scriptId, ...result };
+						}
+					}
+				}
+			}
+		}
+
+		return null;
+	}
+
+	private tryGeneratedPosition(
+		traceMap: TraceMap,
+		source: string,
+		line: number,
+		column: number,
+	): { line: number; column: number } | null {
+		// Try exact match first
+		const exact = generatedPositionFor(traceMap, { source, line, column });
+		if (exact.line != null) {
+			return { line: exact.line, column: exact.column ?? 0 };
+		}
+
+		// Fallback: use LEAST_UPPER_BOUND to find the nearest mapping on this line
+		const approx = generatedPositionFor(traceMap, {
+			source,
+			line,
+			column,
+			bias: LEAST_UPPER_BOUND,
+		});
+		if (approx.line != null) {
+			return { line: approx.line, column: approx.column ?? 0 };
+		}
+
+		return null;
+	}
+
+	getOriginalSource(scriptId: string, sourcePath: string): string | null {
+		if (this.disabled) return null;
+
+		const entry = this.maps.get(scriptId);
+		if (!entry) return null;
+
+		const sourcesContent = entry.traceMap.sourcesContent as (string | null)[] | undefined;
+		if (!sourcesContent) return null;
+
+		// Match by raw source path or resolved path
+		for (let i = 0; i < entry.sources.length; i++) {
+			const raw = entry.sources[i];
+			const resolved = entry.resolvedSources[i];
+			if (
+				(raw && (raw === sourcePath || raw.endsWith(sourcePath) || sourcePath.endsWith(raw))) ||
+				(resolved &&
+					(resolved === sourcePath ||
+						resolved.endsWith(sourcePath) ||
+						sourcePath.endsWith(resolved)))
+			) {
+				return sourcesContent[i] ?? null;
+			}
+		}
+
+		return null;
+	}
+
+	findScriptForSource(path: string): { scriptId: string; url: string } | null {
+		if (this.disabled) return null;
+
+		// Try direct lookup first
+		const direct = this.sourceIndex.get(path);
+		if (direct) {
+			const entry = this.maps.get(direct.scriptId);
+			if (entry) {
+				return { scriptId: direct.scriptId, url: entry.generatedUrl };
+			}
+		}
+
+		// Try suffix matching against all sources
+		for (const [scriptId, entry] of this.maps) {
+			for (let i = 0; i < entry.sources.length; i++) {
+				const raw = entry.sources[i];
+				const resolved = entry.resolvedSources[i];
+				if (raw && (raw.endsWith(path) || path.endsWith(raw))) {
+					return { scriptId, url: entry.generatedUrl };
+				}
+				if (resolved && (resolved.endsWith(path) || path.endsWith(resolved))) {
+					return { scriptId, url: entry.generatedUrl };
+				}
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Returns the primary original source URL for a script that has a source map,
+	 * regardless of whether a specific line has a mapping. Used for Option A:
+	 * always show .ts path when source map exists.
+	 */
+	getScriptOriginalUrl(scriptId: string): string | null {
+		if (this.disabled) return null;
+		const entry = this.maps.get(scriptId);
+		if (!entry) return null;
+		return entry.sources[0] ?? null;
+	}
+
+	getInfo(scriptId: string): SourceMapInfo | null {
+		const entry = this.maps.get(scriptId);
+		if (!entry) return null;
+
+		return {
+			scriptId: entry.scriptId,
+			generatedUrl: entry.generatedUrl,
+			mapUrl: entry.mapUrl,
+			sources: [...entry.sources],
+			hasSourcesContent: entry.hasSourcesContent,
+		};
+	}
+
+	getAllInfos(): SourceMapInfo[] {
+		const result: SourceMapInfo[] = [];
+		for (const entry of this.maps.values()) {
+			result.push({
+				scriptId: entry.scriptId,
+				generatedUrl: entry.generatedUrl,
+				mapUrl: entry.mapUrl,
+				sources: [...entry.sources],
+				hasSourcesContent: entry.hasSourcesContent,
+			});
+		}
+		return result;
+	}
+
+	setDisabled(disabled: boolean): void {
+		this.disabled = disabled;
+	}
+
+	isDisabled(): boolean {
+		return this.disabled;
+	}
+
+	clear(): void {
+		this.maps.clear();
+		this.sourceIndex.clear();
+	}
+}

package/tests/fixtures/async-app.js

@@ -0,0 +1,34 @@
+// Test fixture with async patterns for ndbg integration tests
+// Launch with: node --inspect-brk tests/fixtures/async-app.js
+
+async function delay(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function processItem(item) {
+	await delay(10);
+	const result = { ...item, processed: true, timestamp: Date.now() };
+	return result;
+}
+
+async function processQueue(items) {
+	const results = [];
+	for (const item of items) {
+		const result = await processItem(item);
+		results.push(result);
+	}
+	return results;
+}
+
+const queue = [
+	{ id: 1, name: "alpha" },
+	{ id: 2, name: "beta" },
+	{ id: 3, name: "gamma" },
+];
+
+processQueue(queue).then((results) => {
+	console.log(`Processed ${results.length} items`);
+	for (const r of results) {
+		console.log(`  ${r.id}: ${r.name} (processed: ${r.processed})`);
+	}
+});

package/tests/fixtures/console-app.js

@@ -0,0 +1,12 @@
+console.log("hello from app");
+console.warn("warning message");
+console.error("error message");
+const obj = { key: "value" };
+console.log("object:", obj);
+try {
+	throw new Error("test error");
+} catch (e) {
+	/* swallowed */
+}
+debugger;
+console.log("after debugger");

package/tests/fixtures/error-app.js

@@ -0,0 +1,28 @@
+// Test fixture with errors for ndbg integration tests
+// Launch with: node --inspect-brk tests/fixtures/error-app.js
+
+function riskyOperation(input) {
+	if (!input) {
+		throw new Error("Input is required");
+	}
+	return input.toUpperCase();
+}
+
+function handleError() {
+	try {
+		riskyOperation(null);
+	} catch (err) {
+		console.error("Caught:", err.message);
+		return { error: err.message };
+	}
+}
+
+// Uncaught error path
+const mode = process.argv[2] || "caught";
+
+if (mode === "caught") {
+	const result = handleError();
+	console.log("Result:", result);
+} else if (mode === "uncaught") {
+	riskyOperation(null); // This will throw uncaught
+}

package/tests/fixtures/exception-app.js

@@ -0,0 +1,6 @@
+// This script throws an uncaught exception after a short delay.
+// The process will crash, but the Runtime.exceptionThrown event
+// will be captured before the process exits.
+setTimeout(() => {
+	throw new Error("uncaught!");
+}, 50);

package/tests/fixtures/inspect-app.js

@@ -0,0 +1,10 @@
+const obj = { name: "test", count: 42, nested: { deep: true } };
+const arr = [1, 2, 3];
+const str = "hello";
+const num = 123;
+function greet(who) {
+	return "hi " + who;
+}
+const promise = Promise.resolve(42);
+debugger; // pause here
+console.log(obj, arr);

package/tests/fixtures/mutation-app.js

@@ -0,0 +1,9 @@
+let counter = 0;
+const name = "original";
+function increment() {
+	counter++;
+	return counter;
+}
+debugger;
+const result = increment();
+console.log(name, result);

package/tests/fixtures/simple-app.js

@@ -0,0 +1,50 @@
+// Simple test fixture for ndbg integration tests
+// Launch with: node --inspect-brk tests/fixtures/simple-app.js
+
+function greet(name) {
+	const message = `Hello, ${name}!`;
+	console.log(message);
+	return message;
+}
+
+function add(a, b) {
+	const result = a + b;
+	return result;
+}
+
+async function fetchData(id) {
+	const data = { id, name: "test", items: [1, 2, 3] };
+	await new Promise((resolve) => setTimeout(resolve, 10));
+	return data;
+}
+
+class Counter {
+	constructor(initial = 0) {
+		this.count = initial;
+	}
+
+	increment() {
+		this.count++;
+		return this.count;
+	}
+
+	decrement() {
+		this.count--;
+		return this.count;
+	}
+}
+
+// Main execution
+const counter = new Counter(10);
+const greeting = greet("World");
+const sum = add(2, 3);
+
+counter.increment();
+counter.increment();
+counter.decrement();
+
+fetchData("test-123").then((data) => {
+	console.log("Data:", JSON.stringify(data));
+	console.log("Counter:", counter.count);
+	console.log("Sum:", sum);
+});

package/tests/fixtures/step-app.js

@@ -0,0 +1,13 @@
+// Test fixture for execution control tests
+// Each line is a separate statement for stepping tests
+
+function helper(x) {
+	const doubled = x * 2;
+	return doubled;
+}
+
+const a = 1;
+const b = 2;
+const c = helper(a);
+const d = a + b + c;
+console.log(d);

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

@@ -0,0 +1,21 @@
+// TypeScript test fixture for source map integration tests
+interface Person {
+	name: string;
+	age: number;
+}
+
+function greet(person: Person): string {
+	const message: string = `Hello, ${person.name}! Age: ${person.age}`;
+	return message;
+}
+
+function add(a: number, b: number): number {
+	const result: number = a + b;
+	return result;
+}
+
+const alice: Person = { name: "Alice", age: 30 };
+const greeting: string = greet(alice);
+const sum: number = add(2, 3);
+console.log(greeting);
+console.log("Sum:", sum);

package/tests/fixtures/ts-app/tsconfig.json

@@ -0,0 +1,14 @@
+{
+	"compilerOptions": {
+		"target": "ES2020",
+		"module": "commonjs",
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"sourceMap": true,
+		"inlineSources": true,
+		"strict": true,
+		"esModuleInterop": true,
+		"declaration": false
+	},
+	"include": ["src/**/*.ts"]
+}

package/tests/integration/blackbox.test.ts

@@ -0,0 +1,135 @@
+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);
+	}
+}
+
+describe("Blackbox patterns", () => {
+	test("add blackbox patterns", async () => {
+		const session = new DebugSession("test-blackbox-add");
+		try {
+			await session.launch(["node", "tests/fixtures/step-app.js"], {
+				brk: true,
+			});
+			await waitForState(session, "paused");
+
+			const result = await session.addBlackbox(["node_modules", "internal"]);
+			expect(result).toEqual(["node_modules", "internal"]);
+			expect(session.listBlackbox()).toEqual(["node_modules", "internal"]);
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("list blackbox patterns", async () => {
+		const session = new DebugSession("test-blackbox-list");
+		try {
+			await session.launch(["node", "tests/fixtures/step-app.js"], {
+				brk: true,
+			});
+			await waitForState(session, "paused");
+
+			// Initially empty
+			expect(session.listBlackbox()).toEqual([]);
+
+			// Add some patterns
+			await session.addBlackbox(["node_modules", "vendor"]);
+
+			// Verify they are listed
+			const patterns = session.listBlackbox();
+			expect(patterns).toEqual(["node_modules", "vendor"]);
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("remove specific pattern", async () => {
+		const session = new DebugSession("test-blackbox-rm-specific");
+		try {
+			await session.launch(["node", "tests/fixtures/step-app.js"], {
+				brk: true,
+			});
+			await waitForState(session, "paused");
+
+			await session.addBlackbox(["node_modules", "vendor"]);
+			expect(session.listBlackbox()).toEqual(["node_modules", "vendor"]);
+
+			const result = await session.removeBlackbox(["node_modules"]);
+			expect(result).toEqual(["vendor"]);
+			expect(session.listBlackbox()).toEqual(["vendor"]);
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("remove all patterns", async () => {
+		const session = new DebugSession("test-blackbox-rm-all");
+		try {
+			await session.launch(["node", "tests/fixtures/step-app.js"], {
+				brk: true,
+			});
+			await waitForState(session, "paused");
+
+			await session.addBlackbox(["node_modules", "vendor", "internal"]);
+			expect(session.listBlackbox()).toHaveLength(3);
+
+			const result = await session.removeBlackbox(["all"]);
+			expect(result).toEqual([]);
+			expect(session.listBlackbox()).toEqual([]);
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("blackbox persists across continue", async () => {
+		const session = new DebugSession("test-blackbox-persist");
+		try {
+			await session.launch(["node", "tests/fixtures/step-app.js"], {
+				brk: true,
+			});
+			await waitForState(session, "paused");
+
+			// Set a breakpoint further in the file so we can continue to it
+			await session.setBreakpoint("step-app.js", 12);
+
+			// Add blackbox patterns
+			await session.addBlackbox(["node_modules"]);
+			expect(session.listBlackbox()).toEqual(["node_modules"]);
+
+			// Continue to the breakpoint
+			await session.continue();
+			await waitForState(session, "paused");
+
+			// Patterns should still be present
+			expect(session.listBlackbox()).toEqual(["node_modules"]);
+		} finally {
+			await session.stop();
+		}
+	});
+
+	test("blackbox throws when no session", async () => {
+		const session = new DebugSession("test-blackbox-no-session");
+		try {
+			await expect(session.addBlackbox(["node_modules"])).rejects.toThrow(
+				"No active debug session",
+			);
+
+			await expect(session.removeBlackbox(["node_modules"])).rejects.toThrow(
+				"No active debug session",
+			);
+		} finally {
+			await session.stop();
+		}
+	});
+});