@os-eco/overstory-cli 0.6.1 → 0.6.4

package/src/commands/prime.test.ts

@@ -66,41 +66,9 @@ describe("primeCommand", () => {
 		return stderrChunks.join("");
 	}
 
-	describe("Help", () => {
-		test("--help shows help text", async () => {
-			await primeCommand(["--help"]);
-			const out = output();
-
-			expect(out).toContain("overstory prime");
-			expect(out).toContain("--agent");
-			expect(out).toContain("--compact");
-		});
-
-		test("-h shows help text", async () => {
-			await primeCommand(["-h"]);
-			const out = output();
-
-			expect(out).toContain("overstory prime");
-			expect(out).toContain("--agent");
-			expect(out).toContain("--compact");
-		});
-	});
-
-	describe("parseArgs validation", () => {
-		test("--agent without a name throws AgentError", async () => {
-			await expect(primeCommand(["--agent"])).rejects.toThrow("--agent requires a name argument");
-		});
-
-		test("--agent followed by another flag throws AgentError", async () => {
-			await expect(primeCommand(["--agent", "--compact"])).rejects.toThrow(
-				"--agent requires a name argument",
-			);
-		});
-	});
-
 	describe("Orchestrator priming (no --agent flag)", () => {
 		test("default prime outputs project context", async () => {
-			await primeCommand([]);
+			await primeCommand({});
 			const out = output();
 
 			expect(out).toContain("# Overstory Context");
@@ -111,7 +79,7 @@ describe("primeCommand", () => {
 		});
 
 		test("includes agent manifest section", async () => {
-			await primeCommand([]);
+			await primeCommand({});
 			const out = output();
 
 			expect(out).toContain("## Agent Manifest");
@@ -120,7 +88,7 @@ describe("primeCommand", () => {
 		});
 
 		test("without metrics.db shows no recent sessions message", async () => {
-			await primeCommand([]);
+			await primeCommand({});
 			const out = output();
 
 			expect(out).toContain("## Recent Activity");
@@ -128,7 +96,7 @@ describe("primeCommand", () => {
 		});
 
 		test("--compact skips Recent Activity and Expertise sections", async () => {
-			await primeCommand(["--compact"]);
+			await primeCommand({ compact: true });
 			const out = output();
 
 			// Should still have project basics
@@ -143,7 +111,7 @@ describe("primeCommand", () => {
 
 	describe("Agent priming (--agent <name>)", () => {
 		test("unknown agent outputs basic context and warns", async () => {
-			await primeCommand(["--agent", "unknown-agent"]);
+			await primeCommand({ agent: "unknown-agent" });
 			const out = output();
 			const err = stderr();
 
@@ -172,7 +140,7 @@ recentTasks:
 `,
 			);
 
-			await primeCommand(["--agent", "my-builder"]);
+			await primeCommand({ agent: "my-builder" });
 			const out = output();
 
 			expect(out).toContain("# Agent Context: my-builder");
@@ -212,7 +180,7 @@ recentTasks:
 				`${JSON.stringify(sessions, null, 2)}\n`,
 			);
 
-			await primeCommand(["--agent", "active-builder"]);
+			await primeCommand({ agent: "active-builder" });
 			const out = output();
 
 			expect(out).toContain("# Agent Context: active-builder");
@@ -249,7 +217,7 @@ recentTasks:
 				`${JSON.stringify(sessions, null, 2)}\n`,
 			);
 
-			await primeCommand(["--agent", "completed-builder"]);
+			await primeCommand({ agent: "completed-builder" });
 			const out = output();
 
 			expect(out).toContain("# Agent Context: completed-builder");
@@ -291,7 +259,7 @@ recentTasks: []
 `,
 			);
 
-			await primeCommand(["--agent", "recovery-agent", "--compact"]);
+			await primeCommand({ agent: "recovery-agent", compact: true });
 			const out = output();
 
 			expect(out).toContain("# Agent Context: recovery-agent");
@@ -317,7 +285,7 @@ recentTasks: []
 `,
 			);
 
-			await primeCommand(["--agent", "compact-agent", "--compact"]);
+			await primeCommand({ agent: "compact-agent", compact: true });
 			const out = output();
 
 			expect(out).toContain("# Agent Context: compact-agent");
@@ -340,7 +308,7 @@ recentTasks: []
 				// Save and change cwd to the git repo
 				process.chdir(gitRepoDir);
 
-				await primeCommand([]);
+				await primeCommand({});
 				const out = output();
 
 				expect(out).toContain("# Overstory Context");
@@ -375,7 +343,7 @@ recentTasks: []
 
 				process.chdir(gitRepoDir);
 
-				await primeCommand([]);
+				await primeCommand({});
 				const out = output();
 
 				expect(out).toContain("Session branch: feature/my-work (merge target)");
@@ -412,7 +380,7 @@ recentTasks: []
 			expect(existsBefore).toBe(false);
 
 			// Run primeCommand
-			await primeCommand([]);
+			await primeCommand({});
 
 			// Verify .gitignore was created with correct content
 			const content = await Bun.file(gitignorePath).text();
@@ -435,7 +403,7 @@ sessions.db
 			expect(contentBefore).toBe(staleContent);
 
 			// Run primeCommand
-			await primeCommand([]);
+			await primeCommand({});
 
 			// Verify .gitignore now has the wildcard+whitelist content
 			const contentAfter = await Bun.file(gitignorePath).text();
@@ -455,7 +423,7 @@ sessions.db
 			await new Promise((resolve) => setTimeout(resolve, 10));
 
 			// Run primeCommand
-			await primeCommand([]);
+			await primeCommand({});
 
 			// Verify content is still correct
 			const contentAfter = await Bun.file(gitignorePath).text();

package/src/commands/prime.ts

@@ -12,7 +12,6 @@ import { loadCheckpoint } from "../agents/checkpoint.ts";
 import { loadIdentity } from "../agents/identity.ts";
 import { createManifestLoader } from "../agents/manifest.ts";
 import { loadConfig } from "../config.ts";
-import { AgentError } from "../errors.ts";
 import { createMetricsStore } from "../metrics/store.ts";
 import { createMulchClient } from "../mulch/client.ts";
 import { openSessionStore } from "../sessions/compat.ts";
@@ -35,32 +34,9 @@ const OVERSTORY_GITIGNORE = `# Wildcard+whitelist: ignore everything, whitelist
 !agent-defs/
 `;
 
-/**
- * Parse CLI flags from the args array.
- *
- * Supports:
- * - `--agent <name>` — Prime for a specific agent
- * - `--compact` — Output reduced context
- */
-function parseArgs(args: string[]): { agentName: string | null; compact: boolean } {
-	let agentName: string | null = null;
-	let compact = false;
-
-	for (let i = 0; i < args.length; i++) {
-		const arg = args[i];
-		if (arg === "--agent") {
-			const next = args[i + 1];
-			if (next === undefined || next.startsWith("--")) {
-				throw new AgentError("--agent requires a name argument");
-			}
-			agentName = next;
-			i++; // Skip the value
-		} else if (arg === "--compact") {
-			compact = true;
-		}
-	}
-
-	return { agentName, compact };
+export interface PrimeOptions {
+	agent?: string;
+	compact?: boolean;
 }
 
 /**
@@ -156,24 +132,11 @@ async function healGitignore(overstoryDir: string): Promise<void> {
  * Gathers project state and outputs context to stdout for injection
  * into Claude Code's context.
  *
- * @param args - CLI arguments after "prime" subcommand
+ * @param opts - Command options
  */
-const PRIME_HELP = `overstory prime — Load context for orchestrator/agent
-
-Usage: overstory prime [--agent <name>] [--compact]
-
-Options:
-  --agent <name>   Prime for a specific agent (default: orchestrator)
-  --compact        Output reduced context (for PreCompact hook)
-  --help, -h       Show this help`;
-
-export async function primeCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${PRIME_HELP}\n`);
-		return;
-	}
-
-	const { agentName, compact } = parseArgs(args);
+export async function primeCommand(opts: PrimeOptions): Promise<void> {
+	const agentName = opts.agent ?? null;
+	const compact = opts.compact ?? false;
 
 	// 1. Load config
 	const config = await loadConfig(process.cwd());

package/src/commands/replay.test.ts

@@ -78,7 +78,7 @@ describe("replayCommand", () => {
 			await replayCommand(["--help"]);
 			const out = output();
 
-			expect(out).toContain("overstory replay");
+			expect(out).toContain("replay");
 			expect(out).toContain("--run");
 			expect(out).toContain("--agent");
 			expect(out).toContain("--json");
@@ -91,7 +91,7 @@ describe("replayCommand", () => {
 			await replayCommand(["-h"]);
 			const out = output();
 
-			expect(out).toContain("overstory replay");
+			expect(out).toContain("replay");
 		});
 	});
 

package/src/commands/replay.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";
 
 /** Labels and colors for each event type. */
-const EVENT_LABELS: Record<EventType, { label: string; color: string }> = {
+const EVENT_LABELS: Record<EventType, { label: string; color: ColorFn }> = {
 	tool_start: { label: "TOOL START", color: color.blue },
 	tool_end: { label: "TOOL END  ", color: color.blue },
 	session_start: { label: "SESSION  +", color: color.green },
@@ -26,41 +28,14 @@ const EVENT_LABELS: Record<EventType, { label: string; color: string }> = {
 	custom: { label: "CUSTOM    ", 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 a relative time string from a timestamp.
@@ -150,16 +125,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 color = AGENT_COLORS[colorIndex];
-			if (color !== undefined) {
-				colorMap.set(event.agentName, color);
+			const agentColorFn = AGENT_COLORS[colorIndex];
+			if (agentColorFn !== undefined) {
+				colorMap.set(event.agentName, agentColorFn);
 			}
 		}
 	}
@@ -172,15 +147,15 @@ function buildAgentColorMap(events: StoredEvent[]): Map<string, string> {
 function printReplay(events: StoredEvent[], useAbsoluteTime: boolean): void {
 	const w = process.stdout.write.bind(process.stdout);
 
-	w(`${color.bold}Replay${color.reset}\n`);
+	w(`${color.bold("Replay")}\n`);
 	w(`${"=".repeat(70)}\n`);
 
 	if (events.length === 0) {
-		w(`${color.dim}No events found.${color.reset}\n`);
+		w(`${color.dim("No events found.")}\n`);
 		return;
 	}
 
-	w(`${color.dim}${events.length} event${events.length === 1 ? "" : "s"}${color.reset}\n\n`);
+	w(`${color.dim(`${events.length} event${events.length === 1 ? "" : "s"}`)}\n\n`);
 
 	const colorMap = buildAgentColorMap(events);
 	let lastDate = "";
@@ -192,7 +167,7 @@ function printReplay(events: StoredEvent[], useAbsoluteTime: boolean): void {
 			if (lastDate !== "") {
 				w("\n");
 			}
-			w(`${color.dim}--- ${date} ---${color.reset}\n`);
+			w(`${color.dim(`--- ${date} ---`)}\n`);
 			lastDate = date;
 		}
 
@@ -205,57 +180,40 @@ function printReplay(events: StoredEvent[], useAbsoluteTime: boolean): 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}]${color.reset}`;
+		const agentColorFn = colorMap.get(event.agentName) ?? color.gray;
+		const agentLabel = ` ${agentColorFn(`[${event.agentName}]`)}`;
 
 		w(
-			`${color.dim}${timeStr.padStart(10)}${color.reset} ` +
-				`${levelColor}${eventInfo.color}${color.bold}${eventInfo.label}${color.reset}${levelReset}` +
+			`${color.dim(timeStr.padStart(10))} ` +
+				`${applyLevel(eventInfo.color(color.bold(eventInfo.label)))}` +
 				`${agentLabel}${detailSuffix}\n`,
 		);
 	}
 }
 
-const REPLAY_HELP = `overstory replay -- Interleaved chronological replay across agents
-
-Usage: overstory replay [options]
-
-Options:
-  --run <id>             Filter events by run ID
-  --agent <name>         Filter by agent name (can appear multiple times)
-  --since <timestamp>    Start time filter (ISO 8601)
-  --until <timestamp>    End time filter (ISO 8601)
-  --limit <n>            Max events to show (default: 200)
-  --json                 Output as JSON array of StoredEvent objects
-  --help, -h             Show this help
-
-If --run is specified, shows all events from that run.
-If --agent is specified, shows events from those agents merged chronologically.
-If neither is specified, tries to read the current run from .overstory/current-run.txt.
-Falls back to a 24-hour timeline of all events.`;
-
-/**
- * Entry point for `overstory replay [--run <id>] [--agent <name>...] [--json]`.
- */
-export async function replayCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${REPLAY_HELP}\n`);
-		return;
-	}
+interface ReplayOpts {
+	run?: string;
+	agent: string[]; // repeatable
+	since?: string;
+	until?: string;
+	limit?: string;
+	json?: boolean;
+}
 
-	const json = hasFlag(args, "--json");
-	const runId = getFlag(args, "--run");
-	const agentNames = getAllFlags(args, "--agent");
-	const sinceStr = getFlag(args, "--since");
-	const untilStr = getFlag(args, "--until");
-	const limitStr = getFlag(args, "--limit");
+async function executeReplay(opts: ReplayOpts): Promise<void> {
+	const json = opts.json ?? false;
+	const runId = opts.run;
+	const agentNames = opts.agent;
+	const sinceStr = opts.since;
+	const untilStr = opts.until;
+	const limitStr = opts.limit;
 	const limit = limitStr ? Number.parseInt(limitStr, 10) : 200;
 
 	if (Number.isNaN(limit) || limit < 1) {
@@ -358,3 +316,38 @@ export async function replayCommand(args: string[]): Promise<void> {
 		eventStore.close();
 	}
 }
+
+export function createReplayCommand(): Command {
+	return new Command("replay")
+		.description("Interleaved chronological replay across agents")
+		.option("--run <id>", "Filter events by run ID")
+		.option(
+			"--agent <name>",
+			"Filter by agent name (can appear multiple times)",
+			(val: string, prev: string[]) => [...prev, val],
+			[] as string[],
+		)
+		.option("--since <timestamp>", "Start time filter (ISO 8601)")
+		.option("--until <timestamp>", "End time filter (ISO 8601)")
+		.option("--limit <n>", "Max events to show (default: 200)")
+		.option("--json", "Output as JSON array of StoredEvent objects")
+		.action(async (opts: ReplayOpts) => {
+			await executeReplay(opts);
+		});
+}
+
+export async function replayCommand(args: string[]): Promise<void> {
+	const cmd = createReplayCommand();
+	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;
+			}
+		}
+		throw err;
+	}
+}