@os-eco/overstory-cli 0.6.1 → 0.6.5

package/src/commands/log.test.ts

@@ -88,7 +88,7 @@ describe("logCommand", () => {
 		await logCommand(["--help"]);
 		const out = output();
 
-		expect(out).toContain("overstory log");
+		expect(out).toContain("log");
 		expect(out).toContain("tool-start");
 		expect(out).toContain("tool-end");
 		expect(out).toContain("session-end");
@@ -99,23 +99,18 @@ describe("logCommand", () => {
 		await logCommand(["-h"]);
 		const out = output();
 
-		expect(out).toContain("overstory log");
+		expect(out).toContain("log");
 		expect(out).toContain("tool-start");
 		expect(out).toContain("tool-end");
 		expect(out).toContain("session-end");
 		expect(out).toContain("--agent");
 	});
 
-	test("missing event with only flags throws ValidationError", async () => {
-		// The code finds first non-flag arg. Passing only flags should trigger "Event is required"
-		// Note: the implementation checks for undefined event
+	test("missing event argument throws when required argument missing", async () => {
+		// Commander throws when a required positional argument is missing
 		await expect(async () => {
 			await logCommand([]);
-		}).toThrow(ValidationError);
-
-		await expect(async () => {
-			await logCommand([]);
-		}).toThrow("Event is required");
+		}).toThrow();
 	});
 
 	test("invalid event name throws ValidationError", async () => {
@@ -223,7 +218,7 @@ describe("logCommand", () => {
 			capability: "builder",
 			worktreePath: "/tmp/test",
 			branchName: "test-branch",
-			beadId: "bead-001",
+			taskId: "bead-001",
 			tmuxSession: "test-tmux",
 			state: "working",
 			pid: 12345,
@@ -278,7 +273,7 @@ describe("logCommand", () => {
 			capability: "scout",
 			worktreePath: "/tmp/metrics",
 			branchName: "metrics-branch",
-			beadId: "bead-002",
+			taskId: "bead-002",
 			tmuxSession: "metrics-tmux",
 			state: "working",
 			pid: 54321,
@@ -304,7 +299,7 @@ describe("logCommand", () => {
 
 		expect(metrics).toHaveLength(1);
 		expect(metrics[0]?.agentName).toBe("metrics-agent");
-		expect(metrics[0]?.beadId).toBe("bead-002");
+		expect(metrics[0]?.taskId).toBe("bead-002");
 		expect(metrics[0]?.capability).toBe("scout");
 		expect(metrics[0]?.parentAgent).toBe("parent-agent");
 	});
@@ -318,7 +313,7 @@ describe("logCommand", () => {
 			capability: "coordinator",
 			worktreePath: tempDir,
 			branchName: "main",
-			beadId: "",
+			taskId: "",
 			tmuxSession: "overstory-coordinator",
 			state: "working",
 			pid: 11111,
@@ -357,7 +352,7 @@ describe("logCommand", () => {
 			capability: "monitor",
 			worktreePath: tempDir,
 			branchName: "main",
-			beadId: "",
+			taskId: "",
 			tmuxSession: "overstory-monitor",
 			state: "working",
 			pid: 22222,
@@ -394,7 +389,7 @@ describe("logCommand", () => {
 				capability: "coordinator",
 				worktreePath: tempDir,
 				branchName: "main",
-				beadId: "",
+				taskId: "",
 				tmuxSession: "overstory-coordinator",
 				state: "working",
 				pid: 11111,
@@ -451,7 +446,7 @@ describe("logCommand", () => {
 				capability: "coordinator",
 				worktreePath: tempDir,
 				branchName: "main",
-				beadId: "",
+				taskId: "",
 				tmuxSession: "overstory-coordinator-no-run",
 				state: "working",
 				pid: 11112,
@@ -481,7 +476,7 @@ describe("logCommand", () => {
 				capability: "builder",
 				worktreePath: tempDir,
 				branchName: "builder-branch",
-				beadId: "bead-builder-001",
+				taskId: "bead-builder-001",
 				tmuxSession: "overstory-builder",
 				state: "working",
 				pid: 11113,
@@ -535,7 +530,7 @@ describe("logCommand", () => {
 				capability: "coordinator",
 				worktreePath: tempDir,
 				branchName: "main",
-				beadId: "",
+				taskId: "",
 				tmuxSession: "overstory-coordinator-completed",
 				state: "working",
 				pid: 11114,
@@ -588,7 +583,7 @@ describe("logCommand", () => {
 			capability: "lead",
 			worktreePath: tempDir,
 			branchName: "lead-alpha-branch",
-			beadId: "bead-lead-001",
+			taskId: "bead-lead-001",
 			tmuxSession: "overstory-lead-alpha",
 			state: "working",
 			pid: 33333,
@@ -628,7 +623,7 @@ describe("logCommand", () => {
 			capability: "builder",
 			worktreePath: tempDir,
 			branchName: "builder-beta-branch",
-			beadId: "bead-builder-001",
+			taskId: "bead-builder-001",
 			tmuxSession: "overstory-builder-beta",
 			state: "working",
 			pid: 44444,
@@ -670,7 +665,7 @@ describe("logCommand", () => {
 			capability: "builder",
 			worktreePath: "/tmp/activity",
 			branchName: "activity-branch",
-			beadId: "bead-003",
+			taskId: "bead-003",
 			tmuxSession: "activity-tmux",
 			state: "working",
 			pid: 99999,
@@ -709,7 +704,7 @@ describe("logCommand", () => {
 			capability: "builder",
 			worktreePath: "/tmp/booting",
 			branchName: "booting-branch",
-			beadId: "bead-004",
+			taskId: "bead-004",
 			tmuxSession: "booting-tmux",
 			state: "booting",
 			pid: 11111,
@@ -794,7 +789,7 @@ describe("logCommand", () => {
 			capability: "builder",
 			worktreePath: tempDir,
 			branchName: "mulch-fail-branch",
-			beadId: "bead-mulch-001",
+			taskId: "bead-mulch-001",
 			tmuxSession: "overstory-mulch-fail",
 			state: "working",
 			pid: 55555,
@@ -833,7 +828,7 @@ describe("logCommand", () => {
 			capability: "coordinator",
 			worktreePath: tempDir,
 			branchName: "main",
-			beadId: "",
+			taskId: "",
 			tmuxSession: "overstory-coordinator-mulch",
 			state: "working",
 			pid: 66666,
@@ -880,7 +875,7 @@ describe("logCommand", () => {
 			mulchClient: client,
 			agentName: "test-builder",
 			capability: "builder",
-			beadId: "bead-123",
+			taskId: "bead-123",
 			mailDbPath,
 			parentAgent: "parent-lead",
 			projectRoot: tempDir,
@@ -913,7 +908,7 @@ describe("logCommand", () => {
 			mulchClient: client,
 			agentName: "test-builder",
 			capability: "builder",
-			beadId: "bead-456",
+			taskId: "bead-456",
 			mailDbPath,
 			parentAgent: "parent-lead",
 			projectRoot: tempDir,
@@ -945,7 +940,7 @@ describe("logCommand", () => {
 			mulchClient: client,
 			agentName: "test-builder",
 			capability: "builder",
-			beadId: null,
+			taskId: null,
 			mailDbPath,
 			parentAgent: null,
 			projectRoot: tempDir,
@@ -973,7 +968,7 @@ describe("logCommand", () => {
 			mulchClient: client,
 			agentName: "test-builder",
 			capability: "builder",
-			beadId: null,
+			taskId: null,
 			mailDbPath,
 			parentAgent: null,
 			projectRoot: tempDir,
@@ -1052,7 +1047,7 @@ describe("logCommand", () => {
 			mulchClient: client,
 			agentName: "insight-agent",
 			capability: "builder",
-			beadId: "bead-insight",
+			taskId: "bead-insight",
 			mailDbPath,
 			parentAgent: "parent-agent",
 			projectRoot: tempDir,
@@ -1132,7 +1127,7 @@ describe("logCommand", () => {
 			mulchClient: client,
 			agentName: "mail-insight-agent",
 			capability: "scout",
-			beadId: "bead-mail",
+			taskId: "bead-mail",
 			mailDbPath,
 			parentAgent: "parent-agent",
 			projectRoot: tempDir,

package/src/commands/log.ts

@@ -11,6 +11,7 @@
  */
 
 import { join } from "node:path";
+import { Command } from "commander";
 import { updateIdentity } from "../agents/identity.ts";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
@@ -27,17 +28,6 @@ import { openSessionStore } from "../sessions/compat.ts";
 import { createRunStore } from "../sessions/store.ts";
 import type { AgentSession } from "../types.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];
-}
-
 /**
  * Get or create a session timestamp directory for the agent.
  * Uses a file-based marker to track the current session directory.
@@ -237,7 +227,7 @@ export async function autoRecordExpertise(params: {
 	mulchClient: MulchClient;
 	agentName: string;
 	capability: string;
-	beadId: string | null;
+	taskId: string | null;
 	mailDbPath: string;
 	parentAgent: string | null;
 	projectRoot: string;
@@ -257,7 +247,7 @@ export async function autoRecordExpertise(params: {
 				type: "reference",
 				description: `${params.capability} agent ${params.agentName} completed work in this domain. Files: ${filesList}`,
 				tags: ["auto-session-end", params.capability],
-				evidenceBead: params.beadId ?? undefined,
+				evidenceBead: params.taskId ?? undefined,
 			});
 			recordedDomains.push(domain);
 		} catch {
@@ -296,7 +286,7 @@ export async function autoRecordExpertise(params: {
 					type: insight.type,
 					description: insight.description,
 					tags: insight.tags,
-					evidenceBead: params.beadId ?? undefined,
+					evidenceBead: params.taskId ?? undefined,
 				});
 				if (!recordedDomains.includes(insight.domain)) {
 					recordedDomains.push(insight.domain);
@@ -342,63 +332,32 @@ export async function autoRecordExpertise(params: {
 }
 
 /**
- * Entry point for `overstory log <event> --agent <name>`.
+ * Core implementation for the log command.
  */
-const LOG_HELP = `overstory log — Log a hook event
-
-Usage: overstory log <event> --agent <name> [--stdin]
-
-Arguments:
-  <event>            Event type: tool-start, tool-end, session-end
-
-Options:
-  --agent <name>            Agent name (required)
-  --tool-name <name>        Tool name (for tool-start/tool-end events, legacy)
-  --transcript <path>       Path to Claude Code transcript JSONL (for session-end, legacy)
-  --stdin                   Read hook payload JSON from stdin (preferred)
-  --help, -h                Show this help`;
-
-export async function logCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${LOG_HELP}\n`);
-		return;
-	}
-
-	const event = args.find((a) => !a.startsWith("--"));
-	const agentName = getFlag(args, "--agent");
-	const useStdin = args.includes("--stdin");
-	const toolNameFlag = getFlag(args, "--tool-name") ?? "unknown";
-	const transcriptPathFlag = getFlag(args, "--transcript");
-
-	if (!event) {
-		throw new ValidationError("Event is required: overstory log <event> --agent <name>", {
-			field: "event",
-		});
-	}
-
+async function runLog(opts: {
+	event: string;
+	agent: string;
+	toolName: string;
+	transcript: string | undefined;
+	stdin: boolean;
+}): Promise<void> {
 	const validEvents = ["tool-start", "tool-end", "session-end"];
-	if (!validEvents.includes(event)) {
-		throw new ValidationError(`Invalid event "${event}". Valid: ${validEvents.join(", ")}`, {
+	if (!validEvents.includes(opts.event)) {
+		throw new ValidationError(`Invalid event "${opts.event}". Valid: ${validEvents.join(", ")}`, {
 			field: "event",
-			value: event,
-		});
-	}
-
-	if (!agentName) {
-		throw new ValidationError("--agent is required for log command", {
-			field: "agent",
+			value: opts.event,
 		});
 	}
 
 	// Read stdin payload if --stdin flag is set
 	let stdinPayload: Record<string, unknown> | null = null;
-	if (useStdin) {
+	if (opts.stdin) {
 		stdinPayload = await readStdinJson();
 	}
 
 	// Extract fields from stdin payload (preferred) or fall back to flags
 	const toolName =
-		typeof stdinPayload?.tool_name === "string" ? stdinPayload.tool_name : toolNameFlag;
+		typeof stdinPayload?.tool_name === "string" ? stdinPayload.tool_name : opts.toolName;
 	const toolInput =
 		stdinPayload?.tool_input !== undefined &&
 		stdinPayload?.tool_input !== null &&
@@ -409,28 +368,28 @@ export async function logCommand(args: string[]): Promise<void> {
 	const transcriptPath =
 		typeof stdinPayload?.transcript_path === "string"
 			? stdinPayload.transcript_path
-			: transcriptPathFlag;
+			: opts.transcript;
 
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
 	const logsBase = join(config.project.root, ".overstory", "logs");
-	const sessionDir = await getSessionDir(logsBase, agentName);
+	const sessionDir = await getSessionDir(logsBase, opts.agent);
 
 	const logger = createLogger({
 		logDir: sessionDir,
-		agentName,
+		agentName: opts.agent,
 		verbose: config.logging.verbose,
 		redactSecrets: config.logging.redactSecrets,
 	});
 
-	switch (event) {
+	switch (opts.event) {
 		case "tool-start": {
 			// Backward compatibility: always write to per-agent log files
 			logger.toolStart(toolName, toolInput ?? {});
-			updateLastActivity(config.project.root, agentName);
+			updateLastActivity(config.project.root, opts.agent);
 
 			// When --stdin is used, also write to EventStore for structured observability
-			if (useStdin) {
+			if (opts.stdin) {
 				try {
 					const eventsDbPath = join(config.project.root, ".overstory", "events.db");
 					const eventStore = createEventStore(eventsDbPath);
@@ -439,7 +398,7 @@ export async function logCommand(args: string[]): Promise<void> {
 						: { args: {}, summary: toolName };
 					eventStore.insert({
 						runId: null,
-						agentName,
+						agentName: opts.agent,
 						sessionId,
 						eventType: "tool_start",
 						toolName,
@@ -458,10 +417,10 @@ export async function logCommand(args: string[]): Promise<void> {
 		case "tool-end": {
 			// Backward compatibility: always write to per-agent log files
 			logger.toolEnd(toolName, 0);
-			updateLastActivity(config.project.root, agentName);
+			updateLastActivity(config.project.root, opts.agent);
 
 			// When --stdin is used, write to EventStore and correlate with tool-start
-			if (useStdin) {
+			if (opts.stdin) {
 				try {
 					const eventsDbPath = join(config.project.root, ".overstory", "events.db");
 					const eventStore = createEventStore(eventsDbPath);
@@ -470,7 +429,7 @@ export async function logCommand(args: string[]): Promise<void> {
 						: { args: {}, summary: toolName };
 					eventStore.insert({
 						runId: null,
-						agentName,
+						agentName: opts.agent,
 						sessionId,
 						eventType: "tool_end",
 						toolName,
@@ -479,7 +438,7 @@ export async function logCommand(args: string[]): Promise<void> {
 						level: "info",
 						data: JSON.stringify({ summary: filtered.summary }),
 					});
-					const correlation = eventStore.correlateToolEnd(agentName, toolName);
+					const correlation = eventStore.correlateToolEnd(opts.agent, toolName);
 					if (correlation) {
 						logger.toolEnd(toolName, correlation.durationMs);
 					}
@@ -492,7 +451,7 @@ export async function logCommand(args: string[]): Promise<void> {
 				if (sessionId) {
 					try {
 						// Throttle check
-						const snapshotMarkerPath = join(logsBase, agentName, ".last-snapshot");
+						const snapshotMarkerPath = join(logsBase, opts.agent, ".last-snapshot");
 						const SNAPSHOT_INTERVAL_MS = 30_000;
 						const snapshotMarkerFile = Bun.file(snapshotMarkerPath);
 						let shouldSnapshot = true;
@@ -505,19 +464,19 @@ export async function logCommand(args: string[]): Promise<void> {
 						}
 
 						if (shouldSnapshot) {
-							const transcriptPath = await resolveTranscriptPath(
+							const resolvedTranscriptPath = await resolveTranscriptPath(
 								config.project.root,
 								sessionId,
 								logsBase,
-								agentName,
+								opts.agent,
 							);
-							if (transcriptPath) {
-								const usage = await parseTranscriptUsage(transcriptPath);
+							if (resolvedTranscriptPath) {
+								const usage = await parseTranscriptUsage(resolvedTranscriptPath);
 								const cost = estimateCost(usage);
 								const metricsDbPath = join(config.project.root, ".overstory", "metrics.db");
 								const metricsStore = createMetricsStore(metricsDbPath);
 								metricsStore.recordSnapshot({
-									agentName,
+									agentName: opts.agent,
 									inputTokens: usage.inputTokens,
 									outputTokens: usage.outputTokens,
 									cacheReadTokens: usage.cacheReadTokens,
@@ -538,20 +497,20 @@ export async function logCommand(args: string[]): Promise<void> {
 			break;
 		}
 		case "session-end":
-			logger.info("session.end", { agentName });
+			logger.info("session.end", { agentName: opts.agent });
 			// Transition agent state to completed
-			transitionToCompleted(config.project.root, agentName);
+			transitionToCompleted(config.project.root, opts.agent);
 			// Look up agent session for identity update and metrics recording
 			{
-				const agentSession = getAgentSession(config.project.root, agentName);
-				const beadId = agentSession?.beadId ?? null;
+				const agentSession = getAgentSession(config.project.root, opts.agent);
+				const taskId = agentSession?.taskId ?? null;
 
 				// Update agent identity with completed session
 				const identityBaseDir = join(config.project.root, ".overstory", "agents");
 				try {
-					await updateIdentity(identityBaseDir, agentName, {
+					await updateIdentity(identityBaseDir, opts.agent, {
 						sessionsCompleted: 1,
-						completedTask: beadId ? { beadId, summary: `Completed task ${beadId}` } : undefined,
+						completedTask: taskId ? { taskId, summary: `Completed task ${taskId}` } : undefined,
 					});
 				} catch {
 					// Non-fatal: identity may not exist for this agent
@@ -567,10 +526,10 @@ export async function logCommand(args: string[]): Promise<void> {
 						await mkdir(nudgesDir, { recursive: true });
 						const markerPath = join(nudgesDir, "coordinator.json");
 						const marker = {
-							from: agentName,
+							from: opts.agent,
 							reason: "lead_completed",
-							subject: `Lead ${agentName} completed — check mail for merge_ready/worker_done`,
-							messageId: `auto-nudge-${agentName}-${Date.now()}`,
+							subject: `Lead ${opts.agent} completed — check mail for merge_ready/worker_done`,
+							messageId: `auto-nudge-${opts.agent}-${Date.now()}`,
 							createdAt: new Date().toISOString(),
 						};
 						await Bun.write(markerPath, `${JSON.stringify(marker, null, "\t")}\n`);
@@ -641,8 +600,8 @@ export async function logCommand(args: string[]): Promise<void> {
 						}
 
 						metricsStore.recordSession({
-							agentName,
-							beadId: agentSession.beadId,
+							agentName: opts.agent,
+							taskId: agentSession.taskId,
 							capability: agentSession.capability,
 							startedAt: agentSession.startedAt,
 							completedAt: now,
@@ -671,9 +630,9 @@ export async function logCommand(args: string[]): Promise<void> {
 							const mailDbPath = join(config.project.root, ".overstory", "mail.db");
 							await autoRecordExpertise({
 								mulchClient,
-								agentName,
+								agentName: opts.agent,
 								capability: agentSession.capability,
-								beadId,
+								taskId,
 								mailDbPath,
 								parentAgent: agentSession.parentAgent,
 								projectRoot: config.project.root,
@@ -686,13 +645,13 @@ export async function logCommand(args: string[]): Promise<void> {
 				}
 
 				// Write session-end event to EventStore when --stdin is used
-				if (useStdin) {
+				if (opts.stdin) {
 					try {
 						const eventsDbPath = join(config.project.root, ".overstory", "events.db");
 						const eventStore = createEventStore(eventsDbPath);
 						eventStore.insert({
 							runId: null,
-							agentName,
+							agentName: opts.agent,
 							sessionId,
 							eventType: "session_end",
 							toolName: null,
@@ -709,7 +668,7 @@ export async function logCommand(args: string[]): Promise<void> {
 			}
 			// Clear the current session marker
 			{
-				const markerPath = join(logsBase, agentName, ".current-session");
+				const markerPath = join(logsBase, opts.agent, ".current-session");
 				try {
 					const { unlink } = await import("node:fs/promises");
 					await unlink(markerPath);
@@ -722,3 +681,50 @@ export async function logCommand(args: string[]): Promise<void> {
 
 	logger.close();
 }
+
+export function createLogCommand(): Command {
+	return new Command("log")
+		.description("Log a hook event")
+		.argument("<event>", "Event type: tool-start, tool-end, session-end")
+		.option("--agent <name>", "Agent name (required)")
+		.option("--tool-name <name>", "Tool name (for tool-start/tool-end events, legacy)")
+		.option("--transcript <path>", "Path to Claude Code transcript JSONL (for session-end, legacy)")
+		.option("--stdin", "Read hook payload JSON from stdin (preferred)")
+		.action(
+			async (
+				event: string,
+				opts: { agent?: string; toolName?: string; transcript?: string; stdin?: boolean },
+			) => {
+				if (!opts.agent) {
+					throw new ValidationError("--agent is required for log command", { field: "agent" });
+				}
+				await runLog({
+					event,
+					agent: opts.agent,
+					toolName: opts.toolName ?? "unknown",
+					transcript: opts.transcript,
+					stdin: opts.stdin ?? false,
+				});
+			},
+		);
+}
+
+/**
+ * Entry point for `overstory log <event> --agent <name>`.
+ */
+export async function logCommand(args: string[]): Promise<void> {
+	const cmd = createLogCommand();
+	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/logs.test.ts

@@ -95,7 +95,7 @@ describe("logsCommand", () => {
 			await logsCommand(["--help"]);
 		});
 
-		expect(output).toContain("overstory logs");
+		expect(output).toContain("logs");
 		expect(output).toContain("--agent");
 		expect(output).toContain("--level");
 		expect(output).toContain("--since");