@os-eco/overstory-cli 0.6.1

package/src/doctor/merge-queue.test.ts

@@ -0,0 +1,216 @@
+import { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createMergeQueue } from "../merge/queue.ts";
+import type { OverstoryConfig } from "../types.ts";
+import { checkMergeQueue } from "./merge-queue.ts";
+import type { DoctorCheck } from "./types.ts";
+
+describe("checkMergeQueue", () => {
+	let tempDir: string;
+	let mockConfig: OverstoryConfig;
+
+	beforeEach(() => {
+		tempDir = mkdtempSync(join(tmpdir(), "overstory-test-"));
+		mockConfig = {
+			project: { name: "test", root: tempDir, canonicalBranch: "main" },
+			agents: {
+				manifestPath: "",
+				baseDir: "",
+				maxConcurrent: 5,
+				staggerDelayMs: 100,
+				maxDepth: 2,
+				maxSessionsPerRun: 0,
+			},
+			worktrees: { baseDir: "" },
+			taskTracker: { backend: "auto", enabled: true },
+			mulch: { enabled: true, domains: [], primeFormat: "markdown" },
+			merge: { aiResolveEnabled: false, reimagineEnabled: false },
+			providers: {
+				anthropic: { type: "native" },
+			},
+			watchdog: {
+				tier0Enabled: true,
+				tier0IntervalMs: 30000,
+				tier1Enabled: false,
+				tier2Enabled: false,
+				staleThresholdMs: 300000,
+				zombieThresholdMs: 600000,
+				nudgeIntervalMs: 60000,
+			},
+			models: {},
+			logging: { verbose: false, redactSecrets: true },
+		};
+	});
+
+	afterEach(() => {
+		rmSync(tempDir, { recursive: true, force: true });
+	});
+
+	test("passes when merge queue db does not exist", () => {
+		const checks = checkMergeQueue(mockConfig, tempDir) as DoctorCheck[];
+
+		expect(checks).toHaveLength(1);
+		expect(checks[0]?.status).toBe("pass");
+		expect(checks[0]?.name).toBe("merge-queue.db exists");
+		expect(checks[0]?.message).toContain("normal for new installations");
+	});
+
+	test("passes when merge queue is empty", () => {
+		const dbPath = join(tempDir, "merge-queue.db");
+		// Create empty queue
+		const queue = createMergeQueue(dbPath);
+		queue.close();
+
+		const checks = checkMergeQueue(mockConfig, tempDir) as DoctorCheck[];
+
+		expect(checks).toHaveLength(1);
+		expect(checks[0]?.status).toBe("pass");
+		expect(checks[0]?.name).toBe("merge-queue.db schema");
+		expect(checks[0]?.message).toBe("Merge queue has 0 entries");
+	});
+
+	test("passes with valid queue entries", () => {
+		const dbPath = join(tempDir, "merge-queue.db");
+		const queue = createMergeQueue(dbPath);
+		queue.enqueue({
+			branchName: "feature/test",
+			beadId: "beads-abc",
+			agentName: "test-agent",
+			filesModified: ["src/test.ts"],
+		});
+		queue.enqueue({
+			branchName: "feature/another",
+			beadId: "beads-def",
+			agentName: "another-agent",
+			filesModified: ["src/another.ts"],
+		});
+		// Mark second entry as merged
+		const entry = queue.list()[1];
+		if (entry) {
+			queue.updateStatus(entry.branchName, "merged", "clean-merge");
+		}
+		queue.close();
+
+		const checks = checkMergeQueue(mockConfig, tempDir) as DoctorCheck[];
+
+		expect(checks).toHaveLength(1);
+		expect(checks[0]?.status).toBe("pass");
+		expect(checks[0]?.name).toBe("merge-queue.db schema");
+		expect(checks[0]?.message).toBe("Merge queue has 2 entries");
+	});
+
+	test("fails when db is corrupted", () => {
+		const dbPath = join(tempDir, "merge-queue.db");
+		// Write invalid data to db file
+		const fs = require("node:fs");
+		fs.writeFileSync(dbPath, "not a valid sqlite database");
+
+		const checks = checkMergeQueue(mockConfig, tempDir) as DoctorCheck[];
+
+		expect(checks).toHaveLength(1);
+		expect(checks[0]?.status).toBe("fail");
+		expect(checks[0]?.name).toBe("merge-queue.db readable");
+		expect(checks[0]?.message).toContain("Failed to read merge-queue.db");
+	});
+
+	test("fails when table does not exist", () => {
+		const dbPath = join(tempDir, "merge-queue.db");
+		// Create a db but without the merge_queue table
+		const db = new Database(dbPath);
+		db.exec("CREATE TABLE other_table (id INTEGER PRIMARY KEY)");
+		db.close();
+
+		const checks = checkMergeQueue(mockConfig, tempDir) as DoctorCheck[];
+
+		const schemaCheck = checks.find((c) => c?.name === "merge-queue.db schema");
+		expect(schemaCheck?.status).toBe("fail");
+		expect(schemaCheck?.message).toContain("merge_queue table not found");
+	});
+
+	test("warns about stale pending entries", () => {
+		const dbPath = join(tempDir, "merge-queue.db");
+		// Create queue and manually insert stale entry (2 days old)
+		const queue = createMergeQueue(dbPath);
+		queue.close();
+
+		const staleDate = new Date();
+		staleDate.setDate(staleDate.getDate() - 2); // 2 days ago
+
+		const db = new Database(dbPath);
+		db.prepare(
+			"INSERT INTO merge_queue (branch_name, task_id, agent_name, files_modified, status, enqueued_at) VALUES (?, ?, ?, ?, ?, ?)",
+		).run(
+			"feature/stale",
+			"beads-abc",
+			"test-agent",
+			JSON.stringify(["src/test.ts"]),
+			"pending",
+			staleDate.toISOString(),
+		);
+		db.close();
+
+		const checks = checkMergeQueue(mockConfig, tempDir) as DoctorCheck[];
+
+		const staleCheck = checks.find((c) => c?.name === "merge-queue.db staleness");
+		expect(staleCheck?.status).toBe("warn");
+		expect(staleCheck?.message).toContain("potentially stale");
+		expect(staleCheck?.details?.[0]).toContain("feature/stale");
+	});
+
+	test("does not warn about old completed entries", () => {
+		const dbPath = join(tempDir, "merge-queue.db");
+		// Create queue and manually insert old merged entry (2 days ago)
+		const queue = createMergeQueue(dbPath);
+		queue.close();
+
+		const oldDate = new Date();
+		oldDate.setDate(oldDate.getDate() - 2); // 2 days ago
+
+		const db = new Database(dbPath);
+		db.prepare(
+			"INSERT INTO merge_queue (branch_name, task_id, agent_name, files_modified, status, enqueued_at, resolved_tier) VALUES (?, ?, ?, ?, ?, ?, ?)",
+		).run(
+			"feature/old-merged",
+			"beads-abc",
+			"test-agent",
+			JSON.stringify(["src/test.ts"]),
+			"merged",
+			oldDate.toISOString(),
+			"clean-merge",
+		);
+		db.close();
+
+		const checks = checkMergeQueue(mockConfig, tempDir) as DoctorCheck[];
+
+		const staleCheck = checks.find((c) => c?.name === "merge-queue.db staleness");
+		expect(staleCheck).toBeUndefined();
+	});
+
+	test("warns about duplicate branches", () => {
+		const dbPath = join(tempDir, "merge-queue.db");
+		const queue = createMergeQueue(dbPath);
+		queue.enqueue({
+			branchName: "feature/duplicate",
+			beadId: "beads-abc",
+			agentName: "test-agent",
+			filesModified: ["src/test.ts"],
+		});
+		queue.enqueue({
+			branchName: "feature/duplicate",
+			beadId: "beads-def",
+			agentName: "another-agent",
+			filesModified: ["src/another.ts"],
+		});
+		queue.close();
+
+		const checks = checkMergeQueue(mockConfig, tempDir) as DoctorCheck[];
+
+		const duplicateCheck = checks.find((c) => c?.name === "merge-queue.db duplicates");
+		expect(duplicateCheck?.status).toBe("warn");
+		expect(duplicateCheck?.message).toContain("duplicate branch entries");
+		expect(duplicateCheck?.details?.[0]).toContain("feature/duplicate");
+	});
+});

package/src/doctor/merge-queue.ts

@@ -0,0 +1,144 @@
+import { Database } from "bun:sqlite";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
+
+/**
+ * Merge queue health checks.
+ * Validates merge-queue.db schema and detects stale entries.
+ */
+export const checkMergeQueue: DoctorCheckFn = (_config, overstoryDir): DoctorCheck[] => {
+	const checks: DoctorCheck[] = [];
+	const dbPath = join(overstoryDir, "merge-queue.db");
+
+	if (!existsSync(dbPath)) {
+		checks.push({
+			name: "merge-queue.db exists",
+			category: "merge",
+			status: "pass",
+			message: "No merge queue database (normal for new installations or no merges yet)",
+		});
+		return checks;
+	}
+
+	let db: Database;
+	try {
+		db = new Database(dbPath, { readonly: true });
+	} catch (err) {
+		checks.push({
+			name: "merge-queue.db readable",
+			category: "merge",
+			status: "fail",
+			message: "Failed to open merge-queue.db",
+			details: [err instanceof Error ? err.message : String(err)],
+			fixable: true,
+		});
+		return checks;
+	}
+
+	try {
+		// Check table exists
+		let tableCheck: unknown;
+		try {
+			tableCheck = db
+				.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='merge_queue'")
+				.get();
+		} catch (err) {
+			// Database is corrupted or not a valid SQLite file
+			checks.push({
+				name: "merge-queue.db readable",
+				category: "merge",
+				status: "fail",
+				message: "Failed to read merge-queue.db",
+				details: [err instanceof Error ? err.message : String(err)],
+				fixable: true,
+			});
+			db.close();
+			return checks;
+		}
+
+		if (!tableCheck) {
+			checks.push({
+				name: "merge-queue.db schema",
+				category: "merge",
+				status: "fail",
+				message: "merge_queue table not found in database",
+				fixable: true,
+			});
+			db.close();
+			return checks;
+		}
+
+		// Read all entries
+		const rows = db.prepare("SELECT * FROM merge_queue ORDER BY id ASC").all() as Array<{
+			branch_name: string;
+			agent_name: string;
+			status: string;
+			enqueued_at: string;
+			resolved_tier: string | null;
+		}>;
+
+		checks.push({
+			name: "merge-queue.db schema",
+			category: "merge",
+			status: "pass",
+			message: `Merge queue has ${rows.length} entries`,
+		});
+
+		// Check for stale entries (pending/merging older than 24h)
+		const now = new Date();
+		const staleThresholdMs = 24 * 60 * 60 * 1000;
+		const staleEntries: string[] = [];
+		for (const row of rows) {
+			if (row.status === "pending" || row.status === "merging") {
+				try {
+					const enqueuedAt = new Date(row.enqueued_at);
+					const ageMs = now.getTime() - enqueuedAt.getTime();
+					if (ageMs > staleThresholdMs) {
+						const ageHours = Math.floor(ageMs / (60 * 60 * 1000));
+						staleEntries.push(
+							`${row.branch_name} (${row.status}, ${ageHours}h old) - may be stuck`,
+						);
+					}
+				} catch {
+					/* invalid date */
+				}
+			}
+		}
+
+		if (staleEntries.length > 0) {
+			checks.push({
+				name: "merge-queue.db staleness",
+				category: "merge",
+				status: "warn",
+				message: `Found ${staleEntries.length} potentially stale queue entries`,
+				details: staleEntries,
+				fixable: true,
+			});
+		}
+
+		// Check for duplicate branches
+		const branchCounts = new Map<string, number>();
+		for (const row of rows) {
+			branchCounts.set(row.branch_name, (branchCounts.get(row.branch_name) ?? 0) + 1);
+		}
+		const duplicates: string[] = [];
+		for (const [branch, count] of branchCounts) {
+			if (count > 1) duplicates.push(`${branch} (appears ${count} times)`);
+		}
+		if (duplicates.length > 0) {
+			checks.push({
+				name: "merge-queue.db duplicates",
+				category: "merge",
+				status: "warn",
+				message: "Found duplicate branch entries in queue",
+				details: duplicates,
+				fixable: true,
+			});
+		}
+	} finally {
+		db.close();
+	}
+
+	return checks;
+};

package/src/doctor/structure.test.ts

@@ -0,0 +1,291 @@
+/**
+ * Tests for structure doctor checks.
+ *
+ * Uses temp directories with real filesystem operations.
+ * No mocks needed -- all operations are cheap and local.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { OverstoryConfig } from "../types.ts";
+import { checkStructure } from "./structure.ts";
+
+describe("checkStructure", () => {
+	let tempDir: string;
+	let overstoryDir: string;
+	let mockConfig: OverstoryConfig;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "structure-test-"));
+		overstoryDir = join(tempDir, ".overstory");
+
+		mockConfig = {
+			project: {
+				name: "test-project",
+				root: tempDir,
+				canonicalBranch: "main",
+			},
+			agents: {
+				manifestPath: ".overstory/agent-manifest.json",
+				baseDir: ".overstory/agent-defs",
+				maxConcurrent: 5,
+				staggerDelayMs: 1000,
+				maxDepth: 2,
+				maxSessionsPerRun: 0,
+			},
+			worktrees: {
+				baseDir: ".overstory/worktrees",
+			},
+			taskTracker: {
+				backend: "auto",
+				enabled: true,
+			},
+			mulch: {
+				enabled: true,
+				domains: [],
+				primeFormat: "markdown",
+			},
+			merge: {
+				aiResolveEnabled: false,
+				reimagineEnabled: false,
+			},
+			providers: {
+				anthropic: { type: "native" },
+			},
+			watchdog: {
+				tier0Enabled: true,
+				tier0IntervalMs: 30000,
+				tier1Enabled: false,
+				tier2Enabled: false,
+				staleThresholdMs: 300000,
+				zombieThresholdMs: 600000,
+				nudgeIntervalMs: 60000,
+			},
+			models: {},
+			logging: {
+				verbose: false,
+				redactSecrets: true,
+			},
+		};
+	});
+
+	afterEach(async () => {
+		await rm(tempDir, { recursive: true, force: true });
+	});
+
+	test("fails when .overstory/ directory does not exist", async () => {
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		expect(checks.length).toBeGreaterThan(0);
+		const dirCheck = checks.find((c) => c.name === ".overstory/ directory");
+		expect(dirCheck).toBeDefined();
+		expect(dirCheck?.status).toBe("fail");
+		expect(dirCheck?.message).toContain("missing");
+		expect(dirCheck?.fixable).toBe(true);
+	});
+
+	test("passes when all required files and directories exist", async () => {
+		// Create .overstory/ and all required structure
+		await mkdir(overstoryDir, { recursive: true });
+		await mkdir(join(overstoryDir, "agent-defs"), { recursive: true });
+		await mkdir(join(overstoryDir, "agents"), { recursive: true });
+		await mkdir(join(overstoryDir, "worktrees"), { recursive: true });
+		await mkdir(join(overstoryDir, "specs"), { recursive: true });
+		await mkdir(join(overstoryDir, "logs"), { recursive: true });
+
+		await Bun.write(join(overstoryDir, "config.yaml"), "project:\n  name: test\n");
+		await Bun.write(
+			join(overstoryDir, "agent-manifest.json"),
+			JSON.stringify({ version: "1.0", agents: {}, capabilityIndex: {} }, null, 2),
+		);
+		await Bun.write(join(overstoryDir, "hooks.json"), "{}");
+		await Bun.write(
+			join(overstoryDir, ".gitignore"),
+			`# Wildcard+whitelist: ignore everything, whitelist tracked files
+# Auto-healed by overstory prime on each session start
+*
+!.gitignore
+!config.yaml
+!agent-manifest.json
+!hooks.json
+!groups.json
+!agent-defs/
+`,
+		);
+
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		// All checks should pass
+		const failedChecks = checks.filter((c) => c.status === "fail");
+		expect(failedChecks).toHaveLength(0);
+
+		const dirCheck = checks.find((c) => c.name === ".overstory/ directory");
+		expect(dirCheck?.status).toBe("pass");
+
+		const filesCheck = checks.find((c) => c.name === "Required files");
+		expect(filesCheck?.status).toBe("pass");
+
+		const dirsCheck = checks.find((c) => c.name === "Required subdirectories");
+		expect(dirsCheck?.status).toBe("pass");
+
+		const gitignoreCheck = checks.find((c) => c.name === ".gitignore entries");
+		expect(gitignoreCheck?.status).toBe("pass");
+	});
+
+	test("reports missing required files", async () => {
+		await mkdir(overstoryDir, { recursive: true });
+		await Bun.write(join(overstoryDir, "config.yaml"), "project:\n  name: test\n");
+		// Missing: agent-manifest.json, hooks.json, .gitignore
+
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		const filesCheck = checks.find((c) => c.name === "Required files");
+		expect(filesCheck).toBeDefined();
+		expect(filesCheck?.status).toBe("fail");
+		expect(filesCheck?.details).toContain("agent-manifest.json");
+		expect(filesCheck?.details).toContain("hooks.json");
+		expect(filesCheck?.details).toContain(".gitignore");
+		expect(filesCheck?.fixable).toBe(true);
+	});
+
+	test("reports missing required subdirectories", async () => {
+		await mkdir(overstoryDir, { recursive: true });
+		await mkdir(join(overstoryDir, "agent-defs"), { recursive: true });
+		// Missing: agents/, worktrees/, specs/, logs/
+
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		const dirsCheck = checks.find((c) => c.name === "Required subdirectories");
+		expect(dirsCheck).toBeDefined();
+		expect(dirsCheck?.status).toBe("fail");
+		expect(dirsCheck?.details).toContain("agents/");
+		expect(dirsCheck?.details).toContain("worktrees/");
+		expect(dirsCheck?.details).toContain("specs/");
+		expect(dirsCheck?.details).toContain("logs/");
+		expect(dirsCheck?.fixable).toBe(true);
+	});
+
+	test("warns when .gitignore is missing entries", async () => {
+		await mkdir(overstoryDir, { recursive: true });
+		await Bun.write(
+			join(overstoryDir, ".gitignore"),
+			`# Incomplete gitignore
+*
+!.gitignore
+!config.yaml
+`,
+		);
+
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		const gitignoreCheck = checks.find((c) => c.name === ".gitignore entries");
+		expect(gitignoreCheck).toBeDefined();
+		expect(gitignoreCheck?.status).toBe("warn");
+		expect(gitignoreCheck?.details).toBeDefined();
+		expect(gitignoreCheck?.details?.length).toBeGreaterThan(0);
+		expect(gitignoreCheck?.fixable).toBe(true);
+	});
+
+	test("validates agent-defs files against manifest", async () => {
+		await mkdir(overstoryDir, { recursive: true });
+		await mkdir(join(overstoryDir, "agent-defs"), { recursive: true });
+
+		const manifest = {
+			version: "1.0",
+			agents: {
+				scout: { file: "scout.md", model: "haiku", tools: [], capabilities: [], canSpawn: false },
+				builder: {
+					file: "builder.md",
+					model: "sonnet",
+					tools: [],
+					capabilities: [],
+					canSpawn: false,
+				},
+			},
+			capabilityIndex: {},
+		};
+
+		await Bun.write(join(overstoryDir, "agent-manifest.json"), JSON.stringify(manifest, null, 2));
+		await Bun.write(join(overstoryDir, "agent-defs", "scout.md"), "# Scout");
+		// Missing: builder.md
+
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		const agentDefsCheck = checks.find((c) => c.name === "Agent definition files");
+		expect(agentDefsCheck).toBeDefined();
+		expect(agentDefsCheck?.status).toBe("fail");
+		expect(agentDefsCheck?.details).toContain("builder.md");
+		expect(agentDefsCheck?.fixable).toBe(true);
+	});
+
+	test("passes when all agent-defs files are present", async () => {
+		await mkdir(overstoryDir, { recursive: true });
+		await mkdir(join(overstoryDir, "agent-defs"), { recursive: true });
+
+		const manifest = {
+			version: "1.0",
+			agents: {
+				scout: { file: "scout.md", model: "haiku", tools: [], capabilities: [], canSpawn: false },
+				builder: {
+					file: "builder.md",
+					model: "sonnet",
+					tools: [],
+					capabilities: [],
+					canSpawn: false,
+				},
+			},
+			capabilityIndex: {},
+		};
+
+		await Bun.write(join(overstoryDir, "agent-manifest.json"), JSON.stringify(manifest, null, 2));
+		await Bun.write(join(overstoryDir, "agent-defs", "scout.md"), "# Scout");
+		await Bun.write(join(overstoryDir, "agent-defs", "builder.md"), "# Builder");
+
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		const agentDefsCheck = checks.find((c) => c.name === "Agent definition files");
+		expect(agentDefsCheck).toBeDefined();
+		expect(agentDefsCheck?.status).toBe("pass");
+	});
+
+	test("fails gracefully when manifest is malformed", async () => {
+		await mkdir(overstoryDir, { recursive: true });
+		await Bun.write(join(overstoryDir, "agent-manifest.json"), "invalid json{");
+
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		const agentDefsCheck = checks.find((c) => c.name === "Agent definition files");
+		expect(agentDefsCheck).toBeDefined();
+		expect(agentDefsCheck?.status).toBe("fail");
+		expect(agentDefsCheck?.message).toContain("Cannot validate");
+		expect(agentDefsCheck?.fixable).toBe(false);
+	});
+
+	test("detects leftover temp files", async () => {
+		await mkdir(overstoryDir, { recursive: true });
+		await Bun.write(join(overstoryDir, "config.yaml.tmp"), "temp");
+		await Bun.write(join(overstoryDir, "old-file.bak"), "backup");
+
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		const tempFilesCheck = checks.find((c) => c.name === "Leftover temp files");
+		expect(tempFilesCheck).toBeDefined();
+		expect(tempFilesCheck?.status).toBe("warn");
+		expect(tempFilesCheck?.details).toContain("config.yaml.tmp");
+		expect(tempFilesCheck?.details).toContain("old-file.bak");
+		expect(tempFilesCheck?.fixable).toBe(true);
+	});
+
+	test("passes when no temp files exist", async () => {
+		await mkdir(overstoryDir, { recursive: true });
+		await Bun.write(join(overstoryDir, "config.yaml"), "project:\n  name: test\n");
+
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		const tempFilesCheck = checks.find((c) => c.name === "Leftover temp files");
+		expect(tempFilesCheck).toBeDefined();
+		expect(tempFilesCheck?.status).toBe("pass");
+	});
+});