@wopr-network/platform-core 1.71.0 → 1.72.0

package/dist/server/boot-config.d.ts

@@ -20,8 +20,18 @@ export interface RoutePlugin {
 export interface BootConfig {
     /** Short product identifier (e.g. "paperclip", "wopr", "holyship"). */
     slug: string;
-    /** PostgreSQL connection string. */
+    /** PostgreSQL connection string. Required unless `pool` is provided. */
     databaseUrl: string;
+    /**
+     * Pre-created PostgreSQL connection pool. When provided, buildContainer
+     * reuses this pool and skips pool creation + Drizzle migrations. The
+     * caller is responsible for running their own migrations before calling
+     * buildContainer.
+     *
+     * Use this when the product has its own migration set (e.g. wopr-platform
+     * generates migrations locally from the shared schema).
+     */
+    pool?: import("pg").Pool;
     /** Bind host (default "0.0.0.0"). */
     host?: string;
     /** Bind port (default 3001). */

package/dist/server/container.js

@@ -20,20 +20,29 @@
  * `bootConfig.features`. Disabled features yield `null`.
  */
 export async function buildContainer(bootConfig) {
-    if (!bootConfig.databaseUrl) {
-        throw new Error("buildContainer: databaseUrl is required");
+    // 1. Database pool — reuse existing or create new
+    let pool;
+    if (bootConfig.pool) {
+        pool = bootConfig.pool;
+    }
+    else {
+        if (!bootConfig.databaseUrl) {
+            throw new Error("buildContainer: databaseUrl is required when pool is not provided");
+        }
+        const { Pool: PgPool } = await import("pg");
+        pool = new PgPool({ connectionString: bootConfig.databaseUrl });
     }
-    // 1. Database pool
-    const { Pool: PgPool } = await import("pg");
-    const pool = new PgPool({ connectionString: bootConfig.databaseUrl });
     // 2. Drizzle ORM instance
     const { createDb } = await import("../db/index.js");
     const db = createDb(pool);
-    // 3. Run Drizzle migrations
-    const { migrate } = await import("drizzle-orm/node-postgres/migrator");
-    const path = await import("node:path");
-    const migrationsFolder = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../drizzle");
-    await migrate(db, { migrationsFolder });
+    // 3. Run Drizzle migrations (skip when caller provided their own pool —
+    //    they are responsible for running product-specific migrations first)
+    if (!bootConfig.pool) {
+        const { migrate } = await import("drizzle-orm/node-postgres/migrator");
+        const path = await import("node:path");
+        const migrationsFolder = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../drizzle");
+        await migrate(db, { migrationsFolder });
+    }
     // 4. Bootstrap product config from DB (auto-seeds from presets if needed)
     const { platformBoot } = await import("../product-config/boot.js");
     const { config: productConfig, service: productConfigService } = await platformBoot({ slug: bootConfig.slug, db });

package/dist/server/services/__tests__/hot-pool.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tests for hot pool service functions (getPoolSize, setPoolSize).
+ *
+ * Uses InMemoryPoolRepository to test service logic without Docker or DB.
+ */
+export {};

package/dist/server/services/__tests__/hot-pool.test.js

@@ -0,0 +1,26 @@
+/**
+ * Tests for hot pool service functions (getPoolSize, setPoolSize).
+ *
+ * Uses InMemoryPoolRepository to test service logic without Docker or DB.
+ */
+import { describe, expect, it } from "vitest";
+import { getPoolSize, setPoolSize } from "../hot-pool.js";
+import { InMemoryPoolRepository } from "./in-memory-pool-repository.js";
+describe("hot pool service", () => {
+    describe("getPoolSize / setPoolSize", () => {
+        it("returns default pool size", async () => {
+            const repo = new InMemoryPoolRepository();
+            expect(await getPoolSize(repo)).toBe(2);
+        });
+        it("sets and reads pool size", async () => {
+            const repo = new InMemoryPoolRepository();
+            await setPoolSize(repo, 10);
+            expect(await getPoolSize(repo)).toBe(10);
+        });
+        it("pool size of 0 is valid", async () => {
+            const repo = new InMemoryPoolRepository();
+            await setPoolSize(repo, 0);
+            expect(await getPoolSize(repo)).toBe(0);
+        });
+    });
+});

package/dist/server/services/__tests__/in-memory-pool-repository.d.ts

@@ -0,0 +1,21 @@
+/**
+ * In-memory IPoolRepository for testing.
+ * FIFO claiming, dead instance handling — no DB required.
+ */
+import type { IPoolRepository, PoolInstance } from "../pool-repository.js";
+export declare class InMemoryPoolRepository implements IPoolRepository {
+    private poolSize;
+    private instances;
+    getPoolSize(): Promise<number>;
+    setPoolSize(size: number): Promise<void>;
+    warmCount(): Promise<number>;
+    insertWarm(id: string, containerId: string): Promise<void>;
+    listWarm(): Promise<PoolInstance[]>;
+    markDead(id: string): Promise<void>;
+    deleteDead(): Promise<void>;
+    claimWarm(tenantId: string, name: string): Promise<{
+        id: string;
+        containerId: string;
+    } | null>;
+    updateInstanceStatus(id: string, status: string): Promise<void>;
+}

package/dist/server/services/__tests__/in-memory-pool-repository.js

@@ -0,0 +1,57 @@
+/**
+ * In-memory IPoolRepository for testing.
+ * FIFO claiming, dead instance handling — no DB required.
+ */
+export class InMemoryPoolRepository {
+    poolSize = 2;
+    instances = [];
+    async getPoolSize() {
+        return this.poolSize;
+    }
+    async setPoolSize(size) {
+        this.poolSize = size;
+    }
+    async warmCount() {
+        return this.instances.filter((i) => i.status === "warm").length;
+    }
+    async insertWarm(id, containerId) {
+        this.instances.push({
+            id,
+            containerId,
+            status: "warm",
+            tenantId: null,
+            name: null,
+            createdAt: new Date(),
+            claimedAt: null,
+        });
+    }
+    async listWarm() {
+        return this.instances.filter((i) => i.status === "warm").map(({ createdAt, claimedAt, ...rest }) => rest);
+    }
+    async markDead(id) {
+        const inst = this.instances.find((i) => i.id === id);
+        if (inst)
+            inst.status = "dead";
+    }
+    async deleteDead() {
+        this.instances = this.instances.filter((i) => i.status !== "dead");
+    }
+    async claimWarm(tenantId, name) {
+        const warm = this.instances
+            .filter((i) => i.status === "warm")
+            .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+        if (warm.length === 0)
+            return null;
+        const target = warm[0];
+        target.status = "claimed";
+        target.tenantId = tenantId;
+        target.name = name;
+        target.claimedAt = new Date();
+        return { id: target.id, containerId: target.containerId };
+    }
+    async updateInstanceStatus(id, status) {
+        const inst = this.instances.find((i) => i.id === id);
+        if (inst)
+            inst.status = status;
+    }
+}

package/dist/server/services/__tests__/pool-repository.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tests for IPoolRepository interface contract.
+ *
+ * Uses an in-memory implementation to verify the interface
+ * behavior without requiring a real database.
+ */
+export {};

package/dist/server/services/__tests__/pool-repository.test.js

@@ -0,0 +1,108 @@
+/**
+ * Tests for IPoolRepository interface contract.
+ *
+ * Uses an in-memory implementation to verify the interface
+ * behavior without requiring a real database.
+ */
+import { describe, expect, it } from "vitest";
+import { InMemoryPoolRepository } from "./in-memory-pool-repository.js";
+describe("IPoolRepository (InMemory)", () => {
+    it("returns default pool size of 2", async () => {
+        const repo = new InMemoryPoolRepository();
+        expect(await repo.getPoolSize()).toBe(2);
+    });
+    it("sets and gets pool size", async () => {
+        const repo = new InMemoryPoolRepository();
+        await repo.setPoolSize(5);
+        expect(await repo.getPoolSize()).toBe(5);
+    });
+    it("inserts and counts warm instances", async () => {
+        const repo = new InMemoryPoolRepository();
+        expect(await repo.warmCount()).toBe(0);
+        await repo.insertWarm("a", "container-a");
+        await repo.insertWarm("b", "container-b");
+        expect(await repo.warmCount()).toBe(2);
+    });
+    it("lists warm instances", async () => {
+        const repo = new InMemoryPoolRepository();
+        await repo.insertWarm("a", "container-a");
+        await repo.insertWarm("b", "container-b");
+        const warm = await repo.listWarm();
+        expect(warm).toHaveLength(2);
+        expect(warm[0].id).toBe("a");
+        expect(warm[0].containerId).toBe("container-a");
+        expect(warm[0].status).toBe("warm");
+    });
+    it("claims warm instance FIFO", async () => {
+        const repo = new InMemoryPoolRepository();
+        await repo.insertWarm("first", "c-first");
+        await repo.insertWarm("second", "c-second");
+        const claimed = await repo.claimWarm("tenant-1", "my-bot");
+        expect(claimed).not.toBeNull();
+        expect(claimed?.id).toBe("first");
+        expect(claimed?.containerId).toBe("c-first");
+        // Warm count drops by 1
+        expect(await repo.warmCount()).toBe(1);
+    });
+    it("returns null when claiming from empty pool", async () => {
+        const repo = new InMemoryPoolRepository();
+        const result = await repo.claimWarm("tenant-1", "bot");
+        expect(result).toBeNull();
+    });
+    it("does not re-claim already claimed instances", async () => {
+        const repo = new InMemoryPoolRepository();
+        await repo.insertWarm("only", "c-only");
+        const first = await repo.claimWarm("t1", "bot1");
+        expect(first).not.toBeNull();
+        const second = await repo.claimWarm("t2", "bot2");
+        expect(second).toBeNull();
+    });
+    it("marks instances dead", async () => {
+        const repo = new InMemoryPoolRepository();
+        await repo.insertWarm("a", "c-a");
+        await repo.markDead("a");
+        expect(await repo.warmCount()).toBe(0);
+        const warm = await repo.listWarm();
+        expect(warm).toHaveLength(0);
+    });
+    it("deletes dead instances", async () => {
+        const repo = new InMemoryPoolRepository();
+        await repo.insertWarm("a", "c-a");
+        await repo.insertWarm("b", "c-b");
+        await repo.markDead("a");
+        await repo.deleteDead();
+        // Only 'b' remains (warm)
+        expect(await repo.warmCount()).toBe(1);
+        const warm = await repo.listWarm();
+        expect(warm[0].id).toBe("b");
+    });
+    it("updates instance status", async () => {
+        const repo = new InMemoryPoolRepository();
+        await repo.insertWarm("a", "c-a");
+        await repo.updateInstanceStatus("a", "provisioning");
+        // No longer warm
+        expect(await repo.warmCount()).toBe(0);
+    });
+    it("handles multiple claims in order", async () => {
+        const repo = new InMemoryPoolRepository();
+        await repo.insertWarm("1", "c-1");
+        await repo.insertWarm("2", "c-2");
+        await repo.insertWarm("3", "c-3");
+        const c1 = await repo.claimWarm("t-a", "bot-a");
+        const c2 = await repo.claimWarm("t-b", "bot-b");
+        const c3 = await repo.claimWarm("t-c", "bot-c");
+        const c4 = await repo.claimWarm("t-d", "bot-d");
+        expect(c1?.id).toBe("1");
+        expect(c2?.id).toBe("2");
+        expect(c3?.id).toBe("3");
+        expect(c4).toBeNull();
+        expect(await repo.warmCount()).toBe(0);
+    });
+    it("dead instances are not claimable", async () => {
+        const repo = new InMemoryPoolRepository();
+        await repo.insertWarm("a", "c-a");
+        await repo.markDead("a");
+        const result = await repo.claimWarm("t1", "bot");
+        expect(result).toBeNull();
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.71.0",
+  "version": "1.72.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/server/boot-config.ts

@@ -37,9 +37,20 @@ export interface BootConfig {
   /** Short product identifier (e.g. "paperclip", "wopr", "holyship"). */
   slug: string;
 
-  /** PostgreSQL connection string. */
+  /** PostgreSQL connection string. Required unless `pool` is provided. */
   databaseUrl: string;
 
+  /**
+   * Pre-created PostgreSQL connection pool. When provided, buildContainer
+   * reuses this pool and skips pool creation + Drizzle migrations. The
+   * caller is responsible for running their own migrations before calling
+   * buildContainer.
+   *
+   * Use this when the product has its own migration set (e.g. wopr-platform
+   * generates migrations locally from the shared schema).
+   */
+  pool?: import("pg").Pool;
+
   /** Bind host (default "0.0.0.0"). */
   host?: string;
 

package/src/server/container.ts

@@ -110,23 +110,30 @@ export interface PlatformContainer {
  * `bootConfig.features`. Disabled features yield `null`.
  */
 export async function buildContainer(bootConfig: BootConfig): Promise<PlatformContainer> {
-  if (!bootConfig.databaseUrl) {
-    throw new Error("buildContainer: databaseUrl is required");
+  // 1. Database pool — reuse existing or create new
+  let pool: Pool;
+  if (bootConfig.pool) {
+    pool = bootConfig.pool;
+  } else {
+    if (!bootConfig.databaseUrl) {
+      throw new Error("buildContainer: databaseUrl is required when pool is not provided");
+    }
+    const { Pool: PgPool } = await import("pg");
+    pool = new PgPool({ connectionString: bootConfig.databaseUrl });
   }
 
-  // 1. Database pool
-  const { Pool: PgPool } = await import("pg");
-  const pool: Pool = new PgPool({ connectionString: bootConfig.databaseUrl });
-
   // 2. Drizzle ORM instance
   const { createDb } = await import("../db/index.js");
   const db = createDb(pool);
 
-  // 3. Run Drizzle migrations
-  const { migrate } = await import("drizzle-orm/node-postgres/migrator");
-  const path = await import("node:path");
-  const migrationsFolder = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../drizzle");
-  await migrate(db as never, { migrationsFolder });
+  // 3. Run Drizzle migrations (skip when caller provided their own pool —
+  //    they are responsible for running product-specific migrations first)
+  if (!bootConfig.pool) {
+    const { migrate } = await import("drizzle-orm/node-postgres/migrator");
+    const path = await import("node:path");
+    const migrationsFolder = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../drizzle");
+    await migrate(db as never, { migrationsFolder });
+  }
 
   // 4. Bootstrap product config from DB (auto-seeds from presets if needed)
   const { platformBoot } = await import("../product-config/boot.js");

package/src/server/services/__tests__/hot-pool.test.ts

@@ -0,0 +1,30 @@
+/**
+ * Tests for hot pool service functions (getPoolSize, setPoolSize).
+ *
+ * Uses InMemoryPoolRepository to test service logic without Docker or DB.
+ */
+
+import { describe, expect, it } from "vitest";
+import { getPoolSize, setPoolSize } from "../hot-pool.js";
+import { InMemoryPoolRepository } from "./in-memory-pool-repository.js";
+
+describe("hot pool service", () => {
+  describe("getPoolSize / setPoolSize", () => {
+    it("returns default pool size", async () => {
+      const repo = new InMemoryPoolRepository();
+      expect(await getPoolSize(repo)).toBe(2);
+    });
+
+    it("sets and reads pool size", async () => {
+      const repo = new InMemoryPoolRepository();
+      await setPoolSize(repo, 10);
+      expect(await getPoolSize(repo)).toBe(10);
+    });
+
+    it("pool size of 0 is valid", async () => {
+      const repo = new InMemoryPoolRepository();
+      await setPoolSize(repo, 0);
+      expect(await getPoolSize(repo)).toBe(0);
+    });
+  });
+});

package/src/server/services/__tests__/in-memory-pool-repository.ts

@@ -0,0 +1,66 @@
+/**
+ * In-memory IPoolRepository for testing.
+ * FIFO claiming, dead instance handling — no DB required.
+ */
+
+import type { IPoolRepository, PoolInstance } from "../pool-repository.js";
+
+export class InMemoryPoolRepository implements IPoolRepository {
+  private poolSize = 2;
+  private instances: Array<PoolInstance & { createdAt: Date; claimedAt: Date | null }> = [];
+
+  async getPoolSize(): Promise<number> {
+    return this.poolSize;
+  }
+
+  async setPoolSize(size: number): Promise<void> {
+    this.poolSize = size;
+  }
+
+  async warmCount(): Promise<number> {
+    return this.instances.filter((i) => i.status === "warm").length;
+  }
+
+  async insertWarm(id: string, containerId: string): Promise<void> {
+    this.instances.push({
+      id,
+      containerId,
+      status: "warm",
+      tenantId: null,
+      name: null,
+      createdAt: new Date(),
+      claimedAt: null,
+    });
+  }
+
+  async listWarm(): Promise<PoolInstance[]> {
+    return this.instances.filter((i) => i.status === "warm").map(({ createdAt, claimedAt, ...rest }) => rest);
+  }
+
+  async markDead(id: string): Promise<void> {
+    const inst = this.instances.find((i) => i.id === id);
+    if (inst) inst.status = "dead";
+  }
+
+  async deleteDead(): Promise<void> {
+    this.instances = this.instances.filter((i) => i.status !== "dead");
+  }
+
+  async claimWarm(tenantId: string, name: string): Promise<{ id: string; containerId: string } | null> {
+    const warm = this.instances
+      .filter((i) => i.status === "warm")
+      .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+    if (warm.length === 0) return null;
+    const target = warm[0];
+    target.status = "claimed";
+    target.tenantId = tenantId;
+    target.name = name;
+    target.claimedAt = new Date();
+    return { id: target.id, containerId: target.containerId };
+  }
+
+  async updateInstanceStatus(id: string, status: string): Promise<void> {
+    const inst = this.instances.find((i) => i.id === id);
+    if (inst) inst.status = status;
+  }
+}

package/src/server/services/__tests__/pool-repository.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Tests for IPoolRepository interface contract.
+ *
+ * Uses an in-memory implementation to verify the interface
+ * behavior without requiring a real database.
+ */
+
+import { describe, expect, it } from "vitest";
+import { InMemoryPoolRepository } from "./in-memory-pool-repository.js";
+
+describe("IPoolRepository (InMemory)", () => {
+  it("returns default pool size of 2", async () => {
+    const repo = new InMemoryPoolRepository();
+    expect(await repo.getPoolSize()).toBe(2);
+  });
+
+  it("sets and gets pool size", async () => {
+    const repo = new InMemoryPoolRepository();
+    await repo.setPoolSize(5);
+    expect(await repo.getPoolSize()).toBe(5);
+  });
+
+  it("inserts and counts warm instances", async () => {
+    const repo = new InMemoryPoolRepository();
+    expect(await repo.warmCount()).toBe(0);
+
+    await repo.insertWarm("a", "container-a");
+    await repo.insertWarm("b", "container-b");
+
+    expect(await repo.warmCount()).toBe(2);
+  });
+
+  it("lists warm instances", async () => {
+    const repo = new InMemoryPoolRepository();
+    await repo.insertWarm("a", "container-a");
+    await repo.insertWarm("b", "container-b");
+
+    const warm = await repo.listWarm();
+    expect(warm).toHaveLength(2);
+    expect(warm[0].id).toBe("a");
+    expect(warm[0].containerId).toBe("container-a");
+    expect(warm[0].status).toBe("warm");
+  });
+
+  it("claims warm instance FIFO", async () => {
+    const repo = new InMemoryPoolRepository();
+    await repo.insertWarm("first", "c-first");
+    await repo.insertWarm("second", "c-second");
+
+    const claimed = await repo.claimWarm("tenant-1", "my-bot");
+    expect(claimed).not.toBeNull();
+    expect(claimed?.id).toBe("first");
+    expect(claimed?.containerId).toBe("c-first");
+
+    // Warm count drops by 1
+    expect(await repo.warmCount()).toBe(1);
+  });
+
+  it("returns null when claiming from empty pool", async () => {
+    const repo = new InMemoryPoolRepository();
+    const result = await repo.claimWarm("tenant-1", "bot");
+    expect(result).toBeNull();
+  });
+
+  it("does not re-claim already claimed instances", async () => {
+    const repo = new InMemoryPoolRepository();
+    await repo.insertWarm("only", "c-only");
+
+    const first = await repo.claimWarm("t1", "bot1");
+    expect(first).not.toBeNull();
+
+    const second = await repo.claimWarm("t2", "bot2");
+    expect(second).toBeNull();
+  });
+
+  it("marks instances dead", async () => {
+    const repo = new InMemoryPoolRepository();
+    await repo.insertWarm("a", "c-a");
+    await repo.markDead("a");
+
+    expect(await repo.warmCount()).toBe(0);
+    const warm = await repo.listWarm();
+    expect(warm).toHaveLength(0);
+  });
+
+  it("deletes dead instances", async () => {
+    const repo = new InMemoryPoolRepository();
+    await repo.insertWarm("a", "c-a");
+    await repo.insertWarm("b", "c-b");
+    await repo.markDead("a");
+
+    await repo.deleteDead();
+
+    // Only 'b' remains (warm)
+    expect(await repo.warmCount()).toBe(1);
+    const warm = await repo.listWarm();
+    expect(warm[0].id).toBe("b");
+  });
+
+  it("updates instance status", async () => {
+    const repo = new InMemoryPoolRepository();
+    await repo.insertWarm("a", "c-a");
+    await repo.updateInstanceStatus("a", "provisioning");
+
+    // No longer warm
+    expect(await repo.warmCount()).toBe(0);
+  });
+
+  it("handles multiple claims in order", async () => {
+    const repo = new InMemoryPoolRepository();
+    await repo.insertWarm("1", "c-1");
+    await repo.insertWarm("2", "c-2");
+    await repo.insertWarm("3", "c-3");
+
+    const c1 = await repo.claimWarm("t-a", "bot-a");
+    const c2 = await repo.claimWarm("t-b", "bot-b");
+    const c3 = await repo.claimWarm("t-c", "bot-c");
+    const c4 = await repo.claimWarm("t-d", "bot-d");
+
+    expect(c1?.id).toBe("1");
+    expect(c2?.id).toBe("2");
+    expect(c3?.id).toBe("3");
+    expect(c4).toBeNull();
+    expect(await repo.warmCount()).toBe(0);
+  });
+
+  it("dead instances are not claimable", async () => {
+    const repo = new InMemoryPoolRepository();
+    await repo.insertWarm("a", "c-a");
+    await repo.markDead("a");
+
+    const result = await repo.claimWarm("t1", "bot");
+    expect(result).toBeNull();
+  });
+});