@shivaedev/local-postgres 0.0.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.1 - 2026-10-04
+
+### Changed
+
+- Imports that leave their folder go through `#` aliases declared in the `imports` field of `package.json`: `#*.ts` resolves to `src` under the `source` condition and to `dist` otherwise, and `#test/*` names a test file. The published modules and declarations name the package's own files through these aliases.
+
+- Build with the `@shivaedev/quality` tsconfig presets, which target ESNext and allow only erasable TypeScript syntax.
+
+- Type-check with TypeScript 7 only. TypeScript 6 still builds the package.
+
+- Lint and format with the `@shivaedev/quality` Biome preset through `quality lint` at the repository root, which replaces the package's `check` script.
+
+- Run tests through the `@shivaedev/quality` Vitest projects, which take a test's environment from its file name. Type tests are named `*.typecheck.test.ts`.
+
+- Keep `package.json` in sort-package-json key order, checked by `quality lint`.
+
+## 0.1.0
+
+- Prepare one persistent local PostgreSQL 18.6 service and create missing databases without resetting existing data.
+- Validate loopback database targets and local Docker endpoints; use host or container PostgreSQL client tools.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShivaeDev
+
+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,20 @@
 # @shivaedev/local-postgres
 
-Placeholder that reserves the package name. The first real release follows.
+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`.
+
+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.
+
+```ts
+import { assertLocalDatabase, localPostgres, localServer } from "@shivaedev/local-postgres";
+
+const development = `${localServer}/example_dev`;
+assertLocalDatabase(development, ["example_dev"]);
+const postgres = localPostgres(process.env);
+postgres.prepareDatabases([development]);
+```
+
+`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.
+
+`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.
+
+`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.

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+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): {
+    prepareDatabases: (values: readonly string[]) => void;
+    sql: (value: string | URL, query: string) => string;
+    startPostgres: (connection?: string) => void;
+};
+//# 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,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/index.js

@@ -0,0 +1,84 @@
+import { execFileSync } from "node:child_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";
+export function assertLocalDatabase(value, names) {
+    const url = new URL(value);
+    const name = url.pathname.slice(1);
+    if (!(["postgres:", "postgresql:"].includes(url.protocol) && ["localhost", "127.0.0.1"].includes(url.hostname))
+        || url.port !== "55432"
+        || ["host", "hostaddr", "port", "dbname", "service"].some((key) => url.searchParams.has(key))
+        || !names.includes(name)) {
+        throw new Error(`Use a local database on 127.0.0.1:55432 named ${names.join(" or ")}.`);
+    }
+    return url;
+}
+export function localPostgres(environment) {
+    const localDocker = (args, options = { encoding: "utf8" }) => docker(environment, args, options);
+    function sql(value, query) {
+        const url = new URL(value);
+        assertLocalDatabase(url.toString(), [url.pathname.slice(1)]);
+        for (const key of ["schema", "connection_limit", "pool_timeout", "pgbouncer"]) {
+            url.searchParams.delete(key);
+        }
+        const args = ["-X", "--set", "ON_ERROR_STOP=1", "-At", "-c", query];
+        if (!url.searchParams.has("connect_timeout")) {
+            url.searchParams.set("connect_timeout", "3");
+        }
+        const options = { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] };
+        try {
+            return execFileSync("psql", [...args, "--dbname", String(url)], 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.");
+            }
+            return sqlInContainer(localDocker, url, args, options);
+        }
+    }
+    function startPostgres(connection = localServer) {
+        const server = new URL(connection);
+        server.pathname = "/postgres";
+        assertLocalDatabase(server.toString(), ["postgres"]);
+        let version;
+        try {
+            version = sql(server, "SHOW server_version");
+        }
+        catch {
+            startContainer(localDocker);
+            for (let attempt = 0; attempt < 30; attempt++) {
+                try {
+                    version = sql(server, "SHOW server_version");
+                    break;
+                }
+                catch {
+                    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1000);
+                }
+            }
+        }
+        if (version !== "18.6") {
+            throw new Error("Expected local PostgreSQL 18.6. Check the existing service; setup never removes containers or data.");
+        }
+    }
+    function prepareDatabases(values) {
+        for (const value of values) {
+            const name = new URL(value).pathname.slice(1);
+            assertLocalDatabase(value, [name]);
+            if (!/^[a-z][a-z0-9_]{0,62}$/u.test(name)) {
+                throw new Error("Invalid local database name.");
+            }
+        }
+        startPostgres(values[0]);
+        for (const value of values) {
+            const url = new URL(value);
+            const name = url.pathname.slice(1);
+            const server = new URL(url);
+            server.pathname = "/postgres";
+            if (!sql(server, `SELECT 1 FROM pg_database WHERE datname = '${name}'`)) {
+                sql(server, `CREATE DATABASE "${name}"`);
+            }
+        }
+    }
+    return { prepareDatabases, sql, startPostgres };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/local-container.d.ts

@@ -0,0 +1,6 @@
+import type { ExecFileSyncOptionsWithStringEncoding } from "node:child_process";
+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;
+export {};
+//# sourceMappingURL=local-container.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,48 @@
+const 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) {
+        throw new Error("The shared PostgreSQL image differs from the pinned baseline. Upgrade explicitly, preserving data.");
+    }
+    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();
+}
+export function startContainer(docker) {
+    docker(["info"]);
+    let existing = false;
+    try {
+        docker(["container", "inspect", container]);
+        existing = true;
+    }
+    catch { }
+    if (existing) {
+        if (docker(["inspect", "--format", "{{.Config.Image}}", container]).trim() !== image) {
+            throw new Error("The shared PostgreSQL container uses a different image. Preserve its volume and upgrade it explicitly.");
+        }
+        docker(["start", container]);
+    }
+    else {
+        docker([
+            "run",
+            "--detach",
+            "--name",
+            container,
+            "--publish",
+            "127.0.0.1:55432:5432",
+            "--env",
+            "POSTGRES_USER=postgres",
+            "--env",
+            "POSTGRES_PASSWORD=postgres",
+            "--mount",
+            "type=volume,src=development-postgres,dst=/var/lib/postgresql",
+            image,
+        ]);
+    }
+}
+//# sourceMappingURL=local-container.js.map

package/dist/local-container.js.map

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,7 @@
+import { type ExecFileSyncOptionsWithStringEncoding } from "node:child_process";
+export type DockerEnvironment = Readonly<{
+    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/local-docker.d.ts.map

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,16 @@
+import { execFileSync } from "node:child_process";
+export function docker(environment, args, options = { encoding: "utf8" }) {
+    const context = environment.DOCKER_CONTEXT;
+    const host = environment.DOCKER_HOST;
+    const endpoint = (!context && host)
+        || execFileSync("docker", ["context", "inspect", ...(context ? [context] : []), "--format", "{{.Endpoints.docker.Host}}"], {
+            encoding: "utf8",
+        }).trim();
+    const url = new URL(endpoint);
+    if (!((["unix:", "npipe:"].includes(url.protocol) && ["", "localhost"].includes(url.hostname))
+        || (url.protocol === "tcp:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))) {
+        throw new Error("Local database setup requires a local Docker endpoint; remote contexts are refused.");
+    }
+    return execFileSync("docker", args, options);
+}
+//# sourceMappingURL=local-docker.js.map

package/dist/local-docker.js.map

@@ -0,0 +1 @@
+{"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/package.json

@@ -1,10 +1,60 @@
 {
   "name": "@shivaedev/local-postgres",
-  "version": "0.0.0",
-  "description": "Placeholder that reserves the package name; the first real release follows.",
-  "license": "MIT",
+  "version": "0.1.1",
+  "description": "Repeatable local PostgreSQL preparation with one shared persistent service",
+  "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/local-postgres#readme",
+  "bugs": {
+    "url": "https://github.com/ShivaeDev/platform/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ShivaeDev/platform.git"
+    "url": "git+https://github.com/ShivaeDev/platform.git",
+    "directory": "packages/local-postgres"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "imports": {
+    "#test/*": "./test/*",
+    "#*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "source": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@shivaedev/quality": "0.7.3",
+    "@types/node": "24.10.1",
+    "@typescript/native": "npm:typescript@7.0.2",
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "vitest": "4.1.9"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node --eval \"import('node:fs').then(({ rmSync }) => rmSync('dist', { force: true, recursive: true }))\" && tsc6 --project tsconfig.build.json",
+    "ready": "pnpm typecheck && pnpm test && pnpm build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
 }

package/src/index.ts

@@ -0,0 +1,89 @@
+import { type ExecFileSyncOptionsWithStringEncoding, execFileSync } from "node:child_process";
+import { sqlInContainer, startContainer } from "./local-container.ts";
+import { type DockerEnvironment, docker } from "./local-docker.ts";
+
+export const localServer = "postgresql://postgres:postgres@127.0.0.1:55432";
+
+export function assertLocalDatabase(value: string, names: readonly string[]) {
+	const url = new URL(value);
+	const name = url.pathname.slice(1);
+	if (
+		!(["postgres:", "postgresql:"].includes(url.protocol) && ["localhost", "127.0.0.1"].includes(url.hostname))
+		|| url.port !== "55432"
+		|| ["host", "hostaddr", "port", "dbname", "service"].some((key) => url.searchParams.has(key))
+		|| !names.includes(name)
+	) {
+		throw new Error(`Use a local database on 127.0.0.1:55432 named ${names.join(" or ")}.`);
+	}
+	return url;
+}
+
+export function localPostgres(environment: DockerEnvironment) {
+	const localDocker = (args: readonly string[], options: ExecFileSyncOptionsWithStringEncoding = { encoding: "utf8" }) =>
+		docker(environment, args, options);
+	function sql(value: string | URL, query: string) {
+		const url = new URL(value);
+		assertLocalDatabase(url.toString(), [url.pathname.slice(1)]);
+		for (const key of ["schema", "connection_limit", "pool_timeout", "pgbouncer"]) {
+			url.searchParams.delete(key);
+		}
+
+		const args = ["-X", "--set", "ON_ERROR_STOP=1", "-At", "-c", query];
+		if (!url.searchParams.has("connect_timeout")) {
+			url.searchParams.set("connect_timeout", "3");
+		}
+		const options = { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] } satisfies ExecFileSyncOptionsWithStringEncoding;
+		try {
+			return execFileSync("psql", [...args, "--dbname", String(url)], 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.");
+			}
+			return sqlInContainer(localDocker, url, args, options);
+		}
+	}
+
+	function startPostgres(connection = localServer) {
+		const server = new URL(connection);
+		server.pathname = "/postgres";
+		assertLocalDatabase(server.toString(), ["postgres"]);
+		let version: string | undefined;
+		try {
+			version = sql(server, "SHOW server_version");
+		} catch {
+			startContainer(localDocker);
+			for (let attempt = 0; attempt < 30; attempt++) {
+				try {
+					version = sql(server, "SHOW server_version");
+					break;
+				} catch {
+					Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1000);
+				}
+			}
+		}
+		if (version !== "18.6") {
+			throw new Error("Expected local PostgreSQL 18.6. Check the existing service; setup never removes containers or data.");
+		}
+	}
+
+	function prepareDatabases(values: readonly string[]) {
+		for (const value of values) {
+			const name = new URL(value).pathname.slice(1);
+			assertLocalDatabase(value, [name]);
+			if (!/^[a-z][a-z0-9_]{0,62}$/u.test(name)) {
+				throw new Error("Invalid local database name.");
+			}
+		}
+		startPostgres(values[0]);
+		for (const value of values) {
+			const url = new URL(value);
+			const name = url.pathname.slice(1);
+			const server = new URL(url);
+			server.pathname = "/postgres";
+			if (!sql(server, `SELECT 1 FROM pg_database WHERE datname = '${name}'`)) {
+				sql(server, `CREATE DATABASE "${name}"`);
+			}
+		}
+	}
+	return { prepareDatabases, sql, startPostgres };
+}

package/src/local-container.ts

@@ -0,0 +1,50 @@
+import type { ExecFileSyncOptionsWithStringEncoding } from "node:child_process";
+
+const 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) {
+	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) {
+		throw new Error("The shared PostgreSQL image differs from the pinned baseline. Upgrade explicitly, preserving data.");
+	}
+	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();
+}
+
+export function startContainer(docker: Docker) {
+	docker(["info"]);
+	let existing = false;
+	try {
+		docker(["container", "inspect", container]);
+		existing = true;
+	} catch {}
+	if (existing) {
+		if (docker(["inspect", "--format", "{{.Config.Image}}", container]).trim() !== image) {
+			throw new Error("The shared PostgreSQL container uses a different image. Preserve its volume and upgrade it explicitly.");
+		}
+		docker(["start", container]);
+	} else {
+		docker([
+			"run",
+			"--detach",
+			"--name",
+			container,
+			"--publish",
+			"127.0.0.1:55432:5432",
+			"--env",
+			"POSTGRES_USER=postgres",
+			"--env",
+			"POSTGRES_PASSWORD=postgres",
+			"--mount",
+			"type=volume,src=development-postgres,dst=/var/lib/postgresql",
+			image,
+		]);
+	}
+}

package/src/local-docker.ts

@@ -0,0 +1,27 @@
+import { type ExecFileSyncOptionsWithStringEncoding, execFileSync } from "node:child_process";
+
+export type DockerEnvironment = Readonly<{ DOCKER_CONTEXT?: string | undefined; DOCKER_HOST?: string | undefined }>;
+
+export function docker(
+	environment: DockerEnvironment,
+	args: readonly string[],
+	options: ExecFileSyncOptionsWithStringEncoding = { encoding: "utf8" },
+) {
+	const context = environment.DOCKER_CONTEXT;
+	const host = environment.DOCKER_HOST;
+	const endpoint =
+		(!context && host)
+		|| execFileSync("docker", ["context", "inspect", ...(context ? [context] : []), "--format", "{{.Endpoints.docker.Host}}"], {
+			encoding: "utf8",
+		}).trim();
+	const url = new URL(endpoint);
+	if (
+		!(
+			(["unix:", "npipe:"].includes(url.protocol) && ["", "localhost"].includes(url.hostname))
+			|| (url.protocol === "tcp:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))
+		)
+	) {
+		throw new Error("Local database setup requires a local Docker endpoint; remote contexts are refused.");
+	}
+	return execFileSync("docker", args, options);
+}

package/login.log

@@ -1,26 +0,0 @@
-^D
-https://www.npmjs.com/login?next=/login/cli/534beaea-3e9d-4402-a0fd-8783af95c2f8
-
-▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
-█ ▄▄▄▄▄ █   █▄███▀▄▀▀▄█▀▄█▀█▄██ ▄▄▄▄▄ █
-█ █   █ █ ▀▄ █▄▀  ▄█▀▄▄█ █▀▄ ██ █   █ █
-█ █▄▄▄█ █▀██▀▀  ▀▄▀█▀ ██▄██▄▄▄█ █▄▄▄█ █
-█▄▄▄▄▄▄▄█▄▀▄█ █ █▄▀ █ ▀▄▀ █ ▀ █▄▄▄▄▄▄▄█
-█  ▀█▄▄▄███▀▄▀▄▄▄▄ ▄▄▄ █▀▄█▀  ██▄▀▄  ▄█
-█▄▄█▀█ ▄ ▄▄▄ ▄ ▄ ▀ █▀▀ █▄██▄ █▄▀▀  ▀▄▀█
-██ ██▄█▄▄  ▀█▄ ▀█▀▄▄▄▄▄▀▀▄█▀▀▀▄▄ ▀▀ ▀▄█
-█ ▄███ ▄  ▄ █▀█▀█▄▀▀██▀▄ ▀▄ ▄▄█ ▄▄▀▀▀██
-█▀████▄▄▀▀█ ▄▀▄▄▄▄▄▀▄▀▄▄▀▀▀▀ ▀▄▄█▀▀ ▀▄█
-█▀█▄█▄▀▄▀███ ▄ ▄ ▀ ▀█▄ █▄▄▄ ▄██▄█ █▀▀██
-██▄  ▄▄▄█▄▄▄█▄ ▀█▀▄▀▄▄ ▀▀▀█▀ ▄█▄▄▀ ▄ ▄█
-█▀█▀▄▄ ▄█ ▄▄█▀█▀█▄▀▄█  ▄  █▀▄▄█  ▀█▀▀██
-█ ▄▄▀  ▄█▀██▄▀▄▄▄█ ▄█ ▄▄▀▀█▀ ▀▄▄▄▀ ▄ ▄█
-█████▄▀▄█ ▀█ ▄ ▄   ▀▀█ ▀▄ ▄▄ ▀▀▄███▀▀██
-█▄▄▄▄▄█▄▄ ▀ █▄ ▀ ▄▄▄▄▀ █  █ ▄ ▄▄▄  ▄███
-█ ▄▄▄▄▄ █▀▄▀█▀█▀▄▄  ██ █ ▄▄ █ █▄█ ▀▀▀██
-█ █   █ █▄  ▄▀▄▄▀▀▄▀▄▀▄▀ ▄▀▀▀   ▄▄▀ ▀ █
-█ █▄▄▄█ █▀██ ▄ ▄▄ ▀▀█▀ ▀ ▀▄▀▀▄▄ ▄▀▄▀▀██
-█▄▄▄▄▄▄▄█▄▄▄█▄▄██▄▄▄▄█▄█▄▄██▄█▄████▄▄▄█
-
-Press ENTER to open the URL in your browser.
-Logged in on https://registry.npmjs.org/