@ag-eco/agentplate-cli 0.13.0

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

@@ -0,0 +1,218 @@
+import chalk from "chalk";
+import { type Command, Option } from "commander";
+import { getExpertisePath, readConfig } from "../utils/config.ts";
+import {
+	filterByClassification,
+	filterByFile,
+	filterByType,
+	getFileModTime,
+	readExpertiseFile,
+} from "../utils/expertise.ts";
+import {
+	formatDomainExpertise,
+	formatDomainExpertiseCompact,
+	formatDomainExpertisePlain,
+	formatDomainExpertiseXml,
+	type PrimeFormat,
+} from "../utils/format.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+import { type ScoredRecord, sortByConfirmationScore } from "../utils/scoring.ts";
+
+export function registerQueryCommand(program: Command): void {
+	program
+		.command("query")
+		.argument("[domain]", "expertise domain to query")
+		.description("Query expertise records")
+		.option("--type <type>", "filter by record type")
+		.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",
+			]),
+		)
+		.option("--sort-by-score", "sort results by confirmation-frequency score (highest first)")
+		.option("--all", "show all domains")
+		.addOption(
+			new Option("--format <format>", "output format for records").choices([
+				"markdown",
+				"compact",
+				"xml",
+				"plain",
+				"ids",
+			]),
+		)
+		.action(async (domain: string | undefined, options: Record<string, unknown>) => {
+			const jsonMode = program.opts().json === true;
+			try {
+				const config = await readConfig();
+
+				const domainsToQuery: string[] = [];
+
+				if (options.all) {
+					domainsToQuery.push(...Object.keys(config.domains));
+					if (domainsToQuery.length === 0) {
+						if (jsonMode) {
+							outputJson({ success: true, command: "query", domains: [] });
+						} else {
+							console.log("No domains configured. Run `lm add <domain>` to get started.");
+						}
+						return;
+					}
+				} else if (domain) {
+					if (!(domain in config.domains)) {
+						if (jsonMode) {
+							outputJsonError(
+								"query",
+								`Domain "${domain}" not found in config. Available domains: ${Object.keys(config.domains).join(", ") || "(none)"}`,
+							);
+						} else {
+							console.error(
+								`Error: Domain "${domain}" not found in config. Available domains: ${Object.keys(config.domains).join(", ") || "(none)"}`,
+							);
+							console.error(
+								`Hint: Run \`lm add ${domain}\` to create this domain, or check .loam/loam.config.yaml`,
+							);
+						}
+						process.exitCode = 1;
+						return;
+					}
+					domainsToQuery.push(domain);
+				} else {
+					if (jsonMode) {
+						outputJsonError("query", "Please specify a domain or use --all to query all domains.");
+					} else {
+						console.error(
+							chalk.red("Error: Please specify a domain or use --all to query all domains."),
+						);
+					}
+					process.exitCode = 1;
+					return;
+				}
+
+				if (jsonMode) {
+					const result: Array<{ domain: string; records: unknown[] }> = [];
+					for (const d of domainsToQuery) {
+						const filePath = getExpertisePath(d);
+						let records = await readExpertiseFile(filePath);
+						if (options.type) {
+							records = filterByType(records, options.type as string);
+						}
+						if (options.classification) {
+							records = filterByClassification(records, options.classification as string);
+						}
+						if (options.file) {
+							records = filterByFile(records, options.file as string);
+						}
+						if (options.outcomeStatus) {
+							records = records.filter((r) =>
+								r.outcomes?.some((o) => o.status === (options.outcomeStatus as string)),
+							);
+						}
+						if (options.sortByScore) {
+							records = sortByConfirmationScore(records as ScoredRecord[]);
+						}
+						result.push({ domain: d, records });
+					}
+					outputJson({ success: true, command: "query", domains: result });
+				} else {
+					const globalFormat = program.opts().format as PrimeFormat | undefined;
+					const fmt =
+						(options.format as string | undefined) ??
+						(globalFormat as string | undefined) ??
+						"markdown";
+					if (fmt === "ids") {
+						const ids: string[] = [];
+						for (const d of domainsToQuery) {
+							const filePath = getExpertisePath(d);
+							let records = await readExpertiseFile(filePath);
+							if (options.type) {
+								records = filterByType(records, options.type as string);
+							}
+							if (options.classification) {
+								records = filterByClassification(records, options.classification as string);
+							}
+							if (options.file) {
+								records = filterByFile(records, options.file as string);
+							}
+							if (options.outcomeStatus) {
+								records = records.filter((r) =>
+									r.outcomes?.some((o) => o.status === (options.outcomeStatus as string)),
+								);
+							}
+							if (options.sortByScore) {
+								records = sortByConfirmationScore(records as ScoredRecord[]);
+							}
+							for (const r of records) {
+								if (r.id) ids.push(r.id);
+							}
+						}
+						if (ids.length > 0) {
+							console.log(ids.join("\n"));
+						}
+					} else {
+						const sections: string[] = [];
+						for (const d of domainsToQuery) {
+							const filePath = getExpertisePath(d);
+							let records = await readExpertiseFile(filePath);
+							const lastUpdated = await getFileModTime(filePath);
+							if (options.type) {
+								records = filterByType(records, options.type as string);
+							}
+							if (options.classification) {
+								records = filterByClassification(records, options.classification as string);
+							}
+							if (options.file) {
+								records = filterByFile(records, options.file as string);
+							}
+							if (options.outcomeStatus) {
+								records = records.filter((r) =>
+									r.outcomes?.some((o) => o.status === (options.outcomeStatus as string)),
+								);
+							}
+							if (options.sortByScore) {
+								records = sortByConfirmationScore(records as ScoredRecord[]);
+							}
+							switch (fmt) {
+								case "compact":
+									sections.push(formatDomainExpertiseCompact(d, records, lastUpdated));
+									break;
+								case "xml":
+									sections.push(formatDomainExpertiseXml(d, records, lastUpdated));
+									break;
+								case "plain":
+									sections.push(formatDomainExpertisePlain(d, records, lastUpdated));
+									break;
+								default:
+									sections.push(formatDomainExpertise(d, records, lastUpdated));
+									break;
+							}
+						}
+						console.log(sections.join("\n\n"));
+					}
+				}
+			} catch (err) {
+				if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+					if (jsonMode) {
+						outputJsonError("query", "No .loam/ directory found. Run `lm init` first.");
+					} else {
+						console.error(chalk.red("Error: No .loam/ directory found. Run `lm init` first."));
+					}
+				} else {
+					if (jsonMode) {
+						outputJsonError("query", (err as Error).message);
+					} else {
+						console.error(chalk.red(`Error: ${(err as Error).message}`));
+					}
+				}
+				process.exitCode = 1;
+			}
+		});
+}

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

@@ -0,0 +1,180 @@
+import chalk from "chalk";
+import { type Command, Option } from "commander";
+import { getRegistry } from "../registry/type-registry.ts";
+import type { ExpertiseRecord } from "../schemas/record.ts";
+import { getExpertisePath, readConfig } from "../utils/config.ts";
+import { filterByType, readExpertiseFile } from "../utils/expertise.ts";
+import { getRecordSummary } from "../utils/format.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+import { accent } from "../utils/palette.ts";
+import { computeConfirmationScore, type ScoredRecord } from "../utils/scoring.ts";
+
+interface RankedRecord {
+	domain: string;
+	record: ExpertiseRecord;
+	score: number;
+}
+
+function formatScore(score: number): string {
+	return Number.isInteger(score) ? String(score) : score.toFixed(1);
+}
+
+const POSITIVE_INT_RE = /^\d+$/;
+const NON_NEGATIVE_NUMBER_RE = /^\d+(\.\d+)?$/;
+
+function parseStrictPositiveInt(raw: string): number | null {
+	if (!POSITIVE_INT_RE.test(raw)) return null;
+	const n = Number(raw);
+	return Number.isFinite(n) && n >= 1 ? n : null;
+}
+
+function parseStrictNonNegativeNumber(raw: string): number | null {
+	if (!NON_NEGATIVE_NUMBER_RE.test(raw)) return null;
+	const n = Number(raw);
+	return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+export function registerRankCommand(program: Command): void {
+	program
+		.command("rank")
+		.argument("[domain]", "limit ranking to a specific domain")
+		.description("Rank records by confirmation-frequency score (highest first)")
+		.addOption(new Option("--type <type>", "filter by record type").choices(getRegistry().names()))
+		.option("--limit <n>", "return at most N records", "10")
+		.option(
+			"--min-score <n>",
+			"exclude records whose confirmation score is below N (default: 0, i.e. include all)",
+			"0",
+		)
+		.action(
+			async (
+				domain: string | undefined,
+				options: { type?: string; limit: string; minScore: string },
+			) => {
+				const jsonMode = program.opts().json === true;
+				try {
+					// `Number.parseInt("10abc", 10)` silently strips trailing garbage and
+					// returns 10 — accept the typo as success. Use a regex + Number()
+					// pair so `--limit 10abc` / `--limit 3.7` are rejected.
+					const limit = parseStrictPositiveInt(options.limit);
+					if (limit === null) {
+						const msg = `--limit must be a positive integer (got "${options.limit}").`;
+						if (jsonMode) {
+							outputJsonError("rank", msg);
+						} else {
+							console.error(chalk.red(`Error: ${msg}`));
+						}
+						process.exitCode = 1;
+						return;
+					}
+
+					const minScore = parseStrictNonNegativeNumber(options.minScore);
+					if (minScore === null) {
+						const msg = `--min-score must be a non-negative number (got "${options.minScore}").`;
+						if (jsonMode) {
+							outputJsonError("rank", msg);
+						} else {
+							console.error(chalk.red(`Error: ${msg}`));
+						}
+						process.exitCode = 1;
+						return;
+					}
+
+					const config = await readConfig();
+
+					let domainsToRank: string[];
+					if (domain) {
+						if (!(domain in config.domains)) {
+							const available = Object.keys(config.domains).join(", ") || "(none)";
+							const msg = `Domain "${domain}" not found in config. Available domains: ${available}`;
+							if (jsonMode) {
+								outputJsonError("rank", msg);
+							} else {
+								console.error(chalk.red(`Error: ${msg}`));
+								console.error(
+									`Hint: Run \`lm add ${domain}\` to create this domain, or check .loam/loam.config.yaml`,
+								);
+							}
+							process.exitCode = 1;
+							return;
+						}
+						domainsToRank = [domain];
+					} else {
+						domainsToRank = Object.keys(config.domains);
+					}
+
+					const ranked: RankedRecord[] = [];
+					for (const d of domainsToRank) {
+						const filePath = getExpertisePath(d);
+						let records = await readExpertiseFile(filePath);
+						if (options.type) {
+							records = filterByType(records, options.type);
+						}
+						for (const record of records) {
+							const score = computeConfirmationScore(record as ScoredRecord);
+							if (score < minScore) continue;
+							ranked.push({ domain: d, record, score });
+						}
+					}
+
+					ranked.sort((a, b) => b.score - a.score);
+
+					const top = ranked.slice(0, limit);
+
+					if (jsonMode) {
+						outputJson({
+							success: true,
+							command: "rank",
+							count: top.length,
+							records: top.map((e) => ({
+								domain: e.domain,
+								id: e.record.id ?? null,
+								type: e.record.type,
+								score: e.score,
+								summary: getRecordSummary(e.record),
+								record: e.record,
+							})),
+						});
+						return;
+					}
+
+					if (top.length === 0) {
+						console.log("No records match the ranking criteria.");
+						return;
+					}
+
+					const scope = domain ?? "all domains";
+					console.log(
+						`Top ${top.length} record${top.length === 1 ? "" : "s"} by confirmation score (${scope})`,
+					);
+					console.log("");
+
+					for (const entry of top) {
+						const id = entry.record.id ? `${accent(entry.record.id)}  ` : "";
+						const score = chalk.green(`★${formatScore(entry.score)}`.padEnd(6));
+						const domainCol = chalk.cyan(entry.domain.padEnd(14));
+						const type = chalk.yellow(`[${entry.record.type}]`.padEnd(14));
+						const summary = getRecordSummary(entry.record);
+						console.log(`  ${id}${score}${domainCol}${type}${summary}`);
+					}
+				} catch (err) {
+					if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+						const msg = "No .loam/ directory found. Run `lm init` first.";
+						if (jsonMode) {
+							outputJsonError("rank", msg);
+						} else {
+							console.error(chalk.red(`Error: ${msg}`));
+						}
+					} else {
+						const msg = (err as Error).message;
+						if (jsonMode) {
+							outputJsonError("rank", msg);
+						} else {
+							console.error(chalk.red(`Error: ${msg}`));
+						}
+					}
+					process.exitCode = 1;
+				}
+			},
+		);
+}

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

@@ -0,0 +1,189 @@
+import chalk from "chalk";
+import type { Command } from "commander";
+import type { ExpertiseRecord } from "../schemas/record.ts";
+import { getExpertisePath, readConfig } from "../utils/config.ts";
+import { readExpertiseFile } from "../utils/expertise.ts";
+import { formatTimeAgo, getRecordSummary } from "../utils/format.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+import { accent } from "../utils/palette.ts";
+
+interface AnnotatedRecord {
+	domain: string;
+	record: ExpertiseRecord;
+}
+
+// Strict numeric flag parsing — see mx-5b9578 / src/commands/rank.ts.
+// `Number.parseInt("10abc", 10)` silently returns 10; use regex + Number() so
+// typos like `--limit 10abc` or `--limit 3.7` are rejected.
+const POSITIVE_INT_RE = /^\d+$/;
+
+function parseStrictPositiveInt(raw: string): number | null {
+	if (!POSITIVE_INT_RE.test(raw)) return null;
+	const n = Number(raw);
+	return Number.isFinite(n) && n >= 1 ? n : null;
+}
+
+function parseDuration(input: string): number {
+	const match = input.match(/^(\d+)(h|d|w)$/);
+	if (!match) {
+		throw new Error(`Invalid duration: "${input}". Use format like "24h", "7d", "2w".`);
+	}
+	const value = Number.parseInt(match[1] ?? "", 10);
+	const unit = match[2] ?? "";
+	switch (unit) {
+		case "h":
+			return value * 3600000;
+		case "d":
+			return value * 86400000;
+		case "w":
+			return value * 7 * 86400000;
+		default:
+			throw new Error(`Unknown unit: ${unit}`);
+	}
+}
+
+export function registerReadyCommand(program: Command): void {
+	program
+		.command("ready")
+		.description("Show recently added or updated expertise records")
+		.option("--limit <n>", "maximum number of records to show", "10")
+		.option("--domain <domain>", "limit to a specific domain")
+		.option("--since <duration>", "show records from the last duration (e.g. 24h, 7d, 2w)")
+		.action(async (options: { limit: string; domain?: string; since?: string }) => {
+			const jsonMode = program.opts().json === true;
+
+			try {
+				const config = await readConfig();
+				const limit = parseStrictPositiveInt(options.limit);
+
+				if (limit === null) {
+					const msg = `--limit must be a positive integer (got "${options.limit}").`;
+					if (jsonMode) {
+						outputJsonError("ready", msg);
+					} else {
+						console.error(chalk.red(`Error: ${msg}`));
+					}
+					process.exitCode = 1;
+					return;
+				}
+
+				let domainsToCheck: string[];
+				if (options.domain) {
+					if (!(options.domain in config.domains)) {
+						if (jsonMode) {
+							outputJsonError(
+								"ready",
+								`Domain "${options.domain}" not found in config. Available domains: ${Object.keys(config.domains).join(", ")}`,
+							);
+						} else {
+							console.error(
+								chalk.red(
+									`Error: domain "${options.domain}" not found. Available: ${Object.keys(config.domains).join(", ")}`,
+								),
+							);
+						}
+						process.exitCode = 1;
+						return;
+					}
+					domainsToCheck = [options.domain];
+				} else {
+					domainsToCheck = Object.keys(config.domains);
+				}
+
+				let sinceMs: number | undefined;
+				if (options.since) {
+					try {
+						sinceMs = parseDuration(options.since);
+					} catch (err) {
+						if (jsonMode) {
+							outputJsonError("ready", (err as Error).message);
+						} else {
+							console.error(chalk.red(`Error: ${(err as Error).message}`));
+						}
+						process.exitCode = 1;
+						return;
+					}
+				}
+
+				// Collect all records with domain annotation
+				const all: AnnotatedRecord[] = [];
+				for (const domain of domainsToCheck) {
+					const filePath = getExpertisePath(domain);
+					const records = await readExpertiseFile(filePath);
+					for (const record of records) {
+						all.push({ domain, record });
+					}
+				}
+
+				// Sort by recorded_at descending
+				all.sort((a, b) => {
+					const aTime = new Date(a.record.recorded_at).getTime();
+					const bTime = new Date(b.record.recorded_at).getTime();
+					return bTime - aTime;
+				});
+
+				// Apply --since filter
+				let filtered = all;
+				if (sinceMs !== undefined) {
+					const cutoff = Date.now() - sinceMs;
+					filtered = all.filter((entry) => {
+						return new Date(entry.record.recorded_at).getTime() >= cutoff;
+					});
+				}
+
+				// Apply limit
+				const entries = filtered.slice(0, limit);
+
+				if (jsonMode) {
+					outputJson({
+						success: true,
+						command: "ready",
+						count: entries.length,
+						entries: entries.map((e) => ({
+							domain: e.domain,
+							id: e.record.id ?? null,
+							type: e.record.type,
+							recorded_at: e.record.recorded_at,
+							summary: getRecordSummary(e.record),
+							record: e.record,
+						})),
+					});
+				} else {
+					if (entries.length === 0) {
+						console.log("No recent expertise records found.");
+						return;
+					}
+
+					const header = options.since
+						? `Recent Expertise (last ${options.since})`
+						: `Recent Expertise (last ${entries.length} records)`;
+					console.log(header);
+					console.log("");
+
+					for (const entry of entries) {
+						const age = formatTimeAgo(new Date(entry.record.recorded_at));
+						const id = entry.record.id ? `${accent(entry.record.id)}  ` : "";
+						const domain = chalk.cyan(entry.domain.padEnd(14));
+						const type = chalk.yellow(`[${entry.record.type}]`.padEnd(14));
+						const summary = getRecordSummary(entry.record);
+						console.log(`  ${id}${chalk.dim(age.padEnd(10))}${domain}${type}${summary}`);
+					}
+				}
+			} catch (err) {
+				if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+					if (jsonMode) {
+						outputJsonError("ready", "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("ready", (err as Error).message);
+					} else {
+						console.error(chalk.red(`Error: ${(err as Error).message}`));
+					}
+				}
+				process.exitCode = 1;
+			}
+		});
+}