@ag-eco/agentplate-cli 0.13.0

package/src/tools/loam/commands/status.ts

@@ -0,0 +1,103 @@
+import { existsSync } from "node:fs";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { getExpertisePath, getLoamDir, readConfig } from "../utils/config.ts";
+import {
+	calculateDomainHealth,
+	countRecords,
+	getFileModTime,
+	readExpertiseFile,
+} from "../utils/expertise.ts";
+import { formatStatusOutput } from "../utils/format.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+
+export function registerStatusCommand(program: Command): void {
+	program
+		.command("status")
+		.description("Show status of expertise records")
+		.action(async () => {
+			const jsonMode = program.opts().json === true;
+			const loamDir = getLoamDir();
+
+			if (!existsSync(loamDir)) {
+				if (jsonMode) {
+					outputJsonError("status", "No .loam/ directory found. Run `loam init` first.");
+				} else {
+					console.error(chalk.red("No .loam/ directory found. Run `loam init` first."));
+				}
+				process.exitCode = 1;
+				return;
+			}
+
+			const config = await readConfig();
+			const observationalShelfLifeDays = config.classification_defaults.shelf_life.observational;
+			const now = Date.now();
+
+			const domainStats = await Promise.all(
+				Object.keys(config.domains).map(async (domain) => {
+					const filePath = getExpertisePath(domain);
+					const records = await readExpertiseFile(filePath);
+					const lastUpdated = await getFileModTime(filePath);
+					const health = calculateDomainHealth(
+						records,
+						config.governance.max_entries,
+						config.classification_defaults.shelf_life,
+					);
+					const oldestRecorded = health.oldest_timestamp ? new Date(health.oldest_timestamp) : null;
+					const newestRecorded = health.newest_timestamp ? new Date(health.newest_timestamp) : null;
+					let rotting = false;
+					let rottingDays: number | null = null;
+					if (newestRecorded) {
+						const ageDays = Math.floor((now - newestRecorded.getTime()) / 86400000);
+						if (ageDays > observationalShelfLifeDays) {
+							rotting = true;
+							rottingDays = ageDays;
+						}
+					}
+					return {
+						domain,
+						count: countRecords(records),
+						lastUpdated,
+						oldestRecorded,
+						newestRecorded,
+						rotting,
+						rottingDays,
+						health,
+					};
+				}),
+			);
+
+			if (jsonMode) {
+				outputJson({
+					success: true,
+					command: "status",
+					domains: domainStats.map((s) => ({
+						domain: s.domain,
+						count: s.count,
+						lastUpdated: s.lastUpdated?.toISOString() ?? null,
+						oldest_recorded: s.oldestRecorded?.toISOString() ?? null,
+						newest_recorded: s.newestRecorded?.toISOString() ?? null,
+						rotting: s.rotting,
+						rotting_days: s.rottingDays,
+						health: s.health,
+					})),
+					governance: config.governance,
+					shelf_life: config.classification_defaults.shelf_life,
+				});
+			} else {
+				const output = formatStatusOutput(
+					domainStats.map((s) => ({
+						domain: s.domain,
+						count: s.count,
+						lastUpdated: s.lastUpdated,
+						oldestRecorded: s.oldestRecorded,
+						newestRecorded: s.newestRecorded,
+						rotting: s.rotting,
+						rottingDays: s.rottingDays,
+					})),
+					config.governance,
+				);
+				console.log(output);
+			}
+		});
+}

package/src/tools/loam/commands/sync.ts

@@ -0,0 +1,298 @@
+import { execFileSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { initRegistryFromConfig } from "../registry/init.ts";
+import { getRegistry } from "../registry/type-registry.ts";
+import { getExpertisePath, isInsideWorktree, readConfig } from "../utils/config.ts";
+import {
+	findMissingDomainFields,
+	getAllowedTypes,
+	getRequiredFields,
+} from "../utils/domain-rules.ts";
+import { applyAliases } from "../utils/expertise.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+import { brand, isQuiet } from "../utils/palette.ts";
+
+function isGitRepo(cwd: string): boolean {
+	try {
+		execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+			cwd,
+			stdio: "pipe",
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function gitHasChanges(cwd: string): boolean {
+	try {
+		const status = execFileSync("git", ["status", "--porcelain", ".loam/"], {
+			cwd,
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		});
+		return status.trim().length > 0;
+	} catch {
+		return false;
+	}
+}
+
+function gitAdd(cwd: string): void {
+	execFileSync("git", ["add", ".loam/"], { cwd, stdio: "pipe" });
+}
+
+function gitCommit(cwd: string, message: string): string {
+	return execFileSync("git", ["commit", "-m", message], {
+		cwd,
+		encoding: "utf-8",
+		stdio: ["pipe", "pipe", "pipe"],
+	});
+}
+
+interface ValidateResult {
+	valid: boolean;
+	totalRecords: number;
+	errors: Array<{ domain: string; line: number; message: string }>;
+}
+
+async function validateExpertise(cwd?: string): Promise<ValidateResult> {
+	// Re-init registry from on-disk config so sync validates against the user's
+	// current types — important for worktree/CI lag where JSONL (merge=union)
+	// can land before loam.config.yaml does. Once config catches up, sync
+	// reconciles correctly without needing a restart.
+	await initRegistryFromConfig(cwd);
+	const config = await readConfig(cwd);
+	const domains = Object.keys(config.domains);
+
+	const registry = getRegistry();
+	const validate = registry.validator;
+
+	let totalRecords = 0;
+	const errors: Array<{ domain: string; line: number; message: string }> = [];
+
+	for (const domain of domains) {
+		const filePath = getExpertisePath(domain, cwd);
+		// Resolve domain rules from the just-reloaded config so worktree/CI lag
+		// (records landing before config) is caught once config catches up.
+		// Sync intentionally ignores --allow-domain-mismatch — like
+		// --allow-unknown-types, escape hatches stop at the commit gate.
+		const allowedTypes = getAllowedTypes(config, domain);
+		const requiredFields = getRequiredFields(config, domain);
+		let content: string;
+		try {
+			content = await readFile(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+
+		const lines = content.split("\n");
+		for (let i = 0; i < lines.length; i++) {
+			const line = (lines[i] ?? "").trim();
+			if (line.length === 0) continue;
+			totalRecords++;
+			const lineNumber = i + 1;
+
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(line);
+			} catch {
+				errors.push({
+					domain,
+					line: lineNumber,
+					message: "Invalid JSON: failed to parse",
+				});
+				continue;
+			}
+
+			// Targeted unknown-type error + alias resolution before Ajv. Sync
+			// intentionally ignores --allow-unknown-types — its job is to
+			// gatekeep commits.
+			if (parsed && typeof parsed === "object" && "type" in parsed) {
+				const t = (parsed as { type: unknown }).type;
+				if (typeof t === "string") {
+					const def = registry.get(t);
+					if (!def) {
+						const id = (parsed as { id?: unknown }).id;
+						const idPart = typeof id === "string" ? ` (id=${id})` : "";
+						errors.push({
+							domain,
+							line: lineNumber,
+							message: `Unknown record type "${t}"${idPart}. Register it under custom_types in loam.config.yaml or remove the record.`,
+						});
+						continue;
+					}
+					if (def.aliases) applyAliases(parsed as Record<string, unknown>, def.aliases);
+				}
+			}
+
+			if (!validate(parsed)) {
+				const schemaErrors = (validate.errors ?? [])
+					.map((err) => `${err.instancePath} ${err.message}`)
+					.join("; ");
+				errors.push({
+					domain,
+					line: lineNumber,
+					message: `Schema validation failed: ${schemaErrors}`,
+				});
+				continue;
+			}
+
+			if (parsed && typeof parsed === "object") {
+				const record = parsed as Record<string, unknown>;
+				const recordType = typeof record.type === "string" ? record.type : "<unknown>";
+				const id = typeof record.id === "string" ? record.id : null;
+				const idPart = id ? ` (id=${id})` : "";
+
+				if (allowedTypes && !allowedTypes.includes(recordType)) {
+					errors.push({
+						domain,
+						line: lineNumber,
+						message: `type "${recordType}"${idPart} is not allowed in domain "${domain}". Allowed types: ${allowedTypes.join(", ")}. Fix the record or relax allowed_types in loam.config.yaml.`,
+					});
+					continue;
+				}
+
+				if (requiredFields) {
+					const missing = findMissingDomainFields(record, requiredFields);
+					if (missing.length > 0) {
+						errors.push({
+							domain,
+							line: lineNumber,
+							message: `record${idPart} missing required field(s) ${missing.map((f) => `"${f}"`).join(", ")} in domain "${domain}". Fix the record or relax required_fields in loam.config.yaml.`,
+						});
+					}
+				}
+			}
+		}
+	}
+
+	return { valid: errors.length === 0, totalRecords, errors };
+}
+
+export function registerSyncCommand(program: Command): void {
+	program
+		.command("sync")
+		.description("Validate, stage, and commit .loam/ changes")
+		.option("--message <message>", "custom commit message")
+		.option("--no-validate", "skip validation step")
+		.action(async (options: { message?: string; validate?: boolean }) => {
+			const jsonMode = program.opts().json === true;
+			const cwd = process.cwd();
+
+			// Check if we're in a git repo
+			if (!isGitRepo(cwd)) {
+				if (jsonMode) {
+					outputJsonError(
+						"sync",
+						"Not in a git repository. Run this command from within a git repository.",
+					);
+				} else {
+					console.error(chalk.red("Error: not in a git repository."));
+				}
+				process.exitCode = 1;
+				return;
+			}
+
+			// Validate (unless --no-validate)
+			if (options.validate !== false) {
+				try {
+					const result = await validateExpertise();
+					if (!result.valid) {
+						if (jsonMode) {
+							outputJson({
+								success: false,
+								command: "sync",
+								validated: false,
+								committed: false,
+								errors: result.errors,
+							});
+						} else {
+							console.error(chalk.red("Validation failed:"));
+							for (const err of result.errors) {
+								console.error(chalk.red(`  ${err.domain}:${err.line} - ${err.message}`));
+							}
+							console.error(chalk.red("\nFix errors and retry, or use --no-validate to skip."));
+						}
+						process.exitCode = 1;
+						return;
+					}
+					if (!jsonMode && !isQuiet()) {
+						console.log(`${brand("✓")} ${brand(`Validated ${result.totalRecords} records`)}`);
+					}
+				} catch (err) {
+					if (jsonMode) {
+						outputJsonError("sync", `Validation error: ${(err as Error).message}`);
+					} else {
+						console.error(chalk.red(`Validation error: ${(err as Error).message}`));
+					}
+					process.exitCode = 1;
+					return;
+				}
+			}
+
+			// Skip commit if inside a worktree — .loam/ changes belong to the main repo
+			if (isInsideWorktree(cwd)) {
+				if (jsonMode) {
+					outputJson({
+						success: true,
+						command: "sync",
+						validated: options.validate !== false,
+						committed: false,
+						message:
+							"Skipped commit: running inside a git worktree. Changes are written to the main repo's .loam/.",
+					});
+				} else {
+					if (!isQuiet())
+						console.log(
+							`${brand("ℹ")} Skipped commit: running inside a git worktree. Changes are written to the main repo's .loam/.`,
+						);
+				}
+				return;
+			}
+
+			// Check for changes
+			if (!gitHasChanges(cwd)) {
+				if (jsonMode) {
+					outputJson({
+						success: true,
+						command: "sync",
+						validated: options.validate !== false,
+						committed: false,
+						message: "No changes to commit",
+					});
+				} else {
+					if (!isQuiet()) console.log("No .loam/ changes to commit.");
+				}
+				return;
+			}
+
+			// Git add + commit
+			const commitMessage = options.message ?? "loam: update expertise";
+			try {
+				gitAdd(cwd);
+				gitCommit(cwd, commitMessage);
+
+				if (jsonMode) {
+					outputJson({
+						success: true,
+						command: "sync",
+						validated: options.validate !== false,
+						committed: true,
+						message: commitMessage,
+					});
+				} else {
+					if (!isQuiet())
+						console.log(`${brand("✓")} ${brand(`Committed .loam/ changes: "${commitMessage}"`)}`);
+				}
+			} catch (err) {
+				if (jsonMode) {
+					outputJsonError("sync", `Git error: ${(err as Error).message}`);
+				} else {
+					console.error(chalk.red(`Git error: ${(err as Error).message}`));
+				}
+				process.exitCode = 1;
+			}
+		});
+}

package/src/tools/loam/commands/update.ts

@@ -0,0 +1,19 @@
+import type { Command } from "commander";
+import { outputJsonError } from "../utils/json-output.ts";
+import { printWarning } from "../utils/palette.ts";
+
+export function registerUpdateCommand(program: Command): void {
+	program
+		.command("update", { hidden: true })
+		.description("Deprecated: use 'upgrade' instead")
+		.option("--check", "only check for updates, do not install")
+		.action(async () => {
+			const jsonMode = program.opts().json === true;
+			if (jsonMode) {
+				outputJsonError("update", "'loam update' is deprecated. Use 'loam upgrade' instead.");
+			} else {
+				printWarning("'loam update' is deprecated. Use 'loam upgrade' instead.");
+			}
+			process.exitCode = 1;
+		});
+}

package/src/tools/loam/commands/upgrade.ts

@@ -0,0 +1,93 @@
+import type { Command } from "commander";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+import { printError, printSuccess, printWarning } from "../utils/palette.ts";
+import { compareSemver, getCurrentVersion, getLatestVersion } from "../utils/version.ts";
+
+const PACKAGE_NAME = "@ag-eco/loam-cli";
+
+export function registerUpgradeCommand(program: Command): void {
+	program
+		.command("upgrade")
+		.description("Upgrade loam to the latest version")
+		.option("--check", "Check for updates without installing")
+		.action(async (options: { check?: boolean }) => {
+			const jsonMode = program.opts().json === true;
+
+			const latest = getLatestVersion();
+			if (latest === null) {
+				if (jsonMode) {
+					outputJsonError(
+						"upgrade",
+						"Unable to reach npm registry. Check your internet connection.",
+					);
+				} else {
+					printError("Failed to check for updates: Unable to reach npm registry");
+				}
+				process.exitCode = 1;
+				return;
+			}
+
+			const current = getCurrentVersion();
+			const upToDate = compareSemver(current, latest) >= 0;
+
+			if (upToDate) {
+				if (jsonMode) {
+					outputJson({
+						success: true,
+						command: "upgrade",
+						current,
+						latest,
+						upToDate: true,
+						updated: false,
+					});
+				} else {
+					printSuccess(`loam is up to date (v${current})`);
+				}
+				return;
+			}
+
+			if (options.check) {
+				if (jsonMode) {
+					outputJson({
+						success: true,
+						command: "upgrade",
+						current,
+						latest,
+						upToDate: false,
+						updated: false,
+					});
+				} else {
+					printWarning(`Update available: v${current} → v${latest}`);
+				}
+				return;
+			}
+
+			const result = Bun.spawnSync(["bun", "install", "-g", `${PACKAGE_NAME}@latest`], {
+				stdout: jsonMode ? "pipe" : "inherit",
+				stderr: jsonMode ? "pipe" : "inherit",
+			});
+
+			if (result.exitCode !== 0) {
+				if (jsonMode) {
+					outputJsonError("upgrade", `bun install failed with exit code ${result.exitCode}`);
+				} else {
+					printError(`Failed to upgrade: bun install failed with exit code ${result.exitCode}`);
+				}
+				process.exitCode = 1;
+				return;
+			}
+
+			if (jsonMode) {
+				outputJson({
+					success: true,
+					command: "upgrade",
+					current,
+					latest,
+					upToDate: false,
+					updated: true,
+				});
+			} else {
+				printSuccess(`Updated loam v${current} → v${latest}`);
+			}
+		});
+}

package/src/tools/loam/commands/validate.ts

@@ -0,0 +1,190 @@
+import { readFile } from "node:fs/promises";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { getRegistry } from "../registry/type-registry.ts";
+import { getExpertisePath, readConfig } from "../utils/config.ts";
+import {
+	findMissingDomainFields,
+	getAllowedTypes,
+	getRequiredFields,
+} from "../utils/domain-rules.ts";
+import { applyAliases } from "../utils/expertise.ts";
+import { outputJson } from "../utils/json-output.ts";
+import { isAllowDomainMismatch, isAllowUnknownTypes } from "../utils/runtime-flags.ts";
+
+export function registerValidateCommand(program: Command): void {
+	program
+		.command("validate")
+		.description("Validate expertise records against schemas")
+		.action(async () => {
+			const jsonMode = program.opts().json === true;
+			const config = await readConfig();
+			const domains = Object.keys(config.domains);
+
+			const registry = getRegistry();
+			const validate = registry.validator;
+			const allowUnknown = isAllowUnknownTypes();
+			const allowDomainMismatch = isAllowDomainMismatch();
+
+			let totalRecords = 0;
+			let totalErrors = 0;
+			let totalWarnings = 0;
+			const errors: Array<{ domain: string; line: number; message: string }> = [];
+			const warnings: Array<{ domain: string; line: number; message: string }> = [];
+
+			for (const domain of domains) {
+				const filePath = getExpertisePath(domain);
+				let content: string;
+				try {
+					content = await readFile(filePath, "utf-8");
+				} catch {
+					// File doesn't exist yet, skip
+					continue;
+				}
+
+				const allowedTypes = getAllowedTypes(config, domain);
+				const requiredFields = getRequiredFields(config, domain);
+
+				const lines = content.split("\n");
+				for (let i = 0; i < lines.length; i++) {
+					const line = (lines[i] ?? "").trim();
+					if (line.length === 0) continue;
+
+					totalRecords++;
+					const lineNumber = i + 1;
+
+					let parsed: unknown;
+					try {
+						parsed = JSON.parse(line);
+					} catch {
+						totalErrors++;
+						const msg = "Invalid JSON: failed to parse";
+						errors.push({ domain, line: lineNumber, message: msg });
+						if (!jsonMode) {
+							console.error(chalk.red(`${domain}:${lineNumber} - ${msg}`));
+						}
+						continue;
+					}
+
+					// Targeted unknown-type error + alias resolution. Ajv runs against
+					// the canonical (post-alias) shape, otherwise records with a
+					// legacy field name (e.g. before a schema rename) would fail
+					// validation. --allow-unknown-types skips both the targeted
+					// error AND the downstream Ajv check for unregistered types.
+					if (parsed !== null && typeof parsed === "object" && "type" in parsed) {
+						const t = (parsed as { type: unknown }).type;
+						if (typeof t === "string") {
+							const def = registry.get(t);
+							if (!def) {
+								if (allowUnknown) continue;
+								totalErrors++;
+								const id = (parsed as { id?: unknown }).id;
+								const idPart = typeof id === "string" ? ` (id=${id})` : "";
+								const msg = `Unknown record type "${t}"${idPart}. Register it under custom_types in loam.config.yaml or remove the record.`;
+								errors.push({ domain, line: lineNumber, message: msg });
+								if (!jsonMode) {
+									console.error(chalk.red(`${domain}:${lineNumber} - ${msg}`));
+								}
+								continue;
+							}
+							if (def.aliases) applyAliases(parsed as Record<string, unknown>, def.aliases);
+						}
+					}
+
+					// Detect legacy singular "outcome" field — warn, don't error
+					if (
+						parsed !== null &&
+						typeof parsed === "object" &&
+						"outcome" in parsed &&
+						!("outcomes" in parsed)
+					) {
+						totalWarnings++;
+						const msg =
+							'Legacy "outcome" field (singular); run `loam doctor --fix` to migrate to "outcomes[]"';
+						warnings.push({ domain, line: lineNumber, message: msg });
+						if (!jsonMode) {
+							console.error(chalk.yellow(`${domain}:${lineNumber} - ${msg}`));
+						}
+					} else if (!validate(parsed)) {
+						totalErrors++;
+						const schemaErrors = (validate.errors ?? [])
+							.map((err) => `${err.instancePath} ${err.message}`)
+							.join("; ");
+						const msg = `Schema validation failed: ${schemaErrors}`;
+						errors.push({ domain, line: lineNumber, message: msg });
+						if (!jsonMode) {
+							console.error(chalk.red(`${domain}:${lineNumber} - Schema validation failed:`));
+							for (const err of validate.errors ?? []) {
+								console.error(chalk.red(`  ${err.instancePath} ${err.message}`));
+							}
+						}
+						continue;
+					}
+
+					// Per-domain rule checks. --allow-domain-mismatch skips these,
+					// matching the worktree/CI lag escape hatch pattern. Sync ignores
+					// the flag; validate honors it because validate is read-only and
+					// useful pre-config-catch-up.
+					if (
+						!allowDomainMismatch &&
+						parsed !== null &&
+						typeof parsed === "object" &&
+						(allowedTypes !== null || requiredFields !== null)
+					) {
+						const record = parsed as Record<string, unknown>;
+						const recordType = typeof record.type === "string" ? record.type : "<unknown>";
+						const recId = typeof record.id === "string" ? record.id : null;
+						const idPart = recId ? ` (id=${recId})` : "";
+
+						if (allowedTypes && !allowedTypes.includes(recordType)) {
+							totalErrors++;
+							const msg = `type "${recordType}"${idPart} is not allowed in domain "${domain}". Allowed types: ${allowedTypes.join(", ")}.`;
+							errors.push({ domain, line: lineNumber, message: msg });
+							if (!jsonMode) {
+								console.error(chalk.red(`${domain}:${lineNumber} - ${msg}`));
+							}
+						}
+
+						if (requiredFields) {
+							const missing = findMissingDomainFields(record, requiredFields);
+							if (missing.length > 0) {
+								totalErrors++;
+								const msg = `record${idPart} missing required field(s) ${missing.map((f) => `"${f}"`).join(", ")} in domain "${domain}".`;
+								errors.push({ domain, line: lineNumber, message: msg });
+								if (!jsonMode) {
+									console.error(chalk.red(`${domain}:${lineNumber} - ${msg}`));
+								}
+							}
+						}
+					}
+				}
+			}
+
+			if (jsonMode) {
+				outputJson({
+					success: totalErrors === 0,
+					command: "validate",
+					valid: totalErrors === 0,
+					totalRecords,
+					totalErrors,
+					totalWarnings,
+					errors,
+					warnings,
+				});
+			} else if (totalErrors > 0) {
+				console.log(chalk.red(`${totalRecords} records validated, ${totalErrors} errors found`));
+			} else if (totalWarnings > 0) {
+				console.log(
+					chalk.yellow(
+						`${totalRecords} records validated, ${totalErrors} errors found, ${totalWarnings} warning(s)`,
+					),
+				);
+			} else {
+				console.log(chalk.green(`${totalRecords} records validated, ${totalErrors} errors found`));
+			}
+
+			if (totalErrors > 0) {
+				process.exitCode = 1;
+			}
+		});
+}