@os-eco/overstory-cli 0.6.1 → 0.6.4

package/src/commands/spec.ts

@@ -12,42 +12,9 @@ import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { ValidationError } from "../errors.ts";
 
-/** Boolean flags that do NOT consume the next arg. */
-const BOOLEAN_FLAGS = new Set(["--help", "-h"]);
-
-/**
- * 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];
-}
-
-/**
- * Extract positional arguments, skipping flag-value pairs.
- */
-function getPositionalArgs(args: string[]): string[] {
-	const positional: string[] = [];
-	let i = 0;
-	while (i < args.length) {
-		const arg = args[i];
-		if (arg?.startsWith("-")) {
-			if (BOOLEAN_FLAGS.has(arg)) {
-				i += 1;
-			} else {
-				i += 2;
-			}
-		} else {
-			if (arg !== undefined) {
-				positional.push(arg);
-			}
-			i += 1;
-		}
-	}
-	return positional;
+export interface SpecWriteOptions {
+	body?: string;
+	agent?: string;
 }
 
 /**
@@ -62,23 +29,6 @@ async function readStdin(): Promise<string> {
 	return await new Response(Bun.stdin.stream()).text();
 }
 
-const SPEC_HELP = `overstory spec -- Manage task specifications
-
-Usage: overstory spec <subcommand> [args...]
-
-Subcommands:
-  write <bead-id>          Write a spec file to .overstory/specs/<bead-id>.md
-
-Options for 'write':
-  --body <content>         Spec content (or pipe via stdin)
-  --agent <name>           Agent writing the spec (for attribution)
-  --help, -h               Show this help
-
-Examples:
-  overstory spec write task-abc --body "# Spec\\nDetails here..."
-  echo "# Spec" | overstory spec write task-abc
-  overstory spec write task-abc --body "..." --agent scout-1`;
-
 /**
  * Write a spec file to .overstory/specs/<bead-id>.md.
  *
@@ -112,57 +62,38 @@ export async function writeSpec(
 }
 
 /**
- * Entry point for `overstory spec <subcommand>`.
+ * Entry point for `overstory spec write <bead-id> [flags]`.
+ *
+ * @param beadId - The bead/task ID for the spec file
+ * @param opts - Command options
  */
-export async function specCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h") || args.length === 0) {
-		process.stdout.write(`${SPEC_HELP}\n`);
-		return;
+export async function specWriteCommand(beadId: string, opts: SpecWriteOptions): Promise<void> {
+	if (!beadId || beadId.trim().length === 0) {
+		throw new ValidationError(
+			"Bead ID is required: overstory spec write <bead-id> --body <content>",
+			{ field: "beadId" },
+		);
 	}
 
-	const subcommand = args[0];
-	const subArgs = args.slice(1);
-
-	switch (subcommand) {
-		case "write": {
-			const positional = getPositionalArgs(subArgs);
-			const beadId = positional[0];
-			if (!beadId || beadId.trim().length === 0) {
-				throw new ValidationError(
-					"Bead ID is required: overstory spec write <bead-id> --body <content>",
-					{ field: "beadId" },
-				);
-			}
-
-			const agent = getFlag(subArgs, "--agent");
-			let body = getFlag(subArgs, "--body");
+	let body = opts.body;
 
-			// If no --body flag, try reading from stdin
-			if (body === undefined) {
-				const stdinContent = await readStdin();
-				if (stdinContent.trim().length > 0) {
-					body = stdinContent;
-				}
-			}
-
-			if (body === undefined || body.trim().length === 0) {
-				throw new ValidationError("Spec body is required: use --body <content> or pipe via stdin", {
-					field: "body",
-				});
-			}
-
-			const { resolveProjectRoot } = await import("../config.ts");
-			const projectRoot = await resolveProjectRoot(process.cwd());
-
-			const specPath = await writeSpec(projectRoot, beadId, body, agent);
-			process.stdout.write(`${specPath}\n`);
-			break;
+	// If no --body flag, try reading from stdin
+	if (body === undefined) {
+		const stdinContent = await readStdin();
+		if (stdinContent.trim().length > 0) {
+			body = stdinContent;
 		}
+	}
 
-		default:
-			throw new ValidationError(
-				`Unknown spec subcommand: ${subcommand}. Run 'overstory spec --help' for usage.`,
-				{ field: "subcommand", value: subcommand },
-			);
+	if (body === undefined || body.trim().length === 0) {
+		throw new ValidationError("Spec body is required: use --body <content> or pipe via stdin", {
+			field: "body",
+		});
 	}
+
+	const { resolveProjectRoot } = await import("../config.ts");
+	const projectRoot = await resolveProjectRoot(process.cwd());
+
+	const specPath = await writeSpec(projectRoot, beadId, body, opts.agent);
+	process.stdout.write(`${specPath}\n`);
 }

package/src/commands/status.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 { createMailStore } from "../mail/store.ts";
@@ -64,21 +65,6 @@ export async function getCachedTmuxSessions(
 	}
 }
 
-/**
- * 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.
  */
@@ -323,33 +309,21 @@ export function printStatus(data: StatusData): void {
 	w(`📈 Sessions recorded: ${data.recentMetricsCount}\n`);
 }
 
-/**
- * Entry point for `overstory status [--json] [--watch]`.
- */
-const STATUS_HELP = `overstory status — Show all active agents and project state
-
-Usage: overstory status [--json] [--verbose] [--agent <name>] [--all]
-
-Options:
-  --json             Output as JSON
-  --verbose          Show extra detail per agent (worktree, logs, mail timestamps)
-  --agent <name>     Show unread mail for this agent (default: orchestrator)
-  --all              Show sessions from all runs (default: current run only)
-  --watch            (deprecated) Use 'overstory dashboard' for live monitoring
-  --interval <ms>    Poll interval for --watch in milliseconds (default: 3000)
-  --help, -h         Show this help`;
-
-export async function statusCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${STATUS_HELP}\n`);
-		return;
-	}
+interface StatusOpts {
+	json?: boolean;
+	watch?: boolean;
+	verbose?: boolean;
+	all?: boolean;
+	interval?: string;
+	agent?: string;
+}
 
-	const json = hasFlag(args, "--json");
-	const watch = hasFlag(args, "--watch");
-	const verbose = hasFlag(args, "--verbose");
-	const all = hasFlag(args, "--all");
-	const intervalStr = getFlag(args, "--interval");
+async function executeStatus(opts: StatusOpts): Promise<void> {
+	const json = opts.json ?? false;
+	const watch = opts.watch ?? false;
+	const verbose = opts.verbose ?? false;
+	const all = opts.all ?? false;
+	const intervalStr = opts.interval;
 	const interval = intervalStr ? Number.parseInt(intervalStr, 10) : 3000;
 
 	if (Number.isNaN(interval) || interval < 500) {
@@ -359,7 +333,7 @@ export async function statusCommand(args: string[]): Promise<void> {
 		});
 	}
 
-	const agentName = getFlag(args, "--agent") ?? "orchestrator";
+	const agentName = opts.agent ?? "orchestrator";
 
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
@@ -396,3 +370,33 @@ export async function statusCommand(args: string[]): Promise<void> {
 		}
 	}
 }
+
+export function createStatusCommand(): Command {
+	return new Command("status")
+		.description("Show all active agents and project state")
+		.option("--json", "Output as JSON")
+		.option("--verbose", "Show extra detail per agent (worktree, logs, mail timestamps)")
+		.option("--agent <name>", "Show unread mail for this agent (default: orchestrator)")
+		.option("--all", "Show sessions from all runs (default: current run only)")
+		.option("--watch", "(deprecated) Use 'overstory dashboard' for live monitoring")
+		.option("--interval <ms>", "Poll interval for --watch in milliseconds (default: 3000)")
+		.action(async (opts: StatusOpts) => {
+			await executeStatus(opts);
+		});
+}
+
+export async function statusCommand(args: string[]): Promise<void> {
+	const cmd = createStatusCommand();
+	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/stop.test.ts

@@ -207,37 +207,15 @@ function makeDeps(
 
 // --- Tests ---
 
-describe("stopCommand help", () => {
-	test("--help outputs help text", async () => {
-		const output = await captureStdout(() => stopCommand(["--help"]));
-		expect(output).toContain("overstory stop");
-		expect(output).toContain("<agent-name>");
-		expect(output).toContain("--force");
-		expect(output).toContain("--clean-worktree");
-		expect(output).toContain("--json");
-	});
-
-	test("-h outputs help text", async () => {
-		const output = await captureStdout(() => stopCommand(["-h"]));
-		expect(output).toContain("overstory stop");
-		expect(output).toContain("<agent-name>");
-	});
-});
-
 describe("stopCommand validation", () => {
-	test("throws ValidationError when no agent name provided", async () => {
+	test("throws ValidationError when agent name is empty string", async () => {
 		const { deps } = makeDeps();
-		await expect(stopCommand([], deps)).rejects.toThrow(ValidationError);
-	});
-
-	test("throws ValidationError when only flags are provided (no agent name)", async () => {
-		const { deps } = makeDeps();
-		await expect(stopCommand(["--json"], deps)).rejects.toThrow(ValidationError);
+		await expect(stopCommand("", {}, deps)).rejects.toThrow(ValidationError);
 	});
 
 	test("throws AgentError when agent not found", async () => {
 		const { deps } = makeDeps();
-		await expect(stopCommand(["nonexistent-agent"], deps)).rejects.toThrow(AgentError);
+		await expect(stopCommand("nonexistent-agent", {}, deps)).rejects.toThrow(AgentError);
 	});
 
 	test("throws AgentError when agent is already completed", async () => {
@@ -245,8 +223,8 @@ describe("stopCommand validation", () => {
 		saveSessionsToDb([session]);
 
 		const { deps } = makeDeps();
-		await expect(stopCommand(["my-builder"], deps)).rejects.toThrow(AgentError);
-		await expect(stopCommand(["my-builder"], deps)).rejects.toThrow(/already completed/);
+		await expect(stopCommand("my-builder", {}, deps)).rejects.toThrow(AgentError);
+		await expect(stopCommand("my-builder", {}, deps)).rejects.toThrow(/already completed/);
 	});
 
 	test("throws AgentError when agent is already zombie", async () => {
@@ -254,8 +232,8 @@ describe("stopCommand validation", () => {
 		saveSessionsToDb([session]);
 
 		const { deps } = makeDeps();
-		await expect(stopCommand(["my-builder"], deps)).rejects.toThrow(AgentError);
-		await expect(stopCommand(["my-builder"], deps)).rejects.toThrow(/zombie/);
+		await expect(stopCommand("my-builder", {}, deps)).rejects.toThrow(AgentError);
+		await expect(stopCommand("my-builder", {}, deps)).rejects.toThrow(/zombie/);
 	});
 });
 
@@ -265,7 +243,7 @@ describe("stopCommand stop behavior", () => {
 		saveSessionsToDb([session]);
 
 		const { deps, tmuxCalls } = makeDeps({ [session.tmuxSession]: true });
-		const output = await captureStdout(() => stopCommand(["my-builder"], deps));
+		const output = await captureStdout(() => stopCommand("my-builder", {}, deps));
 
 		expect(output).toContain(`Agent "my-builder" stopped`);
 		expect(output).toContain(`Tmux session killed: ${session.tmuxSession}`);
@@ -284,7 +262,7 @@ describe("stopCommand stop behavior", () => {
 		saveSessionsToDb([session]);
 
 		const { deps, tmuxCalls } = makeDeps({ [session.tmuxSession]: true });
-		await stopCommand(["my-builder"], deps);
+		await stopCommand("my-builder", {}, deps);
 
 		expect(tmuxCalls.killSession).toHaveLength(1);
 		const { store } = openSessionStore(overstoryDir);
@@ -298,7 +276,7 @@ describe("stopCommand stop behavior", () => {
 		saveSessionsToDb([session]);
 
 		const { deps, tmuxCalls } = makeDeps({ [session.tmuxSession]: true });
-		await stopCommand(["my-builder"], deps);
+		await stopCommand("my-builder", {}, deps);
 
 		expect(tmuxCalls.killSession).toHaveLength(1);
 		const { store } = openSessionStore(overstoryDir);
@@ -313,7 +291,7 @@ describe("stopCommand stop behavior", () => {
 
 		// tmux session is NOT alive
 		const { deps, tmuxCalls } = makeDeps({ [session.tmuxSession]: false });
-		const output = await captureStdout(() => stopCommand(["my-builder"], deps));
+		const output = await captureStdout(() => stopCommand("my-builder", {}, deps));
 
 		expect(output).toContain("Tmux session was already dead");
 		expect(tmuxCalls.killSession).toHaveLength(0);
@@ -332,7 +310,7 @@ describe("stopCommand --json output", () => {
 		saveSessionsToDb([session]);
 
 		const { deps } = makeDeps({ [session.tmuxSession]: true });
-		const output = await captureStdout(() => stopCommand(["my-builder", "--json"], deps));
+		const output = await captureStdout(() => stopCommand("my-builder", { json: true }, deps));
 
 		const parsed = JSON.parse(output.trim()) as Record<string, unknown>;
 		expect(parsed.stopped).toBe(true);
@@ -350,7 +328,7 @@ describe("stopCommand --json output", () => {
 
 		const { deps } = makeDeps({ [session.tmuxSession]: true });
 		const output = await captureStdout(() =>
-			stopCommand(["my-builder", "--json", "--force"], deps),
+			stopCommand("my-builder", { json: true, force: true }, deps),
 		);
 
 		const parsed = JSON.parse(output.trim()) as Record<string, unknown>;
@@ -364,7 +342,9 @@ describe("stopCommand --clean-worktree", () => {
 		saveSessionsToDb([session]);
 
 		const { deps, worktreeCalls } = makeDeps({ [session.tmuxSession]: true });
-		const output = await captureStdout(() => stopCommand(["my-builder", "--clean-worktree"], deps));
+		const output = await captureStdout(() =>
+			stopCommand("my-builder", { cleanWorktree: true }, deps),
+		);
 
 		expect(output).toContain(`Worktree removed: ${session.worktreePath}`);
 		expect(worktreeCalls.remove).toHaveLength(1);
@@ -376,7 +356,9 @@ describe("stopCommand --clean-worktree", () => {
 		saveSessionsToDb([session]);
 
 		const { deps, worktreeCalls } = makeDeps({ [session.tmuxSession]: true });
-		await captureStdout(() => stopCommand(["my-builder", "--clean-worktree", "--force"], deps));
+		await captureStdout(() =>
+			stopCommand("my-builder", { cleanWorktree: true, force: true }, deps),
+		);
 
 		expect(worktreeCalls.remove).toHaveLength(1);
 		expect(worktreeCalls.remove[0]?.options?.force).toBe(true);
@@ -389,7 +371,7 @@ describe("stopCommand --clean-worktree", () => {
 
 		const { deps } = makeDeps({ [session.tmuxSession]: true }, { shouldFail: true });
 		const { stderr, stdout } = await captureStderr(() =>
-			stopCommand(["my-builder", "--clean-worktree"], deps),
+			stopCommand("my-builder", { cleanWorktree: true }, deps),
 		);
 
 		// Agent was still stopped
@@ -410,7 +392,7 @@ describe("stopCommand --clean-worktree", () => {
 
 		const { deps } = makeDeps({ [session.tmuxSession]: true }, { shouldFail: true });
 		const { stdout } = await captureStderr(() =>
-			stopCommand(["my-builder", "--clean-worktree", "--json"], deps),
+			stopCommand("my-builder", { cleanWorktree: true, json: true }, deps),
 		);
 
 		const parsed = JSON.parse(stdout.trim()) as Record<string, unknown>;

package/src/commands/stop.ts

@@ -15,6 +15,12 @@ import { openSessionStore } from "../sessions/compat.ts";
 import { removeWorktree } from "../worktree/manager.ts";
 import { isSessionAlive, killSession } from "../worktree/tmux.ts";
 
+export interface StopOptions {
+	force?: boolean;
+	cleanWorktree?: boolean;
+	json?: boolean;
+}
+
 /** Dependency injection for testing. Uses real implementations when omitted. */
 export interface StopDeps {
 	_tmux?: {
@@ -30,50 +36,29 @@ export interface StopDeps {
 	};
 }
 
-const STOP_HELP = `overstory stop — Terminate a running agent
-
-Usage: overstory stop <agent-name> [flags]
-
-Arguments:
-  <agent-name>          Name of the agent to stop
-
-Options:
-  --force               Force kill and force-delete branch when cleaning worktree
-  --clean-worktree      Remove the agent's worktree after stopping
-  --json                Output as JSON
-  --help, -h            Show this help
-
-Examples:
-  overstory stop my-builder
-  overstory stop my-builder --clean-worktree
-  overstory stop my-builder --clean-worktree --force
-  overstory stop my-builder --json`;
-
 /**
  * Entry point for `overstory stop <agent-name>`.
  *
- * @param args - CLI arguments after "stop"
+ * @param agentName - Name of the agent to stop
+ * @param opts - Command options
  * @param deps - Optional dependency injection for testing (tmux, worktree)
  */
-export async function stopCommand(args: string[], deps: StopDeps = {}): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${STOP_HELP}\n`);
-		return;
-	}
-
-	const json = args.includes("--json");
-	const force = args.includes("--force");
-	const cleanWorktree = args.includes("--clean-worktree");
-
-	// First non-flag arg is the agent name
-	const agentName = args.find((a) => !a.startsWith("-"));
-	if (!agentName) {
+export async function stopCommand(
+	agentName: string,
+	opts: StopOptions,
+	deps: StopDeps = {},
+): Promise<void> {
+	if (!agentName || agentName.trim().length === 0) {
 		throw new ValidationError("Missing required argument: <agent-name>", {
 			field: "agentName",
 			value: "",
 		});
 	}
 
+	const json = opts.json ?? false;
+	const force = opts.force ?? false;
+	const cleanWorktree = opts.cleanWorktree ?? false;
+
 	const tmux = deps._tmux ?? { isSessionAlive, killSession };
 	const worktree = deps._worktree ?? { remove: removeWorktree };
 

package/src/commands/supervisor.test.ts

@@ -111,12 +111,10 @@ describe("supervisorCommand", () => {
 
 		try {
 			await supervisorCommand(["--help"]);
-			expect(output).toContain("overstory supervisor");
+			expect(output).toContain("supervisor");
 			expect(output).toContain("start");
 			expect(output).toContain("stop");
 			expect(output).toContain("status");
-			expect(output).toContain("--task");
-			expect(output).toContain("--name");
 		} finally {
 			process.stdout.write = originalWrite;
 		}
@@ -132,7 +130,7 @@ describe("supervisorCommand", () => {
 
 		try {
 			await supervisorCommand(["-h"]);
-			expect(output).toContain("overstory supervisor");
+			expect(output).toContain("supervisor");
 		} finally {
 			process.stdout.write = originalWrite;
 		}
@@ -148,7 +146,7 @@ describe("supervisorCommand", () => {
 
 		try {
 			await supervisorCommand([]);
-			expect(output).toContain("overstory supervisor");
+			expect(output).toContain("supervisor");
 		} finally {
 			process.stdout.write = originalWrite;
 		}