agent-dbg 0.1.0

package/src/commands/sessions.ts

@@ -0,0 +1,71 @@
+import { registerCommand } from "../cli/registry.ts";
+import { DaemonClient } from "../daemon/client.ts";
+
+registerCommand("sessions", async (args) => {
+	const cleanup = args.flags.cleanup === true;
+	const sessions = DaemonClient.listSessions();
+
+	if (cleanup) {
+		let cleaned = 0;
+		for (const s of sessions) {
+			const alive = await DaemonClient.isAlive(s);
+			if (!alive) {
+				try {
+					const client = new DaemonClient(s);
+					await client.request("stop");
+				} catch {
+					// Socket exists but daemon is dead — stale detection handles cleanup
+				}
+				cleaned++;
+			}
+		}
+		console.log(`Cleaned up ${cleaned} orphaned session(s)`);
+		return 0;
+	}
+
+	if (sessions.length === 0) {
+		if (args.global.json) {
+			console.log("[]");
+		} else {
+			console.log("No active sessions");
+		}
+		return 0;
+	}
+
+	if (args.global.json) {
+		const results: unknown[] = [];
+		for (const s of sessions) {
+			try {
+				const client = new DaemonClient(s);
+				const resp = await client.request("status");
+				results.push(resp.ok ? resp.data : { session: s, state: "unknown" });
+			} catch {
+				results.push({ session: s, state: "unreachable" });
+			}
+		}
+		console.log(JSON.stringify(results, null, 2));
+	} else {
+		for (const s of sessions) {
+			try {
+				const client = new DaemonClient(s);
+				const resp = await client.request("status");
+				if (resp.ok) {
+					const d = resp.data as {
+						state: string;
+						pid?: number;
+						uptime: number;
+					};
+					const pid = d.pid ? ` (pid ${d.pid})` : "";
+					const uptime = `${Math.round(d.uptime)}s`;
+					console.log(`  ${s}${pid}  ${d.state}  uptime=${uptime}`);
+				} else {
+					console.log(`  ${s}  unknown`);
+				}
+			} catch {
+				console.log(`  ${s}  unreachable`);
+			}
+		}
+	}
+
+	return 0;
+});

package/src/commands/set-return.ts

@@ -0,0 +1,49 @@
+import { registerCommand } from "../cli/registry.ts";
+import { DaemonClient } from "../daemon/client.ts";
+
+registerCommand("set-return", async (args) => {
+	const session = args.global.session;
+
+	if (!DaemonClient.isRunning(session)) {
+		console.error(`No active session "${session}"`);
+		console.error("  -> Try: ndbg launch --brk node app.js");
+		return 1;
+	}
+
+	// Build value from subcommand + positionals
+	const parts: string[] = [];
+	if (args.subcommand) {
+		parts.push(args.subcommand);
+	}
+	parts.push(...args.positionals);
+	const value = parts.join(" ");
+
+	if (!value) {
+		console.error("No value specified");
+		console.error("  -> Try: ndbg set-return 42");
+		return 1;
+	}
+
+	const client = new DaemonClient(session);
+	const response = await client.request("set-return", { value });
+
+	if (!response.ok) {
+		console.error(`${response.error}`);
+		if (response.suggestion) console.error(`  ${response.suggestion}`);
+		return 1;
+	}
+
+	const data = response.data as {
+		value: string;
+		type: string;
+	};
+
+	if (args.global.json) {
+		console.log(JSON.stringify(data, null, 2));
+		return 0;
+	}
+
+	console.log(`return value set to: ${data.value}`);
+
+	return 0;
+});

package/src/commands/set.ts

@@ -0,0 +1,61 @@
+import { registerCommand } from "../cli/registry.ts";
+import { DaemonClient } from "../daemon/client.ts";
+
+registerCommand("set", async (args) => {
+	const session = args.global.session;
+
+	if (!DaemonClient.isRunning(session)) {
+		console.error(`No active session "${session}"`);
+		console.error("  -> Try: ndbg launch --brk node app.js");
+		return 1;
+	}
+
+	const varName = args.subcommand;
+	if (!varName) {
+		console.error("No variable name specified");
+		console.error("  -> Try: ndbg set counter 42");
+		return 1;
+	}
+
+	const valueParts = args.positionals;
+	if (valueParts.length === 0) {
+		console.error("No value specified");
+		console.error("  -> Try: ndbg set counter 42");
+		return 1;
+	}
+	const value = valueParts.join(" ");
+
+	const setArgs: Record<string, unknown> = {
+		name: varName,
+		value,
+	};
+
+	if (typeof args.flags.frame === "string") {
+		setArgs.frame = args.flags.frame;
+	}
+
+	const client = new DaemonClient(session);
+	const response = await client.request("set", setArgs);
+
+	if (!response.ok) {
+		console.error(`${response.error}`);
+		if (response.suggestion) console.error(`  ${response.suggestion}`);
+		return 1;
+	}
+
+	const data = response.data as {
+		name: string;
+		oldValue?: string;
+		newValue: string;
+		type: string;
+	};
+
+	if (args.global.json) {
+		console.log(JSON.stringify(data, null, 2));
+		return 0;
+	}
+
+	console.log(`${data.name} = ${data.newValue}`);
+
+	return 0;
+});

package/src/commands/source.ts

@@ -0,0 +1,59 @@
+import { registerCommand } from "../cli/registry.ts";
+import { DaemonClient } from "../daemon/client.ts";
+import type { SourceLine } from "../formatter/source.ts";
+import { formatSource } from "../formatter/source.ts";
+
+registerCommand("source", async (args) => {
+	const session = args.global.session;
+
+	if (!DaemonClient.isRunning(session)) {
+		console.error(`No active session "${session}"`);
+		console.error("  -> Try: ndbg launch --brk node app.js");
+		return 1;
+	}
+
+	const client = new DaemonClient(session);
+
+	const sourceArgs: Record<string, unknown> = {};
+
+	if (typeof args.flags.lines === "string") {
+		sourceArgs.lines = parseInt(args.flags.lines, 10);
+	}
+	if (typeof args.flags.file === "string") {
+		sourceArgs.file = args.flags.file;
+	}
+	if (args.flags.all === true) {
+		sourceArgs.all = true;
+	}
+	if (args.flags.generated === true) {
+		sourceArgs.generated = true;
+	}
+
+	const response = await client.request("source", sourceArgs);
+
+	if (!response.ok) {
+		console.error(`${response.error}`);
+		if (response.suggestion) console.error(`  ${response.suggestion}`);
+		return 1;
+	}
+
+	const data = response.data as {
+		url: string;
+		lines: Array<{ line: number; text: string; current?: boolean }>;
+	};
+
+	if (args.global.json) {
+		console.log(JSON.stringify(data, null, 2));
+		return 0;
+	}
+
+	console.log(`Source: ${data.url}`);
+	const sourceLines: SourceLine[] = data.lines.map((l) => ({
+		lineNumber: l.line,
+		content: l.text,
+		isCurrent: l.current,
+	}));
+	console.log(formatSource(sourceLines));
+
+	return 0;
+});

package/src/commands/sourcemap.ts

@@ -0,0 +1,66 @@
+import { registerCommand } from "../cli/registry.ts";
+import { DaemonClient } from "../daemon/client.ts";
+
+registerCommand("sourcemap", async (args) => {
+	const session = args.global.session;
+
+	if (!DaemonClient.isRunning(session)) {
+		console.error(`No active session "${session}"`);
+		console.error("  -> Try: ndbg launch --brk node app.js");
+		return 1;
+	}
+
+	const client = new DaemonClient(session);
+
+	// Handle --disable flag
+	if (args.flags.disable === true) {
+		const response = await client.request("sourcemap-disable", {});
+		if (!response.ok) {
+			console.error(`${response.error}`);
+			return 1;
+		}
+		console.log("Source map resolution disabled");
+		return 0;
+	}
+
+	// Query source map info
+	const smArgs: Record<string, unknown> = {};
+	if (args.subcommand) {
+		smArgs.file = args.subcommand;
+	}
+
+	const response = await client.request("sourcemap", smArgs);
+
+	if (!response.ok) {
+		console.error(`${response.error}`);
+		if (response.suggestion) console.error(`  ${response.suggestion}`);
+		return 1;
+	}
+
+	const data = response.data as Array<{
+		scriptId: string;
+		generatedUrl: string;
+		mapUrl: string;
+		sources: string[];
+		hasSourcesContent: boolean;
+	}>;
+
+	if (args.global.json) {
+		console.log(JSON.stringify(data, null, 2));
+		return 0;
+	}
+
+	if (data.length === 0) {
+		console.log("No source maps loaded");
+		return 0;
+	}
+
+	for (const info of data) {
+		console.log(`Script: ${info.generatedUrl}`);
+		console.log(`  Map: ${info.mapUrl}`);
+		console.log(`  Sources: ${info.sources.join(", ")}`);
+		console.log(`  Has sourcesContent: ${info.hasSourcesContent}`);
+	}
+
+	return 0;
+});

package/src/commands/stack.ts

@@ -0,0 +1,64 @@
+import { registerCommand } from "../cli/registry.ts";
+import { DaemonClient } from "../daemon/client.ts";
+import type { StackFrame } from "../formatter/stack.ts";
+import { formatStack } from "../formatter/stack.ts";
+
+registerCommand("stack", async (args) => {
+	const session = args.global.session;
+
+	if (!DaemonClient.isRunning(session)) {
+		console.error(`No active session "${session}"`);
+		console.error("  -> Try: ndbg launch --brk node app.js");
+		return 1;
+	}
+
+	const client = new DaemonClient(session);
+
+	const stackArgs: Record<string, unknown> = {};
+
+	if (typeof args.flags["async-depth"] === "string") {
+		stackArgs.asyncDepth = parseInt(args.flags["async-depth"], 10);
+	}
+	if (args.flags.generated === true) {
+		stackArgs.generated = true;
+	}
+
+	const response = await client.request("stack", stackArgs);
+
+	if (!response.ok) {
+		console.error(`${response.error}`);
+		if (response.suggestion) console.error(`  ${response.suggestion}`);
+		return 1;
+	}
+
+	const data = response.data as Array<{
+		ref: string;
+		functionName: string;
+		file: string;
+		line: number;
+		column?: number;
+		isAsync?: boolean;
+	}>;
+
+	if (args.global.json) {
+		console.log(JSON.stringify(data, null, 2));
+		return 0;
+	}
+
+	if (data.length === 0) {
+		console.log("No stack frames");
+		return 0;
+	}
+
+	const frames: StackFrame[] = data.map((f) => ({
+		ref: f.ref,
+		functionName: f.functionName,
+		file: f.file,
+		line: f.line,
+		column: f.column,
+		isAsync: f.isAsync,
+	}));
+	console.log(formatStack(frames));
+
+	return 0;
+});

package/src/commands/state.ts

@@ -0,0 +1,124 @@
+import { registerCommand } from "../cli/registry.ts";
+import { DaemonClient } from "../daemon/client.ts";
+import type { StateSnapshot } from "../daemon/session.ts";
+import type { SourceLine } from "../formatter/source.ts";
+import { formatSource } from "../formatter/source.ts";
+import type { StackFrame } from "../formatter/stack.ts";
+import { formatStack } from "../formatter/stack.ts";
+import type { Variable } from "../formatter/variables.ts";
+import { formatVariables } from "../formatter/variables.ts";
+
+registerCommand("state", async (args) => {
+	const session = args.global.session;
+
+	if (!DaemonClient.isRunning(session)) {
+		console.error(`No active session "${session}"`);
+		console.error("  -> Try: ndbg launch --brk node app.js");
+		return 1;
+	}
+
+	const client = new DaemonClient(session);
+
+	const stateArgs: Record<string, unknown> = {};
+
+	if (args.flags.vars === true) stateArgs.vars = true;
+	if (args.flags.stack === true) stateArgs.stack = true;
+	if (args.flags.breakpoints === true) stateArgs.breakpoints = true;
+	if (args.flags.code === true) stateArgs.code = true;
+	if (args.flags.compact === true) stateArgs.compact = true;
+	if (args.flags["all-scopes"] === true) stateArgs.allScopes = true;
+	if (typeof args.flags.depth === "string") {
+		stateArgs.depth = parseInt(args.flags.depth, 10);
+	}
+	if (typeof args.flags.lines === "string") {
+		stateArgs.lines = parseInt(args.flags.lines, 10);
+	}
+	if (typeof args.flags.frame === "string") {
+		stateArgs.frame = args.flags.frame;
+	}
+	if (args.flags.generated === true) stateArgs.generated = true;
+
+	const response = await client.request("state", stateArgs);
+
+	if (!response.ok) {
+		console.error(`${response.error}`);
+		if (response.suggestion) console.error(`  ${response.suggestion}`);
+		return 1;
+	}
+
+	const data = response.data as StateSnapshot;
+
+	if (args.global.json) {
+		console.log(JSON.stringify(data, null, 2));
+		return 0;
+	}
+
+	// Non-paused states
+	if (data.status !== "paused") {
+		const icon = data.status === "running" ? "\u25B6" : "\u25CB";
+		console.log(`${icon} ${data.status === "running" ? "Running" : "Idle"}`);
+		return 0;
+	}
+
+	// Paused state — header
+	const loc = data.location
+		? `${data.location.url}:${data.location.line}${data.location.column !== undefined ? `:${data.location.column}` : ""}`
+		: "unknown";
+	const reason = data.reason ?? "unknown";
+	console.log(`\u23F8 Paused at ${loc} (${reason})`);
+
+	const showAll = !stateArgs.vars && !stateArgs.stack && !stateArgs.breakpoints && !stateArgs.code;
+
+	// Source section
+	if ((showAll || stateArgs.code) && data.source?.lines) {
+		console.log("");
+		console.log("Source:");
+		const sourceLines: SourceLine[] = data.source.lines.map((l) => ({
+			lineNumber: l.line,
+			content: l.text,
+			isCurrent: l.current,
+			currentColumn: l.current ? data.location?.column : undefined,
+		}));
+		console.log(formatSource(sourceLines));
+	}
+
+	// Locals section
+	if ((showAll || stateArgs.vars) && data.locals) {
+		console.log("");
+		console.log("Locals:");
+		const vars: Variable[] = data.locals.map((v) => ({
+			ref: v.ref,
+			name: v.name,
+			value: v.value,
+		}));
+		const formatted = formatVariables(vars);
+		if (formatted) {
+			console.log(formatted);
+		} else {
+			console.log("  (no locals)");
+		}
+	}
+
+	// Stack section
+	if ((showAll || stateArgs.stack) && data.stack) {
+		console.log("");
+		console.log("Stack:");
+		const frames: StackFrame[] = data.stack.map((f) => ({
+			ref: f.ref,
+			functionName: f.functionName,
+			file: f.file,
+			line: f.line,
+			column: f.column,
+			isAsync: f.isAsync,
+		}));
+		console.log(formatStack(frames));
+	}
+
+	// Breakpoints section
+	if ((showAll || stateArgs.breakpoints) && data.breakpointCount !== undefined) {
+		console.log("");
+		console.log(`Breakpoints: ${data.breakpointCount} active`);
+	}
+
+	return 0;
+});

package/src/commands/status.ts

@@ -0,0 +1,57 @@
+import { registerCommand } from "../cli/registry.ts";
+import { DaemonClient } from "../daemon/client.ts";
+
+registerCommand("status", async (args) => {
+	const session = args.global.session;
+
+	if (!DaemonClient.isRunning(session)) {
+		console.error(`No active session "${session}"`);
+		console.error("  -> Try: ndbg launch --brk node app.js");
+		return 1;
+	}
+
+	const client = new DaemonClient(session);
+	const response = await client.request("status");
+
+	if (!response.ok) {
+		console.error(`${response.error}`);
+		return 1;
+	}
+
+	const data = response.data as {
+		session: string;
+		state: string;
+		pid?: number;
+		wsUrl?: string;
+		pauseInfo?: {
+			reason: string;
+			url?: string;
+			line?: number;
+			column?: number;
+		};
+		uptime: number;
+		scriptCount: number;
+	};
+
+	if (args.global.json) {
+		console.log(JSON.stringify(data, null, 2));
+	} else {
+		const stateIcon =
+			data.state === "paused" ? "Paused" : data.state === "running" ? "Running" : "Idle";
+		console.log(`${stateIcon} — Session "${data.session}" — ${data.state}`);
+
+		if (data.pid) console.log(`  PID: ${data.pid}`);
+		if (data.wsUrl) console.log(`  Inspector: ${data.wsUrl}`);
+		console.log(`  Uptime: ${Math.round(data.uptime)}s`);
+		console.log(`  Scripts loaded: ${data.scriptCount}`);
+
+		if (data.pauseInfo) {
+			const loc = data.pauseInfo.url
+				? `${data.pauseInfo.url}:${data.pauseInfo.line}${data.pauseInfo.column !== undefined ? `:${data.pauseInfo.column}` : ""}`
+				: "unknown";
+			console.log(`  Paused: ${data.pauseInfo.reason} at ${loc}`);
+		}
+	}
+
+	return 0;
+});

package/src/commands/step.ts

@@ -0,0 +1,50 @@
+import { registerCommand } from "../cli/registry.ts";
+import { DaemonClient } from "../daemon/client.ts";
+import type { SessionStatus } from "../daemon/session.ts";
+
+registerCommand("step", async (args) => {
+	const session = args.global.session;
+
+	if (!DaemonClient.isRunning(session)) {
+		console.error(`No active session "${session}"`);
+		console.error("  -> Try: ndbg launch --brk node app.js");
+		return 1;
+	}
+
+	// The subcommand is the step mode: over, into, or out (default: over)
+	const validModes = new Set(["over", "into", "out"]);
+	const mode = args.subcommand && validModes.has(args.subcommand) ? args.subcommand : "over";
+
+	const client = new DaemonClient(session);
+	const response = await client.request("step", { mode });
+
+	if (!response.ok) {
+		console.error(`${response.error}`);
+		if (response.suggestion) console.error(`  ${response.suggestion}`);
+		return 1;
+	}
+
+	const data = response.data as SessionStatus;
+
+	if (args.global.json) {
+		console.log(JSON.stringify(data, null, 2));
+	} else {
+		printStatus(data);
+	}
+
+	return 0;
+});
+
+function printStatus(data: SessionStatus): void {
+	if (data.state === "paused" && data.pauseInfo) {
+		const col = data.pauseInfo.column !== undefined ? `:${data.pauseInfo.column + 1}` : "";
+		const loc = data.pauseInfo.url
+			? `${data.pauseInfo.url}:${(data.pauseInfo.line ?? 0) + 1}${col}`
+			: "unknown";
+		console.log(`Paused at ${loc} (${data.pauseInfo.reason})`);
+	} else if (data.state === "running") {
+		console.log("Running");
+	} else {
+		console.log(`${data.state}`);
+	}
+}

package/src/commands/stop.ts

@@ -0,0 +1,27 @@
+import { registerCommand } from "../cli/registry.ts";
+import { DaemonClient } from "../daemon/client.ts";
+
+registerCommand("stop", async (args) => {
+	const session = args.global.session;
+
+	if (!DaemonClient.isRunning(session)) {
+		console.error(`No active session "${session}"`);
+		return 1;
+	}
+
+	const client = new DaemonClient(session);
+	const response = await client.request("stop");
+
+	if (!response.ok) {
+		console.error(`${response.error}`);
+		return 1;
+	}
+
+	if (args.global.json) {
+		console.log(JSON.stringify({ ok: true, session }));
+	} else {
+		console.log(`Session "${session}" stopped`);
+	}
+
+	return 0;
+});

package/src/commands/vars.ts

@@ -0,0 +1,71 @@
+import { registerCommand } from "../cli/registry.ts";
+import { DaemonClient } from "../daemon/client.ts";
+import type { Variable } from "../formatter/variables.ts";
+import { formatVariables } from "../formatter/variables.ts";
+
+registerCommand("vars", async (args) => {
+	const session = args.global.session;
+
+	if (!DaemonClient.isRunning(session)) {
+		console.error(`No active session "${session}"`);
+		console.error("  -> Try: ndbg launch --brk node app.js");
+		return 1;
+	}
+
+	// Optional name filter from subcommand + positionals
+	const names: string[] = [];
+	if (args.subcommand) {
+		names.push(args.subcommand);
+	}
+	names.push(...args.positionals);
+
+	const varsArgs: Record<string, unknown> = {};
+
+	if (names.length > 0) {
+		varsArgs.names = names;
+	}
+	if (typeof args.flags.frame === "string") {
+		varsArgs.frame = args.flags.frame;
+	}
+	if (args.flags["all-scopes"] === true) {
+		varsArgs.allScopes = true;
+	}
+
+	const client = new DaemonClient(session);
+	const response = await client.request("vars", varsArgs);
+
+	if (!response.ok) {
+		console.error(`${response.error}`);
+		if (response.suggestion) console.error(`  ${response.suggestion}`);
+		return 1;
+	}
+
+	const data = response.data as Array<{
+		ref: string;
+		name: string;
+		type: string;
+		value: string;
+	}>;
+
+	if (args.global.json) {
+		console.log(JSON.stringify(data, null, 2));
+		return 0;
+	}
+
+	if (data.length === 0) {
+		console.log("(no variables)");
+		return 0;
+	}
+
+	const vars: Variable[] = data.map((v) => ({
+		ref: v.ref,
+		name: v.name,
+		value: v.value,
+	}));
+	const formatted = formatVariables(vars);
+	if (formatted) {
+		console.log(formatted);
+	}
+
+	return 0;
+});