@os-eco/overstory-cli 0.6.10 → 0.7.0

package/src/logging/format.ts

@@ -0,0 +1,214 @@
+/**
+ * Shared formatting utilities for overstory CLI output.
+ *
+ * Duration, timestamp, event detail, agent color mapping, and status color
+ * helpers used across all observability commands.
+ */
+
+import type { StoredEvent } from "../types.ts";
+import type { ColorFn } from "./color.ts";
+import { color, noColor } from "./color.ts";
+import { AGENT_COLORS } from "./theme.ts";
+
+// === Duration ===
+
+/**
+ * Formats a duration in milliseconds to a human-readable string.
+ * Examples: "0s", "12s", "3m 45s", "2h 15m"
+ */
+export function formatDuration(ms: number): string {
+	if (ms === 0) return "0s";
+	const totalSeconds = Math.floor(ms / 1000);
+	const hours = Math.floor(totalSeconds / 3600);
+	const minutes = Math.floor((totalSeconds % 3600) / 60);
+	const seconds = totalSeconds % 60;
+	if (hours > 0) {
+		return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+	}
+	if (minutes > 0) {
+		return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+	}
+	return `${seconds}s`;
+}
+
+// === Timestamps ===
+
+/**
+ * Extracts "HH:MM:SS" from an ISO 8601 timestamp string.
+ * Returns the raw substring if the timestamp is well-formed.
+ */
+export function formatAbsoluteTime(timestamp: string): string {
+	// ISO format: "YYYY-MM-DDTHH:MM:SS..." or "YYYY-MM-DD HH:MM:SS..."
+	const match = timestamp.match(/T?(\d{2}:\d{2}:\d{2})/);
+	return match?.[1] ?? timestamp;
+}
+
+/**
+ * Extracts "YYYY-MM-DD" from an ISO 8601 timestamp string.
+ */
+export function formatDate(timestamp: string): string {
+	const match = timestamp.match(/^(\d{4}-\d{2}-\d{2})/);
+	return match?.[1] ?? timestamp;
+}
+
+/**
+ * Formats a timestamp as a human-readable relative time string.
+ * Examples: "12s ago", "3m ago", "2h ago", "5d ago"
+ */
+export function formatRelativeTime(timestamp: string): string {
+	const now = Date.now();
+	const then = new Date(timestamp).getTime();
+	const diffMs = now - then;
+	if (diffMs < 0) return "just now";
+	const diffSeconds = Math.floor(diffMs / 1000);
+	const diffMinutes = Math.floor(diffSeconds / 60);
+	const diffHours = Math.floor(diffMinutes / 60);
+	const diffDays = Math.floor(diffHours / 24);
+	if (diffDays > 0) return `${diffDays}d ago`;
+	if (diffHours > 0) return `${diffHours}h ago`;
+	if (diffMinutes > 0) return `${diffMinutes}m ago`;
+	return `${diffSeconds}s ago`;
+}
+
+// === Event Details ===
+
+/**
+ * Builds a compact "key=value" detail string from a StoredEvent's fields.
+ * Values are truncated to maxValueLen (default 80) characters.
+ */
+export function buildEventDetail(event: StoredEvent, maxValueLen = 80): string {
+	const parts: string[] = [];
+
+	if (event.toolName) {
+		parts.push(`tool=${event.toolName}`);
+	}
+	if (event.toolArgs) {
+		const truncated =
+			event.toolArgs.length > maxValueLen
+				? `${event.toolArgs.slice(0, maxValueLen)}…`
+				: event.toolArgs;
+		parts.push(`args=${truncated}`);
+	}
+	if (event.toolDurationMs !== null && event.toolDurationMs !== undefined) {
+		parts.push(`dur=${event.toolDurationMs}ms`);
+	}
+	if (event.data) {
+		const truncated =
+			event.data.length > maxValueLen ? `${event.data.slice(0, maxValueLen)}…` : event.data;
+		parts.push(`data=${truncated}`);
+	}
+
+	return parts.join(" ");
+}
+
+// === Agent Color Mapping ===
+
+/**
+ * Builds a stable color map for agents by first-appearance order in events.
+ * Agents are assigned colors from AGENT_COLORS cycling as needed.
+ */
+export function buildAgentColorMap(events: StoredEvent[]): Map<string, ColorFn> {
+	const colorMap = new Map<string, ColorFn>();
+	let idx = 0;
+	for (const event of events) {
+		if (!colorMap.has(event.agentName)) {
+			const colorFn = AGENT_COLORS[idx % AGENT_COLORS.length] ?? noColor;
+			colorMap.set(event.agentName, colorFn);
+			idx++;
+		}
+	}
+	return colorMap;
+}
+
+/**
+ * Extends an existing agent color map with new agents from the given events.
+ * Used in follow mode to add agents discovered in incremental event batches.
+ */
+export function extendAgentColorMap(colorMap: Map<string, ColorFn>, events: StoredEvent[]): void {
+	let idx = colorMap.size;
+	for (const event of events) {
+		if (!colorMap.has(event.agentName)) {
+			const colorFn = AGENT_COLORS[idx % AGENT_COLORS.length] ?? noColor;
+			colorMap.set(event.agentName, colorFn);
+			idx++;
+		}
+	}
+}
+
+// === Status Colors ===
+
+/**
+ * Returns a color function for a merge status string.
+ * pending=yellow, merging=blue, conflict=red, merged=green
+ */
+export function mergeStatusColor(status: string): ColorFn {
+	switch (status) {
+		case "pending":
+			return color.yellow;
+		case "merging":
+			return color.blue;
+		case "conflict":
+			return color.red;
+		case "merged":
+			return color.green;
+		default:
+			return (text: string) => text;
+	}
+}
+
+/**
+ * Returns a color function for a priority string.
+ * urgent=red, high=yellow, normal=identity, low=dim
+ */
+export function priorityColor(priority: string): ColorFn {
+	switch (priority) {
+		case "urgent":
+			return color.red;
+		case "high":
+			return color.yellow;
+		case "normal":
+			return (text: string) => text;
+		case "low":
+			return color.dim;
+		default:
+			return (text: string) => text;
+	}
+}
+
+/**
+ * Returns a color function for a log level string.
+ * debug=gray, info=blue, warn=yellow, error=red
+ */
+export function logLevelColor(level: string): ColorFn {
+	switch (level) {
+		case "debug":
+			return color.gray;
+		case "info":
+			return color.blue;
+		case "warn":
+			return color.yellow;
+		case "error":
+			return color.red;
+		default:
+			return (text: string) => text;
+	}
+}
+
+/**
+ * Returns a 3-character label for a log level string.
+ * debug="DBG", info="INF", warn="WRN", error="ERR"
+ */
+export function logLevelLabel(level: string): string {
+	switch (level) {
+		case "debug":
+			return "DBG";
+		case "info":
+			return "INF";
+		case "warn":
+			return "WRN";
+		case "error":
+			return "ERR";
+		default:
+			return level.slice(0, 3).toUpperCase();
+	}
+}

package/src/logging/theme.ts

@@ -0,0 +1,132 @@
+/**
+ * Canonical visual theme for overstory CLI output.
+ *
+ * Single source of truth for state colors, event labels, agent palette,
+ * separators, and header rendering. All observability commands import from here.
+ */
+
+import type { AgentState, EventType } from "../types.ts";
+import type { ColorFn } from "./color.ts";
+import { brand, color, noColor, visibleLength } from "./color.ts";
+
+// === Agent State Theme ===
+
+/** Maps agent states to their visual color functions. */
+const STATE_COLORS: Record<AgentState, ColorFn> = {
+	working: color.green,
+	booting: color.yellow,
+	stalled: color.red,
+	zombie: color.dim,
+	completed: color.cyan,
+};
+
+/** Maps agent states to their icon characters. */
+const STATE_ICONS: Record<AgentState, string> = {
+	working: ">",
+	booting: "~",
+	stalled: "!",
+	zombie: "x",
+	completed: "\u2713",
+};
+
+/** Returns the color function for a given agent state. Falls back to noColor. */
+export function stateColor(state: string): ColorFn {
+	return STATE_COLORS[state as AgentState] ?? noColor;
+}
+
+/** Returns the raw icon character for a given agent state. Falls back to "?". */
+export function stateIcon(state: string): string {
+	return STATE_ICONS[state as AgentState] ?? "?";
+}
+
+/** Returns a colored icon string for a given agent state. */
+export function stateIconColored(state: string): string {
+	return stateColor(state)(stateIcon(state));
+}
+
+// === Event Label Theme ===
+
+export interface EventLabel {
+	/** 5-character compact label (for feed). */
+	compact: string;
+	/** 10-character full label (for trace/replay). */
+	full: string;
+	/** Color function for this event type. */
+	color: ColorFn;
+}
+
+/** Maps event types to their compact (5-char) and full (10-char) labels, plus color. */
+const EVENT_LABELS: Record<EventType, EventLabel> = {
+	tool_start: { compact: "TOOL+", full: "TOOL START", color: color.blue },
+	tool_end: { compact: "TOOL-", full: "TOOL END  ", color: color.blue },
+	session_start: { compact: "SESS+", full: "SESSION  +", color: color.green },
+	session_end: { compact: "SESS-", full: "SESSION  -", color: color.yellow },
+	mail_sent: { compact: "MAIL>", full: "MAIL SENT ", color: color.cyan },
+	mail_received: { compact: "MAIL<", full: "MAIL RECV ", color: color.cyan },
+	spawn: { compact: "SPAWN", full: "SPAWN     ", color: color.magenta },
+	error: { compact: "ERROR", full: "ERROR     ", color: color.red },
+	custom: { compact: "CUSTM", full: "CUSTOM    ", color: color.gray },
+};
+
+/** Returns the EventLabel for a given event type. */
+export function eventLabel(eventType: EventType): EventLabel {
+	return EVENT_LABELS[eventType];
+}
+
+// === Agent Colors (for multi-agent displays) ===
+
+/** Stable palette for assigning distinct colors to agents in multi-agent displays. */
+export const AGENT_COLORS: readonly ColorFn[] = [
+	color.blue,
+	color.green,
+	color.yellow,
+	color.cyan,
+	color.magenta,
+] as const;
+
+// === Separators ===
+
+/** Unicode thin horizontal box-drawing character. */
+export const SEPARATOR_CHAR = "\u2500";
+
+/** Unicode double horizontal box-drawing character (thick). */
+export const THICK_SEPARATOR_CHAR = "\u2550";
+
+/** Default line width for separators and headers. */
+export const DEFAULT_WIDTH = 70;
+
+/** Returns a thin separator line of the given width (default 70). */
+export function separator(width?: number): string {
+	return SEPARATOR_CHAR.repeat(width ?? DEFAULT_WIDTH);
+}
+
+/** Returns a thick (double-line) separator of the given width (default 70). */
+export function thickSeparator(width?: number): string {
+	return THICK_SEPARATOR_CHAR.repeat(width ?? DEFAULT_WIDTH);
+}
+
+// === Header Rendering ===
+
+/**
+ * Pads a string to the given visible width, accounting for ANSI escape codes.
+ * If the string is already wider than width, returns it unchanged.
+ */
+export function padVisible(str: string, width: number): string {
+	const visible = visibleLength(str);
+	if (visible >= width) return str;
+	return str + " ".repeat(width - visible);
+}
+
+/**
+ * Renders a primary header: brand bold title + newline + thin separator.
+ */
+export function renderHeader(title: string, width?: number): string {
+	return `${brand.bold(title)}\n${separator(width)}`;
+}
+
+/**
+ * Renders a secondary header: color bold title + newline + dim thin separator.
+ */
+export function renderSubHeader(title: string, width?: number): string {
+	return `${color.bold(title)}\n${color.dim(separator(width))}`;
+}

package/src/metrics/store.test.ts

@@ -399,6 +399,52 @@ describe("getSessionsByRun", () => {
 	});
 });
 
+// === countSessions ===
+
+describe("countSessions", () => {
+	test("returns 0 for empty database", () => {
+		expect(store.countSessions()).toBe(0);
+	});
+
+	test("returns total count of sessions", () => {
+		store.recordSession(makeSession({ agentName: "a1", taskId: "t1" }));
+		store.recordSession(makeSession({ agentName: "a2", taskId: "t2" }));
+		store.recordSession(makeSession({ agentName: "a3", taskId: "t3" }));
+
+		expect(store.countSessions()).toBe(3);
+	});
+
+	test("returns accurate count beyond getRecentSessions default limit", () => {
+		// Insert 25 sessions (more than the default limit of 20)
+		for (let i = 0; i < 25; i++) {
+			store.recordSession(
+				makeSession({
+					agentName: `agent-${i}`,
+					taskId: `task-${i}`,
+					startedAt: new Date(Date.now() + i * 1000).toISOString(),
+				}),
+			);
+		}
+
+		// getRecentSessions is capped at 20 by default
+		expect(store.getRecentSessions().length).toBe(20);
+		// countSessions returns the true total without a cap
+		expect(store.countSessions()).toBe(25);
+	});
+
+	test("count updates after purge", () => {
+		store.recordSession(makeSession({ agentName: "a1", taskId: "t1" }));
+		store.recordSession(makeSession({ agentName: "a2", taskId: "t2" }));
+		expect(store.countSessions()).toBe(2);
+
+		store.purge({ agent: "a1" });
+		expect(store.countSessions()).toBe(1);
+
+		store.purge({ all: true });
+		expect(store.countSessions()).toBe(0);
+	});
+});
+
 // === purge ===
 
 describe("purge", () => {

package/src/metrics/store.ts

@@ -14,6 +14,8 @@ export interface MetricsStore {
 	getSessionsByAgent(agentName: string): SessionMetrics[];
 	getSessionsByRun(runId: string): SessionMetrics[];
 	getAverageDuration(capability?: string): number;
+	/** Count the total number of sessions in the database (no limit cap). */
+	countSessions(): number;
 	/** Delete metrics matching the given criteria. Returns the number of rows deleted. */
 	purge(options: { all?: boolean; agent?: string }): number;
 	/** Record a token usage snapshot for a running agent. */
@@ -252,6 +254,10 @@ export function createMetricsStore(dbPath: string): MetricsStore {
 		SELECT AVG(duration_ms) AS avg_duration FROM sessions WHERE completed_at IS NOT NULL
 	`);
 
+	const countSessionsStmt = db.prepare<{ cnt: number }, Record<string, never>>(`
+		SELECT COUNT(*) as cnt FROM sessions
+	`);
+
 	const avgDurationByCapStmt = db.prepare<
 		{ avg_duration: number | null },
 		{ $capability: string }
@@ -345,6 +351,11 @@ export function createMetricsStore(dbPath: string): MetricsStore {
 			return row?.avg_duration ?? 0;
 		},
 
+		countSessions(): number {
+			const row = countSessionsStmt.get({});
+			return row?.cnt ?? 0;
+		},
+
 		purge(options: { all?: boolean; agent?: string }): number {
 			if (options.all) {
 				const countRow = db

package/src/mulch/client.test.ts

@@ -451,6 +451,26 @@ describe("createMulchClient", () => {
 			const result = await client.search("test", { file: "src/config.ts", sortByScore: true });
 			expect(typeof result).toBe("string");
 		});
+
+		test.skipIf(!hasMulch)("roundtrip: record via API then search and find it", async () => {
+			await initMulch();
+			const addProc = Bun.spawn(["ml", "add", "roundtrip"], {
+				cwd: tempDir,
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			await addProc.exited;
+
+			const client = createMulchClient(tempDir);
+			await client.record("roundtrip", {
+				type: "convention",
+				description: "unique-roundtrip-marker-xyz",
+			});
+
+			const result = await client.search("unique-roundtrip-marker-xyz");
+			expect(typeof result).toBe("string");
+			expect(result).toContain("unique-roundtrip-marker-xyz");
+		});
 	});
 
 	describe("diff", () => {