llm-trace 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# llm-trace
+
+When an LLM debugs your code, it can't see what happens at runtime. It reads your source, guesses what went wrong, and asks you to paste error messages. You end up as a middleman — running code, copying output, adding print statements.
+
+llm-trace lets LLMs see runtime behavior directly. They instrument your code with traces, run it, inspect what happened, and fix the bug — without asking you to copy-paste anything.
+
+## Setup
+
+```bash
+npm install llm-trace
+```
+
+Add the [debugging skill](skills/debugging-with-llm-trace/SKILL.md) to your LLM tool (Claude Code, Codex, etc.) so it knows how to use llm-trace.
+
+## How It Works
+
+1. LLM runs `npx llm-trace start` to begin a debugging session
+2. LLM instruments your code with `trace()`, `span()`, and `checkpoint()` calls
+3. You run your code (or LLM runs it)
+4. LLM queries traces with `npx llm-trace list`, `show`, `tail`
+5. LLM reads structured runtime data, identifies root cause, fixes the bug
+6. LLM runs `npx llm-trace stop` to clean up
+
+Traces are ephemeral — they exist only during the debugging session and are deleted when it ends.
+
+## API
+
+### `trace(name, fn)` — wrap a complete operation
+
+```typescript
+import { trace } from "llm-trace";
+
+const result = await trace("handle-request", async (handle) => {
+  // handle.span() and handle.checkpoint() available here
+  return processRequest(req);
+});
+```
+
+### `handle.span(name, fn)` — time a step within a trace
+
+```typescript
+await handle.span("call-llm", async (h) => {
+  const response = await llm.chat(prompt);
+  h.checkpoint("response", response);
+  return response;
+});
+```
+
+### `handle.checkpoint(name, data?)` — snapshot state at a point in time
+
+```typescript
+handle.checkpoint("parsed-input", { tokens: 142 });
+```
+
+Spans nest arbitrarily. Errors are captured automatically. Checkpoint data is truncated at 64KB.
+
+## CLI
+
+| Command | Description |
+|---------|-------------|
+| `llm-trace start` | Begin session, start trace server |
+| `llm-trace stop` | End session, delete all traces |
+| `llm-trace status` | Check if a session is active |
+| `llm-trace list` | List traces (`--errors`, `--name <glob>`, `--last <n>`, `--human`) |
+| `llm-trace show <id>` | Show trace tree (`--human` for readable output) |
+| `llm-trace tail` | Stream new traces (`--errors`, `--name <glob>`) |
+
+Default output is JSON (for LLM consumption). `--human` for readable output.
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TRACE_AI_PORT` | `13579` | HTTP server port |

package/dist/cli.cjs

@@ -0,0 +1,378 @@
+#!/usr/bin/env node
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+let node_child_process = require("node:child_process");
+let node_url = require("node:url");
+
+//#region src/readers/summarize.ts
+function summarizeEvents(events) {
+	const start = events.find((e) => e.type === "trace:start");
+	if (!start) return null;
+	const end = events.find((e) => e.type === "trace:end");
+	return {
+		id: start.id,
+		name: start.name,
+		status: end ? end.status : "in_progress",
+		duration: end ? end.duration : void 0,
+		spans: events.filter((e) => e.type === "span:start").length,
+		ts: start.ts,
+		error: end?.error ? end.error.message : void 0
+	};
+}
+
+//#endregion
+//#region src/readers/tree-builder.ts
+function buildTree(events) {
+	const nodeMap = /* @__PURE__ */ new Map();
+	let root = null;
+	for (const event of events) switch (event.type) {
+		case "trace:start":
+			root = {
+				type: "trace",
+				id: event.id,
+				name: event.name,
+				status: "in_progress",
+				ts: event.ts,
+				children: []
+			};
+			nodeMap.set(event.id, root);
+			break;
+		case "trace:end":
+			if (root) {
+				root.status = event.status;
+				root.duration = event.duration;
+				if (event.error) root.error = event.error;
+			}
+			break;
+		case "span:start": {
+			const node = {
+				type: "span",
+				id: event.id,
+				name: event.name,
+				status: "in_progress",
+				ts: event.ts,
+				children: []
+			};
+			nodeMap.set(event.id, node);
+			const parent = nodeMap.get(event.parent);
+			if (parent) parent.children.push(node);
+			break;
+		}
+		case "span:end": {
+			const node = nodeMap.get(event.id);
+			if (node) {
+				node.status = event.status;
+				node.duration = event.duration;
+				if (event.error) node.error = event.error;
+			}
+			break;
+		}
+		case "checkpoint": {
+			const node = {
+				type: "checkpoint",
+				name: event.name,
+				ts: event.ts,
+				data: event.data,
+				children: []
+			};
+			const parent = nodeMap.get(event.parent);
+			if (parent) parent.children.push(node);
+			break;
+		}
+	}
+	return root ?? {
+		type: "trace",
+		name: "unknown",
+		status: "in_progress",
+		ts: 0,
+		children: []
+	};
+}
+
+//#endregion
+//#region src/readers/ndjson-reader.ts
+function createNdjsonReader(logDir) {
+	function parseFile(filePath) {
+		const content = (0, node_fs.readFileSync)(filePath, "utf-8").trim();
+		if (!content) return [];
+		return content.split("\n").map((line) => JSON.parse(line));
+	}
+	return {
+		async listTraces(options) {
+			const files = (0, node_fs.readdirSync)(logDir).filter((f) => f.endsWith(".ndjson"));
+			let summaries = [];
+			for (const file of files) {
+				const s = summarizeEvents(parseFile((0, node_path.join)(logDir, file)));
+				if (s) summaries.push(s);
+			}
+			summaries.sort((a, b) => b.ts - a.ts);
+			if (options?.errors) summaries = summaries.filter((s) => s.status === "error");
+			if (options?.name) {
+				const re = new RegExp(`^${options.name.replace(/\*/g, ".*")}$`);
+				summaries = summaries.filter((s) => re.test(s.name));
+			}
+			if (options?.last) summaries = summaries.slice(0, options.last);
+			return summaries;
+		},
+		async readTrace(id) {
+			return buildTree(parseFile((0, node_path.join)(logDir, `${id}.ndjson`)));
+		}
+	};
+}
+
+//#endregion
+//#region src/cli/formatter.ts
+function formatTraceList(traces, human) {
+	if (!human) return JSON.stringify(traces, null, 2);
+	if (traces.length === 0) return "No traces found.";
+	const header = "ID                       NAME             STATUS   DURATION  SPANS";
+	const rows = traces.map((t) => {
+		const dur = t.duration !== void 0 ? `${t.duration}ms` : "—";
+		const statusLabel = t.status === "error" ? "ERROR" : t.status;
+		return [
+			t.id.padEnd(24),
+			t.name.padEnd(16),
+			statusLabel.padEnd(8),
+			dur.padEnd(9),
+			t.spans
+		].join(" ");
+	});
+	return [
+		header,
+		"-".repeat(66),
+		...rows
+	].join("\n");
+}
+function formatTraceTree(tree, human) {
+	if (!human) return JSON.stringify(tree, null, 2);
+	const lines = [];
+	function walk(node, indent) {
+		const pad = "  ".repeat(indent);
+		const status = node.status ? ` [${node.status}]` : "";
+		const dur = node.duration !== void 0 ? ` ${node.duration}ms` : "";
+		const data = node.data ? ` ${JSON.stringify(node.data)}` : "";
+		lines.push(`${pad}${node.type}: ${node.name}${status}${dur}${data}`);
+		for (const child of node.children) walk(child, indent + 1);
+	}
+	walk(tree, 0);
+	return lines.join("\n");
+}
+
+//#endregion
+//#region src/cli/commands/list.ts
+async function getFormattedList(logDir, options) {
+	return formatTraceList(await createNdjsonReader(logDir).listTraces({
+		errors: options.errors === true,
+		name: typeof options.name === "string" ? options.name : void 0,
+		last: typeof options.last === "string" ? parseInt(options.last, 10) : void 0
+	}), options.human === true);
+}
+async function runList(options) {
+	const logDir = (0, node_path.join)(process.cwd(), ".trace-ai-logs");
+	if (!(0, node_fs.existsSync)(logDir)) {
+		console.log("No active session.");
+		return;
+	}
+	console.log(await getFormattedList(logDir, options));
+}
+
+//#endregion
+//#region src/cli/commands/show.ts
+async function runShow(id, options) {
+	const logDir = (0, node_path.join)(process.cwd(), ".trace-ai-logs");
+	if (!(0, node_fs.existsSync)(logDir)) {
+		console.log("No active session.");
+		return;
+	}
+	const tree = await createNdjsonReader(logDir).readTrace(id);
+	console.log(formatTraceTree(tree, options.human === true));
+}
+
+//#endregion
+//#region src/cli/commands/start.ts
+async function startSession(projectDir, options = {}) {
+	const logDir = (0, node_path.join)(projectDir, ".trace-ai-logs");
+	if ((0, node_fs.existsSync)(logDir)) return {
+		created: false,
+		reason: "already_active"
+	};
+	(0, node_fs.mkdirSync)(logDir, { recursive: true });
+	const gitignorePath = (0, node_path.join)(projectDir, ".gitignore");
+	if ((0, node_fs.existsSync)(gitignorePath)) {
+		if (!(0, node_fs.readFileSync)(gitignorePath, "utf-8").includes(".trace-ai-logs/")) (0, node_fs.appendFileSync)(gitignorePath, "\n.trace-ai-logs/\n");
+	} else (0, node_fs.writeFileSync)(gitignorePath, ".trace-ai-logs/\n");
+	if (!options.skipServer) {
+		const port = parseInt(process.env.TRACE_AI_PORT || "", 10) || 13579;
+		const script = (0, node_path.join)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href), "..", "standalone.js");
+		const child = (0, node_child_process.spawn)(process.execPath, [script], {
+			detached: true,
+			stdio: "ignore",
+			env: {
+				...process.env,
+				TRACE_AI_PORT: String(port),
+				TRACE_AI_DIR: logDir
+			}
+		});
+		child.unref();
+		(0, node_fs.writeFileSync)((0, node_path.join)(logDir, ".server"), JSON.stringify({
+			pid: child.pid,
+			port
+		}));
+		return {
+			created: true,
+			port
+		};
+	}
+	return { created: true };
+}
+async function runStart() {
+	const result = await startSession(process.cwd());
+	if (!result.created) console.log("Session already active.");
+	else console.log(`Session started.${result.port ? ` Browser server on port ${result.port}.` : ""}`);
+}
+
+//#endregion
+//#region src/cli/commands/status.ts
+function getSessionStatus(projectDir) {
+	const logDir = (0, node_path.join)(projectDir, ".trace-ai-logs");
+	if (!(0, node_fs.existsSync)(logDir)) return { active: false };
+	const files = (0, node_fs.readdirSync)(logDir).filter((f) => f.endsWith(".ndjson"));
+	let errorCount = 0;
+	for (const file of files) if ((0, node_fs.readFileSync)((0, node_path.join)(logDir, file), "utf-8").includes("\"status\":\"error\"")) errorCount++;
+	let serverPort;
+	const serverFile = (0, node_path.join)(logDir, ".server");
+	if ((0, node_fs.existsSync)(serverFile)) try {
+		serverPort = JSON.parse((0, node_fs.readFileSync)(serverFile, "utf-8")).port;
+	} catch {}
+	return {
+		active: true,
+		traceCount: files.length,
+		errorCount,
+		serverPort
+	};
+}
+async function runStatus() {
+	const status = getSessionStatus(process.cwd());
+	if (!status.active) {
+		console.log("No active session.");
+		return;
+	}
+	console.log(`Session active.\nTraces: ${status.traceCount} (${status.errorCount} errors)`);
+	if (status.serverPort) console.log(`Browser server: port ${status.serverPort}`);
+}
+
+//#endregion
+//#region src/cli/commands/stop.ts
+async function stopSession(projectDir) {
+	const logDir = (0, node_path.join)(projectDir, ".trace-ai-logs");
+	if (!(0, node_fs.existsSync)(logDir)) return {
+		stopped: false,
+		reason: "no_session"
+	};
+	const serverFile = (0, node_path.join)(logDir, ".server");
+	if ((0, node_fs.existsSync)(serverFile)) try {
+		const { pid } = JSON.parse((0, node_fs.readFileSync)(serverFile, "utf-8"));
+		if (pid) process.kill(pid, "SIGTERM");
+	} catch {}
+	(0, node_fs.rmSync)(logDir, { recursive: true });
+	return { stopped: true };
+}
+async function runStop() {
+	if (!(await stopSession(process.cwd())).stopped) console.log("No active session.");
+	else console.log("Session stopped. All traces deleted.");
+}
+
+//#endregion
+//#region src/cli/commands/tail.ts
+function summarizeFile(filePath) {
+	try {
+		const content = (0, node_fs.readFileSync)(filePath, "utf-8").trim();
+		if (!content) return null;
+		return summarizeEvents(content.split("\n").map((l) => JSON.parse(l)));
+	} catch {
+		return null;
+	}
+}
+async function runTail(options) {
+	const logDir = (0, node_path.join)(process.cwd(), ".trace-ai-logs");
+	if (!(0, node_fs.existsSync)(logDir)) {
+		console.log("No active session.");
+		return;
+	}
+	console.log("Watching for traces... (Ctrl+C to stop)");
+	const seen = new Set((0, node_fs.readdirSync)(logDir).filter((f) => f.endsWith(".ndjson")));
+	(0, node_fs.watch)(logDir, (_event, filename) => {
+		if (!filename || !filename.endsWith(".ndjson")) return;
+		const summary = summarizeFile((0, node_path.join)(logDir, filename));
+		if (!summary) return;
+		if (options.errors === true && summary.status !== "error") return;
+		if (typeof options.name === "string") {
+			if (!new RegExp(`^${options.name.replace(/\*/g, ".*")}$`).test(summary.name)) return;
+		}
+		if (summary.status !== "in_progress" || !seen.has(filename)) {
+			seen.add(filename);
+			console.log(JSON.stringify(summary));
+		}
+	});
+	await new Promise(() => {});
+}
+
+//#endregion
+//#region src/cli/parse-args.ts
+function parseCliArgs(argv) {
+	const command = argv[0] || "help";
+	const options = {};
+	let id;
+	for (let i = 1; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg.startsWith("--")) {
+			const key = arg.slice(2);
+			const next = argv[i + 1];
+			if (next && !next.startsWith("--")) {
+				options[key] = next;
+				i++;
+			} else options[key] = true;
+		} else if (!id) id = arg;
+	}
+	return {
+		command,
+		id,
+		options
+	};
+}
+
+//#endregion
+//#region src/cli/index.ts
+const HELP = `trace-ai — Structured execution traces for LLM debugging
+
+Usage:
+  trace-ai start              Begin debugging session
+  trace-ai stop               End session, delete traces
+  trace-ai status             Show session info
+  trace-ai list [--errors] [--name <pattern>] [--last <n>] [--human]
+  trace-ai show <id> [--human]
+  trace-ai tail [--errors] [--name <pattern>]
+`;
+async function main() {
+	const { command, id, options } = parseCliArgs(process.argv.slice(2));
+	switch (command) {
+		case "start": return runStart();
+		case "stop": return runStop();
+		case "status": return runStatus();
+		case "list": return runList(options);
+		case "show":
+			if (!id) {
+				console.error("Usage: trace-ai show <id>");
+				process.exit(1);
+			}
+			return runShow(id, options);
+		case "tail": return runTail(options);
+		default: console.log(HELP);
+	}
+}
+main().catch((err) => {
+	console.error(err.message);
+	process.exit(1);
+});
+
+//#endregion

package/dist/cli.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export { };