@ag-eco/agentplate-cli 0.13.0

package/src/tools/loam/cli.ts

@@ -0,0 +1,278 @@
+#!/usr/bin/env bun
+
+import chalk from "chalk";
+import { Command, Option } from "commander";
+import { registerAddCommand } from "./commands/add.ts";
+import { registerArchiveCommand } from "./commands/archive.ts";
+import { registerAuditCommand } from "./commands/audit.ts";
+import { registerCompactCommand } from "./commands/compact.ts";
+import { registerCompletionsCommand } from "./commands/completions.ts";
+import { registerConfigCommand } from "./commands/config.ts";
+import { registerDeleteCommand } from "./commands/delete.ts";
+import { registerDeleteDomainCommand } from "./commands/delete-domain.ts";
+import { registerDiffCommand } from "./commands/diff.ts";
+import { registerDoctorCommand } from "./commands/doctor.ts";
+import { registerEditCommand } from "./commands/edit.ts";
+import { registerInitCommand } from "./commands/init.ts";
+import { registerLearnCommand } from "./commands/learn.ts";
+import { registerMoveCommand } from "./commands/move.ts";
+import { registerOnboardCommand } from "./commands/onboard.ts";
+import { registerOutcomeCommand } from "./commands/outcome.ts";
+import { registerPrimeCommand } from "./commands/prime.ts";
+import { registerPruneCommand } from "./commands/prune.ts";
+import { registerQueryCommand } from "./commands/query.ts";
+import { registerRankCommand } from "./commands/rank.ts";
+import { registerReadyCommand } from "./commands/ready.ts";
+import { registerRecordCommand } from "./commands/record.ts";
+import { registerRestoreCommand } from "./commands/restore.ts";
+import { registerSearchCommand } from "./commands/search.ts";
+import { registerSetupCommand } from "./commands/setup.ts";
+import { registerStatusCommand } from "./commands/status.ts";
+import { registerSyncCommand } from "./commands/sync.ts";
+import { registerUpdateCommand } from "./commands/update.ts";
+import { registerUpgradeCommand } from "./commands/upgrade.ts";
+import { registerValidateCommand } from "./commands/validate.ts";
+import { log } from "./log.ts";
+import { initRegistryFromConfig } from "./registry/init.ts";
+import { outputJsonError } from "./utils/json-output.ts";
+import { brand, muted, setQuiet } from "./utils/palette.ts";
+import { setAllowDomainMismatch, setAllowUnknownTypes } from "./utils/runtime-flags.ts";
+
+// Initialize the type registry from config so any custom_types declared in
+// loam.config.yaml are first-class. Falls back to built-ins-only when no
+// .loam/ directory exists yet (e.g., before `lm init`). Wrap any thrown
+// registry-init errors (bad custom_types config, disabled_types referencing
+// unknown types, etc.) so users see a formatted message instead of a Bun stack
+// trace from a top-level await failure.
+try {
+	await initRegistryFromConfig();
+} catch (err) {
+	const wantsJson = process.argv.includes("--json");
+	const message = (err as Error).message;
+	if (wantsJson) {
+		// In --json mode stderr must carry ONLY the machine-readable error
+		// object; a diagnostic log line would corrupt the parse. So skip the
+		// structured log here and let the JSON error stand alone.
+		outputJsonError("init", `Config error: ${message}`);
+	} else {
+		// Structured diagnostic for operators, gated behind LOAM_DEBUG so it
+		// never clutters the formatted human error below during normal use.
+		log.debug({ err: message }, "registry init from config failed");
+		process.stderr.write(`${chalk.red("Config error:")} ${message}\n`);
+		process.stderr.write(
+			chalk.dim("Edit .loam/loam.config.yaml to resolve, or run `loam doctor` for details.\n"),
+		);
+	}
+	process.exit(1);
+}
+
+export { VERSION } from "../../version.ts";
+
+import { VERSION } from "../../version.ts";
+
+const rawArgs = process.argv.slice(2);
+
+// Handle --version --json before Commander processes the flag
+if ((rawArgs.includes("-v") || rawArgs.includes("--version")) && rawArgs.includes("--json")) {
+	const platform = `${process.platform}-${process.arch}`;
+	console.log(
+		JSON.stringify({
+			name: "@ag-eco/loam-cli",
+			version: VERSION,
+			runtime: "bun",
+			platform,
+		}),
+	);
+	process.exit();
+}
+
+// Apply quiet mode early so it affects all output during command execution
+if (rawArgs.includes("--quiet") || rawArgs.includes("-q")) {
+	setQuiet(true);
+}
+
+// Apply --allow-unknown-types early so readers (which run before Commander
+// finishes parsing in some commands) consult the right runtime flag.
+if (rawArgs.includes("--allow-unknown-types")) {
+	setAllowUnknownTypes(true);
+}
+
+if (rawArgs.includes("--allow-domain-mismatch")) {
+	setAllowDomainMismatch(true);
+}
+
+// Detect --timing early (before Commander) so we can measure from startup
+const hasTiming = rawArgs.includes("--timing");
+const startTime = Date.now();
+
+const program = new Command();
+
+const COL_WIDTH = 20;
+
+program
+	.name("loam")
+	.description("Structured expertise management")
+	.showSuggestionAfterError(false)
+	.version(VERSION, "-v, --version", "Print version")
+	.option("--json", "Output as structured JSON")
+	.option("-q, --quiet", "Suppress non-error output")
+	.option("--verbose", "Show full details in output")
+	.option("--timing", "Print execution time to stderr")
+	.option(
+		"--allow-unknown-types",
+		"tolerate on-disk records of unregistered types (worktree/CI lag escape hatch)",
+	)
+	.option(
+		"--allow-domain-mismatch",
+		"tolerate records that violate per-domain allowed_types/required_fields (escape hatch for record/validate; ignored by sync)",
+	)
+	.addOption(
+		new Option(
+			"--format <format>",
+			"output format for record-rendering commands (prime, query, search)",
+		).choices(["markdown", "compact", "xml", "plain"]),
+	)
+	.configureHelp({
+		formatHelp(cmd, helper): string {
+			const lines: string[] = [];
+
+			// Header: "loam v0.6.2 — Structured expertise management"
+			lines.push(
+				`${brand.bold(cmd.name())} ${muted(`v${VERSION}`)} — Structured expertise management`,
+			);
+			lines.push("");
+
+			// Usage
+			lines.push(`Usage: ${chalk.dim(cmd.name())} <command> [options]`);
+			lines.push("");
+
+			// Commands
+			const visibleCmds = helper.visibleCommands(cmd);
+			if (visibleCmds.length > 0) {
+				lines.push("Commands:");
+				for (const sub of visibleCmds) {
+					const term = helper.subcommandTerm(sub);
+					const firstSpace = term.indexOf(" ");
+					const name = firstSpace >= 0 ? term.slice(0, firstSpace) : term;
+					const args = firstSpace >= 0 ? ` ${term.slice(firstSpace + 1)}` : "";
+					const coloredTerm = `${chalk.green(name)}${args ? chalk.dim(args) : ""}`;
+					const rawLen = term.length;
+					const padding = " ".repeat(Math.max(2, COL_WIDTH - rawLen));
+					lines.push(`  ${coloredTerm}${padding}${helper.subcommandDescription(sub)}`);
+				}
+				lines.push("");
+			}
+
+			// Options
+			const visibleOpts = helper.visibleOptions(cmd);
+			if (visibleOpts.length > 0) {
+				lines.push("Options:");
+				for (const opt of visibleOpts) {
+					const flags = helper.optionTerm(opt);
+					const padding = " ".repeat(Math.max(2, COL_WIDTH - flags.length));
+					lines.push(`  ${chalk.dim(flags)}${padding}${helper.optionDescription(opt)}`);
+				}
+				lines.push("");
+			}
+
+			// Footer
+			lines.push(`Run '${chalk.dim(cmd.name())} <command> --help' for command-specific help.`);
+
+			return `${lines.join("\n")}\n`;
+		},
+	});
+
+// Suppress the default description header (we handle it in formatHelp)
+program.addHelpCommand(false);
+
+registerInitCommand(program);
+registerAddCommand(program);
+registerRecordCommand(program);
+registerEditCommand(program);
+registerQueryCommand(program);
+registerSetupCommand(program);
+registerPrimeCommand(program);
+registerOnboardCommand(program);
+registerStatusCommand(program);
+registerValidateCommand(program);
+registerPruneCommand(program);
+registerArchiveCommand(program);
+registerRestoreCommand(program);
+registerSearchCommand(program);
+registerRankCommand(program);
+registerOutcomeCommand(program);
+registerDoctorCommand(program);
+registerReadyCommand(program);
+registerSyncCommand(program);
+registerDeleteCommand(program);
+registerDeleteDomainCommand(program);
+registerMoveCommand(program);
+registerLearnCommand(program);
+registerCompactCommand(program);
+registerConfigCommand(program);
+registerDiffCommand(program);
+registerUpdateCommand(program);
+registerUpgradeCommand(program);
+registerCompletionsCommand(program);
+registerAuditCommand(program);
+
+// --- Typo suggestions via Levenshtein distance ---
+
+function editDistance(a: string, b: string): number {
+	const m = a.length;
+	const n = b.length;
+	const dp = new Array<number>((m + 1) * (n + 1)).fill(0);
+	const idx = (i: number, j: number) => i * (n + 1) + j;
+	for (let i = 0; i <= m; i++) dp[idx(i, 0)] = i;
+	for (let j = 0; j <= n; j++) dp[idx(0, j)] = j;
+	for (let i = 1; i <= m; i++) {
+		for (let j = 1; j <= n; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			const del = (dp[idx(i - 1, j)] ?? 0) + 1;
+			const ins = (dp[idx(i, j - 1)] ?? 0) + 1;
+			const sub = (dp[idx(i - 1, j - 1)] ?? 0) + cost;
+			dp[idx(i, j)] = Math.min(del, ins, sub);
+		}
+	}
+	return dp[idx(m, n)] ?? 0;
+}
+
+function suggestCommand(input: string): string | undefined {
+	const commands = program.commands.map((c) => c.name());
+	let bestMatch: string | undefined;
+	let bestDist = 3; // Only suggest if distance <= 2
+	for (const cmd of commands) {
+		const dist = editDistance(input, cmd);
+		if (dist < bestDist) {
+			bestDist = dist;
+			bestMatch = cmd;
+		}
+	}
+	return bestMatch;
+}
+
+program.on("command:*", (operands: string[]) => {
+	const unknown = operands[0] ?? "";
+	const json = rawArgs.includes("--json");
+	const suggestion = suggestCommand(unknown);
+	if (json) {
+		outputJsonError(
+			unknown,
+			`Unknown command: ${unknown}${suggestion ? `. Did you mean '${suggestion}'?` : ""}`,
+		);
+	} else {
+		process.stderr.write(`Unknown command: ${unknown}\n`);
+		if (suggestion) {
+			process.stderr.write(`Did you mean '${suggestion}'?\n`);
+		}
+		process.stderr.write("Run 'loam --help' for usage.\n");
+	}
+	process.exitCode = 1;
+});
+
+await program.parseAsync();
+
+if (hasTiming) {
+	const elapsed = Date.now() - startTime;
+	console.error(muted(`Done in ${elapsed}ms`));
+}

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

@@ -0,0 +1,52 @@
+import { existsSync } from "node:fs";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { getExpertisePath, getLoamDir, readConfig, writeConfig } from "../utils/config.ts";
+import { createExpertiseFile } from "../utils/expertise.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+import { isQuiet } from "../utils/palette.ts";
+
+export function registerAddCommand(program: Command): void {
+	program
+		.command("add")
+		.argument("<domain>", "expertise domain to add")
+		.description("Add a new expertise domain")
+		.action(async (domain: string) => {
+			const jsonMode = program.opts().json === true;
+			const loamDir = getLoamDir();
+
+			if (!existsSync(loamDir)) {
+				if (jsonMode) {
+					outputJsonError("add", "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();
+
+			if (domain in config.domains) {
+				if (jsonMode) {
+					outputJsonError("add", `Domain "${domain}" already exists.`);
+				} else {
+					console.error(chalk.red(`Domain "${domain}" already exists.`));
+				}
+				process.exitCode = 1;
+				return;
+			}
+
+			const expertisePath = getExpertisePath(domain);
+			await createExpertiseFile(expertisePath);
+
+			config.domains[domain] = {};
+			await writeConfig(config);
+
+			if (jsonMode) {
+				outputJson({ success: true, command: "add", domain });
+			} else if (!isQuiet()) {
+				console.log(chalk.green(`Added domain "${domain}".`));
+			}
+		});
+}

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

@@ -0,0 +1,214 @@
+import chalk from "chalk";
+import type { Command } from "commander";
+import type { ExpertiseRecord } from "../schemas/record.ts";
+import { archiveRecords } from "../utils/archive.ts";
+import { getExpertisePath, readConfig } from "../utils/config.ts";
+import { readExpertiseFile, resolveRecordId, writeExpertiseFile } from "../utils/expertise.ts";
+import { getRecordSummary } from "../utils/format.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+import { withFileLock } from "../utils/lock.ts";
+import { accent, brand, isQuiet } from "../utils/palette.ts";
+
+interface ArchivedRecordInfo {
+	id: string | null;
+	type: string;
+	summary: string;
+	reason: string;
+}
+
+function buildArchivedInfo(record: ExpertiseRecord, reason: string): ArchivedRecordInfo {
+	return {
+		id: record.id ?? null,
+		type: record.type,
+		summary: getRecordSummary(record),
+		reason,
+	};
+}
+
+function printArchivedRecord(
+	record: ExpertiseRecord,
+	domain: string,
+	reason: string,
+	dryRun: boolean,
+): void {
+	const prefix = dryRun ? `${chalk.yellow("[DRY RUN]")} ` : "";
+	const verb = dryRun ? "Would archive" : "Archived";
+	const rid = record.id ? ` ${accent(record.id)}` : "";
+	console.log(
+		`${prefix}${brand(`${verb} ${record.type}`)}${rid} ${brand(`from ${domain}`)} (${reason}): ${getRecordSummary(record)}`,
+	);
+}
+
+export function registerArchiveCommand(program: Command): void {
+	program
+		.command("archive")
+		.argument("<domain>", "expertise domain")
+		.argument("[id]", "record ID (e.g. mx-abc123, abc123, or abc)")
+		.description(
+			"Soft-archive one or more live records (symmetric to `lm restore`; pairs with `lm prune` for bulk decay)",
+		)
+		.option("--records <ids>", "comma-separated list of record IDs to archive")
+		.requiredOption("--reason <text>", "why this record is being archived (required, free-text)")
+		.option("--dry-run", "preview what would be archived without making changes", false)
+		.action(
+			async (
+				domain: string,
+				id: string | undefined,
+				options: { records?: string; reason: string; dryRun: boolean },
+			) => {
+				const jsonMode = program.opts().json === true;
+				try {
+					const config = await readConfig();
+
+					if (!(domain in config.domains)) {
+						const available = Object.keys(config.domains).join(", ") || "(none)";
+						if (jsonMode) {
+							outputJsonError(
+								"archive",
+								`Domain "${domain}" not found in config. Available domains: ${available}`,
+							);
+						} else {
+							console.error(chalk.red(`Error: domain "${domain}" not found in config.`));
+							console.error(chalk.red(`Available domains: ${available}`));
+						}
+						process.exitCode = 1;
+						return;
+					}
+
+					const reasonText = options.reason.trim();
+					if (reasonText.length === 0) {
+						if (jsonMode) {
+							outputJsonError("archive", "--reason must not be empty.");
+						} else {
+							console.error(chalk.red("Error: --reason must not be empty."));
+						}
+						process.exitCode = 1;
+						return;
+					}
+
+					const hasId = id !== undefined;
+					const hasRecords = options.records !== undefined;
+					const modeCount = [hasId, hasRecords].filter(Boolean).length;
+
+					if (modeCount === 0) {
+						if (jsonMode) {
+							outputJsonError("archive", "Must provide a record ID or --records.");
+						} else {
+							console.error(chalk.red("Error: must provide a record ID or --records."));
+						}
+						process.exitCode = 1;
+						return;
+					}
+
+					if (modeCount > 1) {
+						if (jsonMode) {
+							outputJsonError(
+								"archive",
+								"Cannot combine a record ID with --records. Use only one mode.",
+							);
+						} else {
+							console.error(
+								chalk.red("Error: cannot combine a record ID with --records. Use only one mode."),
+							);
+						}
+						process.exitCode = 1;
+						return;
+					}
+
+					const rawIds: string[] = hasRecords
+						? (options.records as string)
+								.split(",")
+								.map((s) => s.trim())
+								.filter(Boolean)
+						: [id as string];
+
+					if (rawIds.length === 0) {
+						if (jsonMode) {
+							outputJsonError("archive", "--records requires at least one ID.");
+						} else {
+							console.error(chalk.red("Error: --records requires at least one ID."));
+						}
+						process.exitCode = 1;
+						return;
+					}
+
+					const stampedReason = `manual: ${reasonText}`;
+					const filePath = getExpertisePath(domain);
+
+					// Resolve + remove from live under the live-file lock so concurrent
+					// writers don't lose data between read and write. Archive write
+					// happens after the live write (mirrors `lm prune` phase 3).
+					const lockResult = await withFileLock(filePath, async () => {
+						const records = await readExpertiseFile(filePath);
+						const toArchiveIndices = new Set<number>();
+
+						for (const rawId of rawIds) {
+							const resolved = resolveRecordId(records, rawId);
+							if (!resolved.ok) {
+								return { ok: false as const, error: resolved.error };
+							}
+							toArchiveIndices.add(resolved.index);
+						}
+
+						const archived = records.filter((_, i) => toArchiveIndices.has(i));
+						const kept = records.filter((_, i) => !toArchiveIndices.has(i));
+
+						if (!options.dryRun) {
+							await writeExpertiseFile(filePath, kept);
+						}
+
+						return { ok: true as const, archived, kept };
+					});
+
+					if (!lockResult.ok) {
+						if (jsonMode) {
+							outputJsonError("archive", lockResult.error);
+						} else {
+							console.error(chalk.red(`Error: ${lockResult.error}`));
+						}
+						process.exitCode = 1;
+						return;
+					}
+
+					const { archived, kept } = lockResult;
+
+					if (!options.dryRun && archived.length > 0) {
+						await archiveRecords(domain, archived, new Date(), stampedReason);
+					}
+
+					if (jsonMode) {
+						outputJson({
+							success: true,
+							command: "archive",
+							domain,
+							dryRun: options.dryRun,
+							archived: archived.map((r) => buildArchivedInfo(r, stampedReason)),
+							kept: kept.length,
+						});
+					} else if (!isQuiet()) {
+						for (const r of archived) {
+							printArchivedRecord(r, domain, stampedReason, options.dryRun);
+						}
+						if (!options.dryRun && archived.length > 1) {
+							console.log(brand(`✓ Archived ${archived.length} records from ${domain}`));
+						}
+					}
+				} catch (err) {
+					if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+						if (jsonMode) {
+							outputJsonError("archive", "No .loam/ directory found. Run `loam init` first.");
+						} else {
+							console.error(chalk.red("Error: No .loam/ directory found. Run `loam init` first."));
+						}
+					} else {
+						if (jsonMode) {
+							outputJsonError("archive", (err as Error).message);
+						} else {
+							console.error(chalk.red(`Error: ${(err as Error).message}`));
+						}
+					}
+					process.exitCode = 1;
+				}
+			},
+		);
+}