@ag-eco/agentplate-cli 0.13.0

package/src/doctor/structure.ts

@@ -0,0 +1,285 @@
+import { access, constants, mkdir, rm, stat } 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 .agentplate/ and its subdirectories exist with correct permissions.
+ */
+export const checkStructure: DoctorCheckFn = async (
+	_config,
+	agentplateDir,
+): Promise<DoctorCheck[]> => {
+	const checks: DoctorCheck[] = [];
+
+	// Check 1: .agentplate/ directory exists
+	const agentplateDirExists = await pathExists(agentplateDir);
+	checks.push({
+		name: ".agentplate/ directory",
+		category: "structure",
+		status: agentplateDirExists ? "pass" : "fail",
+		message: agentplateDirExists ? "Directory exists" : "Directory missing",
+		details: agentplateDirExists ? undefined : ["Run 'ap init' to create it"],
+		fixable: !agentplateDirExists,
+	});
+
+	// If .agentplate/ doesn't exist, bail early
+	if (!agentplateDirExists) {
+		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(agentplateDir, 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(agentplateDir, 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,
+		fix:
+			missingDirs.length > 0
+				? async () => {
+						const actions: string[] = [];
+						for (const dir of missingDirs) {
+							const dirPath = join(agentplateDir, dir.replace(/\/$/, ""));
+							await mkdir(dirPath, { recursive: true });
+							actions.push(`Created missing directory: ${dir}`);
+						}
+						return actions;
+					}
+				: undefined,
+	});
+
+	// Check 4: .gitignore contents — validate wildcard+whitelist model
+	const gitignorePath = join(agentplateDir, ".gitignore");
+	const expectedEntries = [
+		"*",
+		"!.gitignore",
+		"!config.yaml",
+		"!agent-manifest.json",
+		"!hooks.json",
+		"!groups.json",
+		"!agent-defs/",
+		"!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,
+			fix:
+				missingEntries.length > 0
+					? async () => {
+							const actions: string[] = [];
+							const content = await Bun.file(gitignorePath).text();
+							const suffix = content.endsWith("\n") ? "" : "\n";
+							await Bun.write(gitignorePath, `${content + suffix + missingEntries.join("\n")}\n`);
+							for (const entry of missingEntries) {
+								actions.push(`Added .gitignore entry: ${entry}`);
+							}
+							return actions;
+						}
+					: undefined,
+		});
+	} 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(agentplateDir, "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(agentplateDir, "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: agentplateDir }));
+		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,
+			fix:
+				tempFiles.length > 0
+					? async () => {
+							const actions: string[] = [];
+							for (const file of tempFiles) {
+								await rm(join(agentplateDir, file), { force: true });
+								actions.push(`Removed temp file: ${file}`);
+							}
+							return actions;
+						}
+					: undefined,
+		});
+	} catch {
+		// Ignore errors scanning for temp files
+	}
+
+	// Check 7: Stale lock files (older than 5 minutes)
+	try {
+		const lockEntries = await Array.fromAsync(new Bun.Glob("*.lock").scan({ cwd: agentplateDir }));
+		const now = Date.now();
+		const staleLockThresholdMs = 5 * 60 * 1000;
+		const staleLockFiles: string[] = [];
+
+		for (const lockFile of lockEntries) {
+			try {
+				const lockPath = join(agentplateDir, lockFile);
+				const stats = await stat(lockPath);
+				const ageMs = now - stats.mtimeMs;
+				if (ageMs > staleLockThresholdMs) {
+					staleLockFiles.push(lockFile);
+				}
+			} catch {
+				// ignore stat errors
+			}
+		}
+
+		checks.push({
+			name: "Stale lock files",
+			category: "structure",
+			status: staleLockFiles.length === 0 ? "pass" : "warn",
+			message:
+				staleLockFiles.length === 0
+					? "No stale lock files found"
+					: `Found ${staleLockFiles.length} stale lock file(s)`,
+			details: staleLockFiles.length > 0 ? staleLockFiles : undefined,
+			fixable: staleLockFiles.length > 0,
+			fix:
+				staleLockFiles.length > 0
+					? async () => {
+							const actions: string[] = [];
+							for (const file of staleLockFiles) {
+								try {
+									await rm(join(agentplateDir, file), { force: true });
+									actions.push(`Removed stale lock file: ${file}`);
+								} catch {
+									// ignore removal errors
+								}
+							}
+							return actions;
+						}
+					: undefined,
+		});
+	} catch {
+		// ignore errors scanning for lock files
+	}
+
+	return checks;
+};

package/src/doctor/types.ts

@@ -0,0 +1,43 @@
+import type { AgentplateConfig } from "../types.ts";
+
+// === Doctor (Health Checks) ===
+
+/** Categories for doctor health checks. */
+export type DoctorCategory =
+	| "dependencies"
+	| "structure"
+	| "config"
+	| "databases"
+	| "consistency"
+	| "agents"
+	| "merge"
+	| "logs"
+	| "version"
+	| "ecosystem"
+	| "providers"
+	| "watchdog"
+	| "serve";
+
+/** 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 via --fix. */
+	fixable?: boolean;
+	/** Auto-fix closure — called when --fix flag is passed. Captures context at construction time. */
+	fix?: () => Promise<string[]> | string[];
+}
+
+/**
+ * Signature for a doctor check function.
+ * Each check module exports a function matching this signature.
+ * Receives the loaded config and the absolute path to .agentplate/.
+ * Returns one or more check results.
+ */
+export type DoctorCheckFn = (
+	config: AgentplateConfig,
+	agentplateDir: string,
+) => DoctorCheck[] | Promise<DoctorCheck[]>;

package/src/doctor/version.test.ts

@@ -0,0 +1,241 @@
+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 { cleanupTempDir } from "../test-helpers.ts";
+import type { AgentplateConfig } from "../types.ts";
+import { checkCurrentVersion, checkVersion, checkVersionSync } from "./version.ts";
+
+// Minimal config for testing
+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,
+	},
+};
+
+describe("checkVersion", () => {
+	test("returns checks with category version", async () => {
+		const checks = await checkVersion(mockConfig, "/tmp/.agentplate");
+
+		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/.agentplate");
+
+		const versionCheck = checks.find((c) => c.name === "version-current");
+		expect(versionCheck).toBeDefined();
+		expect(versionCheck?.status).toBeOneOf(["pass", "warn", "fail"]);
+		expect(versionCheck?.message).toContain("ap");
+	});
+
+	test("includes package-json-sync check", async () => {
+		const checks = await checkVersion(mockConfig, "/tmp/.agentplate");
+
+		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/.agentplate");
+
+		const versionCheck = checks.find((c) => c.name === "version-current");
+		expect(versionCheck).toBeDefined();
+
+		if (versionCheck?.status === "pass") {
+			// Message should contain version in format "ap vX.Y.Z"
+			expect(versionCheck.message).toMatch(/ap v\d+\.\d+\.\d+/);
+		}
+	});
+
+	test("package-json-sync check provides details", async () => {
+		const checks = await checkVersion(mockConfig, "/tmp/.agentplate");
+
+		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/version.ts
+			const detailsText = syncCheck.details?.join(" ");
+			expect(detailsText).toContain("package.json");
+			expect(detailsText).toContain("src/version.ts");
+		}
+	});
+
+	test("all checks have required DoctorCheck fields", async () => {
+		const checks = await checkVersion(mockConfig, "/tmp/.agentplate");
+
+		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");
+			}
+		}
+	});
+});
+
+describe("checkCurrentVersion", () => {
+	test("passes against real repo root", async () => {
+		// Use the real agentplate repo root (two levels up from src/doctor/)
+		const toolRoot = join(import.meta.dir, "..", "..");
+		const check = await checkCurrentVersion(toolRoot);
+		expect(check.name).toBe("version-current");
+		expect(check.category).toBe("version");
+		expect(check.status).toBe("pass");
+		expect(check.message).toMatch(/ap v\d+\.\d+\.\d+/);
+	});
+
+	test("fails for temp dir without version field", async () => {
+		const tempDir = await mkdtemp(join(tmpdir(), "version-test-"));
+		try {
+			// Write a package.json without a version field
+			await Bun.write(join(tempDir, "package.json"), JSON.stringify({ name: "test" }));
+			const check = await checkCurrentVersion(tempDir);
+			expect(check.name).toBe("version-current");
+			expect(check.status).toBe("fail");
+			expect(check.message).toContain("no version field");
+		} finally {
+			await cleanupTempDir(tempDir);
+		}
+	});
+
+	test("fails for temp dir without package.json", async () => {
+		const tempDir = await mkdtemp(join(tmpdir(), "version-test-"));
+		try {
+			const check = await checkCurrentVersion(tempDir);
+			expect(check.name).toBe("version-current");
+			expect(check.status).toBe("fail");
+		} finally {
+			await cleanupTempDir(tempDir);
+		}
+	});
+});
+
+describe("checkVersionSync", () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "version-sync-test-"));
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(tempDir);
+	});
+
+	test("passes when versions match", async () => {
+		await Bun.write(
+			join(tempDir, "package.json"),
+			JSON.stringify({ name: "test", version: "1.2.3" }),
+		);
+		const { mkdir } = await import("node:fs/promises");
+		await mkdir(join(tempDir, "src"), { recursive: true });
+		await Bun.write(
+			join(tempDir, "src", "version.ts"),
+			'const VERSION = "1.2.3";\nexport { VERSION };\n',
+		);
+
+		const check = await checkVersionSync(tempDir);
+		expect(check.name).toBe("package-json-sync");
+		expect(check.category).toBe("version");
+		expect(check.status).toBe("pass");
+		expect(check.message).toContain("synchronized");
+		expect(check.details?.join(" ")).toContain("1.2.3");
+	});
+
+	test("warns when versions mismatch", async () => {
+		await Bun.write(
+			join(tempDir, "package.json"),
+			JSON.stringify({ name: "test", version: "1.0.0" }),
+		);
+		const { mkdir } = await import("node:fs/promises");
+		await mkdir(join(tempDir, "src"), { recursive: true });
+		await Bun.write(
+			join(tempDir, "src", "version.ts"),
+			'const VERSION = "2.0.0";\nexport { VERSION };\n',
+		);
+
+		const check = await checkVersionSync(tempDir);
+		expect(check.name).toBe("package-json-sync");
+		expect(check.status).toBe("warn");
+		expect(check.message).toContain("mismatch");
+		expect(check.fixable).toBe(true);
+	});
+
+	test("warns when src/version.ts is missing", async () => {
+		await Bun.write(
+			join(tempDir, "package.json"),
+			JSON.stringify({ name: "test", version: "1.0.0" }),
+		);
+		// No src/version.ts created
+
+		const check = await checkVersionSync(tempDir);
+		expect(check.name).toBe("package-json-sync");
+		expect(check.status).toBe("warn");
+	});
+});

package/src/doctor/version.ts

@@ -0,0 +1,132 @@
+import { join } from "node:path";
+import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
+
+/**
+ * Version compatibility checks.
+ * Validates agentplate CLI version, config schema version, database schema versions.
+ */
+export const checkVersion: DoctorCheckFn = async (
+	_config,
+	_agentplateDir,
+): Promise<DoctorCheck[]> => {
+	const checks: DoctorCheck[] = [];
+
+	// Determine agentplate 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.
+ * @internal Exported for testing.
+ */
+export 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: `ap 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.
+ * @internal Exported for testing.
+ */
+export 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/version.ts and extract the VERSION constant (the single
+		// source of truth shared by every bundled bin).
+		const versionPath = join(toolRoot, "src", "version.ts");
+		const versionContent = await Bun.file(versionPath).text();
+
+		// Regex to find: const VERSION = "x.y.z" or export const VERSION = "x.y.z"
+		const versionRegex = /(?:export\s+)?const\s+VERSION\s*=\s*["']([^"']+)["']/;
+		const match = versionRegex.exec(versionContent);
+
+		if (!match?.[1]) {
+			return {
+				name: "package-json-sync",
+				category: "version",
+				status: "warn",
+				message: "Cannot find VERSION constant in src/version.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/version.ts: ${indexVersion}`],
+			};
+		}
+
+		return {
+			name: "package-json-sync",
+			category: "version",
+			status: "warn",
+			message: "Version mismatch between package.json and src/version.ts",
+			details: [`package.json: ${pkgVersion}`, `src/version.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)],
+		};
+	}
+}