@os-eco/overstory-cli 0.6.1 → 0.6.4

package/src/commands/trace.ts

@@ -6,15 +6,17 @@
  */
 
 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 { openSessionStore } from "../sessions/compat.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,21 +28,6 @@ const EVENT_LABELS: Record<EventType, { label: string; color: string }> = {
 	custom: { label: "CUSTOM    ", color: color.gray },
 };
 
-/**
- * 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);
-}
-
 /**
  * Detect whether a target string looks like a bead ID.
  * Bead IDs follow the pattern: word-alphanumeric (e.g., "overstory-rj1k", "myproject-abc1").
@@ -142,15 +129,15 @@ function buildEventDetail(event: StoredEvent): string {
 function printTimeline(events: StoredEvent[], agentName: string, useAbsoluteTime: boolean): void {
 	const w = process.stdout.write.bind(process.stdout);
 
-	w(`${color.bold}Timeline for ${agentName}${color.reset}\n`);
+	w(`${color.bold(`Timeline for ${agentName}`)}\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`);
 
 	let lastDate = "";
 
@@ -161,7 +148,7 @@ function printTimeline(events: StoredEvent[], agentName: string, useAbsoluteTime
 			if (lastDate !== "") {
 				w("\n");
 			}
-			w(`${color.dim}--- ${date} ---${color.reset}\n`);
+			w(`${color.dim(`--- ${date} ---`)}\n`);
 			lastDate = date;
 		}
 
@@ -174,74 +161,35 @@ function printTimeline(events: StoredEvent[], agentName: string, useAbsoluteTime
 			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 agentLabel =
-			event.agentName !== agentName ? ` ${color.dim}[${event.agentName}]${color.reset}` : "";
+		const agentLabel = event.agentName !== agentName ? ` ${color.dim(`[${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 TRACE_HELP = `overstory trace -- Show chronological timeline for an agent or bead
-
-Usage: overstory trace <target> [options]
-
-Arguments:
-  <target>               Agent name or bead ID
-
-Options:
-  --json                 Output as JSON array of StoredEvent objects
-  --since <timestamp>    Start time filter (ISO 8601)
-  --until <timestamp>    End time filter (ISO 8601)
-  --limit <n>            Max events to show (default: 100)
-  --help, -h             Show this help`;
-
-/**
- * Entry point for `overstory trace <target> [--json] [--since] [--until] [--limit]`.
- */
-export async function traceCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${TRACE_HELP}\n`);
-		return;
-	}
-
-	// Extract positional target: first arg that is not a flag or flag value
-	const flagsWithValues = new Set(["--since", "--until", "--limit"]);
-	const booleanFlags = new Set(["--json", "--help", "-h"]);
-	let target: string | undefined;
-	for (let i = 0; i < args.length; i++) {
-		const arg = args[i];
-		if (arg === undefined) continue;
-		if (booleanFlags.has(arg)) continue;
-		if (flagsWithValues.has(arg)) {
-			i++; // skip the value
-			continue;
-		}
-		if (arg.startsWith("-")) continue;
-		target = arg;
-		break;
-	}
-
-	if (!target) {
-		throw new ValidationError("Missing target. Usage: overstory trace <agent-name|bead-id>", {
-			field: "target",
-		});
-	}
+interface TraceOpts {
+	json?: boolean;
+	since?: string;
+	until?: string;
+	limit?: string;
+}
 
-	const json = hasFlag(args, "--json");
-	const sinceStr = getFlag(args, "--since");
-	const untilStr = getFlag(args, "--until");
-	const limitStr = getFlag(args, "--limit");
+async function executeTrace(target: string, opts: TraceOpts): Promise<void> {
+	const json = opts.json ?? false;
+	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) {
@@ -323,3 +271,32 @@ export async function traceCommand(args: string[]): Promise<void> {
 		eventStore.close();
 	}
 }
+
+export function createTraceCommand(): Command {
+	return new Command("trace")
+		.description("Chronological event timeline for agent/bead")
+		.argument("<target>", "Agent name or bead ID")
+		.option("--json", "Output as JSON array of StoredEvent objects")
+		.option("--since <timestamp>", "Start time filter (ISO 8601)")
+		.option("--until <timestamp>", "End time filter (ISO 8601)")
+		.option("--limit <n>", "Max events to show (default: 100)")
+		.action(async (target: string, opts: TraceOpts) => {
+			await executeTrace(target, opts);
+		});
+}
+
+export async function traceCommand(args: string[]): Promise<void> {
+	const cmd = createTraceCommand();
+	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;
+	}
+}

package/src/commands/watch.test.ts

@@ -81,7 +81,7 @@ describe("watchCommand", () => {
 		await watchCommand(["--help"]);
 		const out = output();
 
-		expect(out).toContain("overstory watch");
+		expect(out).toContain("watch");
 		expect(out).toContain("--interval");
 		expect(out).toContain("--background");
 		expect(out).toContain("Tier 0");
@@ -91,7 +91,7 @@ describe("watchCommand", () => {
 		await watchCommand(["-h"]);
 		const out = output();
 
-		expect(out).toContain("overstory watch");
+		expect(out).toContain("watch");
 		expect(out).toContain("Tier 0");
 	});
 

package/src/commands/watch.ts

@@ -7,27 +7,13 @@
  */
 
 import { join } from "node:path";
+import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { OverstoryError } from "../errors.ts";
 import type { HealthCheck } from "../types.ts";
 import { startDaemon } from "../watchdog/daemon.ts";
 import { isProcessRunning } from "../watchdog/health.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 a health check for display.
  */
@@ -126,44 +112,21 @@ async function resolveOverstoryBin(): Promise<string> {
 }
 
 /**
- * Entry point for `overstory watch [--interval <ms>] [--background]`.
+ * Core implementation for the watch command.
  */
-const WATCH_HELP = `overstory watch — Start Tier 0 mechanical watchdog daemon
-
-Usage: overstory watch [--interval <ms>] [--background]
-
-Tier numbering:
-  Tier 0  Mechanical daemon (heartbeat, tmux/pid liveness) — this command
-  Tier 1  Triage agent (ephemeral AI analysis of stalled agents)
-  Tier 2  Monitor agent (continuous patrol — not yet implemented)
-  Tier 3  Supervisor monitors (per-project)
-
-Options:
-  --interval <ms>    Health check interval in milliseconds (default: from config)
-  --background       Daemonize (run in background)
-  --help, -h         Show this help`;
-
-export async function watchCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${WATCH_HELP}\n`);
-		return;
-	}
-
-	const intervalStr = getFlag(args, "--interval");
-	const background = hasFlag(args, "--background");
-
+async function runWatch(opts: { interval?: string; background?: boolean }): Promise<void> {
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
 
-	const intervalMs = intervalStr
-		? Number.parseInt(intervalStr, 10)
+	const intervalMs = opts.interval
+		? Number.parseInt(opts.interval, 10)
 		: config.watchdog.tier0IntervalMs;
 
 	const staleThresholdMs = config.watchdog.staleThresholdMs;
 	const zombieThresholdMs = config.watchdog.zombieThresholdMs;
 	const pidFilePath = join(config.project.root, ".overstory", "watchdog.pid");
 
-	if (background) {
+	if (opts.background) {
 		// Check if a watchdog is already running
 		const existingPid = await readPidFile(pidFilePath);
 		if (existingPid !== null && isProcessRunning(existingPid)) {
@@ -182,8 +145,8 @@ export async function watchCommand(args: string[]): Promise<void> {
 
 		// Build the args for the child process, forwarding --interval but not --background
 		const childArgs: string[] = ["watch"];
-		if (intervalStr) {
-			childArgs.push("--interval", intervalStr);
+		if (opts.interval) {
+			childArgs.push("--interval", opts.interval);
 		}
 
 		// Resolve the overstory binary path
@@ -245,3 +208,33 @@ export async function watchCommand(args: string[]): Promise<void> {
 	// Block forever
 	await new Promise(() => {});
 }
+
+export function createWatchCommand(): Command {
+	return new Command("watch")
+		.description("Start Tier 0 mechanical watchdog daemon")
+		.option("--interval <ms>", "Health check interval in milliseconds")
+		.option("--background", "Daemonize (run in background)")
+		.action(async (opts: { interval?: string; background?: boolean }) => {
+			await runWatch(opts);
+		});
+}
+
+/**
+ * Entry point for `overstory watch [--interval <ms>] [--background]`.
+ */
+export async function watchCommand(args: string[]): Promise<void> {
+	const cmd = createWatchCommand();
+	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;
+	}
+}

package/src/commands/worktree.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, realpathSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
+import { ValidationError } from "../errors.ts";
 import { createSessionStore } from "../sessions/store.ts";
 import { cleanupTempDir, commitFile, createTempGitRepo, runGitInDir } from "../test-helpers.ts";
 import type { AgentSession } from "../types.ts";
@@ -99,30 +100,29 @@ describe("worktreeCommand", () => {
 			await worktreeCommand(["--help"]);
 			const out = output();
 
-			expect(out).toContain("overstory worktree");
+			expect(out).toContain("worktree");
 			expect(out).toContain("list");
 			expect(out).toContain("clean");
-			expect(out).toContain("--json");
 		});
 
 		test("-h shows help text", async () => {
 			await worktreeCommand(["-h"]);
 			const out = output();
 
-			expect(out).toContain("overstory worktree");
+			expect(out).toContain("worktree");
 			expect(out).toContain("list");
 		});
 	});
 
 	describe("validation", () => {
 		test("unknown subcommand throws ValidationError", async () => {
-			await expect(worktreeCommand(["unknown"])).rejects.toThrow(
-				"Unknown worktree subcommand: unknown",
-			);
+			await expect(worktreeCommand(["unknown"])).rejects.toThrow(ValidationError);
 		});
 
-		test("missing subcommand throws ValidationError with (none)", async () => {
-			await expect(worktreeCommand([])).rejects.toThrow("Unknown worktree subcommand: (none)");
+		test("empty args shows help text", async () => {
+			await worktreeCommand([]);
+			const out = output();
+			expect(out).toContain("worktree");
 		});
 	});
 

package/src/commands/worktree.ts

@@ -7,6 +7,7 @@
  */
 
 import { join } from "node:path";
+import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { createMailStore } from "../mail/store.ts";
@@ -15,10 +16,6 @@ import type { AgentSession } from "../types.ts";
 import { isBranchMerged, listWorktrees, removeWorktree } from "../worktree/manager.ts";
 import { isSessionAlive, killSession } from "../worktree/tmux.ts";
 
-function hasFlag(args: string[], flag: string): boolean {
-	return args.includes(flag);
-}
-
 /**
  * Handle `overstory worktree list`.
  */
@@ -72,14 +69,12 @@ async function handleList(root: string, json: boolean): Promise<void> {
  * Handle `overstory worktree clean [--completed] [--all] [--force]`.
  */
 async function handleClean(
-	args: string[],
+	opts: { all: boolean; force: boolean; completedOnly: boolean },
 	root: string,
 	json: boolean,
 	canonicalBranch: string,
 ): Promise<void> {
-	const all = hasFlag(args, "--all");
-	const force = hasFlag(args, "--force");
-	const completedOnly = hasFlag(args, "--completed") || !all;
+	const { force, completedOnly } = opts;
 
 	const worktrees = await listWorktrees(root);
 	const overstoryDir = join(root, ".overstory");
@@ -260,52 +255,74 @@ async function handleClean(
 	}
 }
 
+export function createWorktreeCommand(): Command {
+	const cmd = new Command("worktree").description("Manage agent worktrees");
+
+	cmd
+		.command("list")
+		.description("List worktrees with agent status")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { json?: boolean }) => {
+			const cwd = process.cwd();
+			const config = await loadConfig(cwd);
+			await handleList(config.project.root, opts.json ?? false);
+		});
+
+	cmd
+		.command("clean")
+		.description("Remove completed worktrees")
+		.option("--completed", "Only finished agents (default)")
+		.option("--all", "Force remove all worktrees")
+		.option("--force", "Delete even if branches are unmerged")
+		.option("--json", "Output as JSON")
+		.action(
+			async (opts: { completed?: boolean; all?: boolean; force?: boolean; json?: boolean }) => {
+				const cwd = process.cwd();
+				const config = await loadConfig(cwd);
+				const all = opts.all ?? false;
+				await handleClean(
+					{
+						all,
+						force: opts.force ?? false,
+						completedOnly: opts.completed ?? !all,
+					},
+					config.project.root,
+					opts.json ?? false,
+					config.project.canonicalBranch,
+				);
+			},
+		);
+
+	return cmd;
+}
+
 /**
  * Entry point for `overstory worktree <subcommand> [flags]`.
  *
  * Subcommands: list, clean.
  */
-const WORKTREE_HELP = `overstory worktree — Manage agent worktrees
-
-Usage: overstory worktree <subcommand> [flags]
-
-Subcommands:
-  list               List worktrees with agent status
-  clean              Remove completed worktrees
-                       [--completed]  Only finished agents (default)
-                       [--all]        Force remove all
-                       [--force]      Delete even if branches are unmerged
-
-Options:
-  --json             Output as JSON
-  --help, -h         Show this help`;
-
 export async function worktreeCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${WORKTREE_HELP}\n`);
+	const cmd = createWorktreeCommand();
+	cmd.exitOverride();
+
+	if (args.length === 0) {
+		process.stdout.write(cmd.helpInformation());
 		return;
 	}
 
-	const subcommand = args[0];
-	const subArgs = args.slice(1);
-	const jsonFlag = hasFlag(args, "--json");
-
-	const cwd = process.cwd();
-	const config = await loadConfig(cwd);
-	const root = config.project.root;
-	const canonicalBranch = config.project.canonicalBranch;
-
-	switch (subcommand) {
-		case "list":
-			await handleList(root, jsonFlag);
-			break;
-		case "clean":
-			await handleClean(subArgs, root, jsonFlag, canonicalBranch);
-			break;
-		default:
-			throw new ValidationError(
-				`Unknown worktree subcommand: ${subcommand ?? "(none)"}. Use: list, clean`,
-				{ field: "subcommand" },
-			);
+	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 === "commander.unknownCommand") {
+				const message = err instanceof Error ? err.message : String(err);
+				throw new ValidationError(message, { field: "subcommand" });
+			}
+		}
+		throw err;
 	}
 }

package/src/config.test.ts

@@ -265,6 +265,80 @@ providers:
 		expect(config.providers.anthropic).toEqual({ type: "native" });
 	});
 
+	test("multiple providers parsed correctly", async () => {
+		await ensureOverstoryDir();
+		await writeConfig(`
+providers:
+  anthropic:
+    type: native
+  openrouter:
+    type: gateway
+    baseUrl: https://openrouter.ai/api/v1
+    authTokenEnv: OPENROUTER_API_KEY
+  litellm:
+    type: gateway
+    baseUrl: http://localhost:4000
+    authTokenEnv: LITELLM_API_KEY
+`);
+		const config = await loadConfig(tempDir);
+		expect(Object.keys(config.providers).length).toBe(3);
+		expect(config.providers.anthropic).toEqual({ type: "native" });
+		expect(config.providers.openrouter).toEqual({
+			type: "gateway",
+			baseUrl: "https://openrouter.ai/api/v1",
+			authTokenEnv: "OPENROUTER_API_KEY",
+		});
+		expect(config.providers.litellm).toEqual({
+			type: "gateway",
+			baseUrl: "http://localhost:4000",
+			authTokenEnv: "LITELLM_API_KEY",
+		});
+	});
+
+	test("config.local.yaml adds new provider alongside config.yaml providers", async () => {
+		await ensureOverstoryDir();
+		await writeConfig(`
+providers:
+  openrouter:
+    type: gateway
+    baseUrl: https://openrouter.ai/api/v1
+    authTokenEnv: OPENROUTER_API_KEY
+`);
+		await Bun.write(
+			join(tempDir, ".overstory", "config.local.yaml"),
+			`providers:\n  litellm:\n    type: gateway\n    baseUrl: http://localhost:4000\n    authTokenEnv: LITELLM_API_KEY\n`,
+		);
+		const config = await loadConfig(tempDir);
+		// All three providers present: default anthropic + openrouter from config.yaml + litellm from config.local.yaml
+		expect(config.providers.anthropic).toEqual({ type: "native" });
+		expect(config.providers.openrouter).toEqual({
+			type: "gateway",
+			baseUrl: "https://openrouter.ai/api/v1",
+			authTokenEnv: "OPENROUTER_API_KEY",
+		});
+		expect(config.providers.litellm).toEqual({
+			type: "gateway",
+			baseUrl: "http://localhost:4000",
+			authTokenEnv: "LITELLM_API_KEY",
+		});
+	});
+
+	test("simple model strings still work without providers section", async () => {
+		await ensureOverstoryDir();
+		await writeConfig(`
+models:
+  coordinator: sonnet
+  builder: opus
+  monitor: haiku
+`);
+		const config = await loadConfig(tempDir);
+		expect(config.models.coordinator).toBe("sonnet");
+		expect(config.models.builder).toBe("opus");
+		expect(config.models.monitor).toBe("haiku");
+		// Default anthropic provider still present even without explicit providers section
+		expect(config.providers.anthropic).toEqual({ type: "native" });
+	});
+
 	test("migrates deprecated watchdog tier1/tier2 keys to tier0/tier1", async () => {
 		await ensureOverstoryDir();
 		await writeConfig(`
@@ -556,6 +630,28 @@ models:
 		await expect(loadConfig(tempDir)).rejects.toThrow(ValidationError);
 	});
 
+	test("rejects model ref with deeply nested slashes when provider unknown", async () => {
+		await writeConfig(`
+models:
+  coordinator: unknown/openai/gpt-5.3/latest
+`);
+		await expect(loadConfig(tempDir)).rejects.toThrow(ValidationError);
+	});
+
+	test("accepts model ref with deeply nested slashes when provider exists", async () => {
+		await writeConfig(`
+providers:
+  openrouter:
+    type: gateway
+    baseUrl: https://openrouter.ai/api/v1
+    authTokenEnv: OPENROUTER_API_KEY
+models:
+  coordinator: openrouter/openai/gpt-5.3/variant
+`);
+		const config = await loadConfig(tempDir);
+		expect(config.models.coordinator).toBe("openrouter/openai/gpt-5.3/variant");
+	});
+
 	test("rejects bare invalid model name", async () => {
 		await writeConfig(`
 models: