@os-eco/overstory-cli 0.6.1

package/src/commands/feed.ts

@@ -0,0 +1,361 @@
+/**
+ * CLI command: overstory feed [--follow] [--agent <name>...] [--run <id>]
+ *              [--since <ts>] [--limit <n>] [--interval <ms>] [--json]
+ *
+ * Unified real-time event stream across all agents — like `tail -f` for the fleet.
+ * Shows chronological events from all agents merged into a single feed.
+ */
+
+import { join } from "node:path";
+import { loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { createEventStore } from "../events/store.ts";
+import { color } from "../logging/color.ts";
+import type { EventType, StoredEvent } from "../types.ts";
+
+/** Compact 5-char labels for feed output. */
+const EVENT_LABELS: Record<EventType, { label: string; color: string }> = {
+	tool_start: { label: "TOOL+", color: color.blue },
+	tool_end: { label: "TOOL-", color: color.blue },
+	session_start: { label: "SESS+", color: color.green },
+	session_end: { label: "SESS-", color: color.yellow },
+	mail_sent: { label: "MAIL>", color: color.cyan },
+	mail_received: { label: "MAIL<", color: color.cyan },
+	spawn: { label: "SPAWN", color: color.magenta },
+	error: { label: "ERROR", color: color.red },
+	custom: { label: "CUSTM", color: color.gray },
+};
+
+/** Colors assigned to agents in order of first appearance. */
+const AGENT_COLORS = [color.blue, color.green, color.yellow, color.cyan, color.magenta] as const;
+
+/**
+ * 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];
+}
+
+/**
+ * Parse all occurrences of a named flag from args.
+ * Returns an array of values (e.g., --agent a --agent b => ["a", "b"]).
+ */
+function getAllFlags(args: string[], flag: string): string[] {
+	const values: string[] = [];
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === flag && i + 1 < args.length) {
+			const value = args[i + 1];
+			if (value !== undefined) {
+				values.push(value);
+			}
+			i++; // skip the value
+		}
+	}
+	return values;
+}
+
+function hasFlag(args: string[], flag: string): boolean {
+	return args.includes(flag);
+}
+
+/**
+ * Format an absolute time from an ISO timestamp.
+ * Returns "HH:MM:SS" portion.
+ */
+function formatAbsoluteTime(timestamp: string): string {
+	const match = /T(\d{2}:\d{2}:\d{2})/.exec(timestamp);
+	if (match?.[1]) {
+		return match[1];
+	}
+	return timestamp;
+}
+
+/**
+ * Build a detail string for a feed event based on its type and fields.
+ */
+function buildEventDetail(event: StoredEvent): string {
+	const parts: string[] = [];
+
+	if (event.toolName) {
+		parts.push(`tool=${event.toolName}`);
+	}
+
+	if (event.toolDurationMs !== null) {
+		parts.push(`${event.toolDurationMs}ms`);
+	}
+
+	if (event.data) {
+		try {
+			const parsed: unknown = JSON.parse(event.data);
+			if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+				const data = parsed as Record<string, unknown>;
+				for (const [key, value] of Object.entries(data)) {
+					if (value !== null && value !== undefined) {
+						const strValue = typeof value === "string" ? value : JSON.stringify(value);
+						// Truncate long values
+						const truncated = strValue.length > 60 ? `${strValue.slice(0, 57)}...` : strValue;
+						parts.push(`${key}=${truncated}`);
+					}
+				}
+			}
+		} catch {
+			// data is not valid JSON; show it raw if short enough
+			if (event.data.length <= 60) {
+				parts.push(event.data);
+			}
+		}
+	}
+
+	return parts.join(" ");
+}
+
+/**
+ * Assign a stable color to each agent based on order of first appearance.
+ */
+function buildAgentColorMap(events: StoredEvent[]): Map<string, string> {
+	const colorMap = new Map<string, string>();
+	for (const event of events) {
+		if (!colorMap.has(event.agentName)) {
+			const colorIndex = colorMap.size % AGENT_COLORS.length;
+			const agentColor = AGENT_COLORS[colorIndex];
+			if (agentColor !== undefined) {
+				colorMap.set(event.agentName, agentColor);
+			}
+		}
+	}
+	return colorMap;
+}
+
+/**
+ * Print a single event in compact feed format:
+ * HH:MM:SS LABEL agentname    detail
+ */
+function printEvent(event: StoredEvent, colorMap: Map<string, string>): void {
+	const w = process.stdout.write.bind(process.stdout);
+
+	const timeStr = formatAbsoluteTime(event.createdAt);
+
+	const eventInfo = EVENT_LABELS[event.eventType] ?? {
+		label: event.eventType.padEnd(5),
+		color: color.gray,
+	};
+
+	const levelColor =
+		event.level === "error" ? color.red : event.level === "warn" ? color.yellow : "";
+	const levelReset = levelColor ? color.reset : "";
+
+	const detail = buildEventDetail(event);
+	const detailSuffix = detail ? ` ${color.dim}${detail}${color.reset}` : "";
+
+	const agentColor = colorMap.get(event.agentName) ?? color.gray;
+	const agentLabel = ` ${agentColor}${event.agentName.padEnd(15)}${color.reset}`;
+
+	w(
+		`${color.dim}${timeStr}${color.reset} ` +
+			`${levelColor}${eventInfo.color}${color.bold}${eventInfo.label}${color.reset}${levelReset}` +
+			`${agentLabel}${detailSuffix}\n`,
+	);
+}
+
+const FEED_HELP = `overstory feed -- Unified real-time event stream across all agents
+
+Usage: overstory feed [options]
+
+Options:
+  --follow, -f         Continuously poll for new events (like tail -f)
+  --interval <ms>      Polling interval for --follow (default: 1000, min: 200)
+  --agent <name>       Filter by agent name (can appear multiple times)
+  --run <id>           Filter events by run ID
+  --since <timestamp>  Start time (ISO 8601, default: 5 minutes ago)
+  --limit <n>          Max initial events to show (default: 50)
+  --json               Output events as JSON (one per line in follow mode)
+  --help, -h           Show this help`;
+
+/**
+ * Entry point for `overstory feed [--follow] [--agent <name>...] [--run <id>] [--json]`.
+ */
+export async function feedCommand(args: string[]): Promise<void> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(`${FEED_HELP}\n`);
+		return;
+	}
+
+	const json = hasFlag(args, "--json");
+	const follow = hasFlag(args, "--follow") || hasFlag(args, "-f");
+	const runId = getFlag(args, "--run");
+	const agentNames = getAllFlags(args, "--agent");
+	const sinceStr = getFlag(args, "--since");
+	const limitStr = getFlag(args, "--limit");
+	const limit = limitStr ? Number.parseInt(limitStr, 10) : 50;
+
+	const intervalStr = getFlag(args, "--interval");
+	const interval = intervalStr ? Number.parseInt(intervalStr, 10) : 1000;
+
+	if (Number.isNaN(limit) || limit < 1) {
+		throw new ValidationError("--limit must be a positive integer", {
+			field: "limit",
+			value: limitStr,
+		});
+	}
+
+	if (Number.isNaN(interval) || interval < 200) {
+		throw new ValidationError("--interval must be a number >= 200 (milliseconds)", {
+			field: "interval",
+			value: intervalStr,
+		});
+	}
+
+	// Validate timestamp if provided
+	if (sinceStr !== undefined && Number.isNaN(new Date(sinceStr).getTime())) {
+		throw new ValidationError("--since must be a valid ISO 8601 timestamp", {
+			field: "since",
+			value: sinceStr,
+		});
+	}
+
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const overstoryDir = join(config.project.root, ".overstory");
+
+	// Open event store
+	const eventsDbPath = join(overstoryDir, "events.db");
+	const eventsFile = Bun.file(eventsDbPath);
+	if (!(await eventsFile.exists())) {
+		if (json) {
+			process.stdout.write("[]\n");
+		} else {
+			process.stdout.write("No events data yet.\n");
+		}
+		return;
+	}
+
+	const eventStore = createEventStore(eventsDbPath);
+
+	try {
+		// Default since: 5 minutes ago
+		const since = sinceStr ?? new Date(Date.now() - 5 * 60 * 1000).toISOString();
+
+		// Helper to query events based on filters
+		const queryEvents = (queryOpts: { since: string; limit: number }): StoredEvent[] => {
+			if (runId) {
+				return eventStore.getByRun(runId, queryOpts);
+			}
+			if (agentNames.length > 0) {
+				const allEvents: StoredEvent[] = [];
+				for (const name of agentNames) {
+					const agentEvents = eventStore.getByAgent(name, {
+						since: queryOpts.since,
+					});
+					allEvents.push(...agentEvents);
+				}
+				// Sort by createdAt chronologically
+				allEvents.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+				// Apply limit after merge
+				return allEvents.slice(0, queryOpts.limit);
+			}
+			return eventStore.getTimeline(queryOpts);
+		};
+
+		if (!follow) {
+			// Non-follow mode: single snapshot
+			const events = queryEvents({ since, limit });
+
+			if (json) {
+				process.stdout.write(`${JSON.stringify(events)}\n`);
+				return;
+			}
+
+			if (events.length === 0) {
+				process.stdout.write("No events found.\n");
+				return;
+			}
+
+			const colorMap = buildAgentColorMap(events);
+			for (const event of events) {
+				printEvent(event, colorMap);
+			}
+			return;
+		}
+
+		// Follow mode: continuous polling
+		// Print initial events
+		let lastSeenId = 0;
+		const initialEvents = queryEvents({ since, limit });
+
+		if (!json) {
+			const colorMap = buildAgentColorMap(initialEvents);
+			for (const event of initialEvents) {
+				printEvent(event, colorMap);
+			}
+			if (initialEvents.length > 0) {
+				const lastEvent = initialEvents[initialEvents.length - 1];
+				if (lastEvent) {
+					lastSeenId = lastEvent.id;
+				}
+			}
+		} else {
+			// JSON mode: print each event as a line
+			for (const event of initialEvents) {
+				process.stdout.write(`${JSON.stringify(event)}\n`);
+			}
+			if (initialEvents.length > 0) {
+				const lastEvent = initialEvents[initialEvents.length - 1];
+				if (lastEvent) {
+					lastSeenId = lastEvent.id;
+				}
+			}
+		}
+
+		// Maintain a color map across polling iterations (for non-JSON mode)
+		const globalColorMap = buildAgentColorMap(initialEvents);
+
+		// Poll for new events
+		while (true) {
+			await Bun.sleep(interval);
+
+			// Query events from 60s ago, then filter client-side for id > lastSeenId
+			const pollSince = new Date(Date.now() - 60 * 1000).toISOString();
+			const recentEvents = queryEvents({ since: pollSince, limit: 1000 });
+
+			// Filter to new events only
+			const newEvents = recentEvents.filter((e) => e.id > lastSeenId);
+
+			if (newEvents.length > 0) {
+				if (!json) {
+					// Update color map for any new agents
+					for (const event of newEvents) {
+						if (!globalColorMap.has(event.agentName)) {
+							const colorIndex = globalColorMap.size % AGENT_COLORS.length;
+							const agentColor = AGENT_COLORS[colorIndex];
+							if (agentColor !== undefined) {
+								globalColorMap.set(event.agentName, agentColor);
+							}
+						}
+					}
+
+					// Print new events
+					for (const event of newEvents) {
+						printEvent(event, globalColorMap);
+					}
+				} else {
+					// JSON mode: print each event as a line
+					for (const event of newEvents) {
+						process.stdout.write(`${JSON.stringify(event)}\n`);
+					}
+				}
+
+				// Update lastSeenId
+				const lastNew = newEvents[newEvents.length - 1];
+				if (lastNew) {
+					lastSeenId = lastNew.id;
+				}
+			}
+		}
+	} finally {
+		eventStore.close();
+	}
+}

package/src/commands/group.test.ts

@@ -0,0 +1,262 @@
+/**
+ * Tests for overstory group command.
+ *
+ * Uses real temp directories for groups.json I/O. Does NOT mock bd CLI --
+ * tests focus on the JSON storage layer and validation logic.
+ * The beads validation is tested with --skip-validation flag since
+ * bd is an external CLI not available in unit tests.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
+import type { TaskGroup } from "../types.ts";
+import { loadGroups } from "./group.ts";
+
+let tempDir: string;
+let overstoryDir: string;
+let groupsJsonPath: string;
+
+beforeEach(async () => {
+	tempDir = await createTempGitRepo();
+	overstoryDir = join(tempDir, ".overstory");
+	await mkdir(overstoryDir, { recursive: true });
+	groupsJsonPath = join(overstoryDir, "groups.json");
+});
+
+afterEach(async () => {
+	await cleanupTempDir(tempDir);
+});
+
+/**
+ * Helper to write groups.json directly for test setup.
+ */
+async function writeGroups(groups: TaskGroup[]): Promise<void> {
+	await Bun.write(groupsJsonPath, `${JSON.stringify(groups, null, "\t")}\n`);
+}
+
+/**
+ * Helper to read groups.json directly for assertions.
+ */
+async function readGroups(): Promise<TaskGroup[]> {
+	const text = await Bun.file(groupsJsonPath).text();
+	return JSON.parse(text) as TaskGroup[];
+}
+
+function makeGroup(overrides?: Partial<TaskGroup>): TaskGroup {
+	return {
+		id: `group-${crypto.randomUUID().slice(0, 8)}`,
+		name: "Test Group",
+		memberIssueIds: ["issue-1", "issue-2"],
+		status: "active",
+		createdAt: new Date().toISOString(),
+		completedAt: null,
+		...overrides,
+	};
+}
+
+describe("loadGroups", () => {
+	test("returns empty array when groups.json does not exist", async () => {
+		const groups = await loadGroups(tempDir);
+		expect(groups).toEqual([]);
+	});
+
+	test("returns empty array when groups.json is malformed", async () => {
+		await Bun.write(groupsJsonPath, "not valid json");
+		const groups = await loadGroups(tempDir);
+		expect(groups).toEqual([]);
+	});
+
+	test("loads groups from valid groups.json", async () => {
+		const group = makeGroup({ name: "My Group" });
+		await writeGroups([group]);
+		const groups = await loadGroups(tempDir);
+		expect(groups).toHaveLength(1);
+		expect(groups[0]?.name).toBe("My Group");
+	});
+});
+
+describe("group create (via JSON storage)", () => {
+	test("creates a group with correct structure", async () => {
+		const group = makeGroup({
+			name: "Feature Batch",
+			memberIssueIds: ["abc-123", "def-456"],
+		});
+		await writeGroups([group]);
+
+		const groups = await readGroups();
+		expect(groups).toHaveLength(1);
+		const saved = groups[0];
+		expect(saved?.name).toBe("Feature Batch");
+		expect(saved?.memberIssueIds).toEqual(["abc-123", "def-456"]);
+		expect(saved?.status).toBe("active");
+		expect(saved?.completedAt).toBeNull();
+		expect(saved?.id).toMatch(/^group-[a-f0-9]{8}$/);
+	});
+
+	test("group ID has correct format", () => {
+		const id = `group-${crypto.randomUUID().slice(0, 8)}`;
+		expect(id).toMatch(/^group-[a-f0-9]{8}$/);
+	});
+
+	test("groups.json has trailing newline", async () => {
+		await writeGroups([makeGroup()]);
+		const raw = await Bun.file(groupsJsonPath).text();
+		expect(raw.endsWith("\n")).toBe(true);
+	});
+});
+
+describe("group add (via JSON storage)", () => {
+	test("adds issues to existing group", async () => {
+		const group = makeGroup({ memberIssueIds: ["issue-1"] });
+		await writeGroups([group]);
+
+		// Simulate add
+		const groups = await readGroups();
+		const target = groups[0];
+		expect(target).toBeDefined();
+		if (target) {
+			target.memberIssueIds.push("issue-2", "issue-3");
+			await writeGroups(groups);
+		}
+
+		const updated = await readGroups();
+		expect(updated[0]?.memberIssueIds).toEqual(["issue-1", "issue-2", "issue-3"]);
+	});
+
+	test("reopens completed group when adding issues", async () => {
+		const group = makeGroup({
+			status: "completed",
+			completedAt: new Date().toISOString(),
+		});
+		await writeGroups([group]);
+
+		const groups = await readGroups();
+		const target = groups[0];
+		expect(target).toBeDefined();
+		if (target) {
+			target.memberIssueIds.push("new-issue");
+			target.status = "active";
+			target.completedAt = null;
+			await writeGroups(groups);
+		}
+
+		const updated = await readGroups();
+		expect(updated[0]?.status).toBe("active");
+		expect(updated[0]?.completedAt).toBeNull();
+	});
+
+	test("detects duplicate members", () => {
+		const group = makeGroup({ memberIssueIds: ["issue-1", "issue-2"] });
+		const isDuplicate = group.memberIssueIds.includes("issue-1");
+		expect(isDuplicate).toBe(true);
+	});
+});
+
+describe("group remove (via JSON storage)", () => {
+	test("removes issues from group", async () => {
+		const group = makeGroup({ memberIssueIds: ["a", "b", "c"] });
+		await writeGroups([group]);
+
+		const groups = await readGroups();
+		const target = groups[0];
+		expect(target).toBeDefined();
+		if (target) {
+			target.memberIssueIds = target.memberIssueIds.filter((id) => id !== "b");
+			await writeGroups(groups);
+		}
+
+		const updated = await readGroups();
+		expect(updated[0]?.memberIssueIds).toEqual(["a", "c"]);
+	});
+
+	test("cannot remove all issues (would leave empty group)", () => {
+		const group = makeGroup({ memberIssueIds: ["only-one"] });
+		const toRemove = ["only-one"];
+		const remaining = group.memberIssueIds.filter((id) => !toRemove.includes(id));
+		expect(remaining.length).toBe(0);
+		// The command should throw GroupError in this case
+	});
+
+	test("detects non-member issue", () => {
+		const group = makeGroup({ memberIssueIds: ["a", "b"] });
+		const isNotMember = !group.memberIssueIds.includes("c");
+		expect(isNotMember).toBe(true);
+	});
+});
+
+describe("auto-close logic", () => {
+	test("marks group completed when all issues are closed", async () => {
+		const group = makeGroup({
+			status: "active",
+			memberIssueIds: ["done-1", "done-2"],
+		});
+		await writeGroups([group]);
+
+		// Simulate auto-close: all completed
+		const groups = await readGroups();
+		const target = groups[0];
+		expect(target).toBeDefined();
+		if (target && target.status === "active") {
+			// All issues closed -> auto-close
+			target.status = "completed";
+			target.completedAt = new Date().toISOString();
+			await writeGroups(groups);
+		}
+
+		const updated = await readGroups();
+		expect(updated[0]?.status).toBe("completed");
+		expect(updated[0]?.completedAt).not.toBeNull();
+	});
+
+	test("does not auto-close when some issues are still open", async () => {
+		const group = makeGroup({ status: "active" });
+		await writeGroups([group]);
+
+		// No change -- some still open
+		const groups = await readGroups();
+		expect(groups[0]?.status).toBe("active");
+	});
+
+	test("does not auto-close already-completed group", () => {
+		const group = makeGroup({ status: "completed", completedAt: "2025-01-01T00:00:00Z" });
+		// Already completed, should not re-trigger
+		expect(group.status).toBe("completed");
+		expect(group.completedAt).toBe("2025-01-01T00:00:00Z");
+	});
+});
+
+describe("group list (via JSON storage)", () => {
+	test("lists all groups", async () => {
+		const g1 = makeGroup({ name: "Group A" });
+		const g2 = makeGroup({ name: "Group B", status: "completed" });
+		await writeGroups([g1, g2]);
+
+		const groups = await readGroups();
+		expect(groups).toHaveLength(2);
+		expect(groups[0]?.name).toBe("Group A");
+		expect(groups[1]?.name).toBe("Group B");
+	});
+
+	test("empty list when no groups exist", async () => {
+		const groups = await loadGroups(tempDir);
+		expect(groups).toEqual([]);
+	});
+});
+
+describe("error cases", () => {
+	test("group not found by ID", async () => {
+		await writeGroups([makeGroup()]);
+		const groups = await readGroups();
+		const found = groups.find((g) => g.id === "group-nonexist");
+		expect(found).toBeUndefined();
+	});
+
+	test("multiple groups can be stored", async () => {
+		const groups = [makeGroup({ name: "A" }), makeGroup({ name: "B" }), makeGroup({ name: "C" })];
+		await writeGroups(groups);
+		const loaded = await readGroups();
+		expect(loaded).toHaveLength(3);
+	});
+});