@os-eco/overstory-cli 0.6.1 → 0.6.5

package/src/commands/group.ts

@@ -8,38 +8,12 @@
  */
 
 import { join } from "node:path";
+import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { GroupError, ValidationError } from "../errors.ts";
 import { createTrackerClient, resolveBackend, type TrackerClient } from "../tracker/factory.ts";
 import type { TaskGroup, TaskGroupProgress } from "../types.ts";
 
-/** Boolean flags that do NOT consume the next arg. */
-const BOOLEAN_FLAGS = new Set(["--json", "--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;
-}
-
 /**
  * Resolve the groups.json path from the project root.
  */
@@ -322,174 +296,167 @@ function printGroupProgress(progress: TaskGroupProgress): void {
 	}
 }
 
-const GROUP_HELP = `overstory group -- Manage task groups for batch coordination
-
-Usage: overstory group <subcommand> [args...]
-
-Subcommands:
-  create '<name>' <id1> [id2...]   Create a new task group
-  status [group-id]                Show progress for one or all groups
-  add <group-id> <id1> [id2...]    Add issues to a group
-  remove <group-id> <id1> [id2...]  Remove issues from a group
-  list                             List all groups (summary)
-
-Options:
-  --json             Output as JSON
-  --skip-validation  Skip beads issue validation (for offline use)
-  --help, -h         Show this help`;
-
 /**
- * Entry point for `overstory group <subcommand>`.
+ * Create the Commander command for `overstory group`.
  */
-export async function groupCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h") || args.length === 0) {
-		process.stdout.write(`${GROUP_HELP}\n`);
-		return;
-	}
-
-	const subcommand = args[0];
-	const subArgs = args.slice(1);
-	const json = subArgs.includes("--json");
-	const skipValidation = subArgs.includes("--skip-validation");
-
-	const config = await loadConfig(process.cwd());
-	const projectRoot = config.project.root;
-	const resolvedBackend = await resolveBackend(config.taskTracker.backend, projectRoot);
-	const tracker = createTrackerClient(resolvedBackend, projectRoot);
-
-	switch (subcommand) {
-		case "create": {
-			const positional = getPositionalArgs(subArgs);
-			const name = positional[0];
-			if (!name || name.trim().length === 0) {
-				throw new ValidationError(
-					"Group name is required: overstory group create '<name>' <id1> [id2...]",
-					{ field: "name" },
+export function createGroupCommand(): Command {
+	const cmd = new Command("group").description("Manage task groups for batch coordination");
+
+	cmd
+		.command("create")
+		.description("Create a new task group")
+		.argument("<name>", "Group name")
+		.argument("<ids...>", "Issue IDs to include")
+		.option("--json", "Output as JSON")
+		.option("--skip-validation", "Skip beads issue validation (for offline use)")
+		.action(
+			async (name: string, ids: string[], opts: { json?: boolean; skipValidation?: boolean }) => {
+				const config = await loadConfig(process.cwd());
+				const projectRoot = config.project.root;
+				const resolvedBackend = await resolveBackend(config.taskTracker.backend, projectRoot);
+				const tracker = createTrackerClient(resolvedBackend, projectRoot);
+
+				const group = await createGroup(
+					projectRoot,
+					name,
+					ids,
+					opts.skipValidation ?? false,
+					tracker,
 				);
-			}
-			const issueIds = positional.slice(1);
-			if (issueIds.length === 0) {
-				throw new ValidationError(
-					"At least one issue ID is required: overstory group create '<name>' <id1> [id2...]",
-					{ field: "issueIds" },
-				);
-			}
-			const group = await createGroup(projectRoot, name, issueIds, skipValidation, tracker);
-			if (json) {
-				process.stdout.write(`${JSON.stringify(group, null, "\t")}\n`);
-			} else {
-				process.stdout.write(`Created group "${group.name}" (${group.id})\n`);
-				process.stdout.write(`  Members: ${group.memberIssueIds.join(", ")}\n`);
-			}
-			break;
-		}
-
-		case "status": {
-			const positional = getPositionalArgs(subArgs);
-			const groupId = positional[0];
-			const groups = await loadGroups(projectRoot);
-
-			if (groupId) {
-				const group = groups.find((g) => g.id === groupId);
-				if (!group) {
-					throw new GroupError(`Group "${groupId}" not found`, { groupId });
-				}
-				const progress = await getGroupProgress(projectRoot, group, groups, tracker);
-				if (json) {
-					process.stdout.write(`${JSON.stringify(progress, null, "\t")}\n`);
+				if (opts.json) {
+					process.stdout.write(`${JSON.stringify(group, null, "\t")}\n`);
 				} else {
-					printGroupProgress(progress);
+					process.stdout.write(`Created group "${group.name}" (${group.id})\n`);
+					process.stdout.write(`  Members: ${group.memberIssueIds.join(", ")}\n`);
 				}
-			} else {
-				const activeGroups = groups.filter((g) => g.status === "active");
-				if (activeGroups.length === 0) {
+			},
+		);
+
+	cmd
+		.command("status")
+		.description("Show progress for one or all groups")
+		.argument("[group-id]", "Group ID (optional, shows all if omitted)")
+		.option("--json", "Output as JSON")
+		.option("--skip-validation", "Skip beads issue validation (for offline use)")
+		.action(
+			async (groupId: string | undefined, opts: { json?: boolean; skipValidation?: boolean }) => {
+				const config = await loadConfig(process.cwd());
+				const projectRoot = config.project.root;
+				const resolvedBackend = await resolveBackend(config.taskTracker.backend, projectRoot);
+				const tracker = createTrackerClient(resolvedBackend, projectRoot);
+				const json = opts.json ?? false;
+
+				const groups = await loadGroups(projectRoot);
+
+				if (groupId) {
+					const group = groups.find((g) => g.id === groupId);
+					if (!group) {
+						throw new GroupError(`Group "${groupId}" not found`, { groupId });
+					}
+					const progress = await getGroupProgress(projectRoot, group, groups, tracker);
 					if (json) {
-						process.stdout.write("[]\n");
+						process.stdout.write(`${JSON.stringify(progress, null, "\t")}\n`);
 					} else {
-						process.stdout.write("No active groups\n");
+						printGroupProgress(progress);
 					}
-					break;
-				}
-				const progressList: TaskGroupProgress[] = [];
-				for (const group of activeGroups) {
-					const progress = await getGroupProgress(projectRoot, group, groups, tracker);
-					progressList.push(progress);
-				}
-				if (json) {
-					process.stdout.write(`${JSON.stringify(progressList, null, "\t")}\n`);
 				} else {
-					for (const progress of progressList) {
-						printGroupProgress(progress);
-						process.stdout.write("\n");
+					const activeGroups = groups.filter((g) => g.status === "active");
+					if (activeGroups.length === 0) {
+						if (json) {
+							process.stdout.write("[]\n");
+						} else {
+							process.stdout.write("No active groups\n");
+						}
+						return;
+					}
+					const progressList: TaskGroupProgress[] = [];
+					for (const group of activeGroups) {
+						const progress = await getGroupProgress(projectRoot, group, groups, tracker);
+						progressList.push(progress);
+					}
+					if (json) {
+						process.stdout.write(`${JSON.stringify(progressList, null, "\t")}\n`);
+					} else {
+						for (const progress of progressList) {
+							printGroupProgress(progress);
+							process.stdout.write("\n");
+						}
 					}
 				}
-			}
-			break;
-		}
-
-		case "add": {
-			const positional = getPositionalArgs(subArgs);
-			const groupId = positional[0];
-			if (!groupId || groupId.trim().length === 0) {
-				throw new ValidationError(
-					"Group ID is required: overstory group add <group-id> <id1> [id2...]",
-					{ field: "groupId" },
+			},
+		);
+
+	cmd
+		.command("add")
+		.description("Add issues to a group")
+		.argument("<group-id>", "Group ID")
+		.argument("<ids...>", "Issue IDs to add")
+		.option("--json", "Output as JSON")
+		.option("--skip-validation", "Skip beads issue validation (for offline use)")
+		.action(
+			async (
+				groupId: string,
+				ids: string[],
+				opts: { json?: boolean; skipValidation?: boolean },
+			) => {
+				const config = await loadConfig(process.cwd());
+				const projectRoot = config.project.root;
+				const resolvedBackend = await resolveBackend(config.taskTracker.backend, projectRoot);
+				const tracker = createTrackerClient(resolvedBackend, projectRoot);
+
+				const group = await addToGroup(
+					projectRoot,
+					groupId,
+					ids,
+					opts.skipValidation ?? false,
+					tracker,
 				);
-			}
-			const issueIds = positional.slice(1);
-			if (issueIds.length === 0) {
-				throw new ValidationError(
-					"At least one issue ID is required: overstory group add <group-id> <id1> [id2...]",
-					{ field: "issueIds" },
-				);
-			}
-			const group = await addToGroup(projectRoot, groupId, issueIds, skipValidation, tracker);
-			if (json) {
+				if (opts.json) {
+					process.stdout.write(`${JSON.stringify(group, null, "\t")}\n`);
+				} else {
+					process.stdout.write(`Added ${ids.length} issue(s) to "${group.name}"\n`);
+					process.stdout.write(`  Members: ${group.memberIssueIds.join(", ")}\n`);
+				}
+			},
+		);
+
+	cmd
+		.command("remove")
+		.description("Remove issues from a group")
+		.argument("<group-id>", "Group ID")
+		.argument("<ids...>", "Issue IDs to remove")
+		.option("--json", "Output as JSON")
+		.action(async (groupId: string, ids: string[], opts: { json?: boolean }) => {
+			const config = await loadConfig(process.cwd());
+			const projectRoot = config.project.root;
+
+			const group = await removeFromGroup(projectRoot, groupId, ids);
+			if (opts.json) {
 				process.stdout.write(`${JSON.stringify(group, null, "\t")}\n`);
 			} else {
-				process.stdout.write(`Added ${issueIds.length} issue(s) to "${group.name}"\n`);
+				process.stdout.write(`Removed ${ids.length} issue(s) from "${group.name}"\n`);
 				process.stdout.write(`  Members: ${group.memberIssueIds.join(", ")}\n`);
 			}
-			break;
-		}
+		});
 
-		case "remove": {
-			const positional = getPositionalArgs(subArgs);
-			const groupId = positional[0];
-			if (!groupId || groupId.trim().length === 0) {
-				throw new ValidationError(
-					"Group ID is required: overstory group remove <group-id> <id1> [id2...]",
-					{ field: "groupId" },
-				);
-			}
-			const issueIds = positional.slice(1);
-			if (issueIds.length === 0) {
-				throw new ValidationError(
-					"At least one issue ID is required: overstory group remove <group-id> <id1> [id2...]",
-					{ field: "issueIds" },
-				);
-			}
-			const group = await removeFromGroup(projectRoot, groupId, issueIds);
-			if (json) {
-				process.stdout.write(`${JSON.stringify(group, null, "\t")}\n`);
-			} else {
-				process.stdout.write(`Removed ${issueIds.length} issue(s) from "${group.name}"\n`);
-				process.stdout.write(`  Members: ${group.memberIssueIds.join(", ")}\n`);
-			}
-			break;
-		}
+	cmd
+		.command("list")
+		.description("List all groups (summary)")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { json?: boolean }) => {
+			const config = await loadConfig(process.cwd());
+			const projectRoot = config.project.root;
 
-		case "list": {
 			const groups = await loadGroups(projectRoot);
 			if (groups.length === 0) {
-				if (json) {
+				if (opts.json) {
 					process.stdout.write("[]\n");
 				} else {
 					process.stdout.write("No groups\n");
 				}
-				break;
+				return;
 			}
-			if (json) {
+			if (opts.json) {
 				process.stdout.write(`${JSON.stringify(groups, null, "\t")}\n`);
 			} else {
 				for (const group of groups) {
@@ -499,13 +466,36 @@ export async function groupCommand(args: string[]): Promise<void> {
 					);
 				}
 			}
-			break;
-		}
+		});
 
-		default:
-			throw new ValidationError(
-				`Unknown group subcommand: ${subcommand}. Run 'overstory group --help' for usage.`,
-				{ field: "subcommand", value: subcommand },
-			);
+	return cmd;
+}
+
+/**
+ * Entry point for `overstory group <subcommand>`.
+ */
+export async function groupCommand(args: string[]): Promise<void> {
+	const cmd = createGroupCommand();
+	cmd.exitOverride();
+
+	if (args.length === 0) {
+		process.stdout.write(cmd.helpInformation());
+		return;
+	}
+
+	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/hooks.test.ts

@@ -75,7 +75,7 @@ afterEach(async () => {
 describe("hooksCommand help", () => {
 	test("--help outputs help text", async () => {
 		const output = await captureStdout(() => hooksCommand(["--help"]));
-		expect(output).toContain("overstory hooks");
+		expect(output).toContain("hooks");
 		expect(output).toContain("install");
 		expect(output).toContain("uninstall");
 		expect(output).toContain("status");
@@ -83,7 +83,7 @@ describe("hooksCommand help", () => {
 
 	test("empty args outputs help text", async () => {
 		const output = await captureStdout(() => hooksCommand([]));
-		expect(output).toContain("overstory hooks");
+		expect(output).toContain("hooks");
 	});
 
 	test("unknown subcommand throws ValidationError", async () => {

package/src/commands/hooks.ts

@@ -12,6 +12,7 @@
 
 import { mkdir, unlink } from "node:fs/promises";
 import { join } from "node:path";
+import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 
@@ -63,23 +64,6 @@ export function mergeHooksByEventType(
 	return merged;
 }
 
-const HOOKS_HELP = `overstory hooks — Manage orchestrator hooks
-
-Usage: overstory hooks <subcommand>
-
-Subcommands:
-  install                  Install orchestrator hooks to .claude/settings.local.json
-  uninstall                Remove orchestrator hooks from .claude/settings.local.json
-  status                   Check if hooks are installed
-
-Options:
-  --force                  Overwrite existing hooks in .claude/settings.local.json
-  --json                   Output as JSON
-  --help, -h               Show this help
-
-Hooks source: .overstory/hooks.json (generated by overstory init)
-Hooks target: .claude/settings.local.json (read by Claude Code)`;
-
 /**
  * Install orchestrator hooks from .overstory/hooks.json to .claude/settings.local.json.
  *
@@ -87,8 +71,7 @@ Hooks target: .claude/settings.local.json (read by Claude Code)`;
  * .claude/settings.local.json where Claude Code discovers it. Preserves any
  * existing non-hooks keys in the target file.
  */
-async function installHooks(args: string[]): Promise<void> {
-	const force = args.includes("--force");
+async function installHooks(force: boolean): Promise<void> {
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
 	const projectRoot = config.project.root;
@@ -147,7 +130,7 @@ async function installHooks(args: string[]): Promise<void> {
  * If hooks were the only content, removes the file entirely.
  * Otherwise, preserves other keys and only removes the hooks key.
  */
-async function uninstallHooks(_args: string[]): Promise<void> {
+async function uninstallHooks(): Promise<void> {
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
 	const projectRoot = config.project.root;
@@ -188,8 +171,7 @@ async function uninstallHooks(_args: string[]): Promise<void> {
 /**
  * Show hooks installation status.
  */
-async function statusHooks(args: string[]): Promise<void> {
-	const json = args.includes("--json");
+async function statusHooks(json: boolean): Promise<void> {
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
 	const projectRoot = config.project.root;
@@ -222,32 +204,60 @@ async function statusHooks(args: string[]): Promise<void> {
 	}
 }
 
+export function createHooksCommand(): Command {
+	const cmd = new Command("hooks").description("Manage orchestrator hooks");
+
+	cmd
+		.command("install")
+		.description("Install orchestrator hooks to .claude/settings.local.json")
+		.option("--force", "Overwrite existing hooks")
+		.action(async (opts: { force?: boolean }) => {
+			await installHooks(opts.force ?? false);
+		});
+
+	cmd
+		.command("uninstall")
+		.description("Remove orchestrator hooks from .claude/settings.local.json")
+		.action(async () => {
+			await uninstallHooks();
+		});
+
+	cmd
+		.command("status")
+		.description("Check if hooks are installed")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { json?: boolean }) => {
+			await statusHooks(opts.json ?? false);
+		});
+
+	return cmd;
+}
+
 /**
  * Entry point for `overstory hooks <subcommand>`.
  */
 export async function hooksCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h") || args.length === 0) {
-		process.stdout.write(`${HOOKS_HELP}\n`);
+	const cmd = createHooksCommand();
+	cmd.exitOverride();
+
+	if (args.length === 0) {
+		process.stdout.write(cmd.helpInformation());
 		return;
 	}
 
-	const subcommand = args[0];
-	const subArgs = args.slice(1);
-
-	switch (subcommand) {
-		case "install":
-			await installHooks(subArgs);
-			break;
-		case "uninstall":
-			await uninstallHooks(subArgs);
-			break;
-		case "status":
-			await statusHooks(subArgs);
-			break;
-		default:
-			throw new ValidationError(
-				`Unknown hooks subcommand: ${subcommand}. Run 'overstory hooks --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;
 	}
 }