@os-eco/overstory-cli 0.6.1 → 0.6.5

package/src/commands/dashboard.ts

@@ -10,10 +10,12 @@
  */
 
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
+import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
-import { color } from "../logging/color.ts";
+import type { ColorFn } from "../logging/color.ts";
+import { color, noColor, visibleLength } from "../logging/color.ts";
 import { createMailStore, type MailStore } from "../mail/store.ts";
 import { createMergeQueue, type MergeQueue } from "../merge/queue.ts";
 import { createMetricsStore, type MetricsStore } from "../metrics/store.ts";
@@ -23,6 +25,9 @@ import type { MailMessage } from "../types.ts";
 import { evaluateHealth } from "../watchdog/health.ts";
 import { getCachedTmuxSessions, getCachedWorktrees, type StatusData } from "./status.ts";
 
+const pkgPath = resolve(import.meta.dir, "../../package.json");
+const PKG_VERSION: string = JSON.parse(await Bun.file(pkgPath).text()).version ?? "unknown";
+
 /**
  * Terminal control codes (cursor movement, screen clearing).
  * These are not colors, so they stay separate from the color module.
@@ -49,17 +54,6 @@ const BOX = {
 	cross: "┼",
 };
 
-/**
- * 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];
-}
-
 /**
  * Format a duration in ms to a human-readable string.
  */
@@ -408,21 +402,20 @@ async function loadDashboardData(
  * Render the header bar (line 1).
  */
 function renderHeader(width: number, interval: number, currentRunId?: string | null): string {
-	const left = `${color.bold}overstory dashboard v0.2.0${color.reset}`;
+	const left = color.bold(`overstory dashboard v${PKG_VERSION}`);
 	const now = new Date().toLocaleTimeString();
 	const scope = currentRunId ? ` [run: ${currentRunId.slice(0, 8)}]` : " [all runs]";
 	const right = `${now}${scope} | refresh: ${interval}ms`;
-	const leftStripped = "overstory dashboard v0.2.0"; // for length calculation
-	const padding = width - leftStripped.length - right.length;
+	const padding = width - visibleLength(left) - right.length;
 	const line = left + " ".repeat(Math.max(0, padding)) + right;
 	const separator = horizontalLine(width, BOX.topLeft, BOX.horizontal, BOX.topRight);
 	return `${line}\n${separator}`;
 }
 
 /**
- * Get color for agent state.
+ * Get color function for agent state.
  */
-function getStateColor(state: string): string {
+function getStateColor(state: string): ColorFn {
 	switch (state) {
 		case "working":
 			return color.green;
@@ -435,7 +428,7 @@ function getStateColor(state: string): string {
 		case "completed":
 			return color.cyan;
 		default:
-			return color.white;
+			return noColor;
 	}
 }
 
@@ -472,14 +465,12 @@ function renderAgentPanel(
 	let output = "";
 
 	// Panel header
-	const headerLine = `${BOX.vertical} ${color.bold}Agents${color.reset} (${data.status.agents.length})`;
-	const headerPadding = " ".repeat(
-		Math.max(0, width - headerLine.length - 1 + color.bold.length + color.reset.length),
-	);
+	const headerLine = `${BOX.vertical} ${color.bold("Agents")} (${data.status.agents.length})`;
+	const headerPadding = " ".repeat(Math.max(0, width - visibleLength(headerLine) - 1));
 	output += `${CURSOR.cursorTo(startRow, 1)}${headerLine}${headerPadding}${BOX.vertical}\n`;
 
 	// Column headers
-	const colHeaders = `${BOX.vertical} St Name            Capability    State      Bead ID          Duration  Tmux ${BOX.vertical}`;
+	const colHeaders = `${BOX.vertical} St Name            Capability    State      Task ID          Duration  Tmux ${BOX.vertical}`;
 	output += `${CURSOR.cursorTo(startRow + 1, 1)}${colHeaders}\n`;
 
 	// Separator
@@ -509,7 +500,7 @@ function renderAgentPanel(
 		const name = pad(truncate(agent.agentName, 15), 15);
 		const capability = pad(truncate(agent.capability, 12), 12);
 		const state = pad(agent.state, 10);
-		const beadId = pad(truncate(agent.beadId, 16), 16);
+		const taskId = pad(truncate(agent.taskId, 16), 16);
 		const endTime =
 			agent.state === "completed" || agent.state === "zombie"
 				? new Date(agent.lastActivity).getTime()
@@ -517,9 +508,9 @@ function renderAgentPanel(
 		const duration = formatDuration(endTime - new Date(agent.startedAt).getTime());
 		const durationPadded = pad(duration, 9);
 		const tmuxAlive = data.status.tmuxSessions.some((s) => s.name === agent.tmuxSession);
-		const tmuxDot = tmuxAlive ? `${color.green}●${color.reset}` : `${color.red}○${color.reset}`;
+		const tmuxDot = tmuxAlive ? color.green("●") : color.red("○");
 
-		const line = `${BOX.vertical} ${stateColor}${icon}${color.reset}  ${name} ${capability} ${stateColor}${state}${color.reset} ${beadId} ${durationPadded} ${tmuxDot}    ${BOX.vertical}`;
+		const line = `${BOX.vertical} ${stateColor(icon)}  ${name} ${capability} ${stateColor(state)} ${taskId} ${durationPadded} ${tmuxDot}    ${BOX.vertical}`;
 		output += `${CURSOR.cursorTo(startRow + 3 + i, 1)}${line}\n`;
 	}
 
@@ -537,20 +528,20 @@ function renderAgentPanel(
 }
 
 /**
- * Get color for mail priority.
+ * Get color function for mail priority.
  */
-function getPriorityColor(priority: string): string {
+function getPriorityColor(priority: string): ColorFn {
 	switch (priority) {
 		case "urgent":
 			return color.red;
 		case "high":
 			return color.yellow;
 		case "normal":
-			return color.white;
+			return noColor;
 		case "low":
 			return color.dim;
 		default:
-			return color.white;
+			return noColor;
 	}
 }
 
@@ -568,10 +559,8 @@ function renderMailPanel(
 	let output = "";
 
 	const unreadCount = data.status.unreadMailCount;
-	const headerLine = `${BOX.vertical} ${color.bold}Mail${color.reset} (${unreadCount} unread)`;
-	const headerPadding = " ".repeat(
-		Math.max(0, panelWidth - headerLine.length - 1 + color.bold.length + color.reset.length),
-	);
+	const headerLine = `${BOX.vertical} ${color.bold("Mail")} (${unreadCount} unread)`;
+	const headerPadding = " ".repeat(Math.max(0, panelWidth - visibleLength(headerLine) - 1));
 	output += `${CURSOR.cursorTo(startRow, 1)}${headerLine}${headerPadding}${BOX.vertical}\n`;
 
 	const separator = horizontalLine(panelWidth, BOX.tee, BOX.horizontal, BOX.cross);
@@ -584,26 +573,16 @@ function renderMailPanel(
 		const msg = messages[i];
 		if (!msg) continue;
 
-		const priorityColor = getPriorityColor(msg.priority);
+		const priorityColorFn = getPriorityColor(msg.priority);
 		const priority = msg.priority === "normal" ? "" : `[${msg.priority}] `;
 		const from = truncate(msg.from, 12);
 		const to = truncate(msg.to, 12);
 		const subject = truncate(msg.subject, panelWidth - 40);
 		const time = timeAgo(msg.createdAt);
 
-		const line = `${BOX.vertical} ${priorityColor}${priority}${color.reset}${from} → ${to}: ${subject} (${time})`;
-		const padding = " ".repeat(
-			Math.max(
-				0,
-				panelWidth -
-					line.length -
-					1 +
-					priorityColor.length +
-					color.reset.length +
-					priorityColor.length +
-					color.reset.length,
-			),
-		);
+		const coloredPriority = priority ? priorityColorFn(priority) : "";
+		const line = `${BOX.vertical} ${coloredPriority}${from} → ${to}: ${subject} (${time})`;
+		const padding = " ".repeat(Math.max(0, panelWidth - visibleLength(line) - 1));
 		output += `${CURSOR.cursorTo(startRow + 2 + i, 1)}${line}${padding}${BOX.vertical}\n`;
 	}
 
@@ -617,9 +596,9 @@ function renderMailPanel(
 }
 
 /**
- * Get color for merge queue status.
+ * Get color function for merge queue status.
  */
-function getMergeStatusColor(status: string): string {
+function getMergeStatusColor(status: string): ColorFn {
 	switch (status) {
 		case "pending":
 			return color.yellow;
@@ -630,7 +609,7 @@ function getMergeStatusColor(status: string): string {
 		case "merged":
 			return color.green;
 		default:
-			return color.white;
+			return noColor;
 	}
 }
 
@@ -648,10 +627,8 @@ function renderMergeQueuePanel(
 	const panelWidth = width - startCol + 1;
 	let output = "";
 
-	const headerLine = `${BOX.vertical} ${color.bold}Merge Queue${color.reset} (${data.mergeQueue.length})`;
-	const headerPadding = " ".repeat(
-		Math.max(0, panelWidth - headerLine.length - 1 + color.bold.length + color.reset.length),
-	);
+	const headerLine = `${BOX.vertical} ${color.bold("Merge Queue")} (${data.mergeQueue.length})`;
+	const headerPadding = " ".repeat(Math.max(0, panelWidth - visibleLength(headerLine) - 1));
 	output += `${CURSOR.cursorTo(startRow, startCol)}${headerLine}${headerPadding}${BOX.vertical}\n`;
 
 	const separator = horizontalLine(panelWidth, BOX.cross, BOX.horizontal, BOX.teeRight);
@@ -664,15 +641,13 @@ function renderMergeQueuePanel(
 		const entry = entries[i];
 		if (!entry) continue;
 
-		const statusColor = getMergeStatusColor(entry.status);
+		const statusColorFn = getMergeStatusColor(entry.status);
 		const status = pad(entry.status, 10);
 		const agent = truncate(entry.agentName, 15);
 		const branch = truncate(entry.branchName, panelWidth - 30);
 
-		const line = `${BOX.vertical} ${statusColor}${status}${color.reset} ${agent} ${branch}`;
-		const padding = " ".repeat(
-			Math.max(0, panelWidth - line.length - 1 + statusColor.length + color.reset.length),
-		);
+		const line = `${BOX.vertical} ${statusColorFn(status)} ${agent} ${branch}`;
+		const padding = " ".repeat(Math.max(0, panelWidth - visibleLength(line) - 1));
 		output += `${CURSOR.cursorTo(startRow + 2 + i, startCol)}${line}${padding}${BOX.vertical}\n`;
 	}
 
@@ -699,10 +674,8 @@ function renderMetricsPanel(
 	const separator = horizontalLine(width, BOX.tee, BOX.horizontal, BOX.teeRight);
 	output += `${CURSOR.cursorTo(startRow, 1)}${separator}\n`;
 
-	const headerLine = `${BOX.vertical} ${color.bold}Metrics${color.reset}`;
-	const headerPadding = " ".repeat(
-		Math.max(0, width - headerLine.length - 1 + color.bold.length + color.reset.length),
-	);
+	const headerLine = `${BOX.vertical} ${color.bold("Metrics")}`;
+	const headerPadding = " ".repeat(Math.max(0, width - visibleLength(headerLine) - 1));
 	output += `${CURSOR.cursorTo(startRow + 1, 1)}${headerLine}${headerPadding}${BOX.vertical}\n`;
 
 	const totalSessions = data.metrics.totalSessions;
@@ -756,38 +729,15 @@ function renderDashboard(data: DashboardData, interval: number): void {
 	process.stdout.write(output);
 }
 
-/**
- * Entry point for `overstory dashboard [--interval <ms>] [--all]`.
- */
-const DASHBOARD_HELP = `overstory dashboard — Live TUI dashboard for agent monitoring
-
-Usage: overstory dashboard [--interval <ms>] [--all]
-
-Options:
-  --interval <ms>    Poll interval in milliseconds (default: 2000, min: 500)
-  --all              Show data from all runs (default: current run only)
-  --help, -h         Show this help
-
-Dashboard panels:
-  - Agent panel: Active agents with status, capability, bead ID, duration
-  - Mail panel: Recent messages with priority and time
-  - Merge queue: Pending/merging/conflict entries
-  - Metrics: Session counts, avg duration, by-capability breakdown
-
-By default the dashboard scopes all panels to the current run (current-run.txt).
-Use --all to see data across all runs.
-
-Press Ctrl+C to exit.`;
-
-export async function dashboardCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${DASHBOARD_HELP}\n`);
-		return;
-	}
+interface DashboardOpts {
+	interval?: string;
+	all?: boolean;
+}
 
-	const intervalStr = getFlag(args, "--interval");
+async function executeDashboard(opts: DashboardOpts): Promise<void> {
+	const intervalStr = opts.interval;
 	const interval = intervalStr ? Number.parseInt(intervalStr, 10) : 2000;
-	const showAll = args.includes("--all");
+	const showAll = opts.all ?? false;
 
 	if (Number.isNaN(interval) || interval < 500) {
 		throw new ValidationError("--interval must be a number >= 500 (milliseconds)", {
@@ -836,3 +786,33 @@ export async function dashboardCommand(args: string[]): Promise<void> {
 		await Bun.sleep(interval);
 	}
 }
+
+export function createDashboardCommand(): Command {
+	return new Command("dashboard")
+		.description("Live TUI dashboard for agent monitoring (Ctrl+C to stop)")
+		.option("--interval <ms>", "Poll interval in milliseconds (default: 2000, min: 500)")
+		.option("--all", "Show data from all runs (default: current run only)")
+		.action(async (opts: DashboardOpts) => {
+			await executeDashboard(opts);
+		});
+}
+
+export async function dashboardCommand(args: string[]): Promise<void> {
+	const cmd = createDashboardCommand();
+	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/doctor.test.ts

@@ -61,7 +61,7 @@ describe("doctorCommand", () => {
 			await doctorCommand(["--help"], { checkRunners: [] });
 			const out = output();
 
-			expect(out).toContain("overstory doctor");
+			expect(out).toContain("doctor");
 			expect(out).toContain("Run health checks");
 			expect(out).toContain("--json");
 			expect(out).toContain("--verbose");
@@ -72,7 +72,7 @@ describe("doctorCommand", () => {
 			await doctorCommand(["-h"], { checkRunners: [] });
 			const out = output();
 
-			expect(out).toContain("overstory doctor");
+			expect(out).toContain("doctor");
 			expect(out).toContain("--help");
 		});
 	});

package/src/commands/doctor.ts

@@ -5,6 +5,7 @@
  */
 
 import { join } from "node:path";
+import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { checkAgents } from "../doctor/agents.ts";
 import { checkConfig } from "../doctor/config-check.ts";
@@ -32,18 +33,6 @@ const ALL_CHECKS: Array<{ category: DoctorCategory; fn: DoctorCheckFn }> = [
 	{ category: "version", fn: checkVersion },
 ];
 
-function hasFlag(args: string[], flag: string): boolean {
-	return args.includes(flag);
-}
-
-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];
-}
-
 /**
  * Format human-readable output for doctor checks.
  */
@@ -54,7 +43,7 @@ function printHumanReadable(
 ): void {
 	const w = process.stdout.write.bind(process.stdout);
 
-	w(`${color.bold}Overstory Doctor${color.reset}\n`);
+	w(`${color.bold("Overstory Doctor")}\n`);
 	w("================\n\n");
 
 	// Group checks by category
@@ -75,10 +64,10 @@ function printHumanReadable(
 			continue; // Skip empty categories unless verbose
 		}
 
-		w(`${color.bold}[${category}]${color.reset}\n`);
+		w(`${color.bold(`[${category}]`)}\n`);
 
 		if (categoryChecks.length === 0) {
-			w(`  ${color.dim}No checks${color.reset}\n`);
+			w(`  ${color.dim("No checks")}\n`);
 		} else {
 			for (const check of categoryChecks) {
 				// Skip passing checks unless verbose
@@ -88,17 +77,17 @@ function printHumanReadable(
 
 				const icon =
 					check.status === "pass"
-						? `${color.green}✔${color.reset}`
+						? color.green("✔")
 						: check.status === "warn"
-							? `${color.yellow}⚠${color.reset}`
-							: `${color.red}✘${color.reset}`;
+							? color.yellow("⚠")
+							: color.red("✘");
 
 				w(`  ${icon} ${check.message}\n`);
 
 				// Print details if present
 				if (check.details && check.details.length > 0) {
 					for (const detail of check.details) {
-						w(`    ${color.dim}→ ${detail}${color.reset}\n`);
+						w(`    ${color.dim(`→ ${detail}`)}\n`);
 					}
 				}
 			}
@@ -113,7 +102,7 @@ function printHumanReadable(
 	const fail = checks.filter((c) => c.status === "fail").length;
 
 	w(
-		`${color.bold}Summary:${color.reset} ${color.green}${pass} passed${color.reset}, ${color.yellow}${warn} warning${warn === 1 ? "" : "s"}${color.reset}, ${color.red}${fail} failure${fail === 1 ? "" : "s"}${color.reset}\n`,
+		`${color.bold("Summary:")} ${color.green(`${pass} passed`)}, ${color.yellow(`${warn} warning${warn === 1 ? "" : "s"}`)}, ${color.red(`${fail} failure${fail === 1 ? "" : "s"}`)}\n`,
 	);
 }
 
@@ -133,24 +122,76 @@ function printJSON(checks: DoctorCheck[]): void {
 	process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
 }
 
-const DOCTOR_HELP = `overstory doctor -- Run health checks on overstory subsystems
-
-Usage: overstory doctor [options]
-
-Options:
-  --json                 Output as JSON
-  --verbose              Show passing checks (default: only problems)
-  --category <name>      Run only one category
-  --help, -h             Show this help
-
-Categories: dependencies, structure, config, databases, consistency, agents, merge, logs, version`;
-
 /** Options for dependency injection in doctorCommand. */
 export interface DoctorCommandOptions {
 	/** Override the check runners (defaults to ALL_CHECKS). Pass [] to skip all checks. */
 	checkRunners?: Array<{ category: DoctorCategory; fn: DoctorCheckFn }>;
 }
 
+/**
+ * Create the Commander command for `overstory doctor`.
+ */
+export function createDoctorCommand(options?: DoctorCommandOptions): Command {
+	return new Command("doctor")
+		.description("Run health checks on overstory setup")
+		.option("--json", "Output as JSON")
+		.option("--verbose", "Show passing checks (default: only problems)")
+		.option("--category <name>", "Run only one category")
+		.addHelpText(
+			"after",
+			"\nCategories: dependencies, structure, config, databases, consistency, agents, merge, logs, version",
+		)
+		.action(async (opts: { json?: boolean; verbose?: boolean; category?: string }) => {
+			const json = opts.json ?? false;
+			const verbose = opts.verbose ?? false;
+			const categoryFilter = opts.category;
+
+			// Validate category filter if provided
+			if (categoryFilter !== undefined) {
+				const validCategories = ALL_CHECKS.map((c) => c.category);
+				if (!validCategories.includes(categoryFilter as DoctorCategory)) {
+					throw new ValidationError(
+						`Invalid category: ${categoryFilter}. Valid categories: ${validCategories.join(", ")}`,
+						{
+							field: "category",
+							value: categoryFilter,
+						},
+					);
+				}
+			}
+
+			const cwd = process.cwd();
+			const config = await loadConfig(cwd);
+			const overstoryDir = join(config.project.root, ".overstory");
+
+			// Filter checks by category if specified
+			const allChecks = options?.checkRunners ?? ALL_CHECKS;
+			const checksToRun = categoryFilter
+				? allChecks.filter((c) => c.category === categoryFilter)
+				: allChecks;
+
+			// Run all checks sequentially
+			const results: DoctorCheck[] = [];
+			for (const { fn } of checksToRun) {
+				const checkResults = await fn(config, overstoryDir);
+				results.push(...checkResults);
+			}
+
+			// Output results
+			if (json) {
+				printJSON(results);
+			} else {
+				printHumanReadable(results, verbose, allChecks);
+			}
+
+			// Set exit code if any check failed
+			const hasFailures = results.some((c) => c.status === "fail");
+			if (hasFailures) {
+				process.exitCode = 1;
+			}
+		});
+}
+
 /**
  * Entry point for `overstory doctor [--json] [--verbose] [--category <name>]`.
  *
@@ -160,54 +201,26 @@ export async function doctorCommand(
 	args: string[],
 	options?: DoctorCommandOptions,
 ): Promise<number | undefined> {
-	if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
-		process.stdout.write(`${DOCTOR_HELP}\n`);
-		return;
-	}
-
-	const json = hasFlag(args, "--json");
-	const verbose = hasFlag(args, "--verbose");
-	const categoryFilter = getFlag(args, "--category");
-
-	// Validate category filter if provided
-	if (categoryFilter !== undefined) {
-		const validCategories = ALL_CHECKS.map((c) => c.category);
-		if (!validCategories.includes(categoryFilter as DoctorCategory)) {
-			throw new ValidationError(
-				`Invalid category: ${categoryFilter}. Valid categories: ${validCategories.join(", ")}`,
-				{
-					field: "category",
-					value: categoryFilter,
-				},
-			);
+	const cmd = createDoctorCommand(options);
+	cmd.exitOverride();
+
+	const prevExitCode = process.exitCode as number | undefined;
+	process.exitCode = undefined;
+
+	try {
+		await cmd.parseAsync(args, { from: "user" });
+	} catch (err: unknown) {
+		process.exitCode = prevExitCode;
+		if (err && typeof err === "object" && "code" in err) {
+			const code = (err as { code: string }).code;
+			if (code === "commander.helpDisplayed" || code === "commander.version") {
+				return undefined;
+			}
 		}
+		throw err;
 	}
 
-	const cwd = process.cwd();
-	const config = await loadConfig(cwd);
-	const overstoryDir = join(config.project.root, ".overstory");
-
-	// Filter checks by category if specified
-	const allChecks = options?.checkRunners ?? ALL_CHECKS;
-	const checksToRun = categoryFilter
-		? allChecks.filter((c) => c.category === categoryFilter)
-		: allChecks;
-
-	// Run all checks sequentially
-	const results: DoctorCheck[] = [];
-	for (const { fn } of checksToRun) {
-		const checkResults = await fn(config, overstoryDir);
-		results.push(...checkResults);
-	}
-
-	// Output results
-	if (json) {
-		printJSON(results);
-	} else {
-		printHumanReadable(results, verbose, allChecks);
-	}
-
-	// Return exit code if any check failed
-	const hasFailures = results.some((c) => c.status === "fail");
-	return hasFailures ? 1 : undefined;
+	const exitCode = process.exitCode === 1 ? 1 : undefined;
+	process.exitCode = prevExitCode;
+	return exitCode;
 }

package/src/commands/errors.test.ts

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