@os-eco/overstory-cli 0.6.1

package/src/doctor/structure.ts

@@ -0,0 +1,198 @@
+import { access, constants } from "node:fs/promises";
+import { join } from "node:path";
+import type { AgentManifest } from "../types.ts";
+import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
+
+/**
+ * Check if a path exists.
+ */
+async function pathExists(path: string): Promise<boolean> {
+	try {
+		await access(path, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Directory structure checks.
+ * Validates that .overstory/ and its subdirectories exist with correct permissions.
+ */
+export const checkStructure: DoctorCheckFn = async (
+	_config,
+	overstoryDir,
+): Promise<DoctorCheck[]> => {
+	const checks: DoctorCheck[] = [];
+
+	// Check 1: .overstory/ directory exists
+	const overstoryDirExists = await pathExists(overstoryDir);
+	checks.push({
+		name: ".overstory/ directory",
+		category: "structure",
+		status: overstoryDirExists ? "pass" : "fail",
+		message: overstoryDirExists ? "Directory exists" : "Directory missing",
+		details: overstoryDirExists ? undefined : ["Run 'overstory init' to create it"],
+		fixable: !overstoryDirExists,
+	});
+
+	// If .overstory/ doesn't exist, bail early
+	if (!overstoryDirExists) {
+		return checks;
+	}
+
+	// Check 2: Required files
+	const requiredFiles = ["config.yaml", "agent-manifest.json", "hooks.json", ".gitignore"];
+	const missingFiles: string[] = [];
+
+	for (const fileName of requiredFiles) {
+		const filePath = join(overstoryDir, fileName);
+		const exists = await pathExists(filePath);
+		if (!exists) {
+			missingFiles.push(fileName);
+		}
+	}
+
+	checks.push({
+		name: "Required files",
+		category: "structure",
+		status: missingFiles.length === 0 ? "pass" : "fail",
+		message:
+			missingFiles.length === 0
+				? "All required files present"
+				: `Missing ${missingFiles.length} file(s)`,
+		details: missingFiles.length > 0 ? missingFiles : undefined,
+		fixable: missingFiles.length > 0,
+	});
+
+	// Check 3: Required subdirectories
+	const requiredDirs = ["agent-defs", "agents", "worktrees", "specs", "logs"];
+	const missingDirs: string[] = [];
+
+	for (const dirName of requiredDirs) {
+		const dirPath = join(overstoryDir, dirName);
+		const exists = await pathExists(dirPath);
+		if (!exists) {
+			missingDirs.push(`${dirName}/`);
+		}
+	}
+
+	checks.push({
+		name: "Required subdirectories",
+		category: "structure",
+		status: missingDirs.length === 0 ? "pass" : "fail",
+		message:
+			missingDirs.length === 0
+				? "All required subdirectories present"
+				: `Missing ${missingDirs.length} subdirectory(ies)`,
+		details: missingDirs.length > 0 ? missingDirs : undefined,
+		fixable: missingDirs.length > 0,
+	});
+
+	// Check 4: .gitignore contents — validate wildcard+whitelist model
+	const gitignorePath = join(overstoryDir, ".gitignore");
+	const expectedEntries = [
+		"*",
+		"!.gitignore",
+		"!config.yaml",
+		"!agent-manifest.json",
+		"!hooks.json",
+		"!groups.json",
+		"!agent-defs/",
+	];
+
+	try {
+		const gitignoreContent = await Bun.file(gitignorePath).text();
+		const missingEntries = expectedEntries.filter((entry) => !gitignoreContent.includes(entry));
+
+		checks.push({
+			name: ".gitignore entries",
+			category: "structure",
+			status: missingEntries.length === 0 ? "pass" : "warn",
+			message:
+				missingEntries.length === 0
+					? "All expected entries present"
+					: `Missing ${missingEntries.length} entry(ies)`,
+			details: missingEntries.length > 0 ? missingEntries : undefined,
+			fixable: missingEntries.length > 0,
+		});
+	} catch {
+		// .gitignore doesn't exist, already reported in required files check
+		checks.push({
+			name: ".gitignore entries",
+			category: "structure",
+			status: "fail",
+			message: "Cannot read .gitignore",
+			details: ["File is missing or unreadable"],
+			fixable: true,
+		});
+	}
+
+	// Check 5: agent-defs/ contains .md files referenced by agent-manifest.json
+	try {
+		const manifestPath = join(overstoryDir, "agent-manifest.json");
+		const manifestContent = await Bun.file(manifestPath).text();
+		const manifest = JSON.parse(manifestContent) as AgentManifest;
+
+		const referencedFiles = new Set<string>();
+		for (const agentDef of Object.values(manifest.agents)) {
+			referencedFiles.add(agentDef.file);
+		}
+
+		const agentDefsDir = join(overstoryDir, "agent-defs");
+		const missingDefFiles: string[] = [];
+
+		for (const fileName of referencedFiles) {
+			const filePath = join(agentDefsDir, fileName);
+			const exists = await pathExists(filePath);
+			if (!exists) {
+				missingDefFiles.push(fileName);
+			}
+		}
+
+		checks.push({
+			name: "Agent definition files",
+			category: "structure",
+			status: missingDefFiles.length === 0 ? "pass" : "fail",
+			message:
+				missingDefFiles.length === 0
+					? "All referenced .md files present"
+					: `Missing ${missingDefFiles.length} agent definition(s)`,
+			details: missingDefFiles.length > 0 ? missingDefFiles : undefined,
+			fixable: missingDefFiles.length > 0,
+		});
+	} catch (error) {
+		// Manifest missing or malformed, already reported or will be in config checks
+		checks.push({
+			name: "Agent definition files",
+			category: "structure",
+			status: "fail",
+			message: "Cannot validate agent definitions",
+			details: [
+				error instanceof Error ? error.message : "agent-manifest.json is missing or malformed",
+			],
+			fixable: false,
+		});
+	}
+
+	// Check 6: No leftover files from failed init attempts
+	// Common temp files: .tmp, .bak, config.yaml~, etc.
+	try {
+		const entries = await Array.fromAsync(new Bun.Glob("*.{tmp,bak}").scan({ cwd: overstoryDir }));
+		const tempFiles = entries.filter((name) => name.endsWith(".tmp") || name.endsWith(".bak"));
+
+		checks.push({
+			name: "Leftover temp files",
+			category: "structure",
+			status: tempFiles.length === 0 ? "pass" : "warn",
+			message:
+				tempFiles.length === 0 ? "No temp files found" : `Found ${tempFiles.length} temp file(s)`,
+			details: tempFiles.length > 0 ? tempFiles : undefined,
+			fixable: tempFiles.length > 0,
+		});
+	} catch {
+		// Ignore errors scanning for temp files
+	}
+
+	return checks;
+};

package/src/doctor/types.ts

@@ -0,0 +1,37 @@
+import type { OverstoryConfig } from "../types.ts";
+
+// === Doctor (Health Checks) ===
+
+/** Categories for doctor health checks. */
+export type DoctorCategory =
+	| "dependencies"
+	| "structure"
+	| "config"
+	| "databases"
+	| "consistency"
+	| "agents"
+	| "merge"
+	| "logs"
+	| "version";
+
+/** Result of a single doctor health check. */
+export interface DoctorCheck {
+	name: string;
+	category: DoctorCategory;
+	status: "pass" | "warn" | "fail";
+	message: string;
+	details?: string[];
+	/** Whether this check issues can be auto-fixed (future --fix flag). */
+	fixable?: boolean;
+}
+
+/**
+ * Signature for a doctor check function.
+ * Each check module exports a function matching this signature.
+ * Receives the loaded config and the absolute path to .overstory/.
+ * Returns one or more check results.
+ */
+export type DoctorCheckFn = (
+	config: OverstoryConfig,
+	overstoryDir: string,
+) => DoctorCheck[] | Promise<DoctorCheck[]>;

package/src/doctor/version.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from "bun:test";
+import type { OverstoryConfig } from "../types.ts";
+import { checkVersion } from "./version.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("checkVersion", () => {
+	test("returns checks with category version", async () => {
+		const checks = await checkVersion(mockConfig, "/tmp/.overstory");
+
+		expect(checks).toBeArray();
+		expect(checks.length).toBeGreaterThan(0);
+
+		for (const check of checks) {
+			expect(check.category).toBe("version");
+		}
+	});
+
+	test("includes version-current check", async () => {
+		const checks = await checkVersion(mockConfig, "/tmp/.overstory");
+
+		const versionCheck = checks.find((c) => c.name === "version-current");
+		expect(versionCheck).toBeDefined();
+		expect(versionCheck?.status).toBeOneOf(["pass", "warn", "fail"]);
+		expect(versionCheck?.message).toContain("overstory");
+	});
+
+	test("includes package-json-sync check", async () => {
+		const checks = await checkVersion(mockConfig, "/tmp/.overstory");
+
+		const syncCheck = checks.find((c) => c.name === "package-json-sync");
+		expect(syncCheck).toBeDefined();
+		expect(syncCheck?.status).toBeOneOf(["pass", "warn", "fail"]);
+	});
+
+	test("version-current check reports version string", async () => {
+		const checks = await checkVersion(mockConfig, "/tmp/.overstory");
+
+		const versionCheck = checks.find((c) => c.name === "version-current");
+		expect(versionCheck).toBeDefined();
+
+		if (versionCheck?.status === "pass") {
+			// Message should contain version in format "overstory vX.Y.Z"
+			expect(versionCheck.message).toMatch(/overstory v\d+\.\d+\.\d+/);
+		}
+	});
+
+	test("package-json-sync check provides details", async () => {
+		const checks = await checkVersion(mockConfig, "/tmp/.overstory");
+
+		const syncCheck = checks.find((c) => c.name === "package-json-sync");
+		expect(syncCheck).toBeDefined();
+
+		if (syncCheck?.status === "pass") {
+			// Should include version details
+			expect(syncCheck.details).toBeDefined();
+			expect(syncCheck.details?.length).toBeGreaterThan(0);
+
+			// Details should mention both package.json and src/index.ts
+			const detailsText = syncCheck.details?.join(" ");
+			expect(detailsText).toContain("package.json");
+			expect(detailsText).toContain("src/index.ts");
+		}
+	});
+
+	test("all checks have required DoctorCheck fields", async () => {
+		const checks = await checkVersion(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(typeof check.name).toBe("string");
+			expect(typeof check.message).toBe("string");
+			expect(["pass", "warn", "fail"]).toContain(check.status);
+
+			if (check.details !== undefined) {
+				expect(check.details).toBeArray();
+			}
+
+			if (check.fixable !== undefined) {
+				expect(typeof check.fixable).toBe("boolean");
+			}
+		}
+	});
+});

package/src/doctor/version.ts

@@ -0,0 +1,129 @@
+import { join } from "node:path";
+import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
+
+/**
+ * Version compatibility checks.
+ * Validates overstory CLI version, config schema version, database schema versions.
+ */
+export const checkVersion: DoctorCheckFn = async (
+	_config,
+	_overstoryDir,
+): Promise<DoctorCheck[]> => {
+	const checks: DoctorCheck[] = [];
+
+	// Determine overstory tool root (not the target project)
+	// import.meta.dir is src/doctor/, so go up two levels to repo root
+	const toolRoot = join(import.meta.dir, "..", "..");
+
+	// Check 1: version-current (read package.json)
+	const versionCheck = await checkCurrentVersion(toolRoot);
+	checks.push(versionCheck);
+
+	// Check 2: package-json-sync (compare package.json and src/index.ts)
+	const syncCheck = await checkVersionSync(toolRoot);
+	checks.push(syncCheck);
+
+	return checks;
+};
+
+/**
+ * Check that the current version can be determined from package.json.
+ */
+async function checkCurrentVersion(toolRoot: string): Promise<DoctorCheck> {
+	try {
+		const packageJsonPath = join(toolRoot, "package.json");
+		const packageJson = (await Bun.file(packageJsonPath).json()) as { version?: string };
+
+		if (!packageJson.version) {
+			return {
+				name: "version-current",
+				category: "version",
+				status: "fail",
+				message: "Cannot determine version (package.json has no version field)",
+			};
+		}
+
+		return {
+			name: "version-current",
+			category: "version",
+			status: "pass",
+			message: `overstory v${packageJson.version}`,
+		};
+	} catch (error) {
+		return {
+			name: "version-current",
+			category: "version",
+			status: "fail",
+			message: "Cannot determine version",
+			details: [error instanceof Error ? error.message : String(error)],
+		};
+	}
+}
+
+/**
+ * Check that package.json version matches src/index.ts VERSION constant.
+ */
+async function checkVersionSync(toolRoot: string): Promise<DoctorCheck> {
+	try {
+		// Read package.json version
+		const packageJsonPath = join(toolRoot, "package.json");
+		const packageJson = (await Bun.file(packageJsonPath).json()) as { version?: string };
+		const pkgVersion = packageJson.version;
+
+		if (!pkgVersion) {
+			return {
+				name: "package-json-sync",
+				category: "version",
+				status: "warn",
+				message: "Cannot verify version sync (package.json has no version)",
+			};
+		}
+
+		// Read src/index.ts and extract VERSION constant
+		const indexPath = join(toolRoot, "src", "index.ts");
+		const indexContent = await Bun.file(indexPath).text();
+
+		// Regex to find: const VERSION = "x.y.z"
+		const versionRegex = /const\s+VERSION\s*=\s*["']([^"']+)["']/;
+		const match = versionRegex.exec(indexContent);
+
+		if (!match?.[1]) {
+			return {
+				name: "package-json-sync",
+				category: "version",
+				status: "warn",
+				message: "Cannot find VERSION constant in src/index.ts",
+				details: [`package.json version: ${pkgVersion}`],
+			};
+		}
+
+		const indexVersion = match[1];
+
+		if (pkgVersion === indexVersion) {
+			return {
+				name: "package-json-sync",
+				category: "version",
+				status: "pass",
+				message: "Versions are synchronized",
+				details: [`package.json: ${pkgVersion}`, `src/index.ts: ${indexVersion}`],
+			};
+		}
+
+		return {
+			name: "package-json-sync",
+			category: "version",
+			status: "warn",
+			message: "Version mismatch between package.json and src/index.ts",
+			details: [`package.json: ${pkgVersion}`, `src/index.ts: ${indexVersion}`],
+			fixable: true,
+		};
+	} catch (error) {
+		return {
+			name: "package-json-sync",
+			category: "version",
+			status: "warn",
+			message: "Cannot verify version sync",
+			details: [error instanceof Error ? error.message : String(error)],
+		};
+	}
+}