@shivaedev/local-postgres 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.3.0 - 2026-10-17
+
+### Added
+
+- `POSTGRES_IMAGE` exports the pinned PostgreSQL image, so CI can pull it before `db:setup` starts the container.
+- `localPostgres(environment, { attempts, delayMillis })` sets how many readiness checks `startPostgres` makes after it starts the container and how long it waits between them. The defaults stay at 30 checks one second apart.
+
+### Fixed
+
+- PostgreSQL setup query errors no longer expose connection passwords from userinfo or query parameters through host or Docker client commands, while preserving diagnostics and the original error as `cause`.
+
+## 0.2.1 - 2026-10-16
+
+### Changed
+
+- Document local service preparation, application-owned database names and schemas, data-preservation priorities and test boundaries in the README, agent guidance, north star and roadmap. Publish `docs/` with the README while keeping agent guidance out of the package.
+- Build package JavaScript, declarations and source maps with TypeScript 7.
+
 ## 0.2.0 - 2026-10-04
 
 ### Changed

package/README.md

@@ -1,20 +1,121 @@
 # @shivaedev/local-postgres
 
-Prepare one shared local PostgreSQL service without replacing containers, deleting volumes or resetting data. The service uses PostgreSQL 18.6 on loopback port 55432, pinned to `postgres:18.6-alpine@sha256:77f585114c32fbca283dc835b0596f4e52b51b4c6662d7810b2f4084f60a1873`.
+Make development and integration tests share one persistent local PostgreSQL service. Repeat setup without rebuilding the database contents, and keep each application's database names and schema preparation in its own setup script.
 
-This Node 24+ package has no runtime dependencies. It uses a local Docker daemon when no service is available; an existing native service requires host `psql`. With Docker, the container provides `psql` when it is absent from the host.
+## Why you want this
+
+A setup command should make a machine ready to work without erasing the work already on it. Reimplementing PostgreSQL startup in every repository makes that promise harder to keep. This package gives a setup script one place to prepare the service and its databases:
 
 ```ts
 import { assertLocalDatabase, localPostgres, localServer } from "@shivaedev/local-postgres/localPostgres.ts";
 
 const development = `${localServer}/example_dev`;
 assertLocalDatabase(development, ["example_dev"]);
+localPostgres(process.env).prepareDatabases([development]);
+```
+
+The application chooses `example_dev`. Preparation can run again: the package's real PostgreSQL test inserts a row, repeats preparation and reads the same row back.
+
+## Using it
+
+### How to think about it
+
+There are three separate responsibilities:
+
+1. The **service** is PostgreSQL running on the local machine. This package prepares access to it.
+2. A **database** is an application-chosen name on that service. This package creates missing databases; the application explicitly permits their names.
+3. The **schema and data** belong to the application. Its setup script runs migrations, loads fixtures or seeds data after preparation.
+
+`localPostgres(environment)` returns three synchronous functions: `startPostgres`, `prepareDatabases` and `sql`. Use them in setup tooling. Use your application's database client and `@shivaedev/effect-sql` for persistence and migrations in an Effect application.
+
+### 1. Once per application: choose and validate the databases
+
+```ts
+import { assertLocalDatabase, localPostgres, localServer } from "@shivaedev/local-postgres/localPostgres.ts";
+
+const development = process.env.DATABASE_URL ?? `${localServer}/example_dev`;
+const tests = process.env.TEST_DATABASE_URL ?? `${localServer}/example_test`;
+
+assertLocalDatabase(development, ["example_dev"]);
+assertLocalDatabase(tests, ["example_test"]);
+
 const postgres = localPostgres(process.env);
-postgres.prepareDatabases([development]);
+postgres.prepareDatabases([development, tests]);
 ```
 
-`localPostgres(environment)` reads only `DOCKER_CONTEXT` and `DOCKER_HOST` from the supplied settings. Pass the actual process environment or both settings from the application's configuration service so remote Docker endpoints are rejected. Importing this package does not start a service.
+This is a complete preparation script for two application-owned databases. `assertLocalDatabase` checks the name against the list the caller supplies. It rejects a remote host, the wrong port, a different database name or any redirecting connection parameter: `host`, `hostaddr`, `port`, `dbname` or `service`. Preparation and SQL execution also reject remote database targets.
+
+Keep the explicit name checks even though the preparation functions check their destinations. The application's allowlist says which database it intends to touch; service preparation does not choose that policy for it.
+
+### 2. Once per feature: prepare its schema in application tooling
+
+After `prepareDatabases`, run the application's own schema or migration entry point. This package provides no schema model, migration ledger, fixture catalogue or seed convention. In this monorepo, `script/setup-database.ts` chooses the database names and loads test schemas; `@shivaedev/effect-sql` owns the SQL and migration APIs.
+
+### 3. In daily setup: prepare again and inspect with SQL
+
+```ts
+import { assertLocalDatabase, localPostgres, localServer } from "@shivaedev/local-postgres/localPostgres.ts";
+
+const database = `${localServer}/example_dev`;
+assertLocalDatabase(database, ["example_dev"]);
+
+const postgres = localPostgres(process.env);
+postgres.prepareDatabases([database]);
+console.log(postgres.sql(database, "SHOW server_version"));
+```
+
+The version query returns the string `18.6`. `sql` also accepts a `URL` and returns the command's trimmed text. URLs carrying the application's `schema` and `connection_limit` settings work for this query; those settings are removed before calling PostgreSQL's client.
+
+`startPostgres(connection)` prepares the service without choosing an application database to create. Its connection defaults to `localServer`. Prefer `prepareDatabases` when the setup script needs named databases as well.
+
+### API
+
+Import the setup API from `@shivaedev/local-postgres/localPostgres.ts`:
+
+| Export | Purpose |
+| --- | --- |
+| `localServer` | The base URL `postgresql://postgres:postgres@127.0.0.1:55432`. Append the application database name. |
+| `assertLocalDatabase(value: string, names: readonly string[]): URL` | Validate a local database URL against application-owned allowed names. |
+| `localPostgres(environment: DockerEnvironment, readiness?: ReadinessOptions)` | Create the setup functions using the Docker settings to validate. After starting the container, `startPostgres` checks readiness `attempts` times (default 30), waiting `delayMillis` between checks (default 1000). |
+| `prepareDatabases(values: readonly string[]): void` | Prepare the service and create absent databases. |
+| `startPostgres(connection?: string): void` | Prepare the service; the default connection is `localServer`. |
+| `sql(value: string \| URL, query: string): string` | Execute SQL through PostgreSQL's command-line client. |
+
+The last three functions are members of the object returned by `localPostgres`, not module-level exports. They throw on failure; they are synchronous Node functions rather than Effects.
+
+The package's module export pattern also exposes these lower-level functions:
+
+| Module | Exports |
+| --- | --- |
+| `@shivaedev/local-postgres/local-docker.ts` | `DockerEnvironment`, the type with optional `DOCKER_CONTEXT` and `DOCKER_HOST`; `docker(environment, args, options?)`, the local-endpoint-checked Docker command function. |
+| `@shivaedev/local-postgres/local-container.ts` | `startContainer(docker)`, the container-start function; `sqlInContainer(docker, url, args, options)`, the container SQL-client function. Both take a Docker command callback. |
+
+Use `localPostgres.ts` for application preparation. The lower-level functions describe the command paths it uses and take Node child-process options where shown.
+
+### Install and machine setup
+
+```sh
+pnpm add --save-dev @shivaedev/local-postgres
+```
+
+The package requires Node 24 or later and has no runtime dependencies. It needs host `psql` or a local Docker installation. SQL uses host `psql` when available and falls back to the container's client when the host executable is missing. Both clients receive the connection password through `PGPASSWORD`, outside the command line. Query failures retain PostgreSQL's diagnostics and the original error as `cause` without exposing the connection password.
+
+The shared baseline is PostgreSQL 18.6 on loopback port 55432. Docker preparation uses container and volume name `development-postgres`, loopback publication `127.0.0.1:55432:5432`, and this image:
+
+```text
+postgres:18.6-alpine@sha256:77f585114c32fbca283dc835b0596f4e52b51b4c6662d7810b2f4084f60a1873
+```
+
+A newly created container uses username and password `postgres`; connection URLs supply credentials for client commands. An existing service with a different version requires an explicit upgrade that preserves its data. Container preparation and container-client fallback also check the managed image; a successful host-`psql` version probe does not inspect that image.
+
+Pass the process's actual Docker settings to `localPostgres`, as `process.env` in the examples does. With `DOCKER_CONTEXT`, endpoint validation uses that context and ignores `DOCKER_HOST`; otherwise it validates `DOCKER_HOST` or the active context. Remote endpoints are rejected before a Docker operation. Docker subprocesses inherit the process environment. Supplying a different object does not configure those subprocesses.
 
-`prepareDatabases(urls)` starts or reuses the service, checks its version and creates missing databases. `startPostgres(connection)` only prepares the service. `sql(connection, query)` uses host `psql`, or the pinned container's client. Database connection settings come from the supplied URL, including credentials. A new container uses the documented local defaults and a persistent `development-postgres` volume; it is never automatically upgraded.
+### Limits
 
-`assertLocalDatabase(url, names)` permits only the supplied names on localhost or 127.0.0.1 port 55432. It rejects connection parameters that override the destination. Callers own their application-specific names, test isolation, schema initialization, migrations and seeds. This package does not select application databases or run migrations or seeds.
+- The service version, port, container name and volume name are fixed. Choose any upgrade and data-preservation procedure outside this package.
+- Commands block the calling thread. Keep them in development and test setup tooling.
+- Keep allowed names, schema changes, test isolation and cleanup in the application. Preparation is not a database reset.
+- A prepared database name has 1–63 lowercase letters, digits or underscores and starts with a letter. An allowlisted connection URL does not bypass this SQL-name constraint.
+- Scripted command tests cover container start/create, image-mismatch refusal, client selection, Docker context precedence and local endpoint variants. A lifecycle test simulates host-client absence and delayed container discovery, then uses real Docker and PostgreSQL to check readiness. Real service tests cover supplied container-client credentials, password-free failure diagnostics on both clients and data preservation across repeated preparation.
+- Rejection of an exact running PostgreSQL version mismatch still needs a test; image-mismatch command tests do not prove that check.
+- Concurrent creation of the same absent database is not covered by the package's tests. Prepare databases before parallel tests begin.

package/dist/{local-container.d.ts → server/local-container.d.ts}

@@ -1,4 +1,5 @@
 import type { ExecFileSyncOptionsWithStringEncoding } from "node:child_process";
+export declare const POSTGRES_IMAGE = "postgres:18.6-alpine@sha256:77f585114c32fbca283dc835b0596f4e52b51b4c6662d7810b2f4084f60a1873";
 type Docker = (args: readonly string[], options?: ExecFileSyncOptionsWithStringEncoding) => string;
 export declare function sqlInContainer(docker: Docker, url: URL, args: readonly string[], options: ExecFileSyncOptionsWithStringEncoding): string;
 export declare function startContainer(docker: Docker): void;

package/dist/server/local-container.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-container.d.ts","sourceRoot":"","sources":["../../src/server/local-container.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,oBAAoB,CAAC;AAGhF,eAAO,MAAM,cAAc,iGAAiG,CAAC;AAE7H,KAAK,MAAM,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,qCAAqC,KAAK,MAAM,CAAC;AAEnG,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,qCAAqC,UAuB/H;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,QA+B5C"}

package/dist/{local-container.js → server/local-container.js}

@@ -1,38 +1,53 @@
-const image = "postgres:18.6-alpine@sha256:77f585114c32fbca283dc835b0596f4e52b51b4c6662d7810b2f4084f60a1873";
-const container = "development-postgres";
+import { env } from "node:process";
+export const POSTGRES_IMAGE = "postgres:18.6-alpine@sha256:77f585114c32fbca283dc835b0596f4e52b51b4c6662d7810b2f4084f60a1873";
+const CONTAINER = "development-postgres";
 export function sqlInContainer(docker, url, args, options) {
     const id = docker(["ps", "--filter", "publish=55432", "--format", "{{.ID}}"], options).trim();
     if (!id || id.includes("\n")) {
         throw new Error("Install psql or start the shared PostgreSQL service with Docker.");
     }
-    if (docker(["inspect", "--format", "{{.Config.Image}}", id], options).trim() !== image) {
+    if (docker(["inspect", "--format", "{{.Config.Image}}", id], options).trim() !== POSTGRES_IMAGE) {
         throw new Error("The shared PostgreSQL image differs from the pinned baseline. Upgrade explicitly, preserving data.");
     }
+    // libpq treats + literally in URI passwords.
+    const password = new URLSearchParams(url.search.replaceAll("+", "%2B")).getAll("password").at(-1) ?? decodeURIComponent(url.password);
     const inside = new URL(url);
     inside.hostname = "127.0.0.1";
     inside.port = "5432";
-    return docker(["exec", id, "psql", ...args, "--dbname", inside.toString()], options).trim();
+    inside.password = "";
+    inside.searchParams.delete("password");
+    try {
+        return docker(["exec", "--env", "PGPASSWORD", id, "psql", ...args, "--dbname", inside.toString()], {
+            ...options,
+            env: { ...env, ...options.env, ...(password && { "PGPASSWORD": password }) },
+        }).trim();
+    }
+    catch (error) {
+        throw new Error(error instanceof Error && "stderr" in error ? String(error.stderr) : "PostgreSQL query failed.", { cause: error });
+    }
 }
 export function startContainer(docker) {
     docker(["info"]);
-    let existing = false;
+    let existing;
     try {
-        docker(["container", "inspect", container]);
+        docker(["container", "inspect", CONTAINER]);
         existing = true;
     }
-    catch { }
+    catch {
+        existing = false;
+    }
     if (existing) {
-        if (docker(["inspect", "--format", "{{.Config.Image}}", container]).trim() !== image) {
+        if (docker(["inspect", "--format", "{{.Config.Image}}", CONTAINER]).trim() !== POSTGRES_IMAGE) {
             throw new Error("The shared PostgreSQL container uses a different image. Preserve its volume and upgrade it explicitly.");
         }
-        docker(["start", container]);
+        docker(["start", CONTAINER]);
     }
     else {
         docker([
             "run",
             "--detach",
             "--name",
-            container,
+            CONTAINER,
             "--publish",
             "127.0.0.1:55432:5432",
             "--env",
@@ -41,7 +56,7 @@ export function startContainer(docker) {
             "POSTGRES_PASSWORD=postgres",
             "--mount",
             "type=volume,src=development-postgres,dst=/var/lib/postgresql",
-            image,
+            POSTGRES_IMAGE,
         ]);
     }
 }

package/dist/server/local-container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-container.js","sourceRoot":"","sources":["../../src/server/local-container.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAEnC,MAAM,CAAC,MAAM,cAAc,GAAG,8FAA8F,CAAC;AAC7H,MAAM,SAAS,GAAG,sBAAsB,CAAC;AAGzC,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,GAAQ,EAAE,IAAuB,EAAE,OAA8C;IAC/H,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9F,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,MAAM,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,mBAAmB,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,cAAc,EAAE,CAAC;QACjG,MAAM,IAAI,KAAK,CAAC,oGAAoG,CAAC,CAAC;IACvH,CAAC;IACD,6CAA6C;IAC7C,MAAM,QAAQ,GAAG,IAAI,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACtI,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,MAAM,CAAC,QAAQ,GAAG,WAAW,CAAC;IAC9B,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC;IACrB,MAAM,CAAC,QAAQ,GAAG,EAAE,CAAC;IACrB,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACvC,IAAI,CAAC;QACJ,OAAO,MAAM,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE;YAClG,GAAG,OAAO;YACV,GAAG,EAAE,EAAE,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,QAAQ,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,EAAE;SAC5E,CAAC,CAAC,IAAI,EAAE,CAAC;IACX,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,KAAK,YAAY,KAAK,IAAI,QAAQ,IAAI,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,0BAA0B,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACpI,CAAC;AACF,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAc;IAC5C,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACjB,IAAI,QAAiB,CAAC;IACtB,IAAI,CAAC;QACJ,MAAM,CAAC,CAAC,WAAW,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;QAC5C,QAAQ,GAAG,IAAI,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACR,QAAQ,GAAG,KAAK,CAAC;IAClB,CAAC;IACD,IAAI,QAAQ,EAAE,CAAC;QACd,IAAI,MAAM,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,mBAAmB,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,cAAc,EAAE,CAAC;YAC/F,MAAM,IAAI,KAAK,CAAC,wGAAwG,CAAC,CAAC;QAC3H,CAAC;QACD,MAAM,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;IAC9B,CAAC;SAAM,CAAC;QACP,MAAM,CAAC;YACN,KAAK;YACL,UAAU;YACV,QAAQ;YACR,SAAS;YACT,WAAW;YACX,sBAAsB;YACtB,OAAO;YACP,wBAAwB;YACxB,OAAO;YACP,4BAA4B;YAC5B,SAAS;YACT,8DAA8D;YAC9D,cAAc;SACd,CAAC,CAAC;IACJ,CAAC;AACF,CAAC"}

package/dist/{local-docker.d.ts → server/local-docker.d.ts}

@@ -1,7 +1,7 @@
 import { type ExecFileSyncOptionsWithStringEncoding } from "node:child_process";
 export type DockerEnvironment = Readonly<{
-    DOCKER_CONTEXT?: string | undefined;
-    DOCKER_HOST?: string | undefined;
+    "DOCKER_CONTEXT"?: string | undefined;
+    "DOCKER_HOST"?: string | undefined;
 }>;
 export declare function docker(environment: DockerEnvironment, args: readonly string[], options?: ExecFileSyncOptionsWithStringEncoding): string;
 //# sourceMappingURL=local-docker.d.ts.map

package/dist/server/local-docker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-docker.d.ts","sourceRoot":"","sources":["../../src/server/local-docker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,qCAAqC,EAAgB,MAAM,oBAAoB,CAAC;AAE9F,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC,CAAC;AAExH,wBAAgB,MAAM,CACrB,WAAW,EAAE,iBAAiB,EAC9B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,GAAE,qCAA4D,UAmBrE"}

package/dist/server/local-docker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-docker.js","sourceRoot":"","sources":["../../src/server/local-docker.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8C,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAI9F,MAAM,UAAU,MAAM,CACrB,WAA8B,EAC9B,IAAuB,EACvB,OAAO,GAA0C,EAAE,QAAQ,EAAE,MAAM,EAAE;IAErE,MAAM,OAAO,GAAG,WAAW,CAAC,cAAc,CAAC;IAC3C,MAAM,IAAI,GAAG,WAAW,CAAC,WAAW,CAAC;IACrC,MAAM,QAAQ,GACb,CAAC,CAAC,OAAO,IAAI,IAAI,CAAC;WACf,YAAY,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,4BAA4B,CAAC,EAAE;YAC1H,QAAQ,EAAE,MAAM;SAChB,CAAC,CAAC,IAAI,EAAE,CAAC;IACX,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC9B,IACC,CAAC,CACA,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;WACrF,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAC1F,EACA,CAAC;QACF,MAAM,IAAI,KAAK,CAAC,qFAAqF,CAAC,CAAC;IACxG,CAAC;IACD,OAAO,YAAY,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC"}

package/dist/{localPostgres.d.ts → server/localPostgres.d.ts}

@@ -1,7 +1,11 @@
 import { type DockerEnvironment } from "./local-docker.ts";
 export declare const localServer = "postgresql://postgres:postgres@127.0.0.1:55432";
 export declare function assertLocalDatabase(value: string, names: readonly string[]): import("url").URL;
-export declare function localPostgres(environment: DockerEnvironment): {
+export interface ReadinessOptions {
+    readonly attempts?: number;
+    readonly delayMillis?: number;
+}
+export declare function localPostgres(environment: DockerEnvironment, { attempts, delayMillis }?: ReadinessOptions): {
     prepareDatabases: (values: readonly string[]) => void;
     sql: (value: string | URL, query: string) => string;
     startPostgres: (connection?: string) => void;

package/dist/server/localPostgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localPostgres.d.ts","sourceRoot":"","sources":["../../src/server/localPostgres.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,iBAAiB,EAAU,MAAM,mBAAmB,CAAC;AAEnE,eAAO,MAAM,WAAW,mDAAmD,CAAC;AAE5E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,qBAY1E;AAQD,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,aAAa,CAAC,WAAW,EAAE,iBAAiB,EAAE,EAAE,QAAa,EAAE,WAAkB,EAAE,GAAE,gBAAqB;+BAwDvF,SAAS,MAAM,EAAE;iBApD/B,MAAM,GAAG,GAAG,SAAS,MAAM;;EAwE/C"}

package/dist/{localPostgres.js → server/localPostgres.js}

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { env } from "node:process";
 import { sqlInContainer, startContainer } from "./local-container.js";
 import { docker } from "./local-docker.js";
 export const localServer = "postgresql://postgres:postgres@127.0.0.1:55432";
@@ -13,11 +14,21 @@ export function assertLocalDatabase(value, names) {
     }
     return url;
 }
-export function localPostgres(environment) {
-    const localDocker = (args, options = { encoding: "utf8" }) => docker(environment, args, options);
+function clientEnvironment(url) {
+    // libpq treats + literally in URI passwords.
+    const password = new URLSearchParams(url.search.replaceAll("+", "%2B")).getAll("password").at(-1) ?? decodeURIComponent(url.password);
+    return { ...env, ...(password && { "PGPASSWORD": password }) };
+}
+export function localPostgres(environment, { attempts = 30, delayMillis = 1000 } = {}) {
+    function localDocker(args, options = { encoding: "utf8" }) {
+        return docker(environment, args, options);
+    }
     function sql(value, query) {
         const url = new URL(value);
         assertLocalDatabase(url.toString(), [url.pathname.slice(1)]);
+        const childEnvironment = clientEnvironment(url);
+        url.password = "";
+        url.searchParams.delete("password");
         for (const key of ["schema", "connection_limit", "pool_timeout", "pgbouncer"]) {
             url.searchParams.delete(key);
         }
@@ -25,15 +36,19 @@ export function localPostgres(environment) {
         if (!url.searchParams.has("connect_timeout")) {
             url.searchParams.set("connect_timeout", "3");
         }
-        const options = { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] };
+        const options = {
+            encoding: "utf8",
+            env: childEnvironment,
+            stdio: ["ignore", "pipe", "pipe"],
+        };
         try {
-            return execFileSync("psql", [...args, "--dbname", String(url)], options).trim();
+            return execFileSync("psql", [...args, "--dbname", url.toString()], options).trim();
         }
         catch (error) {
-            if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
-                throw new Error(error instanceof Error && "stderr" in error ? String(error.stderr) : "PostgreSQL query failed.");
+            if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+                return sqlInContainer(localDocker, url, args, options);
             }
-            return sqlInContainer(localDocker, url, args, options);
+            throw new Error(error instanceof Error && "stderr" in error ? String(error.stderr) : "PostgreSQL query failed.", { cause: error });
         }
     }
     function startPostgres(connection = localServer) {
@@ -46,13 +61,13 @@ export function localPostgres(environment) {
         }
         catch {
             startContainer(localDocker);
-            for (let attempt = 0; attempt < 30; attempt++) {
+            for (let attempt = 0; attempt < attempts; attempt += 1) {
                 try {
                     version = sql(server, "SHOW server_version");
                     break;
                 }
                 catch {
-                    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1000);
+                    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delayMillis);
                 }
             }
         }

package/dist/server/localPostgres.js.map

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

package/docs/north-star.md

@@ -0,0 +1,41 @@
+# North star
+
+## The problem
+
+Development and integration tests need PostgreSQL, but each repository has its own database names, schemas and test fixtures. Copying the whole setup script between repositories mixes those application choices with service management. A later shortcut in one copy can replace a container, lose a persistent volume or point a local setup command at a remote machine.
+
+Setup also runs more than once. The developer's useful state must survive another checkout, another dependency install and another test run. A mismatch is a reason to stop and inspect the machine, not a reason to rebuild its database service automatically.
+
+## The ideal
+
+There is one small utility for preparing the shared local service, and each application writes only its own choices. A caller chooses explicit database names, checks incoming URLs against those names, prepares absent databases, and then runs its own schema and seed work. The common utility handles reaching the service and PostgreSQL's command-line client.
+
+Repeated preparation preserves existing data. Locality checks come before a command can act on a database or Docker endpoint. Upgrades are explicit decisions with a data-preservation plan rather than recovery work hidden inside a readiness check.
+
+## What good looks like
+
+- A setup script names the databases it owns and validates configured URLs against those names.
+- A service mismatch fails clearly without destructive repair.
+- The application owns schemas, migrations, fixture loading, production guards and test cleanup. The package knows none of its domain tables or database naming conventions.
+- The common setup path stays visible: ordinary Node tools, PostgreSQL client commands and a fixed local baseline. Application runtime persistence goes through its database client and the framework's SQL path.
+- Tests distinguish real database preservation from inspection of generated commands. A test against an already-running PostgreSQL service cannot stand in for a test that starts Docker or exercises a missing client.
+
+## Trade-offs
+
+When these goals conflict, prefer existing data, then an explicit local destination, then application ownership, then a small setup utility.
+
+A fixed service baseline is less flexible than a configurable process manager. It makes one shared machine service easier to reason about and avoids changing the version as a side effect of setup. A machine that needs an upgrade requires a deliberate action outside preparation.
+
+Explicit application name checks add a line to a setup script. That line records which database the script is authorized to prepare; an environment URL alone cannot answer that question.
+
+Synchronous commands are a fit for setup tooling. They should not become an application request path or a second database abstraction. A need for runtime SQL belongs with the native Effect SQL client and repository packages.
+
+## What it deliberately leaves out
+
+- Remote or production database provisioning.
+- Automatic upgrades, container replacement, volume removal, database resets and test cleanup policy.
+- An application database catalogue, schema authoring, migrations and seeds.
+- Query composition, connection pooling, repository APIs or an Effect runtime owner.
+- A configurable multi-service process manager.
+
+The [package roadmap](./roadmap.md) owns implementation work and open decisions. The [framework roadmap](https://github.com/ShivaeDev/platform/blob/main/docs/framework/roadmap.md) owns composed database fixtures and host-level validation.

package/docs/roadmap.md

@@ -0,0 +1,24 @@
+# Roadmap
+
+This file owns local service preparation, its command paths and package API questions. The [framework roadmap](https://github.com/ShivaeDev/platform/blob/main/docs/framework/roadmap.md) owns composed repository and migration fixtures, application adoption and host-level validation. Their completion status is recorded there rather than repeated here.
+
+## Built
+
+- [x] The main setup module exposes an explicit local server URL, application name validation, service preparation, missing-database preparation and SQL execution.
+- [x] Tests reject a remote database host, the wrong port, an unapproved database name and each redirecting query parameter (`host`, `hostaddr`, `port`, `dbname` and `service`). Invalid database identifiers are rejected before preparation. All three setup functions reject remote database targets before connecting.
+- [x] A real PostgreSQL test retains an inserted row across repeated preparation and checks PostgreSQL 18.6, including queries whose URLs carry `schema` and `connection_limit` settings.
+- [x] Scripted container tests cover daemon failures, starting an existing pinned container, creating a missing container with persistent storage and loopback publication, refusing image mismatches without replacement, and refusing client selection when discovery finds zero or multiple containers.
+- [x] Scripted Docker tests cover active and explicit context selection, context precedence over `DOCKER_HOST`, remote endpoint refusal, and local Unix socket, Windows pipe and loopback TCP endpoints.
+- [x] The lifecycle test simulates missing host `psql` and delayed container discovery, then checks readiness through the real Docker client and PostgreSQL service. It scripts container startup rather than starting or creating a real container.
+- [x] Real PostgreSQL tests check supplied container-client credentials and failure diagnostics on both host and Docker clients, including password-free original errors retained as causes.
+- [x] The installed consumer fixture checks the main module's exports and types.
+
+## Next
+
+- [ ] Add a test for rejection of an exact running PostgreSQL version mismatch. Scripted image-mismatch checks do not prove this service-version check.
+- [ ] Establish whether parallel setup needs coordinated creation of an absent database; keep application test startup ordered until there is evidence for another contract.
+
+## Open questions
+
+- Should `localPostgres(environment)` configure the environment of its Docker subprocesses, or only validate it? The implementation validates the supplied settings while Docker commands inherit the process environment. The README therefore asks callers to pass the actual process settings. Selecting a different context through the argument would need an explicit API decision and tests.
+- Should `docker`, `startContainer` and `sqlInContainer` be supported standalone public APIs? The package's wildcard module exports expose them, while the usage examples and installed consumer fixture use `localPostgres.ts`. Narrowing the exports would change the public API; supporting the helpers would need direct consumer and command-path tests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/local-postgres",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Repeatable local PostgreSQL preparation with one shared persistent service",
   "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/local-postgres#readme",
   "bugs": {
@@ -15,34 +15,38 @@
   "sideEffects": false,
   "type": "module",
   "imports": {
-    "#test/*": "./test/*",
+    "#test/*": "./src/test-support/*",
     "#*.ts": {
-      "source": "./src/*.ts",
-      "types": "./dist/*.d.ts",
-      "default": "./dist/*.js"
+      "source": "./src/server/*.ts",
+      "types": "./dist/server/*.d.ts",
+      "default": "./dist/server/*.js"
     }
   },
   "exports": {
     "./*.ts": {
-      "types": "./dist/*.d.ts",
-      "source": "./src/*.ts",
-      "import": "./dist/*.js",
-      "default": "./dist/*.js"
+      "types": "./dist/server/*.d.ts",
+      "source": "./src/server/*.ts",
+      "import": "./dist/server/*.js",
+      "default": "./dist/server/*.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/test-support",
+    "docs",
     "CHANGELOG.md",
     "README.md"
   ],
   "devDependencies": {
-    "@shivaedev/quality": "0.9.0",
-    "@types/node": "24.10.1",
+    "@shivaedev/quality": "0.23.0",
+    "@types/node": "24.19.2",
     "@typescript/native": "npm:typescript@7.0.2",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "vitest": "4.1.9"
+    "vitest": "5.0.3"
   },
   "engines": {
     "node": ">=24"
@@ -52,7 +56,7 @@
     "provenance": true
   },
   "scripts": {
-    "build": "node --eval \"import('node:fs').then(({ rmSync }) => rmSync('dist', { force: true, recursive: true }))\" && tsc6 --project tsconfig.build.json",
+    "build": "node --eval \"import('node:fs').then(({ rmSync }) => rmSync('dist', { force: true, recursive: true }))\" && tsc --project tsconfig.build.json",
     "ready": "pnpm typecheck && pnpm test && pnpm build",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"

package/src/{local-container.ts → server/local-container.ts}

@@ -1,7 +1,8 @@
 import type { ExecFileSyncOptionsWithStringEncoding } from "node:child_process";
+import { env } from "node:process";
 
-const image = "postgres:18.6-alpine@sha256:77f585114c32fbca283dc835b0596f4e52b51b4c6662d7810b2f4084f60a1873";
-const container = "development-postgres";
+export const POSTGRES_IMAGE = "postgres:18.6-alpine@sha256:77f585114c32fbca283dc835b0596f4e52b51b4c6662d7810b2f4084f60a1873";
+const CONTAINER = "development-postgres";
 type Docker = (args: readonly string[], options?: ExecFileSyncOptionsWithStringEncoding) => string;
 
 export function sqlInContainer(docker: Docker, url: URL, args: readonly string[], options: ExecFileSyncOptionsWithStringEncoding) {
@@ -9,33 +10,46 @@ export function sqlInContainer(docker: Docker, url: URL, args: readonly string[]
 	if (!id || id.includes("\n")) {
 		throw new Error("Install psql or start the shared PostgreSQL service with Docker.");
 	}
-	if (docker(["inspect", "--format", "{{.Config.Image}}", id], options).trim() !== image) {
+	if (docker(["inspect", "--format", "{{.Config.Image}}", id], options).trim() !== POSTGRES_IMAGE) {
 		throw new Error("The shared PostgreSQL image differs from the pinned baseline. Upgrade explicitly, preserving data.");
 	}
+	// libpq treats + literally in URI passwords.
+	const password = new URLSearchParams(url.search.replaceAll("+", "%2B")).getAll("password").at(-1) ?? decodeURIComponent(url.password);
 	const inside = new URL(url);
 	inside.hostname = "127.0.0.1";
 	inside.port = "5432";
-	return docker(["exec", id, "psql", ...args, "--dbname", inside.toString()], options).trim();
+	inside.password = "";
+	inside.searchParams.delete("password");
+	try {
+		return docker(["exec", "--env", "PGPASSWORD", id, "psql", ...args, "--dbname", inside.toString()], {
+			...options,
+			env: { ...env, ...options.env, ...(password && { "PGPASSWORD": password }) },
+		}).trim();
+	} catch (error) {
+		throw new Error(error instanceof Error && "stderr" in error ? String(error.stderr) : "PostgreSQL query failed.", { cause: error });
+	}
 }
 
 export function startContainer(docker: Docker) {
 	docker(["info"]);
-	let existing = false;
+	let existing: boolean;
 	try {
-		docker(["container", "inspect", container]);
+		docker(["container", "inspect", CONTAINER]);
 		existing = true;
-	} catch {}
+	} catch {
+		existing = false;
+	}
 	if (existing) {
-		if (docker(["inspect", "--format", "{{.Config.Image}}", container]).trim() !== image) {
+		if (docker(["inspect", "--format", "{{.Config.Image}}", CONTAINER]).trim() !== POSTGRES_IMAGE) {
 			throw new Error("The shared PostgreSQL container uses a different image. Preserve its volume and upgrade it explicitly.");
 		}
-		docker(["start", container]);
+		docker(["start", CONTAINER]);
 	} else {
 		docker([
 			"run",
 			"--detach",
 			"--name",
-			container,
+			CONTAINER,
 			"--publish",
 			"127.0.0.1:55432:5432",
 			"--env",
@@ -44,7 +58,7 @@ export function startContainer(docker: Docker) {
 			"POSTGRES_PASSWORD=postgres",
 			"--mount",
 			"type=volume,src=development-postgres,dst=/var/lib/postgresql",
-			image,
+			POSTGRES_IMAGE,
 		]);
 	}
 }

package/src/{local-docker.ts → server/local-docker.ts}

@@ -1,6 +1,6 @@
 import { type ExecFileSyncOptionsWithStringEncoding, execFileSync } from "node:child_process";
 
-export type DockerEnvironment = Readonly<{ DOCKER_CONTEXT?: string | undefined; DOCKER_HOST?: string | undefined }>;
+export type DockerEnvironment = Readonly<{ "DOCKER_CONTEXT"?: string | undefined; "DOCKER_HOST"?: string | undefined }>;
 
 export function docker(
 	environment: DockerEnvironment,

package/src/{localPostgres.ts → server/localPostgres.ts}

@@ -1,4 +1,5 @@
 import { type ExecFileSyncOptionsWithStringEncoding, execFileSync } from "node:child_process";
+import { env } from "node:process";
 import { sqlInContainer, startContainer } from "./local-container.ts";
 import { type DockerEnvironment, docker } from "./local-docker.ts";
 
@@ -18,12 +19,27 @@ export function assertLocalDatabase(value: string, names: readonly string[]) {
 	return url;
 }
 
-export function localPostgres(environment: DockerEnvironment) {
-	const localDocker = (args: readonly string[], options: ExecFileSyncOptionsWithStringEncoding = { encoding: "utf8" }) =>
-		docker(environment, args, options);
+function clientEnvironment(url: URL) {
+	// libpq treats + literally in URI passwords.
+	const password = new URLSearchParams(url.search.replaceAll("+", "%2B")).getAll("password").at(-1) ?? decodeURIComponent(url.password);
+	return { ...env, ...(password && { "PGPASSWORD": password }) };
+}
+
+export interface ReadinessOptions {
+	readonly attempts?: number;
+	readonly delayMillis?: number;
+}
+
+export function localPostgres(environment: DockerEnvironment, { attempts = 30, delayMillis = 1000 }: ReadinessOptions = {}) {
+	function localDocker(args: readonly string[], options: ExecFileSyncOptionsWithStringEncoding = { encoding: "utf8" }) {
+		return docker(environment, args, options);
+	}
 	function sql(value: string | URL, query: string) {
 		const url = new URL(value);
 		assertLocalDatabase(url.toString(), [url.pathname.slice(1)]);
+		const childEnvironment = clientEnvironment(url);
+		url.password = "";
+		url.searchParams.delete("password");
 		for (const key of ["schema", "connection_limit", "pool_timeout", "pgbouncer"]) {
 			url.searchParams.delete(key);
 		}
@@ -32,14 +48,18 @@ export function localPostgres(environment: DockerEnvironment) {
 		if (!url.searchParams.has("connect_timeout")) {
 			url.searchParams.set("connect_timeout", "3");
 		}
-		const options = { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] } satisfies ExecFileSyncOptionsWithStringEncoding;
+		const options = {
+			encoding: "utf8",
+			env: childEnvironment,
+			stdio: ["ignore", "pipe", "pipe"],
+		} satisfies ExecFileSyncOptionsWithStringEncoding;
 		try {
-			return execFileSync("psql", [...args, "--dbname", String(url)], options).trim();
+			return execFileSync("psql", [...args, "--dbname", url.toString()], options).trim();
 		} catch (error) {
-			if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
-				throw new Error(error instanceof Error && "stderr" in error ? String(error.stderr) : "PostgreSQL query failed.");
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+				return sqlInContainer(localDocker, url, args, options);
 			}
-			return sqlInContainer(localDocker, url, args, options);
+			throw new Error(error instanceof Error && "stderr" in error ? String(error.stderr) : "PostgreSQL query failed.", { cause: error });
 		}
 	}
 
@@ -52,12 +72,12 @@ export function localPostgres(environment: DockerEnvironment) {
 			version = sql(server, "SHOW server_version");
 		} catch {
 			startContainer(localDocker);
-			for (let attempt = 0; attempt < 30; attempt++) {
+			for (let attempt = 0; attempt < attempts; attempt += 1) {
 				try {
 					version = sql(server, "SHOW server_version");
 					break;
 				} catch {
-					Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1000);
+					Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delayMillis);
 				}
 			}
 		}

package/dist/local-container.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"local-container.d.ts","sourceRoot":"","sources":["../src/local-container.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,oBAAoB,CAAC;AAIhF,KAAK,MAAM,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,qCAAqC,KAAK,MAAM,CAAC;AAEnG,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,qCAAqC,UAY/H;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,QA6B5C"}

package/dist/local-container.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"local-container.js","sourceRoot":"","sources":["../src/local-container.ts"],"names":[],"mappings":"AAEA,MAAM,KAAK,GAAG,8FAA8F,CAAC;AAC7G,MAAM,SAAS,GAAG,sBAAsB,CAAC;AAGzC,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,GAAQ,EAAE,IAAuB,EAAE,OAA8C;IAC/H,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9F,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,MAAM,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,mBAAmB,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC;QACxF,MAAM,IAAI,KAAK,CAAC,oGAAoG,CAAC,CAAC;IACvH,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,MAAM,CAAC,QAAQ,GAAG,WAAW,CAAC;IAC9B,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC;IACrB,OAAO,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;AAC7F,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAc;IAC5C,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACjB,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,CAAC;QACJ,MAAM,CAAC,CAAC,WAAW,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;QAC5C,QAAQ,GAAG,IAAI,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC,CAAA,CAAC;IACV,IAAI,QAAQ,EAAE,CAAC;QACd,IAAI,MAAM,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,mBAAmB,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC;YACtF,MAAM,IAAI,KAAK,CAAC,wGAAwG,CAAC,CAAC;QAC3H,CAAC;QACD,MAAM,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;IAC9B,CAAC;SAAM,CAAC;QACP,MAAM,CAAC;YACN,KAAK;YACL,UAAU;YACV,QAAQ;YACR,SAAS;YACT,WAAW;YACX,sBAAsB;YACtB,OAAO;YACP,wBAAwB;YACxB,OAAO;YACP,4BAA4B;YAC5B,SAAS;YACT,8DAA8D;YAC9D,KAAK;SACL,CAAC,CAAC;IACJ,CAAC;AACF,CAAC"}

package/dist/local-docker.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"local-docker.d.ts","sourceRoot":"","sources":["../src/local-docker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,qCAAqC,EAAgB,MAAM,oBAAoB,CAAC;AAE9F,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IAAE,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC,CAAC;AAEpH,wBAAgB,MAAM,CACrB,WAAW,EAAE,iBAAiB,EAC9B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,GAAE,qCAA4D,UAmBrE"}

package/dist/local-docker.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"local-docker.js","sourceRoot":"","sources":["../src/local-docker.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8C,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAI9F,MAAM,UAAU,MAAM,CACrB,WAA8B,EAC9B,IAAuB,EACvB,UAAiD,EAAE,QAAQ,EAAE,MAAM,EAAE;IAErE,MAAM,OAAO,GAAG,WAAW,CAAC,cAAc,CAAC;IAC3C,MAAM,IAAI,GAAG,WAAW,CAAC,WAAW,CAAC;IACrC,MAAM,QAAQ,GACb,CAAC,CAAC,OAAO,IAAI,IAAI,CAAC;WACf,YAAY,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,4BAA4B,CAAC,EAAE;YAC1H,QAAQ,EAAE,MAAM;SAChB,CAAC,CAAC,IAAI,EAAE,CAAC;IACX,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC9B,IACC,CAAC,CACA,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;WACrF,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAC1F,EACA,CAAC;QACF,MAAM,IAAI,KAAK,CAAC,qFAAqF,CAAC,CAAC;IACxG,CAAC;IACD,OAAO,YAAY,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC"}

package/dist/localPostgres.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"localPostgres.d.ts","sourceRoot":"","sources":["../src/localPostgres.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,iBAAiB,EAAU,MAAM,mBAAmB,CAAC;AAEnE,eAAO,MAAM,WAAW,mDAAmD,CAAC;AAE5E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,qBAY1E;AAED,wBAAgB,aAAa,CAAC,WAAW,EAAE,iBAAiB;+BAgDzB,SAAS,MAAM,EAAE;iBA7C/B,MAAM,GAAG,GAAG,SAAS,MAAM;;EAiE/C"}

package/dist/localPostgres.js.map

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