@os-eco/overstory-cli 0.6.1 → 0.6.5

package/src/commands/errors.ts

@@ -7,27 +7,13 @@
  */
 
 import { join } from "node:path";
+import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
 import { color } from "../logging/color.ts";
 import type { StoredEvent } from "../types.ts";
 
-/**
- * Parse a named flag value from args.
- */
-function getFlag(args: string[], flag: string): string | undefined {
-	const idx = args.indexOf(flag);
-	if (idx === -1 || idx + 1 >= args.length) {
-		return undefined;
-	}
-	return args[idx + 1];
-}
-
-function hasFlag(args: string[], flag: string): boolean {
-	return args.includes(flag);
-}
-
 /**
  * Format an absolute time from an ISO timestamp.
  * Returns "HH:MM:SS" portion.
@@ -109,15 +95,15 @@ function groupByAgent(events: StoredEvent[]): Map<string, StoredEvent[]> {
 function printErrors(events: StoredEvent[]): void {
 	const w = process.stdout.write.bind(process.stdout);
 
-	w(`${color.bold}${color.red}Errors${color.reset}\n`);
+	w(`${color.bold(color.red("Errors"))}\n`);
 	w(`${"=".repeat(70)}\n`);
 
 	if (events.length === 0) {
-		w(`${color.dim}No errors found.${color.reset}\n`);
+		w(`${color.dim("No errors found.")}\n`);
 		return;
 	}
 
-	w(`${color.dim}${events.length} error${events.length === 1 ? "" : "s"}${color.reset}\n\n`);
+	w(`${color.dim(`${events.length} error${events.length === 1 ? "" : "s"}`)}\n\n`);
 
 	const grouped = groupByAgent(events);
 
@@ -129,7 +115,7 @@ function printErrors(events: StoredEvent[]): void {
 		firstGroup = false;
 
 		w(
-			`${color.bold}${agentName}${color.reset} ${color.dim}(${agentEvents.length} error${agentEvents.length === 1 ? "" : "s"})${color.reset}\n`,
+			`${color.bold(agentName)} ${color.dim(`(${agentEvents.length} error${agentEvents.length === 1 ? "" : "s"})`)}\n`,
 		);
 
 		for (const event of agentEvents) {
@@ -138,43 +124,29 @@ function printErrors(events: StoredEvent[]): void {
 			const timestamp = date ? `${date} ${time}` : time;
 
 			const detail = buildErrorDetail(event);
-			const detailSuffix = detail ? ` ${color.dim}${detail}${color.reset}` : "";
+			const detailSuffix = detail ? ` ${color.dim(detail)}` : "";
 
-			w(
-				`  ${color.dim}${timestamp}${color.reset} ${color.red}${color.bold}ERROR${color.reset}${detailSuffix}\n`,
-			);
+			w(`  ${color.dim(timestamp)} ${color.red(color.bold("ERROR"))}${detailSuffix}\n`);
 		}
 	}
 }
 
-const ERRORS_HELP = `overstory errors -- Aggregated error view across agents
-
-Usage: overstory errors [options]
-
-Options:
-  --agent <name>         Filter errors by agent name
-  --run <id>             Filter errors by run ID
-  --since <timestamp>    Start time filter (ISO 8601)
-  --until <timestamp>    End time filter (ISO 8601)
-  --limit <n>            Max errors to show (default: 100)
-  --json                 Output as JSON array of StoredEvent objects
-  --help, -h             Show this help`;
-
-/**
- * Entry point for `overstory errors [--agent <name>] [--run <id>] [--json] [--since] [--until] [--limit]`.
- */
-export async function errorsCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${ERRORS_HELP}\n`);
-		return;
-	}
+interface ErrorsOpts {
+	agent?: string;
+	run?: string;
+	since?: string;
+	until?: string;
+	limit?: string;
+	json?: boolean;
+}
 
-	const json = hasFlag(args, "--json");
-	const agentName = getFlag(args, "--agent");
-	const runId = getFlag(args, "--run");
-	const sinceStr = getFlag(args, "--since");
-	const untilStr = getFlag(args, "--until");
-	const limitStr = getFlag(args, "--limit");
+async function executeErrors(opts: ErrorsOpts): Promise<void> {
+	const json = opts.json ?? false;
+	const agentName = opts.agent;
+	const runId = opts.run;
+	const sinceStr = opts.since;
+	const untilStr = opts.until;
+	const limitStr = opts.limit;
 	const limit = limitStr ? Number.parseInt(limitStr, 10) : 100;
 
 	if (Number.isNaN(limit) || limit < 1) {
@@ -246,3 +218,37 @@ export async function errorsCommand(args: string[]): Promise<void> {
 		eventStore.close();
 	}
 }
+
+export function createErrorsCommand(): Command {
+	return new Command("errors")
+		.description("Aggregated error view across agents")
+		.option("--agent <name>", "Filter errors by agent name")
+		.option("--run <id>", "Filter errors by run ID")
+		.option("--since <timestamp>", "Start time filter (ISO 8601)")
+		.option("--until <timestamp>", "End time filter (ISO 8601)")
+		.option("--limit <n>", "Max errors to show (default: 100)")
+		.option("--json", "Output as JSON array of StoredEvent objects")
+		.action(async (opts: ErrorsOpts) => {
+			await executeErrors(opts);
+		});
+}
+
+export async function errorsCommand(args: string[]): Promise<void> {
+	const cmd = createErrorsCommand();
+	cmd.exitOverride();
+	try {
+		await cmd.parseAsync(args, { from: "user" });
+	} catch (err: unknown) {
+		if (err && typeof err === "object" && "code" in err) {
+			const code = (err as { code: string }).code;
+			if (code === "commander.helpDisplayed" || code === "commander.version") {
+				return;
+			}
+			if (code.startsWith("commander.")) {
+				const message = err instanceof Error ? err.message : String(err);
+				throw new ValidationError(message, { field: "args" });
+			}
+		}
+		throw err;
+	}
+}

package/src/commands/feed.test.ts

@@ -78,7 +78,7 @@ describe("feedCommand", () => {
 			await feedCommand(["--help"]);
 			const out = output();
 
-			expect(out).toContain("overstory feed");
+			expect(out).toContain("feed");
 			expect(out).toContain("--follow");
 			expect(out).toContain("--agent");
 			expect(out).toContain("--run");
@@ -92,7 +92,7 @@ describe("feedCommand", () => {
 			await feedCommand(["-h"]);
 			const out = output();
 
-			expect(out).toContain("overstory feed");
+			expect(out).toContain("feed");
 		});
 	});
 

package/src/commands/feed.ts

@@ -7,14 +7,16 @@
  */
 
 import { join } from "node:path";
+import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
+import type { ColorFn } from "../logging/color.ts";
 import { color } from "../logging/color.ts";
 import type { EventType, StoredEvent } from "../types.ts";
 
 /** Compact 5-char labels for feed output. */
-const EVENT_LABELS: Record<EventType, { label: string; color: string }> = {
+const EVENT_LABELS: Record<EventType, { label: string; color: ColorFn }> = {
 	tool_start: { label: "TOOL+", color: color.blue },
 	tool_end: { label: "TOOL-", color: color.blue },
 	session_start: { label: "SESS+", color: color.green },
@@ -26,41 +28,14 @@ const EVENT_LABELS: Record<EventType, { label: string; color: string }> = {
 	custom: { label: "CUSTM", color: color.gray },
 };
 
-/** Colors assigned to agents in order of first appearance. */
-const AGENT_COLORS = [color.blue, color.green, color.yellow, color.cyan, color.magenta] as const;
-
-/**
- * Parse a named flag value from args.
- */
-function getFlag(args: string[], flag: string): string | undefined {
-	const idx = args.indexOf(flag);
-	if (idx === -1 || idx + 1 >= args.length) {
-		return undefined;
-	}
-	return args[idx + 1];
-}
-
-/**
- * Parse all occurrences of a named flag from args.
- * Returns an array of values (e.g., --agent a --agent b => ["a", "b"]).
- */
-function getAllFlags(args: string[], flag: string): string[] {
-	const values: string[] = [];
-	for (let i = 0; i < args.length; i++) {
-		if (args[i] === flag && i + 1 < args.length) {
-			const value = args[i + 1];
-			if (value !== undefined) {
-				values.push(value);
-			}
-			i++; // skip the value
-		}
-	}
-	return values;
-}
-
-function hasFlag(args: string[], flag: string): boolean {
-	return args.includes(flag);
-}
+/** Color functions assigned to agents in order of first appearance. */
+const AGENT_COLORS: readonly ColorFn[] = [
+	color.blue,
+	color.green,
+	color.yellow,
+	color.cyan,
+	color.magenta,
+];
 
 /**
  * Format an absolute time from an ISO timestamp.
@@ -114,16 +89,16 @@ function buildEventDetail(event: StoredEvent): string {
 }
 
 /**
- * Assign a stable color to each agent based on order of first appearance.
+ * Assign a stable color function to each agent based on order of first appearance.
  */
-function buildAgentColorMap(events: StoredEvent[]): Map<string, string> {
-	const colorMap = new Map<string, string>();
+function buildAgentColorMap(events: StoredEvent[]): Map<string, ColorFn> {
+	const colorMap = new Map<string, ColorFn>();
 	for (const event of events) {
 		if (!colorMap.has(event.agentName)) {
 			const colorIndex = colorMap.size % AGENT_COLORS.length;
-			const agentColor = AGENT_COLORS[colorIndex];
-			if (agentColor !== undefined) {
-				colorMap.set(event.agentName, agentColor);
+			const agentColorFn = AGENT_COLORS[colorIndex];
+			if (agentColorFn !== undefined) {
+				colorMap.set(event.agentName, agentColorFn);
 			}
 		}
 	}
@@ -134,7 +109,7 @@ function buildAgentColorMap(events: StoredEvent[]): Map<string, string> {
  * Print a single event in compact feed format:
  * HH:MM:SS LABEL agentname    detail
  */
-function printEvent(event: StoredEvent, colorMap: Map<string, string>): void {
+function printEvent(event: StoredEvent, colorMap: Map<string, ColorFn>): void {
 	const w = process.stdout.write.bind(process.stdout);
 
 	const timeStr = formatAbsoluteTime(event.createdAt);
@@ -144,55 +119,43 @@ function printEvent(event: StoredEvent, colorMap: Map<string, string>): void {
 		color: color.gray,
 	};
 
-	const levelColor =
-		event.level === "error" ? color.red : event.level === "warn" ? color.yellow : "";
-	const levelReset = levelColor ? color.reset : "";
+	const levelColorFn =
+		event.level === "error" ? color.red : event.level === "warn" ? color.yellow : null;
+	const applyLevel = (text: string) => (levelColorFn ? levelColorFn(text) : text);
 
 	const detail = buildEventDetail(event);
-	const detailSuffix = detail ? ` ${color.dim}${detail}${color.reset}` : "";
+	const detailSuffix = detail ? ` ${color.dim(detail)}` : "";
 
-	const agentColor = colorMap.get(event.agentName) ?? color.gray;
-	const agentLabel = ` ${agentColor}${event.agentName.padEnd(15)}${color.reset}`;
+	const agentColorFn = colorMap.get(event.agentName) ?? color.gray;
+	const agentLabel = ` ${agentColorFn(event.agentName.padEnd(15))}`;
 
 	w(
-		`${color.dim}${timeStr}${color.reset} ` +
-			`${levelColor}${eventInfo.color}${color.bold}${eventInfo.label}${color.reset}${levelReset}` +
+		`${color.dim(timeStr)} ` +
+			`${applyLevel(eventInfo.color(color.bold(eventInfo.label)))}` +
 			`${agentLabel}${detailSuffix}\n`,
 	);
 }
 
-const FEED_HELP = `overstory feed -- Unified real-time event stream across all agents
-
-Usage: overstory feed [options]
-
-Options:
-  --follow, -f         Continuously poll for new events (like tail -f)
-  --interval <ms>      Polling interval for --follow (default: 1000, min: 200)
-  --agent <name>       Filter by agent name (can appear multiple times)
-  --run <id>           Filter events by run ID
-  --since <timestamp>  Start time (ISO 8601, default: 5 minutes ago)
-  --limit <n>          Max initial events to show (default: 50)
-  --json               Output events as JSON (one per line in follow mode)
-  --help, -h           Show this help`;
-
-/**
- * Entry point for `overstory feed [--follow] [--agent <name>...] [--run <id>] [--json]`.
- */
-export async function feedCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${FEED_HELP}\n`);
-		return;
-	}
+interface FeedOpts {
+	follow?: boolean;
+	interval?: string;
+	agent: string[]; // repeatable
+	run?: string;
+	since?: string;
+	limit?: string;
+	json?: boolean;
+}
 
-	const json = hasFlag(args, "--json");
-	const follow = hasFlag(args, "--follow") || hasFlag(args, "-f");
-	const runId = getFlag(args, "--run");
-	const agentNames = getAllFlags(args, "--agent");
-	const sinceStr = getFlag(args, "--since");
-	const limitStr = getFlag(args, "--limit");
+async function executeFeed(opts: FeedOpts): Promise<void> {
+	const json = opts.json ?? false;
+	const follow = opts.follow ?? false;
+	const runId = opts.run;
+	const agentNames = opts.agent;
+	const sinceStr = opts.since;
+	const limitStr = opts.limit;
 	const limit = limitStr ? Number.parseInt(limitStr, 10) : 50;
 
-	const intervalStr = getFlag(args, "--interval");
+	const intervalStr = opts.interval;
 	const interval = intervalStr ? Number.parseInt(intervalStr, 10) : 1000;
 
 	if (Number.isNaN(limit) || limit < 1) {
@@ -330,9 +293,9 @@ export async function feedCommand(args: string[]): Promise<void> {
 					for (const event of newEvents) {
 						if (!globalColorMap.has(event.agentName)) {
 							const colorIndex = globalColorMap.size % AGENT_COLORS.length;
-							const agentColor = AGENT_COLORS[colorIndex];
-							if (agentColor !== undefined) {
-								globalColorMap.set(event.agentName, agentColor);
+							const agentColorFn = AGENT_COLORS[colorIndex];
+							if (agentColorFn !== undefined) {
+								globalColorMap.set(event.agentName, agentColorFn);
 							}
 						}
 					}
@@ -359,3 +322,43 @@ export async function feedCommand(args: string[]): Promise<void> {
 		eventStore.close();
 	}
 }
+
+export function createFeedCommand(): Command {
+	return new Command("feed")
+		.description("Unified real-time event stream across all agents")
+		.option("-f, --follow", "Continuously poll for new events (like tail -f)")
+		.option("--interval <ms>", "Polling interval for --follow (default: 1000, min: 200)")
+		.option(
+			"--agent <name>",
+			"Filter by agent name (can appear multiple times)",
+			(val: string, prev: string[]) => [...prev, val],
+			[] as string[],
+		)
+		.option("--run <id>", "Filter events by run ID")
+		.option("--since <timestamp>", "Start time (ISO 8601, default: 5 minutes ago)")
+		.option("--limit <n>", "Max initial events to show (default: 50)")
+		.option("--json", "Output events as JSON (one per line in follow mode)")
+		.action(async (opts: FeedOpts) => {
+			await executeFeed(opts);
+		});
+}
+
+export async function feedCommand(args: string[]): Promise<void> {
+	const cmd = createFeedCommand();
+	cmd.exitOverride();
+	try {
+		await cmd.parseAsync(args, { from: "user" });
+	} catch (err: unknown) {
+		if (err && typeof err === "object" && "code" in err) {
+			const code = (err as { code: string }).code;
+			if (code === "commander.helpDisplayed" || code === "commander.version") {
+				return;
+			}
+			if (code.startsWith("commander.")) {
+				const message = err instanceof Error ? err.message : String(err);
+				throw new ValidationError(message, { field: "args" });
+			}
+		}
+		throw err;
+	}
+}