opencode-swarm-plugin 0.18.0 → 0.20.0

package/src/streams/migrations.ts

@@ -1,9 +1,44 @@
 /**
- * Schema Migration System for PGLite Event Store
+ * Schema Migration System
  *
- * Version-based migrations with up/down support.
- * Tracks applied migrations in schema_version table.
- * Idempotent - safe to run multiple times.
+ * Handles database schema evolution for the PGLite event store.
+ *
+ * ## How It Works
+ *
+ * 1. Each migration has a unique version number (incrementing integer)
+ * 2. On startup, `runMigrations()` checks current schema version
+ * 3. Migrations are applied in order until schema is current
+ * 4. Version is stored in `schema_version` table
+ *
+ * ## Adding a New Migration
+ *
+ * ```typescript
+ * // In migrations.ts
+ * export const migrations: Migration[] = [
+ *   // ... existing migrations
+ *   {
+ *     version: 3,
+ *     description: "add_new_column",
+ *     up: `ALTER TABLE events ADD COLUMN new_col TEXT`,
+ *     down: `ALTER TABLE events DROP COLUMN new_col`,
+ *   },
+ * ];
+ * ```
+ *
+ * ## Rollback
+ *
+ * Rollback is supported via `rollbackTo(db, targetVersion)`.
+ * Note: Some migrations may not be fully reversible (data loss).
+ *
+ * ## Best Practices
+ *
+ * - Always test migrations on a copy of production data
+ * - Keep migrations small and focused
+ * - Include both `up` and `down` SQL
+ * - Use transactions for multi-statement migrations
+ * - Document any data transformations
+ *
+ * @module migrations
  */
 import type { PGlite } from "@electric-sql/pglite";
 
@@ -11,10 +46,17 @@ import type { PGlite } from "@electric-sql/pglite";
 // Types
 // ============================================================================
 
+/**
+ * A database migration definition.
+ */
 export interface Migration {
+  /** Unique version number (must be sequential) */
   version: number;
+  /** Human-readable migration description */
   description: string;
+  /** SQL to apply the migration */
   up: string;
+  /** SQL to rollback the migration (best effort) */
   down: string;
 }
 

package/src/streams/store.integration.test.ts

@@ -17,6 +17,7 @@ import {
   readEvents,
   getLatestSequence,
   replayEvents,
+  replayEventsBatched,
   registerAgent,
   sendMessage,
   reserveFiles,
@@ -343,6 +344,115 @@ describe("Event Store", () => {
     });
   });
 
+  describe("replayEventsBatched", () => {
+    it("should replay events in batches with progress tracking", async () => {
+      // Create 50 events
+      for (let i = 0; i < 50; i++) {
+        await registerAgent(
+          "test-project",
+          `Agent${i}`,
+          { taskDescription: `Agent ${i}` },
+          TEST_PROJECT_PATH,
+        );
+      }
+
+      // Manually corrupt the views
+      const db = await getDatabase(TEST_PROJECT_PATH);
+      await db.query("DELETE FROM agents WHERE project_key = 'test-project'");
+
+      // Verify views are empty
+      const empty = await db.query<{ count: string }>(
+        "SELECT COUNT(*) as count FROM agents WHERE project_key = 'test-project'",
+      );
+      expect(parseInt(empty.rows[0]?.count ?? "0")).toBe(0);
+
+      // Track progress
+      const progressUpdates: Array<{
+        processed: number;
+        total: number;
+        percent: number;
+      }> = [];
+
+      // Replay in batches of 10
+      const result = await replayEventsBatched(
+        "test-project",
+        async (_events, progress) => {
+          progressUpdates.push(progress);
+        },
+        { batchSize: 10, clearViews: false },
+        TEST_PROJECT_PATH,
+      );
+
+      // Verify all events replayed
+      expect(result.eventsReplayed).toBe(50);
+
+      // Verify progress updates
+      expect(progressUpdates.length).toBe(5); // 50 events / 10 per batch = 5 batches
+      expect(progressUpdates[0]).toMatchObject({
+        processed: 10,
+        total: 50,
+        percent: 20,
+      });
+      expect(progressUpdates[4]).toMatchObject({
+        processed: 50,
+        total: 50,
+        percent: 100,
+      });
+
+      // Verify views are restored
+      const restored = await db.query<{ count: string }>(
+        "SELECT COUNT(*) as count FROM agents WHERE project_key = 'test-project'",
+      );
+      expect(parseInt(restored.rows[0]?.count ?? "0")).toBe(50);
+    });
+
+    it("should handle zero events gracefully", async () => {
+      const progressUpdates: Array<{
+        processed: number;
+        total: number;
+        percent: number;
+      }> = [];
+
+      const result = await replayEventsBatched(
+        "test-project",
+        async (_events, progress) => {
+          progressUpdates.push(progress);
+        },
+        { batchSize: 10 },
+        TEST_PROJECT_PATH,
+      );
+
+      expect(result.eventsReplayed).toBe(0);
+      expect(progressUpdates.length).toBe(0);
+    });
+
+    it("should use custom batch size", async () => {
+      // Create 25 events
+      for (let i = 0; i < 25; i++) {
+        await registerAgent("test-project", `Agent${i}`, {}, TEST_PROJECT_PATH);
+      }
+
+      const progressUpdates: Array<{
+        processed: number;
+        total: number;
+        percent: number;
+      }> = [];
+
+      // Replay with batch size of 5
+      await replayEventsBatched(
+        "test-project",
+        async (_events, progress) => {
+          progressUpdates.push(progress);
+        },
+        { batchSize: 5, clearViews: false },
+        TEST_PROJECT_PATH,
+      );
+
+      // Should have 5 batches (25 events / 5 per batch)
+      expect(progressUpdates.length).toBe(5);
+    });
+  });
+
   describe("getDatabaseStats", () => {
     it("should return correct counts", async () => {
       await registerAgent("test-project", "Agent1", {}, TEST_PROJECT_PATH);