@libredb/libredb 0.0.4 → 0.1.0

package/README.md

@@ -1,5 +1,10 @@
 # LibreDB
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/img/01-hero-dark.png">
+  <img alt="LibreDB - Multi-model without the magic. One core, three lenses, every line tested." src="docs/img/01-hero-light.png" width="100%">
+</picture>
+
 **Multi-model without the magic. One core, three lenses, every line tested.**
 
 [![npm version](https://img.shields.io/npm/v/@libredb/libredb.svg)](https://www.npmjs.com/package/@libredb/libredb)
@@ -79,8 +84,86 @@ Each lens has its own guide: [key-value](./docs/guides/key-value.md) ·
 [document](./docs/guides/document.md) · [relational](./docs/guides/relational.md) ·
 [catalog](./docs/guides/catalog.md).
 
+## Install elsewhere: JSR, CDN, and the browser
+
+LibreDB is the same ESM-only package everywhere; only how you reach it changes.
+
+**JSR** — published to [jsr.io](https://jsr.io/@libredb/libredb) alongside npm:
+
+```sh
+bunx jsr add @libredb/libredb
+# or: npx jsr add @libredb/libredb / deno add jsr:@libredb/libredb
+```
+
+**CDN** — every release is served from the npm registry by the usual CDNs. Pin a version:
+
+```ts
+import { open, kv } from "https://esm.sh/@libredb/libredb@0.1.0";
+```
+
+**Browser** — a dedicated entry that imports nothing from `node:`, so it bundles for the browser
+cleanly. Its `open` carries no default filesystem: an in-memory database works anywhere, and a
+path-backed open takes a filesystem you inject (e.g. the OPFS adapter shown below).
+
+```ts
+import { open, kv } from "@libredb/libredb/browser";
+
+const db = open(); // in-memory
+kv(db).set("greeting", "hello");
+```
+
+For durable storage in the browser, run inside a Web Worker and back the database with an OPFS sync
+access handle (the kernel stays synchronous — no async core):
+
+```ts
+import { open, opfsFileSystem } from "@libredb/libredb/browser";
+
+const root = await navigator.storage.getDirectory();
+const file = await root.getFileHandle("app.libredb", { create: true });
+const handle = await file.createSyncAccessHandle();
+const db = open({ path: "app.libredb", fs: opfsFileSystem(handle) });
+```
+
+A browser-targeting bundler resolves the browser build automatically via the package's `browser`
+export condition, so importing the main `@libredb/libredb` entry works too.
+
+## Command-line tool
+
+The package ships a `libredb` bin for inspecting and editing `.libredb` files — no code required:
+
+```sh
+npx libredb inspect data.libredb          # namespaces, kinds, and table schemas
+npx libredb stats data.libredb            # file size and namespace counts
+npx libredb get data.libredb user:1       # print one value
+npx libredb scan data.libredb user:       # print key=value under a prefix
+npx libredb set data.libredb user:1 Ada   # set a key
+npx libredb delete data.libredb user:1    # remove a key
+npx libredb import data.libredb seed.json # bulk-set from a JSON object, atomically
+```
+
+Read commands open the file read-only, so inspection never mutates it. Write commands take an
+advisory `<path>.lock` to refuse a second concurrent writer; pass `--force` to override a stale lock.
+
+Prefer a standalone binary with no Node or Bun installed? Each release attaches self-contained
+executables (Linux, macOS, Windows; x64 and arm64) with `.sha256` checksums on its
+[GitHub Release](https://github.com/libredb/libredb-database/releases). Or build one locally with
+`bun run compile`.
+
+Or run the CLI from a container (multi-arch, published to GHCR) — mount your data and pass a command:
+
+```sh
+docker run --rm -v "$PWD:/data" ghcr.io/libredb/libredb inspect /data/app.libredb
+```
+
+The image is a CLI shell, not a server: LibreDB stays an embedded, in-process database.
+
 ## How it works: one core, three lenses
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/img/02-lenses-dark.png">
+  <img alt="One core, three lenses: kv, document, and relational APIs over a single ordered key-value core (core.ts), reaching disk through one FileSystem seam." src="docs/img/02-lenses-light.png" width="100%">
+</picture>
+
 LibreDB has a single ordered byte key-value kernel (`src/core.ts`). Key-value, document, and relational
 are thin typed *lenses* over it — three faces of the same store. A relational table is physically a
 JSON document collection, which is physically ordered key-value entries built from composite keys like
@@ -122,6 +205,11 @@ flowchart TB
     CORE --> FS
 ```
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/img/03-trust-dark.png">
+  <img alt="Open at the edges, guarded at the core: lenses, query surface, catalog, adapters, Studio, and docs are open to contribute; core.ts is guarded with 100% line coverage, deterministic crash tests, and heavy review - everything reaches the store through one narrow transact() port." src="docs/img/03-trust-light.png" width="100%">
+</picture>
+
 **The file boundary is the trust boundary.** Below the line (`core.ts`) is guarded: heavy review and
 deterministic crash tests, because a bug there corrupts data. Above the line (lenses, query, catalog)
 is open and fast to contribute to, because the worst a bug can do is present a bad *view* — it reaches
@@ -150,6 +238,11 @@ See the [Manifesto](./MANIFESTO.md).
 
 ## Reliability
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/img/04-reliability-dark.png">
+  <img alt="Crash recovery you can trust: a length-framed, CRC-32-checksummed write-ahead log fsync'd before commit; recovery truncates the last un-fsync'd record so what remains is always a valid committed prefix - proven by deterministic simulation testing." src="docs/img/04-reliability-light.png" width="100%">
+</picture>
+
 A transaction that returns has been written to a length-framed, CRC-32-checksummed write-ahead log and
 `fsync`'d *before* the commit becomes visible — so a committed write survives a crash, and a crash can
 only ever damage the last, un-fsync'd record (which recovery detects and truncates). This is not just
@@ -187,6 +280,11 @@ but the API may still change and it is not yet meant for production data.
 
 ## The LibreDB family
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/img/05-family-dark.png">
+  <img alt="The LibreDB family: LibreDB (the database, this repo), LibreDB Studio (the open-source IDE for every database), and LibreDB Platform (the managed, team-oriented form of data) - three products, one access-model spine." src="docs/img/05-family-light.png" width="100%">
+</picture>
+
 LibreDB is the database in a three-product family that shares one access-model spine:
 
 - **LibreDB** — the database (this repository).

package/dist/adapter/node-fs.d.ts

@@ -0,0 +1,3 @@
+import type { FileSystem } from "../core.ts";
+/** Build the default node:fs-backed {@link FileSystem}. */
+export declare function nodeFileSystem(): FileSystem;

package/dist/adapter/node-fs.js

@@ -0,0 +1,49 @@
+/**
+ * adapter/node-fs.ts — the default {@link FileSystem} for Node and Bun.
+ *
+ * This is an edge, not the kernel (DESIGN.md section 5): it holds the one place
+ * LibreDB touches `node:fs`. The kernel (`core.ts`) is runtime-agnostic and
+ * imports nothing from `node:`; it reaches the disk only through the injected
+ * {@link FileSystem} seam. Keeping the node dependency HERE — and out of the
+ * kernel — is what lets the browser entry (`browser.ts`) ship without dragging
+ * `node:fs` into its import graph. The default Node entry (`index.ts`) wires this
+ * adapter in as the default `fs`, so production behaviour is unchanged.
+ *
+ * Each method is the obvious synchronous syscall, so the adapter adds an
+ * interface boundary, not behaviour. Appends go through one append-mode
+ * descriptor (creating the file if missing); reads, size and truncate work by
+ * path, matching how the WAL has always reached the disk.
+ */
+import { closeSync, fsyncSync, openSync, readFileSync, statSync, truncateSync, writeSync } from "node:fs";
+/** Build the default node:fs-backed {@link FileSystem}. */
+export function nodeFileSystem() {
+    return {
+        open(path) {
+            const fd = openSync(path, "a"); // append-only; creates the file if missing
+            return {
+                size() {
+                    return statSync(path).size;
+                },
+                read(offset, length) {
+                    // A fresh Uint8Array so the returned slice is an independent copy, not
+                    // a view aliasing a shared Buffer pool.
+                    return new Uint8Array(readFileSync(path)).subarray(offset, offset + length);
+                },
+                append(bytes) {
+                    for (let written = 0; written < bytes.length;) {
+                        written += writeSync(fd, bytes, written);
+                    }
+                },
+                fsync() {
+                    fsyncSync(fd);
+                },
+                truncate(length) {
+                    truncateSync(path, length);
+                },
+                close() {
+                    closeSync(fd);
+                },
+            };
+        },
+    };
+}

package/dist/adapter/opfs.d.ts

@@ -0,0 +1,49 @@
+/**
+ * adapter/opfs.ts — an OPFS-backed {@link FileSystem} for the browser.
+ *
+ * An edge, not the kernel: it carries no durability logic, only the mapping from
+ * the kernel's synchronous {@link FileSystem} seam onto an OPFS sync access
+ * handle. The point is that a `FileSystemSyncAccessHandle` exposes SYNCHRONOUS
+ * read/write/getSize/truncate/flush/close — the exact shape the kernel's WAL
+ * needs — so LibreDB can be durable in a browser with no async core.
+ *
+ * Sync access handles only exist inside a Web Worker, and obtaining one is async
+ * (navigator.storage.getDirectory -> getFileHandle -> createSyncAccessHandle).
+ * That async acquisition is the caller's, done once before {@link
+ * import("../core.ts").open}; this adapter takes the already-open handle and
+ * wraps it synchronously, keeping `open` synchronous. Typical use in a Worker:
+ *
+ *   const root = await navigator.storage.getDirectory();
+ *   const file = await root.getFileHandle("app.libredb", { create: true });
+ *   const handle = await file.createSyncAccessHandle();
+ *   const db = open({ path: "app.libredb", fs: opfsFileSystem(handle) });
+ *
+ * The handle is bound to one file, so the kernel's `path` is unused here — the
+ * database opened with this adapter is the file the handle was created for.
+ */
+import type { FileSystem } from "../core.ts";
+/**
+ * The synchronous subset of a browser `FileSystemSyncAccessHandle` the WAL uses.
+ * Declared locally so the package needs no DOM lib types; a real sync access
+ * handle satisfies it structurally.
+ */
+export interface SyncAccessHandle {
+    /** Read into `buffer` starting at `options.at` (default 0); returns bytes read. */
+    read(buffer: Uint8Array, options?: {
+        at?: number;
+    }): number;
+    /** Write `buffer` starting at `options.at` (default 0); returns bytes written. */
+    write(buffer: Uint8Array, options?: {
+        at?: number;
+    }): number;
+    /** The file's current size in bytes. */
+    getSize(): number;
+    /** Resize the file to `newSize`, dropping anything beyond it. */
+    truncate(newSize: number): void;
+    /** Persist buffered writes to storage. */
+    flush(): void;
+    /** Release the handle. */
+    close(): void;
+}
+/** Build a {@link FileSystem} backed by an open OPFS sync access `handle`. */
+export declare function opfsFileSystem(handle: SyncAccessHandle): FileSystem;

package/dist/adapter/opfs.js

@@ -0,0 +1,36 @@
+/** Build a {@link FileSystem} backed by an open OPFS sync access `handle`. */
+export function opfsFileSystem(handle) {
+    return {
+        open() {
+            return {
+                size() {
+                    return handle.getSize();
+                },
+                read(offset, length) {
+                    const buffer = new Uint8Array(length);
+                    const read = handle.read(buffer, { at: offset });
+                    return buffer.subarray(0, read);
+                },
+                append(data) {
+                    // write() may write fewer bytes than asked (hence the returned count),
+                    // so loop until the whole record is on the handle — otherwise a short
+                    // write would persist a torn record while fsync reports success. This
+                    // mirrors the node-fs adapter's writeSync loop.
+                    const base = handle.getSize();
+                    for (let written = 0; written < data.length;) {
+                        written += handle.write(data.subarray(written), { at: base + written });
+                    }
+                },
+                fsync() {
+                    handle.flush();
+                },
+                truncate(length) {
+                    handle.truncate(length);
+                },
+                close() {
+                    handle.close();
+                },
+            };
+        },
+    };
+}

package/dist/browser.d.ts

@@ -0,0 +1,24 @@
+/**
+ * browser.ts — the browser entry point of the LibreDB npm package
+ * (`@libredb/libredb/browser`).
+ *
+ * Same lens surface as the default Node entry ({@link import("./index.ts")}),
+ * with one difference: `open` is the kernel's own, carrying NO default
+ * filesystem. An in-memory database (`open()`) works anywhere; a path-backed
+ * open requires an injected `fs` (e.g. the bundled {@link opfsFileSystem}). The
+ * point of this entry is the import graph: it reaches nothing in `node:`, so a
+ * bundler can ship it to a browser. The node:fs adapter lives behind Node only.
+ */
+export { open, version } from "./core.ts";
+export type { Database, FileSystem, OpenOptions, WalFile } from "./core.ts";
+export { opfsFileSystem } from "./adapter/opfs.ts";
+export type { SyncAccessHandle } from "./adapter/opfs.ts";
+export { kv } from "./lens/kv.ts";
+export type { Kv, KvEntry } from "./lens/kv.ts";
+export { doc } from "./lens/document.ts";
+export type { DocCollection, Doc, DocEntry, JsonValue } from "./lens/document.ts";
+export { table } from "./lens/relational.ts";
+export type { Table, TableSchema, Row, ColumnType, Query } from "./lens/relational.ts";
+export { catalog, isReservedKey, CATALOG_PREFIX, RESERVED_MARKER } from "./lens/catalog.ts";
+export type { CatalogEntry, CatalogRegistry } from "./lens/catalog.ts";
+export type { Result, WriteResult } from "./lens/types.ts";

package/dist/browser.js

@@ -0,0 +1,19 @@
+/**
+ * browser.ts — the browser entry point of the LibreDB npm package
+ * (`@libredb/libredb/browser`).
+ *
+ * Same lens surface as the default Node entry ({@link import("./index.ts")}),
+ * with one difference: `open` is the kernel's own, carrying NO default
+ * filesystem. An in-memory database (`open()`) works anywhere; a path-backed
+ * open requires an injected `fs` (e.g. the bundled {@link opfsFileSystem}). The
+ * point of this entry is the import graph: it reaches nothing in `node:`, so a
+ * bundler can ship it to a browser. The node:fs adapter lives behind Node only.
+ */
+export { open, version } from "./core.js";
+// OPFS persistence (browser-only): wrap an OPFS sync access handle as the
+// filesystem for a path-backed open. See adapter/opfs.ts for usage in a Worker.
+export { opfsFileSystem } from "./adapter/opfs.js";
+export { kv } from "./lens/kv.js";
+export { doc } from "./lens/document.js";
+export { table } from "./lens/relational.js";
+export { catalog, isReservedKey, CATALOG_PREFIX, RESERVED_MARKER } from "./lens/catalog.js";

package/dist/cli/lock.d.ts

@@ -0,0 +1,7 @@
+/** A held lock. Call {@link Lock.release} once the write is done. */
+export interface Lock {
+    release(): void;
+}
+/** Acquire the advisory lock for `path`. With `force`, an existing libredb lock
+ * is dropped first; otherwise an existing lock makes this throw. */
+export declare function acquireLock(path: string, force: boolean): Lock;

package/dist/cli/lock.js

@@ -0,0 +1,51 @@
+/**
+ * cli/lock.ts — an advisory write lock for the CLI.
+ *
+ * LibreDB is single-process and does no file locking itself, so two writers to
+ * one file would corrupt it. Write commands take a `<path>.lock` first: an
+ * exclusive create that fails if the file already exists, turning a concurrent
+ * writer into a loud error instead of silent corruption. It is advisory only —
+ * `--force` drops a stale lock and proceeds. The lock is always released after
+ * the write (see withWriteDb in run.ts).
+ */
+import { closeSync, openSync, readFileSync, rmSync, writeSync } from "node:fs";
+// Written into every lock file so a forced acquire can tell a real libredb lock
+// from an unrelated file that merely happens to be named <path>.lock, and refuse
+// to delete the latter.
+const SENTINEL = "libredb-lock\n";
+/** Acquire the advisory lock for `path`. With `force`, an existing libredb lock
+ * is dropped first; otherwise an existing lock makes this throw. */
+export function acquireLock(path, force) {
+    const lockPath = `${path}.lock`;
+    if (force)
+        dropOwnLock(lockPath);
+    try {
+        const fd = openSync(lockPath, "wx"); // "wx": exclusive create, fails if it exists
+        writeSync(fd, SENTINEL);
+        closeSync(fd);
+    }
+    catch {
+        throw new Error(`libredb: ${path} is locked (${lockPath}); another writer may be active — use --force to override`);
+    }
+    return {
+        release() {
+            rmSync(lockPath, { force: true });
+        },
+    };
+}
+/** Remove an existing libredb lock so a forced acquire can proceed. Refuses to
+ * touch a file that is not a libredb lock, so `--force` can never delete
+ * unrelated user data that happens to share the `.lock` name. */
+function dropOwnLock(lockPath) {
+    let contents;
+    try {
+        contents = readFileSync(lockPath, "utf8");
+    }
+    catch {
+        return; // no lock file to drop
+    }
+    if (!contents.startsWith(SENTINEL)) {
+        throw new Error(`libredb: refusing to remove ${lockPath} with --force: not a libredb lock file`);
+    }
+    rmSync(lockPath, { force: true });
+}

package/dist/cli/main.d.ts

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

package/dist/cli/main.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * cli/main.ts — the `libredb` bin shim.
+ *
+ * The only file that touches the real process: it wires process argv/stdout/
+ * stderr/exit code to the pure {@link run}. All behaviour lives in run.ts and is
+ * tested there; this glue is excluded from coverage (see bunfig.toml) because it
+ * cannot be exercised without spawning a process, and a behavioural smoke test
+ * (main.test.ts) runs the bin end-to-end instead.
+ */
+import { run } from "./run.js";
+process.exitCode = run(process.argv.slice(2), {
+    out: (line) => process.stdout.write(`${line}\n`),
+    err: (line) => process.stderr.write(`${line}\n`),
+});

package/dist/cli/readonly-fs.d.ts

@@ -0,0 +1,3 @@
+import type { FileSystem } from "../core.ts";
+/** Build a read-only {@link FileSystem} over `node:fs`. */
+export declare function readonlyFileSystem(): FileSystem;

package/dist/cli/readonly-fs.js

@@ -0,0 +1,41 @@
+/**
+ * cli/readonly-fs.ts — a read-only {@link FileSystem} for the inspection CLI.
+ *
+ * An edge, not the kernel: it carries no durability logic, only the node:fs
+ * calls a read needs. Inspection commands open a database purely to read it, but
+ * open() runs recovery, which truncates a torn tail — a write. This adapter makes
+ * that impossible: `append` and `fsync` refuse, and `truncate` is a no-op, so a
+ * crash-interrupted file is recovered correctly IN MEMORY (the torn tail is
+ * dropped from the returned entries) while the bytes on disk are left exactly as
+ * found. `size` and `read` are the obvious read syscalls.
+ */
+import { closeSync, openSync, readFileSync, statSync } from "node:fs";
+/** Build a read-only {@link FileSystem} over `node:fs`. */
+export function readonlyFileSystem() {
+    return {
+        open(path) {
+            const fd = openSync(path, "r"); // read-only; throws if the file is absent
+            return {
+                size() {
+                    return statSync(path).size;
+                },
+                read(offset, length) {
+                    return new Uint8Array(readFileSync(path)).subarray(offset, offset + length);
+                },
+                append() {
+                    throw new Error("libredb: read-only database; refusing to write");
+                },
+                fsync() {
+                    throw new Error("libredb: read-only database; refusing to write");
+                },
+                truncate() {
+                    // Deliberate no-op: a read must not alter the file. Recovery still
+                    // drops a torn tail from the in-memory state; the disk is untouched.
+                },
+                close() {
+                    closeSync(fd);
+                },
+            };
+        },
+    };
+}

package/dist/cli/run.d.ts

@@ -0,0 +1,7 @@
+/** Where the CLI writes its output. One call is one line; the sink adds newlines. */
+interface Io {
+    out(line: string): void;
+    err(line: string): void;
+}
+export declare function run(argv: string[], io: Io): number;
+export {};

package/dist/cli/run.js

@@ -0,0 +1,231 @@
+/**
+ * cli/run.ts — the LibreDB CLI as a pure function.
+ *
+ * `run(argv, io)` takes an argument vector and an IO sink and returns a process
+ * exit code. Keeping the whole CLI behind this seam — no direct stdout, no
+ * process.exit — is what makes every command and error path unit-testable; the
+ * bin shim (main.ts) is the only place that touches the real process.
+ *
+ * This is open-edge tooling over the public API, not kernel code: it adds no
+ * durability logic. Read commands (inspect/stats/get/scan) open through the
+ * read-only filesystem adapter so inspecting a file never mutates it. Write
+ * commands (set/delete/import) take an advisory lock first, and import commits
+ * all keys in one transaction so a bulk load is atomic.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { open } from "../index.js";
+import { catalog, isReservedKey } from "../lens/catalog.js";
+import { kv } from "../lens/kv.js";
+import { acquireLock } from "./lock.js";
+import { readonlyFileSystem } from "./readonly-fs.js";
+const encoder = new TextEncoder();
+const utf8 = (s) => encoder.encode(s);
+const USAGE = [
+    "libredb - inspect and edit .libredb files",
+    "",
+    "Usage:",
+    "  libredb inspect <path>             List each namespace, its kind, and table schemas",
+    "  libredb stats <path>               Summarize the file: size and namespace counts",
+    "  libredb get <path> <key>           Print the value stored at a key",
+    "  libredb scan <path> <prefix>       Print key=value for every key under a prefix",
+    "  libredb set <path> <key> <value>   Set a key to a value",
+    "  libredb delete <path> <key>        Remove a key",
+    "  libredb import <path> <file.json>  Bulk-set keys from a JSON object (one atomic commit)",
+    "",
+    "Options:",
+    "  --force                            Override an existing write lock",
+].join("\n");
+/** Open `path` read-only, run `fn`, and always close — so a read leaves the file
+ * exactly as it was (recovery cannot truncate a torn tail through this adapter). */
+const withReadDb = (path, fn) => {
+    const db = open({ path, fs: readonlyFileSystem() });
+    try {
+        return fn(db);
+    }
+    finally {
+        db.close();
+    }
+};
+/** Take the advisory lock, open `path` for writing, run `fn`, then always close
+ * and release — so a crash mid-write cannot leave the lock stranded. */
+const withWriteDb = (path, force, fn) => {
+    const lock = acquireLock(path, force);
+    try {
+        const db = open({ path });
+        try {
+            return fn(db);
+        }
+        finally {
+            db.close();
+        }
+    }
+    finally {
+        lock.release();
+    }
+};
+function inspect({ path, io }) {
+    return withReadDb(path, (db) => {
+        const registry = catalog(db);
+        io.out(`${path}  ${statSync(path).size} bytes`);
+        if (registry.size === 0) {
+            io.out("  (no catalogued namespaces)");
+            return 0;
+        }
+        for (const [name, entry] of registry) {
+            const schema = entry.schema === undefined ? "" : `  ${JSON.stringify(entry.schema)}`;
+            io.out(`  ${name}  ${entry.kind}${schema}`);
+        }
+        return 0;
+    });
+}
+function stats({ path, io }) {
+    return withReadDb(path, (db) => {
+        const registry = catalog(db);
+        const counts = { kv: 0, document: 0, relational: 0 };
+        for (const entry of registry.values())
+            counts[entry.kind]++;
+        io.out(`${path}  ${statSync(path).size} bytes  ${registry.size} namespaces`);
+        io.out(`  kv: ${counts.kv}  document: ${counts.document}  relational: ${counts.relational}`);
+        return 0;
+    });
+}
+function get({ path, args, io }) {
+    const [key] = args;
+    if (key === undefined) {
+        io.err("missing <key>");
+        return 2;
+    }
+    return withReadDb(path, (db) => {
+        const value = kv(db).get(key);
+        if (value === undefined) {
+            io.err(`key not found: ${key}`);
+            return 1;
+        }
+        io.out(value);
+        return 0;
+    });
+}
+function scan({ path, args, io }) {
+    const [prefix] = args;
+    if (prefix === undefined) {
+        io.err("missing <prefix>");
+        return 2;
+    }
+    return withReadDb(path, (db) => {
+        for (const entry of kv(db).prefix(prefix))
+            io.out(`${entry.key}=${entry.value}`);
+        return 0;
+    });
+}
+function set({ path, args, io, force }) {
+    const [key, value] = args;
+    if (key === undefined || value === undefined) {
+        io.err("missing <key> <value>");
+        return 2;
+    }
+    if (isReservedKey(key)) {
+        io.err(`refusing to write a reserved key: ${key}`);
+        return 2;
+    }
+    return withWriteDb(path, force, (db) => {
+        const { changed } = kv(db).set(key, value);
+        io.out(`set ${key} (${changed} changed)`);
+        return 0;
+    });
+}
+function remove({ path, args, io, force }) {
+    const [key] = args;
+    if (key === undefined) {
+        io.err("missing <key>");
+        return 2;
+    }
+    return withWriteDb(path, force, (db) => {
+        const { changed } = kv(db).delete(key);
+        io.out(`delete ${key} (${changed} removed)`);
+        return 0;
+    });
+}
+function importKeys({ path, args, io, force }) {
+    const [file] = args;
+    if (file === undefined) {
+        io.err("missing <file>");
+        return 2;
+    }
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        io.err("import expects a JSON object of string values");
+        return 2;
+    }
+    const pairs = [];
+    for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value !== "string") {
+            io.err("import expects a JSON object of string values");
+            return 2;
+        }
+        if (isReservedKey(key)) {
+            io.err(`import: refusing to write a reserved key: ${key}`);
+            return 2;
+        }
+        pairs.push([key, value]);
+    }
+    return withWriteDb(path, force, (db) => {
+        // One transaction for the whole load: a bulk import either lands entirely or,
+        // on a crash mid-write, not at all (recovery discards the torn record).
+        db.transact((tx) => {
+            for (const [key, value] of pairs)
+                tx.set(utf8(key), utf8(value));
+        });
+        io.out(`import ${pairs.length} keys`);
+        return 0;
+    });
+}
+/** The commands, keyed by name. Each takes the parsed {@link Ctx}. */
+const commands = {
+    inspect,
+    stats,
+    get,
+    scan,
+    set,
+    delete: remove,
+    import: importKeys,
+};
+export function run(argv, io) {
+    let positionals;
+    let values;
+    try {
+        const parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: { help: { type: "boolean", short: "h" }, force: { type: "boolean" } },
+        });
+        positionals = parsed.positionals;
+        values = parsed.values;
+    }
+    catch (error) {
+        io.err(error instanceof Error ? error.message : String(error));
+        return 2;
+    }
+    if (values.help === true || positionals.length === 0) {
+        io.out(USAGE);
+        return 0;
+    }
+    const command = positionals[0];
+    const handler = commands[command];
+    if (handler === undefined) {
+        io.err(`unknown command: ${command}`);
+        return 2;
+    }
+    const path = positionals[1];
+    if (path === undefined) {
+        io.err("missing <path>");
+        return 2;
+    }
+    try {
+        return handler({ path, args: positionals.slice(2), io, force: values.force === true });
+    }
+    catch (error) {
+        io.err(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}

package/dist/core.d.ts

@@ -20,7 +20,7 @@
  * and discards any record a crash left half-written.
  */
 /** The LibreDB package version. Kept in sync with package.json. */
-export declare const version = "0.0.4";
+export declare const version = "0.1.0";
 /**
  * A key in the kernel: an immutable sequence of bytes.
  *
@@ -94,9 +94,10 @@ export interface Database {
  * goes through this interface. That keeps the IO boundary explicit and in one
  * place (a readability gain), and it lets a test inject a simulated filesystem
  * to torture crash recovery without a real disk (DESIGN.md section 6.4). The
- * default is a thin real-`node:fs` adapter, so production behaviour is
- * unchanged. The interface is deliberately the SMALLEST set of operations the
- * WAL performs and nothing more.
+ * kernel carries NO default filesystem: a path-backed open must be given one.
+ * The Node entry (index.ts) supplies a `node:fs`-backed adapter by default; the
+ * browser entry supplies none. The interface is deliberately the SMALLEST set
+ * of operations the WAL performs and nothing more.
  */
 export interface FileSystem {
     /** Open the log file at `path` for reading and appending, creating it if it
@@ -133,10 +134,12 @@ export interface WalFile {
 export interface OpenOptions {
     readonly path?: string;
     /**
-     * The filesystem the write-ahead log runs on. Defaults to a thin real
-     * `node:fs` adapter. Injecting one lets tests simulate crashes and IO faults
-     * deterministically (DESIGN.md section 6.4). Ignored when there is no `path`
-     * (an in-memory database never touches a filesystem).
+     * The filesystem the write-ahead log runs on. Required for a path-backed open:
+     * the kernel carries no default, so omitting it with a `path` throws. (The
+     * Node entry defaults this to a `node:fs` adapter; the browser entry has none.)
+     * Injecting one lets tests simulate crashes and IO faults deterministically
+     * (DESIGN.md section 6.4). Ignored when there is no `path` (an in-memory
+     * database never touches a filesystem).
      */
     readonly fs?: FileSystem;
 }

package/dist/core.js

@@ -19,9 +19,8 @@
  * transactions, and a write-ahead log for durability. Recovery replays that log
  * and discards any record a crash left half-written.
  */
-import { closeSync, fsyncSync, openSync, readFileSync, statSync, truncateSync, writeSync } from "node:fs";
 /** The LibreDB package version. Kept in sync with package.json. */
-export const version = "0.0.4";
+export const version = "0.1.0";
 /**
  * Compare two keys by unsigned byte-lexicographic order: the first differing
  * byte decides, and if one key is a prefix of the other the shorter sorts
@@ -245,44 +244,6 @@ function recover(file) {
         file.truncate(offset);
     return entries;
 }
-/**
- * The default {@link FileSystem}: a thin adapter over `node:fs`. Each method is
- * the obvious synchronous syscall, so the seam adds an interface, not behaviour.
- * Appends go through one append-mode descriptor (creating the file if missing);
- * reads, size and truncate work by path, matching how the WAL has always
- * reached the disk.
- */
-function nodeFileSystem() {
-    return {
-        open(path) {
-            const fd = openSync(path, "a"); // append-only; creates the file if missing
-            return {
-                size() {
-                    return statSync(path).size;
-                },
-                read(offset, length) {
-                    // A fresh Uint8Array so the returned slice is an independent copy, not
-                    // a view aliasing a shared Buffer pool.
-                    return new Uint8Array(readFileSync(path)).subarray(offset, offset + length);
-                },
-                append(bytes) {
-                    for (let written = 0; written < bytes.length;) {
-                        written += writeSync(fd, bytes, written);
-                    }
-                },
-                fsync() {
-                    fsyncSync(fd);
-                },
-                truncate(length) {
-                    truncateSync(path, length);
-                },
-                close() {
-                    closeSync(fd);
-                },
-            };
-        },
-    };
-}
 /** Open the log file at `path` on `fs`, recover the store from it, and return
  * the recovered entries together with a {@link Log} that appends future commits
  * to the same file. */
@@ -317,7 +278,20 @@ export const open = (options) => {
     let committed;
     let log;
     if (options?.path !== undefined) {
-        const opened = openLog(options.path, options.fs ?? nodeFileSystem());
+        // A path must actually name a file: reject the degenerate empty string here
+        // with a clear error, rather than letting it reach the filesystem and
+        // surface a raw, adapter-specific failure (e.g. node's ENOENT for "").
+        if (options.path === "") {
+            throw new Error("libredb: open({ path }) requires a non-empty path");
+        }
+        // The kernel is runtime-agnostic: it carries no default filesystem, so a
+        // path-backed open MUST be given one. The default node:fs adapter lives at
+        // the package edge (index.ts wires it in); the browser entry has none. A
+        // pathless, in-memory open never reaches here and needs no filesystem.
+        if (options.fs === undefined) {
+            throw new Error("libredb: open({ path }) requires a filesystem; none was provided");
+        }
+        const opened = openLog(options.path, options.fs);
         committed = opened.entries;
         log = opened.log;
     }

package/dist/index.d.ts

@@ -10,8 +10,18 @@
  * {@link isReservedKey} (with {@link RESERVED_MARKER} / {@link CATALOG_PREFIX})
  * lets a raw-KV tool hide engine-internal keys instead of hardcoding the layout.
  */
-export { version, open } from "./core.ts";
-export type { Database, OpenOptions } from "./core.ts";
+import { type Open } from "./core.ts";
+export { version } from "./core.ts";
+export type { Database, FileSystem, OpenOptions, WalFile } from "./core.ts";
+/**
+ * Open a LibreDB database on Node or Bun. Identical to the kernel's
+ * {@link import("./core.ts").open}, except a path-backed open with no `fs`
+ * defaults to the real `node:fs` adapter — so `open({ path })` is durable out of
+ * the box. A pathless open stays in-memory; an explicit `fs` is passed through.
+ * The browser entry (`@libredb/libredb/browser`) omits this default so it never
+ * imports `node:fs`.
+ */
+export declare const open: Open;
 export { kv } from "./lens/kv.ts";
 export type { Kv, KvEntry } from "./lens/kv.ts";
 export { doc } from "./lens/document.ts";

package/dist/index.js

@@ -10,7 +10,20 @@
  * {@link isReservedKey} (with {@link RESERVED_MARKER} / {@link CATALOG_PREFIX})
  * lets a raw-KV tool hide engine-internal keys instead of hardcoding the layout.
  */
-export { version, open } from "./core.js";
+import { open as openKernel } from "./core.js";
+import { nodeFileSystem } from "./adapter/node-fs.js";
+export { version } from "./core.js";
+/**
+ * Open a LibreDB database on Node or Bun. Identical to the kernel's
+ * {@link import("./core.ts").open}, except a path-backed open with no `fs`
+ * defaults to the real `node:fs` adapter — so `open({ path })` is durable out of
+ * the box. A pathless open stays in-memory; an explicit `fs` is passed through.
+ * The browser entry (`@libredb/libredb/browser`) omits this default so it never
+ * imports `node:fs`.
+ */
+export const open = (options) => options?.path !== undefined && options.fs === undefined
+    ? openKernel({ ...options, fs: nodeFileSystem() })
+    : openKernel(options);
 export { kv } from "./lens/kv.js";
 export { doc } from "./lens/document.js";
 export { table } from "./lens/relational.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libredb/libredb",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "description": "A small, readable, embeddable, multi-model database. One ordered key-value core, thin model lenses on top.",
   "keywords": [
     "database",
@@ -23,6 +23,9 @@
   },
   "type": "module",
   "license": "MIT",
+  "bin": {
+    "libredb": "./dist/cli/main.js"
+  },
   "files": [
     "dist"
   ],
@@ -34,8 +37,16 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "browser": {
+        "types": "./dist/browser.d.ts",
+        "import": "./dist/browser.js"
+      },
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
     }
   },
   "sideEffects": false,
@@ -50,6 +61,7 @@
     "lint": "oxlint && eslint .",
     "test": "bun test --coverage",
     "build": "tsc --project tsconfig.build.json",
+    "compile": "bun build --compile src/cli/main.ts --outfile libredb",
     "size": "size-limit",
     "attw": "rm -rf .attw && bun pm pack --quiet --destination .attw && attw .attw/*.tgz --profile esm-only",
     "publint": "publint",