@os-eco/overstory-cli 0.6.1 → 0.6.4

package/src/index.ts

@@ -7,85 +7,42 @@
  * Usage: overstory <command> [args...]
  */
 
-import { agentsCommand } from "./commands/agents.ts";
+import { Command } from "commander";
+import { createAgentsCommand } from "./commands/agents.ts";
 import { cleanCommand } from "./commands/clean.ts";
-import { completionsCommand } from "./commands/completions.ts";
-import { coordinatorCommand } from "./commands/coordinator.ts";
-import { costsCommand } from "./commands/costs.ts";
-import { dashboardCommand } from "./commands/dashboard.ts";
-import { doctorCommand } from "./commands/doctor.ts";
-import { errorsCommand } from "./commands/errors.ts";
-import { feedCommand } from "./commands/feed.ts";
-import { groupCommand } from "./commands/group.ts";
-import { hooksCommand } from "./commands/hooks.ts";
+import { createCompletionsCommand } from "./commands/completions.ts";
+import { createCoordinatorCommand } from "./commands/coordinator.ts";
+import { createCostsCommand } from "./commands/costs.ts";
+import { createDashboardCommand } from "./commands/dashboard.ts";
+import { createDoctorCommand } from "./commands/doctor.ts";
+import { createErrorsCommand } from "./commands/errors.ts";
+import { createFeedCommand } from "./commands/feed.ts";
+import { createGroupCommand } from "./commands/group.ts";
+import { createHooksCommand } from "./commands/hooks.ts";
 import { initCommand } from "./commands/init.ts";
-import { inspectCommand } from "./commands/inspect.ts";
-import { logCommand } from "./commands/log.ts";
+import { createInspectCommand } from "./commands/inspect.ts";
+import { createLogCommand } from "./commands/log.ts";
 import { logsCommand } from "./commands/logs.ts";
 import { mailCommand } from "./commands/mail.ts";
 import { mergeCommand } from "./commands/merge.ts";
-import { metricsCommand } from "./commands/metrics.ts";
-import { monitorCommand } from "./commands/monitor.ts";
+import { createMetricsCommand } from "./commands/metrics.ts";
+import { createMonitorCommand } from "./commands/monitor.ts";
 import { nudgeCommand } from "./commands/nudge.ts";
 import { primeCommand } from "./commands/prime.ts";
-import { replayCommand } from "./commands/replay.ts";
-import { runCommand } from "./commands/run.ts";
+import { createReplayCommand } from "./commands/replay.ts";
+import { createRunCommand } from "./commands/run.ts";
 import { slingCommand } from "./commands/sling.ts";
-import { specCommand } from "./commands/spec.ts";
-import { statusCommand } from "./commands/status.ts";
+import { specWriteCommand } from "./commands/spec.ts";
+import { createStatusCommand } from "./commands/status.ts";
 import { stopCommand } from "./commands/stop.ts";
-import { supervisorCommand } from "./commands/supervisor.ts";
+import { createSupervisorCommand } from "./commands/supervisor.ts";
 import { traceCommand } from "./commands/trace.ts";
-import { watchCommand } from "./commands/watch.ts";
-import { worktreeCommand } from "./commands/worktree.ts";
+import { createWatchCommand } from "./commands/watch.ts";
+import { createWorktreeCommand } from "./commands/worktree.ts";
 import { OverstoryError, WorktreeError } from "./errors.ts";
 import { setQuiet } from "./logging/color.ts";
 
-const VERSION = "0.6.1";
-
-const HELP = `overstory v${VERSION} — Multi-agent orchestration for Claude Code
-
-Usage: overstory <command> [args...]
-
-Commands:
-  agents <sub>            Discover and query agents (discover)
-  init                    Initialize .overstory/ in current project
-  sling <task-id>         Spawn a worker agent
-  spec <sub>              Manage task specs (write)
-  prime                   Load context for orchestrator/agent
-  stop <agent>            Terminate a running agent
-  status                  Show all active agents and project state
-  dashboard               Live TUI dashboard for agent monitoring
-  inspect <agent>         Deep inspection of a single agent
-  coordinator <sub>       Persistent coordinator agent (start/stop/status)
-  supervisor <sub>        Per-project supervisor agent (start/stop/status)
-  hooks <sub>             Manage orchestrator hooks (install/uninstall/status)
-  mail <sub>              Mail system (send/check/list/read/reply)
-  monitor <sub>           Tier 2 monitor agent (start/stop/status)
-  merge                   Merge agent branches into canonical
-  nudge <agent> [msg]     Send a text nudge to an agent
-  group <sub>             Task groups (create/status/add/remove/list)
-  clean                   Wipe runtime state (nuclear cleanup)
-  doctor                  Run health checks on overstory setup
-  worktree <sub>          Manage worktrees (list/clean)
-  log <event>             Log a hook event
-  logs [options]          Query NDJSON logs across agents
-  watch                   Start watchdog daemon
-  feed [options]          Unified real-time event stream across all agents
-  trace <target>         Chronological event timeline for agent/bead
-  errors [options]        Aggregated error view across agents
-  run [sub]               Manage runs (list/show/complete)
-  replay [options]        Interleaved chronological replay across agents
-  costs [options]          Token/cost analysis and breakdown
-  metrics                 Show session metrics
-
-Options:
-  --help, -h              Show this help
-  --version, -v           Show version
-  --quiet, -q             Suppress non-error output
-  --completions <shell>   Generate shell completions (bash, zsh, fish)
-
-Run 'overstory <command> --help' for command-specific help.`;
+const VERSION = "0.6.4";
 
 const COMMANDS = [
 	"agents",
@@ -153,164 +110,217 @@ function suggestCommand(input: string): string | undefined {
 	return bestMatch;
 }
 
-async function main(): Promise<void> {
-	const args = process.argv.slice(2);
+const program = new Command();
+
+program
+	.name("overstory")
+	.description("Multi-agent orchestration for Claude Code")
+	.version(`overstory v${VERSION}`, "-v, --version")
+	.option("-q, --quiet", "Suppress non-error output")
+	.option("--json", "JSON output")
+	.option("--verbose", "Verbose output");
 
-	// Parse global flags before command routing
-	const quietIndex = args.indexOf("--quiet");
-	const qIndex = args.indexOf("-q");
-	if (quietIndex !== -1 || qIndex !== -1) {
+// Apply global flags before any command action runs
+program.hook("preAction", (thisCmd) => {
+	const opts = thisCmd.optsWithGlobals();
+	if (opts.quiet) {
 		setQuiet(true);
-		// Remove the flag from args so commands do not see it
-		if (quietIndex !== -1) args.splice(quietIndex, 1);
-		if (qIndex !== -1) {
-			const idx = args.indexOf("-q");
-			if (idx !== -1) args.splice(idx, 1);
-		}
 	}
+});
 
-	const command = args[0];
-	const commandArgs = args.slice(1);
+// Migrated commands — use addCommand() with createXCommand() factories
+program.addCommand(createAgentsCommand());
+program.addCommand(createDoctorCommand());
+program.addCommand(createCoordinatorCommand());
+program.addCommand(createSupervisorCommand());
+program.addCommand(createHooksCommand());
+program.addCommand(createMonitorCommand());
+program.addCommand(createWorktreeCommand());
+program.addCommand(createLogCommand());
+program.addCommand(createWatchCommand());
+program.addCommand(createGroupCommand());
+program.addCommand(createCompletionsCommand());
 
-	if (!command || command === "--help" || command === "-h") {
-		process.stdout.write(`${HELP}\n`);
-		return;
-	}
+// Unmigrated commands — passthrough pattern
+program
+	.command("init")
+	.description("Initialize .overstory/ in current project")
+	.option("--force", "Reinitialize even if .overstory/ already exists")
+	.action(async (opts) => {
+		await initCommand(opts);
+	});
 
-	if (command === "--version" || command === "-v") {
-		process.stdout.write(`overstory v${VERSION}\n`);
-		return;
-	}
+program
+	.command("sling")
+	.description("Spawn a worker agent")
+	.argument("<task-id>", "Task ID to assign")
+	.option(
+		"--capability <type>",
+		"Agent type: builder | scout | reviewer | lead | merger",
+		"builder",
+	)
+	.option("--name <name>", "Unique agent name")
+	.option("--spec <path>", "Path to task spec file")
+	.option("--files <list>", "Exclusive file scope (comma-separated)")
+	.option("--parent <agent>", "Parent agent for hierarchy tracking")
+	.option("--depth <n>", "Current hierarchy depth", "0")
+	.option("--skip-scout", "Skip scout phase for lead agents")
+	.option("--skip-task-check", "Skip task existence validation")
+	.option("--force-hierarchy", "Bypass hierarchy validation")
+	.option("--json", "Output result as JSON")
+	.action(async (taskId, opts) => {
+		await slingCommand(taskId, opts);
+	});
+
+const specCmd = program.command("spec").description("Manage task specifications");
+
+specCmd
+	.command("write")
+	.description("Write a spec file to .overstory/specs/<bead-id>.md")
+	.argument("<bead-id>", "Task ID for the spec file")
+	.option("--body <content>", "Spec content (or pipe via stdin)")
+	.option("--agent <name>", "Agent writing the spec (for attribution)")
+	.action(async (beadId, opts) => {
+		await specWriteCommand(beadId, opts);
+	});
+
+program
+	.command("prime")
+	.description("Load context for orchestrator/agent")
+	.option("--agent <name>", "Prime for a specific agent")
+	.option("--compact", "Output reduced context (for PreCompact hook)")
+	.action(async (opts) => {
+		await primeCommand(opts);
+	});
+
+program
+	.command("stop")
+	.description("Terminate a running agent")
+	.argument("<agent-name>", "Name of the agent to stop")
+	.option("--force", "Force kill and force-delete branch")
+	.option("--clean-worktree", "Remove the agent's worktree after stopping")
+	.option("--json", "Output as JSON")
+	.action(async (agentName, opts) => {
+		await stopCommand(agentName, opts);
+	});
+
+program.addCommand(createStatusCommand());
+
+program.addCommand(createDashboardCommand());
+
+program.addCommand(createInspectCommand());
+
+program
+	.command("clean")
+	.description("Wipe runtime state (nuclear cleanup)")
+	.option("--all", "Wipe everything (nuclear option)")
+	.option("--mail", "Delete mail.db")
+	.option("--sessions", "Wipe sessions.db")
+	.option("--metrics", "Delete metrics.db")
+	.option("--logs", "Remove all agent logs")
+	.option("--worktrees", "Remove all worktrees + kill tmux sessions")
+	.option("--branches", "Delete all overstory/* branch refs")
+	.option("--agents", "Remove agent identity files")
+	.option("--specs", "Remove task spec files")
+	.option("--json", "Output as JSON")
+	.action(async (opts) => {
+		await cleanCommand(opts);
+	});
+
+program
+	.command("mail")
+	.description("Mail system (send/check/list/read/reply)")
+	.allowUnknownOption()
+	.allowExcessArguments()
+	.action(async (_opts, cmd) => {
+		await mailCommand(cmd.args);
+	});
+
+program
+	.command("merge")
+	.description("Merge agent branches into canonical")
+	.option("--branch <name>", "Merge a specific branch")
+	.option("--all", "Merge all pending branches in the queue")
+	.option("--into <branch>", "Target branch to merge into")
+	.option("--dry-run", "Check for conflicts without actually merging")
+	.option("--json", "Output results as JSON")
+	.action(async (opts) => {
+		await mergeCommand(opts);
+	});
+
+program
+	.command("nudge")
+	.description("Send a text nudge to an agent")
+	.allowUnknownOption()
+	.allowExcessArguments()
+	.action(async (_opts, cmd) => {
+		await nudgeCommand(cmd.args);
+	});
+
+program
+	.command("logs")
+	.description("Query NDJSON logs across agents")
+	.allowUnknownOption()
+	.allowExcessArguments()
+	.action(async (_opts, cmd) => {
+		await logsCommand(cmd.args);
+	});
+
+program
+	.command("trace")
+	.description("Chronological event timeline for agent/bead")
+	.allowUnknownOption()
+	.allowExcessArguments()
+	.action(async (_opts, cmd) => {
+		await traceCommand(cmd.args);
+	});
+
+program.addCommand(createFeedCommand());
+
+program.addCommand(createErrorsCommand());
+
+program.addCommand(createReplayCommand());
+
+program.addCommand(createRunCommand());
 
-	if (command === "--completions") {
-		completionsCommand(commandArgs);
-		return;
+program.addCommand(createCostsCommand());
+
+program.addCommand(createMetricsCommand());
+
+// Handle unknown commands with Levenshtein fuzzy-match suggestions
+program.on("command:*", (operands) => {
+	const unknown = operands[0] ?? "";
+	process.stderr.write(`Unknown command: ${unknown}\n`);
+	const suggestion = suggestCommand(unknown);
+	if (suggestion) {
+		process.stderr.write(`Did you mean '${suggestion}'?\n`);
 	}
+	process.stderr.write("Run 'overstory --help' for usage.\n");
+	process.exit(1);
+});
 
-	switch (command) {
-		case "agents":
-			await agentsCommand(commandArgs);
-			break;
-		case "init":
-			await initCommand(commandArgs);
-			break;
-		case "sling":
-			await slingCommand(commandArgs);
-			break;
-		case "spec":
-			await specCommand(commandArgs);
-			break;
-		case "prime":
-			await primeCommand(commandArgs);
-			break;
-		case "stop":
-			await stopCommand(commandArgs);
-			break;
-		case "status":
-			await statusCommand(commandArgs);
-			break;
-		case "dashboard":
-			await dashboardCommand(commandArgs);
-			break;
-		case "inspect":
-			await inspectCommand(commandArgs);
-			break;
-		case "clean":
-			await cleanCommand(commandArgs);
-			break;
-		case "doctor": {
-			const exitCode = await doctorCommand(commandArgs);
-			if (exitCode !== undefined) {
-				process.exitCode = exitCode;
-			}
-			break;
+async function main(): Promise<void> {
+	await program.parseAsync(process.argv);
+}
+
+if (import.meta.main)
+	main().catch((err: unknown) => {
+		// Friendly message when running outside a git repository
+		if (err instanceof WorktreeError && err.message.includes("not a git repository")) {
+			process.stderr.write("Not in an overstory project. Run 'overstory init' first.\n");
+			process.exit(1);
 		}
-		case "coordinator":
-			await coordinatorCommand(commandArgs);
-			break;
-		case "supervisor":
-			await supervisorCommand(commandArgs);
-			break;
-		case "hooks":
-			await hooksCommand(commandArgs);
-			break;
-		case "monitor":
-			await monitorCommand(commandArgs);
-			break;
-		case "mail":
-			await mailCommand(commandArgs);
-			break;
-		case "merge":
-			await mergeCommand(commandArgs);
-			break;
-		case "nudge":
-			await nudgeCommand(commandArgs);
-			break;
-		case "group":
-			await groupCommand(commandArgs);
-			break;
-		case "worktree":
-			await worktreeCommand(commandArgs);
-			break;
-		case "log":
-			await logCommand(commandArgs);
-			break;
-		case "logs":
-			await logsCommand(commandArgs);
-			break;
-		case "watch":
-			await watchCommand(commandArgs);
-			break;
-		case "trace":
-			await traceCommand(commandArgs);
-			break;
-		case "feed":
-			await feedCommand(commandArgs);
-			break;
-		case "errors":
-			await errorsCommand(commandArgs);
-			break;
-		case "replay":
-			await replayCommand(commandArgs);
-			break;
-		case "run":
-			await runCommand(commandArgs);
-			break;
-		case "costs":
-			await costsCommand(commandArgs);
-			break;
-		case "metrics":
-			await metricsCommand(commandArgs);
-			break;
-		default: {
-			process.stderr.write(`Unknown command: ${command}\n`);
-			const suggestion = suggestCommand(command);
-			if (suggestion) {
-				process.stderr.write(`Did you mean '${suggestion}'?\n`);
-			}
-			process.stderr.write(`Run 'overstory --help' for usage.\n`);
+		if (err instanceof OverstoryError) {
+			process.stderr.write(`Error [${err.code}]: ${err.message}\n`);
 			process.exit(1);
 		}
-	}
-}
-
-main().catch((err: unknown) => {
-	// Friendly message when running outside a git repository
-	if (err instanceof WorktreeError && err.message.includes("not a git repository")) {
-		process.stderr.write("Not in an overstory project. Run 'overstory init' first.\n");
-		process.exit(1);
-	}
-	if (err instanceof OverstoryError) {
-		process.stderr.write(`Error [${err.code}]: ${err.message}\n`);
-		process.exit(1);
-	}
-	if (err instanceof Error) {
-		process.stderr.write(`Error: ${err.message}\n`);
-		if (process.argv.includes("--verbose")) {
-			process.stderr.write(`${err.stack}\n`);
+		if (err instanceof Error) {
+			process.stderr.write(`Error: ${err.message}\n`);
+			if (process.argv.includes("--verbose")) {
+				process.stderr.write(`${err.stack}\n`);
+			}
+			process.exit(1);
 		}
+		process.stderr.write(`Unknown error: ${String(err)}\n`);
 		process.exit(1);
-	}
-	process.stderr.write(`Unknown error: ${String(err)}\n`);
-	process.exit(1);
-});
+	});