@os-eco/overstory-cli 0.8.7 → 0.9.2

package/src/commands/group.test.ts

@@ -1,28 +1,34 @@
 /**
  * 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.
+ * Uses real temp directories for groups.json I/O and direct function calls
+ * to createGroup, addToGroup, removeFromGroup, getGroupProgress, printGroupProgress.
+ * Tracker validation uses inline stub objects (no mock.module).
  */
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
+import { GroupError, ValidationError } from "../errors.ts";
 import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
-import type { TaskGroup } from "../types.ts";
-import { loadGroups } from "./group.ts";
+import type { TrackerIssue } from "../tracker/types.ts";
+import type { TaskGroup, TaskGroupProgress } from "../types.ts";
+import {
+	addToGroup,
+	createGroup,
+	getGroupProgress,
+	loadGroups,
+	printGroupProgress,
+	removeFromGroup,
+} 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 () => {
@@ -33,15 +39,8 @@ afterEach(async () => {
  * 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[];
+	const path = join(overstoryDir, "groups.json");
+	await Bun.write(path, `${JSON.stringify(groups, null, "\t")}\n`);
 }
 
 function makeGroup(overrides?: Partial<TaskGroup>): TaskGroup {
@@ -56,6 +55,8 @@ function makeGroup(overrides?: Partial<TaskGroup>): TaskGroup {
 	};
 }
 
+// -- loadGroups --
+
 describe("loadGroups", () => {
 	test("returns empty array when groups.json does not exist", async () => {
 		const groups = await loadGroups(tempDir);
@@ -63,7 +64,8 @@ describe("loadGroups", () => {
 	});
 
 	test("returns empty array when groups.json is malformed", async () => {
-		await Bun.write(groupsJsonPath, "not valid json");
+		const path = join(overstoryDir, "groups.json");
+		await Bun.write(path, "not valid json");
 		const groups = await loadGroups(tempDir);
 		expect(groups).toEqual([]);
 	});
@@ -77,186 +79,303 @@ describe("loadGroups", () => {
 	});
 });
 
-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]);
+// -- createGroup --
+
+describe("createGroup", () => {
+	test("creates a group with valid name and issue IDs", async () => {
+		const group = await createGroup(tempDir, "Feature Batch", ["abc-1", "def-2"], true);
+		expect(group.name).toBe("Feature Batch");
+		expect(group.memberIssueIds).toEqual(["abc-1", "def-2"]);
+		expect(group.status).toBe("active");
+		expect(group.completedAt).toBeNull();
+		expect(group.id).toMatch(/^group-[a-f0-9]{8}$/);
+		expect(group.createdAt).toBeTruthy();
+	});
 
-		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("persists to disk", async () => {
+		await createGroup(tempDir, "Persisted", ["x-1"], true);
+		const loaded = await loadGroups(tempDir);
+		expect(loaded).toHaveLength(1);
+		expect(loaded[0]?.name).toBe("Persisted");
+		expect(loaded[0]?.memberIssueIds).toEqual(["x-1"]);
+	});
+
+	test("throws ValidationError for empty name", async () => {
+		await expect(createGroup(tempDir, "", ["id-1"], true)).rejects.toThrow(ValidationError);
+		await expect(createGroup(tempDir, "   ", ["id-1"], true)).rejects.toThrow(ValidationError);
 	});
 
-	test("group ID has correct format", () => {
-		const id = `group-${crypto.randomUUID().slice(0, 8)}`;
-		expect(id).toMatch(/^group-[a-f0-9]{8}$/);
+	test("throws ValidationError for empty issueIds", async () => {
+		await expect(createGroup(tempDir, "Name", [], true)).rejects.toThrow(ValidationError);
 	});
 
-	test("groups.json has trailing newline", async () => {
-		await writeGroups([makeGroup()]);
-		const raw = await Bun.file(groupsJsonPath).text();
-		expect(raw.endsWith("\n")).toBe(true);
+	test("throws ValidationError for duplicate IDs", async () => {
+		await expect(createGroup(tempDir, "Name", ["a", "b", "a"], true)).rejects.toThrow(
+			ValidationError,
+		);
+	});
+
+	test("appends to existing groups", async () => {
+		await createGroup(tempDir, "First", ["id-1"], true);
+		await createGroup(tempDir, "Second", ["id-2"], true);
+		const loaded = await loadGroups(tempDir);
+		expect(loaded).toHaveLength(2);
+		expect(loaded[0]?.name).toBe("First");
+		expect(loaded[1]?.name).toBe("Second");
 	});
 });
 
-describe("group add (via JSON storage)", () => {
-	test("adds issues to existing group", async () => {
-		const group = makeGroup({ memberIssueIds: ["issue-1"] });
-		await writeGroups([group]);
+// -- addToGroup --
 
-		// 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);
-		}
+describe("addToGroup", () => {
+	test("adds IDs to an existing group", async () => {
+		const created = await createGroup(tempDir, "G", ["a"], true);
+		const updated = await addToGroup(tempDir, created.id, ["b", "c"], true);
+		expect(updated.memberIssueIds).toEqual(["a", "b", "c"]);
+	});
 
-		const updated = await readGroups();
-		expect(updated[0]?.memberIssueIds).toEqual(["issue-1", "issue-2", "issue-3"]);
+	test("throws GroupError when group not found", async () => {
+		await expect(addToGroup(tempDir, "group-missing0", ["x"], true)).rejects.toThrow(GroupError);
 	});
 
-	test("reopens completed group when adding issues", async () => {
-		const group = makeGroup({
-			status: "completed",
-			completedAt: new Date().toISOString(),
-		});
-		await writeGroups([group]);
+	test("throws GroupError for duplicate member", async () => {
+		const created = await createGroup(tempDir, "G", ["a", "b"], true);
+		await expect(addToGroup(tempDir, created.id, ["a"], true)).rejects.toThrow(GroupError);
+	});
 
-		const groups = await readGroups();
+	test("reopens completed group when adding issues", async () => {
+		const created = await createGroup(tempDir, "G", ["a"], true);
+		// Manually mark as completed on disk
+		const groups = await loadGroups(tempDir);
 		const target = groups[0];
-		expect(target).toBeDefined();
-		if (target) {
-			target.memberIssueIds.push("new-issue");
-			target.status = "active";
-			target.completedAt = null;
-			await writeGroups(groups);
-		}
+		if (!target) throw new Error("expected group");
+		target.status = "completed";
+		target.completedAt = new Date().toISOString();
+		await writeGroups(groups);
 
-		const updated = await readGroups();
-		expect(updated[0]?.status).toBe("active");
-		expect(updated[0]?.completedAt).toBeNull();
+		const updated = await addToGroup(tempDir, created.id, ["b"], true);
+		expect(updated.status).toBe("active");
+		expect(updated.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);
+	test("throws ValidationError for empty issueIds", async () => {
+		const created = await createGroup(tempDir, "G", ["a"], true);
+		await expect(addToGroup(tempDir, created.id, [], true)).rejects.toThrow(ValidationError);
 	});
 });
 
-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);
-		}
+// -- removeFromGroup --
 
-		const updated = await readGroups();
-		expect(updated[0]?.memberIssueIds).toEqual(["a", "c"]);
+describe("removeFromGroup", () => {
+	test("removes IDs from a group", async () => {
+		const created = await createGroup(tempDir, "G", ["a", "b", "c"], true);
+		const updated = await removeFromGroup(tempDir, created.id, ["b"]);
+		expect(updated.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("throws GroupError when group not found", async () => {
+		await expect(removeFromGroup(tempDir, "group-missing0", ["x"])).rejects.toThrow(GroupError);
 	});
 
-	test("detects non-member issue", () => {
-		const group = makeGroup({ memberIssueIds: ["a", "b"] });
-		const isNotMember = !group.memberIssueIds.includes("c");
-		expect(isNotMember).toBe(true);
+	test("throws GroupError for non-member issue", async () => {
+		const created = await createGroup(tempDir, "G", ["a", "b"], true);
+		await expect(removeFromGroup(tempDir, created.id, ["z"])).rejects.toThrow(GroupError);
 	});
-});
 
-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]);
+	test("throws GroupError when removal would empty the group", async () => {
+		const created = await createGroup(tempDir, "G", ["only"], true);
+		await expect(removeFromGroup(tempDir, created.id, ["only"])).rejects.toThrow(GroupError);
+	});
 
-		// 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);
-		}
+	test("throws ValidationError for empty issueIds", async () => {
+		const created = await createGroup(tempDir, "G", ["a"], true);
+		await expect(removeFromGroup(tempDir, created.id, [])).rejects.toThrow(ValidationError);
+	});
 
-		const updated = await readGroups();
-		expect(updated[0]?.status).toBe("completed");
-		expect(updated[0]?.completedAt).not.toBeNull();
+	test("persists removal to disk", async () => {
+		const created = await createGroup(tempDir, "G", ["a", "b", "c"], true);
+		await removeFromGroup(tempDir, created.id, ["b"]);
+		const loaded = await loadGroups(tempDir);
+		expect(loaded[0]?.memberIssueIds).toEqual(["a", "c"]);
 	});
+});
 
-	test("does not auto-close when some issues are still open", async () => {
-		const group = makeGroup({ status: "active" });
-		await writeGroups([group]);
+// -- getGroupProgress --
 
-		// No change -- some still open
-		const groups = await readGroups();
-		expect(groups[0]?.status).toBe("active");
+describe("getGroupProgress", () => {
+	test("counts default to open without tracker", async () => {
+		const group = makeGroup({ memberIssueIds: ["x", "y", "z"] });
+		const groups = [group];
+		await writeGroups(groups);
+
+		const progress = await getGroupProgress(tempDir, group, groups);
+		expect(progress.total).toBe(3);
+		expect(progress.open).toBe(3);
+		expect(progress.completed).toBe(0);
+		expect(progress.inProgress).toBe(0);
+		expect(progress.blocked).toBe(0);
 	});
 
-	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");
+	test("auto-closes when all issues are closed (stub tracker)", async () => {
+		const group = makeGroup({ memberIssueIds: ["done-1", "done-2"] });
+		const groups = [group];
+		await writeGroups(groups);
+
+		const stubTracker = {
+			ready: async () => [],
+			show: async (id: string): Promise<TrackerIssue> => ({
+				id,
+				title: id,
+				status: "closed",
+				priority: 3,
+				type: "task",
+			}),
+			create: async () => "",
+			claim: async () => {},
+			close: async () => {},
+			list: async () => [],
+			sync: async () => {},
+		};
+
+		const progress = await getGroupProgress(tempDir, group, groups, stubTracker);
+		expect(progress.completed).toBe(2);
+		expect(progress.total).toBe(2);
+		expect(progress.group.status).toBe("completed");
+		expect(progress.group.completedAt).not.toBeNull();
 	});
-});
 
-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]);
+	test("does not auto-close when some issues are still open", async () => {
+		const group = makeGroup({ memberIssueIds: ["done-1", "open-1"] });
+		const groups = [group];
+		await writeGroups(groups);
 
-		const groups = await readGroups();
-		expect(groups).toHaveLength(2);
-		expect(groups[0]?.name).toBe("Group A");
-		expect(groups[1]?.name).toBe("Group B");
+		const stubTracker = {
+			ready: async () => [],
+			show: async (id: string): Promise<TrackerIssue> => ({
+				id,
+				title: id,
+				status: id.startsWith("done-") ? "closed" : "open",
+				priority: 3,
+				type: "task",
+			}),
+			create: async () => "",
+			claim: async () => {},
+			close: async () => {},
+			list: async () => [],
+			sync: async () => {},
+		};
+
+		const progress = await getGroupProgress(tempDir, group, groups, stubTracker);
+		expect(progress.completed).toBe(1);
+		expect(progress.open).toBe(1);
+		expect(progress.group.status).toBe("active");
 	});
 
-	test("empty list when no groups exist", async () => {
-		const groups = await loadGroups(tempDir);
-		expect(groups).toEqual([]);
+	test("counts in_progress and blocked statuses", async () => {
+		const group = makeGroup({ memberIssueIds: ["ip-1", "bl-1", "cl-1", "op-1"] });
+		const groups = [group];
+		await writeGroups(groups);
+
+		const statusMap: Record<string, string> = {
+			"ip-1": "in_progress",
+			"bl-1": "blocked",
+			"cl-1": "closed",
+			"op-1": "open",
+		};
+
+		const stubTracker = {
+			ready: async () => [],
+			show: async (id: string): Promise<TrackerIssue> => ({
+				id,
+				title: id,
+				status: statusMap[id] ?? "open",
+				priority: 3,
+				type: "task",
+			}),
+			create: async () => "",
+			claim: async () => {},
+			close: async () => {},
+			list: async () => [],
+			sync: async () => {},
+		};
+
+		const progress = await getGroupProgress(tempDir, group, groups, stubTracker);
+		expect(progress.inProgress).toBe(1);
+		expect(progress.blocked).toBe(1);
+		expect(progress.completed).toBe(1);
+		expect(progress.open).toBe(1);
 	});
 });
 
-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();
+// -- printGroupProgress --
+
+describe("printGroupProgress", () => {
+	test("outputs formatted progress for active group", () => {
+		const group = makeGroup({ id: "group-abc12345", name: "My Group" });
+		const progress: TaskGroupProgress = {
+			group,
+			total: 5,
+			completed: 2,
+			inProgress: 1,
+			blocked: 1,
+			open: 1,
+		};
+
+		const chunks: string[] = [];
+		const origWrite = process.stdout.write;
+		process.stdout.write = ((chunk: string) => {
+			chunks.push(chunk);
+			return true;
+		}) as typeof process.stdout.write;
+
+		try {
+			printGroupProgress(progress);
+		} finally {
+			process.stdout.write = origWrite;
+		}
+
+		const output = chunks.join("");
+		expect(output).toContain("My Group");
+		expect(output).toContain("group-abc12345");
+		expect(output).toContain("[active]");
+		expect(output).toContain("5 total");
+		expect(output).toContain("2 completed");
+		expect(output).toContain("1 in_progress");
+		expect(output).toContain("1 blocked");
+		expect(output).toContain("1 open");
 	});
 
-	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);
+	test("outputs completed timestamp for completed group", () => {
+		const group = makeGroup({
+			id: "group-done1234",
+			name: "Done Group",
+			status: "completed",
+			completedAt: "2026-01-15T10:00:00.000Z",
+		});
+		const progress: TaskGroupProgress = {
+			group,
+			total: 2,
+			completed: 2,
+			inProgress: 0,
+			blocked: 0,
+			open: 0,
+		};
+
+		const chunks: string[] = [];
+		const origWrite = process.stdout.write;
+		process.stdout.write = ((chunk: string) => {
+			chunks.push(chunk);
+			return true;
+		}) as typeof process.stdout.write;
+
+		try {
+			printGroupProgress(progress);
+		} finally {
+			process.stdout.write = origWrite;
+		}
+
+		const output = chunks.join("");
+		expect(output).toContain("[completed]");
+		expect(output).toContain("2026-01-15T10:00:00.000Z");
 	});
 });

package/src/commands/group.ts

@@ -25,6 +25,7 @@ function groupsPath(projectRoot: string): string {
 
 /**
  * Load groups from .overstory/groups.json.
+ * @internal Exported for testing.
  */
 export async function loadGroups(projectRoot: string): Promise<TaskGroup[]> {
 	const path = groupsPath(projectRoot);
@@ -80,8 +81,9 @@ function generateGroupId(): string {
 
 /**
  * Create a new task group.
+ * @internal Exported for testing.
  */
-async function createGroup(
+export async function createGroup(
 	projectRoot: string,
 	name: string,
 	issueIds: string[],
@@ -124,8 +126,9 @@ async function createGroup(
 
 /**
  * Add issues to an existing group.
+ * @internal Exported for testing.
  */
-async function addToGroup(
+export async function addToGroup(
 	projectRoot: string,
 	groupId: string,
 	issueIds: string[],
@@ -172,8 +175,9 @@ async function addToGroup(
 
 /**
  * Remove issues from an existing group.
+ * @internal Exported for testing.
  */
-async function removeFromGroup(
+export async function removeFromGroup(
 	projectRoot: string,
 	groupId: string,
 	issueIds: string[],
@@ -211,8 +215,9 @@ async function removeFromGroup(
 /**
  * Get progress for a single group. Queries the tracker for member issue statuses.
  * Auto-closes the group if all members are closed.
+ * @internal Exported for testing.
  */
-async function getGroupProgress(
+export async function getGroupProgress(
 	projectRoot: string,
 	group: TaskGroup,
 	groups: TaskGroup[],
@@ -284,8 +289,9 @@ async function getGroupProgress(
 
 /**
  * Print a group's progress in human-readable format.
+ * @internal Exported for testing.
  */
-function printGroupProgress(progress: TaskGroupProgress): void {
+export function printGroupProgress(progress: TaskGroupProgress): void {
 	const w = process.stdout.write.bind(process.stdout);
 	const { group, total, completed, inProgress, blocked, open } = progress;
 	const status = group.status === "completed" ? "[completed]" : "[active]";

package/src/commands/init.test.ts

@@ -27,6 +27,7 @@ const AGENT_DEF_FILES = [
 	"coordinator.md",
 	"monitor.md",
 	"orchestrator.md",
+	"ov-co-creation.md",
 ];
 
 /** Resolve the source agents directory (same logic as init.ts). */
@@ -53,7 +54,7 @@ describe("initCommand: agent-defs deployment", () => {
 		await cleanupTempDir(tempDir);
 	});
 
-	test("creates .overstory/agent-defs/ with all 8 agent definition files (supervisor deprecated)", async () => {
+	test("creates .overstory/agent-defs/ with all 9 agent definition files (supervisor deprecated)", async () => {
 		await initCommand({ _spawner: noopSpawner });
 
 		const agentDefsDir = join(tempDir, ".overstory", "agent-defs");

package/src/commands/init.ts

@@ -396,6 +396,14 @@ export function buildAgentManifest(): AgentManifest {
 			canSpawn: true,
 			constraints: ["read-only", "no-worktree"],
 		},
+		orchestrator: {
+			file: "orchestrator.md",
+			model: "opus",
+			tools: ["Read", "Glob", "Grep", "Bash"],
+			capabilities: ["orchestrate", "coordinate", "dispatch", "escalate"],
+			canSpawn: true,
+			constraints: ["read-only", "no-worktree"],
+		},
 		monitor: {
 			file: "monitor.md",
 			model: "sonnet",

package/src/commands/log.test.ts

@@ -399,6 +399,41 @@ describe("logCommand", () => {
 		expect(updatedSession?.state).toBe("working");
 	});
 
+	test("session-end does NOT transition orchestrator to completed (persistent agent)", async () => {
+		const dbPath = join(tempDir, ".overstory", "sessions.db");
+		const session: AgentSession = {
+			id: "session-orch",
+			agentName: "orchestrator",
+			capability: "orchestrator",
+			worktreePath: tempDir,
+			branchName: "main",
+			taskId: "",
+			tmuxSession: "overstory-orchestrator",
+			state: "working",
+			pid: 33333,
+			parentAgent: null,
+			depth: 0,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date(Date.now() - 60_000).toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		};
+		const store = createSessionStore(dbPath);
+		store.upsert(session);
+		store.close();
+
+		await logCommand(["session-end", "--agent", "orchestrator"]);
+
+		const readStore = createSessionStore(dbPath);
+		const updatedSession = readStore.getByName("orchestrator");
+		readStore.close();
+
+		expect(updatedSession).toBeDefined();
+		expect(updatedSession?.state).toBe("working");
+	});
+
 	describe("session-end coordinator run completion", () => {
 		test("session-end does NOT auto-complete the active run for coordinator agent (per-turn Stop hook guard)", async () => {
 			// Regression test for overstory-adc5: