@os-eco/overstory-cli 0.6.1 → 0.6.5

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]);
 }

package/src/commands/prime.test.ts

@@ -66,41 +66,9 @@ describe("primeCommand", () => {
 		return stderrChunks.join("");
 	}
 
-	describe("Help", () => {
-		test("--help shows help text", async () => {
-			await primeCommand(["--help"]);
-			const out = output();
-
-			expect(out).toContain("overstory prime");
-			expect(out).toContain("--agent");
-			expect(out).toContain("--compact");
-		});
-
-		test("-h shows help text", async () => {
-			await primeCommand(["-h"]);
-			const out = output();
-
-			expect(out).toContain("overstory prime");
-			expect(out).toContain("--agent");
-			expect(out).toContain("--compact");
-		});
-	});
-
-	describe("parseArgs validation", () => {
-		test("--agent without a name throws AgentError", async () => {
-			await expect(primeCommand(["--agent"])).rejects.toThrow("--agent requires a name argument");
-		});
-
-		test("--agent followed by another flag throws AgentError", async () => {
-			await expect(primeCommand(["--agent", "--compact"])).rejects.toThrow(
-				"--agent requires a name argument",
-			);
-		});
-	});
-
 	describe("Orchestrator priming (no --agent flag)", () => {
 		test("default prime outputs project context", async () => {
-			await primeCommand([]);
+			await primeCommand({});
 			const out = output();
 
 			expect(out).toContain("# Overstory Context");
@@ -111,7 +79,7 @@ describe("primeCommand", () => {
 		});
 
 		test("includes agent manifest section", async () => {
-			await primeCommand([]);
+			await primeCommand({});
 			const out = output();
 
 			expect(out).toContain("## Agent Manifest");
@@ -120,7 +88,7 @@ describe("primeCommand", () => {
 		});
 
 		test("without metrics.db shows no recent sessions message", async () => {
-			await primeCommand([]);
+			await primeCommand({});
 			const out = output();
 
 			expect(out).toContain("## Recent Activity");
@@ -128,7 +96,7 @@ describe("primeCommand", () => {
 		});
 
 		test("--compact skips Recent Activity and Expertise sections", async () => {
-			await primeCommand(["--compact"]);
+			await primeCommand({ compact: true });
 			const out = output();
 
 			// Should still have project basics
@@ -143,7 +111,7 @@ describe("primeCommand", () => {
 
 	describe("Agent priming (--agent <name>)", () => {
 		test("unknown agent outputs basic context and warns", async () => {
-			await primeCommand(["--agent", "unknown-agent"]);
+			await primeCommand({ agent: "unknown-agent" });
 			const out = output();
 			const err = stderr();
 
@@ -166,13 +134,13 @@ expertiseDomains:
   - typescript
   - testing
 recentTasks:
-  - beadId: task-001
+  - taskId: task-001
     summary: "Implemented feature X"
     completedAt: "2026-01-10T12:00:00Z"
 `,
 			);
 
-			await primeCommand(["--agent", "my-builder"]);
+			await primeCommand({ agent: "my-builder" });
 			const out = output();
 
 			expect(out).toContain("# Agent Context: my-builder");
@@ -193,7 +161,7 @@ recentTasks:
 					capability: "builder",
 					worktreePath: join(tempDir, ".overstory", "worktrees", "active-builder"),
 					branchName: "overstory/active-builder/task-001",
-					beadId: "task-001",
+					taskId: "task-001",
 					tmuxSession: "overstory-active-builder",
 					state: "working",
 					pid: 12345,
@@ -212,7 +180,7 @@ recentTasks:
 				`${JSON.stringify(sessions, null, 2)}\n`,
 			);
 
-			await primeCommand(["--agent", "active-builder"]);
+			await primeCommand({ agent: "active-builder" });
 			const out = output();
 
 			expect(out).toContain("# Agent Context: active-builder");
@@ -230,7 +198,7 @@ recentTasks:
 					capability: "builder",
 					worktreePath: join(tempDir, ".overstory", "worktrees", "completed-builder"),
 					branchName: "overstory/completed-builder/task-002",
-					beadId: "task-002",
+					taskId: "task-002",
 					tmuxSession: "overstory-completed-builder",
 					state: "completed",
 					pid: null,
@@ -249,7 +217,7 @@ recentTasks:
 				`${JSON.stringify(sessions, null, 2)}\n`,
 			);
 
-			await primeCommand(["--agent", "completed-builder"]);
+			await primeCommand({ agent: "completed-builder" });
 			const out = output();
 
 			expect(out).toContain("# Agent Context: completed-builder");
@@ -265,7 +233,7 @@ recentTasks:
 				`${JSON.stringify(
 					{
 						agentName: "recovery-agent",
-						beadId: "task-003",
+						taskId: "task-003",
 						sessionId: "session-003",
 						timestamp: new Date().toISOString(),
 						progressSummary: "Implemented initial tests for prime command",
@@ -291,7 +259,7 @@ recentTasks: []
 `,
 			);
 
-			await primeCommand(["--agent", "recovery-agent", "--compact"]);
+			await primeCommand({ agent: "recovery-agent", compact: true });
 			const out = output();
 
 			expect(out).toContain("# Agent Context: recovery-agent");
@@ -317,7 +285,7 @@ recentTasks: []
 `,
 			);
 
-			await primeCommand(["--agent", "compact-agent", "--compact"]);
+			await primeCommand({ agent: "compact-agent", compact: true });
 			const out = output();
 
 			expect(out).toContain("# Agent Context: compact-agent");
@@ -340,7 +308,7 @@ recentTasks: []
 				// Save and change cwd to the git repo
 				process.chdir(gitRepoDir);
 
-				await primeCommand([]);
+				await primeCommand({});
 				const out = output();
 
 				expect(out).toContain("# Overstory Context");
@@ -375,7 +343,7 @@ recentTasks: []
 
 				process.chdir(gitRepoDir);
 
-				await primeCommand([]);
+				await primeCommand({});
 				const out = output();
 
 				expect(out).toContain("Session branch: feature/my-work (merge target)");
@@ -412,7 +380,7 @@ recentTasks: []
 			expect(existsBefore).toBe(false);
 
 			// Run primeCommand
-			await primeCommand([]);
+			await primeCommand({});
 
 			// Verify .gitignore was created with correct content
 			const content = await Bun.file(gitignorePath).text();
@@ -435,7 +403,7 @@ sessions.db
 			expect(contentBefore).toBe(staleContent);
 
 			// Run primeCommand
-			await primeCommand([]);
+			await primeCommand({});
 
 			// Verify .gitignore now has the wildcard+whitelist content
 			const contentAfter = await Bun.file(gitignorePath).text();
@@ -455,7 +423,7 @@ sessions.db
 			await new Promise((resolve) => setTimeout(resolve, 10));
 
 			// Run primeCommand
-			await primeCommand([]);
+			await primeCommand({});
 
 			// Verify content is still correct
 			const contentAfter = await Bun.file(gitignorePath).text();

package/src/commands/prime.ts

@@ -12,7 +12,6 @@ import { loadCheckpoint } from "../agents/checkpoint.ts";
 import { loadIdentity } from "../agents/identity.ts";
 import { createManifestLoader } from "../agents/manifest.ts";
 import { loadConfig } from "../config.ts";
-import { AgentError } from "../errors.ts";
 import { createMetricsStore } from "../metrics/store.ts";
 import { createMulchClient } from "../mulch/client.ts";
 import { openSessionStore } from "../sessions/compat.ts";
@@ -35,32 +34,9 @@ const OVERSTORY_GITIGNORE = `# Wildcard+whitelist: ignore everything, whitelist
 !agent-defs/
 `;
 
-/**
- * Parse CLI flags from the args array.
- *
- * Supports:
- * - `--agent <name>` — Prime for a specific agent
- * - `--compact` — Output reduced context
- */
-function parseArgs(args: string[]): { agentName: string | null; compact: boolean } {
-	let agentName: string | null = null;
-	let compact = false;
-
-	for (let i = 0; i < args.length; i++) {
-		const arg = args[i];
-		if (arg === "--agent") {
-			const next = args[i + 1];
-			if (next === undefined || next.startsWith("--")) {
-				throw new AgentError("--agent requires a name argument");
-			}
-			agentName = next;
-			i++; // Skip the value
-		} else if (arg === "--compact") {
-			compact = true;
-		}
-	}
-
-	return { agentName, compact };
+export interface PrimeOptions {
+	agent?: string;
+	compact?: boolean;
 }
 
 /**
@@ -89,7 +65,7 @@ function formatMetrics(sessions: SessionMetrics[]): string {
 		const status = s.completedAt !== null ? "completed" : "in-progress";
 		const duration = s.durationMs > 0 ? ` (${Math.round(s.durationMs / 1000)}s)` : "";
 		const merge = s.mergeResult !== null ? ` [${s.mergeResult}]` : "";
-		lines.push(`- ${s.agentName} (${s.capability}): ${s.beadId} — ${status}${duration}${merge}`);
+		lines.push(`- ${s.agentName} (${s.capability}): ${s.taskId} — ${status}${duration}${merge}`);
 	}
 	return lines.join("\n");
 }
@@ -110,7 +86,7 @@ function formatIdentity(identity: AgentIdentity): string {
 	if (identity.recentTasks.length > 0) {
 		lines.push("Recent tasks:");
 		for (const task of identity.recentTasks) {
-			lines.push(`  - ${task.beadId}: ${task.summary} (${task.completedAt})`);
+			lines.push(`  - ${task.taskId}: ${task.summary} (${task.completedAt})`);
 		}
 	}
 
@@ -156,24 +132,11 @@ async function healGitignore(overstoryDir: string): Promise<void> {
  * Gathers project state and outputs context to stdout for injection
  * into Claude Code's context.
  *
- * @param args - CLI arguments after "prime" subcommand
+ * @param opts - Command options
  */
-const PRIME_HELP = `overstory prime — Load context for orchestrator/agent
-
-Usage: overstory prime [--agent <name>] [--compact]
-
-Options:
-  --agent <name>   Prime for a specific agent (default: orchestrator)
-  --compact        Output reduced context (for PreCompact hook)
-  --help, -h       Show this help`;
-
-export async function primeCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${PRIME_HELP}\n`);
-		return;
-	}
-
-	const { agentName, compact } = parseArgs(args);
+export async function primeCommand(opts: PrimeOptions): Promise<void> {
+	const agentName = opts.agent ?? null;
+	const compact = opts.compact ?? false;
 
 	// 1. Load config
 	const config = await loadConfig(process.cwd());
@@ -221,7 +184,7 @@ async function outputAgentContext(
 	const overstoryDir = join(config.project.root, ".overstory");
 	const { store } = openSessionStore(overstoryDir);
 	let sessionExists = false;
-	let boundSession: { beadId: string } | null = null;
+	let boundSession: { taskId: string } | null = null;
 	try {
 		const agentSession = store.getByName(agentName);
 		sessionExists = agentSession !== null;
@@ -229,9 +192,9 @@ async function outputAgentContext(
 			agentSession &&
 			agentSession.state !== "completed" &&
 			agentSession.state !== "zombie" &&
-			agentSession.beadId
+			agentSession.taskId
 		) {
-			boundSession = { beadId: agentSession.beadId };
+			boundSession = { taskId: agentSession.taskId };
 		}
 	} finally {
 		store.close();
@@ -263,7 +226,7 @@ async function outputAgentContext(
 	// Activation context: if agent has a bound task, inject it
 	if (boundSession) {
 		sections.push("\n## Activation");
-		sections.push(`You have a bound task: **${boundSession.beadId}**`);
+		sections.push(`You have a bound task: **${boundSession.taskId}**`);
 		sections.push("Read your overlay at `.claude/CLAUDE.md` and begin working immediately.");
 		sections.push("Do not wait for dispatch mail. Your assignment was bound at spawn time.");
 	}

package/src/commands/replay.test.ts

@@ -78,7 +78,7 @@ describe("replayCommand", () => {
 			await replayCommand(["--help"]);
 			const out = output();
 
-			expect(out).toContain("overstory replay");
+			expect(out).toContain("replay");
 			expect(out).toContain("--run");
 			expect(out).toContain("--agent");
 			expect(out).toContain("--json");
@@ -91,7 +91,7 @@ describe("replayCommand", () => {
 			await replayCommand(["-h"]);
 			const out = output();
 
-			expect(out).toContain("overstory replay");
+			expect(out).toContain("replay");
 		});
 	});