@os-eco/overstory-cli 0.6.1 → 0.6.5

package/src/commands/init.test.ts

@@ -47,7 +47,7 @@ describe("initCommand: agent-defs deployment", () => {
 	});
 
 	test("creates .overstory/agent-defs/ with all 8 agent definition files", async () => {
-		await initCommand([]);
+		await initCommand({});
 
 		const agentDefsDir = join(tempDir, ".overstory", "agent-defs");
 		const files = await readdir(agentDefsDir);
@@ -57,7 +57,7 @@ describe("initCommand: agent-defs deployment", () => {
 	});
 
 	test("copied files match source content", async () => {
-		await initCommand([]);
+		await initCommand({});
 
 		for (const fileName of AGENT_DEF_FILES) {
 			const sourcePath = join(SOURCE_AGENTS_DIR, fileName);
@@ -72,7 +72,7 @@ describe("initCommand: agent-defs deployment", () => {
 
 	test("--force reinit overwrites existing agent def files", async () => {
 		// First init
-		await initCommand([]);
+		await initCommand({});
 
 		// Tamper with one of the deployed files
 		const tamperPath = join(tempDir, ".overstory", "agent-defs", "scout.md");
@@ -83,7 +83,7 @@ describe("initCommand: agent-defs deployment", () => {
 		expect(tampered).toBe("# tampered content\n");
 
 		// Reinit with --force
-		await initCommand(["--force"]);
+		await initCommand({ force: true });
 
 		// Verify the file was overwritten with the original source
 		const sourceContent = await Bun.file(join(SOURCE_AGENTS_DIR, "scout.md")).text();
@@ -92,7 +92,7 @@ describe("initCommand: agent-defs deployment", () => {
 	});
 
 	test("Stop hook includes mulch learn command", async () => {
-		await initCommand([]);
+		await initCommand({});
 
 		const hooksPath = join(tempDir, ".overstory", "hooks.json");
 		const content = await Bun.file(hooksPath).text();
@@ -105,7 +105,7 @@ describe("initCommand: agent-defs deployment", () => {
 	});
 
 	test("PostToolUse hooks include Bash-matched mulch diff hook", async () => {
-		await initCommand([]);
+		await initCommand({});
 
 		const hooksPath = join(tempDir, ".overstory", "hooks.json");
 		const content = await Bun.file(hooksPath).text();
@@ -147,7 +147,7 @@ describe("initCommand: .overstory/.gitignore", () => {
 	});
 
 	test("creates .overstory/.gitignore with wildcard+whitelist model", async () => {
-		await initCommand([]);
+		await initCommand({});
 
 		const gitignorePath = join(tempDir, ".overstory", ".gitignore");
 		const content = await Bun.file(gitignorePath).text();
@@ -167,7 +167,7 @@ describe("initCommand: .overstory/.gitignore", () => {
 
 	test("gitignore is always written when init completes", async () => {
 		// Init should write gitignore
-		await initCommand([]);
+		await initCommand({});
 
 		const gitignorePath = join(tempDir, ".overstory", ".gitignore");
 		const content = await Bun.file(gitignorePath).text();
@@ -182,7 +182,7 @@ describe("initCommand: .overstory/.gitignore", () => {
 
 	test("--force reinit overwrites stale .overstory/.gitignore", async () => {
 		// First init
-		await initCommand([]);
+		await initCommand({});
 
 		const gitignorePath = join(tempDir, ".overstory", ".gitignore");
 
@@ -195,7 +195,7 @@ describe("initCommand: .overstory/.gitignore", () => {
 		expect(tampered).not.toContain("!.gitignore\n");
 
 		// Reinit with --force
-		await initCommand(["--force"]);
+		await initCommand({ force: true });
 
 		// Verify the file was overwritten with the new wildcard+whitelist format
 		const restored = await Bun.file(gitignorePath).text();
@@ -206,7 +206,7 @@ describe("initCommand: .overstory/.gitignore", () => {
 
 	test("subsequent init without --force does not overwrite gitignore", async () => {
 		// First init
-		await initCommand([]);
+		await initCommand({});
 
 		const gitignorePath = join(tempDir, ".overstory", ".gitignore");
 
@@ -218,7 +218,7 @@ describe("initCommand: .overstory/.gitignore", () => {
 		expect(tampered).toBe("# custom content\n");
 
 		// Second init without --force should return early (not overwrite)
-		await initCommand([]);
+		await initCommand({});
 
 		// Verify the file was NOT overwritten (early return prevented it)
 		const afterSecondInit = await Bun.file(gitignorePath).text();
@@ -248,7 +248,7 @@ describe("initCommand: .overstory/README.md", () => {
 	});
 
 	test("creates .overstory/README.md with expected content", async () => {
-		await initCommand([]);
+		await initCommand({});
 
 		const readmePath = join(tempDir, ".overstory", "README.md");
 		const exists = await Bun.file(readmePath).exists();
@@ -264,7 +264,7 @@ describe("initCommand: .overstory/README.md", () => {
 
 	test("--force reinit overwrites README.md", async () => {
 		// First init
-		await initCommand([]);
+		await initCommand({});
 
 		const readmePath = join(tempDir, ".overstory", "README.md");
 
@@ -274,7 +274,7 @@ describe("initCommand: .overstory/README.md", () => {
 		expect(tampered).toBe("# tampered\n");
 
 		// Reinit with --force
-		await initCommand(["--force"]);
+		await initCommand({ force: true });
 
 		// Verify restored to canonical content
 		const restored = await Bun.file(readmePath).text();
@@ -283,7 +283,7 @@ describe("initCommand: .overstory/README.md", () => {
 
 	test("subsequent init without --force does not overwrite README.md", async () => {
 		// First init
-		await initCommand([]);
+		await initCommand({});
 
 		const readmePath = join(tempDir, ".overstory", "README.md");
 
@@ -293,7 +293,7 @@ describe("initCommand: .overstory/README.md", () => {
 		expect(tampered).toBe("# custom content\n");
 
 		// Second init without --force returns early
-		await initCommand([]);
+		await initCommand({});
 
 		// Verify tampered content preserved (early return)
 		const afterSecondInit = await Bun.file(readmePath).text();
@@ -329,7 +329,7 @@ describe("initCommand: canonical branch detection", () => {
 		// Switch to a non-standard branch name
 		await runGitInDir(tempDir, ["switch", "-c", "trunk"]);
 
-		await initCommand([]);
+		await initCommand({});
 
 		const configPath = join(tempDir, ".overstory", "config.yaml");
 		const content = await Bun.file(configPath).text();
@@ -338,7 +338,7 @@ describe("initCommand: canonical branch detection", () => {
 
 	test("standard branch names (main) still work as canonicalBranch", async () => {
 		// createTempGitRepo defaults to main branch
-		await initCommand([]);
+		await initCommand({});
 
 		const configPath = join(tempDir, ".overstory", "config.yaml");
 		const content = await Bun.file(configPath).text();

package/src/commands/init.ts

@@ -514,6 +514,10 @@ export async function writeOverstoryReadme(overstoryPath: string): Promise<void>
 	await Bun.write(readmePath, OVERSTORY_README);
 }
 
+export interface InitOptions {
+	force?: boolean;
+}
+
 /**
  * Print a success status line.
  */
@@ -526,23 +530,10 @@ function printCreated(relativePath: string): void {
  *
  * Scaffolds the .overstory/ directory structure in the current working directory.
  *
- * @param args - CLI arguments after "init" subcommand
+ * @param opts - Command options
  */
-const INIT_HELP = `overstory init — Initialize .overstory/ in current project
-
-Usage: overstory init [--force]
-
-Options:
-  --force      Reinitialize even if .overstory/ already exists
-  --help, -h   Show this help`;
-
-export async function initCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${INIT_HELP}\n`);
-		return;
-	}
-
-	const force = args.includes("--force");
+export async function initCommand(opts: InitOptions): Promise<void> {
+	const force = opts.force ?? false;
 	const projectRoot = process.cwd();
 	const overstoryPath = join(projectRoot, OVERSTORY_DIR);
 

package/src/commands/inspect.test.ts

@@ -39,7 +39,7 @@ function makeEvent(overrides: Partial<InsertEvent> = {}): InsertEvent {
 function makeMetrics(overrides: Partial<SessionMetrics> = {}): SessionMetrics {
 	return {
 		agentName: "builder-1",
-		beadId: "overstory-001",
+		taskId: "overstory-001",
 		capability: "builder",
 		startedAt: new Date().toISOString(),
 		completedAt: null,
@@ -102,7 +102,7 @@ describe("inspectCommand", () => {
 		test("--help shows help text", async () => {
 			await inspectCommand(["--help"]);
 			const out = output();
-			expect(out).toContain("overstory inspect");
+			expect(out).toContain("inspect");
 			expect(out).toContain("--json");
 			expect(out).toContain("--follow");
 			expect(out).toContain("--limit");
@@ -112,7 +112,7 @@ describe("inspectCommand", () => {
 		test("-h shows help text", async () => {
 			await inspectCommand(["-h"]);
 			const out = output();
-			expect(out).toContain("overstory inspect");
+			expect(out).toContain("inspect");
 		});
 	});
 
@@ -142,7 +142,7 @@ describe("inspectCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt",
 				branchName: "overstory/builder-1/test",
-				beadId: "overstory-001",
+				taskId: "overstory-001",
 				tmuxSession: "overstory-test-builder-1",
 				state: "working",
 				pid: 12345,
@@ -174,7 +174,7 @@ describe("inspectCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt",
 				branchName: "overstory/builder-1/test",
-				beadId: "overstory-001",
+				taskId: "overstory-001",
 				tmuxSession: "overstory-test-builder-1",
 				state: "working",
 				pid: 12345,
@@ -210,7 +210,7 @@ describe("inspectCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt",
 				branchName: "overstory/builder-1/test",
-				beadId: "overstory-001",
+				taskId: "overstory-001",
 				tmuxSession: "overstory-test-builder-1",
 				state: "working",
 				pid: 12345,
@@ -229,7 +229,7 @@ describe("inspectCommand", () => {
 			expect(data.session.agentName).toBe("builder-1");
 			expect(data.session.capability).toBe("builder");
 			expect(data.session.state).toBe("working");
-			expect(data.session.beadId).toBe("overstory-001");
+			expect(data.session.taskId).toBe("overstory-001");
 			expect(data.timeSinceLastActivity).toBeGreaterThan(4000);
 			expect(data.timeSinceLastActivity).toBeLessThan(10000);
 		});
@@ -246,7 +246,7 @@ describe("inspectCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt",
 				branchName: "overstory/builder-1/test",
-				beadId: "overstory-001",
+				taskId: "overstory-001",
 				tmuxSession: "overstory-test-builder-1",
 				state: "working",
 				pid: 12345,
@@ -285,7 +285,7 @@ describe("inspectCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt",
 				branchName: "overstory/builder-1/test",
-				beadId: "overstory-001",
+				taskId: "overstory-001",
 				tmuxSession: "overstory-test-builder-1",
 				state: "working",
 				pid: 12345,
@@ -320,7 +320,7 @@ describe("inspectCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt",
 				branchName: "overstory/builder-1/test",
-				beadId: "overstory-001",
+				taskId: "overstory-001",
 				tmuxSession: "overstory-test-builder-1",
 				state: "working",
 				pid: 12345,
@@ -355,7 +355,7 @@ describe("inspectCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt",
 				branchName: "overstory/builder-1/test",
-				beadId: "overstory-001",
+				taskId: "overstory-001",
 				tmuxSession: "overstory-test-builder-1",
 				state: "working",
 				pid: 12345,
@@ -399,7 +399,7 @@ describe("inspectCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt",
 				branchName: "overstory/builder-1/test",
-				beadId: "overstory-001",
+				taskId: "overstory-001",
 				tmuxSession: "overstory-test-builder-1",
 				state: "working",
 				pid: 12345,
@@ -442,7 +442,7 @@ describe("inspectCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt",
 				branchName: "overstory/builder-1/test",
-				beadId: "overstory-001",
+				taskId: "overstory-001",
 				tmuxSession: "overstory-test-builder-1",
 				state: "working",
 				pid: 12345,
@@ -491,7 +491,7 @@ describe("inspectCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt",
 				branchName: "overstory/builder-1/test",
-				beadId: "overstory-001",
+				taskId: "overstory-001",
 				tmuxSession: "overstory-test-builder-1",
 				state: "working",
 				pid: 12345,
@@ -528,7 +528,7 @@ describe("inspectCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt",
 				branchName: "overstory/builder-1/test",
-				beadId: "overstory-001",
+				taskId: "overstory-001",
 				tmuxSession: "overstory-test-builder-1",
 				state: "working",
 				pid: 12345,
@@ -564,7 +564,7 @@ describe("inspectCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt",
 				branchName: "overstory/builder-1/test",
-				beadId: "overstory-001",
+				taskId: "overstory-001",
 				tmuxSession: "overstory-test-builder-1",
 				state: "working",
 				pid: 12345,
@@ -601,7 +601,7 @@ describe("inspectCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt",
 				branchName: "overstory/builder-1/test",
-				beadId: "overstory-001",
+				taskId: "overstory-001",
 				tmuxSession: "overstory-test-builder-1",
 				state: "working",
 				pid: 12345,
@@ -639,7 +639,7 @@ describe("inspectCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt",
 				branchName: "overstory/builder-1/test",
-				beadId: "overstory-001",
+				taskId: "overstory-001",
 				tmuxSession: "overstory-test-builder-1",
 				state: "working",
 				pid: 12345,

package/src/commands/inspect.ts

@@ -6,6 +6,7 @@
  */
 
 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";
@@ -14,21 +15,6 @@ import { createMetricsStore } from "../metrics/store.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { AgentSession, StoredEvent, ToolStats } 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 a duration in ms to a human-readable string.
  */
@@ -49,15 +35,15 @@ function formatDuration(ms: number): string {
 function getStateIcon(state: AgentSession["state"]): string {
 	switch (state) {
 		case "booting":
-			return `${color.yellow}⏳${color.reset}`; // Yellow hourglass
+			return `${color.yellow("⏳")}`; // Yellow hourglass
 		case "working":
-			return `${color.green}●${color.reset}`; // Green circle
+			return `${color.green("●")}`; // Green circle
 		case "stalled":
-			return `${color.yellow}⚠${color.reset}`; // Yellow warning
+			return `${color.yellow("⚠")}`; // Yellow warning
 		case "completed":
-			return `${color.blue}✓${color.reset}`; // Blue checkmark
+			return `${color.blue("✓")}`; // Blue checkmark
 		case "zombie":
-			return `${color.red}☠${color.reset}`; // Red skull
+			return `${color.red("☠")}`; // Red skull
 		default:
 			return "?";
 	}
@@ -273,7 +259,7 @@ export function printInspectData(data: InspectData): void {
 	const stateIcon = getStateIcon(session.state);
 	w(`${stateIcon} State: ${session.state}\n`);
 	w(`⏱  Last activity: ${formatDuration(data.timeSinceLastActivity)} ago\n`);
-	w(`🎯 Task: ${session.beadId}\n`);
+	w(`🎯 Task: ${session.taskId}\n`);
 	w(`🔧 Capability: ${session.capability}\n`);
 	w(`🌿 Branch: ${session.branchName}\n`);
 	if (session.parentAgent) {
@@ -343,44 +329,21 @@ export function printInspectData(data: InspectData): void {
 	}
 }
 
-const INSPECT_HELP = `overstory inspect <agent-name> — Deep inspection of a single agent
-
-Usage: overstory inspect <agent-name> [options]
-
-Options:
-  --json             Output as JSON
-  --follow           Poll and refresh (clears screen, re-gathers, re-prints)
-  --interval <ms>    Polling interval for --follow in milliseconds (default: 3000, min: 500)
-  --limit <n>        Number of recent tool calls to show (default: 20)
-  --no-tmux          Skip tmux capture-pane
-  --help, -h         Show this help
-
-Examples:
-  overstory inspect builder-1
-  overstory inspect scout-alpha --json
-  overstory inspect builder-1 --follow --interval 2000`;
-
-/**
- * Entry point for `overstory inspect <agent-name>`.
- */
-export async function inspectCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${INSPECT_HELP}\n`);
-		return;
-	}
-
-	const agentName = args[0];
-	if (!agentName) {
-		throw new ValidationError("Agent name is required", {
-			field: "agent-name",
-		});
-	}
+interface InspectOpts {
+	json?: boolean;
+	follow?: boolean;
+	interval?: string;
+	limit?: string;
+	tmux?: boolean; // Commander: --no-tmux sets tmux=false
+}
 
-	const json = hasFlag(args, "--json");
-	const follow = hasFlag(args, "--follow");
-	const noTmux = hasFlag(args, "--no-tmux");
+async function executeInspect(agentName: string, opts: InspectOpts): Promise<void> {
+	const json = opts.json ?? false;
+	const follow = opts.follow ?? false;
+	// Commander --no-tmux sets opts.tmux = false
+	const noTmux = opts.tmux === false;
 
-	const intervalStr = getFlag(args, "--interval");
+	const intervalStr = opts.interval;
 	const interval = intervalStr ? Number.parseInt(intervalStr, 10) : 3000;
 	if (Number.isNaN(interval) || interval < 500) {
 		throw new ValidationError("--interval must be a number >= 500 (milliseconds)", {
@@ -389,7 +352,7 @@ export async function inspectCommand(args: string[]): Promise<void> {
 		});
 	}
 
-	const limitStr = getFlag(args, "--limit");
+	const limitStr = opts.limit;
 	const limit = limitStr ? Number.parseInt(limitStr, 10) : 20;
 	if (Number.isNaN(limit) || limit < 1) {
 		throw new ValidationError("--limit must be a number >= 1", {
@@ -429,3 +392,37 @@ export async function inspectCommand(args: string[]): Promise<void> {
 		}
 	}
 }
+
+export function createInspectCommand(): Command {
+	return new Command("inspect")
+		.description("Deep inspection of a single agent")
+		.argument("<agent-name>", "Agent name to inspect")
+		.option("--json", "Output as JSON")
+		.option("--follow", "Poll and refresh continuously")
+		.option("--interval <ms>", "Polling interval for --follow in milliseconds (default: 3000)")
+		.option("--limit <n>", "Number of recent tool calls to show (default: 20)")
+		.option("--no-tmux", "Skip tmux capture-pane")
+		.action(async (agentName: string, opts: InspectOpts) => {
+			await executeInspect(agentName, opts);
+		});
+}
+
+export async function inspectCommand(args: string[]): Promise<void> {
+	const cmd = createInspectCommand();
+	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;
+	}
+}