@ag-eco/agentplate-cli 0.13.0

package/src/doctor/dependencies.ts

@@ -0,0 +1,272 @@
+import { resolveBackend, trackerCliName } from "../tracker/factory.ts";
+import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
+
+interface ToolSpec {
+	name: string;
+	versionFlag: string;
+	required: boolean;
+	/** Short alias to check if the primary tool is available. */
+	alias?: string;
+	/** npm package name for install hint (e.g. "@ag-eco/loam-cli"). */
+	installHint?: string;
+}
+
+/**
+ * External dependency checks.
+ * Validates that required CLI tools (git, bun, tmux, tracker, loam, agentplate)
+ * and optional tools (tl) are available, including short alias availability.
+ */
+export const checkDependencies: DoctorCheckFn = async (
+	config,
+	_agentplateDir,
+): 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 trackerName = trackerCliName(resolvedBackend);
+
+	const tools: ToolSpec[] = [
+		{ name: "git", versionFlag: "--version", required: true },
+		{ name: "bun", versionFlag: "--version", required: true },
+		{ name: "tmux", versionFlag: "-V", required: true },
+		{
+			name: trackerName,
+			versionFlag: "--version",
+			required: true,
+			installHint: trackerName === "sr" ? "@ag-eco/agentplate-cli" : undefined,
+		},
+		{
+			name: "loam",
+			versionFlag: "--version",
+			required: true,
+			alias: "lm",
+			installHint: "@ag-eco/agentplate-cli",
+		},
+		{
+			name: "ap",
+			versionFlag: "--version",
+			required: true,
+			alias: "agentplate",
+			installHint: "@ag-eco/agentplate-cli",
+		},
+		{
+			name: "tl",
+			versionFlag: "--version",
+			required: false,
+			installHint: "@ag-eco/agentplate-cli",
+		},
+	];
+
+	const checks: DoctorCheck[] = [];
+
+	for (const tool of tools) {
+		const check = await checkTool(tool.name, tool.versionFlag, tool.required, tool.installHint);
+		checks.push(check);
+
+		// Check short alias availability if the main tool is available
+		if (tool.alias && check.status === "pass") {
+			const aliasCheck = await checkAlias(tool.name, tool.alias, tool.installHint);
+			checks.push(aliasCheck);
+		}
+	}
+
+	// If bd is available, probe for CGO/Dolt backend functionality.
+	// Only run for beads backend (CGO check is beads-specific).
+	if (trackerName === "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(), "agentplate-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/hgoudat/agentplate/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 short alias for a CLI tool is available.
+ * @internal Exported for testing.
+ */
+export async function checkAlias(
+	toolName: string,
+	alias: string,
+	installHint?: string,
+): Promise<DoctorCheck> {
+	try {
+		const proc = Bun.spawn([alias, "--version"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const exitCode = await proc.exited;
+
+		if (exitCode === 0) {
+			return {
+				name: `${alias} alias`,
+				category: "dependencies",
+				status: "pass",
+				message: `${alias} alias for ${toolName} is available`,
+				details: [`Short alias '${alias}' is configured`],
+			};
+		}
+
+		const hint = installHint
+			? `Reinstall ${installHint} to get the '${alias}' alias.`
+			: `Ensure '${alias}' alias is in your PATH.`;
+		return {
+			name: `${alias} alias`,
+			category: "dependencies",
+			status: "warn",
+			message: `${alias} alias for ${toolName} not working`,
+			details: [hint],
+			fixable: true,
+		};
+	} catch {
+		const hint = installHint
+			? `Reinstall ${installHint} to get the '${alias}' alias.`
+			: `Ensure '${alias}' alias is in your PATH.`;
+		return {
+			name: `${alias} alias`,
+			category: "dependencies",
+			status: "warn",
+			message: `${alias} alias for ${toolName} is not available`,
+			details: [`'${toolName}' works but short alias '${alias}' was not found.`, hint],
+			fixable: true,
+		};
+	}
+}
+
+/**
+ * Check if a CLI tool is available by attempting to run it with a version flag.
+ * @internal Exported for testing.
+ */
+export async function checkTool(
+	name: string,
+	versionFlag: string,
+	required: boolean,
+	installHint?: string,
+): 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();
+		const details: string[] = [];
+		if (stderr) details.push(stderr.trim());
+		if (installHint) details.push(`Install: npm install -g ${installHint}`);
+		return {
+			name: `${name} availability`,
+			category: "dependencies",
+			status: required ? "fail" : "warn",
+			message: `${name} command failed (exit code ${exitCode})`,
+			details: details.length > 0 ? details : undefined,
+			fixable: true,
+		};
+	} catch (error) {
+		// Command not found or spawn failed
+		const details: string[] = [];
+		if (installHint) {
+			details.push(`Install: npm install -g ${installHint}`);
+		} else {
+			details.push(`Install ${name} or ensure it is in your PATH`);
+		}
+		details.push(error instanceof Error ? error.message : String(error));
+		return {
+			name: `${name} availability`,
+			category: "dependencies",
+			status: required ? "fail" : "warn",
+			message: `${name} is not installed or not in PATH`,
+			details,
+			fixable: true,
+		};
+	}
+}

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 loam record mx-56558b on why mock.module() is avoided).
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { AgentplateConfig } from "../types.ts";
+import { makeCheckEcosystem, parseSemver } from "./ecosystem.ts";
+
+// ---------------------------------------------------------------------------
+// Minimal config fixture
+// ---------------------------------------------------------------------------
+
+const mockConfig: AgentplateConfig = {
+	project: {
+		name: "test-project",
+		root: "/tmp/test",
+		canonicalBranch: "main",
+	},
+	agents: {
+		manifestPath: "/tmp/.agentplate/agent-manifest.json",
+		baseDir: "/tmp/.agentplate/agents",
+		maxConcurrent: 5,
+		staggerDelayMs: 1000,
+		maxDepth: 2,
+		maxSessionsPerRun: 0,
+		maxAgentsPerLead: 5,
+	},
+	worktrees: {
+		baseDir: "/tmp/.agentplate/worktrees",
+	},
+	taskTracker: {
+		backend: "auto",
+		enabled: false,
+	},
+	loam: {
+		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("loam v1.0.0")).toBe("1.0.0");
+		expect(parseSemver("sprout 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({
+			lm: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			sr: { exitCode: 0, stdout: "2.0.0\n", stderr: "" },
+			tl: { exitCode: 0, stdout: "3.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.agentplate");
+
+		expect(results).toHaveLength(3);
+	});
+
+	test("check names match tool names", async () => {
+		const spawner = makeMockSpawner({
+			lm: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			sr: { exitCode: 0, stdout: "2.0.0\n", stderr: "" },
+			tl: { exitCode: 0, stdout: "3.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.agentplate");
+
+		const names = results.map((r) => r.name);
+		expect(names).toContain("loam semver");
+		expect(names).toContain("sprout semver");
+		expect(names).toContain("trellis semver");
+	});
+
+	test("all checks report category 'ecosystem'", async () => {
+		const spawner = makeMockSpawner({
+			lm: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			sr: { exitCode: 0, stdout: "2.0.0\n", stderr: "" },
+			tl: { exitCode: 0, stdout: "3.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.agentplate");
+
+		for (const r of results) {
+			expect(r.category).toBe("ecosystem");
+		}
+	});
+
+	test("pass when all tools report valid semver", async () => {
+		const spawner = makeMockSpawner({
+			lm: { exitCode: 0, stdout: "loam v1.2.3\n", stderr: "" },
+			sr: { exitCode: 0, stdout: "sprout 0.5.0\n", stderr: "" },
+			tl: { exitCode: 0, stdout: "0.1.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.agentplate");
+
+		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({
+			lm: { exitCode: 127, stdout: "", stderr: "lm: command not found" },
+			sr: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			tl: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.agentplate");
+
+		const loam = results.find((r) => r.name === "loam semver");
+		expect(loam?.status).toBe("warn");
+		expect(loam?.fixable).toBe(true);
+		expect(typeof loam?.fix).toBe("function");
+	});
+
+	test("warn when version output is not valid semver", async () => {
+		const spawner = makeMockSpawner({
+			lm: { exitCode: 0, stdout: "loam dev-build\n", stderr: "" },
+			sr: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			tl: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.agentplate");
+
+		const loam = results.find((r) => r.name === "loam semver");
+		expect(loam?.status).toBe("warn");
+		expect(loam?.message).toContain("not parseable semver");
+		expect(loam?.fixable).toBe(true);
+	});
+
+	test("passing checks include version in message", async () => {
+		const spawner = makeMockSpawner({
+			lm: { exitCode: 0, stdout: "1.2.3\n", stderr: "" },
+			sr: { exitCode: 0, stdout: "1.2.3\n", stderr: "" },
+			tl: { exitCode: 0, stdout: "1.2.3\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.agentplate");
+
+		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({
+			lm: { exitCode: 0, stdout: "loam v1.0.0\n", stderr: "" },
+			sr: { exitCode: 0, stdout: "sprout 1.0.0\n", stderr: "" },
+			tl: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.agentplate");
+
+		const loam = results.find((r) => r.name === "loam semver");
+		expect(loam?.details).toContain("loam v1.0.0");
+	});
+
+	test("unavailable tool details include install hint", async () => {
+		const spawner = makeMockSpawner({
+			lm: { exitCode: 127, stdout: "", stderr: "not found" },
+			sr: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			tl: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.agentplate");
+
+		const loam = results.find((r) => r.name === "loam semver");
+		const hasHint = loam?.details?.some((d) => d.includes("@ag-eco/loam-cli"));
+		expect(hasHint).toBe(true);
+	});
+
+	test("all checks have required DoctorCheck fields", async () => {
+		const spawner = makeMockSpawner({
+			lm: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			sr: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			tl: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.agentplate");
+
+		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/.agentplate");
+
+		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({
+			lm: { exitCode: 0, stdout: "", stderr: "1.0.0" },
+			sr: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+			tl: { exitCode: 0, stdout: "1.0.0\n", stderr: "" },
+		});
+		const check = makeCheckEcosystem(spawner);
+		const results = await check(mockConfig, "/tmp/.agentplate");
+
+		const loam = results.find((r) => r.name === "loam semver");
+		expect(loam?.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/.agentplate");
+
+		expect(results).toHaveLength(3);
+		for (const r of results) {
+			expect(r.status).toBe("warn");
+		}
+	});
+});