@ag-eco/agentplate-cli 0.13.0

package/src/tools/loam/utils/git-context.ts

@@ -0,0 +1,50 @@
+import { execFileSync } from "node:child_process";
+
+export function getCurrentCommit(cwd?: string): string | undefined {
+	try {
+		return execFileSync("git", ["rev-parse", "HEAD"], {
+			cwd: cwd ?? process.cwd(),
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+	} catch {
+		return undefined;
+	}
+}
+
+export function getContextFiles(cwd?: string): string[] {
+	const dir = cwd ?? process.cwd();
+	const files = new Set<string>();
+
+	try {
+		const staged = execFileSync("git", ["diff", "--name-only", "--cached"], {
+			cwd: dir,
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+		if (staged) {
+			for (const f of staged.split("\n")) {
+				if (f) files.add(f);
+			}
+		}
+	} catch {
+		// not a git repo or no staged changes
+	}
+
+	try {
+		const unstaged = execFileSync("git", ["diff", "--name-only"], {
+			cwd: dir,
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+		if (unstaged) {
+			for (const f of unstaged.split("\n")) {
+				if (f) files.add(f);
+			}
+		}
+	} catch {
+		// ignore
+	}
+
+	return [...files].sort();
+}

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

@@ -0,0 +1,183 @@
+import { execFileSync } from "node:child_process";
+import type { ExpertiseRecord } from "../schemas/record.ts";
+import type { TrackerName } from "./active-work.ts";
+import { fileLivesUnderDir } from "./dir-anchors.ts";
+
+export function isGitRepo(cwd: string): boolean {
+	try {
+		execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+			cwd,
+			stdio: "pipe",
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export function getChangedFiles(cwd: string, since: string): string[] {
+	const files = new Set<string>();
+
+	// Committed changes (since ref)
+	try {
+		const committed = execFileSync("git", ["diff", "--name-only", since], {
+			cwd,
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+		if (committed) {
+			for (const f of committed.split("\n")) {
+				if (f) files.add(f);
+			}
+		}
+	} catch {
+		// ref might not exist (e.g., first commit) — fall through
+	}
+
+	// Staged but uncommitted changes
+	try {
+		const staged = execFileSync("git", ["diff", "--name-only", "--cached"], {
+			cwd,
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+		if (staged) {
+			for (const f of staged.split("\n")) {
+				if (f) files.add(f);
+			}
+		}
+	} catch {
+		// ignore
+	}
+
+	// Unstaged working tree changes
+	try {
+		const unstaged = execFileSync("git", ["diff", "--name-only"], {
+			cwd,
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+		if (unstaged) {
+			for (const f of unstaged.split("\n")) {
+				if (f) files.add(f);
+			}
+		}
+	} catch {
+		// ignore
+	}
+
+	return [...files].sort();
+}
+
+// Files reported by `git status --porcelain` — staged, unstaged, and untracked
+// (excluding ignored). Includes rename destinations rather than sources. Used
+// by prime's auto-context-scope (slice 2) which mirrors V1_PLAN's "what the
+// agent is about to work on" framing rather than `git diff HEAD~1`'s "what
+// recently shipped."
+export function getActiveFiles(cwd: string): string[] {
+	const files = new Set<string>();
+	try {
+		// `-uall` lists every untracked file individually instead of collapsing
+		// directories to a single `??` entry — the prime context-scope needs
+		// per-file granularity to match record `files`/`dir_anchors`.
+		const out = execFileSync("git", ["status", "--porcelain", "-uall"], {
+			cwd,
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		});
+		for (const raw of out.split("\n")) {
+			if (!raw) continue;
+			// Porcelain v1 lines are `XY <path>` where XY is two status chars.
+			// Renames are `R  old -> new`; we keep the destination only.
+			const path = raw.slice(3);
+			const arrow = path.indexOf(" -> ");
+			if (arrow >= 0) {
+				files.add(path.slice(arrow + 4));
+			} else if (path) {
+				files.add(path);
+			}
+		}
+	} catch {
+		// not a repo, git missing, or status failed — caller treats empty as
+		// "no signal" and falls back to unscoped output.
+	}
+	return [...files].sort();
+}
+
+export function fileMatchesAny(file: string, changedFiles: string[]): boolean {
+	return changedFiles.some(
+		(changed) => changed === file || changed.endsWith(file) || file.endsWith(changed),
+	);
+}
+
+export function filterByContext(
+	records: ExpertiseRecord[],
+	changedFiles: string[],
+): ExpertiseRecord[] {
+	return records.filter((r) => {
+		const hasFiles = "files" in r && Array.isArray(r.files) && r.files.length > 0;
+		const hasDirAnchors = Array.isArray(r.dir_anchors) && r.dir_anchors.length > 0;
+
+		// No anchors at all → always relevant (conventions, decisions, failures,
+		// guides; or named records with no scoping declared).
+		if (!hasFiles && !hasDirAnchors) return true;
+
+		if (hasFiles && r.files !== undefined && r.files.some((f) => fileMatchesAny(f, changedFiles))) {
+			return true;
+		}
+		if (hasDirAnchors && r.dir_anchors !== undefined) {
+			for (const dir of r.dir_anchors) {
+				if (changedFiles.some((cf) => fileLivesUnderDir(cf, dir))) return true;
+			}
+		}
+		return false;
+	});
+}
+
+export type ActiveTrackers = Partial<Record<TrackerName, string>>;
+
+export interface ActiveContext {
+	changedFiles: string[];
+	trackers: ActiveTrackers;
+}
+
+export function activeContextHasSignal(ctx: ActiveContext): boolean {
+	if (ctx.changedFiles.length > 0) return true;
+	for (const v of Object.values(ctx.trackers)) {
+		if (typeof v === "string" && v !== "") return true;
+	}
+	return false;
+}
+
+// Slice-2 auto-scope: union of filterByContext + evidence-tracker match. A
+// record with no file/dir anchors AND no tracker anchors is treated as
+// universal (applies everywhere); anchored records require a match on at
+// least one signal.
+export function filterByActiveContext(
+	records: ExpertiseRecord[],
+	ctx: ActiveContext,
+): ExpertiseRecord[] {
+	const { changedFiles, trackers } = ctx;
+	return records.filter((r) => {
+		const hasFiles = "files" in r && Array.isArray(r.files) && r.files.length > 0;
+		const hasDirAnchors = Array.isArray(r.dir_anchors) && r.dir_anchors.length > 0;
+		const ev = r.evidence;
+		const sproutMatch = !!(ev?.sprout && trackers.sprout && ev.sprout === trackers.sprout);
+		const ghMatch = !!(ev?.gh && trackers.gh && ev.gh === trackers.gh);
+		const linearMatch = !!(ev?.linear && trackers.linear && ev.linear === trackers.linear);
+		const beadMatch = !!(ev?.bead && trackers.bead && ev.bead === trackers.bead);
+		if (sproutMatch || ghMatch || linearMatch || beadMatch) return true;
+
+		if (!hasFiles && !hasDirAnchors) return true;
+
+		if (hasFiles && r.files !== undefined && r.files.some((f) => fileMatchesAny(f, changedFiles))) {
+			return true;
+		}
+		if (hasDirAnchors && r.dir_anchors !== undefined) {
+			for (const dir of r.dir_anchors) {
+				if (changedFiles.some((cf) => fileLivesUnderDir(cf, dir))) return true;
+			}
+		}
+		return false;
+	});
+}

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

@@ -0,0 +1,299 @@
+import { spawn } from "node:child_process";
+import { log } from "../log.ts";
+import {
+	DEFAULT_HOOK_TIMEOUT_MS,
+	HOOK_EVENTS,
+	type HookEvent,
+	type LoamConfig,
+} from "../schemas/config.ts";
+import { readConfig } from "./config.ts";
+
+// Events whose hooks may mutate the payload via stdout JSON. `pre-record` and
+// `pre-prime` carry the original R-02 mutable payloads; `pre-compact` lets a
+// hook substitute the merged replacement record (loam-184b). `pre-prune` is
+// block-or-allow only (a hook can prevent the prune but not reshape the
+// candidate set).
+const MUTABLE_EVENTS: ReadonlySet<HookEvent> = new Set<HookEvent>([
+	"pre-record",
+	"pre-prime",
+	"pre-compact",
+]);
+
+const BLOCKING_EVENTS: ReadonlySet<HookEvent> = new Set<HookEvent>([
+	"pre-record",
+	"pre-prime",
+	"pre-prune",
+	"pre-compact",
+]);
+
+export interface HookExecution {
+	command: string;
+	exitCode: number;
+	stderr: string;
+	stdout: string;
+	durationMs: number;
+	timedOut: boolean;
+}
+
+export interface HookResult<T> {
+	// Whether at least one hook script was executed.
+	ranAny: boolean;
+	// True iff a `pre-*` hook exited non-zero (or timed out). The caller MUST
+	// abort the parent command when blocked is true.
+	blocked: boolean;
+	// Human-readable reason when blocked (script command + exit code/stderr).
+	blockReason?: string;
+	// Warnings collected from post-* failures or pre-* hooks whose stdout
+	// could not be parsed as JSON. Callers should surface these to the user.
+	warnings: string[];
+	// Possibly-mutated payload. For non-mutable events or when no hook altered
+	// stdout, this equals the input payload.
+	payload: T;
+	// Per-script execution diagnostics (in invocation order).
+	executions: HookExecution[];
+}
+
+interface HookSettings {
+	timeoutMs: number;
+}
+
+function resolveSettings(config: LoamConfig): HookSettings {
+	const raw = config.hook_settings?.timeout_ms;
+	const timeoutMs = typeof raw === "number" && raw > 0 ? raw : DEFAULT_HOOK_TIMEOUT_MS;
+	return { timeoutMs };
+}
+
+function getHookList(config: LoamConfig, event: HookEvent): string[] {
+	const list = config.hooks?.[event] ?? [];
+	return Array.isArray(list)
+		? list.filter((s) => typeof s === "string" && s.trim().length > 0)
+		: [];
+}
+
+interface RunOneResult {
+	exitCode: number;
+	stdout: string;
+	stderr: string;
+	durationMs: number;
+	timedOut: boolean;
+}
+
+async function runOne(
+	command: string,
+	stdinJson: string,
+	cwd: string,
+	timeoutMs: number,
+): Promise<RunOneResult> {
+	const start = Date.now();
+	// Run the hook in its own process group (POSIX session) so a timeout can
+	// SIGKILL every descendant — not just the immediate `sh`. Bun.spawn's
+	// `timeout` option only signals the direct child; a forked exec like
+	// `sleep 30 & wait` orphans the sleep, which keeps stdout/stderr open and
+	// hangs `Promise.all([Response.text(), Response.text(), proc.exited])`
+	// indefinitely (R-02 stress finding). Node's child_process supports
+	// `detached: true` (calls setsid on POSIX, putting the child in a new pgid
+	// equal to its pid), and `process.kill(-pid, "SIGKILL")` reaches the whole
+	// group. Bun re-exports node:child_process so this works on the Bun runtime.
+	const child = spawn("sh", ["-c", command], {
+		cwd,
+		stdio: ["pipe", "pipe", "pipe"],
+		env: { ...process.env, LOAM_HOOK: "1" },
+		detached: true,
+	});
+
+	let timedOut = false;
+	const timer = setTimeout(() => {
+		timedOut = true;
+		if (typeof child.pid === "number") {
+			try {
+				// Negative pid → process group. SIGKILL is unblockable so this
+				// reaches every descendant even if the hook script ignores SIGTERM.
+				process.kill(-child.pid, "SIGKILL");
+			} catch {
+				// ESRCH if the group already died; ignore.
+			}
+		}
+	}, timeoutMs);
+
+	let stdout = "";
+	let stderr = "";
+	child.stdout?.on("data", (b: Buffer) => {
+		stdout += b.toString();
+	});
+	child.stderr?.on("data", (b: Buffer) => {
+		stderr += b.toString();
+	});
+
+	if (child.stdin) {
+		try {
+			child.stdin.write(stdinJson);
+			child.stdin.end();
+		} catch {
+			// Script may have closed stdin early — not fatal.
+		}
+	}
+
+	const exitCode = await new Promise<number>((resolve) => {
+		child.on("close", (code: number | null) => resolve(code ?? 0));
+		child.on("error", () => resolve(1));
+	});
+	clearTimeout(timer);
+
+	return {
+		exitCode: timedOut ? 124 : exitCode,
+		stdout,
+		stderr,
+		durationMs: Date.now() - start,
+		timedOut,
+	};
+}
+
+/**
+ * Run all hook scripts registered for `event` in declaration order. Each script
+ * receives the current payload as JSON on stdin. For mutable events
+ * (`pre-record`, `pre-prime`), a script may print modified JSON on stdout; that
+ * JSON becomes the input to the next script and the final `result.payload`
+ * returned to the caller. `pre-prune` is block-or-allow only — its stdout is
+ * ignored even though it is a `pre-*` event, so a hook cannot reshape the
+ * candidate set.
+ *
+ * Semantics summary:
+ *   - `pre-*` non-zero exit (or timeout) → blocks: subsequent scripts skipped,
+ *     caller must abort. `result.blocked` is true with a reason string.
+ *   - `post-*` non-zero exit → warning only, all scripts still run.
+ *   - Empty / whitespace stdout from a mutable hook → payload unchanged.
+ *   - Non-JSON stdout from a mutable hook → payload unchanged + warning.
+ *   - Stderr from any script is forwarded to the user's stderr unless captured.
+ */
+export async function runHooks<T>(
+	event: HookEvent,
+	payload: T,
+	opts: { cwd?: string; config?: LoamConfig; forwardStderr?: boolean } = {},
+): Promise<HookResult<T>> {
+	if (!HOOK_EVENTS.includes(event)) {
+		throw new Error(`Unknown hook event: "${event}".`);
+	}
+
+	const cwd = opts.cwd ?? process.cwd();
+
+	let config: LoamConfig;
+	try {
+		config = opts.config ?? (await readConfig(cwd));
+	} catch {
+		// No config available (e.g., before `lm init`). Treat as no hooks.
+		return {
+			ranAny: false,
+			blocked: false,
+			warnings: [],
+			payload,
+			executions: [],
+		};
+	}
+
+	const scripts = getHookList(config, event);
+	if (scripts.length === 0) {
+		return {
+			ranAny: false,
+			blocked: false,
+			warnings: [],
+			payload,
+			executions: [],
+		};
+	}
+
+	const settings = resolveSettings(config);
+	const isMutable = MUTABLE_EVENTS.has(event);
+	const isBlocking = BLOCKING_EVENTS.has(event);
+	const forwardStderr = opts.forwardStderr !== false;
+
+	const warnings: string[] = [];
+	const executions: HookExecution[] = [];
+	let currentPayload: T = payload;
+
+	for (const command of scripts) {
+		const stdinJson = JSON.stringify({ event, payload: currentPayload });
+		const res = await runOne(command, stdinJson, cwd, settings.timeoutMs);
+
+		executions.push({
+			command,
+			exitCode: res.exitCode,
+			stderr: res.stderr,
+			stdout: res.stdout,
+			durationMs: res.durationMs,
+			timedOut: res.timedOut,
+		});
+
+		// Diagnostic trace of hook execution. Silent at the default `info`
+		// level; surfaces under LOAM_DEBUG. Runs outside the expertise-file
+		// write lock (record.ts runs pre-/post-hooks around the locked write),
+		// so logging here can never contend with a concurrent writer.
+		log.debug(
+			{
+				event,
+				command,
+				exitCode: res.exitCode,
+				durationMs: res.durationMs,
+				timedOut: res.timedOut,
+			},
+			"hook executed",
+		);
+
+		if (forwardStderr && res.stderr.length > 0) {
+			process.stderr.write(res.stderr);
+			if (!res.stderr.endsWith("\n")) process.stderr.write("\n");
+		}
+
+		if (res.exitCode !== 0) {
+			const reason = res.timedOut
+				? `hook \`${command}\` timed out after ${settings.timeoutMs}ms`
+				: `hook \`${command}\` exited with code ${res.exitCode}`;
+			log.warn(
+				{ event, command, exitCode: res.exitCode, timedOut: res.timedOut, blocking: isBlocking },
+				reason,
+			);
+			if (isBlocking) {
+				return {
+					ranAny: true,
+					blocked: true,
+					blockReason: reason,
+					warnings,
+					payload: currentPayload,
+					executions,
+				};
+			}
+			warnings.push(reason);
+			continue;
+		}
+
+		if (isMutable) {
+			const trimmed = res.stdout.trim();
+			if (trimmed.length === 0) continue;
+			try {
+				const parsed = JSON.parse(trimmed) as { payload?: T } | T;
+				if (
+					parsed !== null &&
+					typeof parsed === "object" &&
+					"payload" in (parsed as Record<string, unknown>)
+				) {
+					currentPayload = (parsed as { payload: T }).payload;
+				} else {
+					currentPayload = parsed as T;
+				}
+			} catch (err) {
+				warnings.push(
+					`hook \`${command}\` printed non-JSON on stdout (mutation ignored): ${
+						err instanceof Error ? err.message : String(err)
+					}`,
+				);
+			}
+		}
+	}
+
+	return {
+		ranAny: true,
+		blocked: false,
+		warnings,
+		payload: currentPayload,
+		executions,
+	};
+}

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

@@ -0,0 +1,52 @@
+export {
+	getConfigPath,
+	getExpertiseDir,
+	getExpertisePath,
+	getLoamDir,
+	initLoamDir,
+	readConfig,
+	writeConfig,
+} from "./config.ts";
+
+export {
+	appendRecord,
+	countRecords,
+	createExpertiseFile,
+	filterByType,
+	generateRecordId,
+	getFileModTime,
+	readExpertiseFile,
+} from "./expertise.ts";
+
+export {
+	formatDomainExpertise,
+	formatPrimeOutput,
+	formatStatusOutput,
+	formatTimeAgo,
+	getRecordSummary,
+} from "./format.ts";
+export {
+	fileMatchesAny,
+	filterByContext,
+	getChangedFiles,
+	isGitRepo,
+} from "./git.ts";
+export {
+	outputJson,
+	outputJsonError,
+} from "./json-output.ts";
+
+export {
+	hasMarkerSection,
+	MARKER_END,
+	MARKER_START,
+	removeMarkerSection,
+	replaceMarkerSection,
+	wrapInMarkers,
+} from "./markers.ts";
+
+export {
+	compareSemver,
+	getCurrentVersion,
+	getLatestVersion,
+} from "./version.ts";

package/src/tools/loam/utils/json-output.ts

@@ -0,0 +1,13 @@
+export interface JsonResult {
+	success: boolean;
+	command: string;
+	[key: string]: unknown;
+}
+
+export function outputJson(result: JsonResult): void {
+	console.log(JSON.stringify(result, null, 2));
+}
+
+export function outputJsonError(command: string, error: string): void {
+	console.error(JSON.stringify({ success: false, command, error }, null, 2));
+}

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

@@ -0,0 +1,76 @@
+import { constants } from "node:fs";
+import { lstat, open, unlink } from "node:fs/promises";
+
+const LOCK_STALE_MS = 30_000; // 30 seconds
+const LOCK_RETRY_INTERVAL_MS = 50;
+const LOCK_TIMEOUT_MS = 5_000; // 5 seconds
+
+/**
+ * Advisory file-level lock using O_CREAT | O_EXCL.
+ * Wraps an async function with lock acquisition and guaranteed cleanup.
+ */
+export async function withFileLock<T>(filePath: string, fn: () => Promise<T>): Promise<T> {
+	const lockPath = `${filePath}.lock`;
+	await acquireLock(lockPath);
+	try {
+		return await fn();
+	} finally {
+		await releaseLock(lockPath);
+	}
+}
+
+async function acquireLock(lockPath: string): Promise<void> {
+	const deadline = Date.now() + LOCK_TIMEOUT_MS;
+
+	while (true) {
+		try {
+			const fd = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY);
+			await fd.close();
+			return;
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code !== "EEXIST") {
+				throw err;
+			}
+
+			// Lock file exists — check if it's stale
+			if (await isStaleLock(lockPath)) {
+				try {
+					await unlink(lockPath);
+				} catch {
+					// Another process may have already removed it
+				}
+				continue;
+			}
+
+			if (Date.now() >= deadline) {
+				throw new Error(
+					`Timed out waiting for lock on ${lockPath}. If no other loam process is running, delete the lock file manually.`,
+				);
+			}
+
+			await sleep(LOCK_RETRY_INTERVAL_MS);
+		}
+	}
+}
+
+async function isStaleLock(lockPath: string): Promise<boolean> {
+	try {
+		const stats = await lstat(lockPath);
+		return Date.now() - stats.mtimeMs > LOCK_STALE_MS;
+	} catch {
+		// Lock file disappeared between check — not stale, just gone
+		return false;
+	}
+}
+
+async function releaseLock(lockPath: string): Promise<void> {
+	try {
+		await unlink(lockPath);
+	} catch {
+		// Lock file already gone — acceptable
+	}
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}