@ag-eco/agentplate-cli 0.13.0

package/src/tools/loam/utils/active-work.ts

@@ -0,0 +1,205 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export type TrackerName = "sprout" | "gh" | "linear" | "bead";
+
+export const TRACKERS: readonly TrackerName[] = ["sprout", "gh", "linear", "bead"];
+
+export interface ResolverHit {
+	tracker: TrackerName;
+	matches: string[];
+	source: string;
+}
+
+export type Resolver = (cwd: string) => ResolverHit;
+
+export interface ActiveWorkResult {
+	sprout?: string;
+	gh?: string;
+	linear?: string;
+	bead?: string;
+	warnings: string[];
+}
+
+export interface ActiveWorkOptions {
+	cwd?: string;
+	resolvers?: Resolver[];
+	// Explicit overrides (e.g. from `--evidence-sprout`). When set, the resolver
+	// chain for that tracker is short-circuited and the override is used as-is.
+	// Empty string is treated as "not set".
+	overrides?: Partial<Record<TrackerName, string | undefined>>;
+}
+
+function getCurrentBranch(cwd: string): string {
+	try {
+		const branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+			cwd,
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+		return branch === "HEAD" ? "" : branch;
+	} catch {
+		return "";
+	}
+}
+
+function readJsonl<T>(path: string): T[] {
+	if (!existsSync(path)) return [];
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf-8");
+	} catch {
+		return [];
+	}
+	const out: T[] = [];
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		try {
+			out.push(JSON.parse(trimmed) as T);
+		} catch {
+			// skip malformed lines — caller may have other valid rows
+		}
+	}
+	return out;
+}
+
+// Sprout: <project>-<4–8 hex>. e.g. "loam-f3d0", "sprout-a051".
+const SPROUT_ID_RE = /\b([a-z][a-z0-9]*-[a-f0-9]{4,8})\b/g;
+// Linear: <UPPER>-<digits>. e.g. "WEB-123", "ENG-4567". Two+ leading uppercase
+// chars so single-letter prefixes don't collide with branch nicknames.
+const LINEAR_ID_RE = /\b([A-Z]{2,}[A-Z0-9]*-\d+)\b/g;
+// Bead: bd-<digits> or bead-<digits>.
+const BEAD_ID_RE = /\b((?:bd|bead)-\d+)\b/gi;
+// GH: gh-<digits> or #<digits>.
+const GH_ID_RE = /(?:^|[^a-zA-Z0-9])(?:gh-|#)(\d+)\b/gi;
+
+function matchAll(re: RegExp, text: string, group = 1): string[] {
+	const out = new Set<string>();
+	for (const m of text.matchAll(re)) {
+		const val = m[group];
+		if (val) out.add(val);
+	}
+	return [...out].sort();
+}
+
+export const sproutResolver: Resolver = (cwd) => {
+	type SproutIssue = { id?: unknown; status?: unknown };
+	const issues = readJsonl<SproutIssue>(join(cwd, ".sprout", "issues.jsonl"));
+	const inProgress: string[] = [];
+	for (const i of issues) {
+		if (i.status === "in_progress" && typeof i.id === "string") inProgress.push(i.id);
+	}
+	if (inProgress.length > 0) {
+		return {
+			tracker: "sprout",
+			matches: [...new Set(inProgress)].sort(),
+			source: "in_progress",
+		};
+	}
+	const branch = getCurrentBranch(cwd);
+	const branchMatches = matchAll(SPROUT_ID_RE, branch);
+	if (branchMatches.length > 0) {
+		return { tracker: "sprout", matches: branchMatches, source: "branch" };
+	}
+	return { tracker: "sprout", matches: [], source: "none" };
+};
+
+export const ghResolver: Resolver = (cwd) => {
+	const branch = getCurrentBranch(cwd);
+	if (branch) {
+		try {
+			const out = execFileSync("gh", ["pr", "view", "--json", "number", "--jq", ".number"], {
+				cwd,
+				encoding: "utf-8",
+				stdio: ["pipe", "pipe", "pipe"],
+			}).trim();
+			if (out && /^\d+$/.test(out)) {
+				return { tracker: "gh", matches: [`#${out}`], source: "gh-cli" };
+			}
+		} catch {
+			// gh missing, unauthenticated, or no PR linked — fall through
+		}
+	}
+	const branchMatches = matchAll(GH_ID_RE, branch).map((n) => `#${n}`);
+	if (branchMatches.length > 0) {
+		return { tracker: "gh", matches: branchMatches, source: "branch" };
+	}
+	return { tracker: "gh", matches: [], source: "none" };
+};
+
+export const linearResolver: Resolver = (cwd) => {
+	const branch = getCurrentBranch(cwd);
+	const branchMatches = matchAll(LINEAR_ID_RE, branch);
+	if (branchMatches.length > 0) {
+		return { tracker: "linear", matches: branchMatches, source: "branch" };
+	}
+	return { tracker: "linear", matches: [], source: "none" };
+};
+
+export const beadResolver: Resolver = (cwd) => {
+	type BeadIssue = { id?: unknown; status?: unknown };
+	const issues = readJsonl<BeadIssue>(join(cwd, ".beads", "issues.jsonl"));
+	const inProgress: string[] = [];
+	for (const i of issues) {
+		if (i.status === "in_progress" && typeof i.id === "string") inProgress.push(i.id);
+	}
+	if (inProgress.length > 0) {
+		return {
+			tracker: "bead",
+			matches: [...new Set(inProgress)].sort(),
+			source: "in_progress",
+		};
+	}
+	const branch = getCurrentBranch(cwd);
+	const branchMatches = matchAll(BEAD_ID_RE, branch).map((s) => s.toLowerCase());
+	if (branchMatches.length > 0) {
+		return {
+			tracker: "bead",
+			matches: [...new Set(branchMatches)].sort(),
+			source: "branch",
+		};
+	}
+	return { tracker: "bead", matches: [], source: "none" };
+};
+
+export const DEFAULT_RESOLVERS: Resolver[] = [
+	sproutResolver,
+	ghResolver,
+	linearResolver,
+	beadResolver,
+];
+
+export function resolveActiveWork(options: ActiveWorkOptions = {}): ActiveWorkResult {
+	const cwd = options.cwd ?? process.cwd();
+	const resolvers = options.resolvers ?? DEFAULT_RESOLVERS;
+	const overrides = options.overrides ?? {};
+	const result: ActiveWorkResult = { warnings: [] };
+
+	const hitsByTracker = new Map<TrackerName, ResolverHit>();
+	for (const resolver of resolvers) {
+		const hit = resolver(cwd);
+		// First resolver to claim a tracker wins; later ones for the same tracker
+		// are ignored so callers can prepend a custom resolver to override.
+		if (!hitsByTracker.has(hit.tracker)) hitsByTracker.set(hit.tracker, hit);
+	}
+
+	for (const tracker of TRACKERS) {
+		const override = overrides[tracker];
+		if (typeof override === "string" && override !== "") {
+			result[tracker] = override;
+			continue;
+		}
+		const hit = hitsByTracker.get(tracker);
+		if (!hit) continue;
+		if (hit.matches.length === 1) {
+			result[tracker] = hit.matches[0];
+		} else if (hit.matches.length > 1) {
+			result.warnings.push(
+				`active-work: multiple ${tracker} candidates [${hit.matches.join(", ")}] from ${hit.source}; pass --evidence-${tracker} <id> to disambiguate`,
+			);
+		}
+	}
+	return result;
+}

package/src/tools/loam/utils/anchor-validity.ts

@@ -0,0 +1,80 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ExpertiseRecord } from "../schemas/record.ts";
+
+export type AnchorKind = "file" | "dir" | "evidence_file";
+
+export interface RecordAnchor {
+	kind: AnchorKind;
+	path: string;
+}
+
+export interface AnchorValidity {
+	total: number;
+	valid: number;
+	broken: RecordAnchor[];
+	// `null` when the record has zero anchors — callers should treat that as
+	// "applies globally, no decay signal" rather than 100% valid (a 0/0 record
+	// would otherwise compute NaN and falsely trigger the threshold).
+	validFraction: number | null;
+}
+
+/**
+ * Enumerate every filesystem anchor a record carries: the typed `files[]`
+ * (PatternRecord/ReferenceRecord), `dir_anchors[]` (any record), and
+ * `evidence.file` (single string). Returns canonical kind+path pairs so
+ * `--explain` output can attribute each broken entry.
+ */
+export function getRecordAnchors(record: ExpertiseRecord): RecordAnchor[] {
+	const anchors: RecordAnchor[] = [];
+	if ("files" in record && Array.isArray(record.files)) {
+		for (const f of record.files) {
+			if (typeof f === "string" && f.length > 0) {
+				anchors.push({ kind: "file", path: f });
+			}
+		}
+	}
+	if (Array.isArray(record.dir_anchors)) {
+		for (const d of record.dir_anchors) {
+			if (typeof d === "string" && d.length > 0) {
+				anchors.push({ kind: "dir", path: d });
+			}
+		}
+	}
+	if (record.evidence?.file && typeof record.evidence.file === "string") {
+		anchors.push({ kind: "evidence_file", path: record.evidence.file });
+	}
+	return anchors;
+}
+
+export function computeAnchorValidity(
+	record: ExpertiseRecord,
+	projectRoot: string,
+): AnchorValidity {
+	const anchors = getRecordAnchors(record);
+	const total = anchors.length;
+	if (total === 0) {
+		return { total: 0, valid: 0, broken: [], validFraction: null };
+	}
+	const broken: RecordAnchor[] = [];
+	let valid = 0;
+	for (const a of anchors) {
+		if (existsSync(resolve(projectRoot, a.path))) {
+			valid++;
+		} else {
+			broken.push(a);
+		}
+	}
+	return { total, valid, broken, validFraction: valid / total };
+}
+
+/**
+ * True when the record is older than the configured grace period, so we
+ * shouldn't punish anchor decay on a record that was just written (e.g., a
+ * file moved/created between `lm record` and the next `lm prune`).
+ */
+export function passedAnchorGrace(record: ExpertiseRecord, now: Date, graceDays: number): boolean {
+	const recordedAt = new Date(record.recorded_at);
+	const ageDays = (now.getTime() - recordedAt.getTime()) / (1000 * 60 * 60 * 24);
+	return ageDays > graceDays;
+}

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

@@ -0,0 +1,146 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { ExpertiseRecord } from "../schemas/record.ts";
+import { getLoamDir, validateDomainName } from "./config.ts";
+import { readExpertiseFile, writeExpertiseFile } from "./expertise.ts";
+import { withFileLock } from "./lock.ts";
+
+const ARCHIVE_DIR = "archive";
+
+export const ARCHIVE_BANNER = "# ARCHIVED — not for active use. Run `lm restore <id>` to revive.";
+
+export function getArchiveDir(cwd: string = process.cwd()): string {
+	return join(getLoamDir(cwd), ARCHIVE_DIR);
+}
+
+export function getArchivePath(domain: string, cwd: string = process.cwd()): string {
+	validateDomainName(domain);
+	return join(getArchiveDir(cwd), `${domain}.jsonl`);
+}
+
+/**
+ * Read archived records from an archive file. The file's leading banner
+ * comment is stripped by readExpertiseFile (which skips `#`-prefixed lines).
+ */
+export async function readArchiveFile(filePath: string): Promise<ExpertiseRecord[]> {
+	return readExpertiseFile(filePath, { allowUnknownTypes: true });
+}
+
+/**
+ * Write archive records back, prefixed with the standard banner. Uses the
+ * same temp-file + rename atomic pattern as writeExpertiseFile.
+ */
+export async function writeArchiveFile(
+	filePath: string,
+	records: ExpertiseRecord[],
+): Promise<void> {
+	await mkdir(dirname(filePath), { recursive: true });
+	const body = records.map((r) => JSON.stringify(r)).join("\n");
+	const content = `${ARCHIVE_BANNER}\n${body}${records.length > 0 ? "\n" : ""}`;
+	const tmpPath = `${filePath}.tmp.${randomBytes(8).toString("hex")}`;
+	await writeFile(tmpPath, content, "utf-8");
+	try {
+		await rename(tmpPath, filePath);
+	} catch (err) {
+		try {
+			await unlink(tmpPath);
+		} catch {
+			/* best-effort cleanup */
+		}
+		throw err;
+	}
+}
+
+/**
+ * Move records from a live expertise file to the corresponding archive file.
+ * Each archived record gets `status: "archived"`, an `archived_at` timestamp,
+ * and an `archive_reason` (use values from `ArchiveReason` as a convention;
+ * free-text suffix permitted, e.g. "manual: wrong domain"). A pre-existing
+ * `archive_reason` on the record (e.g. from a re-archive on restore rollback)
+ * is preserved. Locks the archive file during the merge+write; the caller is
+ * responsible for locking the source expertise file before invoking.
+ */
+export async function archiveRecords(
+	domain: string,
+	records: ExpertiseRecord[],
+	now: Date,
+	reason: string,
+	cwd: string = process.cwd(),
+): Promise<void> {
+	if (records.length === 0) return;
+	const archivePath = getArchivePath(domain, cwd);
+	const stamped = records.map((r) => ({
+		...r,
+		status: "archived" as const,
+		archived_at: r.archived_at ?? now.toISOString(),
+		archive_reason: r.archive_reason ?? reason,
+	}));
+	await mkdir(dirname(archivePath), { recursive: true });
+	await withFileLock(archivePath, async () => {
+		const existing = await readArchiveFile(archivePath);
+		await writeArchiveFile(archivePath, [...existing, ...stamped]);
+	});
+}
+
+/**
+ * Canonical archive_reason values. Free-text suffix permitted via raw string;
+ * the union is just the convention for the five known code paths.
+ */
+export type ArchiveReason = "stale" | "superseded" | "anchor_decay" | "manual" | "compacted";
+
+/** Strip soft-archive lifecycle fields. Used when restoring a record to live. */
+export function stripArchiveFields(record: ExpertiseRecord): ExpertiseRecord {
+	const { status, archived_at, archive_reason, ...rest } = record as ExpertiseRecord & {
+		status?: unknown;
+		archived_at?: unknown;
+		archive_reason?: unknown;
+	};
+	void status;
+	void archived_at;
+	void archive_reason;
+	return rest as ExpertiseRecord;
+}
+
+/**
+ * Remove a record from an archive file by id (mutates archive on disk under a
+ * lock). Returns the removed record, or null if not found.
+ */
+export async function removeFromArchive(
+	domain: string,
+	recordId: string,
+	cwd: string = process.cwd(),
+): Promise<ExpertiseRecord | null> {
+	const archivePath = getArchivePath(domain, cwd);
+	return withFileLock(archivePath, async () => {
+		const records = await readArchiveFile(archivePath);
+		const idx = records.findIndex((r) => r.id === recordId);
+		if (idx === -1) return null;
+		const [removed] = records.splice(idx, 1);
+		await writeArchiveFile(archivePath, records);
+		return removed ?? null;
+	});
+}
+
+export type RestoreResult = { ok: true } | { ok: false; conflict: ExpertiseRecord };
+
+/**
+ * Append a single record to a live expertise file under a lock. Used by
+ * `lm restore` to push an archived record back into circulation. Refuses
+ * to write when a live record with the same id already exists — restoring
+ * over a live id silently created duplicates pre-v0.8.1.
+ */
+export async function restoreToExpertise(
+	expertisePath: string,
+	record: ExpertiseRecord,
+): Promise<RestoreResult> {
+	return withFileLock(expertisePath, async () => {
+		const existing = await readExpertiseFile(expertisePath);
+		if (record.id !== undefined) {
+			const conflict = existing.find((r) => r.id === record.id);
+			if (conflict) return { ok: false, conflict };
+		}
+		await writeExpertiseFile(expertisePath, [...existing, record]);
+		return { ok: true };
+	});
+}