@ag-eco/agentplate-cli 0.13.0

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

@@ -0,0 +1,166 @@
+import chalk from "chalk";
+import type { Command } from "commander";
+import type { ExpertiseRecord } from "../schemas/record.ts";
+import {
+	archiveRecords,
+	getArchivePath,
+	readArchiveFile,
+	removeFromArchive,
+	restoreToExpertise,
+	stripArchiveFields,
+} from "../utils/archive.ts";
+import { getExpertisePath, readConfig } from "../utils/config.ts";
+import { readExpertiseFile, resolveRecordId } from "../utils/expertise.ts";
+import { getRecordSummary } from "../utils/format.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+import { accent, brand, isQuiet } from "../utils/palette.ts";
+
+export function registerRestoreCommand(program: Command): void {
+	program
+		.command("restore")
+		.argument("<id>", "archived record ID (e.g. mx-abc123, abc123, or abc)")
+		.description("Restore a soft-archived record from .loam/archive/ back to live expertise")
+		.action(async (id: string) => {
+			const jsonMode = program.opts().json === true;
+			try {
+				const config = await readConfig();
+
+				// Search every archive file for the record id. Records carry no
+				// domain field, so we have to scan domain by domain. The id space
+				// is sha-derived and effectively unique, so collisions across
+				// domain archives are vanishingly rare; surface them as an error
+				// when they do happen.
+				const matches: Array<{ domain: string; record: ExpertiseRecord }> = [];
+				for (const domain of Object.keys(config.domains)) {
+					const archivePath = getArchivePath(domain);
+					const records = await readArchiveFile(archivePath);
+					const resolved = resolveRecordId(records, id);
+					if (resolved.ok) {
+						matches.push({ domain, record: resolved.record });
+					}
+				}
+
+				if (matches.length === 0) {
+					const msg = `Archived record "${id}" not found in any domain. Run \`lm search --archived <query>\` to browse archives.`;
+					if (jsonMode) {
+						outputJsonError("restore", msg);
+					} else {
+						console.error(chalk.red(`Error: ${msg}`));
+					}
+					process.exitCode = 1;
+					return;
+				}
+
+				if (matches.length > 1) {
+					const where = matches.map((m) => `${m.domain} (${m.record.id})`).join(", ");
+					const msg = `Identifier "${id}" matches archived records in multiple domains: ${where}. Use a longer prefix.`;
+					if (jsonMode) {
+						outputJsonError("restore", msg);
+					} else {
+						console.error(chalk.red(`Error: ${msg}`));
+					}
+					process.exitCode = 1;
+					return;
+				}
+
+				const target = matches[0];
+				if (!target) return;
+				const { domain, record } = target;
+				const recordId = record.id;
+				if (!recordId) {
+					const msg = `Archived record has no id; cannot restore safely.`;
+					if (jsonMode) {
+						outputJsonError("restore", msg);
+					} else {
+						console.error(chalk.red(`Error: ${msg}`));
+					}
+					process.exitCode = 1;
+					return;
+				}
+
+				// Pre-check: refuse to restore over an existing live id BEFORE touching
+				// the archive. Race-safe re-check happens inside restoreToExpertise
+				// under the live file's lock; if that catches a duplicate we'll roll
+				// the archive back below.
+				const expertisePath = getExpertisePath(domain);
+				const liveExisting = await readExpertiseFile(expertisePath);
+				const livePreConflict = liveExisting.find((r) => r.id === recordId);
+				if (livePreConflict) {
+					const msg = `Live record "${recordId}" already exists in domain "${domain}" (classification: ${livePreConflict.classification}). Delete or rename the live record before restoring, or run \`lm search --archived ${recordId}\` to inspect the archived copy.`;
+					if (jsonMode) {
+						outputJsonError("restore", msg);
+					} else {
+						console.error(chalk.red(`Error: ${msg}`));
+					}
+					process.exitCode = 1;
+					return;
+				}
+
+				const removed = await removeFromArchive(domain, recordId);
+				if (!removed) {
+					const msg = `Archived record "${recordId}" disappeared between read and write (concurrent restore?).`;
+					if (jsonMode) {
+						outputJsonError("restore", msg);
+					} else {
+						console.error(chalk.red(`Error: ${msg}`));
+					}
+					process.exitCode = 1;
+					return;
+				}
+
+				// Capture the original archive_reason BEFORE stripping so we can
+				// surface it in the success line and preserve it on a rollback
+				// re-archive. Archives written before loam-b41a have no reason
+				// on disk — fall back to "manual" so the field is always set.
+				const originalReason = removed.archive_reason ?? "manual";
+				const live = stripArchiveFields(removed);
+				const restoreRes = await restoreToExpertise(expertisePath, live);
+				if (!restoreRes.ok) {
+					// Race lost between pre-check and lock. Roll the archive back so
+					// the record isn't stranded. Preserve the original archive_reason
+					// so the round-trip is invisible to anyone reading the archive.
+					await archiveRecords(domain, [stripArchiveFields(removed)], new Date(), originalReason);
+					const msg = `Live record "${recordId}" appeared in domain "${domain}" while restore was in flight (classification: ${restoreRes.conflict.classification}). Re-archived; nothing changed.`;
+					if (jsonMode) {
+						outputJsonError("restore", msg);
+					} else {
+						console.error(chalk.red(`Error: ${msg}`));
+					}
+					process.exitCode = 1;
+					return;
+				}
+
+				if (jsonMode) {
+					outputJson({
+						success: true,
+						command: "restore",
+						domain,
+						id: live.id ?? null,
+						type: live.type,
+						summary: getRecordSummary(live),
+						archive_reason: originalReason,
+					});
+				} else if (!isQuiet()) {
+					const rid = live.id ? ` ${accent(live.id)}` : "";
+					console.log(
+						`${brand("✓")} ${brand(`Restored ${live.type}`)}${rid} ${brand(`to ${domain}`)} (archived: ${originalReason}): ${getRecordSummary(live)}`,
+					);
+				}
+			} catch (err) {
+				if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+					if (jsonMode) {
+						outputJsonError("restore", "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("restore", (err as Error).message);
+					} else {
+						console.error(chalk.red(`Error: ${(err as Error).message}`));
+					}
+				}
+				process.exitCode = 1;
+			}
+		});
+}

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

@@ -0,0 +1,327 @@
+import chalk from "chalk";
+import { type Command, Option } from "commander";
+import { getRegistry } from "../registry/type-registry.ts";
+import { DEFAULT_SEARCH_BOOST_FACTOR } from "../schemas/config.ts";
+import type { ExpertiseRecord } from "../schemas/record.ts";
+import { getArchivePath, readArchiveFile } from "../utils/archive.ts";
+import { getExpertisePath, readConfig } from "../utils/config.ts";
+import {
+	filterByClassification,
+	filterByFile,
+	filterByType,
+	getFileModTime,
+	readExpertiseFile,
+	searchRecords,
+} from "../utils/expertise.ts";
+import {
+	formatDomainExpertise,
+	formatDomainExpertiseCompact,
+	formatDomainExpertisePlain,
+	formatDomainExpertiseXml,
+	getRecordSummary,
+	type PrimeFormat,
+} from "../utils/format.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+import { type ScoredRecord, sortByConfirmationScore } from "../utils/scoring.ts";
+
+function formatArchivedSection(domain: string, records: ExpertiseRecord[]): string {
+	const lines = [
+		`## ${domain} (archived, ${records.length} record${records.length === 1 ? "" : "s"})`,
+	];
+	for (const r of records) {
+		const date = (r.archived_at ?? "").slice(0, 10) || "unknown";
+		const id = r.id ? `${r.id} ` : "";
+		// Archives written before loam-b41a have no reason on disk; omit the
+		// suffix gracefully so back-compat output stays readable.
+		const reason = r.archive_reason ? ` ${r.archive_reason}` : "";
+		lines.push(`- [ARCHIVED ${date}${reason}] ${id}[${r.type}] ${getRecordSummary(r)}`);
+	}
+	return lines.join("\n");
+}
+
+function applyFilters(
+	records: ExpertiseRecord[],
+	options: {
+		type?: string;
+		tag?: string;
+		classification?: string;
+		file?: string;
+		outcomeStatus?: string;
+	},
+): ExpertiseRecord[] {
+	let out = records;
+	if (options.type) out = filterByType(out, options.type);
+	if (options.tag) {
+		const tagLower = options.tag.toLowerCase();
+		out = out.filter((r) => r.tags?.some((t) => t.toLowerCase() === tagLower));
+	}
+	if (options.classification) out = filterByClassification(out, options.classification);
+	if (options.file) out = filterByFile(out, options.file);
+	if (options.outcomeStatus) {
+		out = out.filter((r) => r.outcomes?.some((o) => o.status === options.outcomeStatus));
+	}
+	return out;
+}
+
+export function registerSearchCommand(program: Command): void {
+	program
+		.command("search")
+		.argument("[query]", "search string (case-insensitive substring match)")
+		.description("Search expertise records across domains")
+		.option("--domain <domain>", "limit search to a specific domain")
+		.addOption(new Option("--type <type>", "filter by record type").choices(getRegistry().names()))
+		.option("--tag <tag>", "filter by tag")
+		.addOption(
+			new Option("--classification <classification>", "filter by classification").choices([
+				"foundational",
+				"tactical",
+				"observational",
+			]),
+		)
+		.option("--file <file>", "filter by associated file path (substring match)")
+		.addOption(
+			new Option("--outcome-status <status>", "filter by outcome status").choices([
+				"success",
+				"failure",
+				"partial",
+			]),
+		)
+		.option("--sort-by-score", "sort results by confirmation-frequency score (highest first)")
+		.option("--no-boost", "disable confirmation-frequency boost on BM25 ranking (pure BM25)")
+		.option("--archived", "include soft-archived records from .loam/archive/ (excluded by default)")
+		.addOption(
+			new Option("--format <format>", "output format for records").choices([
+				"markdown",
+				"compact",
+				"xml",
+				"plain",
+				"ids",
+			]),
+		)
+		.action(
+			async (
+				query: string | undefined,
+				options: {
+					domain?: string;
+					type?: string;
+					tag?: string;
+					classification?: string;
+					file?: string;
+					outcomeStatus?: string;
+					sortByScore?: boolean;
+					boost?: boolean;
+					format?: string;
+					archived?: boolean;
+				},
+			) => {
+				const jsonMode = program.opts().json === true;
+				try {
+					if (
+						!query &&
+						!options.type &&
+						!options.domain &&
+						!options.tag &&
+						!options.classification &&
+						!options.file &&
+						!options.outcomeStatus
+					) {
+						if (jsonMode) {
+							outputJsonError(
+								"search",
+								"Provide a search query or use --type, --domain, --tag, --classification, --file, or --outcome-status to filter.",
+							);
+						} else {
+							console.error(
+								"Error: Provide a search query or use --type, --domain, --tag, --classification, --file, or --outcome-status to filter.",
+							);
+						}
+						process.exitCode = 1;
+						return;
+					}
+
+					const config = await readConfig();
+					const boostFactor =
+						options.boost === false
+							? 0
+							: (config.search?.boost_factor ?? DEFAULT_SEARCH_BOOST_FACTOR);
+
+					let domainsToSearch: string[];
+
+					if (options.domain) {
+						if (!(options.domain in config.domains)) {
+							if (jsonMode) {
+								outputJsonError(
+									"search",
+									`Domain "${options.domain}" not found in config. Available domains: ${Object.keys(config.domains).join(", ")}`,
+								);
+							} else {
+								console.error(
+									`Error: Domain "${options.domain}" not found in config. Available domains: ${Object.keys(config.domains).join(", ")}`,
+								);
+								console.error(
+									`Hint: Run \`loam add ${options.domain}\` to create this domain, or check .loam/loam.config.yaml`,
+								);
+							}
+							process.exitCode = 1;
+							return;
+						}
+						domainsToSearch = [options.domain];
+					} else {
+						domainsToSearch = Object.keys(config.domains);
+					}
+
+					let totalMatches = 0;
+
+					if (jsonMode) {
+						const result: Array<{
+							domain: string;
+							matches: unknown[];
+							archived?: unknown[];
+						}> = [];
+						for (const domain of domainsToSearch) {
+							const filePath = getExpertisePath(domain);
+							const records = applyFilters(await readExpertiseFile(filePath), options);
+							let matches = query ? searchRecords(records, query, { boostFactor }) : records;
+							if (options.sortByScore) {
+								matches = sortByConfirmationScore(matches as ScoredRecord[]);
+							}
+							let archivedMatches: ExpertiseRecord[] = [];
+							if (options.archived) {
+								const archiveRecords = applyFilters(
+									await readArchiveFile(getArchivePath(domain)),
+									options,
+								);
+								archivedMatches = query
+									? searchRecords(archiveRecords, query, { boostFactor })
+									: archiveRecords;
+								if (options.sortByScore) {
+									archivedMatches = sortByConfirmationScore(archivedMatches as ScoredRecord[]);
+								}
+							}
+							if (matches.length > 0 || archivedMatches.length > 0) {
+								totalMatches += matches.length + archivedMatches.length;
+								const entry: { domain: string; matches: unknown[]; archived?: unknown[] } = {
+									domain,
+									matches,
+								};
+								if (options.archived) entry.archived = archivedMatches;
+								result.push(entry);
+							}
+						}
+						outputJson({
+							success: true,
+							command: "search",
+							query: query ?? null,
+							total: totalMatches,
+							domains: result,
+						});
+					} else {
+						const globalFormat = program.opts().format as PrimeFormat | undefined;
+						const fmt = options.format ?? (globalFormat as string | undefined) ?? "markdown";
+						const label = query ? `matching "${query}"` : "matching filters";
+
+						if (fmt === "ids") {
+							const ids: string[] = [];
+							for (const domain of domainsToSearch) {
+								const filePath = getExpertisePath(domain);
+								const records = applyFilters(await readExpertiseFile(filePath), options);
+								let matches = query ? searchRecords(records, query, { boostFactor }) : records;
+								if (options.sortByScore) {
+									matches = sortByConfirmationScore(matches as ScoredRecord[]);
+								}
+								for (const r of matches) {
+									if (r.id) ids.push(r.id);
+								}
+								if (options.archived) {
+									const archiveRecords = applyFilters(
+										await readArchiveFile(getArchivePath(domain)),
+										options,
+									);
+									let archivedMatches = query
+										? searchRecords(archiveRecords, query, { boostFactor })
+										: archiveRecords;
+									if (options.sortByScore) {
+										archivedMatches = sortByConfirmationScore(archivedMatches as ScoredRecord[]);
+									}
+									for (const r of archivedMatches) {
+										if (r.id) ids.push(r.id);
+									}
+								}
+							}
+							if (ids.length === 0) {
+								console.log(`No records ${label} found.`);
+							} else {
+								console.log(ids.join("\n"));
+							}
+						} else {
+							const sections: string[] = [];
+							for (const domain of domainsToSearch) {
+								const filePath = getExpertisePath(domain);
+								const records = applyFilters(await readExpertiseFile(filePath), options);
+								const lastUpdated = await getFileModTime(filePath);
+								let matches = query ? searchRecords(records, query, { boostFactor }) : records;
+								if (options.sortByScore) {
+									matches = sortByConfirmationScore(matches as ScoredRecord[]);
+								}
+								if (matches.length > 0) {
+									totalMatches += matches.length;
+									switch (fmt) {
+										case "compact":
+											sections.push(formatDomainExpertiseCompact(domain, matches, lastUpdated));
+											break;
+										case "xml":
+											sections.push(formatDomainExpertiseXml(domain, matches, lastUpdated));
+											break;
+										case "plain":
+											sections.push(formatDomainExpertisePlain(domain, matches, lastUpdated));
+											break;
+										default:
+											sections.push(formatDomainExpertise(domain, matches, lastUpdated));
+											break;
+									}
+								}
+								if (options.archived) {
+									const archiveRecords = applyFilters(
+										await readArchiveFile(getArchivePath(domain)),
+										options,
+									);
+									let archivedMatches = query
+										? searchRecords(archiveRecords, query, { boostFactor })
+										: archiveRecords;
+									if (options.sortByScore) {
+										archivedMatches = sortByConfirmationScore(archivedMatches as ScoredRecord[]);
+									}
+									if (archivedMatches.length > 0) {
+										totalMatches += archivedMatches.length;
+										sections.push(formatArchivedSection(domain, archivedMatches));
+									}
+								}
+							}
+
+							if (sections.length === 0) {
+								console.log(`No records ${label} found.`);
+							} else {
+								console.log(sections.join("\n\n"));
+								console.log(`\n${totalMatches} match${totalMatches === 1 ? "" : "es"} found.`);
+							}
+						}
+					}
+				} catch (err) {
+					if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+						if (jsonMode) {
+							outputJsonError("search", "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("search", (err as Error).message);
+						} else {
+							console.error(chalk.red(`Error: ${(err as Error).message}`));
+						}
+					}
+					process.exitCode = 1;
+				}
+			},
+		);
+}