@os-eco/overstory-cli 0.6.1 → 0.6.5

package/src/commands/trace.ts

@@ -2,19 +2,21 @@
  * CLI command: overstory trace <target> [--json] [--since <ts>] [--until <ts>] [--limit <n>]
  *
  * Shows a chronological timeline of events for an agent or bead task.
- * Target can be an agent name or a bead ID (resolved to agent name via SessionStore).
+ * Target can be an agent name or a task ID (resolved to agent name via SessionStore).
  */
 
 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 },
@@ -27,22 +29,7 @@ const EVENT_LABELS: Record<EventType, { label: string; color: string }> = {
 };
 
 /**
- * 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.
+ * Detect whether a target string looks like a task ID.
  * Bead IDs follow the pattern: word-alphanumeric (e.g., "overstory-rj1k", "myproject-abc1").
  */
 function looksLikeBeadId(target: string): boolean {
@@ -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) {
@@ -273,15 +221,15 @@ export async function traceCommand(args: string[]): Promise<void> {
 	let agentName = target;
 
 	if (looksLikeBeadId(target)) {
-		// Try to resolve bead ID to agent name via SessionStore
+		// Try to resolve task ID to agent name via SessionStore
 		const { store: sessionStore } = openSessionStore(overstoryDir);
 		try {
 			const allSessions = sessionStore.getAll();
-			const matchingSession = allSessions.find((s) => s.beadId === target);
+			const matchingSession = allSessions.find((s) => s.taskId === target);
 			if (matchingSession) {
 				agentName = matchingSession.agentName;
 			} else {
-				// No session found for this bead ID; treat it as an agent name anyway
+				// No session found for this task ID; treat it as an agent name anyway
 				// (the event query will return empty results if no events match)
 				agentName = target;
 			}
@@ -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 task 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;
+	}
+}