@oliphaunt/wasix-tools 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.1.0 (2026-09-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* **wasix-ts:** run host runtimes through Rust Node-API ([#156](https://github.com/f0rr0/oliphaunt/issues/156))
+* **sdk:** unify embedded PostgreSQL public APIs ([#153](https://github.com/f0rr0/oliphaunt/issues/153))
+* Rust WASIX removes temporary/application-data storage variants, and browser IndexedDB uses the new per-database v3 layout without migrating prior generations.
+
+### Features
+
+* **sdk:** unify embedded PostgreSQL public APIs ([#153](https://github.com/f0rr0/oliphaunt/issues/153)) ([4384d1b](https://github.com/f0rr0/oliphaunt/commit/4384d1bdfafee07e4e1963ac68027b4bcf002a1e))
+* unify native and WASIX runtimes and SDKs ([#129](https://github.com/f0rr0/oliphaunt/issues/129)) ([fae2bd7](https://github.com/f0rr0/oliphaunt/commit/fae2bd7bde00ae436d9b62ba6a37d919679ac790))
+* **wasix-ts:** run host runtimes through Rust Node-API ([#156](https://github.com/f0rr0/oliphaunt/issues/156)) ([28e07be](https://github.com/f0rr0/oliphaunt/commit/28e07be782388915b28ad3fd30e3e78143710d28))
+
+
+### Bug Fixes
+
+* **ci:** preserve native lifecycle server sessions ([#165](https://github.com/f0rr0/oliphaunt/issues/165)) ([b8cab0b](https://github.com/f0rr0/oliphaunt/commit/b8cab0be2b86c6b9fab4c279add89113c5797d23))
+
+
+### Performance Improvements
+
+* **js:** streamline exec response handling ([#158](https://github.com/f0rr0/oliphaunt/issues/158)) ([5eaf05b](https://github.com/f0rr0/oliphaunt/commit/5eaf05b8a8d21bd974b9fcb6d618103be5689151))
+* **wasix:** preserve and accelerate seek end ([#154](https://github.com/f0rr0/oliphaunt/issues/154)) ([169852f](https://github.com/f0rr0/oliphaunt/commit/169852f22d1c5eab4cfd30c17ccca014b8d84592))
+
+
+### Code Refactoring
+
+* **ci:** align product and release task boundaries ([#170](https://github.com/f0rr0/oliphaunt/issues/170)) ([009a5f5](https://github.com/f0rr0/oliphaunt/commit/009a5f5ec0659d70f6a22902c071a81e0806fabe))
+* **ci:** model independent product dependencies ([#173](https://github.com/f0rr0/oliphaunt/issues/173)) ([2d5f90c](https://github.com/f0rr0/oliphaunt/commit/2d5f90c837ef7ecd8b43c2547e4b3c9b04767121))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 oliphaunt-wasix Contributors
+
+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,43 @@
+# @oliphaunt/wasix-tools
+
+Optional standard PostgreSQL `pg_dump` and non-interactive `psql` runners for
+an open `@oliphaunt/wasix-ts` database. This package remains the public opt-in
+facade on every host. Browsers load separately carried portable tool binaries;
+Node.js, Bun, Deno, and Electron call the copies compiled into the matching Node-API
+platform carrier.
+
+`pgDump()` returns PostgreSQL's ordinary plain SQL dump, including normal
+`COPY` data. `psql()` accepts a command or script and can restore that output.
+Both operations exclusively own the database session until they finish.
+They reset PostgreSQL session state before and after running, so raw-protocol
+callers must not expect prepared statements or session settings to survive.
+
+```sh
+pnpm add @oliphaunt/wasix-ts @oliphaunt/wasix-tools
+```
+
+```ts
+import Oliphaunt from '@oliphaunt/wasix-ts';
+import WorkerOliphaunt from '@oliphaunt/wasix-ts/worker';
+import { pgDump, psql } from '@oliphaunt/wasix-tools';
+
+await using source = await Oliphaunt.open();
+const sql = await pgDump(source, { args: ['--schema-only'] });
+await using target = await WorkerOliphaunt.open();
+await psql(target, { script: sql });
+```
+
+`pgDump()` supports databases from the root, `/direct`, and `/worker` entrypoints.
+In browsers, `psql()` requires `/worker` because COPY restore is full duplex.
+On Node.js, Bun, Deno, and Electron the Rust tool bridge supports `psql()` on
+all three entrypoints.
+Ordinary PostgreSQL
+arguments are passed through, except connection, input/output, encoding, dump
+format, compression, and parallel-job arguments owned by the runner.
+`pgDump()` always uses plain UTF-8 output and rejects custom formats; it does
+not force `--inserts` or rewrite valid dump SQL. `psql()` accepts `command` or
+`script`, uses no user psqlrc, and stops on the first SQL error. Interactive
+input and `pg_restore` are not part of this package.
+
+Tool failures throw `PostgresToolError` with `tool`, `exitCode`, `stdout`, and
+`stderr` fields.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,20 @@
+# Third-Party Notices
+
+Oliphaunt source code in this repository is licensed under the MIT license in
+`LICENSE`.
+
+This file is the repository-level notice index. Product-specific runtime and
+packaging notices live next to the product that ships the relevant artifacts:
+
+- `src/runtimes/liboliphaunt/native/THIRD_PARTY_NOTICES.md`
+- `src/bindings/wasix-rust/THIRD_PARTY_NOTICES.md`
+
+Shared PostgreSQL source pins, third-party source pins, and extension metadata
+are maintained in `src/postgres/versions/18/`, `src/sources/third-party/`, and
+`src/extensions/`. Generated release artifacts must include the notices and
+exact pinned license bytes for every product and third-party component they
+ship.
+
+Canonical runtime license snapshots live in
+`src/runtimes/liboliphaunt/licenses/`; their source pins and digests are
+enforced by `tools/release/release-notices.mjs`.

package/lib/index.d.ts

@@ -0,0 +1,30 @@
+import type { OliphauntDatabase } from '@oliphaunt/wasix-ts';
+export type PgDumpOptions = Readonly<{
+    /** Ordinary PostgreSQL pg_dump arguments. Connection, file input/output, format, compression, encoding, and job flags are managed. */
+    args?: readonly string[];
+}>;
+export type PsqlOptions = Readonly<{
+    /** Ordinary PostgreSQL psql arguments. Connection, input, and output are managed. */
+    args?: readonly string[];
+    command?: string;
+    script?: string;
+}>;
+export declare class PostgresToolError extends Error {
+    readonly tool: 'pg_dump' | 'psql';
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    constructor(tool: 'pg_dump' | 'psql', message: string, options?: {
+        exitCode?: number | null;
+        stdout?: string;
+        stderr?: string;
+        cause?: unknown;
+    });
+}
+/** Run standard PostgreSQL plain pg_dump against an open WASIX database. */
+export declare function pgDump(database: OliphauntDatabase, options?: PgDumpOptions): Promise<string>;
+/**
+ * Run standard non-interactive psql. Browsers require a `/worker` database;
+ * Node.js, Bun, Deno, and Electron support root, `/direct`, and `/worker` databases.
+ */
+export declare function psql(database: OliphauntDatabase, options?: PsqlOptions): Promise<string>;

package/lib/index.js

@@ -0,0 +1,268 @@
+import tools from '@oliphaunt/liboliphaunt-wasix-tools';
+import { getWasixDatabaseIdentity, runWasixToolProcess } from '@oliphaunt/wasix-ts/internal/tools';
+assertToolsCarrier();
+const VIRTUAL_TOOL_HOST = '127.0.0.1';
+const VIRTUAL_TOOL_PORT = '65432';
+// PostgreSQL 18 getopt_long optstrings. A value-taking option owns the rest
+// of its token, so a managed-looking character inside that value stays data.
+const PG_DUMP_SHORT_OPTIONS = 'abBcCd:e:E:f:F:h:j:n:N:Op:RsS:t:T:U:vwWxXZ:';
+const PSQL_SHORT_OPTIONS = 'aAbc:d:eEf:F:h:HlL:no:p:P:qR:sStT:U:v:VwWxXz?01';
+const PG_DUMP_VALUE_OPTIONS = [
+    '--extension',
+    '--schema',
+    '--exclude-schema',
+    '--superuser',
+    '--table',
+    '--exclude-table',
+    '--exclude-table-data',
+    '--extra-float-digits',
+    '--lock-wait-timeout',
+    '--role',
+    '--section',
+    '--snapshot',
+    '--rows-per-insert',
+    '--include-foreign-data',
+    '--table-and-children',
+    '--exclude-table-and-children',
+    '--exclude-table-data-and-children',
+    '--sync-method',
+    '--exclude-extension',
+    '--restrict-key',
+];
+const PSQL_VALUE_OPTIONS = [
+    '--field-separator',
+    '--pset',
+    '--record-separator',
+    '--table-attr',
+    '--set',
+    '--variable',
+];
+export class PostgresToolError extends Error {
+    tool;
+    exitCode;
+    stdout;
+    stderr;
+    constructor(tool, message, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = 'PostgresToolError';
+        this.tool = tool;
+        this.exitCode = options.exitCode ?? null;
+        this.stdout = options.stdout ?? '';
+        this.stderr = options.stderr ?? '';
+    }
+}
+/** Run standard PostgreSQL plain pg_dump against an open WASIX database. */
+export async function pgDump(database, options = {}) {
+    const args = validatedArguments('pg_dump', options.args, pgDumpManagedArgument, PG_DUMP_SHORT_OPTIONS, PG_DUMP_VALUE_OPTIONS);
+    const identity = getWasixDatabaseIdentity(database);
+    return runTool('pg_dump', database, [
+        ...args,
+        '--encoding=UTF8',
+        '--no-password',
+        `--username=${identity.username}`,
+        `--host=${VIRTUAL_TOOL_HOST}`,
+        `--port=${VIRTUAL_TOOL_PORT}`,
+        `--dbname=${identity.database}`,
+    ]);
+}
+/**
+ * Run standard non-interactive psql. Browsers require a `/worker` database;
+ * Node.js, Bun, Deno, and Electron support root, `/direct`, and `/worker` databases.
+ */
+export async function psql(database, options = {}) {
+    const args = validatedArguments('psql', options.args, psqlManagedArgument, PSQL_SHORT_OPTIONS, PSQL_VALUE_OPTIONS);
+    if (options.command !== undefined && options.script !== undefined) {
+        throw new TypeError('psql accepts command or script, not both');
+    }
+    const command = validatedInput(options.command, 'psql command');
+    const script = validatedInput(options.script, 'psql script');
+    if (command === undefined && script === undefined && args.length === 0) {
+        throw new TypeError('psql requires non-interactive input through command, script, or args');
+    }
+    const inputArgs = command !== undefined ? ['--command', command] : script !== undefined ? ['--file=-'] : [];
+    const identity = getWasixDatabaseIdentity(database);
+    return runTool('psql', database, [
+        ...args,
+        '--no-psqlrc',
+        '--no-password',
+        '--set=ON_ERROR_STOP=1',
+        `--username=${identity.username}`,
+        `--host=${VIRTUAL_TOOL_HOST}`,
+        `--port=${VIRTUAL_TOOL_PORT}`,
+        `--dbname=${identity.database}`,
+        ...inputArgs,
+    ], script === undefined ? undefined : new TextEncoder().encode(script));
+}
+async function runTool(name, database, args, stdin) {
+    const descriptor = name === 'pg_dump' ? tools.pgDump : tools.psql;
+    let result;
+    try {
+        result = await runWasixToolProcess(database, {
+            runtimeVersion: tools.runtimeVersion,
+            tool: descriptor,
+            args,
+            stdin,
+        });
+    }
+    catch (cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        throw new PostgresToolError(name, `could not run ${name}: ${detail}`, { cause });
+    }
+    if (result.exitCode !== 0) {
+        // Diagnostics are best-effort text just like native process output. Keep
+        // the structured failure even if either stream contains invalid UTF-8.
+        const stdout = decodeDiagnostics(result.stdout);
+        const stderr = decodeDiagnostics(result.stderr);
+        throw new PostgresToolError(name, `${name} exited with status ${result.exitCode}${stderr.trim() === '' ? '' : `: ${stderr.trim()}`}`, { exitCode: result.exitCode, stdout, stderr });
+    }
+    try {
+        return decode(result.stdout, `${name} output`);
+    }
+    catch (cause) {
+        throw new PostgresToolError(name, `${name} output is not valid UTF-8`, {
+            exitCode: result.exitCode,
+            stdout: decodeDiagnostics(result.stdout),
+            stderr: decodeDiagnostics(result.stderr),
+            cause,
+        });
+    }
+}
+function validatedInput(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new TypeError(`${label} must be a string`);
+    if (value.includes('\0'))
+        throw new TypeError(`${label} must not contain NUL bytes`);
+    return value;
+}
+function validatedArguments(tool, value, managed, shortOptions, valueOptions) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new TypeError(`${tool} args must be an array of strings`);
+    let expectsValue = false;
+    const validated = value.map((argument) => {
+        if (typeof argument !== 'string')
+            throw new TypeError(`${tool} argument must be a string`);
+        if (argument.includes('\0'))
+            throw new TypeError(`${tool} argument must not contain NUL bytes`);
+        if (expectsValue) {
+            expectsValue = false;
+            return argument;
+        }
+        const label = managed(argument);
+        if (label !== undefined) {
+            throw new TypeError(`${tool} argument ${JSON.stringify(argument)} conflicts with Oliphaunt's managed ${label}`);
+        }
+        if (argument === '-' || !argument.startsWith('-')) {
+            throw new TypeError(`${tool} argument ${JSON.stringify(argument)} conflicts with Oliphaunt's managed database or username`);
+        }
+        expectsValue = optionConsumesNext(argument, shortOptions, valueOptions);
+        return argument;
+    });
+    if (expectsValue) {
+        throw new TypeError(`${tool} argument ${JSON.stringify(validated.at(-1))} requires a value`);
+    }
+    return validated;
+}
+function pgDumpManagedArgument(argument) {
+    if (argument === '--')
+        return 'option terminator';
+    return managedArgument(argument, [
+        ['--password', '-W', 'password prompting'],
+        ['--filter', '', 'input file'],
+        ['--file', '-f', 'output file'],
+        ['--format', '-F', 'output format'],
+        ['--compress', '-Z', 'output compression'],
+        ['--encoding', '-E', 'output encoding'],
+        ['--host', '-h', 'host'],
+        ['--port', '-p', 'port'],
+        ['--username', '-U', 'username'],
+        ['--dbname', '-d', 'database'],
+        ['--jobs', '-j', 'job count'],
+    ], PG_DUMP_SHORT_OPTIONS);
+}
+function optionConsumesNext(argument, shortOptions, valueOptions) {
+    if (argument.startsWith('--')) {
+        if (argument.includes('='))
+            return false;
+        return valueOptions.some((option) => option.startsWith(argument));
+    }
+    for (let index = 1; index < argument.length; index += 1) {
+        const option = argument[index];
+        if (option === undefined)
+            return false;
+        const position = shortOptions.indexOf(option);
+        if (position < 0)
+            return false;
+        if (shortOptions[position + 1] === ':')
+            return index === argument.length - 1;
+    }
+    return false;
+}
+function psqlManagedArgument(argument) {
+    if (argument === '--')
+        return 'option terminator';
+    return managedArgument(argument, [
+        ['--password', '-W', 'password prompting'],
+        ['--single-step', '-s', 'interactive prompting'],
+        ['--host', '-h', 'host'],
+        ['--port', '-p', 'port'],
+        ['--username', '-U', 'username'],
+        ['--dbname', '-d', 'database'],
+        ['--output', '-o', 'stdout capture'],
+        ['--log-file', '-L', 'stderr capture'],
+        ['--command', '-c', 'input'],
+        ['--file', '-f', 'input'],
+    ], PSQL_SHORT_OPTIONS);
+}
+function managedArgument(argument, flags, shortOptions) {
+    const longName = argument.split('=', 1)[0];
+    if (longName !== undefined && longName.length > 2 && longName.startsWith('--')) {
+        for (const [long, , label] of flags) {
+            // Native getopt_long accepts unique prefixes while PostgreSQL's bundled
+            // fallback requires exact names. Reject either spelling consistently so
+            // a managed option cannot become host-dependent.
+            if (long.startsWith(longName))
+                return label;
+        }
+    }
+    if (argument.length < 2 || argument[0] !== '-' || argument[1] === '-') {
+        return undefined;
+    }
+    for (let index = 1; index < argument.length; index += 1) {
+        const option = argument[index];
+        if (option === undefined)
+            return undefined;
+        const position = shortOptions.indexOf(option);
+        if (position < 0)
+            return undefined;
+        const managed = flags.find(([, short]) => short === `-${option}`);
+        if (managed !== undefined)
+            return managed[2];
+        if (shortOptions[position + 1] === ':')
+            return undefined;
+    }
+    return undefined;
+}
+function decode(bytes, label) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch (cause) {
+        throw new Error(`${label} is not valid UTF-8`, { cause });
+    }
+}
+function decodeDiagnostics(bytes) {
+    return new TextDecoder().decode(bytes);
+}
+function assertToolsCarrier() {
+    if (tools.schema !== 'oliphaunt-wasix-tools-v1' ||
+        tools.product !== 'oliphaunt-wasix-tools' ||
+        tools.runtimeProduct !== 'liboliphaunt-wasix' ||
+        typeof tools.runtimeVersion !== 'string' ||
+        tools.runtimeVersion.length === 0) {
+        throw new Error('@oliphaunt/liboliphaunt-wasix-tools has an invalid descriptor');
+    }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@oliphaunt/wasix-tools",
+  "version": "0.1.0",
+  "description": "Optional in-process PostgreSQL pg_dump and psql runners for Oliphaunt WASIX.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/f0rr0/oliphaunt.git",
+    "directory": "src/bindings/wasix-ts/tools-package"
+  },
+  "bugs": {
+    "url": "https://github.com/f0rr0/oliphaunt/issues"
+  },
+  "homepage": "https://oliphaunt.dev",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "oliphaunt": {
+    "runtimeProduct": "liboliphaunt-wasix",
+    "runtimeVersion": "0.2.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "dependencies": {
+    "@oliphaunt/liboliphaunt-wasix-tools": "0.2.0"
+  },
+  "peerDependencies": {
+    "@oliphaunt/wasix-ts": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22.13 <25",
+    "bun": ">=1.3.14",
+    "deno": ">=2.8.1"
+  }
+}