@os-eco/overstory-cli 0.6.1

package/src/merge/queue.test.ts

@@ -0,0 +1,359 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MergeError } from "../errors.ts";
+import { createMergeQueue } from "./queue.ts";
+
+describe("createMergeQueue", () => {
+	let tempDir: string;
+	let queuePath: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "overstory-merge-queue-test-"));
+		// The database file should NOT exist initially — createMergeQueue handles this
+		queuePath = join(tempDir, "merge-queue.db");
+	});
+
+	afterEach(async () => {
+		await rm(tempDir, { recursive: true, force: true });
+	});
+
+	function makeInput(
+		overrides?: Partial<{
+			branchName: string;
+			beadId: string;
+			agentName: string;
+			filesModified: string[];
+		}>,
+	) {
+		return {
+			branchName: overrides?.branchName ?? "overstory/test-agent/bead-123",
+			beadId: overrides?.beadId ?? "bead-123",
+			agentName: overrides?.agentName ?? "test-agent",
+			filesModified: overrides?.filesModified ?? ["src/test.ts"],
+		};
+	}
+
+	describe("enqueue", () => {
+		test("adds entry with pending status and null resolvedTier", () => {
+			const queue = createMergeQueue(queuePath);
+			const entry = queue.enqueue(makeInput());
+
+			expect(entry.status).toBe("pending");
+			expect(entry.resolvedTier).toBeNull();
+		});
+
+		test("returns the created entry with enqueuedAt timestamp", () => {
+			const queue = createMergeQueue(queuePath);
+			const before = new Date().toISOString();
+			const entry = queue.enqueue(makeInput());
+			const after = new Date().toISOString();
+
+			expect(entry.branchName).toBe("overstory/test-agent/bead-123");
+			expect(entry.beadId).toBe("bead-123");
+			expect(entry.agentName).toBe("test-agent");
+			expect(entry.filesModified).toEqual(["src/test.ts"]);
+			expect(entry.enqueuedAt).toBeDefined();
+			// enqueuedAt should be between before and after
+			expect(entry.enqueuedAt >= before).toBe(true);
+			expect(entry.enqueuedAt <= after).toBe(true);
+		});
+
+		test("preserves all input fields on the returned entry", () => {
+			const queue = createMergeQueue(queuePath);
+			const input = makeInput({
+				branchName: "overstory/builder-1/bead-xyz",
+				beadId: "bead-xyz",
+				agentName: "builder-1",
+				filesModified: ["src/a.ts", "src/b.ts"],
+			});
+
+			const entry = queue.enqueue(input);
+
+			expect(entry.branchName).toBe("overstory/builder-1/bead-xyz");
+			expect(entry.beadId).toBe("bead-xyz");
+			expect(entry.agentName).toBe("builder-1");
+			expect(entry.filesModified).toEqual(["src/a.ts", "src/b.ts"]);
+		});
+	});
+
+	describe("dequeue", () => {
+		test("returns first pending entry (FIFO)", () => {
+			const queue = createMergeQueue(queuePath);
+			queue.enqueue(makeInput({ branchName: "branch-a", beadId: "bead-a" }));
+			queue.enqueue(makeInput({ branchName: "branch-b", beadId: "bead-b" }));
+
+			const dequeued = queue.dequeue();
+
+			expect(dequeued).not.toBeNull();
+			expect(dequeued?.branchName).toBe("branch-a");
+		});
+
+		test("removes the entry from the queue", () => {
+			const queue = createMergeQueue(queuePath);
+			queue.enqueue(makeInput({ branchName: "branch-a" }));
+			queue.enqueue(makeInput({ branchName: "branch-b" }));
+
+			queue.dequeue();
+			const all = queue.list();
+
+			expect(all).toHaveLength(1);
+			expect(all[0]?.branchName).toBe("branch-b");
+		});
+
+		test("returns null on empty queue", () => {
+			const queue = createMergeQueue(queuePath);
+			const result = queue.dequeue();
+
+			expect(result).toBeNull();
+		});
+
+		test("skips non-pending entries", () => {
+			const queue = createMergeQueue(queuePath);
+			queue.enqueue(makeInput({ branchName: "branch-a" }));
+			queue.enqueue(makeInput({ branchName: "branch-b" }));
+
+			// Mark the first entry as "merging" so it's no longer pending
+			queue.updateStatus("branch-a", "merging");
+
+			const dequeued = queue.dequeue();
+
+			expect(dequeued).not.toBeNull();
+			expect(dequeued?.branchName).toBe("branch-b");
+		});
+
+		test("returns null when all entries are non-pending", () => {
+			const queue = createMergeQueue(queuePath);
+			queue.enqueue(makeInput({ branchName: "branch-a" }));
+			queue.updateStatus("branch-a", "merged", "clean-merge");
+
+			const result = queue.dequeue();
+
+			expect(result).toBeNull();
+		});
+	});
+
+	describe("peek", () => {
+		test("returns first pending entry without removing it", () => {
+			const queue = createMergeQueue(queuePath);
+			queue.enqueue(makeInput({ branchName: "branch-a" }));
+			queue.enqueue(makeInput({ branchName: "branch-b" }));
+
+			const peeked = queue.peek();
+
+			expect(peeked).not.toBeNull();
+			expect(peeked?.branchName).toBe("branch-a");
+
+			// Entry should still be in the queue
+			const all = queue.list();
+			expect(all).toHaveLength(2);
+		});
+
+		test("returns null on empty queue", () => {
+			const queue = createMergeQueue(queuePath);
+			const result = queue.peek();
+
+			expect(result).toBeNull();
+		});
+
+		test("skips non-pending entries", () => {
+			const queue = createMergeQueue(queuePath);
+			queue.enqueue(makeInput({ branchName: "branch-a" }));
+			queue.enqueue(makeInput({ branchName: "branch-b" }));
+			queue.updateStatus("branch-a", "merged", "clean-merge");
+
+			const peeked = queue.peek();
+
+			expect(peeked).not.toBeNull();
+			expect(peeked?.branchName).toBe("branch-b");
+		});
+	});
+
+	describe("list", () => {
+		test("returns all entries when called without arguments", () => {
+			const queue = createMergeQueue(queuePath);
+			queue.enqueue(makeInput({ branchName: "branch-a" }));
+			queue.enqueue(makeInput({ branchName: "branch-b" }));
+			queue.updateStatus("branch-a", "merged", "clean-merge");
+
+			const all = queue.list();
+
+			expect(all).toHaveLength(2);
+		});
+
+		test("returns empty array on empty queue", () => {
+			const queue = createMergeQueue(queuePath);
+			const all = queue.list();
+
+			expect(all).toEqual([]);
+		});
+
+		test("filters by status when status argument is provided", () => {
+			const queue = createMergeQueue(queuePath);
+			queue.enqueue(makeInput({ branchName: "branch-a" }));
+			queue.enqueue(makeInput({ branchName: "branch-b" }));
+			queue.enqueue(makeInput({ branchName: "branch-c" }));
+			queue.updateStatus("branch-a", "merged", "clean-merge");
+			queue.updateStatus("branch-b", "failed");
+
+			const pending = queue.list("pending");
+			expect(pending).toHaveLength(1);
+			expect(pending[0]?.branchName).toBe("branch-c");
+
+			const merged = queue.list("merged");
+			expect(merged).toHaveLength(1);
+			expect(merged[0]?.branchName).toBe("branch-a");
+
+			const failed = queue.list("failed");
+			expect(failed).toHaveLength(1);
+			expect(failed[0]?.branchName).toBe("branch-b");
+		});
+	});
+
+	describe("updateStatus", () => {
+		test("changes status of an existing entry", () => {
+			const queue = createMergeQueue(queuePath);
+			queue.enqueue(makeInput({ branchName: "branch-a" }));
+
+			queue.updateStatus("branch-a", "merging");
+
+			const all = queue.list();
+			expect(all[0]?.status).toBe("merging");
+			expect(all[0]?.resolvedTier).toBeNull();
+		});
+
+		test("changes status and tier when tier is provided", () => {
+			const queue = createMergeQueue(queuePath);
+			queue.enqueue(makeInput({ branchName: "branch-a" }));
+
+			queue.updateStatus("branch-a", "merged", "auto-resolve");
+
+			const all = queue.list();
+			expect(all[0]?.status).toBe("merged");
+			expect(all[0]?.resolvedTier).toBe("auto-resolve");
+		});
+
+		test("throws MergeError for unknown branch", () => {
+			const queue = createMergeQueue(queuePath);
+			queue.enqueue(makeInput({ branchName: "branch-a" }));
+
+			expect(() => queue.updateStatus("nonexistent-branch", "merging")).toThrow(MergeError);
+		});
+
+		test("MergeError includes the unknown branch name in message", () => {
+			const queue = createMergeQueue(queuePath);
+
+			try {
+				queue.updateStatus("nonexistent-branch", "merging");
+				// Should not reach here
+				expect(true).toBe(false);
+			} catch (err: unknown) {
+				expect(err).toBeInstanceOf(MergeError);
+				const mergeErr = err as MergeError;
+				expect(mergeErr.message).toContain("nonexistent-branch");
+			}
+		});
+	});
+
+	describe("FIFO ordering", () => {
+		test("multiple enqueue/dequeue preserves FIFO order", () => {
+			const queue = createMergeQueue(queuePath);
+			queue.enqueue(makeInput({ branchName: "first" }));
+			queue.enqueue(makeInput({ branchName: "second" }));
+			queue.enqueue(makeInput({ branchName: "third" }));
+
+			const d1 = queue.dequeue();
+			const d2 = queue.dequeue();
+			const d3 = queue.dequeue();
+			const d4 = queue.dequeue();
+
+			expect(d1?.branchName).toBe("first");
+			expect(d2?.branchName).toBe("second");
+			expect(d3?.branchName).toBe("third");
+			expect(d4).toBeNull();
+		});
+
+		test("interleaved enqueue and dequeue preserves order", () => {
+			const queue = createMergeQueue(queuePath);
+			queue.enqueue(makeInput({ branchName: "first" }));
+			queue.enqueue(makeInput({ branchName: "second" }));
+
+			const d1 = queue.dequeue();
+			expect(d1?.branchName).toBe("first");
+
+			queue.enqueue(makeInput({ branchName: "third" }));
+
+			const d2 = queue.dequeue();
+			expect(d2?.branchName).toBe("second");
+
+			const d3 = queue.dequeue();
+			expect(d3?.branchName).toBe("third");
+		});
+	});
+
+	describe("persistence", () => {
+		test("queue survives across separate createMergeQueue calls", () => {
+			const queue1 = createMergeQueue(queuePath);
+			queue1.enqueue(makeInput({ branchName: "branch-a" }));
+			queue1.enqueue(makeInput({ branchName: "branch-b" }));
+
+			// Create a new queue instance pointing at the same file
+			const queue2 = createMergeQueue(queuePath);
+			const all = queue2.list();
+
+			expect(all).toHaveLength(2);
+			expect(all[0]?.branchName).toBe("branch-a");
+			expect(all[1]?.branchName).toBe("branch-b");
+		});
+
+		test("dequeue from one instance is visible from another", () => {
+			const queue1 = createMergeQueue(queuePath);
+			queue1.enqueue(makeInput({ branchName: "branch-a" }));
+			queue1.enqueue(makeInput({ branchName: "branch-b" }));
+
+			const queue2 = createMergeQueue(queuePath);
+			queue2.dequeue();
+
+			const all = queue1.list();
+			expect(all).toHaveLength(1);
+			expect(all[0]?.branchName).toBe("branch-b");
+		});
+
+		test("updateStatus from one instance is visible from another", () => {
+			const queue1 = createMergeQueue(queuePath);
+			queue1.enqueue(makeInput({ branchName: "branch-a" }));
+
+			const queue2 = createMergeQueue(queuePath);
+			queue2.updateStatus("branch-a", "merged", "clean-merge");
+
+			const all = queue1.list();
+			expect(all[0]?.status).toBe("merged");
+			expect(all[0]?.resolvedTier).toBe("clean-merge");
+		});
+	});
+
+	describe("close", () => {
+		test("closes the database connection", () => {
+			const queue = createMergeQueue(queuePath);
+			queue.enqueue(makeInput({ branchName: "branch-a" }));
+
+			// Should not throw
+			expect(() => queue.close()).not.toThrow();
+		});
+
+		test("database can be reopened after close", () => {
+			const queue1 = createMergeQueue(queuePath);
+			queue1.enqueue(makeInput({ branchName: "branch-a" }));
+			queue1.close();
+
+			// Create a new queue instance after closing the first one
+			const queue2 = createMergeQueue(queuePath);
+			const all = queue2.list();
+
+			expect(all).toHaveLength(1);
+			expect(all[0]?.branchName).toBe("branch-a");
+			queue2.close();
+		});
+	});
+});

package/src/merge/queue.ts

@@ -0,0 +1,231 @@
+/**
+ * SQLite-backed FIFO merge queue for agent branches.
+ *
+ * Backed by a SQLite database with WAL mode for concurrent access.
+ * Uses bun:sqlite for zero-dependency, synchronous database access.
+ * FIFO ordering guaranteed via autoincrement id.
+ */
+
+import { Database } from "bun:sqlite";
+import { MergeError } from "../errors.ts";
+import type { MergeEntry, ResolutionTier } from "../types.ts";
+
+export interface MergeQueue {
+	/** Add a new entry to the end of the queue with pending status. */
+	enqueue(entry: Omit<MergeEntry, "enqueuedAt" | "status" | "resolvedTier">): MergeEntry;
+
+	/** Remove and return the first pending entry, or null if none. */
+	dequeue(): MergeEntry | null;
+
+	/** Return the first pending entry without removing it, or null if none. */
+	peek(): MergeEntry | null;
+
+	/** List entries, optionally filtered by status. */
+	list(status?: MergeEntry["status"]): MergeEntry[];
+
+	/** Update the status (and optional resolution tier) of an entry by branch name. */
+	updateStatus(branchName: string, status: MergeEntry["status"], tier?: ResolutionTier): void;
+
+	/** Close the database connection. */
+	close(): void;
+}
+
+/** Row shape as stored in SQLite (snake_case columns). */
+interface MergeQueueRow {
+	id: number;
+	branch_name: string;
+	task_id: string;
+	agent_name: string;
+	files_modified: string; // JSON array stored as text
+	enqueued_at: string;
+	status: string;
+	resolved_tier: string | null;
+}
+
+const CREATE_TABLE = `
+CREATE TABLE IF NOT EXISTS merge_queue (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  branch_name TEXT NOT NULL,
+  task_id TEXT NOT NULL,
+  agent_name TEXT NOT NULL,
+  files_modified TEXT NOT NULL DEFAULT '[]',
+  enqueued_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f','now')),
+  status TEXT NOT NULL DEFAULT 'pending'
+    CHECK(status IN ('pending','merging','merged','conflict','failed')),
+  resolved_tier TEXT
+    CHECK(resolved_tier IS NULL OR resolved_tier IN ('clean-merge','auto-resolve','ai-resolve','reimagine'))
+)`;
+
+const CREATE_INDEXES = `
+CREATE INDEX IF NOT EXISTS idx_merge_queue_status ON merge_queue(status);
+CREATE INDEX IF NOT EXISTS idx_merge_queue_branch ON merge_queue(branch_name)`;
+
+/** Convert a database row (snake_case) to a MergeEntry object (camelCase). */
+function rowToEntry(row: MergeQueueRow): MergeEntry {
+	// Parse files_modified from JSON string to array, with fallback to empty array
+	let filesModified: string[] = [];
+	try {
+		const parsed = JSON.parse(row.files_modified);
+		filesModified = Array.isArray(parsed) ? parsed : [];
+	} catch {
+		// Fallback to empty array on parse error
+		filesModified = [];
+	}
+
+	return {
+		branchName: row.branch_name,
+		beadId: row.task_id,
+		agentName: row.agent_name,
+		filesModified,
+		enqueuedAt: row.enqueued_at,
+		status: row.status as MergeEntry["status"],
+		resolvedTier: row.resolved_tier as ResolutionTier | null,
+	};
+}
+
+/**
+ * Create a new MergeQueue backed by a SQLite database at the given path.
+ *
+ * Initializes the database with WAL mode and a 5-second busy timeout.
+ * Creates the merge_queue table and indexes if they do not already exist.
+ */
+export function createMergeQueue(dbPath: string): MergeQueue {
+	const db = new Database(dbPath);
+
+	// Configure for concurrent access from multiple agent processes
+	db.exec("PRAGMA journal_mode = WAL");
+	db.exec("PRAGMA synchronous = NORMAL");
+	db.exec("PRAGMA busy_timeout = 5000");
+
+	// Create schema
+	db.exec(CREATE_TABLE);
+	db.exec(CREATE_INDEXES);
+
+	// Prepare statements for frequent operations
+	const insertStmt = db.prepare<
+		MergeQueueRow,
+		{
+			$branch_name: string;
+			$task_id: string;
+			$agent_name: string;
+			$files_modified: string;
+			$enqueued_at: string;
+		}
+	>(`
+		INSERT INTO merge_queue (branch_name, task_id, agent_name, files_modified, enqueued_at)
+		VALUES ($branch_name, $task_id, $agent_name, $files_modified, $enqueued_at)
+		RETURNING *
+	`);
+
+	const getFirstPendingStmt = db.prepare<MergeQueueRow, Record<string, never>>(`
+		SELECT * FROM merge_queue WHERE status = 'pending' ORDER BY id ASC LIMIT 1
+	`);
+
+	const deleteByIdStmt = db.prepare<void, { $id: number }>(`
+		DELETE FROM merge_queue WHERE id = $id
+	`);
+
+	const listAllStmt = db.prepare<MergeQueueRow, Record<string, never>>(`
+		SELECT * FROM merge_queue ORDER BY id ASC
+	`);
+
+	const listByStatusStmt = db.prepare<MergeQueueRow, { $status: string }>(`
+		SELECT * FROM merge_queue WHERE status = $status ORDER BY id ASC
+	`);
+
+	const getByBranchStmt = db.prepare<MergeQueueRow, { $branch_name: string }>(`
+		SELECT * FROM merge_queue WHERE branch_name = $branch_name
+	`);
+
+	const updateStatusStmt = db.prepare<
+		void,
+		{
+			$branch_name: string;
+			$status: string;
+			$resolved_tier: string | null;
+		}
+	>(`
+		UPDATE merge_queue
+		SET status = $status, resolved_tier = $resolved_tier
+		WHERE branch_name = $branch_name
+	`);
+
+	return {
+		enqueue(input): MergeEntry {
+			const filesModifiedJson = JSON.stringify(input.filesModified);
+			const enqueuedAt = new Date().toISOString();
+
+			const row = insertStmt.get({
+				$branch_name: input.branchName,
+				$task_id: input.beadId,
+				$agent_name: input.agentName,
+				$files_modified: filesModifiedJson,
+				$enqueued_at: enqueuedAt,
+			});
+
+			if (row === null || row === undefined) {
+				throw new MergeError("Failed to insert entry into merge queue");
+			}
+
+			return rowToEntry(row);
+		},
+
+		dequeue(): MergeEntry | null {
+			const row = getFirstPendingStmt.get({});
+
+			if (row === null || row === undefined) {
+				return null;
+			}
+
+			// Delete the entry
+			deleteByIdStmt.run({ $id: row.id });
+
+			return rowToEntry(row);
+		},
+
+		peek(): MergeEntry | null {
+			const row = getFirstPendingStmt.get({});
+
+			if (row === null || row === undefined) {
+				return null;
+			}
+
+			return rowToEntry(row);
+		},
+
+		list(status?): MergeEntry[] {
+			let rows: MergeQueueRow[];
+
+			if (status === undefined) {
+				rows = listAllStmt.all({});
+			} else {
+				rows = listByStatusStmt.all({ $status: status });
+			}
+
+			return rows.map(rowToEntry);
+		},
+
+		updateStatus(branchName, status, tier?): void {
+			// Check if entry exists
+			const existing = getByBranchStmt.get({ $branch_name: branchName });
+
+			if (existing === null || existing === undefined) {
+				throw new MergeError(`No queue entry found for branch: ${branchName}`, {
+					branchName,
+				});
+			}
+
+			// Update the entry
+			updateStatusStmt.run({
+				$branch_name: branchName,
+				$status: status,
+				$resolved_tier: tier ?? null,
+			});
+		},
+
+		close(): void {
+			db.exec("PRAGMA wal_checkpoint(PASSIVE)");
+			db.close();
+		},
+	};
+}