@ag-eco/agentplate-cli 0.13.0

package/src/test-helpers.test.ts

@@ -0,0 +1,124 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { cleanupTempDir, commitFile, createTempGitRepo } from "./test-helpers.ts";
+
+describe("createTempGitRepo", () => {
+	let repoDir: string | undefined;
+
+	afterEach(async () => {
+		if (repoDir) {
+			await cleanupTempDir(repoDir);
+			repoDir = undefined;
+		}
+	});
+
+	test("creates a directory with an initialized git repo", async () => {
+		repoDir = await createTempGitRepo();
+
+		expect(existsSync(join(repoDir, ".git"))).toBe(true);
+	});
+
+	test("repo has at least one commit (HEAD exists)", async () => {
+		repoDir = await createTempGitRepo();
+
+		const proc = Bun.spawn(["git", "rev-parse", "HEAD"], {
+			cwd: repoDir,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const exitCode = await proc.exited;
+
+		expect(exitCode).toBe(0);
+	});
+
+	test("repo is on a branch (not detached HEAD)", async () => {
+		repoDir = await createTempGitRepo();
+
+		const proc = Bun.spawn(["git", "symbolic-ref", "HEAD"], {
+			cwd: repoDir,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const stdout = await new Response(proc.stdout).text();
+		const exitCode = await proc.exited;
+
+		expect(exitCode).toBe(0);
+		expect(stdout.trim()).toMatch(/^refs\/heads\//);
+	});
+});
+
+describe("commitFile", () => {
+	let repoDir: string | undefined;
+
+	afterEach(async () => {
+		if (repoDir) {
+			await cleanupTempDir(repoDir);
+			repoDir = undefined;
+		}
+	});
+
+	test("creates file and commits it", async () => {
+		repoDir = await createTempGitRepo();
+
+		await commitFile(repoDir, "hello.txt", "world");
+
+		// File exists with correct content
+		const content = await readFile(join(repoDir, "hello.txt"), "utf-8");
+		expect(content).toBe("world");
+
+		// Git log shows the commit
+		const proc = Bun.spawn(["git", "log", "--oneline"], {
+			cwd: repoDir,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const stdout = await new Response(proc.stdout).text();
+		await proc.exited;
+
+		expect(stdout).toContain("add hello.txt");
+	});
+
+	test("creates nested directories as needed", async () => {
+		repoDir = await createTempGitRepo();
+
+		await commitFile(repoDir, "src/deep/nested/file.ts", "export const x = 1;");
+
+		expect(existsSync(join(repoDir, "src/deep/nested/file.ts"))).toBe(true);
+	});
+
+	test("uses custom commit message when provided", async () => {
+		repoDir = await createTempGitRepo();
+
+		await commitFile(repoDir, "readme.md", "# Hi", "docs: add readme");
+
+		const proc = Bun.spawn(["git", "log", "--oneline", "-1"], {
+			cwd: repoDir,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const stdout = await new Response(proc.stdout).text();
+		await proc.exited;
+
+		expect(stdout).toContain("docs: add readme");
+	});
+});
+
+describe("cleanupTempDir", () => {
+	test("removes directory and all contents", async () => {
+		const repoDir = await createTempGitRepo();
+		await commitFile(repoDir, "file.txt", "data");
+
+		expect(existsSync(repoDir)).toBe(true);
+
+		await cleanupTempDir(repoDir);
+
+		expect(existsSync(repoDir)).toBe(false);
+	});
+
+	test("does not throw when directory does not exist", async () => {
+		await cleanupTempDir("/tmp/agentplate-nonexistent-test-dir-12345");
+		// No error thrown = pass
+	});
+});

package/src/test-helpers.ts

@@ -0,0 +1,145 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Git environment variables for test repos.
+ * Using env vars instead of per-repo `git config` eliminates 2 subprocess
+ * spawns per repo creation.
+ */
+const GIT_TEST_ENV = {
+	GIT_AUTHOR_NAME: "Agentplate Test",
+	GIT_AUTHOR_EMAIL: "test@agentplate.dev",
+	GIT_COMMITTER_NAME: "Agentplate Test",
+	GIT_COMMITTER_EMAIL: "test@agentplate.dev",
+};
+
+/** Cached template repo path. Created lazily on first call. */
+let _templateDir: string | null = null;
+
+/**
+ * Get or create a template git repo with an initial commit.
+ * All test repos clone from this template (1 subprocess instead of 5).
+ */
+async function getTemplateRepo(): Promise<string> {
+	if (_templateDir) return _templateDir;
+
+	const dir = await mkdtemp(join(tmpdir(), "agentplate-template-"));
+	await runGitInDir(dir, ["init", "-b", "main"]);
+	await Bun.write(join(dir, ".gitkeep"), "");
+	await runGitInDir(dir, ["add", ".gitkeep"]);
+	await runGitInDir(dir, ["commit", "-m", "initial commit"]);
+
+	_templateDir = dir;
+	return dir;
+}
+
+/**
+ * Create a temporary directory with a real git repo initialized.
+ * Includes an initial commit so branches can be created immediately.
+ *
+ * Uses a cached template repo + `git clone --local` for speed:
+ * 1 subprocess per call instead of 5.
+ *
+ * @returns The absolute path to the temp git repo.
+ */
+export async function createTempGitRepo(): Promise<string> {
+	const template = await getTemplateRepo();
+	const dir = await mkdtemp(join(tmpdir(), "agentplate-test-"));
+	// Clone into the empty dir. Avoid --local (hardlinks trigger EFAULT in Bun's rm).
+	await runGitInDir(".", ["clone", template, dir]);
+	// Set git identity at repo level so code that doesn't use GIT_TEST_ENV
+	// (e.g., resolver's runGit) can still commit. Locally this is covered by
+	// ~/.gitconfig, but CI runners have no global git identity.
+	await runGitInDir(dir, ["config", "user.name", "Agentplate Test"]);
+	await runGitInDir(dir, ["config", "user.email", "test@agentplate.dev"]);
+	return dir;
+}
+
+/**
+ * Add and commit a file to a git repo.
+ *
+ * @param repoDir - Absolute path to the git repo
+ * @param filePath - Relative path within the repo (e.g. "src/foo.ts")
+ * @param content - File content to write
+ * @param message - Commit message (defaults to "add {filePath}")
+ */
+export async function commitFile(
+	repoDir: string,
+	filePath: string,
+	content: string,
+	message?: string,
+): Promise<void> {
+	const fullPath = join(repoDir, filePath);
+
+	// Ensure parent directories exist
+	const parentDir = join(fullPath, "..");
+	const { mkdir } = await import("node:fs/promises");
+	await mkdir(parentDir, { recursive: true });
+
+	await Bun.write(fullPath, content);
+	await runGitInDir(repoDir, ["add", filePath]);
+	await runGitInDir(repoDir, ["commit", "-m", message ?? `add ${filePath}`]);
+}
+
+/**
+ * Get the default branch name of a git repo (e.g., "main" or "master").
+ * Uses `git symbolic-ref --short HEAD` to read the current branch.
+ *
+ * Useful in tests to avoid hardcoding "main" -- CI runners may default to "master".
+ */
+export async function getDefaultBranch(repoDir: string): Promise<string> {
+	const stdout = await runGitInDir(repoDir, ["symbolic-ref", "--short", "HEAD"]);
+	return stdout.trim();
+}
+
+/**
+ * Remove a temp directory. Safe to call even if the directory doesn't exist.
+ *
+ * On Windows, SQLite WAL/SHM file handles may linger briefly after db.close(),
+ * causing EBUSY errors on immediate rm(). Retries with exponential backoff
+ * (up to ~1.5s total) to handle this OS-level timing issue.
+ */
+export async function cleanupTempDir(dir: string): Promise<void> {
+	const maxRetries = process.platform === "win32" ? 5 : 0;
+	for (let attempt = 0; attempt <= maxRetries; attempt++) {
+		try {
+			await rm(dir, { recursive: true, force: true });
+			return;
+		} catch (err: unknown) {
+			const code = (err as NodeJS.ErrnoException).code;
+			if (code === "EBUSY" && attempt < maxRetries) {
+				// Exponential backoff: 50, 100, 200, 400, 800ms
+				await Bun.sleep(50 * 2 ** attempt);
+				continue;
+			}
+			// Non-EBUSY or final attempt: swallow (temp dirs are cleaned by OS anyway)
+			if (code !== "ENOENT") return;
+		}
+	}
+}
+
+/**
+ * Run a git command in the given directory. Throws on non-zero exit.
+ * Passes GIT_AUTHOR/COMMITTER env vars so repos don't need per-repo config.
+ */
+export async function runGitInDir(cwd: string, args: string[]): Promise<string> {
+	const proc = Bun.spawn(["git", ...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+		env: { ...process.env, ...GIT_TEST_ENV },
+	});
+
+	const [stdout, stderr, exitCode] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+		proc.exited,
+	]);
+
+	if (exitCode !== 0) {
+		throw new Error(`git ${args.join(" ")} failed (exit ${exitCode}): ${stderr.trim()}`);
+	}
+
+	return stdout;
+}

package/src/test-setup.test.ts

@@ -0,0 +1,31 @@
+/**
+ * Regression test for agentplate-6d42: bun test must not be redirectable to a
+ * real .agentplate/ via inherited AGENTPLATE_PROJECT_ROOT (or sibling) env vars.
+ *
+ * The preload in bunfig.toml runs src/test-setup.ts before any test loads,
+ * deleting AGENTPLATE_* env vars and clearing the project-root override. By
+ * the time this test executes, those values must already be gone — even if a
+ * worker agent's environment had them set when bun test was invoked.
+ */
+
+import { expect, test } from "bun:test";
+import { getProjectRootOverride } from "./config.ts";
+
+const ENV_KEYS = [
+	"AGENTPLATE_PROJECT_ROOT",
+	"AGENTPLATE_AGENT_NAME",
+	"AGENTPLATE_WORKTREE_PATH",
+	"AGENTPLATE_TASK_ID",
+	"AGENTPLATE_PROFILE",
+	"AGENTPLATE_RUN_ID",
+] as const;
+
+for (const key of ENV_KEYS) {
+	test(`${key} is unset by the test preload`, () => {
+		expect(process.env[key]).toBeUndefined();
+	});
+}
+
+test("project-root override is cleared by the test preload", () => {
+	expect(getProjectRootOverride()).toBeUndefined();
+});

package/src/test-setup.ts

@@ -0,0 +1,28 @@
+/**
+ * Global test preload (referenced from bunfig.toml [test] preload).
+ *
+ * Prevents test runs from leaking into a real .agentplate/ when bun test is
+ * executed inside an agent worktree (where ap sling injects AGENTPLATE_PROJECT_ROOT
+ * into the spawned process — see src/commands/sling.ts:928).
+ *
+ * Without this preload, resolveProjectRoot() short-circuits to the env var
+ * before consulting the per-test temp dir, so tests calling cleanCommand,
+ * coordinatorCommand, mailCommand, etc. silently target the live project.
+ * That's how agentplate-6d42 contamination occurred: a worker agent ran
+ * bun test, clean.test.ts wiped the live .agentplate/, coordinator.test.ts
+ * left dozens of bogus runs, and mail.test.ts inserted fixture messages.
+ *
+ * Tests that need AGENTPLATE_PROJECT_ROOT set (e.g. config.test.ts) set it
+ * explicitly inside the test body and restore it in afterEach.
+ */
+
+import { clearProjectRootOverride } from "./config.ts";
+
+delete process.env.AGENTPLATE_PROJECT_ROOT;
+delete process.env.AGENTPLATE_AGENT_NAME;
+delete process.env.AGENTPLATE_WORKTREE_PATH;
+delete process.env.AGENTPLATE_TASK_ID;
+delete process.env.AGENTPLATE_PROFILE;
+delete process.env.AGENTPLATE_RUN_ID;
+
+clearProjectRootOverride();

package/src/tools/loam/api.ts

@@ -0,0 +1,368 @@
+import type { Classification, ExpertiseRecord, Outcome } from "./schemas/record.ts";
+import { getExpertisePath, readConfig } from "./utils/config.ts";
+import {
+	appendRecord,
+	filterByClassification,
+	filterByFile,
+	filterByType,
+	findDuplicate,
+	readExpertiseFile,
+	resolveRecordId,
+	searchRecords,
+	writeExpertiseFile,
+} from "./utils/expertise.ts";
+import { withFileLock } from "./utils/lock.ts";
+
+export interface RecordOptions {
+	force?: boolean;
+	cwd?: string;
+}
+
+export interface RecordResult {
+	action: "created" | "updated" | "skipped";
+	record: ExpertiseRecord;
+}
+
+export interface SearchOptions {
+	domain?: string;
+	type?: string;
+	tag?: string;
+	classification?: string;
+	file?: string;
+	cwd?: string;
+}
+
+export interface SearchResult {
+	domain: string;
+	records: ExpertiseRecord[];
+}
+
+export interface QueryOptions {
+	type?: string;
+	classification?: string;
+	file?: string;
+	cwd?: string;
+}
+
+export interface EditOptions {
+	cwd?: string;
+}
+
+export interface OutcomeOptions {
+	cwd?: string;
+}
+
+export interface AppendOutcomeResult {
+	record: ExpertiseRecord;
+	outcome: Outcome;
+	total_outcomes: number;
+}
+
+export interface RecordUpdates {
+	classification?: Classification;
+	tags?: string[];
+	relates_to?: string[];
+	supersedes?: string[];
+	outcomes?: Outcome[];
+	// type-specific fields
+	content?: string;
+	name?: string;
+	description?: string;
+	resolution?: string;
+	title?: string;
+	rationale?: string;
+	files?: string[];
+}
+
+/**
+ * Record an expertise record in the given domain.
+ * Named record types (pattern, decision, reference, guide) are upserted on
+ * duplicate key; convention and failure duplicates are skipped unless force=true.
+ */
+export async function recordExpertise(
+	domain: string,
+	record: ExpertiseRecord,
+	options: RecordOptions = {},
+): Promise<RecordResult> {
+	const { force = false, cwd } = options;
+
+	const config = await readConfig(cwd);
+	if (!(domain in config.domains)) {
+		throw new Error(
+			`Domain "${domain}" not found in config. Available domains: ${Object.keys(config.domains).join(", ") || "(none)"}`,
+		);
+	}
+
+	const filePath = getExpertisePath(domain, cwd);
+
+	return withFileLock(filePath, async () => {
+		const existing = await readExpertiseFile(filePath);
+		const dup = findDuplicate(existing, record);
+
+		if (dup && !force) {
+			const isNamed =
+				record.type === "pattern" ||
+				record.type === "decision" ||
+				record.type === "reference" ||
+				record.type === "guide";
+
+			if (isNamed) {
+				existing[dup.index] = record;
+				await writeExpertiseFile(filePath, existing);
+				return { action: "updated" as const, record };
+			}
+			return { action: "skipped" as const, record: dup.record };
+		}
+		await appendRecord(filePath, record);
+		return { action: "created" as const, record };
+	});
+}
+
+/**
+ * Search expertise records across domains using BM25 ranking.
+ * Returns domains with at least one matching record.
+ */
+export async function searchExpertise(
+	query: string,
+	options: SearchOptions = {},
+): Promise<SearchResult[]> {
+	const { cwd } = options;
+	const config = await readConfig(cwd);
+
+	let domainsToSearch: string[];
+	if (options.domain) {
+		if (!(options.domain in config.domains)) {
+			throw new Error(
+				`Domain "${options.domain}" not found in config. Available domains: ${Object.keys(config.domains).join(", ")}`,
+			);
+		}
+		domainsToSearch = [options.domain];
+	} else {
+		domainsToSearch = Object.keys(config.domains);
+	}
+
+	const results: SearchResult[] = [];
+
+	for (const d of domainsToSearch) {
+		const filePath = getExpertisePath(d, cwd);
+		let records = await readExpertiseFile(filePath);
+
+		if (options.type) {
+			records = filterByType(records, options.type);
+		}
+		if (options.tag) {
+			const tagLower = options.tag.toLowerCase();
+			records = records.filter((r) => r.tags?.some((t) => t.toLowerCase() === tagLower));
+		}
+		if (options.classification) {
+			records = filterByClassification(records, options.classification);
+		}
+		if (options.file) {
+			records = filterByFile(records, options.file);
+		}
+
+		const matches = searchRecords(records, query);
+		if (matches.length > 0) {
+			results.push({ domain: d, records: matches });
+		}
+	}
+
+	return results;
+}
+
+/**
+ * Query all records in a domain with optional filtering.
+ */
+export async function queryDomain(
+	domain: string,
+	options: QueryOptions = {},
+): Promise<ExpertiseRecord[]> {
+	const { cwd } = options;
+	const config = await readConfig(cwd);
+
+	if (!(domain in config.domains)) {
+		throw new Error(
+			`Domain "${domain}" not found in config. Available domains: ${Object.keys(config.domains).join(", ") || "(none)"}`,
+		);
+	}
+
+	const filePath = getExpertisePath(domain, cwd);
+	let records = await readExpertiseFile(filePath);
+
+	if (options.type) {
+		records = filterByType(records, options.type);
+	}
+	if (options.classification) {
+		records = filterByClassification(records, options.classification);
+	}
+	if (options.file) {
+		records = filterByFile(records, options.file);
+	}
+
+	return records;
+}
+
+/**
+ * Edit an existing record by ID in the given domain.
+ * Only provided fields in updates are modified; all other fields are preserved.
+ */
+export async function editRecord(
+	domain: string,
+	id: string,
+	updates: RecordUpdates,
+	options: EditOptions = {},
+): Promise<ExpertiseRecord> {
+	const { cwd } = options;
+	const config = await readConfig(cwd);
+
+	if (!(domain in config.domains)) {
+		throw new Error(
+			`Domain "${domain}" not found in config. Available domains: ${Object.keys(config.domains).join(", ") || "(none)"}`,
+		);
+	}
+
+	const filePath = getExpertisePath(domain, cwd);
+
+	return withFileLock(filePath, async () => {
+		const records = await readExpertiseFile(filePath);
+		const resolved = resolveRecordId(records, id);
+
+		if (!resolved.ok) {
+			throw new Error(resolved.error);
+		}
+
+		const targetIndex = resolved.index;
+		const original = records[targetIndex];
+		if (!original) {
+			throw new Error(`Record at index ${targetIndex} not found`);
+		}
+		const record: ExpertiseRecord = { ...original };
+
+		// Apply common updates
+		if (updates.classification !== undefined) {
+			record.classification = updates.classification;
+		}
+		if (updates.tags !== undefined) {
+			record.tags = updates.tags;
+		}
+		if (updates.relates_to !== undefined) {
+			record.relates_to = updates.relates_to;
+		}
+		if (updates.supersedes !== undefined) {
+			record.supersedes = updates.supersedes;
+		}
+		if (updates.outcomes !== undefined) {
+			record.outcomes = updates.outcomes;
+		}
+
+		// Apply type-specific updates
+		switch (record.type) {
+			case "convention":
+				if (updates.content !== undefined) {
+					record.content = updates.content;
+				}
+				break;
+			case "pattern":
+				if (updates.name !== undefined) {
+					record.name = updates.name;
+				}
+				if (updates.description !== undefined) {
+					record.description = updates.description;
+				}
+				if (updates.files !== undefined) {
+					record.files = updates.files;
+				}
+				break;
+			case "failure":
+				if (updates.description !== undefined) {
+					record.description = updates.description;
+				}
+				if (updates.resolution !== undefined) {
+					record.resolution = updates.resolution;
+				}
+				break;
+			case "decision":
+				if (updates.title !== undefined) {
+					record.title = updates.title;
+				}
+				if (updates.rationale !== undefined) {
+					record.rationale = updates.rationale;
+				}
+				break;
+			case "reference":
+				if (updates.name !== undefined) {
+					record.name = updates.name;
+				}
+				if (updates.description !== undefined) {
+					record.description = updates.description;
+				}
+				if (updates.files !== undefined) {
+					record.files = updates.files;
+				}
+				break;
+			case "guide":
+				if (updates.name !== undefined) {
+					record.name = updates.name;
+				}
+				if (updates.description !== undefined) {
+					record.description = updates.description;
+				}
+				break;
+		}
+
+		records[targetIndex] = record;
+		await writeExpertiseFile(filePath, records);
+
+		return record;
+	});
+}
+
+/**
+ * Append an outcome to an existing record by ID in the given domain.
+ * Outcomes accumulate (are not replaced) to build a confirmation-frequency
+ * history that drives confidence scoring.
+ */
+export async function appendOutcome(
+	domain: string,
+	id: string,
+	outcome: Outcome,
+	options: OutcomeOptions = {},
+): Promise<AppendOutcomeResult> {
+	const { cwd } = options;
+	const config = await readConfig(cwd);
+
+	if (!(domain in config.domains)) {
+		throw new Error(
+			`Domain "${domain}" not found in config. Available domains: ${Object.keys(config.domains).join(", ") || "(none)"}`,
+		);
+	}
+
+	const filePath = getExpertisePath(domain, cwd);
+
+	return withFileLock(filePath, async () => {
+		const records = await readExpertiseFile(filePath);
+		const resolved = resolveRecordId(records, id);
+
+		if (!resolved.ok) {
+			throw new Error(resolved.error);
+		}
+
+		const targetIndex = resolved.index;
+		const original = records[targetIndex];
+		if (!original) {
+			throw new Error(`Record at index ${targetIndex} not found`);
+		}
+		const record: ExpertiseRecord = { ...original };
+
+		const o: Outcome = {
+			...outcome,
+			recorded_at: outcome.recorded_at ?? new Date().toISOString(),
+		};
+
+		record.outcomes = [...(record.outcomes ?? []), o];
+		records[targetIndex] = record;
+		await writeExpertiseFile(filePath, records);
+
+		return { record, outcome: o, total_outcomes: record.outcomes.length };
+	});
+}