@ag-eco/agentplate-cli 0.13.0

package/src/tools/loam/utils/config.ts

@@ -0,0 +1,344 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import yaml from "js-yaml";
+import type { DomainConfig, LoamConfig } from "../schemas/config.ts";
+import { DEFAULT_CONFIG } from "../schemas/config.ts";
+import { createExpertiseFile } from "./expertise.ts";
+
+const LOAM_DIR = ".loam";
+const CONFIG_FILE = "loam.config.yaml";
+const EXPERTISE_DIR = "expertise";
+
+export const GITATTRIBUTES_LINE = ".loam/expertise/*.jsonl merge=union";
+
+const INIT_CONFIG_HEADER = `# Loam configuration. See https://github.com/hgoudat/loam for docs.
+#
+# Required fields below. Optional knobs are commented out at the bottom — uncomment
+# to enable. Note: commands that mutate this file (e.g. \`lm add <domain>\`,
+# \`lm record\` auto-creating a domain) rewrite it via the YAML serializer and
+# strip these comments.
+
+`;
+
+const INIT_CONFIG_OPTIONAL_KNOBS = `
+# ─── Optional knobs (uncomment to enable) ────────────────────────────────────
+#
+# prime:
+#   # Pin \`lm prime\`'s unscoped output shape. When unset (recommended), prime
+#   # auto-flips to manifest above 100 records or 5 domains and renders full
+#   # records otherwise. Set explicitly to override both directions:
+#   #   - full     → always emit full records (skip the auto-flip)
+#   #   - manifest → always emit the domain index
+#   # --full / --manifest / scoping flags always override this on a per-call basis.
+#   default_mode: full        # one of: full, manifest
+#   # Trust-tier ranking weights for full-mode output. Sort score per record =
+#   # (★ count * star) + classification weight. Override only the knobs you
+#   # want to retune; unset fields keep their default. Higher scores surface
+#   # first; within-tier ties preserve insertion order.
+#   tier_weights:
+#     star: 100               # multiplier on the ★ confirmation count
+#     foundational: 50        # base score for foundational records
+#     tactical: 20             # base score for tactical records
+#     observational: 10        # base score for observational records
+#
+# search:
+#   # Multiplier applied to BM25 scores so records with more confirmed outcomes
+#   # rank higher. 0 disables (pure BM25). Default 0.1: a record with N successes
+#   # gets a (1 + 0.1*N) boost. Override per-call with \`lm search --no-boost\`.
+#   boost_factor: 0.1
+#
+# disabled_types:
+#   # Names of registered types (built-in or custom) that emit a deprecation
+#   # warning on write. Reads still succeed; the type stays in CLI choices so
+#   # peers in shared domains don't hard-fail. Use to retire a type gracefully.
+#   - failure
+#
+# custom_types:
+#   # Project-specific record types. Required + optional fields, dedup_key,
+#   # and a summary template. See README for the full schema.
+#   hypothesis:
+#     required: [statement, prediction]
+#     optional: [evidence_files]
+#     dedup_key: statement
+#     summary: "{statement}"   # tokens use single braces; {{statement}} also accepted
+#     # aliases: rename a field while still reading legacy on-disk records.
+#     # Map canonical (current) name → list of legacy names. At read time,
+#     # legacy fields are rewritten to canonical and dropped from the record.
+#     aliases:
+#       statement: [claim]
+#   # Inherit from a built-in type with extends:. Required/optional arrays
+#   # merge with the parent's (union); dedup_key, summary, compact, section_title,
+#   # extracts_files, and files_field override only when set, otherwise inherit.
+#   # Custom-from-custom is not supported in v1.
+#   adr:
+#     extends: decision
+#     required: [decision_status, deciders]   # added on top of decision's [title, rationale]
+#     summary: "{decision_status}: {title}"   # tokens must be declared fields (parent's included)
+#
+# hooks:
+#   # Lifecycle hook scripts. Each event maps to an ordered list of shell
+#   # commands. Loam invokes each with the relevant payload as JSON on stdin.
+#   # Exit 0 = continue. Non-zero from a \`pre-*\` hook blocks the action; from
+#   # a \`post-*\` hook emits a warning. \`pre-record\`, \`pre-prime\`, and
+#   # \`pre-compact\` may mutate the payload by printing modified JSON on
+#   # stdout; \`pre-prune\` is block-or-allow only — its stdout is ignored.
+#   #
+#   # pre-record:    [./.loam/hooks/scan-secrets.sh, ./.loam/hooks/require-owner.sh]
+#   # post-record:   [./.loam/hooks/post-to-slack.sh]
+#   # pre-prime:     [./.loam/hooks/filter-by-team.sh]
+#   # pre-prune:     [./.loam/hooks/digest-then-confirm.sh]
+#   # pre-compact:   [./.loam/hooks/llm-summarize.sh]
+#
+# hook_settings:
+#   # Per-hook execution timeout in milliseconds. Default 5000.
+#   timeout_ms: 5000
+`;
+
+export function buildInitialConfigYaml(): string {
+	const body = yaml.dump(DEFAULT_CONFIG, { lineWidth: -1 });
+	return INIT_CONFIG_HEADER + body + INIT_CONFIG_OPTIONAL_KNOBS;
+}
+
+export const LOAM_README = `# .loam/
+
+This directory is managed by [loam](https://github.com/hgoudat/loam) — a structured expertise layer for coding agents.
+
+## Key Commands
+
+- \`lm init\`      — Initialize a .loam directory
+- \`lm add\`       — Add a new domain
+- \`lm record\`    — Record an expertise record
+- \`lm edit\`      — Edit an existing record
+- \`lm query\`     — Query expertise records
+- \`lm prime [domain]\` — Output a priming prompt (optionally scoped to one domain)
+- \`lm search\`   — Search records across domains
+- \`lm status\`    — Show domain statistics
+- \`lm validate\`  — Validate all records against the schema
+- \`lm prune\`     — Remove expired records
+
+## Structure
+
+- \`loam.config.yaml\` — Configuration file
+- \`expertise/\`        — JSONL files, one per domain
+
+## Configuration
+
+Optional knobs in \`loam.config.yaml\`:
+
+\`\`\`yaml
+prime:
+  default_mode: manifest   # or "full". Omit to let \`lm prime\` auto-flip:
+                           # full output until the corpus exceeds 100 records
+                           # or 5 domains, then manifest. Set explicitly to pin
+                           # one mode. Scoping flags (\`--files\`, \`<domain>\`)
+                           # always force full.
+
+search:
+  boost_factor: 0.1        # multiplier on BM25 scores for confirmed records.
+                           # 0 disables (pure BM25). Override with
+                           # \`lm search --no-boost\`.
+\`\`\`
+`;
+
+function gitCommonDir(cwd: string): string | null {
+	try {
+		const raw = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+			cwd,
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+		if (!raw) return null;
+		return resolve(cwd, raw);
+	} catch {
+		return null;
+	}
+}
+
+function resolveWorktreeRoot(cwd: string): string {
+	const common = gitCommonDir(cwd);
+	if (!common) return cwd;
+
+	// .git/worktrees/<name> → strip to repo root; .git → already main
+	const mainRoot = common.endsWith(".git") ? dirname(common) : dirname(dirname(common));
+	const mainResolved = resolve(mainRoot);
+
+	if (mainResolved === resolve(cwd)) return cwd;
+
+	// Only redirect if main repo has a .loam/ with config
+	const mainLoamConfig = join(mainResolved, LOAM_DIR, CONFIG_FILE);
+	if (existsSync(mainLoamConfig)) {
+		return mainResolved;
+	}
+
+	return cwd;
+}
+
+export function isInsideWorktree(cwd: string = process.cwd()): boolean {
+	const common = gitCommonDir(cwd);
+	if (!common) return false;
+
+	// For actual worktrees, --git-common-dir always returns the main .git dir
+	// (ends with ".git"). Submodules return /parent/.git/modules/<name> which
+	// does NOT end with ".git" — those are not worktrees, avoid false positive.
+	if (!common.endsWith(".git")) return false;
+
+	const mainRoot = dirname(common);
+	return resolve(mainRoot) !== resolve(cwd);
+}
+
+export function getLoamDir(cwd: string = process.cwd()): string {
+	return join(resolveWorktreeRoot(cwd), LOAM_DIR);
+}
+
+export function getConfigPath(cwd: string = process.cwd()): string {
+	return join(getLoamDir(cwd), CONFIG_FILE);
+}
+
+export function getExpertiseDir(cwd: string = process.cwd()): string {
+	return join(getLoamDir(cwd), EXPERTISE_DIR);
+}
+
+export function validateDomainName(domain: string): void {
+	if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(domain)) {
+		throw new Error(
+			`Invalid domain name: "${domain}". Only alphanumeric characters, hyphens, and underscores are allowed.`,
+		);
+	}
+}
+
+export function getExpertisePath(domain: string, cwd: string = process.cwd()): string {
+	validateDomainName(domain);
+	return join(getExpertiseDir(cwd), `${domain}.jsonl`);
+}
+
+// Legacy on-disk shape was `domains: [a, b]`; current shape is
+// `domains: { a: {}, b: {} }`. Normalize both to the object map at read time so
+// older configs keep working without user migration.
+function normalizeDomains(raw: unknown): Record<string, DomainConfig> {
+	if (Array.isArray(raw)) {
+		const map: Record<string, DomainConfig> = {};
+		for (const name of raw) {
+			if (typeof name === "string") map[name] = {};
+		}
+		return map;
+	}
+	if (raw && typeof raw === "object") return raw as Record<string, DomainConfig>;
+	return {};
+}
+
+// Backfill required-by-type top-level sections that a hand-written minimal
+// config may omit. Schema marks `governance` and `classification_defaults` as
+// required, but consumers (doctor, prune, status, compact, prime) destructure
+// them directly and would otherwise crash with a TypeError on a config that
+// only declares `domains:`. Shallow-merge so partial user overrides
+// (e.g. `governance: { max_entries: 50 }`) keep the other defaults.
+function applyConfigDefaults(parsed: LoamConfig): LoamConfig {
+	const userGov = (parsed.governance ?? {}) as Partial<LoamConfig["governance"]>;
+	const userCD = (parsed.classification_defaults ?? {}) as Partial<
+		LoamConfig["classification_defaults"]
+	>;
+	const userShelf = (userCD.shelf_life ?? {}) as Partial<
+		LoamConfig["classification_defaults"]["shelf_life"]
+	>;
+	parsed.governance = { ...DEFAULT_CONFIG.governance, ...userGov };
+	parsed.classification_defaults = {
+		shelf_life: { ...DEFAULT_CONFIG.classification_defaults.shelf_life, ...userShelf },
+	};
+	return parsed;
+}
+
+export async function readConfig(cwd: string = process.cwd()): Promise<LoamConfig> {
+	const configPath = getConfigPath(cwd);
+	let content: string;
+	try {
+		content = await readFile(configPath, "utf-8");
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+			throw new Error("No .loam/ directory found. Run `loam init` to set up this project.");
+		}
+		throw err;
+	}
+	let parsed: LoamConfig;
+	try {
+		parsed = (yaml.load(content) ?? {}) as LoamConfig;
+	} catch (err) {
+		throw new Error(
+			`Failed to parse loam.config.yaml: ${(err as Error).message}. Check the YAML syntax.`,
+		);
+	}
+	if (!parsed || typeof parsed !== "object") {
+		// Empty file or scalar at top level — treat as empty object so defaults apply.
+		parsed = {} as LoamConfig;
+	}
+	parsed.domains = normalizeDomains(parsed.domains);
+	return applyConfigDefaults(parsed);
+}
+
+export async function addDomain(domain: string, cwd: string = process.cwd()): Promise<void> {
+	validateDomainName(domain);
+	const config = await readConfig(cwd);
+	if (!(domain in config.domains)) {
+		config.domains[domain] = {};
+		await writeConfig(config, cwd);
+	}
+	const filePath = getExpertisePath(domain, cwd);
+	if (!existsSync(filePath)) {
+		await createExpertiseFile(filePath);
+	}
+}
+
+export async function removeDomain(domain: string, cwd: string = process.cwd()): Promise<void> {
+	validateDomainName(domain);
+	const config = await readConfig(cwd);
+	if (!(domain in config.domains)) {
+		throw new Error(`Domain "${domain}" not found in config.`);
+	}
+	delete config.domains[domain];
+	await writeConfig(config, cwd);
+	const filePath = getExpertisePath(domain, cwd);
+	if (existsSync(filePath)) {
+		await rm(filePath);
+	}
+}
+
+export async function writeConfig(config: LoamConfig, cwd: string = process.cwd()): Promise<void> {
+	const configPath = getConfigPath(cwd);
+	const content = yaml.dump(config, { lineWidth: -1 });
+	await writeFile(configPath, content, "utf-8");
+}
+
+export async function initLoamDir(cwd: string = process.cwd()): Promise<void> {
+	const loamDir = getLoamDir(cwd);
+	const expertiseDir = getExpertiseDir(cwd);
+	await mkdir(loamDir, { recursive: true });
+	await mkdir(expertiseDir, { recursive: true });
+
+	// Only write default config if none exists — preserve user customizations.
+	// Use the templated YAML (with commented-out optional knobs) for discoverability;
+	// subsequent writes via writeConfig() round-trip through yaml.dump and lose comments.
+	const configPath = getConfigPath(cwd);
+	if (!existsSync(configPath)) {
+		await writeFile(configPath, buildInitialConfigYaml(), "utf-8");
+	}
+
+	// Create or append .gitattributes with merge=union for JSONL files
+	const gitattributesPath = join(cwd, ".gitattributes");
+	let existing = "";
+	try {
+		existing = await readFile(gitattributesPath, "utf-8");
+	} catch {
+		// File doesn't exist yet — will create it
+	}
+	if (!existing.includes(GITATTRIBUTES_LINE)) {
+		const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+		await writeFile(gitattributesPath, `${existing + separator + GITATTRIBUTES_LINE}\n`, "utf-8");
+	}
+
+	// Create .loam/README.md if missing
+	const readmePath = join(loamDir, "README.md");
+	if (!existsSync(readmePath)) {
+		await writeFile(readmePath, LOAM_README, "utf-8");
+	}
+}

package/src/tools/loam/utils/dir-anchors.ts

@@ -0,0 +1,62 @@
+// Repo-relative POSIX paths. Strip trailing slashes and a leading "./", coerce
+// repo-root markers ("." / "" / "./") to "" so they're filtered out of stored
+// anchors (meaningless to anchor at the repo root). Tolerant of legacy values
+// on disk: never throws — see assertWritableDirAnchor for write-time validation
+// (which rejects absolute paths and parent-traversal segments).
+export function normalizeDirAnchor(input: string): string {
+	let v = input.trim();
+	if (v === "" || v === ".") return "";
+	v = v.replace(/\\+/g, "/");
+	v = v.replace(/\/+$/, "");
+	if (v.startsWith("./")) v = v.slice(2);
+	v = v.replace(/\/+$/, "");
+	if (v === "" || v === ".") return "";
+	return v;
+}
+
+// Throws if the input is unsafe to store as a project-root-relative anchor:
+// absolute paths (`/etc/passwd`, `C:\…`) and parent-traversal segments (`..`)
+// would silently break lm prime/--files matching, doctor's existsSync probe,
+// and anchor-validity decay. Called at write time (lm record / lm edit) so
+// invalid input surfaces as a formatted error before it lands on disk.
+export function assertWritableDirAnchor(raw: string): void {
+	const v = raw.trim();
+	if (v.length === 0) return;
+	if (/^[a-zA-Z]:[\\/]/.test(v) || v.startsWith("/") || v.startsWith("\\")) {
+		throw new Error(
+			`dir-anchor "${raw}" is an absolute path. Use a project-root-relative path like "src/utils".`,
+		);
+	}
+	const segments = v.replace(/\\+/g, "/").split("/");
+	if (segments.includes("..")) {
+		throw new Error(
+			`dir-anchor "${raw}" contains ".." (parent traversal). Anchors must stay inside the project root.`,
+		);
+	}
+}
+
+export function fileLivesUnderDir(file: string, dir: string): boolean {
+	const f = file.replace(/\\+/g, "/");
+	const d = normalizeDirAnchor(dir);
+	if (d === "") return true;
+	return f === d || f.startsWith(`${d}/`);
+}
+
+// Heuristic: any directory that is the parent of >= threshold changed files
+// becomes a dir anchor. Returns the deepest such directories, deduped and sorted.
+// Threshold default of 3 keeps single-file edits and pair-edits from generating
+// noisy anchors.
+export function inferDirAnchors(files: string[], threshold = 3): string[] {
+	const counts = new Map<string, number>();
+	for (const raw of files) {
+		const f = raw.replace(/\\+/g, "/");
+		const i = f.lastIndexOf("/");
+		if (i <= 0) continue;
+		const dir = f.substring(0, i);
+		counts.set(dir, (counts.get(dir) ?? 0) + 1);
+	}
+	return [...counts.entries()]
+		.filter(([, c]) => c >= threshold)
+		.map(([d]) => d)
+		.sort();
+}

package/src/tools/loam/utils/domain-rules.ts

@@ -0,0 +1,114 @@
+// Per-domain rule helpers shared across record (write-time gate), validate
+// and sync (read-time re-validation), and doctor (diagnostic surfacing).
+// Empty/missing arrays mean "no rule" — back-compat with pre-R-01 configs.
+
+import type { ErrorObject } from "ajv";
+import type { TypeRegistry } from "../registry/type-registry.ts";
+import type { LoamConfig } from "../schemas/config.ts";
+
+export function getAllowedTypes(config: LoamConfig, domain: string): string[] | null {
+	const list = config.domains[domain]?.allowed_types;
+	if (!list || list.length === 0) return null;
+	return list;
+}
+
+export function getRequiredFields(config: LoamConfig, domain: string): string[] | null {
+	const list = config.domains[domain]?.required_fields;
+	if (!list || list.length === 0) return null;
+	return list;
+}
+
+// Return the subset of `fields` that are missing or empty on the record.
+// Treats undefined/null/""/empty-array as missing. Top-level field names only;
+// nested paths are out of scope for v1.
+export function findMissingDomainFields(
+	record: Record<string, unknown>,
+	fields: string[],
+): string[] {
+	const missing: string[] = [];
+	for (const field of fields) {
+		const value = record[field];
+		if (
+			value === undefined ||
+			value === null ||
+			value === "" ||
+			(Array.isArray(value) && value.length === 0)
+		) {
+			missing.push(field);
+		}
+	}
+	return missing;
+}
+
+// Fields owned by BaseRecord — accepted by every type's schema (built-in or
+// custom). A domain.required_fields entry naming one of these is always
+// compatible regardless of allowed_types.
+const BASE_RECORD_FIELDS: ReadonlySet<string> = new Set([
+	"id",
+	"type",
+	"classification",
+	"recorded_at",
+	"evidence",
+	"tags",
+	"relates_to",
+	"supersedes",
+	"outcomes",
+	"dir_anchors",
+	"supersession_demoted_at",
+	"owner",
+	"status",
+]);
+
+// Detect required_fields entries that no allowed type can hold. Built-in (and
+// custom) record schemas use `additionalProperties: false`, so a domain that
+// requires a field which isn't declared on any of its allowed types is
+// unsatisfiable: every write fails AJV before the domain gate runs. Returns
+// one entry per offending field with the resolved allowed-type names so
+// callers can render a fix-it hint.
+export function findIncompatibleRequiredFields(
+	config: LoamConfig,
+	domain: string,
+	registry: TypeRegistry,
+): Array<{ field: string; allowedTypes: string[] }> {
+	const required = getRequiredFields(config, domain);
+	if (!required) return [];
+	const allowedTypeNames = getAllowedTypes(config, domain) ?? registry.names();
+	const incompatible: Array<{ field: string; allowedTypes: string[] }> = [];
+	for (const field of required) {
+		if (BASE_RECORD_FIELDS.has(field)) continue;
+		let acceptedByAny = false;
+		for (const name of allowedTypeNames) {
+			const def = registry.get(name);
+			if (!def) continue;
+			if (def.required.includes(field) || def.optional.includes(field)) {
+				acceptedByAny = true;
+				break;
+			}
+		}
+		if (!acceptedByAny) {
+			incompatible.push({ field, allowedTypes: [...allowedTypeNames] });
+		}
+	}
+	return incompatible;
+}
+
+// Scan AJV errors for `additionalProperties` rejections whose property name is
+// listed in domain.required_fields. Returns the deduped set of such field
+// names so the caller can render a targeted hint instead of the raw AJV soup.
+export function findRejectedRequiredFields(
+	errors: readonly ErrorObject[] | null | undefined,
+	requiredFields: readonly string[] | null,
+): string[] {
+	if (!errors || !requiredFields || requiredFields.length === 0) return [];
+	const requiredSet = new Set(requiredFields);
+	const rejected = new Set<string>();
+	for (const err of errors) {
+		if (err.keyword !== "additionalProperties") continue;
+		const params = err.params as { additionalProperty?: unknown };
+		const prop = params.additionalProperty;
+		if (typeof prop === "string" && requiredSet.has(prop)) {
+			rejected.add(prop);
+		}
+	}
+	return [...rejected];
+}