llm-cli-gateway 1.17.8 → 2.0.0

package/CHANGELOG.md

@@ -4,6 +4,188 @@ All notable changes to the llm-cli-gateway project.
 
 ## Unreleased
 
+## [2.0.0] - 2026-06-04: node:sqlite migration — native module out of the prod graph
+
+Major release. Persistence moves from the native `better-sqlite3` binding to
+Node's built-in `node:sqlite` module behind a thin adapter. The entire
+1.17.6-1.17.8 supply-chain incident class — every one of which traced to
+`better-sqlite3`'s install path (`prebuild-install → tar-fs → tar-stream`),
+not its runtime — is now **structurally** gone: the production dependency
+graph contains zero native modules, zero install scripts, and no
+`prebuild-install`/`tar-fs`/`tar-stream` chain. Verified end to end against a
+verdaccio registry reproduction (`scripts/verify-registry-install.sh`):
+consumer tree reified at 94 packages (down from ~124 in 1.17.9), `npm ls`
+exits 0, and no `better-sqlite3`/`tar-stream`/`prebuild-install` appears
+anywhere in the consumer tree.
+
+### BREAKING
+
+- **`engines.node` is now `>=24.4.0`** (was `>=20.0.0`). Node 20 is EOL
+  (April 2026). The 24.4 floor is required because `node:sqlite`'s
+  `allowBareNamedParameters` defaults to `true` only from Node 24.4 — the
+  persistence layer binds bare `{ id: ... }` objects to `@id` placeholders
+  throughout, and on 24.0-24.3 that would need a per-statement
+  `setAllowBareNamedParameters(true)` call. The adapter unit tests assert
+  bare-name binding works, so a regression in either direction is caught.
+
+### Added
+
+- `src/sqlite-driver.ts`: thin adapter over `node:sqlite`'s `DatabaseSync`.
+  Exports `openDatabase`, `openReadOnly`, and a `GatewayDatabase` /
+  `GatewayStatement` surface (`exec`/`prepare`/`run`/`get`/`all`/
+  `withTransaction`/`close`). It is the ONLY production module that touches
+  `node:sqlite`; the release security audit hard-fails if any other
+  production module references it. Preserves the flight recorder's
+  graceful-degradation path (constructor failure → recorder disabled, gateway
+  still runs).
+- Read-only `queryRequests` connection: `openReadOnly` opens the DB with
+  `{ readOnly: true }`, so write-disguised-as-read SQL fails at the SQLite
+  engine level (`SQLITE_READONLY`). This is **stronger** than the old
+  better-sqlite3 `stmt.readonly` JS-property check it replaces — enforcement
+  is at the engine, not in JavaScript — with one belt-and-braces guard: the
+  read-only connection also rejects `VACUUM`/`VACUUM INTO`, the one statement
+  that writes a new file to disk despite `{ readOnly: true }` (and that
+  `stmt.readonly` previously blocked). ATTACH-then-write and
+  `writable_schema` schema edits are already engine-rejected.
+- Cross-engine WAL crash-recovery fixtures in both directions
+  (`src/__tests__/cross-engine-wal.test.ts`): a `better-sqlite3`-written DB
+  (SQLite 3.53.1) with live `-wal`/`-shm` from a simulated unclean stop is
+  opened and exercised under `node:sqlite` (3.51.3), and the reverse for the
+  rollback direction. These gate the "zero data migration" claim across the
+  engine-version skew.
+
+### Changed
+
+- `better-sqlite3` **moved from `dependencies` to `devDependencies`** (same
+  `^12.10.0` range; `@types/better-sqlite3` stays in devDependencies). It is
+  retained at dev time deliberately: two suites seed legacy-schema DB files
+  with it (`src/__tests__/flight-recorder.test.ts`,
+  `src/__tests__/test-veracity-regressions-slice-kappa.test.ts`) to simulate
+  databases written by pre-2.0.0 gateways — that realism is the point, and it
+  makes them standing old-engine-writer → node:sqlite-reader coverage on every
+  CI run — and the cross-engine WAL fixtures need a better-sqlite3 writer.
+  Consumers never see it: devDependencies do not install transitively, and the
+  prod-only shrinkwrap excludes the whole subtree.
+- `flight-recorder.ts` / `job-store.ts` now open SQLite through the adapter
+  (`openDatabase`/`openReadOnly`/`withTransaction`) instead of
+  `require("better-sqlite3")`. SQL, schema, migrations, and pragmas are
+  unchanged.
+- `package.json#overrides`: the `tar-stream` pin is **removed** (the chain
+  that needed it is gone from the prod graph). The `type-is` and `content-type`
+  pins stay — unrelated to this chain.
+- `scripts/release-security-audit.sh`: the `consumerAdvisory` carve-out is
+  **deleted** — blocked `tar-stream` versions are now hard-fail tripwires
+  everywhere (the chain no longer exists in any prod tree). The packed-consumer
+  policy now hard-fails on ANY `tar-stream` in the consumer tree (was an
+  advisory warning). The repo-lockfile tripwire skips dev-only entries so the
+  deliberate devDependency `tar-stream@2.2.0` does not false-fail, while still
+  hard-failing any blocked version that re-enters the prod graph. The
+  better-sqlite3 PRAGMA scan is repointed at the adapter: it now also asserts
+  `node:sqlite` is referenced only by `src/sqlite-driver.ts`.
+- `scripts/pre-release.sh`: the better-sqlite3 native-binding sanity guard is
+  removed (the test suite exercises the binding as a devDep and fails loudly if
+  broken); the `npm ls tar-stream` step is replaced by an absence assertion
+  against the generated prod-only shrinkwrap
+  (`better-sqlite3`/`prebuild-install`/`tar-fs`/`tar-stream` must be absent).
+- `scripts/verify-registry-install.sh`: assertions updated for 2.0.0 —
+  `tar-stream`/`better-sqlite3`/`prebuild-install` must be ABSENT from the
+  consumer tree; consumer `npm ls` must exit 0 (the out-of-range pin that
+  caused ELSPROBLEMS is gone); a `node:sqlite` runtime smoke
+  (`new DatabaseSync(':memory:')`) confirms the engine; and the reified package
+  count is asserted at 94 ±2.
+- README, `socket.yml`, and `docs/personal-mcp/RELEASE_READINESS.md` updated to
+  reflect the node:sqlite reality (no native binding, no install scripts,
+  Node >=24.4.0, adapter-isolation audit replacing the PRAGMA-helper note).
+
+### Rollback
+
+Reverting the 2.0.0 commit re-adds `better-sqlite3` to `dependencies`, the
+`tar-stream` override, and the audit advisory carve-out. DB files are
+compatible in both directions — exactly what the cross-engine WAL fixtures
+prove (the rollback claim inherits that gate; it is not asserted
+independently).
+
+## [1.17.9] - 2026-06-04: prod-only shrinkwrap + registry-fidelity verification
+
+Patch release shipping a prod-only `npm-shrinkwrap.json` and correcting the
+1.17.8 record: registry installs **do** honour the published shrinkwrap (the
+real distribution channel), so consumers of `npm install llm-cli-gateway`
+already get the pinned `tar-stream@3.1.7`. The 1.17.8 changelog called the
+shrinkwrap "inert today because of npm/cli#7977" — that was wrong. npm/cli#7977
+covers a remote-registry edge case; what we actually reproduced on this host
+(npm 11.12.1) is that **local-tarball** installs ignore a nested shrinkwrap
+(npm/cli#5349/#5325 class), while registry installs honour it via the
+packument's `hasShrinkwrap` flag. This release verifies the registry path end
+to end with a verdaccio reproduction.
+
+### Added
+
+- `scripts/make-prod-shrinkwrap.mjs`: deterministic generator that projects
+  `package-lock.json` into a prod-only `npm-shrinkwrap.json` — drops every
+  dev-only (`dev === true`) `packages` entry and deletes the root
+  `devDependencies` field. A byte-identical copy of the lockfile (1.17.8's
+  approach) reified all ~316 packages into consumer trees (npm/cli#4323); the
+  prod-only projection ships ~124 and eliminates the dev-dep bloat for registry
+  consumers. Output is byte-deterministic; the security audit regenerates and
+  compares for parity. `optional` (and any `devOptional`) entries are kept —
+  prod installs need them. The shrinkwrap is GENERATED at pack/publish time
+  and never committed: a committed npm-shrinkwrap.json is treated by
+  `npm ci`/`npm install` as the authoritative lockfile, and the prod-only
+  projection (no dev deps) breaks every dev/CI install with EUSAGE "lock
+  file out of sync" — discovered when the first 1.17.9 release attempt
+  failed all four `npm ci`-based workflows. `.gitignore` now covers it; the
+  CI, publish, and tag-release workflows generate it just before the
+  security audit / pack / publish steps.
+- `scripts/verify-registry-install.sh`: registry-fidelity gate (run by
+  `scripts/pre-release.sh` and standalone). Publishes the current tree to an
+  ephemeral verdaccio, installs it into a fresh consumer dir, and asserts (a)
+  `tar-stream` resolves to `3.1.7` (shrinkwrap honoured), (b) no dev-dep markers
+  (`vitest`/`typescript`/`eslint`/`prettier`) in the consumer tree, (c) the
+  installed bin prints the expected version, (d) `better-sqlite3` loads from the
+  installed package (binding built through the pinned tar chain). The publish /
+  consumer-install / assertion flow runs entirely against throwaway temp dirs
+  (registry storage, npm cache, userconfig) and the localhost registry — the
+  package under test never reaches the public registry. One exception: the
+  verdaccio bootstrap itself (`npx --yes verdaccio`) resolves through the user's
+  normal npm config and npx cache (unavoidable for an ephemeral tool), touching
+  only verdaccio's own packages. Sets the packument's
+  `_hasShrinkwrap` flag to mirror what npmjs sets at publish (verdaccio does not
+  compute it), so the reproduction faithfully matches the real registry. Logs
+  the observed reified-package count (not hard-asserted in this release).
+
+### Changed
+
+- `scripts/pre-release.sh` / `scripts/refresh-release-lockfile.sh`: replace
+  `cp package-lock.json npm-shrinkwrap.json` with
+  `node scripts/make-prod-shrinkwrap.mjs`; pre-release now also runs
+  `scripts/verify-registry-install.sh` after the shrinkwrap regeneration and the
+  release gate.
+- `scripts/release-security-audit.sh`: the shrinkwrap parity gate no longer does
+  byte-identity against the lockfile (that no longer holds — the shrinkwrap is a
+  prod-only projection). It regenerates the expected projection from
+  `package-lock.json` via the same deterministic generator into a temp file and
+  `cmp -s` against the shipped `npm-shrinkwrap.json`.
+
+### Fixed (record correction)
+
+- The 1.17.8 claim that the shipped shrinkwrap is "inert today because of
+  npm/cli#7977" was incorrect. Registry installs honour it (verified via the new
+  verdaccio reproduction); only **local-tarball** installs ignore it
+  (npm/cli#5349/#5325 class — our live repro). The packed-consumer-install
+  advisory in the audit is requalified accordingly: registry installs get
+  `tar-stream@3.1.7`, local-tarball installs still resolve `tar-stream@2.2.0`,
+  and the advisory (warn, not fail) stays until Phase B drops `better-sqlite3`
+  from the prod graph. The 1.17.8 entry itself is left unedited.
+
+### Known residuals
+
+- Consumer `npm ls` exits ELSPROBLEMS: the pinned `tar-stream@3.1.7` sits
+  outside `tar-fs`'s `^2.1.4` range. Inherent to the out-of-range pin; disappears
+  in 2.0.0 (Phase B / node:sqlite) when the `better-sqlite3 → prebuild-install
+  → tar-fs` chain leaves the prod graph entirely.
+- Local-tarball installs still resolve `tar-stream@2.2.0` (shrinkwrap ignored on
+  that path); the audit's advisory carve-out stays until Phase B.
+
 ## [1.17.8] - 2026-06-04: release-audit integrity fix + shrinkwrap groundwork
 
 Patch release fixing a masking bug in the release security audit and documenting

package/README.md

@@ -214,6 +214,8 @@ Opt-in flags (all default off) live under `[cache_awareness]` in `~/.llm-cli-gat
 
 ## Prerequisites
 
+**Node.js >= 24.4.0** is required (`engines.node` in `package.json`). The gateway uses Node's built-in `node:sqlite` module for persistence — there is no native binding to compile and no install scripts run. The 24.4 floor is where `allowBareNamedParameters` defaults to `true`, which the persistence layer relies on.
+
 Before using this gateway, you need to install the CLI tools you want to use:
 
 ### Claude Code CLI
@@ -1180,8 +1182,8 @@ If you're vetting `llm-cli-gateway` through [Socket](https://socket.dev/npm/pack
 | **Network access**               | `src/http-transport.ts` opens an HTTP MCP transport when started via `npm run start:http`. `src/endpoint-exposure.ts` issues a HEAD probe to verify configured public/tunnel URLs. Socket also flagged `dist/upstream-contracts.js` in v1.17.2 from descriptive text, not a network call. | The transport binds to `127.0.0.1` by default and requires `LLM_GATEWAY_AUTH_TOKEN` to be set. The default stdio MCP entry point (`npm start`) opens no sockets. `src/upstream-contracts.ts` stores provider CLI metadata and imports no HTTP client APIs.                                                                                                  |
 | **Shell access**                 | `src/executor.ts` uses `child_process.spawn(cmd, args, …)` to invoke the underlying LLM CLIs.                                                                                                    | `spawn` is called with an argument array and **never** `shell: true`, so there is no shell interpolation path for caller input. The command name is restricted to an allow-list of known CLI binaries (`claude`, `codex`, `gemini`, `grok`, `vibe`).                                                                                                         |
 | **Uses eval**                    | None in our source. Transitive: `@modelcontextprotocol/sdk` → `ajv@8` uses `new Function(...)` in `ajv/dist/compile/index.js` to compile JSON Schema validators.                                 | This is ajv's standard codegen path. Only known schemas (defined in our source and the MCP SDK) flow into it; no caller-supplied data ever reaches the compiled function body.                                                                                                                                                                               |
-| **better-sqlite3 PRAGMA helper** | Transitive: `better-sqlite3/lib/methods/pragma.js` interpolates its caller-provided `source` into a `PRAGMA ${source}` statement.                                                                | We do not call `db.pragma()` from production source. Internal SQLite setup uses fixed literal `db.exec("PRAGMA ...")` statements, and `npm run security:audit` fails the release if production code reintroduces `.pragma()` calls.                                                                                                                          |
-| **Dependency ownership**         | A handful of small transitive packages (e.g. `bindings` via `better-sqlite3`, `media-typer` via `@modelcontextprotocol/sdk`) trip Socket's "unstable ownership" or "obfuscated code" heuristics. | These are pinned, well-known micro-deps in the Node ecosystem with no known issues. We pin direct override versions of `content-type` and `type-is` in `package.json#overrides`. Our previous direct dependency on `toml@3.0.0` (also single-maintainer, last released 2020) was replaced with the actively-maintained `smol-toml` to reduce inherited risk. |
+| **SQLite adapter isolation**     | Persistence uses Node's built-in `node:sqlite` module (no native binding, no install scripts) through a single adapter, `src/sqlite-driver.ts`.                                                  | `node:sqlite` is touched by exactly one production module (the adapter); every other module talks to SQLite through its typed surface. We never call any `db.pragma()` helper (it does not exist on `node:sqlite`); SQLite setup uses fixed literal `db.exec("PRAGMA ...")` statements. `npm run security:audit` fails the release if production code references `node:sqlite` outside the adapter or reintroduces a `.pragma()` call.                                                            |
+| **Dependency ownership**         | A handful of small transitive packages (e.g. `media-typer` via `@modelcontextprotocol/sdk`) trip Socket's "unstable ownership" or "obfuscated code" heuristics.                                  | These are pinned, well-known micro-deps in the Node ecosystem with no known issues. We pin direct override versions of `content-type` and `type-is` in `package.json#overrides`. As of 2.0.0 the prod graph carries no native module (`better-sqlite3` moved to devDependencies; `node:sqlite` is built into Node), eliminating the entire `prebuild-install`/`tar-fs`/`tar-stream` install-time chain. Our earlier direct dependency on `toml@3.0.0` was replaced with `smol-toml`.        |
 
 See [`socket.yml`](./socket.yml) for the same context in machine-readable form.
 

package/dist/flight-recorder.d.ts

@@ -34,6 +34,9 @@ interface LoggerLike {
 export declare function resolveFlightRecorderDbPath(): string | null;
 export declare class FlightRecorder {
     private db;
+    private readOnlyDb;
+    private closed;
+    private readonly dbPath;
     private insertStartTxn;
     private updateCompleteTxn;
     constructor(dbPath: string);

package/dist/flight-recorder.js

@@ -1,10 +1,10 @@
-import { chmodSync, existsSync, mkdirSync } from "fs";
+import { chmodSync } from "fs";
 import os from "os";
 import path from "path";
-import { createRequire } from "module";
+import { openDatabase, openReadOnly } from "./sqlite-driver.js";
 const MAX_THINKING_BYTES = 1_000_000;
 function ensureRequestsCacheColumns(db) {
-    const rows = db.prepare("PRAGMA table_info(requests)").all?.() ?? [];
+    const rows = db.prepare("PRAGMA table_info(requests)").all();
     const names = new Set(rows.map((row) => (row && typeof row.name === "string" ? row.name : "")));
     if (!names.has("cache_read_tokens")) {
         db.exec("ALTER TABLE requests ADD COLUMN cache_read_tokens INTEGER");
@@ -14,7 +14,7 @@ function ensureRequestsCacheColumns(db) {
     }
 }
 function ensureStablePrefixColumns(db) {
-    const rows = db.prepare("PRAGMA table_info(requests)").all?.() ?? [];
+    const rows = db.prepare("PRAGMA table_info(requests)").all();
     const names = new Set(rows.map((row) => (row && typeof row.name === "string" ? row.name : "")));
     if (!names.has("stable_prefix_hash")) {
         db.exec("ALTER TABLE requests ADD COLUMN stable_prefix_hash TEXT");
@@ -25,7 +25,7 @@ function ensureStablePrefixColumns(db) {
     db.exec("CREATE INDEX IF NOT EXISTS idx_requests_stable_hash ON requests(stable_prefix_hash)");
 }
 function ensureCacheControlBlocksColumn(db) {
-    const rows = db.prepare("PRAGMA table_info(requests)").all?.() ?? [];
+    const rows = db.prepare("PRAGMA table_info(requests)").all();
     const names = new Set(rows.map((row) => (row && typeof row.name === "string" ? row.name : "")));
     if (!names.has("cache_control_blocks")) {
         db.exec("ALTER TABLE requests ADD COLUMN cache_control_blocks INTEGER");
@@ -77,16 +77,14 @@ function truncateThinkingBlocks(blocks) {
 }
 export class FlightRecorder {
     db;
+    readOnlyDb = null;
+    closed = false;
+    dbPath;
     insertStartTxn;
     updateCompleteTxn;
     constructor(dbPath) {
-        const require = createRequire(import.meta.url);
-        const BetterSqlite3 = require("better-sqlite3");
-        const directory = path.dirname(dbPath);
-        if (!existsSync(directory)) {
-            mkdirSync(directory, { recursive: true });
-        }
-        this.db = new BetterSqlite3(dbPath);
+        this.dbPath = dbPath;
+        this.db = openDatabase(dbPath);
         this.db.exec("PRAGMA journal_mode = WAL");
         this.db.exec("PRAGMA foreign_keys = ON");
         this.db.exec(`
@@ -165,7 +163,7 @@ export class FlightRecorder {
       INSERT INTO gateway_metadata (request_id, async_job_id, status)
       VALUES (@request_id, @async_job_id, 'started')
     `);
-        this.insertStartTxn = this.db.transaction((entry) => {
+        this.insertStartTxn = this.db.withTransaction((entry) => {
             insertRequest.run({
                 id: entry.correlationId,
                 cli: entry.cli,
@@ -206,7 +204,7 @@ export class FlightRecorder {
           status = @status
       WHERE request_id = @id AND status = 'started'
     `);
-        this.updateCompleteTxn = this.db.transaction((correlationId, result) => {
+        this.updateCompleteTxn = this.db.withTransaction((correlationId, result) => {
             const thinkingBlocks = result.thinkingBlocks && result.thinkingBlocks.length > 0
                 ? JSON.stringify(truncateThinkingBlocks(result.thinkingBlocks))
                 : null;
@@ -240,18 +238,22 @@ export class FlightRecorder {
         this.updateCompleteTxn(correlationId, result);
     }
     queryRequests(sql, ...params) {
-        const stmt = this.db.prepare(sql);
-        if (stmt.readonly === false) {
-            throw new Error("FlightRecorder.queryRequests refuses non-readonly SQL — use a transaction or a separate write surface for INSERT/UPDATE/DELETE.");
+        if (this.closed) {
+            throw new Error("flight recorder is closed");
         }
-        if (!stmt.all) {
-            return [];
+        if (!this.readOnlyDb) {
+            this.readOnlyDb = openReadOnly(this.dbPath);
         }
-        return stmt.all(...params);
+        return this.readOnlyDb.prepare(sql).all(...params);
     }
     flush() {
     }
     close() {
+        this.closed = true;
+        if (this.readOnlyDb) {
+            this.readOnlyDb.close();
+            this.readOnlyDb = null;
+        }
         this.db.close();
     }
 }

package/dist/job-store.js

@@ -1,8 +1,8 @@
-import { chmodSync, existsSync, mkdirSync } from "fs";
+import { chmodSync } from "fs";
 import os from "os";
 import path from "path";
 import { createHash } from "crypto";
-import { createRequire } from "module";
+import { openDatabase } from "./sqlite-driver.js";
 import { noopLogger } from "./logger.js";
 export function resolveJobStoreDbPath() {
     const configured = process.env.LLM_GATEWAY_JOBS_DB ?? process.env.LLM_GATEWAY_LOGS_DB;
@@ -74,13 +74,7 @@ export class SqliteJobStore {
     deleteExpiredStmt;
     constructor(dbPath, logger = noopLogger, options = {}) {
         this.logger = logger;
-        const require = createRequire(import.meta.url);
-        const BetterSqlite3 = require("better-sqlite3");
-        const directory = path.dirname(dbPath);
-        if (!existsSync(directory)) {
-            mkdirSync(directory, { recursive: true });
-        }
-        this.db = new BetterSqlite3(dbPath);
+        this.db = openDatabase(dbPath);
         this.db.exec("PRAGMA journal_mode = WAL");
         this.db.exec("PRAGMA synchronous = NORMAL");
         this.db.exec(`
@@ -211,7 +205,7 @@ export class SqliteJobStore {
     markOrphanedOnStartup() {
         const now = new Date().toISOString();
         const expiresAt = new Date(Date.now() + this.retentionMs).toISOString();
-        const rows = (this.selectRunningOrphansStmt.all?.() ?? []);
+        const rows = this.selectRunningOrphansStmt.all();
         const orphaned = rows.map(row => ({
             id: row.id,
             correlationId: row.correlation_id,
@@ -221,12 +215,12 @@ export class SqliteJobStore {
             exitCode: row.exit_code,
         }));
         const result = this.markOrphanedStmt.run(now, expiresAt);
-        return { count: result?.changes ?? 0, orphaned };
+        return { count: Number(result.changes), orphaned };
     }
     evictExpired() {
         const now = new Date().toISOString();
         const result = this.deleteExpiredStmt.run(now);
-        return result?.changes ?? 0;
+        return Number(result.changes);
     }
     close() {
         try {

package/dist/sqlite-driver.d.ts

@@ -0,0 +1,16 @@
+export interface GatewayStatement {
+    run(...args: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    get(...args: unknown[]): unknown;
+    all(...args: unknown[]): unknown[];
+}
+export interface GatewayDatabase {
+    exec(sql: string): void;
+    prepare(sql: string): GatewayStatement;
+    withTransaction<A extends unknown[]>(fn: (...args: A) => void): (...args: A) => void;
+    close(): void;
+}
+export declare function openDatabase(dbPath: string): GatewayDatabase;
+export declare function openReadOnly(dbPath: string): GatewayDatabase;

package/dist/sqlite-driver.js

@@ -0,0 +1,149 @@
+import { existsSync, mkdirSync } from "fs";
+import path from "path";
+import { createRequire } from "module";
+function loadNodeSqlite() {
+    const require = createRequire(import.meta.url);
+    return require("node:sqlite");
+}
+function wrapStatement(stmt) {
+    return {
+        run(...args) {
+            return stmt.run(...args);
+        },
+        get(...args) {
+            return stmt.get(...args);
+        },
+        all(...args) {
+            return stmt.all(...args);
+        },
+    };
+}
+function statementLeadingKeywords(sql) {
+    const keywords = [];
+    let i = 0;
+    const skipTrivia = () => {
+        for (;;) {
+            while (i < sql.length && /\s|;/.test(sql[i] ?? ""))
+                i++;
+            if (sql.startsWith("--", i)) {
+                i += 2;
+                while (i < sql.length && sql[i] !== "\n")
+                    i++;
+                continue;
+            }
+            if (sql.startsWith("/*", i)) {
+                const end = sql.indexOf("*/", i + 2);
+                i = end === -1 ? sql.length : end + 2;
+                continue;
+            }
+            break;
+        }
+    };
+    const skipQuoted = (quote) => {
+        i++;
+        while (i < sql.length) {
+            if (sql[i] === quote) {
+                if (sql[i + 1] === quote) {
+                    i += 2;
+                    continue;
+                }
+                i++;
+                return;
+            }
+            i++;
+        }
+    };
+    while (i < sql.length) {
+        skipTrivia();
+        const m = /^[a-zA-Z]+/.exec(sql.slice(i));
+        if (m) {
+            keywords.push(m[0].toUpperCase());
+        }
+        while (i < sql.length && sql[i] !== ";") {
+            if (sql.startsWith("--", i)) {
+                i += 2;
+                while (i < sql.length && sql[i] !== "\n")
+                    i++;
+            }
+            else if (sql.startsWith("/*", i)) {
+                const end = sql.indexOf("*/", i + 2);
+                i = end === -1 ? sql.length : end + 2;
+            }
+            else if (sql[i] === "'" || sql[i] === '"' || sql[i] === "`") {
+                skipQuoted(sql[i]);
+            }
+            else if (sql[i] === "[") {
+                i++;
+                while (i < sql.length && sql[i] !== "]")
+                    i++;
+                if (i < sql.length)
+                    i++;
+            }
+            else {
+                i++;
+            }
+        }
+    }
+    return keywords;
+}
+class GatewayDatabaseImpl {
+    db;
+    readOnly;
+    inTransaction = false;
+    constructor(db, readOnly = false) {
+        this.db = db;
+        this.readOnly = readOnly;
+    }
+    guardReadOnly(sql) {
+        if (this.readOnly && statementLeadingKeywords(sql).includes("VACUUM")) {
+            throw new Error("read-only connection rejects VACUUM (writes to disk despite readOnly)");
+        }
+    }
+    exec(sql) {
+        this.guardReadOnly(sql);
+        this.db.exec(sql);
+    }
+    prepare(sql) {
+        this.guardReadOnly(sql);
+        return wrapStatement(this.db.prepare(sql));
+    }
+    withTransaction(fn) {
+        return (...args) => {
+            if (this.inTransaction) {
+                throw new Error("nested transaction");
+            }
+            this.db.exec("BEGIN");
+            this.inTransaction = true;
+            try {
+                fn(...args);
+                this.db.exec("COMMIT");
+            }
+            catch (error) {
+                try {
+                    this.db.exec("ROLLBACK");
+                }
+                catch {
+                }
+                throw error;
+            }
+            finally {
+                this.inTransaction = false;
+            }
+        };
+    }
+    close() {
+        this.db.close();
+    }
+}
+export function openDatabase(dbPath) {
+    const { DatabaseSync } = loadNodeSqlite();
+    const directory = path.dirname(dbPath);
+    if (!existsSync(directory)) {
+        mkdirSync(directory, { recursive: true });
+    }
+    return new GatewayDatabaseImpl(new DatabaseSync(dbPath));
+}
+export function openReadOnly(dbPath) {
+    const { DatabaseSync } = loadNodeSqlite();
+    return new GatewayDatabaseImpl(new DatabaseSync(dbPath, { readOnly: true }), true);
+}