@agentplate/cli 1.0.0

package/src/mail/store.ts

@@ -0,0 +1,311 @@
+/**
+ * SQLite-backed mail store (low-level).
+ *
+ * The mail bus is how agents talk to each other and to the orchestrator. This
+ * module is the *storage* layer: a thin, synchronous CRUD wrapper over a single
+ * `messages` table. The higher-level mail client (broadcast resolution,
+ * `--inject` formatting, protocol semantics) is built on top of this store.
+ *
+ * Design notes:
+ * - The DB is opened through {@link openDatabase}, which applies WAL mode and a
+ *   busy timeout — both required because many agent processes poll the same file
+ *   concurrently (~ms-latency reads, occasional writes).
+ * - Columns are snake_case (SQL idiom); the public {@link MailMessage} shape is
+ *   camelCase. {@link rowToMessage} is the single translation point.
+ * - `read` is stored as an INTEGER (0/1) because SQLite has no boolean type.
+ * - This is a greenfield schema, so there is no migration logic: `CREATE TABLE
+ *   IF NOT EXISTS` is the whole story.
+ */
+
+import type { Database } from "bun:sqlite";
+import { openDatabase } from "../db/sqlite.ts";
+import { NotFoundError, ValidationError } from "../errors.ts";
+import type { MailMessage, MailPriority, MailType, NewMail } from "../types.ts";
+
+/** Filters accepted by {@link MailStore.list}. */
+export interface MailListFilter {
+	from?: string;
+	to?: string;
+	unread?: boolean;
+	limit?: number;
+}
+
+/** Options for {@link MailStore.purge}. */
+export interface MailPurgeOptions {
+	/** Delete messages strictly older than this many days. */
+	olderThanDays?: number;
+	/** Restrict to messages this agent sent or received. */
+	agent?: string;
+	/** Delete every message (ignores the other options when true). */
+	all?: boolean;
+}
+
+/** The low-level mail storage contract. */
+export interface MailStore {
+	/** Persist a new message; assigns id/createdAt/read and applies defaults. */
+	send(mail: NewMail): MailMessage;
+	/** Messages addressed to `agent`, newest first (optionally unread-only). */
+	getInbox(agent: string, opts?: { unreadOnly?: boolean }): MailMessage[];
+	/** Mark a single message read (no-op if the id does not exist). */
+	markRead(id: string): void;
+	/** Fetch one message by id, or null if absent. */
+	getById(id: string): MailMessage | null;
+	/** Query messages with optional filters, newest first. */
+	list(filter?: MailListFilter): MailMessage[];
+	/** Reply to a message in the same thread; returns the stored reply. */
+	reply(id: string, body: string, from: string): MailMessage;
+	/** Delete messages matching `opts`; returns the number deleted. */
+	purge(opts?: MailPurgeOptions): number;
+	/** Close the underlying database connection. */
+	close(): void;
+}
+
+/**
+ * Row shape as stored in SQLite. Distinct from {@link MailMessage} because
+ * columns are snake_case and `read` is an integer rather than a boolean.
+ */
+interface MessageRow {
+	/** Monotonic insertion sequence; the deterministic ordering tiebreak. */
+	seq: number;
+	id: string;
+	from_agent: string;
+	to_agent: string;
+	subject: string;
+	body: string;
+	type: string;
+	priority: string;
+	thread_id: string | null;
+	payload: string | null;
+	read: number;
+	created_at: string;
+}
+
+const CREATE_TABLE = `
+CREATE TABLE IF NOT EXISTS messages (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  id TEXT NOT NULL UNIQUE,
+  from_agent TEXT NOT NULL,
+  to_agent TEXT NOT NULL,
+  subject TEXT NOT NULL,
+  body TEXT NOT NULL,
+  type TEXT NOT NULL,
+  priority TEXT NOT NULL DEFAULT 'normal',
+  thread_id TEXT,
+  payload TEXT,
+  read INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL
+)`;
+
+// Indexes target the two hot read paths: inbox lookups (to_agent + read) and
+// thread reconstruction (thread_id). Created up front, not per query.
+const CREATE_INDEXES = `
+CREATE INDEX IF NOT EXISTS idx_messages_inbox ON messages(to_agent, read);
+CREATE INDEX IF NOT EXISTS idx_messages_thread ON messages(thread_id)`;
+
+/** Translate a stored row (snake_case, int boolean) into a {@link MailMessage}. */
+function rowToMessage(row: MessageRow): MailMessage {
+	return {
+		id: row.id,
+		from: row.from_agent,
+		to: row.to_agent,
+		subject: row.subject,
+		body: row.body,
+		// The CHECK-free schema trusts callers (typed at NewMail) for valid values;
+		// narrow back to the union here so consumers get the precise types.
+		type: row.type as MailType,
+		priority: row.priority as MailPriority,
+		threadId: row.thread_id,
+		payload: row.payload,
+		read: row.read === 1,
+		createdAt: row.created_at,
+	};
+}
+
+/** Insert one fully-resolved message and return the public view of it. */
+function insertMessage(db: Database, message: MailMessage): MailMessage {
+	db.query(
+		`INSERT INTO messages
+			(id, from_agent, to_agent, subject, body, type, priority, thread_id, payload, read, created_at)
+		VALUES
+			($id, $from, $to, $subject, $body, $type, $priority, $threadId, $payload, $read, $createdAt)`,
+	).run({
+		$id: message.id,
+		$from: message.from,
+		$to: message.to,
+		$subject: message.subject,
+		$body: message.body,
+		$type: message.type,
+		$priority: message.priority,
+		$threadId: message.threadId,
+		$payload: message.payload,
+		// SQLite stores booleans as integers.
+		$read: message.read ? 1 : 0,
+		$createdAt: message.createdAt,
+	});
+	return message;
+}
+
+/**
+ * Open (or create) a mail store backed by the SQLite database at `dbPath`.
+ * Pass `":memory:"` for an ephemeral store (used in tests).
+ */
+export function createMailStore(dbPath: string): MailStore {
+	// Guard on `messages.seq`: the unrelated @ag-eco/agentplate-cli uses a
+	// `messages` table without our `seq` column and a stricter `type` CHECK that
+	// would reject Agentplate's delivery-pipeline message types.
+	const db = openDatabase(dbPath, { guard: { table: "messages", columns: ["seq"] } });
+	db.exec(CREATE_TABLE);
+	db.exec(CREATE_INDEXES);
+
+	return {
+		send(mail: NewMail): MailMessage {
+			// `to`/`from` are the routing keys; an empty address would silently
+			// strand the message, so reject it early with a clear error.
+			if (mail.to.trim() === "") {
+				throw new ValidationError("mail.to must be a non-empty agent name");
+			}
+			if (mail.from.trim() === "") {
+				throw new ValidationError("mail.from must be a non-empty agent name");
+			}
+
+			const message: MailMessage = {
+				id: crypto.randomUUID(),
+				from: mail.from,
+				to: mail.to,
+				subject: mail.subject,
+				body: mail.body,
+				type: mail.type,
+				priority: mail.priority ?? "normal",
+				threadId: mail.threadId ?? null,
+				payload: mail.payload ?? null,
+				read: false,
+				createdAt: new Date().toISOString(),
+			};
+			return insertMessage(db, message);
+		},
+
+		getInbox(agent: string, opts?: { unreadOnly?: boolean }): MailMessage[] {
+			// Newest first so callers see the most recent messages at the top. The
+			// seq tiebreak makes ordering deterministic even when many messages
+			// share a created_at (sub-millisecond inserts); UUID ids would not.
+			const sql = opts?.unreadOnly
+				? `SELECT * FROM messages WHERE to_agent = $agent AND read = 0 ORDER BY created_at DESC, seq DESC`
+				: `SELECT * FROM messages WHERE to_agent = $agent ORDER BY created_at DESC, seq DESC`;
+			const rows = db.query(sql).all({ $agent: agent }) as MessageRow[];
+			return rows.map(rowToMessage);
+		},
+
+		markRead(id: string): void {
+			db.query("UPDATE messages SET read = 1 WHERE id = $id").run({ $id: id });
+		},
+
+		getById(id: string): MailMessage | null {
+			const row = db
+				.query("SELECT * FROM messages WHERE id = $id")
+				.get({ $id: id }) as MessageRow | null;
+			return row ? rowToMessage(row) : null;
+		},
+
+		list(filter?: MailListFilter): MailMessage[] {
+			// Build the WHERE clause dynamically from whichever filters are set.
+			// Parameters are always bound (never interpolated) to avoid injection.
+			const conditions: string[] = [];
+			const params: Record<string, string | number> = {};
+
+			if (filter?.from !== undefined) {
+				conditions.push("from_agent = $from");
+				params.$from = filter.from;
+			}
+			if (filter?.to !== undefined) {
+				conditions.push("to_agent = $to");
+				params.$to = filter.to;
+			}
+			if (filter?.unread !== undefined) {
+				conditions.push("read = $read");
+				params.$read = filter.unread ? 0 : 1;
+			}
+
+			const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+			let sql = `SELECT * FROM messages ${where} ORDER BY created_at DESC, seq DESC`;
+			if (filter?.limit !== undefined) {
+				sql += " LIMIT $limit";
+				params.$limit = filter.limit;
+			}
+
+			const rows = db.query(sql).all(params) as MessageRow[];
+			return rows.map(rowToMessage);
+		},
+
+		reply(id: string, body: string, from: string): MailMessage {
+			const original = this.getById(id);
+			if (!original) {
+				throw new NotFoundError(`Cannot reply: message "${id}" not found`);
+			}
+
+			// A reply joins the original's thread. If the original started a new
+			// thread (threadId === null) we adopt its id as the thread root so the
+			// whole exchange shares one thread id.
+			const reply: MailMessage = {
+				id: crypto.randomUUID(),
+				from,
+				to: original.from,
+				subject: original.subject,
+				body,
+				type: "result",
+				priority: original.priority,
+				threadId: original.threadId ?? original.id,
+				payload: null,
+				read: false,
+				createdAt: new Date().toISOString(),
+			};
+			return insertMessage(db, reply);
+		},
+
+		purge(opts?: MailPurgeOptions): number {
+			// `all` is the nuclear option and ignores the finer-grained filters.
+			if (opts?.all) {
+				const before = countRows(db, "", {});
+				db.query("DELETE FROM messages").run();
+				return before;
+			}
+
+			const conditions: string[] = [];
+			const params: Record<string, string> = {};
+
+			if (opts?.olderThanDays !== undefined) {
+				// Cutoff is an ISO timestamp so the comparison matches created_at's
+				// lexicographic ordering (ISO-8601 sorts chronologically as text).
+				const cutoffMs = Date.now() - opts.olderThanDays * 24 * 60 * 60 * 1000;
+				conditions.push("created_at < $cutoff");
+				params.$cutoff = new Date(cutoffMs).toISOString();
+			}
+			if (opts?.agent !== undefined) {
+				conditions.push("(from_agent = $agent OR to_agent = $agent)");
+				params.$agent = opts.agent;
+			}
+
+			// With no criteria there is nothing to purge — refuse to wipe the table
+			// implicitly (that path is reserved for the explicit `all` flag).
+			if (conditions.length === 0) {
+				return 0;
+			}
+
+			const where = `WHERE ${conditions.join(" AND ")}`;
+			const before = countRows(db, where, params);
+			db.query(`DELETE FROM messages ${where}`).run(params);
+			return before;
+		},
+
+		close(): void {
+			db.close();
+		},
+	};
+}
+
+/** Count rows matching an optional WHERE clause (used to report purge totals). */
+function countRows(db: Database, where: string, params: Record<string, string | number>): number {
+	const row = db.query(`SELECT COUNT(*) AS n FROM messages ${where}`).get(params) as {
+		n: number;
+	} | null;
+	return row?.n ?? 0;
+}

package/src/merge/lock.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Tests for the sentinel-file merge lock.
+ *
+ * Uses real temp directories so the O_EXCL filesystem semantics are genuinely
+ * exercised (no mocking of fs). Each test works inside a fresh temp root that
+ * stands in for a project root containing `.agentplate/`.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { WorktreeError } from "../errors.ts";
+import { acquireMergeLock, releaseMergeLock, withMergeLock } from "./lock.ts";
+
+let root: string;
+
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "agentplate-lock-"));
+});
+
+afterEach(() => {
+	// Best-effort: drop the lock before removing the tree.
+	releaseMergeLock(root);
+	rmSync(root, { recursive: true, force: true });
+});
+
+describe("acquireMergeLock / releaseMergeLock", () => {
+	test("first acquire succeeds and creates the sentinel file", () => {
+		expect(acquireMergeLock(root)).toBe(true);
+		expect(existsSync(join(root, ".agentplate", "merge.lock"))).toBe(true);
+	});
+
+	test("second acquire fails while the lock is held, then succeeds after release", () => {
+		expect(acquireMergeLock(root)).toBe(true);
+		// Lock is held: a second attempt must report contention (false), not throw.
+		expect(acquireMergeLock(root)).toBe(false);
+
+		releaseMergeLock(root);
+		// After release the lock is free again.
+		expect(acquireMergeLock(root)).toBe(true);
+	});
+
+	test("releaseMergeLock is idempotent (no throw when already released)", () => {
+		expect(acquireMergeLock(root)).toBe(true);
+		releaseMergeLock(root);
+		expect(() => releaseMergeLock(root)).not.toThrow();
+		expect(existsSync(join(root, ".agentplate", "merge.lock"))).toBe(false);
+	});
+
+	test("acquire creates .agentplate/ if it does not exist", () => {
+		// Fresh temp root has no .agentplate/ subdir yet.
+		expect(existsSync(join(root, ".agentplate"))).toBe(false);
+		expect(acquireMergeLock(root)).toBe(true);
+		expect(existsSync(join(root, ".agentplate"))).toBe(true);
+	});
+});
+
+describe("withMergeLock", () => {
+	test("runs fn while holding the lock and releases afterward", async () => {
+		let observedDuringRun = false;
+		const result = await withMergeLock(root, async () => {
+			// Inside the critical section the lock is held, so a fresh acquire fails.
+			observedDuringRun = acquireMergeLock(root) === false;
+			return 42;
+		});
+		expect(result).toBe(42);
+		expect(observedDuringRun).toBe(true);
+		// Lock released after the body resolved: it can be taken again.
+		expect(acquireMergeLock(root)).toBe(true);
+	});
+
+	test("releases the lock even when fn throws", async () => {
+		await expect(
+			withMergeLock(root, async () => {
+				throw new Error("boom");
+			}),
+		).rejects.toThrow("boom");
+		// Despite the throw, the lock must be free.
+		expect(acquireMergeLock(root)).toBe(true);
+	});
+
+	test("throws WorktreeError if the lock is already held", async () => {
+		expect(acquireMergeLock(root)).toBe(true);
+		await expect(withMergeLock(root, async () => "unused")).rejects.toBeInstanceOf(WorktreeError);
+	});
+});

package/src/merge/lock.ts

@@ -0,0 +1,84 @@
+// Sentinel-file merge lock.
+//
+// WHY a file lock (and not an in-process mutex or a SQLite row): `agentplate merge`
+// can be invoked by several independent processes at once (the operator's shell,
+// the coordinator agent, a watchdog retry). They are separate OS processes, so an
+// in-memory lock is useless. A sentinel file created with O_EXCL is atomic at the
+// filesystem level — exactly one caller can win the create, everyone else sees
+// EEXIST — which gives us a cheap cross-process mutex without a daemon.
+//
+// We deliberately keep this dumb: no PID tracking, no stale-lock reaping. The lock
+// is held only for the duration of a single `withMergeLock` body (one merge), and
+// `releaseMergeLock` runs in a `finally`, so a crash mid-merge is the only way to
+// leak it. Recovering from that is a manual `agentplate clean`-style concern, not
+// something we want to guess at here (auto-reaping a "stale" lock races with a
+// merge that is simply slow).
+
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { WorktreeError } from "../errors.ts";
+
+/** Absolute path to the sentinel file for a given project root. */
+function lockPath(root: string): string {
+	return join(root, ".agentplate", "merge.lock");
+}
+
+/**
+ * Try to acquire the merge lock for `root`.
+ *
+ * Returns `true` if this call created the sentinel (caller now holds the lock),
+ * `false` if it was already held by someone else. Never throws on contention —
+ * contention is an expected, recoverable condition the caller decides how to
+ * handle.
+ */
+export function acquireMergeLock(root: string): boolean {
+	const path = lockPath(root);
+	// Ensure `.agentplate/` exists; a fresh checkout or a targeted test dir may not
+	// have it yet, and `wx` would otherwise fail with ENOENT instead of EEXIST.
+	mkdirSync(dirname(path), { recursive: true });
+	try {
+		// `flag: "wx"` === open(O_CREAT | O_EXCL | O_WRONLY): atomic create-or-fail.
+		// The payload is informational only (a timestamp aids manual debugging).
+		writeFileSync(path, `${new Date().toISOString()}\n`, { flag: "wx" });
+		return true;
+	} catch (err) {
+		// EEXIST means another process holds the lock — the one outcome we treat as
+		// "not acquired" rather than an error. Anything else (EACCES, EROFS, …) is a
+		// real filesystem failure and must surface.
+		if (err instanceof Error && "code" in err && err.code === "EEXIST") {
+			return false;
+		}
+		throw err;
+	}
+}
+
+/**
+ * Release the merge lock for `root`. Idempotent: removing an already-absent lock
+ * is a no-op, so double-release (e.g. a `finally` after an early manual release)
+ * is safe.
+ */
+export function releaseMergeLock(root: string): void {
+	const path = lockPath(root);
+	if (existsSync(path)) {
+		rmSync(path, { force: true });
+	}
+}
+
+/**
+ * Run `fn` while holding the merge lock, releasing it afterwards no matter how
+ * `fn` settles. Throws `WorktreeError` if the lock is already held — callers that
+ * want to wait/retry should loop on `acquireMergeLock` themselves.
+ */
+export async function withMergeLock<T>(root: string, fn: () => Promise<T>): Promise<T> {
+	if (!acquireMergeLock(root)) {
+		throw new WorktreeError(
+			`Merge lock is already held (${lockPath(root)}). Another merge is in progress.`,
+		);
+	}
+	try {
+		return await fn();
+	} finally {
+		releaseMergeLock(root);
+	}
+}

package/src/merge/queue.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Tests for the FIFO merge queue.
+ *
+ * Uses a real on-disk temp-file SQLite database (not `:memory:`) so we exercise
+ * the same WAL-mode path production uses; an in-memory DB would skip WAL/journal
+ * behavior entirely. Each test gets a fresh temp directory.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { MergeEntry } from "../types.ts";
+import { createMergeQueue, type MergeQueue } from "./queue.ts";
+
+let dir: string;
+let queue: MergeQueue;
+
+/** Convenience: enqueue with sensible defaults, overridable per field. */
+function add(overrides: Partial<Omit<MergeEntry, "id" | "createdAt" | "status">> = {}): MergeEntry {
+	return queue.enqueue({
+		branchName: overrides.branchName ?? "agent/feature",
+		agentName: overrides.agentName ?? "builder-1",
+		taskId: overrides.taskId ?? "task-1",
+		targetBranch: overrides.targetBranch ?? "main",
+	});
+}
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "agentplate-queue-"));
+	queue = createMergeQueue(join(dir, "merge-queue.db"));
+});
+
+afterEach(() => {
+	queue.close();
+	rmSync(dir, { recursive: true, force: true });
+});
+
+describe("createMergeQueue", () => {
+	test("enqueue assigns id, createdAt, and pending status", () => {
+		const entry = add({ branchName: "agent/a", agentName: "a", taskId: "t-a" });
+		expect(entry.id).toBeString();
+		expect(entry.id.length).toBeGreaterThan(0);
+		expect(entry.status).toBe("pending");
+		expect(entry.branchName).toBe("agent/a");
+		expect(entry.agentName).toBe("a");
+		expect(entry.taskId).toBe("t-a");
+		expect(entry.targetBranch).toBe("main");
+		// createdAt is an ISO-8601 string round-trippable through Date.
+		expect(new Date(entry.createdAt).toISOString()).toBe(entry.createdAt);
+	});
+
+	test("each enqueue produces a unique id", () => {
+		const a = add();
+		const b = add();
+		expect(a.id).not.toBe(b.id);
+	});
+
+	test("listPending returns only pending entries, oldest first", () => {
+		const a = add({ branchName: "agent/a" });
+		const b = add({ branchName: "agent/b" });
+		const c = add({ branchName: "agent/c" });
+
+		// Mark the middle one merged — it should drop out of listPending.
+		queue.markStatus(b.id, "merged");
+
+		const pending = queue.listPending();
+		expect(pending.map((e) => e.branchName)).toEqual(["agent/a", "agent/c"]);
+		expect(pending.map((e) => e.id)).toEqual([a.id, c.id]);
+	});
+
+	test("dequeue removes and returns the oldest pending entry (FIFO)", () => {
+		const first = add({ branchName: "agent/first" });
+		const second = add({ branchName: "agent/second" });
+
+		const dq1 = queue.dequeue();
+		expect(dq1?.id).toBe(first.id);
+		expect(dq1?.branchName).toBe("agent/first");
+
+		// It is gone now; the next dequeue yields the second entry.
+		const dq2 = queue.dequeue();
+		expect(dq2?.id).toBe(second.id);
+
+		expect(queue.dequeue()).toBeNull();
+		expect(queue.listPending()).toHaveLength(0);
+	});
+
+	test("dequeue skips non-pending entries", () => {
+		const a = add({ branchName: "agent/a" });
+		const b = add({ branchName: "agent/b" });
+
+		// First entry already failed — dequeue must return the next pending one.
+		queue.markStatus(a.id, "failed");
+
+		const dq = queue.dequeue();
+		expect(dq?.id).toBe(b.id);
+		// The failed entry remains in the table (it was not dequeued).
+		expect(queue.listPending()).toHaveLength(0);
+	});
+
+	test("dequeue returns null on an empty queue", () => {
+		expect(queue.dequeue()).toBeNull();
+	});
+
+	test("markStatus updates an entry and removes it from listPending", () => {
+		const a = add();
+		expect(queue.listPending()).toHaveLength(1);
+
+		queue.markStatus(a.id, "merged");
+		expect(queue.listPending()).toHaveLength(0);
+	});
+
+	test("markStatus throws NotFoundError for an unknown id", () => {
+		expect(() => queue.markStatus("does-not-exist", "merged")).toThrow(
+			/No merge queue entry with id/,
+		);
+	});
+
+	test("queue state persists across reopen (same db file)", () => {
+		const a = add({ branchName: "agent/persist" });
+		queue.close();
+
+		const reopened = createMergeQueue(join(dir, "merge-queue.db"));
+		try {
+			const pending = reopened.listPending();
+			expect(pending).toHaveLength(1);
+			expect(pending[0]?.id).toBe(a.id);
+			expect(pending[0]?.branchName).toBe("agent/persist");
+		} finally {
+			reopened.close();
+			// Re-open the module-level handle so afterEach's close() is valid.
+			queue = createMergeQueue(join(dir, "merge-queue.db"));
+		}
+	});
+});