@os-eco/overstory-cli 0.6.1

package/src/commands/doctor.test.ts

@@ -0,0 +1,294 @@
+/**
+ * Tests for `overstory doctor` command.
+ *
+ * Uses temp directories with real config.yaml to test the doctor scaffold.
+ * All check modules return empty arrays (stubs), so tests verify the scaffold
+ * structure, not individual check implementations.
+ *
+ * Real implementations used for: filesystem (temp dirs), config loading.
+ * No mocks needed -- all dependencies are cheap and local.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ValidationError } from "../errors.ts";
+import { doctorCommand } from "./doctor.ts";
+
+describe("doctorCommand", () => {
+	let chunks: string[];
+	let originalWrite: typeof process.stdout.write;
+	let tempDir: string;
+	let originalCwd: string;
+
+	beforeEach(async () => {
+		// Spy on stdout
+		chunks = [];
+		originalWrite = process.stdout.write;
+		process.stdout.write = ((chunk: string) => {
+			chunks.push(chunk);
+			return true;
+		}) as typeof process.stdout.write;
+
+		// Create temp dir with .overstory/config.yaml structure
+		tempDir = await mkdtemp(join(tmpdir(), "doctor-test-"));
+		const overstoryDir = join(tempDir, ".overstory");
+		await Bun.write(
+			join(overstoryDir, "config.yaml"),
+			`project:\n  name: test\n  root: ${tempDir}\n  canonicalBranch: main\n`,
+		);
+
+		// Change to temp dir so loadConfig() works
+		originalCwd = process.cwd();
+		process.chdir(tempDir);
+	});
+
+	afterEach(async () => {
+		process.stdout.write = originalWrite;
+		process.chdir(originalCwd);
+		await rm(tempDir, { recursive: true, force: true });
+	});
+
+	function output(): string {
+		return chunks.join("");
+	}
+
+	// === Help flag ===
+
+	describe("help flag", () => {
+		test("--help shows help text", async () => {
+			await doctorCommand(["--help"], { checkRunners: [] });
+			const out = output();
+
+			expect(out).toContain("overstory doctor");
+			expect(out).toContain("Run health checks");
+			expect(out).toContain("--json");
+			expect(out).toContain("--verbose");
+			expect(out).toContain("--category");
+		});
+
+		test("-h shows help text", async () => {
+			await doctorCommand(["-h"], { checkRunners: [] });
+			const out = output();
+
+			expect(out).toContain("overstory doctor");
+			expect(out).toContain("--help");
+		});
+	});
+
+	// === JSON output ===
+
+	describe("JSON output mode", () => {
+		test("outputs valid JSON with checks array and summary", async () => {
+			await doctorCommand(["--json"], { checkRunners: [] });
+			const out = output();
+
+			const parsed = JSON.parse(out.trim()) as {
+				checks: unknown[];
+				summary: { pass: number; warn: number; fail: number };
+			};
+			expect(parsed).toBeDefined();
+			expect(Array.isArray(parsed.checks)).toBe(true);
+			expect(parsed.summary).toBeDefined();
+			expect(typeof parsed.summary.pass).toBe("number");
+			expect(typeof parsed.summary.warn).toBe("number");
+			expect(typeof parsed.summary.fail).toBe("number");
+		});
+
+		test("empty stubs produce zero counts in summary", async () => {
+			await doctorCommand(["--json"], { checkRunners: [] });
+			const out = output();
+
+			const parsed = JSON.parse(out.trim()) as {
+				checks: unknown[];
+				summary: { pass: number; warn: number; fail: number };
+			};
+			expect(parsed.checks).toEqual([]);
+			expect(parsed.summary.pass).toBe(0);
+			expect(parsed.summary.warn).toBe(0);
+			expect(parsed.summary.fail).toBe(0);
+		});
+	});
+
+	// === Human-readable output ===
+
+	describe("human-readable output", () => {
+		test("shows header", async () => {
+			await doctorCommand([], { checkRunners: [] });
+			const out = output();
+
+			expect(out).toContain("Overstory Doctor");
+			expect(out).toContain("================");
+		});
+
+		test("shows summary line with zero counts", async () => {
+			await doctorCommand([], { checkRunners: [] });
+			const out = output();
+
+			expect(out).toContain("Summary:");
+			expect(out).toContain("0 passed");
+			expect(out).toContain("0 warning");
+			expect(out).toContain("0 failure");
+		});
+
+		test("summary uses singular form for one failure", async () => {
+			// This test can't verify "1 failure" without real checks, but we can test the logic
+			// by checking that the scaffold doesn't crash on empty checks
+			await doctorCommand([], { checkRunners: [] });
+			const out = output();
+
+			// Should show "0 failures" (plural) when count is 0
+			expect(out).toContain("0 failure");
+		});
+
+		test("default mode does not show empty categories", async () => {
+			await doctorCommand([], { checkRunners: [] });
+			const out = output();
+
+			// Since all stubs return empty arrays, no category headers should appear
+			// in non-verbose mode
+			expect(out).not.toContain("[dependencies]");
+			expect(out).not.toContain("[structure]");
+			expect(out).not.toContain("[config]");
+		});
+	});
+
+	// === --verbose flag ===
+
+	describe("--verbose flag", () => {
+		test("shows header and summary even with no check runners", async () => {
+			await doctorCommand(["--verbose"], { checkRunners: [] });
+			const out = output();
+
+			// With no check runners, no categories appear (even in verbose mode)
+			expect(out).toContain("Overstory Doctor");
+			expect(out).toContain("Summary:");
+			expect(out).toContain("0 passed");
+			// No categories should appear with empty checkRunners
+			expect(out).not.toContain("[dependencies]");
+			expect(out).not.toContain("[structure]");
+		});
+
+		test("verbose mode works with empty check runners", async () => {
+			await doctorCommand(["--verbose"], { checkRunners: [] });
+			const out = output();
+
+			// Should still produce valid output with no categories
+			expect(out).toContain("Overstory Doctor");
+			expect(out).toContain("Summary:");
+			// With no check runners, "No checks" doesn't appear (no categories to show it under)
+			expect(out).not.toContain("No checks");
+		});
+	});
+
+	// === --category flag ===
+
+	describe("--category flag", () => {
+		test("runs only specified category", async () => {
+			await doctorCommand(["--category", "dependencies", "--json"], { checkRunners: [] });
+			const out = output();
+
+			const parsed = JSON.parse(out.trim()) as {
+				checks: Array<{ category: string }>;
+			};
+			// Since dependencies stub returns [], checks should be empty
+			expect(parsed.checks).toEqual([]);
+		});
+
+		test("validates category name", async () => {
+			await expect(
+				doctorCommand(["--category", "invalid-category"], { checkRunners: [] }),
+			).rejects.toThrow(ValidationError);
+		});
+
+		test("invalid category error mentions valid categories", async () => {
+			try {
+				await doctorCommand(["--category", "bad"], { checkRunners: [] });
+				expect.unreachable("should have thrown");
+			} catch (err) {
+				expect(err).toBeInstanceOf(ValidationError);
+				const message = (err as ValidationError).message;
+				expect(message).toContain("Invalid category");
+				expect(message).toContain("dependencies");
+				expect(message).toContain("structure");
+				expect(message).toContain("config");
+			}
+		});
+
+		test("accepts all valid category names", async () => {
+			const categories = [
+				"dependencies",
+				"structure",
+				"config",
+				"databases",
+				"consistency",
+				"agents",
+				"merge",
+				"logs",
+				"version",
+			];
+
+			for (const category of categories) {
+				chunks = []; // Reset output
+				await doctorCommand(["--category", category, "--json"], { checkRunners: [] });
+				const out = output();
+				// Should not throw, and output should be valid JSON
+				JSON.parse(out.trim());
+			}
+		});
+	});
+
+	// === Exit code ===
+
+	describe("exit code", () => {
+		test("returns undefined when all checks pass or warn", async () => {
+			const exitCode = await doctorCommand([], { checkRunners: [] });
+			expect(exitCode).toBeUndefined();
+		});
+
+		test("returns undefined on success (no failures)", async () => {
+			const exitCode = await doctorCommand([], { checkRunners: [] });
+			expect(exitCode).toBeUndefined();
+		});
+	});
+
+	// === Edge cases ===
+
+	describe("edge cases", () => {
+		test("handles multiple flags together", async () => {
+			await doctorCommand(["--json", "--verbose", "--category", "config"], {
+				checkRunners: [],
+			});
+			const out = output();
+
+			const parsed = JSON.parse(out.trim()) as {
+				checks: unknown[];
+				summary: unknown;
+			};
+			expect(parsed.checks).toEqual([]);
+		});
+
+		test("flags can appear in any order", async () => {
+			chunks = [];
+			await doctorCommand(["--category", "logs", "--json"], { checkRunners: [] });
+			const out1 = output();
+
+			chunks = [];
+			await doctorCommand(["--json", "--category", "logs"], { checkRunners: [] });
+			const out2 = output();
+
+			// Both should produce the same JSON
+			expect(JSON.parse(out1.trim())).toEqual(JSON.parse(out2.trim()));
+		});
+
+		test("runs without crashing on minimal config", async () => {
+			// The beforeEach already sets up minimal config, so this just
+			// verifies the command doesn't crash
+			await doctorCommand([], { checkRunners: [] });
+			const out = output();
+
+			expect(out).toContain("Overstory Doctor");
+		});
+	});
+});

package/src/commands/doctor.ts

@@ -0,0 +1,213 @@
+/**
+ * CLI command: overstory doctor [options]
+ *
+ * Runs health checks on overstory subsystems and reports problems.
+ */
+
+import { join } from "node:path";
+import { loadConfig } from "../config.ts";
+import { checkAgents } from "../doctor/agents.ts";
+import { checkConfig } from "../doctor/config-check.ts";
+import { checkConsistency } from "../doctor/consistency.ts";
+import { checkDatabases } from "../doctor/databases.ts";
+import { checkDependencies } from "../doctor/dependencies.ts";
+import { checkLogs } from "../doctor/logs.ts";
+import { checkMergeQueue } from "../doctor/merge-queue.ts";
+import { checkStructure } from "../doctor/structure.ts";
+import type { DoctorCategory, DoctorCheck, DoctorCheckFn } from "../doctor/types.ts";
+import { checkVersion } from "../doctor/version.ts";
+import { ValidationError } from "../errors.ts";
+import { color } from "../logging/color.ts";
+
+/** Registry of all check modules in execution order. */
+const ALL_CHECKS: Array<{ category: DoctorCategory; fn: DoctorCheckFn }> = [
+	{ category: "dependencies", fn: checkDependencies },
+	{ category: "config", fn: checkConfig },
+	{ category: "structure", fn: checkStructure },
+	{ category: "databases", fn: checkDatabases },
+	{ category: "consistency", fn: checkConsistency },
+	{ category: "agents", fn: checkAgents },
+	{ category: "merge", fn: checkMergeQueue },
+	{ category: "logs", fn: checkLogs },
+	{ category: "version", fn: checkVersion },
+];
+
+function hasFlag(args: string[], flag: string): boolean {
+	return args.includes(flag);
+}
+
+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];
+}
+
+/**
+ * Format human-readable output for doctor checks.
+ */
+function printHumanReadable(
+	checks: DoctorCheck[],
+	verbose: boolean,
+	checkRegistry: Array<{ category: DoctorCategory; fn: DoctorCheckFn }>,
+): void {
+	const w = process.stdout.write.bind(process.stdout);
+
+	w(`${color.bold}Overstory Doctor${color.reset}\n`);
+	w("================\n\n");
+
+	// Group checks by category
+	const byCategory = new Map<DoctorCategory, DoctorCheck[]>();
+	for (const check of checks) {
+		const existing = byCategory.get(check.category);
+		if (existing) {
+			existing.push(check);
+		} else {
+			byCategory.set(check.category, [check]);
+		}
+	}
+
+	// Print each category
+	for (const { category } of checkRegistry) {
+		const categoryChecks = byCategory.get(category) ?? [];
+		if (categoryChecks.length === 0 && !verbose) {
+			continue; // Skip empty categories unless verbose
+		}
+
+		w(`${color.bold}[${category}]${color.reset}\n`);
+
+		if (categoryChecks.length === 0) {
+			w(`  ${color.dim}No checks${color.reset}\n`);
+		} else {
+			for (const check of categoryChecks) {
+				// Skip passing checks unless verbose
+				if (check.status === "pass" && !verbose) {
+					continue;
+				}
+
+				const icon =
+					check.status === "pass"
+						? `${color.green}✔${color.reset}`
+						: check.status === "warn"
+							? `${color.yellow}⚠${color.reset}`
+							: `${color.red}✘${color.reset}`;
+
+				w(`  ${icon} ${check.message}\n`);
+
+				// Print details if present
+				if (check.details && check.details.length > 0) {
+					for (const detail of check.details) {
+						w(`    ${color.dim}→ ${detail}${color.reset}\n`);
+					}
+				}
+			}
+		}
+
+		w("\n");
+	}
+
+	// Summary
+	const pass = checks.filter((c) => c.status === "pass").length;
+	const warn = checks.filter((c) => c.status === "warn").length;
+	const fail = checks.filter((c) => c.status === "fail").length;
+
+	w(
+		`${color.bold}Summary:${color.reset} ${color.green}${pass} passed${color.reset}, ${color.yellow}${warn} warning${warn === 1 ? "" : "s"}${color.reset}, ${color.red}${fail} failure${fail === 1 ? "" : "s"}${color.reset}\n`,
+	);
+}
+
+/**
+ * Format JSON output for doctor checks.
+ */
+function printJSON(checks: DoctorCheck[]): void {
+	const pass = checks.filter((c) => c.status === "pass").length;
+	const warn = checks.filter((c) => c.status === "warn").length;
+	const fail = checks.filter((c) => c.status === "fail").length;
+
+	const output = {
+		checks,
+		summary: { pass, warn, fail },
+	};
+
+	process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+}
+
+const DOCTOR_HELP = `overstory doctor -- Run health checks on overstory subsystems
+
+Usage: overstory doctor [options]
+
+Options:
+  --json                 Output as JSON
+  --verbose              Show passing checks (default: only problems)
+  --category <name>      Run only one category
+  --help, -h             Show this help
+
+Categories: dependencies, structure, config, databases, consistency, agents, merge, logs, version`;
+
+/** Options for dependency injection in doctorCommand. */
+export interface DoctorCommandOptions {
+	/** Override the check runners (defaults to ALL_CHECKS). Pass [] to skip all checks. */
+	checkRunners?: Array<{ category: DoctorCategory; fn: DoctorCheckFn }>;
+}
+
+/**
+ * Entry point for `overstory doctor [--json] [--verbose] [--category <name>]`.
+ *
+ * @returns Exit code (1 if any check failed, undefined otherwise)
+ */
+export async function doctorCommand(
+	args: string[],
+	options?: DoctorCommandOptions,
+): Promise<number | undefined> {
+	if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
+		process.stdout.write(`${DOCTOR_HELP}\n`);
+		return;
+	}
+
+	const json = hasFlag(args, "--json");
+	const verbose = hasFlag(args, "--verbose");
+	const categoryFilter = getFlag(args, "--category");
+
+	// Validate category filter if provided
+	if (categoryFilter !== undefined) {
+		const validCategories = ALL_CHECKS.map((c) => c.category);
+		if (!validCategories.includes(categoryFilter as DoctorCategory)) {
+			throw new ValidationError(
+				`Invalid category: ${categoryFilter}. Valid categories: ${validCategories.join(", ")}`,
+				{
+					field: "category",
+					value: categoryFilter,
+				},
+			);
+		}
+	}
+
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const overstoryDir = join(config.project.root, ".overstory");
+
+	// Filter checks by category if specified
+	const allChecks = options?.checkRunners ?? ALL_CHECKS;
+	const checksToRun = categoryFilter
+		? allChecks.filter((c) => c.category === categoryFilter)
+		: allChecks;
+
+	// Run all checks sequentially
+	const results: DoctorCheck[] = [];
+	for (const { fn } of checksToRun) {
+		const checkResults = await fn(config, overstoryDir);
+		results.push(...checkResults);
+	}
+
+	// Output results
+	if (json) {
+		printJSON(results);
+	} else {
+		printHumanReadable(results, verbose, allChecks);
+	}
+
+	// Return exit code if any check failed
+	const hasFailures = results.some((c) => c.status === "fail");
+	return hasFailures ? 1 : undefined;
+}