feat: add transactional module migration runner

core/tests/postgres-migration-database.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it, vi } from "vitest";
+
+const clientConstructor = vi.hoisted(() => vi.fn());
+
+vi.mock("pg", () => ({ Client: clientConstructor }));
+
+import {
+  createPostgresMigrationDatabase,
+  PostgresMigrationDatabaseError,
+} from "../src/migrations/postgres-database.js";
+
+describe("PostgreSQL migration database composition", () => {
+  it("does not construct a client or execute SQL merely because the adapter is imported", () => {
+    expect(clientConstructor).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    undefined,
+    "",
+    "not-a-database-url",
+    "https://admin:[email protected]/database",
+  ])("rejects missing or invalid configuration without exposing it (%s)", (databaseUrl) => {
+    let captured: unknown;
+    try {
+      createPostgresMigrationDatabase(databaseUrl);
+    } catch (error) {
+      captured = error;
+    }
+
+    expect(captured).toBeInstanceOf(PostgresMigrationDatabaseError);
+    expect(captured).toMatchObject({ code: "POSTGRES_MIGRATION_CONFIGURATION_INVALID" });
+    const publicText = `${String(captured)}\n${
+      captured instanceof Error ? (captured.stack ?? "") : ""
+    }\n${JSON.stringify(captured)}`;
+    if (databaseUrl) {
+      expect(publicText).not.toContain(databaseUrl);
+    }
+    expect(clientConstructor).not.toHaveBeenCalled();
+  });
+
+  it("creates a lazy database composition without opening a connection", () => {
+    const database = createPostgresMigrationDatabase(
+      "postgresql://operator:[email protected]/ekklesia",
+    );
+
+    expect(Object.isFrozen(database)).toBe(true);
+    expect(clientConstructor).not.toHaveBeenCalled();
+    expect(JSON.stringify(database)).not.toContain("operator");
+    expect(JSON.stringify(database)).not.toContain("do-not-log");
+    expect(JSON.stringify(database)).not.toContain("example.test");
+  });
+});