@os-eco/overstory-cli 0.6.1 → 0.6.4

package/src/commands/merge.ts

@@ -19,21 +19,12 @@ import { createMergeResolver } from "../merge/resolver.ts";
 import { createMulchClient } from "../mulch/client.ts";
 import type { MergeEntry, MergeResult } from "../types.ts";
 
-/**
- * Parse a named flag value from an args array.
- * Returns the value after the flag, or undefined if not present.
- */
-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];
-}
-
-/** Check if a boolean flag is present in the args. */
-function hasFlag(args: string[], flag: string): boolean {
-	return args.includes(flag);
+export interface MergeOptions {
+	branch?: string;
+	all?: boolean;
+	into?: string;
+	dryRun?: boolean;
+	json?: boolean;
 }
 
 /**
@@ -135,35 +126,14 @@ function formatDryRun(entry: MergeEntry): string {
 /**
  * Entry point for `overstory merge [flags]`.
  *
- * Flags:
- *   --branch <name>  Merge a specific branch
- *   --all            Merge all pending branches in the queue
- *   --dry-run        Check for conflicts without actually merging
- *   --json           Output results as JSON
+ * @param opts - Command options
  */
-const MERGE_HELP = `overstory merge — Merge agent branches into canonical
-
-Usage: overstory merge --branch <name> | --all [--into <branch>] [--dry-run] [--json]
-
-Options:
-  --branch <name>   Merge a specific branch
-  --all             Merge all pending branches in the queue
-  --into <branch>   Target branch to merge into (default: config canonicalBranch)
-  --dry-run         Check for conflicts without actually merging
-  --json            Output results as JSON
-  --help, -h        Show this help`;
-
-export async function mergeCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${MERGE_HELP}\n`);
-		return;
-	}
-
-	const branchName = getFlag(args, "--branch");
-	const all = hasFlag(args, "--all");
-	const into = getFlag(args, "--into");
-	const dryRun = hasFlag(args, "--dry-run");
-	const json = hasFlag(args, "--json");
+export async function mergeCommand(opts: MergeOptions): Promise<void> {
+	const branchName = opts.branch;
+	const all = opts.all ?? false;
+	const into = opts.into;
+	const dryRun = opts.dryRun ?? false;
+	const json = opts.json ?? false;
 
 	if (!branchName && !all) {
 		throw new ValidationError("Either --branch <name> or --all is required for overstory merge", {

package/src/commands/metrics.test.ts

@@ -77,7 +77,7 @@ describe("metricsCommand", () => {
 		await metricsCommand(["--help"]);
 		const out = output();
 
-		expect(out).toContain("overstory metrics");
+		expect(out).toContain("metrics");
 		expect(out).toContain("--last <n>");
 		expect(out).toContain("--json");
 		expect(out).toContain("--help");
@@ -87,7 +87,7 @@ describe("metricsCommand", () => {
 		await metricsCommand(["-h"]);
 		const out = output();
 
-		expect(out).toContain("overstory metrics");
+		expect(out).toContain("metrics");
 		expect(out).toContain("--last <n>");
 	});
 

package/src/commands/metrics.ts

@@ -6,22 +6,13 @@
  */
 
 import { join } from "node:path";
+import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { createMetricsStore } from "../metrics/store.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);
+interface MetricsOpts {
+	last?: string;
+	json?: boolean;
 }
 
 /**
@@ -39,27 +30,9 @@ function formatDuration(ms: number): string {
 	return `${hours}h ${remainMin}m`;
 }
 
-/**
- * Entry point for `overstory metrics [--last <n>] [--json]`.
- */
-const METRICS_HELP = `overstory metrics — Show session metrics
-
-Usage: overstory metrics [--last <n>] [--json]
-
-Options:
-  --last <n>         Number of recent sessions to show (default: 20)
-  --json             Output as JSON
-  --help, -h         Show this help`;
-
-export async function metricsCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${METRICS_HELP}\n`);
-		return;
-	}
-
-	const lastStr = getFlag(args, "--last");
-	const limit = lastStr ? Number.parseInt(lastStr, 10) : 20;
-	const json = hasFlag(args, "--json");
+async function executeMetrics(opts: MetricsOpts): Promise<void> {
+	const limit = opts.last ? Number.parseInt(opts.last, 10) : 20;
+	const json = opts.json ?? false;
 
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
@@ -141,3 +114,29 @@ export async function metricsCommand(args: string[]): Promise<void> {
 		store.close();
 	}
 }
+
+export function createMetricsCommand(): Command {
+	return new Command("metrics")
+		.description("Show session metrics")
+		.option("--last <n>", "Number of recent sessions to show (default: 20)")
+		.option("--json", "Output as JSON")
+		.action(async (opts: MetricsOpts) => {
+			await executeMetrics(opts);
+		});
+}
+
+export async function metricsCommand(args: string[]): Promise<void> {
+	const cmd = createMetricsCommand();
+	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/monitor.test.ts

@@ -89,7 +89,7 @@ describe("monitorCommand", () => {
 	test("--help prints help text containing 'overstory monitor'", async () => {
 		await monitorCommand(["--help"]);
 		const output = stdoutWrites.join("");
-		expect(output).toContain("overstory monitor");
+		expect(output).toContain("monitor");
 	});
 
 	test("--help prints help text containing 'start'", async () => {
@@ -113,13 +113,13 @@ describe("monitorCommand", () => {
 	test("-h prints help text", async () => {
 		await monitorCommand(["-h"]);
 		const output = stdoutWrites.join("");
-		expect(output).toContain("overstory monitor");
+		expect(output).toContain("monitor");
 	});
 
 	test("empty args [] shows help (same as --help)", async () => {
 		await monitorCommand([]);
 		const output = stdoutWrites.join("");
-		expect(output).toContain("overstory monitor");
+		expect(output).toContain("monitor");
 	});
 
 	test("unknown subcommand 'restart' throws ValidationError", async () => {

package/src/commands/monitor.ts

@@ -15,6 +15,7 @@
 
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
+import { Command } from "commander";
 import { deployHooks } from "../agents/hooks-deployer.ts";
 import { createIdentity, loadIdentity } from "../agents/identity.ts";
 import { createManifestLoader, resolveModel } from "../agents/manifest.ts";
@@ -50,15 +51,6 @@ export function buildMonitorBeacon(): string {
 	return parts.join(" — ");
 }
 
-/**
- * Determine whether to auto-attach to the tmux session after starting.
- */
-function resolveAttach(args: string[], isTTY: boolean): boolean {
-	if (args.includes("--attach")) return true;
-	if (args.includes("--no-attach")) return false;
-	return isTTY;
-}
-
 /**
  * Start the monitor agent.
  *
@@ -70,9 +62,8 @@ function resolveAttach(args: string[], isTTY: boolean): boolean {
  * 6. Send startup beacon
  * 7. Record session in SessionStore (sessions.db)
  */
-async function startMonitor(args: string[]): Promise<void> {
-	const json = args.includes("--json");
-	const shouldAttach = resolveAttach(args, !!process.stdout.isTTY);
+async function startMonitor(opts: { json: boolean; attach: boolean }): Promise<void> {
+	const { json, attach: shouldAttach } = opts;
 
 	if (isRunningAsRoot()) {
 		throw new AgentError(
@@ -118,8 +109,6 @@ async function startMonitor(args: string[]): Promise<void> {
 		}
 
 		// Deploy monitor-specific hooks to the project root's .claude/ directory.
-		// The monitor gets the same structural enforcement as other non-implementation
-		// agents (Write/Edit/NotebookEdit blocked, dangerous bash commands blocked).
 		await deployHooks(projectRoot, MONITOR_NAME, "monitor");
 
 		// Create monitor identity if first run
@@ -146,7 +135,6 @@ async function startMonitor(args: string[]): Promise<void> {
 		const { model, env } = resolveModel(config, manifest, "monitor", "sonnet");
 
 		// Spawn tmux session at project root with Claude Code (interactive mode).
-		// Inject the monitor base definition via --append-system-prompt.
 		const agentDefPath = join(projectRoot, ".overstory", "agent-defs", "monitor.md");
 		const agentDefFile = Bun.file(agentDefPath);
 		let claudeCmd = `claude --model ${model} --dangerously-skip-permissions`;
@@ -226,8 +214,8 @@ async function startMonitor(args: string[]): Promise<void> {
  * 2. Kill the tmux session (with process tree cleanup)
  * 3. Mark session as completed in SessionStore
  */
-async function stopMonitor(args: string[]): Promise<void> {
-	const json = args.includes("--json");
+async function stopMonitor(opts: { json: boolean }): Promise<void> {
+	const { json } = opts;
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
 	const projectRoot = config.project.root;
@@ -273,8 +261,8 @@ async function stopMonitor(args: string[]): Promise<void> {
  *
  * Checks session registry and tmux liveness to report actual state.
  */
-async function statusMonitor(args: string[]): Promise<void> {
-	const json = args.includes("--json");
+async function statusMonitor(opts: { json: boolean }): Promise<void> {
+	const { json } = opts;
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
 	const projectRoot = config.project.root;
@@ -301,8 +289,6 @@ async function statusMonitor(args: string[]): Promise<void> {
 		const alive = await isSessionAlive(session.tmuxSession);
 
 		// Reconcile state: if session says active but tmux is dead, update.
-		// We already filtered out completed/zombie states above, so if tmux is dead
-		// this session needs to be marked as zombie.
 		if (!alive) {
 			store.updateState(MONITOR_NAME, "zombie");
 			store.updateLastActivity(MONITOR_NAME);
@@ -335,56 +321,65 @@ async function statusMonitor(args: string[]): Promise<void> {
 	}
 }
 
-const MONITOR_HELP = `overstory monitor — Manage the persistent Tier 2 monitor agent
-
-Usage: overstory monitor <subcommand> [flags]
-
-Subcommands:
-  start                    Start the monitor (spawns Claude Code at project root)
-  stop                     Stop the monitor (kills tmux session)
-  status                   Show monitor state
+export function createMonitorCommand(): Command {
+	const cmd = new Command("monitor").description("Manage the persistent Tier 2 monitor agent");
+
+	cmd
+		.command("start")
+		.description("Start the monitor (spawns Claude Code at project root)")
+		.option("--attach", "Always attach to tmux session after start")
+		.option("--no-attach", "Never attach to tmux session after start")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { attach?: boolean; json?: boolean }) => {
+			// opts.attach = true if --attach, false if --no-attach, undefined if neither
+			const shouldAttach = opts.attach !== undefined ? opts.attach : !!process.stdout.isTTY;
+			await startMonitor({ json: opts.json ?? false, attach: shouldAttach });
+		});
 
-Start options:
-  --attach                 Always attach to tmux session after start
-  --no-attach              Never attach to tmux session after start
-                           Default: attach when running in an interactive TTY
+	cmd
+		.command("stop")
+		.description("Stop the monitor (kills tmux session)")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { json?: boolean }) => {
+			await stopMonitor({ json: opts.json ?? false });
+		});
 
-General options:
-  --json                   Output as JSON
-  --help, -h               Show this help
+	cmd
+		.command("status")
+		.description("Show monitor state")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { json?: boolean }) => {
+			await statusMonitor({ json: opts.json ?? false });
+		});
 
-The monitor agent (Tier 2) continuously patrols the agent fleet by:
-  - Checking agent health via overstory status
-  - Sending progressive nudges to stalled agents
-  - Escalating unresponsive agents to the coordinator
-  - Producing periodic health summaries`;
+	return cmd;
+}
 
 /**
  * Entry point for `overstory monitor <subcommand>`.
  */
 export async function monitorCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h") || args.length === 0) {
-		process.stdout.write(`${MONITOR_HELP}\n`);
+	const cmd = createMonitorCommand();
+	cmd.exitOverride();
+
+	if (args.length === 0) {
+		process.stdout.write(cmd.helpInformation());
 		return;
 	}
 
-	const subcommand = args[0];
-	const subArgs = args.slice(1);
-
-	switch (subcommand) {
-		case "start":
-			await startMonitor(subArgs);
-			break;
-		case "stop":
-			await stopMonitor(subArgs);
-			break;
-		case "status":
-			await statusMonitor(subArgs);
-			break;
-		default:
-			throw new ValidationError(
-				`Unknown monitor subcommand: ${subcommand}. Run 'overstory monitor --help' for usage.`,
-				{ field: "subcommand", value: 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/commands/nudge.ts

@@ -10,7 +10,8 @@
  */
 
 import { join } from "node:path";
-import { AgentError, ValidationError } from "../errors.ts";
+import { Command } from "commander";
+import { AgentError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { EventStore } from "../types.ts";
@@ -21,44 +22,6 @@ const MAX_RETRIES = 3;
 const RETRY_DELAY_MS = 500;
 const DEBOUNCE_MS = 500;
 
-/**
- * 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];
-}
-
-/** Boolean flags that do NOT consume the next arg. */
-const BOOLEAN_FLAGS = new Set(["--json", "--force", "--help", "-h"]);
-
-/**
- * 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;
-}
-
 /**
  * Load the orchestrator's registered tmux session name.
  *
@@ -317,56 +280,45 @@ export async function nudgeAgent(
 /**
  * Entry point for `overstory nudge <agent-name> [message]`.
  */
-const NUDGE_HELP = `overstory nudge — Send a text nudge to an agent
-
-Usage: overstory nudge <agent-name> [message]
-
-Arguments:
-  <agent-name>           Name of the agent to nudge
-  [message]              Text to send (default: "${DEFAULT_MESSAGE}")
-
-Options:
-  --from <name>          Sender name for the nudge prefix (default: orchestrator)
-  --force                Skip debounce check
-  --json                 Output result as JSON
-  --help, -h             Show this help`;
-
 export async function nudgeCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${NUDGE_HELP}\n`);
-		return;
-	}
-
-	const positional = getPositionalArgs(args);
-	const agentName = positional[0];
-	if (!agentName || agentName.trim().length === 0) {
-		throw new ValidationError("Agent name is required: overstory nudge <agent-name> [message]", {
-			field: "agentName",
-		});
-	}
-
-	const from = getFlag(args, "--from") ?? "orchestrator";
-	const force = args.includes("--force");
-	const json = args.includes("--json");
-
-	// Build the nudge message: prefix with sender, use custom or default text
-	const customMessage = positional.slice(1).join(" ");
-	const rawMessage = customMessage.length > 0 ? customMessage : DEFAULT_MESSAGE;
-	const message = `[NUDGE from ${from}] ${rawMessage}`;
-
-	// Resolve project root
-	const { resolveProjectRoot } = await import("../config.ts");
-	const projectRoot = await resolveProjectRoot(process.cwd());
-
-	const result = await nudgeAgent(projectRoot, agentName, message, force);
-
-	if (json) {
-		process.stdout.write(
-			`${JSON.stringify({ agentName, delivered: result.delivered, reason: result.reason })}\n`,
+	const program = new Command();
+	program
+		.name("overstory nudge")
+		.description("Send a text nudge to an agent")
+		.argument("<agent-name>", "Name of the agent to nudge")
+		.argument("[message...]", "Text to send (default: check mail prompt)")
+		.option("--from <name>", "Sender name", "orchestrator")
+		.option("--force", "Skip debounce check")
+		.option("--json", "Output result as JSON")
+		.exitOverride()
+		.action(
+			async (
+				agentName: string,
+				messageParts: string[],
+				opts: { from: string; force?: boolean; json?: boolean },
+			) => {
+				// Build the nudge message: prefix with sender, use custom or default text
+				const customMessage = messageParts.join(" ");
+				const rawMessage = customMessage.length > 0 ? customMessage : DEFAULT_MESSAGE;
+				const message = `[NUDGE from ${opts.from}] ${rawMessage}`;
+
+				// Resolve project root
+				const { resolveProjectRoot } = await import("../config.ts");
+				const projectRoot = await resolveProjectRoot(process.cwd());
+
+				const result = await nudgeAgent(projectRoot, agentName, message, opts.force ?? false);
+
+				if (opts.json) {
+					process.stdout.write(
+						`${JSON.stringify({ agentName, delivered: result.delivered, reason: result.reason })}\n`,
+					);
+				} else if (result.delivered) {
+					process.stdout.write(`📢 Nudged "${agentName}"\n`);
+				} else {
+					throw new AgentError(`Nudge failed: ${result.reason}`, { agentName });
+				}
+			},
 		);
-	} else if (result.delivered) {
-		process.stdout.write(`📢 Nudged "${agentName}"\n`);
-	} else {
-		throw new AgentError(`Nudge failed: ${result.reason}`, { agentName });
-	}
+
+	await program.parseAsync(["node", "overstory-nudge", ...args]);
 }