@os-eco/overstory-cli 0.6.1

package/src/logging/logger.ts

@@ -0,0 +1,266 @@
+/**
+ * Multi-format logger that writes to multiple outputs simultaneously.
+ *
+ * Output files (all created in the provided logDir):
+ * - session.log    — Human-readable: [TIMESTAMP] EVENT key=value
+ * - events.ndjson  — Machine-parseable NDJSON stream (all events)
+ * - tools.ndjson   — Tool use log (toolStart / toolEnd events only)
+ * - errors.log     — Stack traces with context (error events only)
+ *
+ * Log directory structure: .overstory/logs/{agent-name}/{session-timestamp}/
+ */
+
+import { appendFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { LogEvent } from "../types.ts";
+import { printToConsole } from "./reporter.ts";
+import { sanitize, sanitizeObject } from "./sanitizer.ts";
+
+export interface Logger {
+	info(event: string, data?: Record<string, unknown>): void;
+	warn(event: string, data?: Record<string, unknown>): void;
+	error(event: string, error: Error, data?: Record<string, unknown>): void;
+	debug(event: string, data?: Record<string, unknown>): void;
+	toolStart(toolName: string, args: Record<string, unknown>): void;
+	toolEnd(toolName: string, durationMs: number, result?: string): void;
+	close(): void;
+}
+
+interface LoggerOptions {
+	logDir: string;
+	agentName: string;
+	verbose?: boolean;
+	redactSecrets?: boolean;
+}
+
+/**
+ * Create a multi-format logger that writes to session.log, events.ndjson,
+ * tools.ndjson, and errors.log simultaneously.
+ *
+ * The logDir is created if it does not exist. All writes are fire-and-forget
+ * (errors during file I/O are silently ignored to avoid log-induced crashes).
+ */
+export function createLogger(options: LoggerOptions): Logger {
+	const { logDir, agentName, verbose = false, redactSecrets = true } = options;
+
+	const sessionLogPath = join(logDir, "session.log");
+	const eventsPath = join(logDir, "events.ndjson");
+	const toolsPath = join(logDir, "tools.ndjson");
+	const errorsPath = join(logDir, "errors.log");
+
+	// Pending writes queue. We chain promises to guarantee ordering
+	// within each file, but different files write independently.
+	let dirReady: Promise<void> | null = null;
+	let closed = false;
+
+	/**
+	 * Ensure the log directory exists. Called lazily on first write.
+	 * Subsequent calls return the cached promise.
+	 */
+	function ensureDir(): Promise<void> {
+		if (dirReady === null) {
+			dirReady = mkdir(logDir, { recursive: true }).then(() => undefined);
+		}
+		return dirReady;
+	}
+
+	/**
+	 * Append text to a file, ensuring the directory exists first.
+	 * Errors are silently swallowed — logging must never crash the app.
+	 */
+	function safeAppend(filePath: string, content: string): void {
+		if (closed) return;
+		ensureDir()
+			.then(() => appendFile(filePath, content, "utf-8"))
+			.catch(() => {
+				// Silently ignore write errors — logging should never crash the host
+			});
+	}
+
+	/**
+	 * Conditionally redact secrets from a string.
+	 */
+	function maybeRedact(input: string): string {
+		return redactSecrets ? sanitize(input) : input;
+	}
+
+	/**
+	 * Conditionally redact secrets from an object.
+	 */
+	function maybeRedactObject(obj: Record<string, unknown>): Record<string, unknown> {
+		return redactSecrets ? sanitizeObject(obj) : obj;
+	}
+
+	/**
+	 * Build a LogEvent and dispatch it to all relevant outputs.
+	 */
+	function emit(
+		level: LogEvent["level"],
+		event: string,
+		data: Record<string, unknown>,
+		error?: Error,
+	): void {
+		const safeData = maybeRedactObject(data);
+
+		const logEvent: LogEvent = {
+			timestamp: new Date().toISOString(),
+			level,
+			event,
+			agentName,
+			data: safeData,
+		};
+
+		// 1. Console output
+		printToConsole(logEvent, verbose);
+
+		// 2. session.log — human-readable line
+		const kvPairs = formatKeyValues(safeData);
+		const kvSuffix = kvPairs.length > 0 ? ` ${kvPairs}` : "";
+		const sessionLine = `[${logEvent.timestamp}] ${level.toUpperCase()} ${event}${kvSuffix}\n`;
+		safeAppend(sessionLogPath, sessionLine);
+
+		// 3. events.ndjson — full event as JSON
+		safeAppend(eventsPath, `${JSON.stringify(logEvent)}\n`);
+
+		// 4. errors.log — stack traces with context (error level only)
+		if (level === "error" && error) {
+			const errorBlock = buildErrorBlock(logEvent, error);
+			safeAppend(errorsPath, errorBlock);
+		}
+	}
+
+	/**
+	 * Emit a tool event to the tools.ndjson file (and also to events.ndjson).
+	 */
+	function emitTool(event: string, data: Record<string, unknown>): void {
+		const safeData = maybeRedactObject(data);
+
+		const logEvent: LogEvent = {
+			timestamp: new Date().toISOString(),
+			level: "info",
+			event,
+			agentName,
+			data: safeData,
+		};
+
+		// Console output
+		printToConsole(logEvent, verbose);
+
+		// events.ndjson
+		safeAppend(eventsPath, `${JSON.stringify(logEvent)}\n`);
+
+		// tools.ndjson
+		safeAppend(toolsPath, `${JSON.stringify(logEvent)}\n`);
+
+		// session.log
+		const kvPairs = formatKeyValues(safeData);
+		const kvSuffix = kvPairs.length > 0 ? ` ${kvPairs}` : "";
+		const sessionLine = `[${logEvent.timestamp}] INFO ${event}${kvSuffix}\n`;
+		safeAppend(sessionLogPath, sessionLine);
+	}
+
+	return {
+		info(event: string, data?: Record<string, unknown>): void {
+			emit("info", event, data ?? {});
+		},
+
+		warn(event: string, data?: Record<string, unknown>): void {
+			emit("warn", event, data ?? {});
+		},
+
+		error(event: string, err: Error, data?: Record<string, unknown>): void {
+			const errorData: Record<string, unknown> = {
+				...data,
+				errorMessage: maybeRedact(err.message),
+				errorName: err.name,
+			};
+			emit("error", event, errorData, err);
+		},
+
+		debug(event: string, data?: Record<string, unknown>): void {
+			emit("debug", event, data ?? {});
+		},
+
+		toolStart(toolName: string, args: Record<string, unknown>): void {
+			emitTool("tool.start", { toolName, args });
+		},
+
+		toolEnd(toolName: string, durationMs: number, result?: string): void {
+			const data: Record<string, unknown> = { toolName, durationMs };
+			if (result !== undefined) {
+				data.result = maybeRedact(result);
+			}
+			emitTool("tool.end", data);
+		},
+
+		close(): void {
+			closed = true;
+		},
+	};
+}
+
+/**
+ * Format a data record as space-separated key=value pairs for session.log.
+ */
+function formatKeyValues(data: Record<string, unknown>): string {
+	const entries = Object.entries(data);
+	if (entries.length === 0) {
+		return "";
+	}
+
+	return entries
+		.map(([key, value]) => {
+			if (value === undefined || value === null) {
+				return `${key}=null`;
+			}
+			if (typeof value === "string") {
+				return value.includes(" ") ? `${key}="${value}"` : `${key}=${value}`;
+			}
+			if (typeof value === "object") {
+				return `${key}=${JSON.stringify(value)}`;
+			}
+			return `${key}=${String(value)}`;
+		})
+		.join(" ");
+}
+
+/**
+ * Build a multi-line error block for errors.log.
+ */
+function buildErrorBlock(event: LogEvent, error: Error): string {
+	const separator = "=".repeat(72);
+	const lines: string[] = [
+		separator,
+		`Timestamp: ${event.timestamp}`,
+		`Event:     ${event.event}`,
+		`Agent:     ${event.agentName ?? "unknown"}`,
+	];
+
+	// Include data fields
+	const dataEntries = Object.entries(event.data);
+	if (dataEntries.length > 0) {
+		lines.push(`Data:      ${JSON.stringify(event.data)}`);
+	}
+
+	lines.push("");
+	lines.push(`Error:     ${error.name}: ${error.message}`);
+
+	if (error.stack) {
+		lines.push("");
+		lines.push("Stack Trace:");
+		lines.push(error.stack);
+	}
+
+	if (error.cause instanceof Error) {
+		lines.push("");
+		lines.push(`Caused by: ${error.cause.name}: ${error.cause.message}`);
+		if (error.cause.stack) {
+			lines.push(error.cause.stack);
+		}
+	}
+
+	lines.push(separator);
+	lines.push("");
+
+	return lines.join("\n");
+}

package/src/logging/reporter.test.ts

@@ -0,0 +1,259 @@
+import { afterEach, describe, expect, spyOn, test } from "bun:test";
+import type { LogEvent } from "../types.ts";
+import { formatLogLine, printToConsole } from "./reporter.ts";
+
+// Helper to build a LogEvent with sensible defaults
+function makeEvent(overrides: Partial<LogEvent> = {}): LogEvent {
+	return {
+		timestamp: "2026-02-13T14:30:00.123Z",
+		level: "info",
+		event: "test.event",
+		agentName: "test-agent",
+		data: {},
+		...overrides,
+	};
+}
+
+describe("formatLogLine", () => {
+	test("uses DBG label for debug level", () => {
+		const result = formatLogLine(makeEvent({ level: "debug" }));
+		expect(result).toContain("DBG");
+	});
+
+	test("uses INF label for info level", () => {
+		const result = formatLogLine(makeEvent({ level: "info" }));
+		expect(result).toContain("INF");
+	});
+
+	test("uses WRN label for warn level", () => {
+		const result = formatLogLine(makeEvent({ level: "warn" }));
+		expect(result).toContain("WRN");
+	});
+
+	test("uses ERR label for error level", () => {
+		const result = formatLogLine(makeEvent({ level: "error" }));
+		expect(result).toContain("ERR");
+	});
+
+	test("includes agent name and separator when present", () => {
+		const result = formatLogLine(makeEvent({ agentName: "scout-1" }));
+		expect(result).toContain("scout-1");
+		expect(result).toContain(" | ");
+	});
+
+	test("omits agent name and separator when null", () => {
+		const result = formatLogLine(makeEvent({ agentName: null }));
+		expect(result).not.toContain(" | ");
+	});
+
+	test("includes event name in output", () => {
+		const result = formatLogLine(makeEvent({ event: "agent.started" }));
+		expect(result).toContain("agent.started");
+	});
+
+	test("formats string data values as key=value", () => {
+		const result = formatLogLine(makeEvent({ data: { status: "ok" } }));
+		expect(result).toContain("status=ok");
+	});
+
+	test("formats number data values as key=value", () => {
+		const result = formatLogLine(makeEvent({ data: { duration: 5000 } }));
+		expect(result).toContain("duration=5000");
+	});
+
+	test("formats object data values as JSON", () => {
+		const result = formatLogLine(makeEvent({ data: { config: { enabled: true, timeout: 5000 } } }));
+		expect(result).toContain('config={"enabled":true,"timeout":5000}');
+	});
+
+	test("formats null data values as key=null", () => {
+		const result = formatLogLine(makeEvent({ data: { value: null } }));
+		expect(result).toContain("value=null");
+	});
+
+	test("formats undefined data values as key=null", () => {
+		const result = formatLogLine(makeEvent({ data: { value: undefined } }));
+		expect(result).toContain("value=null");
+	});
+
+	test("quotes string data values containing spaces", () => {
+		const result = formatLogLine(makeEvent({ data: { message: "hello world", status: "ok" } }));
+		expect(result).toContain('message="hello world"');
+		expect(result).toContain("status=ok");
+	});
+
+	test("handles multiple data key=value pairs", () => {
+		const result = formatLogLine(makeEvent({ data: { taskId: "task-123", duration: 5000 } }));
+		expect(result).toContain("taskId=task-123");
+		expect(result).toContain("duration=5000");
+	});
+
+	test("produces no data suffix for empty data object", () => {
+		const result = formatLogLine(makeEvent({ data: {} }));
+		// The event name should be at the end with no trailing key=value content
+		expect(result).toContain("test.event");
+		// No equals sign means no key=value pairs present
+		expect(result).not.toMatch(/\w+=\S/);
+	});
+
+	test("extracts HH:MM:SS time from ISO timestamp", () => {
+		const result = formatLogLine(makeEvent({ timestamp: "2026-02-13T14:30:00.123Z" }));
+		expect(result).toContain("[14:30:00]");
+	});
+
+	test("falls back to raw timestamp when no T separator", () => {
+		const result = formatLogLine(makeEvent({ timestamp: "invalid-timestamp" }));
+		expect(result).toContain("[invalid-timestamp]");
+	});
+
+	test("contains ANSI escape codes in output", () => {
+		const result = formatLogLine(makeEvent());
+		// \x1b[ is the ANSI escape sequence prefix
+		expect(result).toContain("\x1b[");
+		// Reset sequence should appear at least once
+		expect(result).toContain("\x1b[0m");
+	});
+
+	test("uses different ANSI color codes for different levels", () => {
+		const debugResult = formatLogLine(makeEvent({ level: "debug" }));
+		const infoResult = formatLogLine(makeEvent({ level: "info" }));
+		const warnResult = formatLogLine(makeEvent({ level: "warn" }));
+		const errorResult = formatLogLine(makeEvent({ level: "error" }));
+
+		// Each level uses a distinct color: gray(90), blue(34), yellow(33), red(31)
+		expect(debugResult).toContain("\x1b[90m");
+		expect(infoResult).toContain("\x1b[34m");
+		expect(warnResult).toContain("\x1b[33m");
+		expect(errorResult).toContain("\x1b[31m");
+	});
+
+	test("formats boolean data values via String()", () => {
+		const result = formatLogLine(makeEvent({ data: { enabled: true } }));
+		expect(result).toContain("enabled=true");
+	});
+});
+
+describe("printToConsole", () => {
+	let logSpy: ReturnType<typeof spyOn>;
+	let errorSpy: ReturnType<typeof spyOn>;
+
+	afterEach(() => {
+		logSpy?.mockRestore();
+		errorSpy?.mockRestore();
+	});
+
+	test("sends info events to console.log", () => {
+		logSpy = spyOn(console, "log").mockImplementation(() => {});
+		errorSpy = spyOn(console, "error").mockImplementation(() => {});
+		// Clear any calls captured during spy setup (bun's test reporter
+		// may flush output through console.log between spy creation and here)
+		logSpy.mockClear();
+		errorSpy.mockClear();
+
+		printToConsole(makeEvent({ level: "info" }), true);
+
+		expect(logSpy).toHaveBeenCalledTimes(1);
+		expect(errorSpy).toHaveBeenCalledTimes(0);
+	});
+
+	test("sends warn events to console.log", () => {
+		logSpy = spyOn(console, "log").mockImplementation(() => {});
+		errorSpy = spyOn(console, "error").mockImplementation(() => {});
+		logSpy.mockClear();
+		errorSpy.mockClear();
+
+		printToConsole(makeEvent({ level: "warn" }), false);
+
+		expect(logSpy).toHaveBeenCalledTimes(1);
+		expect(errorSpy).toHaveBeenCalledTimes(0);
+	});
+
+	test("sends error events to console.error", () => {
+		logSpy = spyOn(console, "log").mockImplementation(() => {});
+		errorSpy = spyOn(console, "error").mockImplementation(() => {});
+		logSpy.mockClear();
+		errorSpy.mockClear();
+
+		printToConsole(makeEvent({ level: "error" }), false);
+
+		expect(logSpy).toHaveBeenCalledTimes(0);
+		expect(errorSpy).toHaveBeenCalledTimes(1);
+	});
+
+	test("suppresses debug events when verbose is false", () => {
+		logSpy = spyOn(console, "log").mockImplementation(() => {});
+		errorSpy = spyOn(console, "error").mockImplementation(() => {});
+		logSpy.mockClear();
+		errorSpy.mockClear();
+
+		printToConsole(makeEvent({ level: "debug" }), false);
+
+		expect(logSpy).toHaveBeenCalledTimes(0);
+		expect(errorSpy).toHaveBeenCalledTimes(0);
+	});
+
+	test("shows debug events when verbose is true", () => {
+		logSpy = spyOn(console, "log").mockImplementation(() => {});
+		errorSpy = spyOn(console, "error").mockImplementation(() => {});
+		logSpy.mockClear();
+		errorSpy.mockClear();
+
+		printToConsole(makeEvent({ level: "debug" }), true);
+
+		expect(logSpy).toHaveBeenCalledTimes(1);
+		expect(errorSpy).toHaveBeenCalledTimes(0);
+	});
+
+	test("passes formatted line to console method", () => {
+		logSpy = spyOn(console, "log").mockImplementation(() => {});
+		errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+		const event = makeEvent({ level: "info", event: "my.custom.event" });
+		printToConsole(event, true);
+
+		const calledWith = logSpy.mock.calls[0]?.[0] as string;
+		expect(calledWith).toContain("my.custom.event");
+		expect(calledWith).toContain("INF");
+	});
+
+	test("error event output contains the formatted line", () => {
+		logSpy = spyOn(console, "log").mockImplementation(() => {});
+		errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+		const event = makeEvent({ level: "error", event: "fatal.crash" });
+		printToConsole(event, false);
+
+		const calledWith = errorSpy.mock.calls[0]?.[0] as string;
+		expect(calledWith).toContain("fatal.crash");
+		expect(calledWith).toContain("ERR");
+	});
+
+	test("suppresses non-error output when quiet mode is enabled", () => {
+		const { setQuiet } = require("./color.ts") as { setQuiet: (enabled: boolean) => void };
+
+		logSpy = spyOn(console, "log").mockImplementation(() => {});
+		errorSpy = spyOn(console, "error").mockImplementation(() => {});
+		logSpy.mockClear();
+		errorSpy.mockClear();
+
+		// Enable quiet mode
+		setQuiet(true);
+
+		// info, warn, debug should all be suppressed
+		printToConsole(makeEvent({ level: "info" }), true);
+		printToConsole(makeEvent({ level: "warn" }), true);
+		printToConsole(makeEvent({ level: "debug" }), true);
+
+		expect(logSpy).toHaveBeenCalledTimes(0);
+		expect(errorSpy).toHaveBeenCalledTimes(0);
+
+		// errors should still be output
+		printToConsole(makeEvent({ level: "error" }), true);
+
+		expect(logSpy).toHaveBeenCalledTimes(0);
+		expect(errorSpy).toHaveBeenCalledTimes(1);
+
+		// Restore quiet mode
+		setQuiet(false);
+	});
+});

package/src/logging/reporter.ts

@@ -0,0 +1,109 @@
+/**
+ * Console reporter with ANSI colors for human-readable log output.
+ *
+ * Formats LogEvent objects into colored terminal output.
+ * Uses ANSI escape codes directly (no external dependencies).
+ */
+
+import type { LogEvent } from "../types.ts";
+import { color, isQuiet } from "./color.ts";
+
+const LEVEL_COLORS: Record<LogEvent["level"], string> = {
+	debug: color.gray,
+	info: color.blue,
+	warn: color.yellow,
+	error: color.red,
+};
+
+const LEVEL_LABELS: Record<LogEvent["level"], string> = {
+	debug: "DBG",
+	info: "INF",
+	warn: "WRN",
+	error: "ERR",
+};
+
+/**
+ * Format a LogEvent into a single human-readable line with ANSI colors.
+ *
+ * Format: `[HH:MM:SS] LVL agent | event key=value key=value`
+ */
+export function formatLogLine(event: LogEvent): string {
+	const levelColor = LEVEL_COLORS[event.level];
+	const label = LEVEL_LABELS[event.level];
+
+	// Extract just the time portion for compact display
+	const time = extractTime(event.timestamp);
+
+	// Build the agent prefix
+	const agentPart = event.agentName ? `${color.dim}${event.agentName}${color.reset} | ` : "";
+
+	// Build key=value pairs from data
+	const dataPart = formatData(event.data);
+	const dataSuffix = dataPart.length > 0 ? ` ${color.dim}${dataPart}${color.reset}` : "";
+
+	return `${color.dim}[${time}]${color.reset} ${levelColor}${color.bold}${label}${color.reset} ${agentPart}${event.event}${dataSuffix}`;
+}
+
+/**
+ * Print a LogEvent to the console, respecting verbose mode and quiet mode.
+ *
+ * When verbose is false, debug-level events are suppressed.
+ * When quiet mode is active, non-error events are suppressed.
+ * Errors go to stderr; everything else goes to stdout.
+ */
+export function printToConsole(event: LogEvent, verbose: boolean): void {
+	if (isQuiet() && event.level !== "error") {
+		return;
+	}
+	if (!verbose && event.level === "debug") {
+		return;
+	}
+
+	const line = formatLogLine(event);
+
+	if (event.level === "error") {
+		console.error(line);
+	} else {
+		console.log(line);
+	}
+}
+
+/**
+ * Extract the HH:MM:SS portion from an ISO timestamp.
+ * Falls back to the raw timestamp if parsing fails.
+ */
+function extractTime(timestamp: string): string {
+	// ISO 8601: "2024-01-15T14:30:00.123Z" -> "14:30:00"
+	const match = /T(\d{2}:\d{2}:\d{2})/.exec(timestamp);
+	if (match?.[1]) {
+		return match[1];
+	}
+	return timestamp;
+}
+
+/**
+ * Format a data record as space-separated key=value pairs.
+ * Handles nested objects by JSON-stringifying them.
+ */
+function formatData(data: Record<string, unknown>): string {
+	const entries = Object.entries(data);
+	if (entries.length === 0) {
+		return "";
+	}
+
+	return entries
+		.map(([key, value]) => {
+			if (value === undefined || value === null) {
+				return `${key}=null`;
+			}
+			if (typeof value === "string") {
+				// Quote strings that contain spaces
+				return value.includes(" ") ? `${key}="${value}"` : `${key}=${value}`;
+			}
+			if (typeof value === "object") {
+				return `${key}=${JSON.stringify(value)}`;
+			}
+			return `${key}=${String(value)}`;
+		})
+		.join(" ");
+}