@os-eco/overstory-cli 0.6.1

package/src/doctor/databases.ts

@@ -0,0 +1,218 @@
+import { Database } from "bun:sqlite";
+import { join } from "node:path";
+import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
+
+/**
+ * Database integrity checks.
+ * Validates SQLite databases (mail.db, metrics.db, sessions.db) exist and have correct schema.
+ */
+export const checkDatabases: DoctorCheckFn = (_config, overstoryDir): DoctorCheck[] => {
+	const checks: DoctorCheck[] = [];
+
+	// Define expected databases and their required tables
+	const databases = [
+		{
+			name: "mail.db",
+			tables: ["messages"],
+			requiredColumns: {
+				messages: [
+					"id",
+					"from_agent",
+					"to_agent",
+					"subject",
+					"body",
+					"type",
+					"priority",
+					"thread_id",
+					"payload",
+					"read",
+					"created_at",
+				],
+			},
+		},
+		{
+			name: "metrics.db",
+			tables: ["sessions"],
+			requiredColumns: {
+				sessions: [
+					"agent_name",
+					"task_id",
+					"capability",
+					"started_at",
+					"completed_at",
+					"duration_ms",
+					"exit_code",
+					"merge_result",
+					"parent_agent",
+					"input_tokens",
+					"output_tokens",
+					"cache_read_tokens",
+					"cache_creation_tokens",
+					"estimated_cost_usd",
+					"model_used",
+				],
+			},
+		},
+		{
+			name: "sessions.db",
+			tables: ["sessions", "runs"],
+			requiredColumns: {
+				sessions: [
+					"id",
+					"agent_name",
+					"capability",
+					"worktree_path",
+					"branch_name",
+					"task_id",
+					"tmux_session",
+					"state",
+					"pid",
+					"parent_agent",
+					"depth",
+					"run_id",
+					"started_at",
+					"last_activity",
+					"escalation_level",
+					"stalled_since",
+				],
+				runs: [
+					"id",
+					"started_at",
+					"completed_at",
+					"agent_count",
+					"coordinator_session_id",
+					"status",
+				],
+			},
+		},
+	];
+
+	for (const dbSpec of databases) {
+		const dbPath = join(overstoryDir, dbSpec.name);
+
+		// Check if database file exists
+		if (!existsSync(dbPath)) {
+			checks.push({
+				name: `${dbSpec.name} exists`,
+				category: "databases",
+				status: "fail",
+				message: `Database file ${dbSpec.name} does not exist`,
+				details: [`Expected at: ${dbPath}`],
+			});
+			continue;
+		}
+
+		// Try to open the database
+		let db: Database | null = null;
+		try {
+			db = new Database(dbPath);
+
+			// Check WAL mode is enabled
+			const journalMode = db.prepare<{ journal_mode: string }, []>("PRAGMA journal_mode").get();
+			const walEnabled = journalMode?.journal_mode?.toLowerCase() === "wal";
+
+			// Check for required tables
+			const missingTables: string[] = [];
+			const schemaIssues: string[] = [];
+
+			for (const tableName of dbSpec.tables) {
+				const tableExists = db
+					.prepare<{ count: number }, [string]>(
+						"SELECT COUNT(*) as count FROM sqlite_master WHERE type='table' AND name=?",
+					)
+					.get(tableName);
+
+				if (!tableExists || tableExists.count === 0) {
+					missingTables.push(tableName);
+					continue;
+				}
+
+				// Check columns if table exists
+				const requiredCols =
+					dbSpec.requiredColumns[tableName as keyof typeof dbSpec.requiredColumns];
+				if (requiredCols) {
+					const columns = db.prepare<{ name: string }, []>(`PRAGMA table_info(${tableName})`).all();
+					const existingCols = new Set(columns.map((c) => c.name));
+
+					for (const reqCol of requiredCols) {
+						if (!existingCols.has(reqCol)) {
+							schemaIssues.push(`Table ${tableName} missing column: ${reqCol}`);
+						}
+					}
+				}
+			}
+
+			// Determine check status
+			if (missingTables.length > 0 || schemaIssues.length > 0) {
+				const details: string[] = [];
+				if (missingTables.length > 0) {
+					details.push(`Missing tables: ${missingTables.join(", ")}`);
+				}
+				if (schemaIssues.length > 0) {
+					details.push(...schemaIssues);
+				}
+				if (!walEnabled) {
+					details.push("WAL mode not enabled");
+				}
+
+				checks.push({
+					name: `${dbSpec.name} schema`,
+					category: "databases",
+					status: "fail",
+					message: `Database ${dbSpec.name} has schema issues`,
+					details,
+					fixable: true,
+				});
+			} else if (!walEnabled) {
+				checks.push({
+					name: `${dbSpec.name} WAL mode`,
+					category: "databases",
+					status: "warn",
+					message: `Database ${dbSpec.name} is not using WAL mode`,
+					details: ["WAL mode improves concurrent access performance"],
+					fixable: true,
+				});
+			} else {
+				checks.push({
+					name: `${dbSpec.name} health`,
+					category: "databases",
+					status: "pass",
+					message: `Database ${dbSpec.name} is healthy`,
+				});
+			}
+
+			db.close();
+		} catch (err) {
+			if (db) {
+				try {
+					db.close();
+				} catch {
+					// Ignore close errors
+				}
+			}
+
+			checks.push({
+				name: `${dbSpec.name} integrity`,
+				category: "databases",
+				status: "fail",
+				message: `Failed to open or validate ${dbSpec.name}`,
+				details: [
+					err instanceof Error ? err.message : String(err),
+					"Database may be corrupted or locked",
+				],
+			});
+		}
+	}
+
+	return checks;
+};
+
+/** Helper to check if file exists (synchronous). */
+function existsSync(path: string): boolean {
+	try {
+		const { existsSync } = require("node:fs");
+		return existsSync(path);
+	} catch {
+		return false;
+	}
+}

package/src/doctor/dependencies.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, test } from "bun:test";
+import type { OverstoryConfig } from "../types.ts";
+import { checkDependencies } from "./dependencies.ts";
+
+// Minimal config for testing
+const mockConfig: OverstoryConfig = {
+	project: {
+		name: "test-project",
+		root: "/tmp/test",
+		canonicalBranch: "main",
+	},
+	agents: {
+		manifestPath: "/tmp/.overstory/agent-manifest.json",
+		baseDir: "/tmp/.overstory/agents",
+		maxConcurrent: 5,
+		staggerDelayMs: 1000,
+		maxDepth: 2,
+		maxSessionsPerRun: 0,
+	},
+	worktrees: {
+		baseDir: "/tmp/.overstory/worktrees",
+	},
+	taskTracker: {
+		backend: "auto",
+		enabled: false,
+	},
+	mulch: {
+		enabled: false,
+		domains: [],
+		primeFormat: "markdown",
+	},
+	merge: {
+		aiResolveEnabled: false,
+		reimagineEnabled: false,
+	},
+	providers: {
+		anthropic: { type: "native" },
+	},
+	watchdog: {
+		tier0Enabled: false,
+		tier0IntervalMs: 30000,
+		tier1Enabled: false,
+		tier2Enabled: false,
+		staleThresholdMs: 300000,
+		zombieThresholdMs: 600000,
+		nudgeIntervalMs: 60000,
+	},
+	models: {},
+	logging: {
+		verbose: false,
+		redactSecrets: true,
+	},
+};
+
+describe("checkDependencies", () => {
+	test("returns checks for all required tools", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+
+		expect(checks).toBeArray();
+		expect(checks.length).toBeGreaterThanOrEqual(5);
+
+		// Verify we have checks for each required tool
+		const toolNames = checks.map((c) => c.name);
+		expect(toolNames).toContain("git availability");
+		expect(toolNames).toContain("bun availability");
+		expect(toolNames).toContain("tmux availability");
+		expect(toolNames).toContain("sd availability");
+		expect(toolNames).toContain("mulch availability");
+	});
+
+	test("includes bd CGO support check when bd is available", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+
+		const bdCheck = checks.find((c) => c.name === "bd availability");
+		if (bdCheck?.status === "pass") {
+			const cgoCheck = checks.find((c) => c.name === "bd CGO support");
+			expect(cgoCheck).toBeDefined();
+			expect(cgoCheck?.category).toBe("dependencies");
+			expect(["pass", "warn", "fail"]).toContain(cgoCheck?.status ?? "");
+		}
+	});
+
+	test("all checks have required DoctorCheck fields", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+
+		for (const check of checks) {
+			expect(check).toHaveProperty("name");
+			expect(check).toHaveProperty("category");
+			expect(check).toHaveProperty("status");
+			expect(check).toHaveProperty("message");
+
+			expect(check.category).toBe("dependencies");
+			expect(["pass", "warn", "fail"]).toContain(check.status);
+			expect(typeof check.name).toBe("string");
+			expect(typeof check.message).toBe("string");
+
+			if (check.details !== undefined) {
+				expect(check.details).toBeArray();
+			}
+
+			if (check.fixable !== undefined) {
+				expect(typeof check.fixable).toBe("boolean");
+			}
+		}
+	});
+
+	test("checks for commonly available tools should pass", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+
+		// git and bun should definitely be available in this environment
+		const gitCheck = checks.find((c) => c.name === "git availability");
+		const bunCheck = checks.find((c) => c.name === "bun availability");
+
+		expect(gitCheck).toBeDefined();
+		expect(bunCheck).toBeDefined();
+
+		// These should pass in a normal development environment
+		expect(gitCheck?.status).toBe("pass");
+		expect(bunCheck?.status).toBe("pass");
+
+		// Passing checks should include version info
+		if (gitCheck?.status === "pass") {
+			expect(gitCheck.details).toBeArray();
+			expect(gitCheck.details?.length).toBeGreaterThan(0);
+		}
+	});
+
+	test("checks include version details for available tools", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+
+		const passingChecks = checks.filter((c) => c.status === "pass");
+
+		for (const check of passingChecks) {
+			expect(check.details).toBeDefined();
+			expect(check.details).toBeArray();
+			expect(check.details?.length).toBeGreaterThan(0);
+
+			// Version string should not be empty
+			const version = check.details?.[0];
+			expect(version).toBeDefined();
+			expect(typeof version).toBe("string");
+			expect(version?.length).toBeGreaterThan(0);
+		}
+	});
+
+	test("failing checks are marked as fixable", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+
+		const failingChecks = checks.filter((c) => c.status === "fail" || c.status === "warn");
+
+		// If there are any failing checks, they should be marked fixable
+		for (const check of failingChecks) {
+			expect(check.fixable).toBe(true);
+		}
+	});
+
+	test("checks for sd when backend is seeds", async () => {
+		const seedsConfig: typeof mockConfig = {
+			...mockConfig,
+			taskTracker: { backend: "seeds", enabled: true },
+		};
+		const checks = await checkDependencies(seedsConfig, "/tmp/.overstory");
+		const toolNames = checks.map((c) => c.name);
+		expect(toolNames).toContain("sd availability");
+		expect(toolNames).not.toContain("bd availability");
+	});
+
+	test("checks for sd when backend is auto (seeds is default)", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+		const toolNames = checks.map((c) => c.name);
+		expect(toolNames).toContain("sd availability");
+		expect(toolNames).not.toContain("bd availability");
+	});
+
+	test("skips bd CGO check when backend is seeds", async () => {
+		const seedsConfig: typeof mockConfig = {
+			...mockConfig,
+			taskTracker: { backend: "seeds", enabled: true },
+		};
+		const checks = await checkDependencies(seedsConfig, "/tmp/.overstory");
+		const cgoCheck = checks.find((c) => c.name === "bd CGO support");
+		expect(cgoCheck).toBeUndefined();
+	});
+});

package/src/doctor/dependencies.ts

@@ -0,0 +1,175 @@
+import { resolveBackend, trackerCliName } from "../tracker/factory.ts";
+import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
+
+/**
+ * External dependency checks.
+ * Validates that required CLI tools (git, bun, tmux, bd, mulch) are available
+ * and that bd has functional CGO support for its Dolt database backend.
+ */
+export const checkDependencies: DoctorCheckFn = async (
+	config,
+	_overstoryDir,
+): Promise<DoctorCheck[]> => {
+	// Determine which tracker CLI to check based on config backend (resolve "auto")
+	const resolvedBackend = await resolveBackend(config.taskTracker.backend, config.project.root);
+	const trackerTool = {
+		name: trackerCliName(resolvedBackend),
+		versionFlag: "--version",
+		required: true,
+	};
+
+	const requiredTools = [
+		{ name: "git", versionFlag: "--version", required: true },
+		{ name: "bun", versionFlag: "--version", required: true },
+		{ name: "tmux", versionFlag: "-V", required: true },
+		trackerTool,
+		{ name: "mulch", versionFlag: "--version", required: true },
+	];
+
+	const checks: DoctorCheck[] = [];
+
+	for (const tool of requiredTools) {
+		const check = await checkTool(tool.name, tool.versionFlag, tool.required);
+		checks.push(check);
+	}
+
+	// If bd is available, probe for CGO/Dolt backend functionality.
+	// Only run for beads backend (CGO check is beads-specific).
+	if (trackerTool.name === "bd") {
+		const bdCheck = checks.find((c) => c.name === "bd availability");
+		if (bdCheck?.status === "pass") {
+			const cgoCheck = await checkBdCgoSupport();
+			checks.push(cgoCheck);
+		}
+	}
+
+	return checks;
+};
+
+/**
+ * Probe whether bd's Dolt database backend is functional.
+ * The npm-distributed bd binary may be built without CGO, which causes
+ * `bd init` and all database operations to fail even though `bd --version` succeeds.
+ * We detect this by running `bd status` in a temp directory and checking for
+ * the characteristic "without CGO support" error message.
+ */
+async function checkBdCgoSupport(): Promise<DoctorCheck> {
+	const { mkdtemp, rm } = await import("node:fs/promises");
+	const { join } = await import("node:path");
+	const { tmpdir } = await import("node:os");
+
+	let tempDir: string | undefined;
+	try {
+		tempDir = await mkdtemp(join(tmpdir(), "overstory-bd-cgo-"));
+		const proc = Bun.spawn(["bd", "status"], {
+			cwd: tempDir,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+
+		const exitCode = await proc.exited;
+		const stderr = await new Response(proc.stderr).text();
+
+		if (stderr.includes("without CGO support")) {
+			return {
+				name: "bd CGO support",
+				category: "dependencies",
+				status: "fail",
+				message: "bd binary was built without CGO — Dolt database operations will fail",
+				details: [
+					"The installed bd binary lacks CGO support required by its Dolt backend.",
+					"Workaround: rebuild bd from source with CGO_ENABLED=1 and ICU headers.",
+					"See: https://github.com/jayminwest/overstory/issues/10",
+				],
+				fixable: true,
+			};
+		}
+
+		// Any other exit code is fine — bd status may fail for other reasons
+		// (no .beads/ dir, etc.) but those aren't CGO issues
+		if (exitCode === 0 || !stderr.includes("CGO")) {
+			return {
+				name: "bd CGO support",
+				category: "dependencies",
+				status: "pass",
+				message: "bd has functional database backend",
+				details: ["Dolt backend operational"],
+			};
+		}
+
+		return {
+			name: "bd CGO support",
+			category: "dependencies",
+			status: "warn",
+			message: `bd status returned unexpected error (exit code ${exitCode})`,
+			details: [stderr.trim().split("\n")[0] || "unknown error"],
+		};
+	} catch (error) {
+		return {
+			name: "bd CGO support",
+			category: "dependencies",
+			status: "warn",
+			message: "Could not verify bd CGO support",
+			details: [error instanceof Error ? error.message : String(error)],
+		};
+	} finally {
+		if (tempDir) {
+			await rm(tempDir, { recursive: true }).catch(() => {});
+		}
+	}
+}
+
+/**
+ * Check if a CLI tool is available by attempting to run it with a version flag.
+ */
+async function checkTool(
+	name: string,
+	versionFlag: string,
+	required: boolean,
+): Promise<DoctorCheck> {
+	try {
+		const proc = Bun.spawn([name, versionFlag], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+
+		const exitCode = await proc.exited;
+
+		if (exitCode === 0) {
+			const stdout = await new Response(proc.stdout).text();
+			const version = stdout.split("\n")[0]?.trim() || "version unknown";
+
+			return {
+				name: `${name} availability`,
+				category: "dependencies",
+				status: "pass",
+				message: `${name} is available`,
+				details: [version],
+			};
+		}
+
+		// Non-zero exit code
+		const stderr = await new Response(proc.stderr).text();
+		return {
+			name: `${name} availability`,
+			category: "dependencies",
+			status: required ? "fail" : "warn",
+			message: `${name} command failed (exit code ${exitCode})`,
+			details: stderr ? [stderr.trim()] : undefined,
+			fixable: true,
+		};
+	} catch (error) {
+		// Command not found or spawn failed
+		return {
+			name: `${name} availability`,
+			category: "dependencies",
+			status: required ? "fail" : "warn",
+			message: `${name} is not installed or not in PATH`,
+			details: [
+				`Install ${name} or ensure it is in your PATH`,
+				error instanceof Error ? error.message : String(error),
+			],
+			fixable: true,
+		};
+	}
+}