@ag-eco/agentplate-cli 0.13.0

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

@@ -0,0 +1,226 @@
+import chalk from "chalk";
+import { type Command, Option } from "commander";
+import { getRegistry } from "../registry/type-registry.ts";
+import type { Classification, ExpertiseRecord, Outcome } from "../schemas/record.ts";
+import { getExpertisePath, readConfig } from "../utils/config.ts";
+import { readExpertiseFile, resolveRecordId, writeExpertiseFile } from "../utils/expertise.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+import { withFileLock } from "../utils/lock.ts";
+import { parseStrictNonNegativeNumber } from "../utils/numeric-flags.ts";
+import { accent, brand, isQuiet } from "../utils/palette.ts";
+
+// snake_case field name → camelCase Commander option key.
+function fieldToOptionKey(field: string): string {
+	return field.replace(/_(.)/g, (_, c: string) => c.toUpperCase());
+}
+
+export function registerEditCommand(program: Command): void {
+	const registry = getRegistry();
+	const cmd = program
+		.command("edit")
+		.argument("<domain>", "expertise domain")
+		.argument("<id>", "record ID (e.g. mx-abc123, abc123, or abc)")
+		.description("Edit an existing expertise record")
+		.addOption(
+			new Option("--classification <classification>", "update classification").choices([
+				"foundational",
+				"tactical",
+				"observational",
+			]),
+		)
+		.option("--content <content>", "update content (convention)")
+		.option("--name <name>", "update name (pattern)")
+		.option("--description <description>", "update description")
+		.option("--resolution <resolution>", "update resolution (failure)")
+		.option("--title <title>", "update title (decision)")
+		.option("--rationale <rationale>", "update rationale (decision)")
+		.option("--files <files>", "update related files (comma-separated)")
+		.option("--relates-to <ids>", "update linked record IDs (comma-separated)")
+		.option("--supersedes <ids>", "update superseded record IDs (comma-separated)")
+		.addOption(
+			new Option("--outcome-status <status>", "set outcome status").choices([
+				"success",
+				"failure",
+				"partial",
+			]),
+		)
+		.option("--outcome-duration <ms>", "set outcome duration in milliseconds")
+		.option("--outcome-test-results <text>", "set outcome test results summary")
+		.option("--outcome-agent <agent>", "set outcome agent name");
+
+	// Dynamic flags for custom-type fields not already declared by built-ins.
+	const declaredOptionNames = new Set(cmd.options.map((o) => o.name()).concat(["files"]));
+	for (const def of registry.enabled()) {
+		if (def.kind === "builtin") continue;
+		for (const field of [...def.required, ...def.optional]) {
+			const flagName = field.replace(/_/g, "-");
+			if (declaredOptionNames.has(flagName)) continue;
+			declaredOptionNames.add(flagName);
+			cmd.option(`--${flagName} <${field}>`, `update ${def.name} field: ${field}`);
+		}
+	}
+
+	cmd.action(async (domain: string, id: string, options: Record<string, unknown>) => {
+		const jsonMode = program.opts().json === true;
+		try {
+			const config = await readConfig();
+
+			if (!(domain in config.domains)) {
+				if (jsonMode) {
+					outputJsonError(
+						"edit",
+						`Domain "${domain}" not found in config. Available domains: ${Object.keys(config.domains).join(", ") || "(none)"}`,
+					);
+				} else {
+					console.error(chalk.red(`Error: domain "${domain}" not found in config.`));
+					console.error(
+						chalk.red(`Available domains: ${Object.keys(config.domains).join(", ") || "(none)"}`),
+					);
+				}
+				process.exitCode = 1;
+				return;
+			}
+
+			const filePath = getExpertisePath(domain);
+			await withFileLock(filePath, async () => {
+				const records = await readExpertiseFile(filePath);
+
+				const resolved = resolveRecordId(records, id);
+				if (!resolved.ok) {
+					if (jsonMode) {
+						outputJsonError("edit", resolved.error);
+					} else {
+						console.error(chalk.red(`Error: ${resolved.error}`));
+					}
+					process.exitCode = 1;
+					return;
+				}
+				const targetIndex = resolved.index;
+
+				const original = records[targetIndex];
+				if (!original) {
+					console.error(chalk.red(`Error: Record at index ${targetIndex} not found`));
+					process.exitCode = 1;
+					return;
+				}
+				const record: ExpertiseRecord = { ...original };
+
+				// Apply updates based on record type
+				if (options.classification) {
+					record.classification = options.classification as Classification;
+				}
+				if (typeof options.relatesTo === "string") {
+					record.relates_to = options.relatesTo
+						.split(",")
+						.map((id: string) => id.trim())
+						.filter(Boolean);
+				}
+				if (typeof options.supersedes === "string") {
+					record.supersedes = options.supersedes
+						.split(",")
+						.map((id: string) => id.trim())
+						.filter(Boolean);
+				}
+				if (options.outcomeStatus) {
+					const o: Outcome = {
+						status: options.outcomeStatus as "success" | "failure" | "partial",
+					};
+					if (options.outcomeDuration !== undefined) {
+						const parsed = parseStrictNonNegativeNumber(options.outcomeDuration as string);
+						if (parsed === null) {
+							const msg = `--outcome-duration must be a non-negative number (got "${options.outcomeDuration as string}").`;
+							if (jsonMode) {
+								outputJsonError("edit", msg);
+							} else {
+								console.error(chalk.red(`Error: ${msg}`));
+							}
+							process.exitCode = 1;
+							return;
+						}
+						o.duration = parsed;
+					}
+					if (options.outcomeTestResults) {
+						o.test_results = options.outcomeTestResults as string;
+					}
+					if (options.outcomeAgent) {
+						o.agent = options.outcomeAgent as string;
+					}
+					record.outcomes = [...(record.outcomes ?? []), o];
+				}
+
+				const def = registry.get(record.type);
+				if (def) {
+					const mutable = record as unknown as Record<string, unknown>;
+					for (const field of [...def.required, ...def.optional]) {
+						const optKey = fieldToOptionKey(field);
+						const value = options[optKey];
+						if (value === undefined) continue;
+						if (def.extractsFiles && field === def.filesField && typeof value === "string") {
+							mutable[field] = value
+								.split(",")
+								.map((s) => s.trim())
+								.filter(Boolean);
+						} else {
+							mutable[field] = value;
+						}
+					}
+				}
+
+				// Validate the updated record (cached on registry)
+				const validate = getRegistry().validator;
+				if (!validate(record)) {
+					const errors = (validate.errors ?? []).map((err) => `${err.instancePath} ${err.message}`);
+					if (jsonMode) {
+						outputJsonError(
+							"edit",
+							`Updated record failed schema validation: ${errors.join("; ")}`,
+						);
+					} else {
+						console.error(chalk.red("Error: updated record failed schema validation:"));
+						for (const err of validate.errors ?? []) {
+							console.error(chalk.red(`  ${err.instancePath} ${err.message}`));
+						}
+					}
+					process.exitCode = 1;
+					return;
+				}
+
+				records[targetIndex] = record;
+				await writeExpertiseFile(filePath, records);
+
+				if (jsonMode) {
+					outputJson({
+						success: true,
+						command: "edit",
+						domain,
+						id: record.id ?? null,
+						type: record.type,
+						record,
+					});
+				} else {
+					if (!isQuiet()) {
+						const id = record.id ? ` ${accent(record.id)}` : "";
+						console.log(
+							`${brand("✓")} ${brand(`Updated ${record.type}`)}${id} ${brand(`in ${domain}`)}`,
+						);
+					}
+				}
+			});
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+				if (jsonMode) {
+					outputJsonError("edit", "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("edit", (err as Error).message);
+				} else {
+					console.error(chalk.red(`Error: ${(err as Error).message}`));
+				}
+			}
+			process.exitCode = 1;
+		}
+	});
+}

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

@@ -0,0 +1,31 @@
+import { existsSync } from "node:fs";
+import type { Command } from "commander";
+import { getLoamDir, initLoamDir } from "../utils/config.ts";
+import { outputJson } from "../utils/json-output.ts";
+import { brand, isQuiet } from "../utils/palette.ts";
+
+export function registerInitCommand(program: Command): void {
+	program
+		.command("init")
+		.description("Initialize .loam/ in the current project")
+		.action(async () => {
+			const jsonMode = program.opts().json === true;
+			const loamDir = getLoamDir();
+			const alreadyExists = existsSync(loamDir);
+
+			await initLoamDir();
+
+			if (jsonMode) {
+				outputJson({
+					success: true,
+					command: "init",
+					created: !alreadyExists,
+					path: loamDir,
+				});
+			} else if (alreadyExists) {
+				if (!isQuiet()) console.log(brand("Updated .loam/ — filled in any missing artifacts."));
+			} else {
+				if (!isQuiet()) console.log(brand(`Initialized .loam/ in ${process.cwd()}`));
+			}
+		});
+}

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

@@ -0,0 +1,179 @@
+import { existsSync } from "node:fs";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { getRegistry } from "../registry/type-registry.ts";
+import { getExpertisePath, getLoamDir, readConfig } from "../utils/config.ts";
+import { readExpertiseFile } from "../utils/expertise.ts";
+import { getChangedFiles, isGitRepo } from "../utils/git.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+
+interface DomainMatch {
+	domain: string;
+	matchedFiles: string[];
+}
+
+export async function matchFilesToDomains(
+	changedFiles: string[],
+	cwd?: string,
+): Promise<{ matches: DomainMatch[]; unmatched: string[] }> {
+	const config = await readConfig(cwd);
+	const matched = new Set<string>();
+	const matches: DomainMatch[] = [];
+
+	for (const domain of Object.keys(config.domains)) {
+		const filePath = getExpertisePath(domain, cwd);
+		const records = await readExpertiseFile(filePath);
+
+		// Collect all file paths from records whose type extracts files
+		// (built-in pattern/reference, plus any custom types with extracts_files: true).
+		const registry = getRegistry();
+		const domainFiles = new Set<string>();
+		for (const record of records) {
+			const def = registry.get(record.type);
+			if (!def?.extractsFiles) continue;
+			const files = (record as unknown as Record<string, unknown>)[def.filesField];
+			if (!Array.isArray(files)) continue;
+			for (const f of files) {
+				if (typeof f === "string") domainFiles.add(f);
+			}
+		}
+
+		// Match changed files against domain file paths
+		const domainMatched: string[] = [];
+		for (const changedFile of changedFiles) {
+			for (const domainFile of domainFiles) {
+				if (
+					changedFile === domainFile ||
+					changedFile.endsWith(domainFile) ||
+					domainFile.endsWith(changedFile)
+				) {
+					domainMatched.push(changedFile);
+					matched.add(changedFile);
+					break;
+				}
+			}
+		}
+
+		if (domainMatched.length > 0) {
+			matches.push({ domain, matchedFiles: domainMatched });
+		}
+	}
+
+	// Sort by match count descending
+	matches.sort((a, b) => b.matchedFiles.length - a.matchedFiles.length);
+
+	const unmatched = changedFiles.filter((f) => !matched.has(f));
+	return { matches, unmatched };
+}
+
+export function registerLearnCommand(program: Command): void {
+	program
+		.command("learn")
+		.description("Show changed files and suggest domains for recording learnings")
+		.option("--since <ref>", "git ref to diff against", "HEAD~1")
+		.action(async (options: { since: string }) => {
+			const jsonMode = program.opts().json === true;
+			const cwd = process.cwd();
+
+			if (!isGitRepo(cwd)) {
+				if (jsonMode) {
+					outputJsonError(
+						"learn",
+						"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;
+			}
+
+			// No .loam/ directory — exit cleanly (supports hook usage in non-loam projects)
+			if (!existsSync(getLoamDir(cwd))) {
+				if (jsonMode) {
+					outputJson({
+						success: true,
+						command: "learn",
+						changedFiles: [],
+						suggestedDomains: [],
+						unmatchedFiles: [],
+						message: "No .loam/ directory found — skipping",
+					});
+				}
+				return;
+			}
+
+			try {
+				const changedFiles = getChangedFiles(cwd, options.since);
+
+				if (changedFiles.length === 0) {
+					if (jsonMode) {
+						outputJson({
+							success: true,
+							command: "learn",
+							changedFiles: [],
+							suggestedDomains: [],
+							unmatchedFiles: [],
+							message: "No changed files found",
+						});
+					} else {
+						console.log("No changed files found. Nothing to learn from.");
+					}
+					return;
+				}
+
+				const { matches, unmatched } = await matchFilesToDomains(changedFiles);
+
+				if (jsonMode) {
+					outputJson({
+						success: true,
+						command: "learn",
+						changedFiles,
+						suggestedDomains: matches.map((m) => ({
+							domain: m.domain,
+							matchCount: m.matchedFiles.length,
+							files: m.matchedFiles,
+						})),
+						unmatchedFiles: unmatched,
+					});
+					return;
+				}
+
+				// Plain text output
+				console.log(chalk.bold("\nSession learnings check\n"));
+
+				console.log(chalk.cyan(`Changed files (${changedFiles.length}):`));
+				for (const f of changedFiles) {
+					console.log(`  ${f}`);
+				}
+
+				if (matches.length > 0) {
+					console.log(chalk.cyan("\nSuggested domains:"));
+					for (const m of matches) {
+						const label = m.matchedFiles.length === 1 ? "file matches" : "files match";
+						console.log(
+							`  ${chalk.bold(m.domain)} (${m.matchedFiles.length} ${label} existing records)`,
+						);
+					}
+				}
+
+				if (unmatched.length > 0) {
+					console.log(chalk.yellow("\nUnmatched files (no domain association):"));
+					for (const f of unmatched) {
+						console.log(`  ${f}`);
+					}
+				}
+
+				console.log(chalk.dim("\nRecord learnings with:"));
+				console.log(chalk.dim('  lm record <domain> --type <type> --description "..."'));
+				console.log();
+			} catch (err) {
+				if (jsonMode) {
+					outputJsonError("learn", (err as Error).message);
+				} else {
+					console.error(chalk.red(`Error: ${(err as Error).message}`));
+				}
+				process.exitCode = 1;
+			}
+		});
+}