@ag-eco/agentplate-cli 0.13.0

package/src/tools/loam/index.ts

@@ -0,0 +1,62 @@
+// Type exports
+
+export type {
+	AppendOutcomeResult,
+	EditOptions,
+	OutcomeOptions,
+	QueryOptions,
+	RecordOptions,
+	RecordResult,
+	RecordUpdates,
+	SearchOptions,
+	SearchResult,
+} from "./api.ts";
+// Programmatic API
+export {
+	appendOutcome,
+	editRecord,
+	queryDomain,
+	recordExpertise,
+	searchExpertise,
+} from "./api.ts";
+// Schema exports
+export { configSchema } from "./schemas/config-schema.ts";
+export type {
+	Classification,
+	ConventionRecord,
+	DecisionRecord,
+	Evidence,
+	ExpertiseRecord,
+	FailureRecord,
+	GuideRecord,
+	LoamConfig,
+	Outcome,
+	PatternRecord,
+	RecordType,
+	ReferenceRecord,
+} from "./schemas/index.ts";
+export { DEFAULT_CONFIG } from "./schemas/index.ts";
+export { recordSchema } from "./schemas/record-schema.ts";
+// Config utilities
+export { getExpertisePath, readConfig } from "./utils/config.ts";
+// Expertise utilities
+export {
+	appendRecord,
+	findDuplicate,
+	generateRecordId,
+	readExpertiseFile,
+	searchRecords,
+	writeExpertiseFile,
+} from "./utils/expertise.ts";
+
+// Scoring utilities
+export type { ScoredRecord } from "./utils/scoring.ts";
+export {
+	applyConfirmationBoost,
+	computeConfirmationScore,
+	getFailureCount,
+	getSuccessCount,
+	getSuccessRate,
+	getTotalApplications,
+	sortByConfirmationScore,
+} from "./utils/scoring.ts";

package/src/tools/loam/log.ts

@@ -0,0 +1,127 @@
+/**
+ * Structured logger for loam's diagnostic / operational channel.
+ *
+ * IMPORTANT: this is NOT the product-output channel. Loam's user-facing
+ * output (the markdown `lm prime` emits, status tables, `--json` results,
+ * hints) intentionally goes straight to stdout via `console.log` /
+ * `outputJson`. Routing that through pino would wrap the product output in
+ * log envelopes and corrupt machine-readable `--json` consumers.
+ *
+ * This logger is for *diagnostics* — hook execution, unexpected internal
+ * errors, anything an operator (not the end user) wants when debugging.
+ * For that reason it writes to **stderr** (fd 2), never stdout, so it can
+ * never collide with the CLI result on stdout. It is silent at `info` for
+ * routine internals (those log at `debug`, gated behind `LOAM_DEBUG`).
+ *
+ * Level: `LOAM_LOG_LEVEL` wins; otherwise `debug` when `LOAM_DEBUG` is
+ * set, else `info`. In a dev TTY we render with `pino-pretty` (a devDep);
+ * in CI / non-TTY / production we emit newline-delimited JSON. `pino-pretty`
+ * is intentionally not a runtime dependency — published consumers of
+ * `@ag-eco/loam-cli` get JSON logs and never need the pretty transport.
+ */
+
+import pino, { type Logger } from "pino";
+
+/**
+ * Resolve the effective log level from the environment. `LOAM_LOG_LEVEL`
+ * is authoritative; `LOAM_DEBUG` is the ergonomic shortcut to `debug`.
+ */
+export function resolveLogLevel(env: NodeJS.ProcessEnv = process.env): string {
+	return env.LOAM_LOG_LEVEL ?? (env.LOAM_DEBUG ? "debug" : "info");
+}
+
+/**
+ * Redaction paths use pino/fast-redact syntax, where `*` is a *full key
+ * segment* wildcard (`*.password` = a `password` key one level under any
+ * key). We list both the bare key (`password`) and the wildcard form
+ * (`*.password`) so a secret is masked whether it appears at the top level
+ * or nested. `remove: true` drops the key entirely rather than printing a
+ * `[Redacted]` placeholder.
+ *
+ * Note on `env.*KEY*` / `env.*TOKEN*`: fast-redact wildcards match a whole
+ * segment, so these only catch a literally-matching nested key — they do
+ * NOT pattern-match arbitrary `*_API_KEY` env names. They are kept because
+ * the L5 governance spec lists them and they are harmless, but the real
+ * defence for connection strings is `redactDbUrl()` below, applied inline
+ * before the value ever reaches a log call.
+ */
+export const REDACT_PATHS = [
+	"password",
+	"*.password",
+	"token",
+	"*.token",
+	"apiKey",
+	"*.apiKey",
+	"secret",
+	"*.secret",
+	"headers.authorization",
+	"headers.cookie",
+	"env.*KEY*",
+	"env.*TOKEN*",
+] as const;
+
+/**
+ * Build a pino logger. Exposed (in addition to the default `log` instance)
+ * so tests can inject a capturing destination and a fixed env without
+ * mutating `process.env` — mirrors loam's no-mocks, real-stream testing
+ * convention.
+ */
+export function createLogger(
+	opts: { level?: string; destination?: pino.DestinationStream; pretty?: boolean } = {},
+): Logger {
+	const level = opts.level ?? resolveLogLevel();
+	const redact = { paths: [...REDACT_PATHS], remove: true };
+
+	// Pretty transport and an explicit destination stream are mutually
+	// exclusive in pino — passing both throws. When a test hands us a
+	// destination we always take the plain-JSON path so output is captured
+	// verbatim.
+	if (opts.destination) {
+		return pino({ name: "loam", level, redact }, opts.destination);
+	}
+
+	const usePretty =
+		opts.pretty ?? (process.stderr.isTTY === true && process.env.LOAM_LOG_JSON !== "1");
+
+	if (usePretty) {
+		return pino({
+			name: "loam",
+			level,
+			redact,
+			transport: {
+				target: "pino-pretty",
+				options: { destination: 2, colorize: true, translateTime: "SYS:HH:MM:ss.l" },
+			},
+		});
+	}
+
+	// CI / non-TTY / production: newline-delimited JSON straight to stderr.
+	return pino({ name: "loam", level, redact }, pino.destination(2));
+}
+
+/**
+ * Strip credentials (`user:password@`) from a URL before logging it.
+ * Mirrors warren's helper: non-URL sentinels (`:memory:`, bare sqlite
+ * paths) and credential-free URLs pass through unchanged; an unparseable
+ * URL collapses to a safe placeholder so a malformed value can never leak.
+ */
+export function redactDbUrl(url: string): string {
+	// Bare sqlite / sentinel values have no userinfo to strip.
+	if (url === ":memory:" || url.startsWith("sqlite:") || !url.includes("@")) {
+		return url;
+	}
+	try {
+		const u = new URL(url);
+		if (u.username !== "" || u.password !== "") {
+			u.username = "";
+			u.password = "";
+			return u.toString();
+		}
+		return url;
+	} catch {
+		return "<redacted-url>";
+	}
+}
+
+/** Default process-wide logger. Diagnostics only — see file header. */
+export const log = createLogger();

package/src/tools/loam/registry/builtins.ts

@@ -0,0 +1,409 @@
+import type {
+	ConventionRecord,
+	DecisionRecord,
+	ExpertiseRecord,
+	FailureRecord,
+	GuideRecord,
+	PatternRecord,
+	ReferenceRecord,
+} from "../schemas/record.ts";
+import {
+	compactMeta,
+	formatLinks,
+	formatOutcome,
+	formatRecordMeta,
+	idTag,
+	truncate,
+	xmlEscape,
+} from "../utils/format-helpers.ts";
+import { type SharedDefinitions, type TypeDefinition, TypeRegistry } from "./type-registry.ts";
+
+const linkArray = {
+	type: "array",
+	items: { type: "string", pattern: "^([a-z0-9-]+:)?mx-[0-9a-f]{4,8}$" },
+} as const;
+
+const SHARED_DEFINITIONS: SharedDefinitions = {
+	classification: {
+		type: "string",
+		enum: ["foundational", "tactical", "observational"],
+	},
+	evidence: {
+		type: "object",
+		properties: {
+			commit: { type: "string" },
+			date: { type: "string" },
+			issue: { type: "string" },
+			file: { type: "string" },
+			bead: { type: "string" },
+			sprout: { type: "string" },
+			gh: { type: "string" },
+			linear: { type: "string" },
+		},
+		additionalProperties: false,
+	},
+	outcome: {
+		type: "object",
+		properties: {
+			status: { type: "string", enum: ["success", "failure", "partial"] },
+			duration: { type: "number" },
+			test_results: { type: "string" },
+			agent: { type: "string" },
+			notes: { type: "string" },
+			recorded_at: { type: "string" },
+		},
+		required: ["status"],
+		additionalProperties: false,
+	},
+};
+
+const baseSchemaProps = {
+	id: { type: "string", pattern: "^mx-[0-9a-f]{4,8}$" },
+	classification: { $ref: "#/definitions/classification" },
+	recorded_at: { type: "string" },
+	evidence: { $ref: "#/definitions/evidence" },
+	tags: { type: "array", items: { type: "string" } },
+	relates_to: linkArray,
+	supersedes: linkArray,
+	outcomes: { type: "array", items: { $ref: "#/definitions/outcome" } },
+	dir_anchors: { type: "array", items: { type: "string" } },
+	supersession_demoted_at: { type: "string" },
+	anchor_decay_demoted_at: { type: "string" },
+	owner: { type: "string" },
+	// "archived" is intentionally absent — soft-archived records bypass AJV
+	// (they live under .loam/archive/) and live records may not carry it.
+	status: { type: "string", enum: ["draft", "active", "deprecated"] },
+} as const;
+
+// --- convention ---
+
+const conventionDef: TypeDefinition = {
+	name: "convention",
+	kind: "builtin",
+	required: ["content"],
+	optional: [],
+	dedupKey: "content",
+	idKey: "content",
+	summary: (r) => truncate((r as ConventionRecord).content, 60),
+	extractsFiles: false,
+	filesField: "files",
+	compact: "concat",
+	sectionTitle: "Conventions",
+	ajvSchema: {
+		type: "object",
+		properties: {
+			...baseSchemaProps,
+			type: { type: "string", const: "convention" },
+			content: { type: "string" },
+		},
+		required: ["type", "content", "classification", "recorded_at"],
+		additionalProperties: false,
+	},
+	formatMarkdown: (records, full) => {
+		if (records.length === 0) return "";
+		const lines = ["### Conventions"];
+		for (const rec of records as ConventionRecord[]) {
+			lines.push(`- ${idTag(rec)}${rec.content}${formatRecordMeta(rec, full)}`);
+		}
+		return lines.join("\n");
+	},
+	formatCompactLine: (record) => {
+		const r = record as ConventionRecord;
+		const links = formatLinks(r);
+		const meta = compactMeta(r);
+		const outcome = formatOutcome(r.outcomes);
+		return `- [convention] ${truncate(r.content)}${meta}${outcome}${links}`;
+	},
+	formatXml: (record) => {
+		const r = record as ConventionRecord;
+		return [`    ${xmlEscape(r.content)}`];
+	},
+};
+
+// --- pattern ---
+
+const patternDef: TypeDefinition = {
+	name: "pattern",
+	kind: "builtin",
+	required: ["name", "description"],
+	optional: ["files"],
+	dedupKey: "name",
+	idKey: "name",
+	summary: (r) => (r as PatternRecord).name,
+	extractsFiles: true,
+	filesField: "files",
+	compact: "concat",
+	sectionTitle: "Patterns",
+	ajvSchema: {
+		type: "object",
+		properties: {
+			...baseSchemaProps,
+			type: { type: "string", const: "pattern" },
+			name: { type: "string" },
+			description: { type: "string" },
+			files: { type: "array", items: { type: "string" } },
+		},
+		required: ["type", "name", "description", "classification", "recorded_at"],
+		additionalProperties: false,
+	},
+	formatMarkdown: (records, full) => {
+		if (records.length === 0) return "";
+		const lines = ["### Patterns"];
+		for (const rec of records as PatternRecord[]) {
+			let line = `- ${idTag(rec)}**${rec.name}**: ${rec.description}`;
+			if (rec.files && rec.files.length > 0) {
+				line += ` (${rec.files.join(", ")})`;
+			}
+			line += formatRecordMeta(rec, full);
+			lines.push(line);
+		}
+		return lines.join("\n");
+	},
+	formatCompactLine: (record) => {
+		const r = record as PatternRecord;
+		const links = formatLinks(r);
+		const meta = compactMeta(r);
+		const outcome = formatOutcome(r.outcomes);
+		const files = r.files && r.files.length > 0 ? ` (${r.files.join(", ")})` : "";
+		return `- [pattern] ${r.name}: ${truncate(r.description)}${files}${meta}${outcome}${links}`;
+	},
+	formatXml: (record) => {
+		const r = record as PatternRecord;
+		const lines: string[] = [];
+		lines.push(`    <name>${xmlEscape(r.name)}</name>`);
+		lines.push(`    <description>${xmlEscape(r.description)}</description>`);
+		if (r.files && r.files.length > 0) {
+			lines.push(`    <files>${r.files.map(xmlEscape).join(", ")}</files>`);
+		}
+		return lines;
+	},
+};
+
+// --- failure ---
+
+const failureDef: TypeDefinition = {
+	name: "failure",
+	kind: "builtin",
+	required: ["description", "resolution"],
+	optional: [],
+	dedupKey: "description",
+	idKey: "description",
+	summary: (r) => truncate((r as FailureRecord).description, 60),
+	extractsFiles: false,
+	filesField: "files",
+	compact: "concat",
+	sectionTitle: "Known Failures",
+	ajvSchema: {
+		type: "object",
+		properties: {
+			...baseSchemaProps,
+			type: { type: "string", const: "failure" },
+			description: { type: "string" },
+			resolution: { type: "string" },
+		},
+		required: ["type", "description", "resolution", "classification", "recorded_at"],
+		additionalProperties: false,
+	},
+	formatMarkdown: (records, full) => {
+		if (records.length === 0) return "";
+		const lines = ["### Known Failures"];
+		for (const rec of records as FailureRecord[]) {
+			lines.push(`- ${idTag(rec)}${rec.description}${formatRecordMeta(rec, full)}`);
+			lines.push(`  → ${rec.resolution}`);
+		}
+		return lines.join("\n");
+	},
+	formatCompactLine: (record) => {
+		const r = record as FailureRecord;
+		const links = formatLinks(r);
+		const meta = compactMeta(r);
+		const outcome = formatOutcome(r.outcomes);
+		return `- [failure] ${truncate(r.description)} → ${truncate(r.resolution)}${meta}${outcome}${links}`;
+	},
+	formatXml: (record) => {
+		const r = record as FailureRecord;
+		return [
+			`    <description>${xmlEscape(r.description)}</description>`,
+			`    <resolution>${xmlEscape(r.resolution)}</resolution>`,
+		];
+	},
+};
+
+// --- decision ---
+
+const decisionDef: TypeDefinition = {
+	name: "decision",
+	kind: "builtin",
+	required: ["title", "rationale"],
+	optional: ["date"],
+	dedupKey: "title",
+	idKey: "title",
+	summary: (r) => (r as DecisionRecord).title,
+	extractsFiles: false,
+	filesField: "files",
+	compact: "concat",
+	sectionTitle: "Decisions",
+	ajvSchema: {
+		type: "object",
+		properties: {
+			...baseSchemaProps,
+			type: { type: "string", const: "decision" },
+			title: { type: "string" },
+			rationale: { type: "string" },
+			date: { type: "string" },
+		},
+		required: ["type", "title", "rationale", "classification", "recorded_at"],
+		additionalProperties: false,
+	},
+	formatMarkdown: (records, full) => {
+		if (records.length === 0) return "";
+		const lines = ["### Decisions"];
+		for (const rec of records as DecisionRecord[]) {
+			lines.push(`- ${idTag(rec)}**${rec.title}**: ${rec.rationale}${formatRecordMeta(rec, full)}`);
+		}
+		return lines.join("\n");
+	},
+	formatCompactLine: (record) => {
+		const r = record as DecisionRecord;
+		const links = formatLinks(r);
+		const meta = compactMeta(r);
+		const outcome = formatOutcome(r.outcomes);
+		return `- [decision] ${r.title}: ${truncate(r.rationale)}${meta}${outcome}${links}`;
+	},
+	formatXml: (record) => {
+		const r = record as DecisionRecord;
+		return [
+			`    <title>${xmlEscape(r.title)}</title>`,
+			`    <rationale>${xmlEscape(r.rationale)}</rationale>`,
+		];
+	},
+};
+
+// --- reference ---
+
+const referenceDef: TypeDefinition = {
+	name: "reference",
+	kind: "builtin",
+	required: ["name", "description"],
+	optional: ["files"],
+	dedupKey: "name",
+	idKey: "name",
+	summary: (r) => (r as ReferenceRecord).name,
+	extractsFiles: true,
+	filesField: "files",
+	compact: "concat",
+	sectionTitle: "References",
+	ajvSchema: {
+		type: "object",
+		properties: {
+			...baseSchemaProps,
+			type: { type: "string", const: "reference" },
+			name: { type: "string" },
+			description: { type: "string" },
+			files: { type: "array", items: { type: "string" } },
+		},
+		required: ["type", "name", "description", "classification", "recorded_at"],
+		additionalProperties: false,
+	},
+	formatMarkdown: (records, full) => {
+		if (records.length === 0) return "";
+		const lines = ["### References"];
+		for (const rec of records as ReferenceRecord[]) {
+			let line = `- ${idTag(rec)}**${rec.name}**: ${rec.description}`;
+			if (rec.files && rec.files.length > 0) {
+				line += ` (${rec.files.join(", ")})`;
+			}
+			line += formatRecordMeta(rec, full);
+			lines.push(line);
+		}
+		return lines.join("\n");
+	},
+	formatCompactLine: (record) => {
+		const r = record as ReferenceRecord;
+		const links = formatLinks(r);
+		const meta = compactMeta(r);
+		const outcome = formatOutcome(r.outcomes);
+		const refFiles =
+			r.files && r.files.length > 0 ? `: ${r.files.join(", ")}` : `: ${truncate(r.description)}`;
+		return `- [reference] ${r.name}${refFiles}${meta}${outcome}${links}`;
+	},
+	formatXml: (record) => {
+		const r = record as ReferenceRecord;
+		const lines: string[] = [];
+		lines.push(`    <name>${xmlEscape(r.name)}</name>`);
+		lines.push(`    <description>${xmlEscape(r.description)}</description>`);
+		if (r.files && r.files.length > 0) {
+			lines.push(`    <files>${r.files.map(xmlEscape).join(", ")}</files>`);
+		}
+		return lines;
+	},
+};
+
+// --- guide ---
+
+const guideDef: TypeDefinition = {
+	name: "guide",
+	kind: "builtin",
+	required: ["name", "description"],
+	optional: [],
+	dedupKey: "name",
+	idKey: "name",
+	summary: (r) => (r as GuideRecord).name,
+	extractsFiles: false,
+	filesField: "files",
+	compact: "concat",
+	sectionTitle: "Guides",
+	ajvSchema: {
+		type: "object",
+		properties: {
+			...baseSchemaProps,
+			type: { type: "string", const: "guide" },
+			name: { type: "string" },
+			description: { type: "string" },
+		},
+		required: ["type", "name", "description", "classification", "recorded_at"],
+		additionalProperties: false,
+	},
+	formatMarkdown: (records, full) => {
+		if (records.length === 0) return "";
+		const lines = ["### Guides"];
+		for (const rec of records as GuideRecord[]) {
+			lines.push(
+				`- ${idTag(rec)}**${rec.name}**: ${rec.description}${formatRecordMeta(rec, full)}`,
+			);
+		}
+		return lines.join("\n");
+	},
+	formatCompactLine: (record) => {
+		const r = record as GuideRecord;
+		const links = formatLinks(r);
+		const meta = compactMeta(r);
+		const outcome = formatOutcome(r.outcomes);
+		return `- [guide] ${r.name}: ${truncate(r.description)}${meta}${outcome}${links}`;
+	},
+	formatXml: (record) => {
+		const r = record as GuideRecord;
+		return [
+			`    <name>${xmlEscape(r.name)}</name>`,
+			`    <description>${xmlEscape(r.description)}</description>`,
+		];
+	},
+};
+
+// Section enumeration order for markdown rendering. Matches the historical
+// order in formatDomainExpertise so output stays byte-identical.
+export const BUILTIN_DEFS: readonly TypeDefinition[] = [
+	conventionDef,
+	patternDef,
+	failureDef,
+	decisionDef,
+	referenceDef,
+	guideDef,
+] as const;
+
+export function buildBuiltinRegistry(): TypeRegistry {
+	return new TypeRegistry([...BUILTIN_DEFS], SHARED_DEFINITIONS);
+}
+
+// Re-export helper for downstream cast-assertion sites:
+export type AnyRecord = ExpertiseRecord;