@jitsusama/agentic-harness.core 0.1.0

package/dist/lsp/standalone/server.js

@@ -0,0 +1,521 @@
+/**
+ * One language server, spawned and supervised over stdio.
+ *
+ * Owns the JSON-RPC connection, the initialize handshake and
+ * the open-document set, and pulls diagnostics on demand.
+ * Positions cross the boundary here: the tool's
+ * byte columns convert to LSP's UTF-16 columns on the way in
+ * and back on the way out.
+ */
+import { spawn } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { basename } from "node:path";
+import { createMessageConnection, StreamMessageReader, StreamMessageWriter, } from "vscode-jsonrpc/node";
+import { CodeActionRequest, ConfigurationRequest, DefinitionRequest, DidChangeTextDocumentNotification, DidOpenTextDocumentNotification, DocumentDiagnosticReportKind, DocumentDiagnosticRequest, DocumentSymbolRequest, HoverRequest, InitializedNotification, InitializeRequest, PublishDiagnosticsNotification, ReferencesRequest, RegistrationRequest, RenameRequest, UnregistrationRequest, WorkDoneProgressCreateRequest, WorkspaceFoldersRequest, WorkspaceSymbolRequest, } from "vscode-languageserver-protocol";
+import { applyProtocolEdits, fileToUri, fromProtocolRange, languageIdFor, toLines, toProtocolPosition, uriToFile, } from "./document.js";
+/**
+ * Client capabilities advertised at initialize. A server may
+ * report diagnostics two ways: TypeScript 7's native LSP answers
+ * them on demand (pull), while tsserver-based and many other
+ * servers push them after a document opens. We advertise both so
+ * the backend stays general, and it picks the mode per server
+ * from the initialize response. The native server also drives
+ * the client with dynamic registration and workspace queries, so
+ * the configuration, workspaceFolders and workDoneProgress
+ * capabilities are load-bearing, not decorative.
+ */
+const CLIENT_CAPABILITIES = {
+    textDocument: {
+        synchronization: { didSave: true, dynamicRegistration: true },
+        diagnostic: { dynamicRegistration: true },
+        publishDiagnostics: { relatedInformation: true },
+        definition: { linkSupport: true },
+        references: {},
+        hover: { contentFormat: ["markdown", "plaintext"] },
+        documentSymbol: { hierarchicalDocumentSymbolSupport: true },
+        rename: { prepareSupport: true },
+        codeAction: {},
+    },
+    workspace: {
+        workspaceEdit: { documentChanges: true },
+        configuration: true,
+        workspaceFolders: true,
+        didChangeConfiguration: { dynamicRegistration: true },
+    },
+    window: { workDoneProgress: true },
+};
+/** How long a cold initialize may take before we give up. */
+const WARMUP_TIMEOUT_MS = 15_000;
+/** Quiet window after the last diagnostics publish before we read them. */
+const DIAGNOSTICS_SETTLE_MS = 300;
+/** Hard cap on waiting for a document's diagnostics. Generous
+ * because it also bounds the first request against a cold,
+ * large project whose program is still building. */
+const DIAGNOSTICS_TIMEOUT_MS = 20_000;
+const SEVERITY = {
+    1: "error",
+    2: "warning",
+    3: "information",
+    4: "hint",
+};
+/** A live server connection rooted at one project directory. */
+export class StandaloneServer {
+    serverName;
+    root;
+    child;
+    connection;
+    openDocs = new Set();
+    lineCache = new Map();
+    diagnostics = new Map();
+    diagWaiters = new Set();
+    // Whether the server answers pull diagnostics (textDocument/diagnostic).
+    // Set from the initialize response; false means it pushes instead.
+    pullSupported = false;
+    version = 0;
+    constructor(serverName, root, child, connection) {
+        this.serverName = serverName;
+        this.root = root;
+        this.child = child;
+        this.connection = connection;
+    }
+    /** Spawn a server, run the initialize handshake and return it ready. */
+    static async start(config, root, binaryPath) {
+        const child = spawn(binaryPath, [...config.args], {
+            cwd: root,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const { stdout, stdin } = child;
+        if (!stdout || !stdin) {
+            child.kill();
+            throw new Error(`failed to open stdio for ${config.name}`);
+        }
+        // Killing the server mid-write (on dispose) makes the jsonrpc
+        // writer hit EPIPE on a destroyed stream. That is expected at
+        // teardown, so swallow it here rather than let it surface as an
+        // unhandled stream error.
+        stdin.on("error", () => { });
+        stdout.on("error", () => { });
+        const connection = createMessageConnection(new StreamMessageReader(stdout), new StreamMessageWriter(stdin));
+        const server = new StandaloneServer(config.name, root, child, connection);
+        // Swallow transport errors (a write after the child is killed);
+        // they are expected during dispose and must not go unhandled.
+        connection.onError(() => { });
+        // A push-style server publishes a file's diagnostics after it
+        // opens; capture them so a pull-incapable server still reports.
+        connection.onNotification(PublishDiagnosticsNotification.type, (params) => {
+            server.diagnostics.set(params.uri, params.diagnostics);
+            for (const waiter of server.diagWaiters)
+                waiter(params.uri);
+        });
+        // TypeScript 7's native LSP drives the client with dynamic
+        // capability registration and workspace queries, and stalls until
+        // they are answered. Accept registration as a no-op, answer
+        // configuration with defaults, grant progress tokens, and report
+        // the resolved project root as the one workspace folder.
+        connection.onRequest(RegistrationRequest.type, () => undefined);
+        connection.onRequest(UnregistrationRequest.type, () => undefined);
+        connection.onRequest(ConfigurationRequest.type, (params) => params.items.map(() => ({})));
+        connection.onRequest(WorkDoneProgressCreateRequest.type, () => undefined);
+        connection.onRequest(WorkspaceFoldersRequest.type, () => [
+            { uri: fileToUri(root), name: basename(root) },
+        ]);
+        connection.listen();
+        const initResult = await withTimeout(connection.sendRequest(InitializeRequest.type, {
+            processId: process.pid,
+            rootUri: fileToUri(root),
+            workspaceFolders: [{ uri: fileToUri(root), name: basename(root) }],
+            capabilities: CLIENT_CAPABILITIES,
+            ...(config.initOptions
+                ? { initializationOptions: config.initOptions }
+                : {}),
+        }), WARMUP_TIMEOUT_MS, `initialize ${config.name}`);
+        // Prefer pull diagnostics when the server advertises them, and
+        // fall back to the pushed stream otherwise.
+        server.pullSupported = Boolean(initResult?.capabilities?.diagnosticProvider);
+        connection
+            .sendNotification(InitializedNotification.type, {})
+            .catch(() => { });
+        return server;
+    }
+    /** Problems the server reports against the file's current bytes. */
+    async diagnose(path) {
+        this.ensureOpen(path);
+        const raw = this.pullSupported
+            ? await this.pullDiagnostics(path)
+            : await this.pushedDiagnostics(path);
+        const lines = this.linesFor(path);
+        return raw.map((d) => this.toDiagnostic(path, lines, d));
+    }
+    /** Where the symbol under the target is defined. */
+    async definition(target) {
+        await this.ensureReady(target.path);
+        const result = await this.connection.sendRequest(DefinitionRequest.type, {
+            textDocument: { uri: fileToUri(target.path) },
+            position: toProtocolPosition(this.linesFor(target.path), target.position),
+        });
+        return this.toLocations(result);
+    }
+    /** Every reference to the symbol under the target. */
+    async references(target) {
+        await this.ensureReady(target.path);
+        const result = await this.connection.sendRequest(ReferencesRequest.type, {
+            textDocument: { uri: fileToUri(target.path) },
+            position: toProtocolPosition(this.linesFor(target.path), target.position),
+            context: { includeDeclaration: true },
+        });
+        return this.toLocations(result);
+    }
+    /** Documentation for the symbol under the target, or null. */
+    async hover(target) {
+        await this.ensureReady(target.path);
+        const result = await this.connection.sendRequest(HoverRequest.type, {
+            textDocument: { uri: fileToUri(target.path) },
+            position: toProtocolPosition(this.linesFor(target.path), target.position),
+        });
+        if (!result)
+            return null;
+        const contents = hoverText(result.contents);
+        if (!contents)
+            return null;
+        return result.range
+            ? {
+                contents,
+                range: fromProtocolRange(this.linesFor(target.path), result.range),
+            }
+            : { contents };
+    }
+    /** Symbols declared in one file. */
+    async documentSymbols(path) {
+        await this.ensureReady(path);
+        const result = await this.connection.sendRequest(DocumentSymbolRequest.type, { textDocument: { uri: fileToUri(path) } });
+        if (!result)
+            return [];
+        const lines = this.linesFor(path);
+        return result.flatMap((item) => "location" in item
+            ? [this.fromSymbolInformation(item)]
+            : this.flattenDocumentSymbol(path, lines, item));
+    }
+    /** Symbols across the project matching a query. */
+    async workspaceSymbols(query) {
+        const result = await this.connection.sendRequest(WorkspaceSymbolRequest.type, { query });
+        if (!result)
+            return [];
+        return result.map((item) => this.fromSymbolInformation(item));
+    }
+    /** Rename the symbol under the target and apply the edits. */
+    async rename(target, newName) {
+        await this.ensureReady(target.path);
+        const edit = await this.connection.sendRequest(RenameRequest.type, {
+            textDocument: { uri: fileToUri(target.path) },
+            position: toProtocolPosition(this.linesFor(target.path), target.position),
+            newName,
+        });
+        if (!edit)
+            return { changes: [] };
+        return this.applyWorkspaceEdit(edit);
+    }
+    /** Code actions the server offers for a file, optionally at a range. */
+    async codeActions(path, range) {
+        await this.ensureReady(path);
+        const lines = this.linesFor(path);
+        const protocolRange = range
+            ? {
+                start: toProtocolPosition(lines, range.start),
+                end: toProtocolPosition(lines, range.end),
+            }
+            : { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } };
+        const result = await this.connection.sendRequest(CodeActionRequest.type, {
+            textDocument: { uri: fileToUri(path) },
+            range: protocolRange,
+            context: { diagnostics: [] },
+        });
+        if (!result)
+            return [];
+        return result.map((item) => ({
+            title: item.title,
+            ...("kind" in item && item.kind ? { kind: item.kind } : {}),
+        }));
+    }
+    /** Re-sync a document after the caller edited it, so diagnostics stay current. */
+    syncDocument(path, text) {
+        const uri = fileToUri(path);
+        if (!this.openDocs.has(uri)) {
+            this.ensureOpen(path);
+            return;
+        }
+        this.lineCache.set(uri, toLines(text));
+        this.version += 1;
+        this.connection
+            .sendNotification(DidChangeTextDocumentNotification.type, {
+            textDocument: { uri, version: this.version },
+            contentChanges: [{ text }],
+        })
+            .catch(() => { });
+    }
+    /** Release the connection and kill the server process. */
+    async dispose() {
+        try {
+            this.connection.dispose();
+        }
+        catch {
+            // The connection may already be torn down; nothing to do.
+        }
+        this.child.kill();
+    }
+    /**
+     * Open the target and wait for the server to finish building
+     * the project's program before a type-intelligence request.
+     * The server answers references and definition only across
+     * files in the loaded program. Both diagnostics modes signal
+     * that build: a pull resolves once the program is ready, and a
+     * push server publishes the file's first diagnostics then.
+     * Cached per file so warm requests skip the wait.
+     */
+    async ensureReady(path) {
+        const uri = fileToUri(path);
+        const alreadyOpen = this.openDocs.has(uri);
+        this.ensureOpen(path);
+        if (alreadyOpen)
+            return;
+        // Drive the program build and use its completion as the gate.
+        if (this.pullSupported)
+            await this.pullDiagnostics(path).catch(() => { });
+        else
+            await this.settleDiagnostics(uri);
+    }
+    /**
+     * Pull the current diagnostics for a file. TypeScript 7's native
+     * LSP computes them on request and resolves once the program is
+     * built, so this both reports problems and gates readiness.
+     */
+    async pullDiagnostics(path) {
+        const report = await withTimeout(this.connection.sendRequest(DocumentDiagnosticRequest.type, {
+            textDocument: { uri: fileToUri(path) },
+        }), DIAGNOSTICS_TIMEOUT_MS, `diagnostics ${path}`);
+        if (report?.kind === DocumentDiagnosticReportKind.Full) {
+            return report.items;
+        }
+        return [];
+    }
+    /** Read the diagnostics a push server published, waiting for them to settle. */
+    async pushedDiagnostics(path) {
+        const uri = fileToUri(path);
+        await this.settleDiagnostics(uri);
+        return this.diagnostics.get(uri) ?? [];
+    }
+    /**
+     * Resolve once a push server's diagnostics for `uri` have gone
+     * quiet, or the hard timeout fires. The quiet window only starts
+     * after the first publish, so a server slower than the window is
+     * still caught, while the timeout bounds one that never speaks.
+     */
+    settleDiagnostics(uri) {
+        return new Promise((resolve) => {
+            let settleTimer;
+            let done = false;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(settleTimer);
+                clearTimeout(hardTimer);
+                this.diagWaiters.delete(onPublish);
+                resolve();
+            };
+            const arm = () => {
+                clearTimeout(settleTimer);
+                settleTimer = setTimeout(finish, DIAGNOSTICS_SETTLE_MS);
+            };
+            const onPublish = (published) => {
+                if (published === uri)
+                    arm();
+            };
+            const hardTimer = setTimeout(finish, DIAGNOSTICS_TIMEOUT_MS);
+            this.diagWaiters.add(onPublish);
+            if (this.diagnostics.has(uri))
+                arm();
+        });
+    }
+    ensureOpen(path) {
+        const uri = fileToUri(path);
+        if (this.openDocs.has(uri))
+            return;
+        const text = readFileSync(path, "utf8");
+        this.lineCache.set(uri, toLines(text));
+        this.version += 1;
+        this.openDocs.add(uri);
+        this.connection
+            .sendNotification(DidOpenTextDocumentNotification.type, {
+            textDocument: {
+                uri,
+                languageId: languageIdFor(path),
+                version: this.version,
+                text,
+            },
+        })
+            .catch(() => { });
+    }
+    linesFor(path) {
+        const uri = fileToUri(path);
+        const cached = this.lineCache.get(uri);
+        if (cached)
+            return cached;
+        const lines = toLines(readFileSync(path, "utf8"));
+        this.lineCache.set(uri, lines);
+        return lines;
+    }
+    toDiagnostic(path, lines, d) {
+        return {
+            path,
+            range: fromProtocolRange(lines, d.range),
+            severity: SEVERITY[d.severity ?? 1] ?? "error",
+            message: d.message,
+            ...(d.source ? { source: d.source } : {}),
+            ...(d.code !== undefined ? { code: String(d.code) } : {}),
+        };
+    }
+    /**
+     * Apply a protocol workspace edit to disk, updating caches
+     * and re-syncing open documents, and return what changed in
+     * tool coordinates.
+     */
+    applyWorkspaceEdit(edit) {
+        const byUri = new Map();
+        const plainEdits = (edits) => edits.flatMap((e) => typeof e.newText === "string"
+            ? [{ range: e.range, newText: e.newText }]
+            : []);
+        if (edit.changes) {
+            for (const [uri, edits] of Object.entries(edit.changes)) {
+                byUri.set(uri, plainEdits(edits));
+            }
+        }
+        if (edit.documentChanges) {
+            for (const change of edit.documentChanges) {
+                if ("textDocument" in change && "edits" in change) {
+                    byUri.set(change.textDocument.uri, plainEdits(change.edits));
+                }
+            }
+        }
+        const changes = [];
+        for (const [uri, edits] of byUri) {
+            const path = uriToFile(uri);
+            const original = readFileSync(path, "utf8");
+            const updated = applyProtocolEdits(original, edits);
+            writeFileSync(path, updated);
+            const lines = toLines(original);
+            changes.push({
+                path,
+                edits: edits.map((e) => ({
+                    range: fromProtocolRange(lines, e.range),
+                    newText: e.newText,
+                })),
+            });
+            // Keep the server in step with what we just wrote.
+            this.syncDocument(path, updated);
+        }
+        return { changes };
+    }
+    fromSymbolInformation(item) {
+        const location = item.location;
+        const path = uriToFile(location.uri);
+        // A WorkspaceSymbol may carry only a uri, without a range.
+        const range = "range" in location
+            ? fromProtocolRange(this.linesFor(path), location.range)
+            : {
+                start: { line: 1, character: 0 },
+                end: { line: 1, character: 0 },
+            };
+        return {
+            name: item.name,
+            kind: symbolKindName(item.kind),
+            location: { path, range },
+            ...(item.containerName ? { containerName: item.containerName } : {}),
+        };
+    }
+    flattenDocumentSymbol(path, lines, symbol, container) {
+        const self = {
+            name: symbol.name,
+            kind: symbolKindName(symbol.kind),
+            location: { path, range: fromProtocolRange(lines, symbol.range) },
+            ...(container ? { containerName: container } : {}),
+        };
+        const children = (symbol.children ?? []).flatMap((child) => this.flattenDocumentSymbol(path, lines, child, symbol.name));
+        return [self, ...children];
+    }
+    toLocations(result) {
+        if (!result)
+            return [];
+        const array = Array.isArray(result) ? result : [result];
+        return array.map((item) => {
+            if ("targetUri" in item) {
+                const path = uriToFile(item.targetUri);
+                return {
+                    path,
+                    range: fromProtocolRange(this.linesFor(path), item.targetRange),
+                };
+            }
+            const path = uriToFile(item.uri);
+            return {
+                path,
+                range: fromProtocolRange(this.linesFor(path), item.range),
+            };
+        });
+    }
+}
+function hoverText(contents) {
+    if (contents === null || contents === undefined)
+        return "";
+    if (typeof contents === "string")
+        return contents;
+    if (Array.isArray(contents))
+        return contents.map(hoverText).join("\n");
+    if (typeof contents === "object") {
+        const value = contents.value;
+        if (typeof value === "string")
+            return value;
+    }
+    return "";
+}
+const SYMBOL_KINDS = {
+    1: "file",
+    2: "module",
+    3: "namespace",
+    4: "package",
+    5: "class",
+    6: "method",
+    7: "property",
+    8: "field",
+    9: "constructor",
+    10: "enum",
+    11: "interface",
+    12: "function",
+    13: "variable",
+    14: "constant",
+    15: "string",
+    16: "number",
+    17: "boolean",
+    18: "array",
+    19: "object",
+    20: "key",
+    21: "null",
+    22: "enum-member",
+    23: "struct",
+    24: "event",
+    25: "operator",
+    26: "type-parameter",
+};
+function symbolKindName(kind) {
+    return SYMBOL_KINDS[kind] ?? "symbol";
+}
+function withTimeout(promise, ms, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}

package/dist/lsp/types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Backend-agnostic surface for semantic code intelligence.
+ *
+ * One tool speaks these shapes; a standalone backend that spawns
+ * language servers itself and an editor-forwarding backend both
+ * normalize to them, so a caller cannot tell which answered.
+ *
+ * Positions follow the convention pi's own LSP integration
+ * established: a 1-indexed line and a 0-indexed UTF-8 byte
+ * column. The LSP protocol itself is 0-indexed and counts UTF-16
+ * code units, so a backend translates at its edge.
+ */
+/** A point in a file: 1-indexed line, 0-indexed UTF-8 byte column. */
+export interface LspPosition {
+    readonly line: number;
+    readonly character: number;
+}
+/** A half-open span between two positions. */
+export interface LspRange {
+    readonly start: LspPosition;
+    readonly end: LspPosition;
+}
+/** A range within a specific file. */
+export interface LspLocation {
+    readonly path: string;
+    readonly range: LspRange;
+}
+/** Diagnostic severity, normalized to words rather than LSP's integers. */
+export type DiagnosticSeverity = "error" | "warning" | "information" | "hint";
+/** One problem the server reported against a file. */
+export interface Diagnostic {
+    readonly path: string;
+    readonly range: LspRange;
+    readonly severity: DiagnosticSeverity;
+    readonly message: string;
+    readonly source?: string;
+    readonly code?: string;
+}
+/** A file path plus the position an operation targets. */
+export interface LspTarget {
+    readonly path: string;
+    readonly position: LspPosition;
+}
+/** A single text replacement within a file. */
+export interface LspTextEdit {
+    readonly range: LspRange;
+    readonly newText: string;
+}
+/** Edits grouped by the file they touch. */
+export interface WorkspaceEdit {
+    readonly changes: ReadonlyArray<{
+        readonly path: string;
+        readonly edits: readonly LspTextEdit[];
+    }>;
+}
+/** A symbol the server knows about, with where it lives. */
+export interface SymbolInfo {
+    readonly name: string;
+    readonly kind: string;
+    readonly location: LspLocation;
+    readonly containerName?: string;
+}
+/** Hover documentation for a position, as plain text or markdown. */
+export interface HoverInfo {
+    readonly contents: string;
+    readonly range?: LspRange;
+}
+/** A code action the server offers at a position or range. */
+export interface CodeAction {
+    readonly title: string;
+    readonly kind?: string;
+}
+/**
+ * A registered backend and the rule for when it may serve.
+ * Lower priority resolves first, so a downstream backend can
+ * register below the standalone default to take over when its
+ * own precondition is met.
+ */
+export interface LspBackendEntry {
+    /** Stable backend name. */
+    readonly name: string;
+    /** Lower numbers resolve first; the standalone default sits at 100. */
+    readonly priority: number;
+    /** Whether this backend can serve right now. */
+    isAvailable(): boolean;
+    /** The backend itself. */
+    readonly backend: LspBackend;
+}
+/**
+ * The operations a backend serves. The foundation ships
+ * diagnostics, definition and references; write operations
+ * (rename, hover, symbols, code actions) widen this contract
+ * as they land.
+ */
+export interface LspBackend {
+    /** Stable name used in backend selection and messages. */
+    readonly name: string;
+    /** Problems the server reports against a file's current bytes. */
+    diagnostics(path: string): Promise<readonly Diagnostic[]>;
+    /** Where the symbol under the target is defined. */
+    definition(target: LspTarget): Promise<readonly LspLocation[]>;
+    /** Every reference to the symbol under the target. */
+    references(target: LspTarget): Promise<readonly LspLocation[]>;
+    /** Documentation for the symbol under the target, or null. */
+    hover(target: LspTarget): Promise<HoverInfo | null>;
+    /** Symbols declared in one file. */
+    documentSymbols(path: string): Promise<readonly SymbolInfo[]>;
+    /** Symbols across the project matching a query. */
+    workspaceSymbols(query: string): Promise<readonly SymbolInfo[]>;
+    /**
+     * Rename the symbol under the target across its root and
+     * apply the edits, returning what changed.
+     */
+    rename(target: LspTarget, newName: string): Promise<WorkspaceEdit>;
+    /** Code actions the server offers for a file, optionally at a range. */
+    codeActions(path: string, range?: LspRange): Promise<readonly CodeAction[]>;
+    /** Release every server the backend holds open. */
+    dispose(): Promise<void>;
+}

package/dist/lsp/types.js

@@ -0,0 +1,13 @@
+/**
+ * Backend-agnostic surface for semantic code intelligence.
+ *
+ * One tool speaks these shapes; a standalone backend that spawns
+ * language servers itself and an editor-forwarding backend both
+ * normalize to them, so a caller cannot tell which answered.
+ *
+ * Positions follow the convention pi's own LSP integration
+ * established: a 1-indexed line and a 0-indexed UTF-8 byte
+ * column. The LSP protocol itself is 0-indexed and counts UTF-16
+ * code units, so a backend translates at its edge.
+ */
+export {};

package/dist/memory/db.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Thin promise wrapper over the callback-based sqlite3 driver.
+ * sqlite3 is a native module, so it is lazy-imported on first
+ * open; callers speak promises and never touch the driver
+ * directly.
+ */
+/** A promise-speaking handle to a SQLite database. */
+export interface Db {
+    run(sql: string, params?: readonly unknown[]): Promise<void>;
+    all<T>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+    exec(sql: string): Promise<void>;
+    close(): Promise<void>;
+}
+/** Open a SQLite database at the given path (`:memory:` for tests). */
+export declare function openDb(dbPath: string): Promise<Db>;

package/dist/memory/db.js

@@ -0,0 +1,25 @@
+/**
+ * Thin promise wrapper over the callback-based sqlite3 driver.
+ * sqlite3 is a native module, so it is lazy-imported on first
+ * open; callers speak promises and never touch the driver
+ * directly.
+ */
+/** Open a SQLite database at the given path (`:memory:` for tests). */
+export async function openDb(dbPath) {
+    const sqlite3 = await import("sqlite3");
+    const database = new sqlite3.default.Database(dbPath);
+    return {
+        run: (sql, params = []) => new Promise((resolve, reject) => {
+            database.run(sql, params, (err) => (err ? reject(err) : resolve()));
+        }),
+        all: (sql, params = []) => new Promise((resolve, reject) => {
+            database.all(sql, params, (err, rows) => err ? reject(err) : resolve(rows));
+        }),
+        exec: (sql) => new Promise((resolve, reject) => {
+            database.exec(sql, (err) => (err ? reject(err) : resolve()));
+        }),
+        close: () => new Promise((resolve, reject) => {
+            database.close((err) => (err ? reject(err) : resolve()));
+        }),
+    };
+}