@ag-eco/agentplate-cli 0.13.0

package/src/tools/trellis/id.ts

@@ -0,0 +1,24 @@
+import { randomBytes } from "node:crypto";
+
+export function generateId(prefix: string, existingIds: string[]): string {
+	const existingSet = new Set(existingIds);
+
+	for (let attempt = 0; attempt < 100; attempt++) {
+		const hex = randomBytes(2).toString("hex");
+		const id = `${prefix}-${hex}`;
+		if (!existingSet.has(id)) {
+			return id;
+		}
+	}
+
+	// Fallback to 8 hex chars after 100 collisions
+	for (let attempt = 0; attempt < 1000; attempt++) {
+		const hex = randomBytes(4).toString("hex");
+		const id = `${prefix}-${hex}`;
+		if (!existingSet.has(id)) {
+			return id;
+		}
+	}
+
+	throw new Error(`Failed to generate unique ID with prefix "${prefix}"`);
+}

package/src/tools/trellis/index.ts

@@ -0,0 +1,209 @@
+#!/usr/bin/env bun
+import chalk from "chalk";
+import { Command, Help } from "commander";
+import { VERSION } from "../../version.ts";
+import { errorOut, isJsonMode, jsonOut, palette, setQuiet } from "./output.ts";
+import { ExitError } from "./types.ts";
+
+export { VERSION };
+
+const t0 = performance.now();
+
+const rawArgs = process.argv.slice(2);
+
+// Apply quiet mode early (before any output)
+if (rawArgs.includes("--quiet") || rawArgs.includes("-q")) {
+	setQuiet(true);
+}
+
+// --version --json: rich metadata output (before Commander processes version flag)
+if ((rawArgs.includes("-v") || rawArgs.includes("--version")) && rawArgs.includes("--json")) {
+	const platform = `${process.platform}-${process.arch}`;
+	jsonOut({ name: "@ag-eco/trellis-cli", version: VERSION, runtime: "bun", platform });
+	if (rawArgs.includes("--timing")) {
+		const elapsed = Math.round(performance.now() - t0);
+		process.stderr.write(`[timing] ${elapsed}ms\n`);
+	}
+	process.exit();
+}
+
+const program = new Command();
+program
+	.name("tl")
+	.description("Prompt management & composition")
+	.version(VERSION, "-v, --version", "Show version")
+	.option("-q, --quiet", "Suppress non-error output")
+	.option("--verbose", "Extra diagnostic output")
+	.option("--timing", "Show command execution time")
+	.option("--json", "Output as JSON")
+	.addHelpCommand(false)
+	.configureHelp({
+		formatHelp(cmd: Command, helper: Help): string {
+			if (cmd.parent) {
+				return Help.prototype.formatHelp.call(helper, cmd, helper);
+			}
+			const header = `${palette.brand(chalk.bold("trellis"))} ${palette.muted(`v${VERSION}`)} — Prompt management & composition\n\nUsage: tl <command> [options]`;
+
+			const cmdLines: string[] = ["\nCommands:"];
+			for (const sub of cmd.commands) {
+				const name = sub.name();
+				const argStr = sub.registeredArguments
+					.map((a) => (a.required ? `<${a.name()}>` : `[${a.name()}]`))
+					.join(" ");
+				const rawEntry = argStr ? `${name} ${argStr}` : name;
+				const colored = argStr ? `${chalk.green(name)} ${chalk.dim(argStr)}` : chalk.green(name);
+				const pad = " ".repeat(Math.max(18 - rawEntry.length, 2));
+				cmdLines.push(`  ${colored}${pad}${sub.description()}`);
+			}
+
+			const opts: [string, string][] = [
+				["-h, --help", "Show help"],
+				["-v, --version", "Show version"],
+				["--json", "Output as JSON"],
+				["-q, --quiet", "Suppress non-error output"],
+				["--verbose", "Extra diagnostic output"],
+				["--timing", "Show command execution time"],
+			];
+			const optLines: string[] = ["\nOptions:"];
+			for (const [flag, desc] of opts) {
+				const pad = " ".repeat(Math.max(18 - flag.length, 2));
+				optLines.push(`  ${chalk.dim(flag)}${pad}${desc}`);
+			}
+
+			const footer = `\nRun '${chalk.dim("tl")} <command> --help' for command-specific help.`;
+
+			return `${[header, ...cmdLines, ...optLines, footer].join("\n")}\n`;
+		},
+	});
+
+const { registerInitCommand } = await import("./commands/init.ts");
+const { registerShowCommand } = await import("./commands/show.ts");
+const { registerListCommand } = await import("./commands/list.ts");
+const { registerArchiveCommand } = await import("./commands/archive.ts");
+const { registerHistoryCommand } = await import("./commands/history.ts");
+const { registerTreeCommand } = await import("./commands/tree.ts");
+const { registerStatsCommand } = await import("./commands/stats.ts");
+const { registerSyncCommand } = await import("./commands/sync.ts");
+const { registerDiffCommand } = await import("./commands/diff.ts");
+const { registerRenderCommand } = await import("./commands/render.ts");
+const { registerCreateCommand } = await import("./commands/create.ts");
+const { registerUpdateCommand } = await import("./commands/update.ts");
+const { registerEmitCommand } = await import("./commands/emit.ts");
+const { registerSchemaCommand } = await import("./commands/schema.ts");
+const { registerValidateCommand } = await import("./commands/validate.ts");
+const { registerConfigCommand } = await import("./commands/config.ts");
+const { registerImportCommand } = await import("./commands/import.ts");
+const { registerPrimeCommand } = await import("./commands/prime.ts");
+const { registerOnboardCommand } = await import("./commands/onboard.ts");
+const { registerPinCommand } = await import("./commands/pin.ts");
+const { registerDoctorCommand } = await import("./commands/doctor.ts");
+const { registerUpgradeCommand } = await import("./commands/upgrade.ts");
+const { registerCompletionsCommand } = await import("./commands/completions.ts");
+
+registerInitCommand(program);
+registerShowCommand(program);
+registerListCommand(program);
+registerArchiveCommand(program);
+registerHistoryCommand(program);
+registerTreeCommand(program);
+registerStatsCommand(program);
+registerSyncCommand(program);
+registerDiffCommand(program);
+registerRenderCommand(program);
+registerCreateCommand(program);
+registerUpdateCommand(program);
+registerEmitCommand(program);
+registerSchemaCommand(program);
+registerValidateCommand(program);
+registerConfigCommand(program);
+registerImportCommand(program);
+registerPrimeCommand(program);
+registerOnboardCommand(program);
+registerPinCommand(program); // registers both pin and unpin
+registerDoctorCommand(program);
+registerUpgradeCommand(program);
+registerCompletionsCommand(program);
+
+// --- Typo suggestions via Levenshtein distance ---
+
+function editDistance(a: string, b: string): number {
+	const m = a.length;
+	const n = b.length;
+	const dp = new Array<number>((m + 1) * (n + 1)).fill(0);
+	const idx = (i: number, j: number) => i * (n + 1) + j;
+	for (let i = 0; i <= m; i++) dp[idx(i, 0)] = i;
+	for (let j = 0; j <= n; j++) dp[idx(0, j)] = j;
+	for (let i = 1; i <= m; i++) {
+		for (let j = 1; j <= n; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			const del = (dp[idx(i - 1, j)] ?? 0) + 1;
+			const ins = (dp[idx(i, j - 1)] ?? 0) + 1;
+			const sub = (dp[idx(i - 1, j - 1)] ?? 0) + cost;
+			dp[idx(i, j)] = Math.min(del, ins, sub);
+		}
+	}
+	return dp[idx(m, n)] ?? 0;
+}
+
+function suggestCommand(input: string): string | undefined {
+	const commands = program.commands.map((c) => c.name());
+	let bestMatch: string | undefined;
+	let bestDist = 3; // Only suggest if distance <= 2
+	for (const cmd of commands) {
+		const dist = editDistance(input, cmd);
+		if (dist < bestDist) {
+			bestDist = dist;
+			bestMatch = cmd;
+		}
+	}
+	return bestMatch;
+}
+
+program.on("command:*", (operands) => {
+	const unknown = operands[0] ?? "";
+	const json = isJsonMode(rawArgs);
+	const suggestion = suggestCommand(unknown);
+	if (json) {
+		jsonOut({
+			success: false,
+			command: unknown,
+			error: `Unknown command: ${unknown}`,
+			suggestion: suggestion ?? undefined,
+		});
+	} else {
+		process.stderr.write(`Unknown command: ${unknown}\n`);
+		if (suggestion) {
+			process.stderr.write(`Did you mean '${suggestion}'?\n`);
+		}
+		process.stderr.write("Run 'tl --help' for usage.\n");
+	}
+	process.exitCode = 1;
+});
+
+program
+	.parseAsync(process.argv)
+	.then(() => {
+		if (program.opts().timing) {
+			const elapsed = Math.round(performance.now() - t0);
+			process.stderr.write(`[timing] ${elapsed}ms\n`);
+		}
+	})
+	.catch((err: unknown) => {
+		if (program.opts().timing) {
+			const elapsed = Math.round(performance.now() - t0);
+			process.stderr.write(`[timing] ${elapsed}ms\n`);
+		}
+		if (err instanceof ExitError) {
+			process.exitCode = err.exitCode;
+			return;
+		}
+		const msg = err instanceof Error ? err.message : String(err);
+		const command = process.argv[2] ?? "";
+		const json = isJsonMode(process.argv.slice(2));
+		if (json) {
+			jsonOut({ success: false, command, error: msg });
+		} else {
+			errorOut(`Error: ${msg}`);
+		}
+		process.exitCode = 1;
+	});

package/src/tools/trellis/markers.ts

@@ -0,0 +1,28 @@
+export const START_MARKER = "<!-- trellis:start -->";
+export const END_MARKER = "<!-- trellis:end -->";
+
+export const ONBOARD_VERSION = 2;
+export const VERSION_MARKER = `<!-- trellis-onboard-v:${String(ONBOARD_VERSION)} -->`;
+
+export function hasMarkerSection(content: string): boolean {
+	return content.includes(START_MARKER) && content.includes(END_MARKER);
+}
+
+export function detectStatus(content: string): "missing" | "current" | "outdated" {
+	if (!hasMarkerSection(content)) return "missing";
+	if (content.includes(VERSION_MARKER)) return "current";
+	return "outdated";
+}
+
+export function replaceMarkerSection(content: string, newSection: string): string | null {
+	const startIdx = content.indexOf(START_MARKER);
+	const endIdx = content.indexOf(END_MARKER);
+	if (startIdx === -1 || endIdx === -1) return null;
+	const before = content.slice(0, startIdx);
+	const after = content.slice(endIdx + END_MARKER.length);
+	return before + wrapInMarkers(newSection) + after;
+}
+
+export function wrapInMarkers(section: string): string {
+	return `${START_MARKER}\n${section}\n${END_MARKER}`;
+}

package/src/tools/trellis/output.ts

@@ -0,0 +1,84 @@
+import chalk from "chalk";
+
+let _quiet = false;
+
+export function setQuiet(v: boolean): void {
+	_quiet = v;
+}
+
+export function isQuiet(): boolean {
+	return _quiet;
+}
+
+export function jsonOut(data: unknown): void {
+	if (_quiet) {
+		const isError =
+			data != null &&
+			typeof data === "object" &&
+			"success" in data &&
+			(data as Record<string, unknown>).success === false;
+		if (!isError) return;
+	}
+	console.log(JSON.stringify(data, null, 2));
+}
+
+export function humanOut(text: string): void {
+	if (_quiet) return;
+	console.log(text);
+}
+
+export function errorOut(msg: string): void {
+	console.error(msg);
+}
+
+export function isJsonMode(args: string[]): boolean {
+	return args.includes("--json");
+}
+
+// Brand palette — chalk instances (supports chaining e.g. palette.brand.bold(...))
+// chalk handles NO_COLOR and TTY detection automatically
+export const palette = {
+	brand: chalk.rgb(56, 142, 60), // Trellis deep green
+	accent: chalk.rgb(255, 183, 77), // amber — IDs and accents
+	muted: chalk.rgb(120, 120, 110), // stone gray — metadata
+};
+
+// Color helpers
+export const c = {
+	bold: (s: string) => chalk.bold(s),
+	dim: (s: string) => chalk.dim(s),
+	green: (s: string) => palette.brand(s),
+	red: (s: string) => chalk.red(s),
+	yellow: (s: string) => palette.accent(s),
+	cyan: (s: string) => chalk.cyan(s),
+	blue: (s: string) => chalk.blue(s),
+};
+
+// Status icons: Set D (minimal, maximum terminal compatibility)
+// Use these for list status indicators, not message prefixes
+export const icons = {
+	pending: chalk.green("-"), // open / pending
+	active: chalk.cyan(">"), // in_progress / active
+	done: chalk.dim("x"), // closed / done
+	blocked: chalk.yellow("!"), // blocked / warning
+};
+
+// Message format helpers per visual-spec.md
+export const fmt = {
+	// brand bold ✓ + brand message text
+	success: (msg: string) => `${palette.brand.bold("✓")} ${palette.brand(msg)}`,
+	// highlight an ID or reference in accent (amber)
+	id: (id: string) => palette.accent(id),
+	// yellow bold ! + yellow message + optional dim hint
+	warning: (msg: string, hint?: string) =>
+		hint
+			? `${chalk.yellow.bold("!")} ${chalk.yellow(msg)} ${chalk.dim(hint)}`
+			: `${chalk.yellow.bold("!")} ${chalk.yellow(msg)}`,
+	// red bold ✗ + red message + optional dim hint
+	error: (msg: string, hint?: string) =>
+		hint
+			? `${chalk.red.bold("✗")} ${chalk.red(msg)} ${chalk.dim(hint)}`
+			: `${chalk.red.bold("✗")} ${chalk.red(msg)}`,
+	// dim indented info/hint text
+	info: (msg: string) => chalk.dim(`  ${msg}`),
+};

package/src/tools/trellis/render.ts

@@ -0,0 +1,212 @@
+import type { LoamBlock, Prompt, Section } from "./types.ts";
+import { MAX_INHERIT_DEPTH } from "./types.ts";
+
+export interface RenderResult {
+	sections: Section[];
+	frontmatter: Record<string, unknown>;
+	resolvedFrom: string[];
+	version: number;
+	loam?: LoamBlock;
+}
+
+/**
+ * Resolve a prompt's full section list by walking the inheritance chain
+ * and applying mixins. Resolution order:
+ * 1. Resolve extends chain (parent first)
+ * 2. For each mixin (left-to-right), resolve it fully
+ * 3. Merge: base → mixin₁ → mixin₂ → … → focal prompt
+ * Later entries override earlier on section name conflicts.
+ */
+export function resolvePrompt(name: string, prompts: Prompt[], version?: number): RenderResult {
+	const visited: string[] = [];
+	return resolveInner(name, prompts, version, visited);
+}
+
+function resolveInner(
+	name: string,
+	prompts: Prompt[],
+	version: number | undefined,
+	visited: string[],
+): RenderResult {
+	if (visited.includes(name)) {
+		throw new Error(`Circular inheritance: ${[...visited, name].join(" → ")}`);
+	}
+	if (visited.length >= MAX_INHERIT_DEPTH) {
+		throw new Error(
+			`Inheritance depth limit (${MAX_INHERIT_DEPTH}) exceeded at "${name}". Chain: ${visited.join(" → ")}`,
+		);
+	}
+
+	// Find the prompt
+	const prompt = findPrompt(prompts, name, version);
+	if (!prompt) {
+		const versionStr = version !== undefined ? `@${version}` : "";
+		throw new Error(`Prompt "${name}${versionStr}" not found`);
+	}
+
+	visited.push(name);
+
+	// No parent and no mixins — return own sections (excluding empty-body removals)
+	if (!prompt.extends && (!prompt.mixins || prompt.mixins.length === 0)) {
+		const sections = prompt.sections.filter((s) => s.body !== "");
+		return withLoam(
+			{
+				sections,
+				frontmatter: prompt.frontmatter ?? {},
+				resolvedFrom: [name],
+				version: prompt.version,
+			},
+			prompt.loam,
+		);
+	}
+
+	// Start with parent chain if exists
+	let baseSections: Section[] = [];
+	let baseFrontmatter: Record<string, unknown> = {};
+	let baseResolvedFrom: string[] = [];
+	let baseLoam: LoamBlock | undefined;
+	const mixinLoames: (LoamBlock | undefined)[] = [];
+
+	if (prompt.extends) {
+		const parentResult = resolveInner(prompt.extends, prompts, undefined, visited);
+		baseSections = parentResult.sections;
+		baseFrontmatter = parentResult.frontmatter;
+		baseResolvedFrom = parentResult.resolvedFrom;
+		baseLoam = parentResult.loam;
+	}
+
+	// Apply each mixin left-to-right on top of the base
+	if (prompt.mixins && prompt.mixins.length > 0) {
+		for (const mixinName of prompt.mixins) {
+			// Each mixin resolves with its own visited-branch to allow
+			// the same ancestor to appear via extends AND a mixin (diamond).
+			// But we must still detect cycles involving the focal prompt.
+			const mixinVisited = [...visited];
+			const mixinResult = resolveInner(mixinName, prompts, undefined, mixinVisited);
+			baseSections = mergeSections(baseSections, mixinResult.sections);
+			baseFrontmatter = { ...baseFrontmatter, ...mixinResult.frontmatter };
+			baseResolvedFrom = [...baseResolvedFrom, ...mixinResult.resolvedFrom];
+			mixinLoames.push(mixinResult.loam);
+		}
+	}
+
+	// Finally apply the focal prompt's own sections on top
+	const merged = mergeSections(baseSections, prompt.sections);
+
+	// Resolve loam with override-vs-merge semantics gated by extends_loam.
+	// extends_loam=true: union parent + each mixin's resolved loam + focal.loam
+	//   (domains/files unioned, budget/on_empty last-wins).
+	// extends_loam=false (default): focal.loam wholesale overrides — no inheritance,
+	//   not even from mixins. If focal has no loam block, result is undefined.
+	let resolvedLoam: LoamBlock | undefined;
+	if (prompt.extends_loam) {
+		resolvedLoam = baseLoam;
+		for (const m of mixinLoames) {
+			resolvedLoam = mergeLoam(resolvedLoam, m);
+		}
+		resolvedLoam = mergeLoam(resolvedLoam, prompt.loam);
+	} else {
+		resolvedLoam = prompt.loam;
+	}
+
+	return withLoam(
+		{
+			sections: merged,
+			frontmatter: { ...baseFrontmatter, ...(prompt.frontmatter ?? {}) },
+			resolvedFrom: [...baseResolvedFrom, name],
+			version: prompt.version,
+		},
+		resolvedLoam,
+	);
+}
+
+function withLoam(result: RenderResult, loam: LoamBlock | undefined): RenderResult {
+	if (loam === undefined) return result;
+	return { ...result, loam };
+}
+
+function mergeLoam(
+	base: LoamBlock | undefined,
+	overlay: LoamBlock | undefined,
+): LoamBlock | undefined {
+	if (base === undefined) return overlay;
+	if (overlay === undefined) return base;
+
+	const merged: LoamBlock = {};
+
+	const baseDomains = base.prime?.domains;
+	const overlayDomains = overlay.prime?.domains;
+	const baseFiles = base.prime?.files;
+	const overlayFiles = overlay.prime?.files;
+	const domains =
+		baseDomains || overlayDomains ? unionPreserveOrder(baseDomains, overlayDomains) : undefined;
+	const files = baseFiles || overlayFiles ? unionPreserveOrder(baseFiles, overlayFiles) : undefined;
+	if (domains !== undefined || files !== undefined) {
+		merged.prime = {};
+		if (domains !== undefined) merged.prime.domains = domains;
+		if (files !== undefined) merged.prime.files = files;
+	}
+
+	const budget = overlay.budget !== undefined ? overlay.budget : base.budget;
+	if (budget !== undefined) merged.budget = budget;
+
+	const on_empty = overlay.on_empty !== undefined ? overlay.on_empty : base.on_empty;
+	if (on_empty !== undefined) merged.on_empty = on_empty;
+
+	return merged;
+}
+
+function unionPreserveOrder(a: string[] | undefined, b: string[] | undefined): string[] {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const item of a ?? []) {
+		if (!seen.has(item)) {
+			seen.add(item);
+			out.push(item);
+		}
+	}
+	for (const item of b ?? []) {
+		if (!seen.has(item)) {
+			seen.add(item);
+			out.push(item);
+		}
+	}
+	return out;
+}
+
+function findPrompt(prompts: Prompt[], name: string, version?: number): Prompt | undefined {
+	if (version !== undefined) {
+		return prompts.find((p) => p.name === name && p.version === version);
+	}
+	// Get latest version for this name
+	const candidates = prompts.filter((p) => p.name === name);
+	if (candidates.length === 0) return undefined;
+	return candidates.reduce((best, p) => (p.version > best.version ? p : best));
+}
+
+function mergeSections(parentSections: Section[], childSections: Section[]): Section[] {
+	// Start with parent sections
+	const result: Section[] = [...parentSections];
+
+	for (const childSection of childSections) {
+		const parentIdx = result.findIndex((s) => s.name === childSection.name);
+
+		if (childSection.body === "") {
+			// Empty body = remove the section
+			if (parentIdx !== -1) {
+				result.splice(parentIdx, 1);
+			}
+			continue;
+		}
+
+		if (parentIdx !== -1) {
+			// Override parent section
+			result[parentIdx] = childSection;
+		} else {
+			// Append new section
+			result.push(childSection);
+		}
+	}
+
+	return result;
+}

package/src/tools/trellis/store.ts

@@ -0,0 +1,144 @@
+import { randomBytes } from "node:crypto";
+import { closeSync, constants, openSync, renameSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { LOCK_RETRY_MS, LOCK_STALE_MS, LOCK_TIMEOUT_MS } from "./types.ts";
+
+function lockPath(filePath: string): string {
+	return `${filePath}.lock`;
+}
+
+export async function acquireLock(filePath: string): Promise<void> {
+	const lock = lockPath(filePath);
+	const deadline = Date.now() + LOCK_TIMEOUT_MS;
+
+	while (Date.now() < deadline) {
+		try {
+			// O_CREAT | O_EXCL — atomic, fails if exists
+			const fd = openSync(lock, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY);
+			closeSync(fd);
+			return;
+		} catch (err: unknown) {
+			if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+
+			// Check if stale
+			try {
+				const stat = statSync(lock);
+				const age = Date.now() - stat.mtimeMs;
+				if (age > LOCK_STALE_MS) {
+					unlinkSync(lock);
+					continue;
+				}
+			} catch {
+				// Lock was removed between our check and stat — retry
+				continue;
+			}
+
+			await Bun.sleep(LOCK_RETRY_MS);
+		}
+	}
+
+	throw new Error(`Timeout acquiring lock on ${filePath} after ${LOCK_TIMEOUT_MS}ms`);
+}
+
+export function releaseLock(filePath: string): void {
+	try {
+		unlinkSync(lockPath(filePath));
+	} catch {
+		// Best-effort release
+	}
+}
+
+export async function readJsonl<T>(filePath: string): Promise<T[]> {
+	try {
+		const text = await Bun.file(filePath).text();
+		const records: T[] = [];
+
+		for (const line of text.split("\n")) {
+			const trimmed = line.trim();
+			if (!trimmed) continue;
+			try {
+				records.push(JSON.parse(trimmed) as T);
+			} catch {
+				// Skip malformed lines
+			}
+		}
+
+		return records;
+	} catch {
+		return [];
+	}
+}
+
+export async function writeJsonl<T>(filePath: string, records: T[]): Promise<void> {
+	const dir = filePath.substring(0, filePath.lastIndexOf("/"));
+	const tmp = join(dir, `.jsonl.tmp.${randomBytes(4).toString("hex")}`);
+
+	const lines = records.map((r) => JSON.stringify(r)).join("\n");
+	const content = lines ? `${lines}\n` : "";
+
+	await Bun.write(tmp, content);
+	renameSync(tmp, filePath);
+}
+
+export async function appendJsonl<T>(filePath: string, record: T): Promise<void> {
+	const line = `${JSON.stringify(record)}\n`;
+
+	// Check if file exists and has content
+	let existing = "";
+	try {
+		existing = await Bun.file(filePath).text();
+	} catch {
+		existing = "";
+	}
+
+	const content = existing ? existing + line : line;
+
+	const dir = filePath.substring(0, filePath.lastIndexOf("/"));
+	const tmp = join(dir, `.jsonl.tmp.${randomBytes(4).toString("hex")}`);
+
+	await Bun.write(tmp, content);
+	renameSync(tmp, filePath);
+}
+
+/**
+ * Dedup records by ID + version — last occurrence wins.
+ * For getting current state, return only highest version per ID.
+ */
+export function dedupById<T extends { id: string; version: number }>(records: T[]): T[] {
+	const map = new Map<string, T>();
+	for (const record of records) {
+		const existing = map.get(record.id);
+		if (!existing || record.version >= existing.version) {
+			map.set(record.id, record);
+		}
+	}
+	return Array.from(map.values());
+}
+
+/**
+ * Dedup records by ID — last occurrence wins (no version required).
+ * Use this for record types without version fields (e.g., schemas).
+ */
+export function dedupByIdLast<T extends { id: string }>(records: T[]): T[] {
+	const map = new Map<string, T>();
+	for (const record of records) {
+		map.set(record.id, record);
+	}
+	return Array.from(map.values());
+}
+
+/**
+ * Get all versions for a specific ID.
+ */
+export function getVersions<T extends { id: string; version: number }>(
+	records: T[],
+	id: string,
+): T[] {
+	const seen = new Map<number, T>();
+	for (const record of records) {
+		if (record.id === id) {
+			seen.set(record.version, record);
+		}
+	}
+	return Array.from(seen.values()).sort((a, b) => a.version - b.version);
+}