opencode-swarm-plugin 0.1.0

package/src/beads.integration.test.ts

@@ -0,0 +1,688 @@
+/**
+ * Beads Integration Tests
+ *
+ * These tests exercise the real `bd` CLI in a Docker environment.
+ * They validate the tool wrappers work correctly with actual beads operations.
+ *
+ * Run with: bun run docker:test
+ */
+import { describe, it, expect, beforeAll, beforeEach, afterAll } from "vitest";
+import {
+  beads_create,
+  beads_create_epic,
+  beads_query,
+  beads_update,
+  beads_close,
+  beads_start,
+  beads_ready,
+  beads_link_thread,
+  BeadError,
+} from "./beads";
+import type { Bead, EpicCreateResult } from "./schemas";
+
+/**
+ * Mock tool context for execute functions
+ * The real context is provided by OpenCode runtime
+ */
+const mockContext = {
+  sessionID: "test-session-" + Date.now(),
+  messageID: "test-message-" + Date.now(),
+  agent: "test-agent",
+  abort: new AbortController().signal,
+};
+
+/**
+ * Helper to parse JSON response from tool execute
+ */
+function parseResponse<T>(response: string): T {
+  return JSON.parse(response) as T;
+}
+
+/**
+ * Track created beads for cleanup
+ */
+const createdBeadIds: string[] = [];
+
+/**
+ * Cleanup helper - close all created beads after tests
+ */
+async function cleanupBeads() {
+  for (const id of createdBeadIds) {
+    try {
+      await beads_close.execute({ id, reason: "Test cleanup" }, mockContext);
+    } catch {
+      // Ignore cleanup errors - bead may already be closed
+    }
+  }
+  createdBeadIds.length = 0;
+}
+
+describe("beads integration", () => {
+  // Verify bd CLI is available before running tests
+  beforeAll(async () => {
+    const result = await Bun.$`bd --version`.quiet().nothrow();
+    if (result.exitCode !== 0) {
+      throw new Error(
+        "bd CLI not found. Run tests in Docker with: bun run docker:test",
+      );
+    }
+  });
+
+  afterAll(async () => {
+    await cleanupBeads();
+  });
+
+  describe("beads_create", () => {
+    it("creates a bead with minimal args (title only)", async () => {
+      const result = await beads_create.execute(
+        { title: "Test bead minimal" },
+        mockContext,
+      );
+
+      const bead = parseResponse<Bead>(result);
+      createdBeadIds.push(bead.id);
+
+      expect(bead.title).toBe("Test bead minimal");
+      expect(bead.status).toBe("open");
+      expect(bead.issue_type).toBe("task"); // default
+      expect(bead.priority).toBe(2); // default
+      expect(bead.id).toMatch(/^[a-z0-9-]+-[a-z0-9]+$/);
+    });
+
+    it("creates a bead with all options", async () => {
+      const result = await beads_create.execute(
+        {
+          title: "Test bug with priority",
+          type: "bug",
+          priority: 0, // P0 critical
+          description: "This is a critical bug",
+        },
+        mockContext,
+      );
+
+      const bead = parseResponse<Bead>(result);
+      createdBeadIds.push(bead.id);
+
+      expect(bead.title).toBe("Test bug with priority");
+      expect(bead.issue_type).toBe("bug");
+      expect(bead.priority).toBe(0);
+      expect(bead.description).toContain("critical bug");
+    });
+
+    it("creates a feature type bead", async () => {
+      const result = await beads_create.execute(
+        { title: "New feature request", type: "feature", priority: 1 },
+        mockContext,
+      );
+
+      const bead = parseResponse<Bead>(result);
+      createdBeadIds.push(bead.id);
+
+      expect(bead.issue_type).toBe("feature");
+      expect(bead.priority).toBe(1);
+    });
+
+    it("creates a chore type bead", async () => {
+      const result = await beads_create.execute(
+        { title: "Cleanup task", type: "chore", priority: 3 },
+        mockContext,
+      );
+
+      const bead = parseResponse<Bead>(result);
+      createdBeadIds.push(bead.id);
+
+      expect(bead.issue_type).toBe("chore");
+      expect(bead.priority).toBe(3);
+    });
+  });
+
+  describe("beads_query", () => {
+    let testBeadId: string;
+
+    beforeEach(async () => {
+      // Create a test bead for query tests
+      const result = await beads_create.execute(
+        { title: "Query test bead", type: "task" },
+        mockContext,
+      );
+      const bead = parseResponse<Bead>(result);
+      testBeadId = bead.id;
+      createdBeadIds.push(testBeadId);
+    });
+
+    it("queries all open beads", async () => {
+      const result = await beads_query.execute({ status: "open" }, mockContext);
+
+      const beads = parseResponse<Bead[]>(result);
+
+      expect(Array.isArray(beads)).toBe(true);
+      expect(beads.length).toBeGreaterThan(0);
+      expect(beads.every((b) => b.status === "open")).toBe(true);
+    });
+
+    it("queries beads by type", async () => {
+      const result = await beads_query.execute({ type: "task" }, mockContext);
+
+      const beads = parseResponse<Bead[]>(result);
+
+      expect(Array.isArray(beads)).toBe(true);
+      expect(beads.every((b) => b.issue_type === "task")).toBe(true);
+    });
+
+    it("queries ready beads (unblocked)", async () => {
+      const result = await beads_query.execute({ ready: true }, mockContext);
+
+      const beads = parseResponse<Bead[]>(result);
+
+      expect(Array.isArray(beads)).toBe(true);
+      // Ready beads should be open (not closed, not blocked)
+      for (const bead of beads) {
+        expect(["open", "in_progress"]).toContain(bead.status);
+      }
+    });
+
+    it("limits results", async () => {
+      // Create multiple beads first
+      for (let i = 0; i < 5; i++) {
+        const result = await beads_create.execute(
+          { title: `Limit test bead ${i}` },
+          mockContext,
+        );
+        const bead = parseResponse<Bead>(result);
+        createdBeadIds.push(bead.id);
+      }
+
+      const result = await beads_query.execute({ limit: 3 }, mockContext);
+
+      const beads = parseResponse<Bead[]>(result);
+      expect(beads.length).toBeLessThanOrEqual(3);
+    });
+
+    it("combines filters", async () => {
+      const result = await beads_query.execute(
+        { status: "open", type: "task", limit: 5 },
+        mockContext,
+      );
+
+      const beads = parseResponse<Bead[]>(result);
+
+      expect(Array.isArray(beads)).toBe(true);
+      expect(beads.length).toBeLessThanOrEqual(5);
+      for (const bead of beads) {
+        expect(bead.status).toBe("open");
+        expect(bead.issue_type).toBe("task");
+      }
+    });
+  });
+
+  describe("beads_update", () => {
+    let testBeadId: string;
+
+    beforeEach(async () => {
+      const result = await beads_create.execute(
+        { title: "Update test bead", description: "Original description" },
+        mockContext,
+      );
+      const bead = parseResponse<Bead>(result);
+      testBeadId = bead.id;
+      createdBeadIds.push(testBeadId);
+    });
+
+    it("updates bead status", async () => {
+      const result = await beads_update.execute(
+        { id: testBeadId, status: "in_progress" },
+        mockContext,
+      );
+
+      const bead = parseResponse<Bead>(result);
+      expect(bead.status).toBe("in_progress");
+    });
+
+    it("updates bead description", async () => {
+      const result = await beads_update.execute(
+        { id: testBeadId, description: "Updated description" },
+        mockContext,
+      );
+
+      const bead = parseResponse<Bead>(result);
+      expect(bead.description).toContain("Updated description");
+    });
+
+    it("updates bead priority", async () => {
+      const result = await beads_update.execute(
+        { id: testBeadId, priority: 0 },
+        mockContext,
+      );
+
+      const bead = parseResponse<Bead>(result);
+      expect(bead.priority).toBe(0);
+    });
+
+    it("updates multiple fields at once", async () => {
+      const result = await beads_update.execute(
+        {
+          id: testBeadId,
+          status: "blocked",
+          description: "Blocked on dependency",
+          priority: 1,
+        },
+        mockContext,
+      );
+
+      const bead = parseResponse<Bead>(result);
+      expect(bead.status).toBe("blocked");
+      expect(bead.description).toContain("Blocked on dependency");
+      expect(bead.priority).toBe(1);
+    });
+
+    it("throws BeadError for invalid bead ID", async () => {
+      await expect(
+        beads_update.execute(
+          { id: "nonexistent-bead-xyz", status: "closed" },
+          mockContext,
+        ),
+      ).rejects.toThrow(BeadError);
+    });
+  });
+
+  describe("beads_close", () => {
+    it("closes a bead with reason", async () => {
+      // Create a fresh bead to close
+      const createResult = await beads_create.execute(
+        { title: "Bead to close" },
+        mockContext,
+      );
+      const created = parseResponse<Bead>(createResult);
+      // Don't add to cleanup since we're closing it
+
+      const result = await beads_close.execute(
+        { id: created.id, reason: "Task completed successfully" },
+        mockContext,
+      );
+
+      expect(result).toContain("Closed");
+      expect(result).toContain(created.id);
+
+      // Verify it's actually closed using bd show (query has limit issues with many closed beads)
+      const showResult = await Bun.$`bd show ${created.id} --json`.quiet();
+      const showData = JSON.parse(showResult.stdout.toString());
+      const closedBead = Array.isArray(showData) ? showData[0] : showData;
+      expect(closedBead.status).toBe("closed");
+    });
+
+    it("throws BeadError for invalid bead ID", async () => {
+      await expect(
+        beads_close.execute(
+          { id: "nonexistent-bead-xyz", reason: "Test" },
+          mockContext,
+        ),
+      ).rejects.toThrow(BeadError);
+    });
+  });
+
+  describe("beads_start", () => {
+    it("marks a bead as in_progress", async () => {
+      // Create a fresh bead
+      const createResult = await beads_create.execute(
+        { title: "Bead to start" },
+        mockContext,
+      );
+      const created = parseResponse<Bead>(createResult);
+      createdBeadIds.push(created.id);
+
+      expect(created.status).toBe("open");
+
+      const result = await beads_start.execute({ id: created.id }, mockContext);
+
+      expect(result).toContain("Started");
+      expect(result).toContain(created.id);
+
+      // Verify status changed
+      const queryResult = await beads_query.execute(
+        { status: "in_progress" },
+        mockContext,
+      );
+      const inProgressBeads = parseResponse<Bead[]>(queryResult);
+      const startedBead = inProgressBeads.find((b) => b.id === created.id);
+      expect(startedBead).toBeDefined();
+      expect(startedBead?.status).toBe("in_progress");
+    });
+
+    it("throws BeadError for invalid bead ID", async () => {
+      await expect(
+        beads_start.execute({ id: "nonexistent-bead-xyz" }, mockContext),
+      ).rejects.toThrow(BeadError);
+    });
+  });
+
+  describe("beads_ready", () => {
+    it("returns the highest priority unblocked bead", async () => {
+      // Create a high priority bead
+      const createResult = await beads_create.execute(
+        { title: "High priority ready bead", priority: 0 },
+        mockContext,
+      );
+      const created = parseResponse<Bead>(createResult);
+      createdBeadIds.push(created.id);
+
+      const result = await beads_ready.execute({}, mockContext);
+
+      // Should return a bead (or "No ready beads" message)
+      if (result !== "No ready beads") {
+        const bead = parseResponse<Bead>(result);
+        expect(bead.id).toBeDefined();
+        expect(bead.status).not.toBe("closed");
+        expect(bead.status).not.toBe("blocked");
+      }
+    });
+
+    it("returns no ready beads message when all are closed", async () => {
+      // This test depends on the state of the beads database
+      // It may return a bead if there are open ones
+      const result = await beads_ready.execute({}, mockContext);
+
+      expect(typeof result).toBe("string");
+      // Either a JSON bead or "No ready beads"
+      if (result === "No ready beads") {
+        expect(result).toBe("No ready beads");
+      } else {
+        const bead = parseResponse<Bead>(result);
+        expect(bead.id).toBeDefined();
+      }
+    });
+  });
+
+  describe("beads_create_epic", () => {
+    it("creates an epic with subtasks", async () => {
+      const result = await beads_create_epic.execute(
+        {
+          epic_title: "Integration test epic",
+          epic_description: "Testing epic creation",
+          subtasks: [
+            { title: "Subtask 1", priority: 2 },
+            { title: "Subtask 2", priority: 3 },
+            { title: "Subtask 3", priority: 1 },
+          ],
+        },
+        mockContext,
+      );
+
+      const epicResult = parseResponse<EpicCreateResult>(result);
+      createdBeadIds.push(epicResult.epic.id);
+      for (const subtask of epicResult.subtasks) {
+        createdBeadIds.push(subtask.id);
+      }
+
+      expect(epicResult.success).toBe(true);
+      expect(epicResult.epic.title).toBe("Integration test epic");
+      expect(epicResult.epic.issue_type).toBe("epic");
+      expect(epicResult.subtasks).toHaveLength(3);
+
+      // Subtasks should have IDs that indicate parent relationship
+      // Format: {epic_id}.{index} e.g., "opencode-swarm-plugin-abc.1"
+      for (const subtask of epicResult.subtasks) {
+        expect(subtask.id).toContain(epicResult.epic.id);
+        expect(subtask.id).toMatch(/\.\d+$/); // ends with .N
+      }
+    });
+
+    it("creates an epic with files metadata in subtasks", async () => {
+      const result = await beads_create_epic.execute(
+        {
+          epic_title: "Epic with file references",
+          subtasks: [
+            { title: "Edit src/a.ts", priority: 2, files: ["src/a.ts"] },
+            {
+              title: "Edit src/b.ts",
+              priority: 2,
+              files: ["src/b.ts", "src/c.ts"],
+            },
+          ],
+        },
+        mockContext,
+      );
+
+      const epicResult = parseResponse<EpicCreateResult>(result);
+      createdBeadIds.push(epicResult.epic.id);
+      for (const subtask of epicResult.subtasks) {
+        createdBeadIds.push(subtask.id);
+      }
+
+      expect(epicResult.success).toBe(true);
+      expect(epicResult.subtasks).toHaveLength(2);
+    });
+
+    it("creates epic with single subtask", async () => {
+      const result = await beads_create_epic.execute(
+        {
+          epic_title: "Single subtask epic",
+          subtasks: [{ title: "Only task", priority: 1 }],
+        },
+        mockContext,
+      );
+
+      const epicResult = parseResponse<EpicCreateResult>(result);
+      createdBeadIds.push(epicResult.epic.id);
+      createdBeadIds.push(epicResult.subtasks[0].id);
+
+      expect(epicResult.success).toBe(true);
+      expect(epicResult.subtasks).toHaveLength(1);
+    });
+
+    it("preserves subtask order", async () => {
+      const titles = ["First", "Second", "Third", "Fourth"];
+      const result = await beads_create_epic.execute(
+        {
+          epic_title: "Ordered subtasks epic",
+          subtasks: titles.map((title, i) => ({ title, priority: 2 })),
+        },
+        mockContext,
+      );
+
+      const epicResult = parseResponse<EpicCreateResult>(result);
+      createdBeadIds.push(epicResult.epic.id);
+      for (const subtask of epicResult.subtasks) {
+        createdBeadIds.push(subtask.id);
+      }
+
+      expect(epicResult.success).toBe(true);
+      // Subtasks should be in creation order
+      for (let i = 0; i < titles.length; i++) {
+        expect(epicResult.subtasks[i].title).toBe(titles[i]);
+      }
+    });
+  });
+
+  describe("beads_link_thread", () => {
+    let testBeadId: string;
+
+    beforeEach(async () => {
+      const result = await beads_create.execute(
+        { title: "Thread link test bead" },
+        mockContext,
+      );
+      const bead = parseResponse<Bead>(result);
+      testBeadId = bead.id;
+      createdBeadIds.push(testBeadId);
+    });
+
+    it("links a bead to an Agent Mail thread", async () => {
+      const threadId = "test-thread-123";
+      const result = await beads_link_thread.execute(
+        { bead_id: testBeadId, thread_id: threadId },
+        mockContext,
+      );
+
+      expect(result).toContain("Linked");
+      expect(result).toContain(testBeadId);
+      expect(result).toContain(threadId);
+
+      // Verify the thread marker is in the description using bd show
+      const showResult = await Bun.$`bd show ${testBeadId} --json`.quiet();
+      const showData = JSON.parse(showResult.stdout.toString());
+      const linkedBead = Array.isArray(showData) ? showData[0] : showData;
+      expect(linkedBead.description).toContain(`[thread:${threadId}]`);
+    });
+
+    it("returns message if thread already linked", async () => {
+      const threadId = "test-thread-456";
+
+      // Link once
+      await beads_link_thread.execute(
+        { bead_id: testBeadId, thread_id: threadId },
+        mockContext,
+      );
+
+      // Try to link again
+      const result = await beads_link_thread.execute(
+        { bead_id: testBeadId, thread_id: threadId },
+        mockContext,
+      );
+
+      expect(result).toContain("already linked");
+    });
+
+    it("preserves existing description when linking", async () => {
+      // Update bead with a description first
+      await beads_update.execute(
+        { id: testBeadId, description: "Important context here" },
+        mockContext,
+      );
+
+      const threadId = "test-thread-789";
+      await beads_link_thread.execute(
+        { bead_id: testBeadId, thread_id: threadId },
+        mockContext,
+      );
+
+      // Verify both original description and thread marker exist using bd show
+      const showResult = await Bun.$`bd show ${testBeadId} --json`.quiet();
+      const showData = JSON.parse(showResult.stdout.toString());
+      const linkedBead = Array.isArray(showData) ? showData[0] : showData;
+
+      expect(linkedBead.description).toContain("Important context here");
+      expect(linkedBead.description).toContain(`[thread:${threadId}]`);
+    });
+
+    it("throws BeadError for invalid bead ID", async () => {
+      await expect(
+        beads_link_thread.execute(
+          { bead_id: "nonexistent-bead-xyz", thread_id: "thread-123" },
+          mockContext,
+        ),
+      ).rejects.toThrow(BeadError);
+    });
+  });
+
+  describe("error handling", () => {
+    it("throws BeadError with command info on CLI failure", async () => {
+      try {
+        await beads_update.execute(
+          { id: "definitely-not-a-real-bead-id", status: "closed" },
+          mockContext,
+        );
+        expect.fail("Should have thrown");
+      } catch (error) {
+        expect(error).toBeInstanceOf(BeadError);
+        const beadError = error as BeadError;
+        expect(beadError.command).toContain("bd");
+        expect(beadError.exitCode).toBeDefined();
+      }
+    });
+  });
+
+  describe("workflow integration", () => {
+    it("complete bead lifecycle: create -> start -> update -> close", async () => {
+      // 1. Create
+      const createResult = await beads_create.execute(
+        { title: "Lifecycle test bead", type: "task", priority: 2 },
+        mockContext,
+      );
+      const bead = parseResponse<Bead>(createResult);
+      expect(bead.status).toBe("open");
+
+      // 2. Start (in_progress)
+      const startResult = await beads_start.execute(
+        { id: bead.id },
+        mockContext,
+      );
+      expect(startResult).toContain("Started");
+
+      // 3. Update (add progress note)
+      const updateResult = await beads_update.execute(
+        { id: bead.id, description: "50% complete" },
+        mockContext,
+      );
+      const updated = parseResponse<Bead>(updateResult);
+      expect(updated.description).toContain("50%");
+
+      // 4. Close
+      const closeResult = await beads_close.execute(
+        { id: bead.id, reason: "Completed successfully" },
+        mockContext,
+      );
+      expect(closeResult).toContain("Closed");
+
+      // Verify final state using bd show
+      const showResult = await Bun.$`bd show ${bead.id} --json`.quiet();
+      const showData = JSON.parse(showResult.stdout.toString());
+      const finalBead = Array.isArray(showData) ? showData[0] : showData;
+      expect(finalBead.status).toBe("closed");
+    });
+
+    it("epic workflow: create epic -> start subtasks -> close subtasks -> close epic", async () => {
+      // 1. Create epic with subtasks
+      const epicResult = await beads_create_epic.execute(
+        {
+          epic_title: "Workflow test epic",
+          subtasks: [
+            { title: "Step 1", priority: 2 },
+            { title: "Step 2", priority: 2 },
+          ],
+        },
+        mockContext,
+      );
+      const epic = parseResponse<EpicCreateResult>(epicResult);
+      expect(epic.success).toBe(true);
+
+      // 2. Start and complete first subtask
+      await beads_start.execute({ id: epic.subtasks[0].id }, mockContext);
+      await beads_close.execute(
+        { id: epic.subtasks[0].id, reason: "Step 1 done" },
+        mockContext,
+      );
+
+      // 3. Start and complete second subtask
+      await beads_start.execute({ id: epic.subtasks[1].id }, mockContext);
+      await beads_close.execute(
+        { id: epic.subtasks[1].id, reason: "Step 2 done" },
+        mockContext,
+      );
+
+      // 4. Close the epic
+      await beads_close.execute(
+        { id: epic.epic.id, reason: "All subtasks completed" },
+        mockContext,
+      );
+
+      // Verify all are closed using bd show
+      const epicShowResult =
+        await Bun.$`bd show ${epic.epic.id} --json`.quiet();
+      const epicShowData = JSON.parse(epicShowResult.stdout.toString());
+      const epicClosed = Array.isArray(epicShowData)
+        ? epicShowData[0]
+        : epicShowData;
+      expect(epicClosed.status).toBe("closed");
+
+      for (const subtask of epic.subtasks) {
+        const subtaskShowResult =
+          await Bun.$`bd show ${subtask.id} --json`.quiet();
+        const subtaskShowData = JSON.parse(subtaskShowResult.stdout.toString());
+        const subtaskClosed = Array.isArray(subtaskShowData)
+          ? subtaskShowData[0]
+          : subtaskShowData;
+        expect(subtaskClosed.status).toBe("closed");
+      }
+    });
+  });
+});