@ag-eco/agentplate-cli 0.13.0

package/src/commands/doctor.test.ts

@@ -0,0 +1,303 @@
+/**
+ * Tests for `agentplate 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 } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ValidationError } from "../errors.ts";
+import { cleanupTempDir } from "../test-helpers.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 .agentplate/config.yaml structure
+		tempDir = await mkdtemp(join(tmpdir(), "doctor-test-"));
+		const agentplateDir = join(tempDir, ".agentplate");
+		await Bun.write(
+			join(agentplateDir, "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 cleanupTempDir(tempDir);
+	});
+
+	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("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("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 {
+				success: boolean;
+				command: string;
+				checks: unknown[];
+				summary: { pass: number; warn: number; fail: number };
+			};
+			expect(parsed).toBeDefined();
+			expect(parsed.success).toBe(true);
+			expect(parsed.command).toBe("doctor");
+			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 {
+				success: boolean;
+				command: string;
+				checks: unknown[];
+				summary: { pass: number; warn: number; fail: number };
+			};
+			expect(parsed.success).toBe(true);
+			expect(parsed.command).toBe("doctor");
+			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("Agentplate 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("Agentplate 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("Agentplate 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("Agentplate Doctor");
+		});
+	});
+});

package/src/commands/doctor.ts

@@ -0,0 +1,311 @@
+/**
+ * CLI command: ap doctor [options]
+ *
+ * Runs health checks on agentplate subsystems and reports problems.
+ */
+
+import { join } from "node:path";
+import { Command } from "commander";
+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 { checkEcosystem } from "../doctor/ecosystem.ts";
+import { checkLogs } from "../doctor/logs.ts";
+import { checkMergeQueue } from "../doctor/merge-queue.ts";
+import { checkProviders } from "../doctor/providers.ts";
+import { checkServe } from "../doctor/serve.ts";
+import { checkStructure } from "../doctor/structure.ts";
+import type { DoctorCategory, DoctorCheck, DoctorCheckFn } from "../doctor/types.ts";
+import { checkVersion } from "../doctor/version.ts";
+import { checkWatchdog } from "../doctor/watchdog.ts";
+import { ValidationError } from "../errors.ts";
+import { jsonOutput } from "../json.ts";
+import { color } from "../logging/color.ts";
+import { renderHeader } from "../logging/theme.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 },
+	{ category: "ecosystem", fn: checkEcosystem },
+	{ category: "providers", fn: checkProviders },
+	{ category: "watchdog", fn: checkWatchdog },
+	{ category: "serve", fn: checkServe },
+];
+
+/**
+ * Run doctor checks and return the raw results without printing. Consumed by
+ * the web dashboard's `GET /api/doctor` endpoint. The non-serializable `fix`
+ * closures drop out automatically during JSON encoding.
+ */
+export async function collectDoctorChecks(
+	projectRoot: string,
+	category?: DoctorCategory,
+): Promise<DoctorCheck[]> {
+	const config = await loadConfig(projectRoot);
+	const agentplateDir = join(config.project.root, ".agentplate");
+	const checksToRun = category ? ALL_CHECKS.filter((c) => c.category === category) : ALL_CHECKS;
+	const results: DoctorCheck[] = [];
+	for (const { fn } of checksToRun) {
+		results.push(...(await fn(config, agentplateDir)));
+	}
+	return results;
+}
+
+/**
+ * Execute all fix functions on non-passing fixable checks.
+ * Returns a list of human-readable actions taken.
+ */
+async function applyFixes(checks: DoctorCheck[]): Promise<string[]> {
+	const fixable = checks.filter((c) => c.fixable && c.status !== "pass" && c.fix);
+	const fixed: string[] = [];
+	for (const check of fixable) {
+		if (check.fix) {
+			const actions = await check.fix();
+			fixed.push(...actions);
+		}
+	}
+	return fixed;
+}
+
+/**
+ * Format human-readable output for doctor checks.
+ */
+function printHumanReadable(
+	checks: DoctorCheck[],
+	verbose: boolean,
+	checkRegistry: Array<{ category: DoctorCategory; fn: DoctorCheckFn }>,
+	fixedItems?: string[],
+): void {
+	const w = process.stdout.write.bind(process.stdout);
+
+	w(`${renderHeader("Agentplate Doctor")}\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}]`)}\n`);
+
+		if (categoryChecks.length === 0) {
+			w(`  ${color.dim("No checks")}\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("-")
+						: check.status === "warn"
+							? color.yellow("!")
+							: color.red("x");
+
+				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}`)}\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.green(`${pass} passed`)}, ${color.yellow(`${warn} warning${warn === 1 ? "" : "s"}`)}, ${color.red(`${fail} failure${fail === 1 ? "" : "s"}`)}\n`,
+	);
+
+	if (fixedItems && fixedItems.length > 0) {
+		w(`\n${color.bold("Fixed:")}\n`);
+		for (const item of fixedItems) {
+			w(`  ${color.green("-")} ${item}\n`);
+		}
+	}
+}
+
+/**
+ * Format JSON output for doctor checks.
+ */
+function printJSON(checks: DoctorCheck[], fixed?: string[]): 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;
+
+	jsonOutput("doctor", {
+		checks,
+		summary: { pass, warn, fail },
+		...(fixed && fixed.length > 0 ? { fixed } : {}),
+	});
+}
+
+/** 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 }>;
+}
+
+interface DoctorActionOpts {
+	json?: boolean;
+	verbose?: boolean;
+	category?: string;
+	fix?: boolean;
+}
+
+/**
+ * Run the doctor checks. Returns true if any check failed.
+ * Shared by both the Commander action and the programmatic entry point so the
+ * exit-code signal never has to travel through `process.exitCode` (which is
+ * global mutable state and races with other tests in parallel bun test runs).
+ */
+async function runDoctorChecks(
+	opts: DoctorActionOpts,
+	checkRunners: Array<{ category: DoctorCategory; fn: DoctorCheckFn }>,
+): Promise<boolean> {
+	const json = opts.json ?? false;
+	const verbose = opts.verbose ?? false;
+	const categoryFilter = opts.category;
+	const fix = opts.fix ?? false;
+
+	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 agentplateDir = join(config.project.root, ".agentplate");
+
+	const checksToRun = categoryFilter
+		? checkRunners.filter((c) => c.category === categoryFilter)
+		: checkRunners;
+
+	let results: DoctorCheck[] = [];
+	for (const { fn } of checksToRun) {
+		const checkResults = await fn(config, agentplateDir);
+		results.push(...checkResults);
+	}
+
+	let fixedItems: string[] | undefined;
+	if (fix) {
+		const applied = await applyFixes(results);
+		if (applied.length > 0) {
+			fixedItems = applied;
+			results = [];
+			for (const { fn } of checksToRun) {
+				const checkResults = await fn(config, agentplateDir);
+				results.push(...checkResults);
+			}
+		}
+	}
+
+	if (json) {
+		printJSON(results, fixedItems);
+	} else {
+		printHumanReadable(results, verbose, checkRunners, fixedItems);
+	}
+
+	return results.some((c) => c.status === "fail");
+}
+
+function buildDoctorCommand(
+	onResult: (hasFailures: boolean) => void,
+	checkRunners: Array<{ category: DoctorCategory; fn: DoctorCheckFn }>,
+): Command {
+	return new Command("doctor")
+		.description("Run health checks on agentplate setup")
+		.option("--json", "Output as JSON")
+		.option("--verbose", "Show passing checks (default: only problems)")
+		.option("--category <name>", "Run only one category")
+		.option("--fix", "Attempt to auto-fix issues")
+		.addHelpText(
+			"after",
+			"\nCategories: dependencies, structure, config, databases, consistency, agents, merge, logs, version, ecosystem, providers, watchdog, serve",
+		)
+		.action(async (opts: DoctorActionOpts) => {
+			onResult(await runDoctorChecks(opts, checkRunners));
+		});
+}
+
+/**
+ * Create the Commander command for `agentplate doctor`.
+ */
+export function createDoctorCommand(options?: DoctorCommandOptions): Command {
+	return buildDoctorCommand((hasFailures) => {
+		if (hasFailures) {
+			process.exitCode = 1;
+		}
+	}, options?.checkRunners ?? ALL_CHECKS);
+}
+
+/**
+ * Entry point for `agentplate 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> {
+	let hasFailures = false;
+	const cmd = buildDoctorCommand((result) => {
+		hasFailures = result;
+	}, options?.checkRunners ?? ALL_CHECKS);
+	cmd.exitOverride();
+
+	try {
+		await cmd.parseAsync(args, { from: "user" });
+	} catch (err: unknown) {
+		if (err && typeof err === "object" && "code" in err) {
+			const code = (err as { code: string }).code;
+			if (code === "commander.helpDisplayed" || code === "commander.version") {
+				return undefined;
+			}
+		}
+		throw err;
+	}
+
+	return hasFailures ? 1 : undefined;
+}