@os-eco/overstory-cli 0.6.9 → 0.6.11

package/src/doctor/ecosystem.test.ts

@@ -0,0 +1,308 @@
+/**
+ * Tests for the ecosystem doctor check module.
+ *
+ * We inject a mock spawner instead of using mock.module() to avoid cross-test
+ * leakage (see mulch record mx-56558b on why mock.module() is avoided).
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { OverstoryConfig } from "../types.ts";
+import { makeCheckEcosystem, parseSemver } from "./ecosystem.ts";
+
+// ---------------------------------------------------------------------------
+// Minimal config fixture
+// ---------------------------------------------------------------------------
+
+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,
+		maxAgentsPerLead: 5,
+	},
+	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,
+	},
+};
+
+// ---------------------------------------------------------------------------
+// Mock spawner helpers
+// ---------------------------------------------------------------------------
+
+type SpawnResponse = { exitCode: number; stdout: string; stderr: string };
+
+/**
+ * Build a mock spawner that dispatches by binary name (first arg).
+ */
+function makeMockSpawner(responses: Record<string, SpawnResponse>) {
+	return async (args: string[]): Promise<SpawnResponse> => {
+		const bin = args[0] ?? "";
+		return (
+			responses[bin] ?? {
+				exitCode: 127,
+				stdout: "",
+				stderr: `${bin}: command not found`,
+			}
+		);
+	};
+}
+
+// ---------------------------------------------------------------------------
+// parseSemver unit tests
+// ---------------------------------------------------------------------------
+
+describe("parseSemver", () => {
+	test("extracts bare semver", () => {
+		expect(parseSemver("1.2.3")).toBe("1.2.3");
+	});
+
+	test("extracts semver from prefixed output", () => {
+		expect(parseSemver("mulch v1.0.0")).toBe("1.0.0");
+		expect(parseSemver("seeds version 2.3.4")).toBe("2.3.4");
+	});
+
+	test("extracts semver with prerelease", () => {
+		expect(parseSemver("1.2.3-alpha.1")).toBe("1.2.3-alpha.1");
+	});
+
+	test("extracts semver with build metadata", () => {
+		expect(parseSemver("1.2.3+build.42")).toBe("1.2.3+build.42");
+	});
+
+	test("returns null for non-semver strings", () => {
+		expect(parseSemver("not-a-version")).toBeNull();
+		expect(parseSemver("")).toBeNull();
+		expect(parseSemver("v2.0")).toBeNull();
+	});
+
+	test("extracts first semver when multiple exist", () => {
+		expect(parseSemver("tool 1.0.0 requires node 18.0.0")).toBe("1.0.0");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// checkEcosystem integration tests
+// ---------------------------------------------------------------------------
+
+describe("checkEcosystem", () => {
+	test("returns exactly 3 checks (one per tool)", async () => {
+		const spawner = makeMockSpawner({
+			ml: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			sd: { exitCode: 0, stdout: "2.0.0\n", stderr: "" },
+			cn: { exitCode: 0, stdout: "3.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.overstory");
+
+		expect(results).toHaveLength(3);
+	});
+
+	test("check names match tool names", async () => {
+		const spawner = makeMockSpawner({
+			ml: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			sd: { exitCode: 0, stdout: "2.0.0\n", stderr: "" },
+			cn: { exitCode: 0, stdout: "3.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.overstory");
+
+		const names = results.map((r) => r.name);
+		expect(names).toContain("mulch semver");
+		expect(names).toContain("seeds semver");
+		expect(names).toContain("canopy semver");
+	});
+
+	test("all checks report category 'ecosystem'", async () => {
+		const spawner = makeMockSpawner({
+			ml: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			sd: { exitCode: 0, stdout: "2.0.0\n", stderr: "" },
+			cn: { exitCode: 0, stdout: "3.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.overstory");
+
+		for (const r of results) {
+			expect(r.category).toBe("ecosystem");
+		}
+	});
+
+	test("pass when all tools report valid semver", async () => {
+		const spawner = makeMockSpawner({
+			ml: { exitCode: 0, stdout: "mulch v1.2.3\n", stderr: "" },
+			sd: { exitCode: 0, stdout: "seeds 0.5.0\n", stderr: "" },
+			cn: { exitCode: 0, stdout: "0.1.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.overstory");
+
+		for (const r of results) {
+			expect(r.status).toBe("pass");
+		}
+	});
+
+	test("warn when a tool is not available (non-zero exit code)", async () => {
+		const spawner = makeMockSpawner({
+			ml: { exitCode: 127, stdout: "", stderr: "ml: command not found" },
+			sd: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			cn: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.overstory");
+
+		const mulch = results.find((r) => r.name === "mulch semver");
+		expect(mulch?.status).toBe("warn");
+		expect(mulch?.fixable).toBe(true);
+		expect(typeof mulch?.fix).toBe("function");
+	});
+
+	test("warn when version output is not valid semver", async () => {
+		const spawner = makeMockSpawner({
+			ml: { exitCode: 0, stdout: "mulch dev-build\n", stderr: "" },
+			sd: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			cn: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.overstory");
+
+		const mulch = results.find((r) => r.name === "mulch semver");
+		expect(mulch?.status).toBe("warn");
+		expect(mulch?.message).toContain("not parseable semver");
+		expect(mulch?.fixable).toBe(true);
+	});
+
+	test("passing checks include version in message", async () => {
+		const spawner = makeMockSpawner({
+			ml: { exitCode: 0, stdout: "1.2.3\n", stderr: "" },
+			sd: { exitCode: 0, stdout: "1.2.3\n", stderr: "" },
+			cn: { exitCode: 0, stdout: "1.2.3\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.overstory");
+
+		for (const r of results) {
+			expect(r.status).toBe("pass");
+			expect(r.message).toContain("1.2.3");
+		}
+	});
+
+	test("passing checks include raw output in details", async () => {
+		const spawner = makeMockSpawner({
+			ml: { exitCode: 0, stdout: "mulch v1.0.0\n", stderr: "" },
+			sd: { exitCode: 0, stdout: "seeds 1.0.0\n", stderr: "" },
+			cn: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.overstory");
+
+		const mulch = results.find((r) => r.name === "mulch semver");
+		expect(mulch?.details).toContain("mulch v1.0.0");
+	});
+
+	test("unavailable tool details include install hint", async () => {
+		const spawner = makeMockSpawner({
+			ml: { exitCode: 127, stdout: "", stderr: "not found" },
+			sd: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			cn: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.overstory");
+
+		const mulch = results.find((r) => r.name === "mulch semver");
+		const hasHint = mulch?.details?.some((d) => d.includes("@os-eco/mulch-cli"));
+		expect(hasHint).toBe(true);
+	});
+
+	test("all checks have required DoctorCheck fields", async () => {
+		const spawner = makeMockSpawner({
+			ml: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			sd: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			cn: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.overstory");
+
+		for (const r of results) {
+			expect(typeof r.name).toBe("string");
+			expect(r.name.length).toBeGreaterThan(0);
+			expect(r.category).toBe("ecosystem");
+			expect(["pass", "warn", "fail"]).toContain(r.status);
+			expect(typeof r.message).toBe("string");
+		}
+	});
+
+	test("failing checks are marked fixable and have a fix closure", async () => {
+		const spawner = makeMockSpawner({}); // all tools unavailable
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.overstory");
+
+		for (const r of results) {
+			expect(r.status).toBe("warn");
+			expect(r.fixable).toBe(true);
+			expect(typeof r.fix).toBe("function");
+		}
+	});
+
+	test("handles version in stderr when stdout is empty", async () => {
+		const spawner = makeMockSpawner({
+			ml: { exitCode: 0, stdout: "", stderr: "1.0.0" },
+			sd: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			cn: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.overstory");
+
+		const mulch = results.find((r) => r.name === "mulch semver");
+		expect(mulch?.status).toBe("pass");
+	});
+
+	test("handles spawn exception gracefully", async () => {
+		const errorSpawner = async (_args: string[]) => {
+			throw new Error("spawn failed");
+		};
+		const check = makeCheckEcosystem(errorSpawner);
+		const results = await check(mockConfig, "/tmp/.overstory");
+
+		expect(results).toHaveLength(3);
+		for (const r of results) {
+			expect(r.status).toBe("warn");
+		}
+	});
+});

package/src/doctor/ecosystem.ts

@@ -0,0 +1,155 @@
+import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
+
+/**
+ * Ecosystem health checks.
+ *
+ * Validates that os-eco CLI tools (ml, sd, cn) are on PATH and report valid
+ * semver versions. Intentionally does NOT duplicate the availability checks in
+ * dependencies.ts — those confirm the binaries exist. These checks focus on
+ * whether the reported version string is parseable semver, and whether the
+ * tools are mutually compatible.
+ *
+ * Fix closures reinstall the relevant package via `bun install -g <pkg>`.
+ */
+
+/** A single os-eco ecosystem tool. */
+interface EcosystemTool {
+	/** Human-readable tool name. */
+	name: string;
+	/** Primary binary to invoke for version check. */
+	bin: string;
+	/** npm package name for install / reinstall. */
+	pkg: string;
+}
+
+const ECOSYSTEM_TOOLS: EcosystemTool[] = [
+	{ name: "mulch", bin: "ml", pkg: "@os-eco/mulch-cli" },
+	{ name: "seeds", bin: "sd", pkg: "@os-eco/seeds-cli" },
+	{ name: "canopy", bin: "cn", pkg: "@os-eco/canopy-cli" },
+];
+
+/** Spawner abstraction — injected in tests, uses Bun.spawn in production. */
+export type Spawner = (
+	args: string[],
+) => Promise<{ exitCode: number; stdout: string; stderr: string }>;
+
+async function defaultSpawner(
+	args: string[],
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+	const proc = Bun.spawn(args, {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const exitCode = await proc.exited;
+	const stdout = await new Response(proc.stdout).text();
+	const stderr = await new Response(proc.stderr).text();
+	return { exitCode, stdout, stderr };
+}
+
+/**
+ * Loose semver extractor.
+ * Finds the first x.y.z (optionally x.y.z-pre or x.y.z+build) token in a string.
+ * Returns null when no valid semver token is found.
+ */
+export function parseSemver(output: string): string | null {
+	const match = /(\d+\.\d+\.\d+(?:[-.+][a-zA-Z0-9._-]*)?)/.exec(output);
+	return match?.[1] ?? null;
+}
+
+/** Internal result of probing a binary's version output. */
+interface VersionProbeResult {
+	available: boolean;
+	version: string | null;
+	raw: string;
+}
+
+async function probeVersion(bin: string, spawner: Spawner): Promise<VersionProbeResult> {
+	try {
+		const { exitCode, stdout, stderr } = await spawner([bin, "--version"]);
+		const raw = (stdout + stderr).trim();
+		if (exitCode !== 0) {
+			return { available: false, version: null, raw };
+		}
+		const version = parseSemver(raw);
+		return { available: true, version, raw };
+	} catch {
+		return { available: false, version: null, raw: "" };
+	}
+}
+
+/** Build a DoctorCheck for a single ecosystem tool. */
+function buildCheck(tool: EcosystemTool, probe: VersionProbeResult): DoctorCheck {
+	const { bin, pkg, name } = tool;
+
+	if (!probe.available) {
+		return {
+			name: `${name} semver`,
+			category: "ecosystem",
+			status: "warn",
+			message: `${bin} is not available — cannot verify version`,
+			details: [`Install: bun install -g ${pkg}`],
+			fixable: true,
+			fix: async () => {
+				const proc = Bun.spawn(["bun", "install", "-g", pkg], {
+					stdout: "inherit",
+					stderr: "inherit",
+				});
+				await proc.exited;
+				return [`Installed ${pkg}`];
+			},
+		};
+	}
+
+	if (probe.version === null) {
+		return {
+			name: `${name} semver`,
+			category: "ecosystem",
+			status: "warn",
+			message: `${bin} --version output is not parseable semver`,
+			details: [
+				`Raw output: ${probe.raw || "(empty)"}`,
+				"Expected format: x.y.z",
+				`Reinstall: bun install -g ${pkg}`,
+			],
+			fixable: true,
+			fix: async () => {
+				const proc = Bun.spawn(["bun", "install", "-g", pkg], {
+					stdout: "inherit",
+					stderr: "inherit",
+				});
+				await proc.exited;
+				return [`Reinstalled ${pkg}`];
+			},
+		};
+	}
+
+	return {
+		name: `${name} semver`,
+		category: "ecosystem",
+		status: "pass",
+		message: `${name} v${probe.version} (valid semver)`,
+		details: [probe.raw],
+	};
+}
+
+/**
+ * Factory that creates a DoctorCheckFn with an injectable spawner.
+ * Used for testing without module-level mocks.
+ */
+export function makeCheckEcosystem(spawner: Spawner = defaultSpawner): DoctorCheckFn {
+	return async (_config, _overstoryDir): Promise<DoctorCheck[]> => {
+		const checks: DoctorCheck[] = [];
+
+		for (const tool of ECOSYSTEM_TOOLS) {
+			const probe = await probeVersion(tool.bin, spawner);
+			checks.push(buildCheck(tool, probe));
+		}
+
+		return checks;
+	};
+}
+
+/**
+ * Ecosystem health check — validates semver version output for ml, sd, cn.
+ */
+export const checkEcosystem: DoctorCheckFn = makeCheckEcosystem();

package/src/doctor/logs.test.ts

@@ -36,6 +36,7 @@ describe("checkLogs", () => {
 				staggerDelayMs: 1000,
 				maxDepth: 2,
 				maxSessionsPerRun: 0,
+				maxAgentsPerLead: 5,
 			},
 			worktrees: {
 				baseDir: ".overstory/worktrees",

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

@@ -23,6 +23,7 @@ describe("checkMergeQueue", () => {
 				staggerDelayMs: 100,
 				maxDepth: 2,
 				maxSessionsPerRun: 0,
+				maxAgentsPerLead: 5,
 			},
 			worktrees: { baseDir: "" },
 			taskTracker: { backend: "auto", enabled: true },
@@ -213,4 +214,102 @@ describe("checkMergeQueue", () => {
 		expect(duplicateCheck?.message).toContain("duplicate branch entries");
 		expect(duplicateCheck?.details?.[0]).toContain("feature/duplicate");
 	});
+
+	test("fix() deletes stale pending entries", () => {
+		const dbPath = join(tempDir, "merge-queue.db");
+		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-1",
+			"beads-abc",
+			"test-agent",
+			JSON.stringify(["src/test.ts"]),
+			"pending",
+			staleDate.toISOString(),
+		);
+		db.prepare(
+			"INSERT INTO merge_queue (branch_name, task_id, agent_name, files_modified, status, enqueued_at) VALUES (?, ?, ?, ?, ?, ?)",
+		).run(
+			"feature/stale-2",
+			"beads-def",
+			"test-agent",
+			JSON.stringify(["src/other.ts"]),
+			"merging",
+			staleDate.toISOString(),
+		);
+		db.close();
+
+		const checks = checkMergeQueue(mockConfig, tempDir) as DoctorCheck[];
+
+		const staleCheck = checks.find((c) => c?.name === "merge-queue.db staleness");
+		expect(staleCheck?.fix).toBeDefined();
+
+		const actions = staleCheck?.fix?.();
+		expect(Array.isArray(actions)).toBe(true);
+		const actionsArr = actions as string[];
+		expect(actionsArr.some((a) => a.includes("Deleted") && a.includes("stale"))).toBe(true);
+
+		// Verify entries were deleted
+		const verifyDb = new Database(dbPath);
+		const remaining = verifyDb
+			.prepare("SELECT COUNT(*) as count FROM merge_queue WHERE status IN ('pending', 'merging')")
+			.get() as { count: number };
+		verifyDb.close();
+		expect(remaining.count).toBe(0);
+	});
+
+	test("fix() removes duplicate entries keeping newest", () => {
+		const dbPath = join(tempDir, "merge-queue.db");
+		const queue = createMergeQueue(dbPath);
+		queue.enqueue({
+			branchName: "feature/dup",
+			taskId: "beads-abc",
+			agentName: "agent-1",
+			filesModified: ["src/a.ts"],
+		});
+		queue.enqueue({
+			branchName: "feature/dup",
+			taskId: "beads-def",
+			agentName: "agent-2",
+			filesModified: ["src/b.ts"],
+		});
+		queue.enqueue({
+			branchName: "feature/other",
+			taskId: "beads-ghi",
+			agentName: "agent-3",
+			filesModified: ["src/c.ts"],
+		});
+		queue.close();
+
+		const checks = checkMergeQueue(mockConfig, tempDir) as DoctorCheck[];
+
+		const dupCheck = checks.find((c) => c?.name === "merge-queue.db duplicates");
+		expect(dupCheck?.fix).toBeDefined();
+
+		const actions = dupCheck?.fix?.();
+		expect(Array.isArray(actions)).toBe(true);
+		const actionsArr = actions as string[];
+		expect(actionsArr.some((a) => a.includes("Removed") && a.includes("duplicate"))).toBe(true);
+
+		// Verify only 2 entries remain (1 per branch)
+		const verifyDb = new Database(dbPath);
+		const remaining = verifyDb.prepare("SELECT COUNT(*) as count FROM merge_queue").get() as {
+			count: number;
+		};
+		// Check the newest entry for feature/dup is kept (highest id)
+		const dupEntries = verifyDb
+			.prepare("SELECT agent_name FROM merge_queue WHERE branch_name = 'feature/dup'")
+			.all() as Array<{ agent_name: string }>;
+		verifyDb.close();
+		expect(remaining.count).toBe(2);
+		expect(dupEntries).toHaveLength(1);
+		expect(dupEntries[0]?.agent_name).toBe("agent-2"); // newest entry kept
+	});
 });

package/src/doctor/merge-queue.ts

@@ -114,6 +114,18 @@ export const checkMergeQueue: DoctorCheckFn = (_config, overstoryDir): DoctorChe
 				message: `Found ${staleEntries.length} potentially stale queue entries`,
 				details: staleEntries,
 				fixable: true,
+				fix: () => {
+					const fixDb = new Database(dbPath);
+					fixDb.exec("PRAGMA busy_timeout=5000");
+					const staleThreshold = new Date(now.getTime() - staleThresholdMs).toISOString();
+					const result = fixDb
+						.prepare(
+							"DELETE FROM merge_queue WHERE status IN ('pending', 'merging') AND enqueued_at < ?",
+						)
+						.run(staleThreshold);
+					fixDb.close();
+					return [`Deleted ${result.changes} stale merge queue entries`];
+				},
 			});
 		}
 
@@ -134,6 +146,17 @@ export const checkMergeQueue: DoctorCheckFn = (_config, overstoryDir): DoctorChe
 				message: "Found duplicate branch entries in queue",
 				details: duplicates,
 				fixable: true,
+				fix: () => {
+					const fixDb = new Database(dbPath);
+					fixDb.exec("PRAGMA busy_timeout=5000");
+					const result = fixDb
+						.prepare(
+							"DELETE FROM merge_queue WHERE id NOT IN (SELECT MAX(id) FROM merge_queue GROUP BY branch_name)",
+						)
+						.run();
+					fixDb.close();
+					return [`Removed ${result.changes} duplicate merge queue entries`];
+				},
 			});
 		}
 	} finally {