@locci/db 1.0.0-alpha-1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MikeTeddyOmondi
+
+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

@@ -0,0 +1,319 @@
+# Locci DB - [@locci/db]()
+
+Lightweight PostgreSQL-compatible database server powered by [PGlite](https://pglite.dev/).
+
+## Features
+
+- **Embedded Database**: Full PostgreSQL compatibility with PGlite
+- **Easy to Deploy**: Standalone executable or Docker container
+- **Secure**: Password hashing, connection limiting, IP filtering
+- **Configurable**: Support for config files, environment variables, and CLI flags
+- **CLI Support**: Generate hashes, manage database via command line
+- **Production Ready**: Graceful shutdown, connection pooling, comprehensive logging
+
+## Installation
+
+### As NPM Package
+
+```bash
+npm install @locci/db
+```
+
+### Global Installation
+
+```bash
+npm install -g @locci/db
+```
+
+### Using npx
+
+```bash
+npx @locci/db start
+```
+
+## Usage
+
+### Start the Server
+
+```bash
+locci-db start
+```
+
+Options:
+- `-p, --port <port>` - Port to listen on (default: 5432)
+- `-h, --host <host>` - Host to bind to (default: 127.0.0.1)
+- `-d, --data-dir <path>` - Data directory path
+- `-l, --log-level <level>` - Log level: trace, debug, info, warn, error, fatal (default: info)
+
+### Generate Password Hash
+
+```bash
+locci-db hash-password "clear-text-password-here"
+```
+
+This generates a secure hash to use in configuration files instead of plaintext passwords.
+
+## Configuration
+
+Configuration is loaded from multiple sources in this order:
+1. CLI flags (highest priority)
+2. Environment variables
+3. A `.env` file in the working directory
+4. Configuration files
+5. Built-in defaults (lowest priority)
+
+A value set at a higher level overrides the same value below it. Levels are
+merged per field, so a config file can supply `auth` while an environment
+variable overrides only the port.
+
+### Environment Variables
+
+```bash
+export LOCCI_DB_PORT=5433
+export LOCCI_DB_HOST=127.0.0.1
+export LOCCI_DB_USERNAME=dbuser
+export LOCCI_DB_PASSWORD=dbpassword
+export LOCCI_DB_PASSWORD_HASH="salt:derivedkey"  # If using hash
+export LOCCI_DB_DATA_DIR=/path/to/data
+export LOCCI_DB_LOG_LEVEL=info
+```
+
+These can also live in a `.env` file in the working directory, which is read at
+startup. Real environment variables take precedence over the file, so exporting
+a value still overrides it.
+
+### Configuration File
+
+Create `.locci-db.json` in your project directory:
+
+```json
+{
+  "port": 5432,
+  "host": "127.0.0.1",
+  "dataDir": "./my-database",
+  "logLevel": "info",
+  "auth": {
+    "username": "postgres",
+    "passwordHash": "salt:derivedkey"
+  },
+  "security": {
+    "allowedHosts": ["127.0.0.1", "localhost"],
+    "maxConnections": 10
+  }
+}
+```
+
+Supported file formats:
+- `.locci-db.json`
+- `.locci-db.yaml`
+- `.locci-db.yml`
+- `.locci-db.config.js`
+- `locci-db.config.js`
+- `package.json` (under `locci-db` key)
+
+## Single-file binary
+
+The server compiles to a standalone executable with Bun. It embeds the Bun
+runtime and PGlite's WASM, so it needs no Node, no Bun, and no `node_modules`
+on the target machine.
+
+```bash
+bun run compile        # -> dist-bin/locci-db
+./dist-bin/locci-db start
+```
+
+Every release publishes prebuilt binaries for Linux (x64, arm64, x64-musl),
+macOS (x64, arm64), and Windows (x64), alongside a `SHA256SUMS` file. Verify a
+download before running it:
+
+```bash
+sha256sum -c SHA256SUMS --ignore-missing
+```
+
+When a signing key is configured for the repository, each artifact also ships a
+detached PGP signature (`.asc`):
+
+```bash
+gpg --verify locci-db-linux-x64.asc locci-db-linux-x64
+```
+
+## Docker
+
+The image ships the compiled binary on `distroless/cc`, so it contains no Node,
+no Bun, and no `node_modules`. Images are built for `linux/amd64` and
+`linux/arm64`.
+
+
+### Build
+
+```bash
+docker build -t locci/db:latest .
+```
+
+### Run
+
+```bash
+docker run -d \
+  -p 5432:5432 \
+  -e LOCCI_DB_USERNAME=postgres \
+  -e LOCCI_DB_PASSWORD=postgres \
+  -v locci-data:/app/data \
+  locci/db:latest
+```
+
+### Docker Compose
+
+```bash
+docker compose up -d
+```
+
+## Security Features
+
+- **Password Hashing**: Uses scrypt for secure password hashing
+- **Connection Limiting**: Prevents resource exhaustion
+- **IP Whitelisting**: Restrict connections to authorized hosts
+- **Input Validation**: Zod schema validation for all configurations
+- **Graceful Shutdown**: Properly closes connections on SIGTERM/SIGINT
+
+## Development
+
+### Prerequisites
+
+- [Bun](https://bun.sh/) (package manager, and required to compile binaries)
+- Node.js >= 20.0.0 (the published package targets Node)
+
+### Installation
+
+Dependencies are managed with Bun (`bun.lock`):
+
+```bash
+bun install
+```
+
+### Building
+
+```bash
+npm run build
+```
+
+### Development Mode
+
+```bash
+npm run dev
+```
+
+### Testing
+
+Tests run on [Vitest](https://vitest.dev/) under Node, split into two projects:
+
+```bash
+npm test           # unit tests
+npm run test:unit  # same, explicit
+npm run test:e2e   # builds, then boots the real server and connects to it
+npm run test:all   # both projects
+npm run test:watch # unit tests in watch mode
+npm run test:coverage
+```
+
+Unit specs live in `tests/unit`, end-to-end specs in `tests/e2e`. E2E specs bind
+real ports, so they run serially with longer timeouts.
+
+### Linting and type checking
+
+```bash
+npm run lint      # oxlint, warnings are errors
+npm run lint:fix  # apply autofixes
+npm run typecheck # tsc over src and tests
+```
+
+### Compiling
+
+```bash
+npm run compile   # single-file binary into dist-bin/
+```
+
+## API
+
+### `startServer(): Promise<net.Server>`
+
+Starts the database server with loaded configuration.
+
+```typescript
+import { startServer } from '@locci/db';
+
+const server = await startServer();
+```
+
+### `loadConfig(): Config`
+
+Loads configuration from files and environment variables.
+
+```typescript
+import { loadConfig } from '@locci/db/config';
+
+const config = loadConfig();
+```
+
+### `hashPassword(password: string): Promise<string>`
+
+Generates a secure password hash.
+
+```typescript
+import { hashPassword } from '@locci/db/config';
+
+const hash = await hashPassword('my-password');
+```
+
+### `verifyPassword(password: string, hash: string): Promise<boolean>`
+
+Verifies a password against a hash.
+
+```typescript
+import { verifyPassword } from '@locci/db/config';
+
+const isValid = await verifyPassword('my-password', hash);
+```
+
+## Publishing
+
+Releases are automated. Pushing a version tag runs the `Release` workflow,
+which verifies the build, cross-compiles the binaries, creates the GitHub
+release with those binaries and their checksums attached, publishes to npm, and
+pushes multi-arch images to Docker Hub and GHCR.
+
+```bash
+npm version patch|minor|major   # updates package.json and creates the tag
+git push --follow-tags
+```
+
+The workflow fails if the tag does not match the version in `package.json`. A
+prerelease version (one containing a hyphen, such as `1.0.0-alpha-1`) publishes
+to npm under the `next` dist-tag and does not move the `latest` Docker tag.
+
+Required repository secrets: `NPM_TOKEN`, `DOCKER_USERNAME`, `DOCKER_PASSWORD`.
+GHCR uses the built-in `GITHUB_TOKEN`. Set `GPG_PRIVATE_KEY` and
+`GPG_PASSPHRASE` to sign the release binaries; without them the release still
+completes, with a warning, and the binaries are published unsigned.
+
+## License
+
+MIT - See LICENSE file for details
+
+## Dependencies
+
+- [PGlite](https://pglite.dev/) - PostgreSQL in WASM
+- [pg-gateway](https://github.com/supabase-community/pg-gateway) - PostgreSQL wire protocol handler
+- [Pino](https://getpino.io/) - Fast logger
+- [Commander](https://github.com/tj/commander.js) - CLI framework
+- [Zod](https://zod.dev/) - TypeScript-first schema validation
+- [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) - Configuration file discovery
+- [defu](https://github.com/unjs/defu) - Configuration merging
+- [dotenv](https://github.com/motdotla/dotenv) - `.env` file loading
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Support
+
+For issues and feature requests, please use the GitHub issues page.

package/bin/locci-db.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+// Shim to load the compiled TypeScript CLI
+import('../dist/cli.js').catch((err) => {
+  console.error('Failed to start @locci/db:', err);
+  process.exit(1);
+});

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// Must come before any import that reads process.env. Values already present
+// in the real environment win; .env only fills in what is missing.
+import { config as loadEnvFile } from "dotenv";
+loadEnvFile({ quiet: true });
+import { Command } from "commander";
+import { startServer } from "./index.js";
+import { hashPassword } from "./config.js";
+import { VERSION } from "./version.js";
+import { log } from "./utils.js";
+const program = new Command();
+program
+    .name("locci-db")
+    .description("Lightweight PostgreSQL-compatible database server")
+    .version(VERSION);
+program
+    .command("start")
+    .description("Start the database server")
+    .option("-p, --port <port>", "Port to listen on (default: 5432)")
+    .option("-h, --host <host>", "Host to bind to (default: 127.0.0.1)")
+    .option("-d, --data-dir <path>", "Data directory path")
+    .option("-l, --log-level <level>", "Log level (default: info)")
+    .action(async (options) => {
+    // Only flags the user actually passed become overrides. Setting these
+    // unconditionally would make commander defaults outrank the config file.
+    if (options.port)
+        process.env.LOCCI_DB_PORT = options.port;
+    if (options.host)
+        process.env.LOCCI_DB_HOST = options.host;
+    if (options.dataDir)
+        process.env.LOCCI_DB_DATA_DIR = options.dataDir;
+    if (options.logLevel)
+        process.env.LOCCI_DB_LOG_LEVEL = options.logLevel;
+    try {
+        await startServer();
+    }
+    catch (error) {
+        log.error({ error }, "Failed to start server:");
+        process.exit(1);
+    }
+});
+program
+    .command("hash-password <password>")
+    .description("Generate a password hash for configuration")
+    .action(async (password) => {
+    try {
+        const hash = await hashPassword(password);
+        log.info({ hash }, "Password hash (store this in your config) ");
+    }
+    catch (error) {
+        log.error({ error }, "Failed to generate password hash:");
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/config.d.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+/**
+ * Configuration schema with validation
+ */
+export declare const ConfigSchema: z.ZodObject<{
+    port: z.ZodDefault<z.ZodNumber>;
+    host: z.ZodDefault<z.ZodString>;
+    dataDir: z.ZodOptional<z.ZodString>;
+    logLevel: z.ZodDefault<z.ZodEnum<["trace", "debug", "info", "warn", "error", "fatal"]>>;
+    auth: z.ZodObject<{
+        username: z.ZodString;
+        password: z.ZodOptional<z.ZodString>;
+        passwordHash: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        username: string;
+        password?: string | undefined;
+        passwordHash?: string | undefined;
+    }, {
+        username: string;
+        password?: string | undefined;
+        passwordHash?: string | undefined;
+    }>;
+    security: z.ZodOptional<z.ZodObject<{
+        allowedHosts: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        maxConnections: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        allowedHosts: string[];
+        maxConnections: number;
+    }, {
+        allowedHosts?: string[] | undefined;
+        maxConnections?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    port: number;
+    host: string;
+    logLevel: "info" | "fatal" | "error" | "warn" | "debug" | "trace";
+    auth: {
+        username: string;
+        password?: string | undefined;
+        passwordHash?: string | undefined;
+    };
+    dataDir?: string | undefined;
+    security?: {
+        allowedHosts: string[];
+        maxConnections: number;
+    } | undefined;
+}, {
+    auth: {
+        username: string;
+        password?: string | undefined;
+        passwordHash?: string | undefined;
+    };
+    port?: number | undefined;
+    host?: string | undefined;
+    dataDir?: string | undefined;
+    logLevel?: "info" | "fatal" | "error" | "warn" | "debug" | "trace" | undefined;
+    security?: {
+        allowedHosts?: string[] | undefined;
+        maxConnections?: number | undefined;
+    } | undefined;
+}>;
+export type Config = z.infer<typeof ConfigSchema>;
+/**
+ * Hash password securely using scrypt
+ */
+export declare function hashPassword(password: string): Promise<string>;
+/**
+ * Verify password against hash
+ */
+export declare function verifyPassword(password: string, hash: string): Promise<boolean>;
+/**
+ * Load configuration from multiple sources
+ */
+export declare function loadConfig(): Config;

package/dist/config.js

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import { cosmiconfigSync } from "cosmiconfig";
+import { defu } from "defu";
+import { randomBytes, scrypt } from "crypto";
+import { promisify } from "util";
+import { log } from "./utils.js";
+const scryptAsync = promisify(scrypt);
+/**
+ * Configuration schema with validation
+ */
+export const ConfigSchema = z.object({
+    port: z.number().int().min(1024).max(65535).default(5432),
+    host: z.string().default("127.0.0.1"),
+    dataDir: z.string().optional(),
+    logLevel: z
+        .enum(["trace", "debug", "info", "warn", "error", "fatal"])
+        .default("info"),
+    auth: z.object({
+        username: z.string().min(3).max(63),
+        password: z.string().min(8).optional(),
+        // Optional: password hash instead of plaintext
+        passwordHash: z.string().optional(),
+    }),
+    security: z
+        .object({
+        allowedHosts: z.array(z.string()).default(["127.0.0.1", "localhost"]),
+        maxConnections: z.number().int().positive().default(10),
+    })
+        .optional(),
+});
+/**
+ * Hash password securely using scrypt
+ */
+export async function hashPassword(password) {
+    const salt = randomBytes(16).toString("hex");
+    const derivedKey = (await scryptAsync(password, salt, 64));
+    return `${salt}:${derivedKey.toString("hex")}`;
+}
+/**
+ * Verify password against hash
+ */
+export async function verifyPassword(password, hash) {
+    try {
+        const [salt, key] = hash.split(":");
+        if (!salt || !key)
+            return false;
+        const derivedKey = (await scryptAsync(password, salt, 64));
+        return key === derivedKey.toString("hex");
+    }
+    catch (error) {
+        log.error({ error }, "Error verifying password:");
+        return false;
+    }
+}
+/**
+ * Load configuration from multiple sources
+ */
+export function loadConfig() {
+    const explorer = cosmiconfigSync("locci-db", {
+        searchPlaces: [
+            "package.json",
+            ".locci-db.json",
+            ".locci-db.yaml",
+            ".locci-db.yml",
+            ".locci-db.config.js",
+            "locci-db.config.js",
+        ],
+    });
+    const result = explorer.search();
+    const config = result?.config || {};
+    // Merge with environment variables
+    const envConfig = {
+        port: process.env.LOCCI_DB_PORT
+            ? parseInt(process.env.LOCCI_DB_PORT, 10)
+            : undefined,
+        host: process.env.LOCCI_DB_HOST,
+        dataDir: process.env.LOCCI_DB_DATA_DIR,
+        logLevel: process.env.LOCCI_DB_LOG_LEVEL,
+        auth: {
+            username: process.env.LOCCI_DB_USERNAME,
+            password: process.env.LOCCI_DB_PASSWORD,
+            passwordHash: process.env.LOCCI_DB_PASSWORD_HASH,
+        },
+    };
+    // defu merges right-to-left by falling priority and skips undefined values,
+    // so an env var that is not set falls through to the config file.
+    const mergedConfig = defu(envConfig, config);
+    // Validate with Zod
+    return ConfigSchema.parse(mergedConfig);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import net from "node:net";
+export declare function startServer(): Promise<net.Server>;

package/dist/index.js

@@ -0,0 +1,114 @@
+import { PGlite } from "@electric-sql/pglite";
+import net from "node:net";
+import { join } from "path";
+import { homedir } from "os";
+import { dirname } from "node:path";
+import { mkdir } from "node:fs/promises";
+import { fromNodeSocket } from "pg-gateway/node";
+import { log } from "./utils.js";
+import { loadConfig, verifyPassword } from "./config.js";
+import { getEmbeddedPGliteAssets } from "./pglite-assets.js";
+export async function startServer() {
+    const config = loadConfig();
+    // Secure data directory (user's home by default)
+    const dataDir = config.dataDir || join(homedir(), ".locci/db", "data");
+    // Ensure parent directory exists
+    await mkdir(dirname(dataDir), { recursive: true });
+    log.info(`Initializing PGlite database at ${dataDir}`);
+    const db = new PGlite({ dataDir, ...getEmbeddedPGliteAssets() });
+    let activeConnections = 0;
+    const server = net.createServer(async (socket) => {
+        const clientAddress = socket.remoteAddress;
+        // Connection limiting
+        if (activeConnections >= (config.security?.maxConnections || 10)) {
+            log.warn(`Connection rejected: max connections reached (${activeConnections})`);
+            socket.destroy();
+            return;
+        }
+        // IP filtering
+        if (config.security?.allowedHosts &&
+            !config.security.allowedHosts.includes(clientAddress || "")) {
+            log.warn(`Connection rejected from unauthorized host: ${clientAddress}`);
+            socket.destroy();
+            return;
+        }
+        activeConnections++;
+        log.info(`Client connected from ${clientAddress} (${activeConnections} active)`);
+        await fromNodeSocket(socket, {
+            serverVersion: "16.3 (PGlite 0.2.0)",
+            auth: {
+                method: "password",
+                validateCredentials: async function (credentials) {
+                    if (credentials.clearTextPassword) {
+                        const isValidUser = credentials.username === config.auth.username;
+                        // Use password hash if available, otherwise compare plaintext
+                        let isValidPassword;
+                        if (config.auth.passwordHash) {
+                            isValidPassword = await verifyPassword(credentials.password, config.auth.passwordHash);
+                        }
+                        else if (config.auth.password) {
+                            isValidPassword = credentials.password === config.auth.password;
+                        }
+                        else {
+                            isValidPassword = false;
+                        }
+                        if (!isValidUser || !isValidPassword) {
+                            log.warn(`Authentication failed for user: ${credentials.username} from ${clientAddress}`);
+                        }
+                        return isValidUser && isValidPassword;
+                    }
+                    return false;
+                },
+                getClearTextPassword: async function (credentials) {
+                    return credentials.username;
+                },
+            },
+            async onStartup() {
+                log.debug("Awaiting database to be ready...");
+                await db.waitReady;
+            },
+            async onMessage(data, { isAuthenticated }) {
+                if (!isAuthenticated) {
+                    log.warn("Unauthenticated message rejected");
+                    return;
+                }
+                return await db.execProtocolRaw(data);
+            },
+        });
+        socket.on("end", () => {
+            activeConnections--;
+            log.info(`Client disconnected from ${clientAddress} (${activeConnections} active)`);
+        });
+        socket.on("error", (err) => {
+            activeConnections--;
+            log.error(`Socket error from ${clientAddress}: ${err.message}`);
+        });
+    });
+    server.on("error", (err) => {
+        log.error(`Server error: ${err.message}`);
+        process.exit(1);
+    });
+    server.listen(config.port, config.host, async () => {
+        log.info(`🚀 Server listening on ${config.host}:${config.port}`);
+        log.info(`📁 Data directory: ${dataDir}`);
+        log.info(`🔐 Authenticated as: ${config.auth.username}`);
+    });
+    // Graceful shutdown
+    process.on("SIGTERM", () => gracefulShutdown(server, db));
+    process.on("SIGINT", () => gracefulShutdown(server, db));
+    return server;
+}
+async function gracefulShutdown(server, db) {
+    log.info("Shutting down gracefully...");
+    server.close(() => {
+        log.info("Server closed");
+    });
+    try {
+        await db.close();
+        log.info("Database closed");
+    }
+    catch (error) {
+        log.error({ error }, "Error closing database:");
+    }
+    process.exit(0);
+}

package/dist/pglite-assets.d.ts

@@ -0,0 +1,10 @@
+import type { PGliteOptions } from "@electric-sql/pglite";
+/**
+ * PGlite normally fetches postgres.wasm and postgres.data from disk, relative
+ * to its own module URL. That does not work inside a compiled single-file
+ * binary, so the Bun entry point embeds both and injects them here before the
+ * server starts.
+ */
+export type EmbeddedPGliteAssets = Pick<PGliteOptions, "wasmModule" | "fsBundle">;
+export declare function setEmbeddedPGliteAssets(assets: EmbeddedPGliteAssets): void;
+export declare function getEmbeddedPGliteAssets(): EmbeddedPGliteAssets;

package/dist/pglite-assets.js

@@ -0,0 +1,7 @@
+let embedded = {};
+export function setEmbeddedPGliteAssets(assets) {
+    embedded = assets;
+}
+export function getEmbeddedPGliteAssets() {
+    return embedded;
+}

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Type definitions for @locci/db
+ */
+export interface ServerConfig {
+    port: number;
+    host: string;
+    dataDir?: string;
+    logLevel: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+    auth: AuthConfig;
+    security?: SecurityConfig;
+}
+export interface AuthConfig {
+    username: string;
+    password?: string;
+    passwordHash?: string;
+}
+export interface SecurityConfig {
+    allowedHosts?: string[];
+    maxConnections?: number;
+}
+export interface ConnectionInfo {
+    clientAddress?: string;
+    username: string;
+    timestamp: Date;
+    authenticated: boolean;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for @locci/db
+ */
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,21 @@
+import pino from 'pino';
+/**
+ * Create logger instance
+ */
+export declare const log: pino.Logger<never, boolean>;
+/**
+ * Format bytes for human-readable output
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Validate port number
+ */
+export declare function isValidPort(port: number): boolean;
+/**
+ * Validate hostname
+ */
+export declare function isValidHost(host: string): boolean;
+/**
+ * Sleep for specified milliseconds
+ */
+export declare function sleep(ms: number): Promise<void>;

package/dist/utils.js

@@ -0,0 +1,41 @@
+import pino from 'pino';
+import pretty from 'pino-pretty';
+/**
+ * Create logger instance
+ */
+export const log = pino({
+    level: process.env.LOCCI_DB_LOG_LEVEL || 'info',
+}, pretty({
+    colorize: true,
+    singleLine: false,
+    translateTime: 'SYS:standard',
+}));
+/**
+ * Format bytes for human-readable output
+ */
+export function formatBytes(bytes) {
+    if (bytes === 0)
+        return '0 Bytes';
+    const k = 1024;
+    const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return Math.round((bytes / Math.pow(k, i)) * 100) / 100 + ' ' + sizes[i];
+}
+/**
+ * Validate port number
+ */
+export function isValidPort(port) {
+    return port >= 1024 && port <= 65535 && Number.isInteger(port);
+}
+/**
+ * Validate hostname
+ */
+export function isValidHost(host) {
+    return /^([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)*[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$|^(::)?1?$|^127\.0\.0\.1$|^localhost$|^::$/.test(host);
+}
+/**
+ * Sleep for specified milliseconds
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "1.0.0-alpha-1";

package/dist/version.js

@@ -0,0 +1,2 @@
+// Generated by scripts/gen-version.mjs. Do not edit.
+export const VERSION = "1.0.0-alpha-1";

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@locci/db",
+  "version": "1.0.0-alpha-1",
+  "description": "Lightweight PostgreSQL-compatible database server powered by PGlite",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "locci-db": "./bin/locci-db.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "git config core.hooksPath .githooks || true",
+    "dev": "tsx ./src/cli.ts",
+    "start": "node ./dist/cli.js",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run --project unit",
+    "lint": "oxlint --deny-warnings",
+    "docker:build": "docker build -t locci/db:latest .",
+    "docker:run": "docker run -p 5432:5432 --env-file .env locci/db:latest",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "test:unit": "vitest run --project unit",
+    "test:e2e": "npm run build && vitest run --project e2e",
+    "test:all": "npm run build && vitest run",
+    "test:watch": "vitest --project unit",
+    "test:coverage": "vitest run --project unit --coverage",
+    "lint:fix": "oxlint --fix",
+    "prebuild": "node scripts/gen-version.mjs",
+    "pretypecheck": "node scripts/gen-version.mjs",
+    "compile": "bun build ./src/bun.ts --compile --minify --outfile dist-bin/locci-db",
+    "precompile": "node scripts/gen-version.mjs"
+  },
+  "keywords": [
+    "postgresql",
+    "pglite",
+    "database",
+    "cli",
+    "postgres",
+    "embedded-database"
+  ],
+  "author": "MikeTeddyOmondi <contact@miketeddyomondi.dev>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MikeTeddyOmondi/locci-db.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MikeTeddyOmondi/locci-db/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@electric-sql/pglite": "^0.2.9",
+    "commander": "^12.0.0",
+    "cosmiconfig": "^9.0.0",
+    "defu": "^6.1.7",
+    "dotenv": "^17.4.2",
+    "pg-gateway": "0.3.0-beta.3",
+    "pino": "^9.5.0",
+    "pino-pretty": "^11.3.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "@vitest/coverage-v8": "^5.0.0",
+    "oxlint": "^1.82.0",
+    "tsx": "^4.16.2",
+    "typescript": "^5.5.3",
+    "vitest": "^5.0.0"
+  }
+}