@softure-ai/db 0.0.0-stage → 0.1.5

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAIA,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAQ9F;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,cAAc,CAAC,CAS3G;AAED,+EAA+E;AAC/E,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAO1D"}

package/dist/shared.js

@@ -0,0 +1,32 @@
+// One database handle per URL for the whole server process, shared by every module's Next.js
+// adapter and the app. Package code cannot import the app's own handle, and `next dev` re-evaluates
+// modules on every change, so the handles live on `globalThis` under a `Symbol.for` key: each
+// reload, and each copy of this file in separate server bundles, finds the same pool.
+import { createDatabase } from "./client.js";
+const HANDLES_KEY = Symbol.for("@softure-ai/db/shared-handles");
+const host = globalThis;
+/**
+ * The process-wide handle for `url`, opened on first use. `options` apply only to that first call.
+ * A failed open is not kept, so the next call tries again.
+ */
+export function getSharedDatabase(url, options = {}) {
+    const handles = (host[HANDLES_KEY] ??= new Map());
+    let handle = handles.get(url);
+    if (handle === undefined) {
+        handle = createDatabase(url, options);
+        handles.set(url, handle);
+        handle.catch(() => handles.delete(url));
+    }
+    return handle;
+}
+/** Closes and forgets every shared handle. For tests and graceful shutdown. */
+export async function closeSharedDatabases() {
+    const handles = host[HANDLES_KEY];
+    if (handles === undefined)
+        return;
+    const opened = [...handles.values()];
+    handles.clear();
+    const results = await Promise.allSettled(opened);
+    await Promise.all(results.flatMap((result) => (result.status === "fulfilled" ? [result.value.close()] : [])));
+}
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,oGAAoG;AACpG,8FAA8F;AAC9F,sFAAsF;AACtF,OAAO,EAAE,cAAc,EAAmD,MAAM,aAAa,CAAC;AAE9F,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;AAIhE,MAAM,IAAI,GAAG,UAAmC,CAAC;AAEjD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,UAAiC,EAAE;IAChF,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI,GAAG,EAAmC,CAAC,CAAC;IACnF,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,GAAG,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACzB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;IAClC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO;IAClC,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACrC,OAAO,CAAC,KAAK,EAAE,CAAC;IAChB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAChH,CAAC"}

package/dist/testing.d.ts

@@ -0,0 +1,14 @@
+import { PGlite } from "@electric-sql/pglite";
+import type { AnySoftureModule } from "@softure-ai/core";
+import { type PgliteClientDatabase } from "./client.js";
+export interface TestDatabase {
+    readonly db: PgliteClientDatabase;
+    readonly client: PGlite;
+    readonly close: () => Promise<void>;
+}
+/**
+ * A fresh, migrated, in-memory database per call. List the module under test and the modules it
+ * depends on. Throws when a migration is invalid or fails: that is a bug in the module package.
+ */
+export declare function createTestDatabase(modules?: readonly AnySoftureModule[]): Promise<TestDatabase>;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAsB,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAI5E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,oBAAoB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAID;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,SAAS,gBAAgB,EAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAIzG"}

package/dist/testing.js

@@ -0,0 +1,43 @@
+// Test databases for module unit tests (docs/02-module-standard.md §10): a real Postgres (PGlite)
+// with the real migrations of the given modules. Migrating costs about two seconds, so each
+// module set is migrated once per test worker into a template, and every call starts from a copy
+// of the template's data folder (FIRE_TRACKER `src/db/test-db.ts`).
+import { PGlite } from "@electric-sql/pglite";
+import { createPgliteHandle } from "./client.js";
+import { migrate } from "./migrations/migrator.js";
+import { describeProblem } from "./migrations/problems.js";
+const templates = new Map();
+/**
+ * A fresh, migrated, in-memory database per call. List the module under test and the modules it
+ * depends on. Throws when a migration is invalid or fails: that is a bug in the module package.
+ */
+export async function createTestDatabase(modules = []) {
+    const client = new PGlite({ loadDataDir: await getTemplate(modules) });
+    const handle = await createPgliteHandle(client);
+    return { db: handle.db, client, close: handle.close };
+}
+function getTemplate(modules) {
+    const key = modules.map((module) => `${module.id}@${module.migrations?.dir.href ?? "-"}`).join("|");
+    let template = templates.get(key);
+    if (template === undefined) {
+        template = buildTemplate(modules);
+        templates.set(key, template);
+        // A failed build is not cached: the next call reports the problem again.
+        template.catch(() => templates.delete(key));
+    }
+    return template;
+}
+async function buildTemplate(modules) {
+    const handle = await createPgliteHandle(new PGlite());
+    try {
+        const result = await migrate(handle, { modules });
+        if (!result.ok) {
+            throw new Error(`createTestDatabase: migrations failed:\n${result.problems.map(describeProblem).join("\n")}`);
+        }
+        return await handle.client.dumpDataDir("none");
+    }
+    finally {
+        await handle.close();
+    }
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,4FAA4F;AAC5F,iGAAiG;AACjG,oEAAoE;AACpE,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE9C,OAAO,EAAE,kBAAkB,EAA6B,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAQ3D,MAAM,SAAS,GAAG,IAAI,GAAG,EAAgC,CAAC;AAE1D;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,UAAuC,EAAE;IAChF,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACvE,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAChD,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;AACxD,CAAC;AAED,SAAS,WAAW,CAAC,OAAoC;IACvD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,UAAU,EAAE,GAAG,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpG,IAAI,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QAClC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC7B,yEAAyE;QACzE,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,OAAoC;IAC/D,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC;IACtD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,2CAA2C,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChH,CAAC;QACD,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACjD,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@softure-ai/db",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.5",
+  "description": "SOFTURE AI database layer: pg/PGlite client, per-module migrator with plan and adopt, PGlite test databases.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SOFTURE/AI.git",
+    "directory": "foundation/db"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "softure": "./dist/cli/bin.js"
+  },
+  "exports": {
+    ".": {
+      "@softure-ai/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "@softure-ai/source": "./src/testing.ts",
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
+    "./cli": {
+      "@softure-ai/source": "./src/cli/index.ts",
+      "types": "./dist/cli/index.d.ts",
+      "default": "./dist/cli/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@electric-sql/pglite": "^0.5.8",
+    "@softure-ai/core": "^0.1.0",
+    "@types/pg": "^8.23.1",
+    "pg": "^8.23.1"
+  },
+  "peerDependencies": {
+    "drizzle-orm": "^0.45.2"
+  }
+}

package/src/cli/bin.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// The `softure` executable. All logic lives in command.ts, which the tests call directly.
+import { runSoftureCommand } from "./command.js";
+
+process.exitCode = await runSoftureCommand({ argv: process.argv.slice(2), cwd: process.cwd() });

package/src/cli/command.ts

@@ -0,0 +1,47 @@
+// The `softure` bin: `softure migrate [--config <file>] [options]`. It loads the app's config through
+// `@softure-ai/core/cli`, so the file must be loadable by Node itself: `.js`/`.mjs`, or `.ts` where
+// Node strips types (Node >= 22.18; relative imports then need `.ts` extensions). Anything else
+// uses an app script with `runMigrateCli` instead (see run.ts).
+import { loadAppConfig, takeConfigOption } from "@softure-ai/core/cli";
+import { EXIT_FAILED, EXIT_OK, EXIT_USAGE, MIGRATE_USAGE, runMigrateCli, type CliOutput } from "./run.js";
+
+export interface RunSoftureCommandOptions {
+  readonly argv: readonly string[];
+  readonly cwd: string;
+  readonly output?: CliOutput;
+}
+
+const APP_SCRIPT = { runner: "runMigrateCli", packageName: "@softure-ai/db" };
+
+const consoleOutput: CliOutput = {
+  log: (line) => console.log(line),
+  error: (line) => console.error(line),
+};
+
+export async function runSoftureCommand(options: RunSoftureCommandOptions): Promise<number> {
+  const output = options.output ?? consoleOutput;
+  const [command, ...rest] = options.argv;
+  if (command !== "migrate") {
+    output.error(command === undefined ? "softure: missing command" : `softure: unknown command "${command}"`);
+    output.error("Commands: migrate");
+    output.error(MIGRATE_USAGE);
+    return EXIT_USAGE;
+  }
+
+  if (rest.includes("--help")) {
+    output.log(MIGRATE_USAGE);
+    return EXIT_OK;
+  }
+  const taken = takeConfigOption(rest);
+  if (!taken.ok) {
+    output.error(`softure migrate: ${taken.problem}`);
+    output.error(MIGRATE_USAGE);
+    return EXIT_USAGE;
+  }
+  const loaded = await loadAppConfig({ cwd: options.cwd, configPath: taken.configPath, appScript: APP_SCRIPT });
+  if (!loaded.ok) {
+    output.error(`softure: ${loaded.problem}`);
+    return EXIT_FAILED;
+  }
+  return runMigrateCli({ config: loaded.config, argv: taken.argv, cwd: options.cwd, output });
+}

package/src/cli/index.ts

@@ -0,0 +1,3 @@
+// `@softure-ai/db/cli`: the `softure migrate` command for app scripts and container bundles.
+export { runSoftureCommand, type RunSoftureCommandOptions } from "./command.js";
+export { EXIT_FAILED, EXIT_OK, EXIT_USAGE, MIGRATE_USAGE, runMigrateCli, type CliOutput, type RunMigrateCliOptions } from "./run.js";

package/src/cli/run.ts

@@ -0,0 +1,189 @@
+// `softure migrate` (docs/02-module-standard.md §4). The app passes its validated config, so the
+// same function serves the `softure` bin and an app script that esbuild bundles for a container:
+//
+//   // scripts/migrate.ts
+//   import { runMigrateCli } from "@softure-ai/db/cli";
+//   import config from "../softure.config";
+//   process.exitCode = await runMigrateCli({ config, argv: process.argv.slice(2) });
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { pathToFileURL } from "node:url";
+import type { SoftureConfig } from "@softure-ai/core";
+import { createDatabase, type DatabaseHandle } from "../client.js";
+import { adoptModule } from "../migrations/adopt.js";
+import { exportMigrations } from "../migrations/export.js";
+import { migrate, planMigrations, type MigrationStep } from "../migrations/migrator.js";
+import { describeProblem, type MigrationFailure } from "../migrations/problems.js";
+
+export interface CliOutput {
+  readonly log: (line: string) => void;
+  readonly error: (line: string) => void;
+}
+
+export interface RunMigrateCliOptions {
+  readonly config: Pick<SoftureConfig, "database" | "modules">;
+  /** The arguments after the command name, e.g. `["--plan"]`. */
+  readonly argv: readonly string[];
+  /** Relative paths resolve against it. Default: `process.cwd()`. */
+  readonly cwd?: string;
+  readonly output?: CliOutput;
+}
+
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_USAGE = 2;
+
+export const MIGRATE_USAGE = `Usage: softure migrate [options]
+
+Applies the SQL migrations of every enabled module, each in its own schema.
+
+Options:
+  --plan                        show what would be applied (or adopted) and change nothing
+  --adopt <module>@<version>    record an existing schema as migrated, after comparing it
+  --migrations-dir <dir>        read module files from <dir>/<module id>/ (bundled runners)
+  --export-migrations <dir>     copy module files to <dir>/<module id>/ and exit (build stage)
+  --help                        show this help`;
+
+const ADOPT_TARGET = /^([a-z][a-z0-9]*(?:-[a-z0-9]+)*)@(\d+\.\d+\.\d+)$/;
+
+const consoleOutput: CliOutput = {
+  log: (line) => console.log(line),
+  error: (line) => console.error(line),
+};
+
+type Command =
+  | { kind: "help" }
+  | { kind: "export"; targetDir: string }
+  | { kind: "migrate"; plan: boolean; migrationsDir: string | undefined }
+  | { kind: "adopt"; plan: boolean; module: string; version: string; migrationsDir: string | undefined };
+
+/** Runs the command and returns the process exit code: 0 done, 1 failed, 2 usage error. */
+export async function runMigrateCli(options: RunMigrateCliOptions): Promise<number> {
+  const output = options.output ?? consoleOutput;
+  const cwd = options.cwd ?? process.cwd();
+  const command = parseCommand(options.argv);
+  if (typeof command === "string") {
+    output.error(`softure migrate: ${command}`);
+    output.error(MIGRATE_USAGE);
+    return EXIT_USAGE;
+  }
+  if (command.kind === "help") {
+    output.log(MIGRATE_USAGE);
+    return EXIT_OK;
+  }
+  if (command.kind === "export") {
+    const result = await exportMigrations(options.config.modules, resolve(cwd, command.targetDir));
+    if (!result.ok) return reportFailure(output, result);
+    result.value.forEach((step) => output.log(`exported ${formatStep(step)}`));
+    return EXIT_OK;
+  }
+
+  const url = options.config.database?.url;
+  if (url === undefined) {
+    output.error("softure migrate: the config has no database; set database.url in softure.config");
+    return EXIT_FAILED;
+  }
+  let handle: DatabaseHandle;
+  try {
+    handle = await createDatabase(url);
+  } catch (error) {
+    output.error(`softure migrate: ${describeError(error)}`);
+    return EXIT_FAILED;
+  }
+  try {
+    const migrationsDir = command.migrationsDir === undefined ? undefined : pathToFileURL(`${resolve(cwd, command.migrationsDir)}/`);
+    return await runDatabaseCommand(handle, { command, modules: options.config.modules, migrationsDir, output });
+  } catch (error) {
+    // Connection and driver errors: the message only, never a stack or the database URL.
+    output.error(`softure migrate: ${describeError(error)}`);
+    return EXIT_FAILED;
+  } finally {
+    await handle.close();
+  }
+}
+
+async function runDatabaseCommand(
+  handle: DatabaseHandle,
+  input: {
+    command: Extract<Command, { kind: "migrate" | "adopt" }>;
+    modules: RunMigrateCliOptions["config"]["modules"];
+    migrationsDir: URL | undefined;
+    output: CliOutput;
+  },
+): Promise<number> {
+  const { command, modules, output } = input;
+  const dirOption = input.migrationsDir === undefined ? {} : { migrationsDir: input.migrationsDir };
+
+  if (command.kind === "adopt") {
+    const result = await adoptModule(handle, { modules, module: command.module, version: command.version, dryRun: command.plan, ...dirOption });
+    if (!result.ok) return reportFailure(output, result);
+    const verb = command.plan ? "would" : "did";
+    result.value.ledger.forEach((step) => output.log(`${verb} apply ${formatStep(step)}`));
+    result.value.adopted.forEach((step) => output.log(`${verb} adopt ${formatStep(step)}`));
+    output.log(`${command.module}@${command.version}: the schema matches its migrations${command.plan ? " (plan only, nothing written)" : "; adopted"}`);
+    return EXIT_OK;
+  }
+
+  if (command.plan) {
+    const result = await planMigrations(handle, { modules, ...dirOption });
+    if (!result.ok) return reportFailure(output, result);
+    result.value.pending.forEach((step) => output.log(`pending ${formatStep(step)}`));
+    output.log(result.value.pending.length === 0 ? "nothing to apply" : `${result.value.pending.length} migration(s) to apply`);
+    return EXIT_OK;
+  }
+
+  const result = await migrate(handle, { modules, ...dirOption, onApplied: (step) => output.log(`applied ${formatStep(step)}`) });
+  if (!result.ok) return reportFailure(output, result);
+  output.log(result.value.applied.length === 0 ? "nothing to apply" : `${result.value.applied.length} migration(s) applied`);
+  return EXIT_OK;
+}
+
+function parseCommand(argv: readonly string[]): Command | string {
+  let values: { plan?: boolean; adopt?: string; "migrations-dir"?: string; "export-migrations"?: string; help?: boolean };
+  try {
+    ({ values } = parseArgs({
+      args: [...argv],
+      options: {
+        plan: { type: "boolean" },
+        adopt: { type: "string" },
+        "migrations-dir": { type: "string" },
+        "export-migrations": { type: "string" },
+        help: { type: "boolean" },
+      },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (error) {
+    return describeError(error);
+  }
+
+  if (values.help === true) return { kind: "help" };
+  const exportDir = values["export-migrations"];
+  if (exportDir !== undefined) {
+    const others = (["plan", "adopt", "migrations-dir"] as const).filter((name) => values[name] !== undefined);
+    return others.length > 0 ? `--export-migrations cannot be combined with --${others.join(", --")}` : { kind: "export", targetDir: exportDir };
+  }
+  const plan = values.plan === true;
+  const migrationsDir = values["migrations-dir"];
+  if (values.adopt === undefined) {
+    return { kind: "migrate", plan, migrationsDir };
+  }
+  const match = ADOPT_TARGET.exec(values.adopt);
+  if (match?.[1] === undefined || match[2] === undefined) {
+    return `--adopt expects <module>@<x.y.z>, e.g. auth@0.1.0, got "${values.adopt}"`;
+  }
+  return { kind: "adopt", plan, module: match[1], version: match[2], migrationsDir };
+}
+
+function reportFailure(output: CliOutput, failure: MigrationFailure): number {
+  failure.problems.forEach((problem) => output.error(describeProblem(problem)));
+  return EXIT_FAILED;
+}
+
+function formatStep(step: MigrationStep): string {
+  return `${step.module} ${String(step.version).padStart(4, "0")}_${step.name}.sql`;
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/client.ts

@@ -0,0 +1,79 @@
+// The database client (FIRE_TRACKER `src/db/client.ts`, generalised). The driver follows the URL:
+// `postgres://` or `postgresql://` → node-postgres (production), `pglite://<dir>` → PGlite, a
+// real Postgres in-process (dev without a server); `pglite://` alone is an in-memory database.
+// Drivers load through dynamic `import()`, so a bundle can keep both external and an app pays
+// only for the one it uses.
+import type { PGlite } from "@electric-sql/pglite";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { PgliteDatabase } from "drizzle-orm/pglite";
+import type { Pool } from "pg";
+
+const PGLITE_PREFIX = "pglite://";
+const POSTGRES_PREFIXES = ["postgres://", "postgresql://"];
+
+export type PostgresDatabase = NodePgDatabase & { $client: Pool };
+export type PgliteClientDatabase = PgliteDatabase & { $client: PGlite };
+
+/** The drizzle database modules and the app query through. */
+export type Database = PostgresDatabase | PgliteClientDatabase;
+
+/**
+ * A connection *or* an open transaction. Query helpers take this, so one function serves a
+ * plain read and a step inside `db.transaction()` (FIRE `client.ts`).
+ */
+export type Queryable = Database | Parameters<Parameters<Database["transaction"]>[0]>[0];
+
+export type DatabaseHandle =
+  | {
+      readonly kind: "postgres";
+      readonly db: PostgresDatabase;
+      readonly pool: Pool;
+      readonly close: () => Promise<void>;
+    }
+  | {
+      readonly kind: "pglite";
+      readonly db: PgliteClientDatabase;
+      readonly client: PGlite;
+      readonly close: () => Promise<void>;
+    };
+
+export interface CreateDatabaseOptions {
+  /** Pool size for Postgres; ignored by PGlite, which has a single connection. Default 10. */
+  readonly max?: number;
+}
+
+/**
+ * Opens the database a URL points at. Throws when the scheme is not supported: that is a
+ * deployment bug. The message names the scheme only, never the URL, which holds a password.
+ */
+export async function createDatabase(url: string, options: CreateDatabaseOptions = {}): Promise<DatabaseHandle> {
+  if (url.startsWith(PGLITE_PREFIX)) {
+    const dataDir = url.slice(PGLITE_PREFIX.length);
+    const { PGlite } = await import("@electric-sql/pglite");
+    const client = dataDir === "" ? new PGlite() : new PGlite(dataDir);
+    return createPgliteHandle(client);
+  }
+  if (POSTGRES_PREFIXES.some((prefix) => url.startsWith(prefix))) {
+    const { default: pg } = await import("pg");
+    const { drizzle } = await import("drizzle-orm/node-postgres");
+    const pool = new pg.Pool({ connectionString: url, max: options.max ?? 10 });
+    // An idle client that loses its connection emits 'error' on the pool; unhandled, it would
+    // crash the process. The pool drops that client and the next query opens a new one.
+    pool.on("error", () => undefined);
+    return { kind: "postgres", db: drizzle({ client: pool }), pool, close: () => pool.end() };
+  }
+  throw new Error(
+    `createDatabase: unsupported database URL scheme ${describeScheme(url)}; use postgres://, postgresql:// or pglite://<dir>`,
+  );
+}
+
+/** Wraps an open PGlite instance (used by `createTestDatabase`). */
+export async function createPgliteHandle(client: PGlite): Promise<DatabaseHandle & { kind: "pglite" }> {
+  const { drizzle } = await import("drizzle-orm/pglite");
+  return { kind: "pglite", db: drizzle({ client }), client, close: () => client.close() };
+}
+
+function describeScheme(url: string): string {
+  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(url)?.[1];
+  return scheme === undefined ? "(none)" : `"${scheme}:"`;
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+// Public API of @softure-ai/db: the database client and the module migrator
+// (docs/02-module-standard.md §4). Test databases: `@softure-ai/db/testing`; CLI: `@softure-ai/db/cli`.
+export {
+  createDatabase,
+  type CreateDatabaseOptions,
+  type Database,
+  type DatabaseHandle,
+  type PgliteClientDatabase,
+  type PostgresDatabase,
+  type Queryable,
+} from "./client.js";
+export { closeSharedDatabases, getSharedDatabase } from "./shared.js";
+export { computeChecksum, readMigrationFiles, type MigrationFile } from "./migrations/files.js";
+export {
+  describeProblem,
+  type MigrationErrorCode,
+  type MigrationFailure,
+  type MigrationProblem,
+  type MigrationResult,
+} from "./migrations/problems.js";
+export {
+  migrate,
+  planMigrations,
+  type MigrateOptions,
+  type MigrationPlan,
+  type MigrationReport,
+  type MigrationStep,
+} from "./migrations/migrator.js";
+export { adoptModule, type AdoptionReport, type AdoptOptions } from "./migrations/adopt.js";
+export { exportMigrations } from "./migrations/export.js";
+export {
+  checkExportedMigrations,
+  type ExportedMigration,
+  type ExportedMigrationsCheck,
+} from "./migrations/exported.js";
+export { readJournal, type JournalRow, type MigrationMethod } from "./migrations/ledger.js";
+export type { MigrationSession } from "./migrations/session.js";