@softure-ai/db 0.0.0-stage → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SOFTURE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,190 @@
-# Temporary Holding Version
+# @softure-ai/db
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Status:** wave 0 · implemented in FD-4 (`db-migrator`), 0.1.5, prepared for its first release (the owner's tag, `scripts/release/README.md`).
+
+The database layer every SOFTURE module stands on. Standard:
+[docs/02-module-standard.md](../../docs/02-module-standard.md) §4. Sources in FIRE_TRACKER:
+`src/db/client.ts`, `src/db/test-db.ts`, `scripts/migrate.ts`, `docker/Dockerfile` (`migrate.cjs`).
+
+## 1. What it provides
+
+A pg/PGlite client chosen by URL, a migrator that runs each module's SQL in the module's own
+Postgres schema (with a ledger, checksums, a lock, a dry run and adoption of existing tables),
+`createTestDatabase` for unit tests, and the `softure migrate` command.
+
+## 2. Installation
+
+```bash
+npm install @softure-ai/db drizzle-orm
+```
+
+Node ≥ 22, ESM only. `drizzle-orm` (`^0.45.2`) is a peer dependency, so the app, the modules and
+this package share one drizzle. `pg` and `@electric-sql/pglite` come with the package and load
+only when used.
+
+## 3. Configuration
+
+The database URL comes from the app config (`database.url` in `defineSoftureConfig`), usually
+`process.env.DATABASE_URL`:
+
+| URL | Driver |
+| --- | --- |
+| `postgres://…`, `postgresql://…` | node-postgres pool (production) |
+| `pglite://<dir>` | PGlite, a real Postgres in-process, data in `<dir>` (dev without a server) |
+| `pglite://` | PGlite in memory |
+
+```ts
+import { createDatabase, type Queryable } from "@softure-ai/db";
+
+const handle = await createDatabase(config.database.url, { max: 10 }); // max: pg pool size
+await handle.db.select().from(notes);   // drizzle
+await handle.close();
+```
+
+- `DatabaseHandle` is `{ kind: "postgres", db, pool, close } | { kind: "pglite", db, client, close }`.
+- `Database` is the drizzle database of either driver; `Queryable` is a `Database` or an open
+  transaction, so one helper serves both (`db.transaction(async (tx) => helper(tx))`).
+- An unsupported scheme throws, naming the scheme only; the URL (and its password) is never
+  printed.
+
+## 4. Mounting
+
+Nothing to mount. Migrations run as a deploy step:
+
+- **Dev:** `npx softure migrate` finds `softure.config.{ts,mts,js,mjs}` in the working directory
+  (or `--config <file>`). The file must be one Node can import: `.js`/`.mjs`, or `.ts` where Node
+  strips types (Node ≥ 22.18, relative imports written with `.ts`). Otherwise use the script below.
+  The lookup is `@softure-ai/core/cli`'s, shared with `softure-mail` and `softure-blog`.
+- **App script and container image:** the app owns a three-line script, which esbuild bundles:
+
+```ts
+// 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) });
+```
+
+```dockerfile
+# build stage: copy each module's SQL next to the bundle, then bundle the runner
+RUN npx tsx scripts/migrate.ts --export-migrations ./softure-migrations
+RUN npx esbuild scripts/migrate.ts --bundle --platform=node --format=esm --target=node22 \
+      --external:pg --external:@electric-sql/pglite --outfile=migrate.mjs
+# run stage (needs pg, and @electric-sql/pglite for --adopt)
+COPY --from=builder /app/migrate.mjs ./migrate.mjs
+COPY --from=builder /app/softure-migrations ./softure-migrations
+CMD ["node", "migrate.mjs", "--migrations-dir", "./softure-migrations"]
+```
+
+A bundle cannot find package folders (`import.meta.url` points at the bundle), hence
+`--export-migrations` at build time and `--migrations-dir` at run time. The ledger's own migration
+ships as code.
+
+**Options of `softure migrate`:**
+
+| Option | Effect |
+| --- | --- |
+| (none) | apply every pending migration |
+| `--plan` | print what would be applied (or adopted); change nothing |
+| `--adopt <module>@<version>` | record an existing schema as migrated after comparing it (section 5) |
+| `--migrations-dir <dir>` | read module files from `<dir>/<module id>/` |
+| `--export-migrations <dir>` | copy module files to `<dir>/<module id>/` and exit; needs no database; replaces older `.sql` copies and refuses a module folder holding anything else |
+
+Exit codes: 0 done, 1 a problem or failure (each printed on stderr), 2 a usage error.
+
+The same operations as functions: `migrate(handle, { modules, migrationsDir?, onApplied? })`,
+`planMigrations(handle, { modules })`, `adoptModule(handle, { modules, module, version, dryRun? })`,
+`exportMigrations(modules, dir)`. Each returns `{ ok: true, value } | { ok: false, error, problems }`;
+`describeProblem(problem)` gives the English line.
+
+For a deploy, `checkExportedMigrations(dir, journal)` runs the same comparison on an exported folder without the app
+config: `journal` is `readJournal(session)` of the target database, and the result lists the pending files and the
+ledger modules the folder does not hold, or every problem. `softure-deploy schema-guard` (`@softure-ai/deploy`) is
+built on it.
+
+## 5. Migrations and tables
+
+**Owned:** schema `softure`, table `softure.migrations` (`id, module, version, name, checksum,
+module_version, method ('applied' | 'adopted'), applied_at`, primary key `(module, version)`).
+
+**Module files** (`migrations/NNNN_<lower_snake>.sql`, numbered 1..n without gaps):
+- the file opens with a comment block that contains `Rollback:` and says how to undo it;
+- no top-level statement may begin, end or abort a transaction (`BEGIN`, `COMMIT`, `ROLLBACK`,
+  `END`, `ABORT`, `START TRANSACTION`, `PREPARE TRANSACTION`); bodies in quotes or dollar quotes
+  (PL/pgSQL `BEGIN … END;`) are fine, SQL-standard `BEGIN ATOMIC` bodies are not. Each file runs in
+  its own transaction with its ledger row, and a file that still ended it is reported as such,
+  not as rolled back;
+- unqualified names land in the module's schema: the runner runs `CREATE SCHEMA IF NOT EXISTS` and
+  `SET LOCAL search_path TO <schema>, public` first. Name other modules' tables with their schema
+  (`REFERENCES notes.notes (id)`), and create extensions `WITH SCHEMA public`.
+
+**Each run:** modules in dependency order (`sortModulesByDependencies`), files in number order.
+Before anything runs, every file of every module is checked: an applied file that was edited or
+renamed (`db.migration_changed`), deleted (`db.migration_missing`), or a new file numbered below an
+applied one (`db.migration_out_of_order`) refuses the whole run. The run holds a session-level
+`pg_advisory_lock`, so a second runner waits, then finds nothing to do. A failing file is rolled
+back completely and stops the run; the files before it stay applied. The migration connection is
+closed after the run, never returned to the pool.
+
+**Refused modules:** the id `softure`; the schemas `softure`, `public`, `information_schema`,
+`pg_*` and names over 63 bytes; migrations without a `dbSchema`.
+
+**Adoption** ([docs/05](../../docs/05-adoption-playbook.md) step 3): after the app's own migration
+moved its tables into the module's schema, `--adopt <module>@<version>` (with `--plan` first)
+builds the schema the module's migrations create on a scratch PGlite and compares it with the live
+one through `pg_catalog`: relations (and whether they are unlogged), columns (type, collation,
+not null, default, identity, generated), sequences with their parameters, constraints and indexes
+(names and definitions), triggers, functions, and enum, domain, range and composite types. Only an
+exact match records the files as `adopted`; every difference is printed (`missing in database: …`,
+`unexpected in database: …`). The version must equal the enabled module's, the module must be new
+to the ledger, and the modules it depends on must be fully migrated or adopted first. Undo:
+`DELETE FROM softure.migrations WHERE module = '<id>' AND method = 'adopted'`.
+
+**Tests:** `createTestDatabase(modules)` from `@softure-ai/db/testing` returns `{ db, client, close }`:
+an in-memory PGlite with the ledger and the listed modules migrated (list the module and the
+modules it depends on). Each module set is migrated once per test worker and copied per call; a
+broken migration throws naming the file.
+
+```ts
+import { createTestDatabase } from "@softure-ai/db/testing";
+
+const database = await createTestDatabase([notes()]);
+afterEach(() => database.close());
+```
+
+## 6. Environment variables
+
+None read by the package. The app passes `DATABASE_URL` (or any variable) through
+`database.url` in its config.
+
+## 7. Switches
+
+None.
+
+## 8. Appearance
+
+None.
+
+## 9. Copy
+
+None: no user-facing text. Command output and problem lines are English developer messages.
+
+## 10. Hooks
+
+`onApplied(step)` in `migrate` options, called after each committed file.
+
+## 11. GDPR
+
+No personal data. The ledger holds module ids, file names and checksums.
+
+## 12. Limitations
+
+- Forward only: there are no down migrations; each file states its rollback in its comment.
+- A file cannot run outside a transaction (`CREATE INDEX CONCURRENTLY`, `ALTER TYPE … ADD VALUE`
+  before Postgres 12).
+- No lock timeout: a stuck runner holds the lock until its connection ends (visible in `pg_locks`).
+  The session-level lock needs a direct connection or a session-mode pooler, not a
+  transaction-mode PgBouncer.
+- Adoption does not compare grants, comments, column order, row-level security policies or view
+  bodies, and needs PGlite installed where it runs (also in an image that otherwise uses `pg`).
+- No cached connection for Next.js dev reloads yet; the Next adapter (identity ID-1, FD-7) adds it.

package/dist/cli/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/cli/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":""}

package/dist/cli/bin.js

@@ -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() });
+//# sourceMappingURL=bin.js.map

package/dist/cli/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AACA,0FAA0F;AAC1F,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,CAAC,QAAQ,GAAG,MAAM,iBAAiB,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC"}

package/dist/cli/command.d.ts

@@ -0,0 +1,8 @@
+import { type CliOutput } from "./run.js";
+export interface RunSoftureCommandOptions {
+    readonly argv: readonly string[];
+    readonly cwd: string;
+    readonly output?: CliOutput;
+}
+export declare function runSoftureCommand(options: RunSoftureCommandOptions): Promise<number>;
+//# sourceMappingURL=command.d.ts.map

package/dist/cli/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/cli/command.ts"],"names":[],"mappings":"AAKA,OAAO,EAAkE,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1G,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AASD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CA0B1F"}

package/dist/cli/command.js

@@ -0,0 +1,38 @@
+// 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 } from "./run.js";
+const APP_SCRIPT = { runner: "runMigrateCli", packageName: "@softure-ai/db" };
+const consoleOutput = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+export async function runSoftureCommand(options) {
+    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 });
+}
+//# sourceMappingURL=command.js.map

package/dist/cli/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/cli/command.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,oGAAoG;AACpG,gGAAgG;AAChG,gEAAgE;AAChE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAkB,MAAM,UAAU,CAAC;AAQ1G,MAAM,UAAU,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,WAAW,EAAE,gBAAgB,EAAE,CAAC;AAE9E,MAAM,aAAa,GAAc;IAC/B,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;IAChC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;CACrC,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAiC;IACvE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,aAAa,CAAC;IAC/C,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IACxC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,6BAA6B,OAAO,GAAG,CAAC,CAAC;QAC3G,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;QAClC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAC5B,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QAC1B,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;QACd,MAAM,CAAC,KAAK,CAAC,oBAAoB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAClD,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAC5B,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC;IAC9G,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,YAAY,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3C,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,OAAO,aAAa,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;AAC9F,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+export { runSoftureCommand, type RunSoftureCommandOptions } from "./command.js";
+export { EXIT_FAILED, EXIT_OK, EXIT_USAGE, MIGRATE_USAGE, runMigrateCli, type CliOutput, type RunMigrateCliOptions } from "./run.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,KAAK,SAAS,EAAE,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,4 @@
+// `@softure-ai/db/cli`: the `softure migrate` command for app scripts and container bundles.
+export { runSoftureCommand } from "./command.js";
+export { EXIT_FAILED, EXIT_OK, EXIT_USAGE, MIGRATE_USAGE, runMigrateCli } from "./run.js";
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,OAAO,EAAE,iBAAiB,EAAiC,MAAM,cAAc,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAA6C,MAAM,UAAU,CAAC"}

package/dist/cli/run.d.ts

@@ -0,0 +1,20 @@
+import type { SoftureConfig } from "@softure-ai/core";
+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 declare const EXIT_OK = 0;
+export declare const EXIT_FAILED = 1;
+export declare const EXIT_USAGE = 2;
+export declare const MIGRATE_USAGE = "Usage: softure migrate [options]\n\nApplies the SQL migrations of every enabled module, each in its own schema.\n\nOptions:\n  --plan                        show what would be applied (or adopted) and change nothing\n  --adopt <module>@<version>    record an existing schema as migrated, after comparing it\n  --migrations-dir <dir>        read module files from <dir>/<module id>/ (bundled runners)\n  --export-migrations <dir>     copy module files to <dir>/<module id>/ and exit (build stage)\n  --help                        show this help";
+/** Runs the command and returns the process exit code: 0 done, 1 failed, 2 usage error. */
+export declare function runMigrateCli(options: RunMigrateCliOptions): Promise<number>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAOtD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,SAAS,CAAC,CAAC;IAC7D,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AAED,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,eAAO,MAAM,aAAa,oiBASqB,CAAC;AAehD,2FAA2F;AAC3F,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CA0ClF"}

package/dist/cli/run.js

@@ -0,0 +1,155 @@
+// `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 { createDatabase } from "../client.js";
+import { adoptModule } from "../migrations/adopt.js";
+import { exportMigrations } from "../migrations/export.js";
+import { migrate, planMigrations } from "../migrations/migrator.js";
+import { describeProblem } from "../migrations/problems.js";
+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 = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+/** Runs the command and returns the process exit code: 0 done, 1 failed, 2 usage error. */
+export async function runMigrateCli(options) {
+    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;
+    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, input) {
+    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) {
+    let values;
+    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"].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, failure) {
+    failure.problems.forEach((problem) => output.error(describeProblem(problem)));
+    return EXIT_FAILED;
+}
+function formatStep(step) {
+    return `${step.module} ${String(step.version).padStart(4, "0")}_${step.name}.sql`;
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=run.js.map

package/dist/cli/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,42 @@
+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";
+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 declare function createDatabase(url: string, options?: CreateDatabaseOptions): Promise<DatabaseHandle>;
+/** Wraps an open PGlite instance (used by `createTestDatabase`). */
+export declare function createPgliteHandle(client: PGlite): Promise<DatabaseHandle & {
+    kind: "pglite";
+}>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAK/B,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,CAAC;AAClE,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,8DAA8D;AAC9D,MAAM,MAAM,QAAQ,GAAG,gBAAgB,GAAG,oBAAoB,CAAC;AAE/D;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEzF,MAAM,MAAM,cAAc,GACtB;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,gBAAgB,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,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,CAAC;AAEN,MAAM,WAAW,qBAAqB;IACpC,4FAA4F;IAC5F,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,cAAc,CAAC,CAmB9G;AAED,oEAAoE;AACpE,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,CAGrG"}

package/dist/client.js

@@ -0,0 +1,34 @@
+const PGLITE_PREFIX = "pglite://";
+const POSTGRES_PREFIXES = ["postgres://", "postgresql://"];
+/**
+ * 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, options = {}) {
+    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) {
+    const { drizzle } = await import("drizzle-orm/pglite");
+    return { kind: "pglite", db: drizzle({ client }), client, close: () => client.close() };
+}
+function describeScheme(url) {
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(url)?.[1];
+    return scheme === undefined ? "(none)" : `"${scheme}:"`;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAUA,MAAM,aAAa,GAAG,WAAW,CAAC;AAClC,MAAM,iBAAiB,GAAG,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;AAiC3D;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAW,EAAE,UAAiC,EAAE;IACnF,IAAI,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAClC,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QAChD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;QACxD,MAAM,MAAM,GAAG,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC;QACnE,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;QAC/D,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3C,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,2BAA2B,CAAC,CAAC;QAC9D,MAAM,IAAI,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,gBAAgB,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC;QAC5E,0FAA0F;QAC1F,oFAAoF;QACpF,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAClC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IAC5F,CAAC;IACD,MAAM,IAAI,KAAK,CACb,mDAAmD,cAAc,CAAC,GAAG,CAAC,oDAAoD,CAC3H,CAAC;AACJ,CAAC;AAED,oEAAoE;AACpE,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAc;IACrD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;IACvD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;AAC1F,CAAC;AAED,SAAS,cAAc,CAAC,GAAW;IACjC,MAAM,MAAM,GAAG,wBAAwB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACvD,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,MAAM,IAAI,CAAC;AAC1D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,SAAS,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,EACL,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,OAAO,EACP,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EACL,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC5F,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+// 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, } from "./client.js";
+export { closeSharedDatabases, getSharedDatabase } from "./shared.js";
+export { computeChecksum, readMigrationFiles } from "./migrations/files.js";
+export { describeProblem, } from "./migrations/problems.js";
+export { migrate, planMigrations, } from "./migrations/migrator.js";
+export { adoptModule } from "./migrations/adopt.js";
+export { exportMigrations } from "./migrations/export.js";
+export { checkExportedMigrations, } from "./migrations/exported.js";
+export { readJournal } from "./migrations/ledger.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,wGAAwG;AACxG,OAAO,EACL,cAAc,GAOf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAsB,MAAM,uBAAuB,CAAC;AAChG,OAAO,EACL,eAAe,GAKhB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,OAAO,EACP,cAAc,GAKf,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAA0C,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EACL,uBAAuB,GAGxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAyC,MAAM,wBAAwB,CAAC"}