cursedbelt-server 1.0.0

package/dist/server/sqlite/browse.js

@@ -0,0 +1,84 @@
+import { clampPageLimit } from 'cwip/math';
+import { isReadOnlySql } from './readonlySql';
+/**
+ * Hono-free read-only SQLite browse primitives — the shared core beneath
+ * `createSqliteViewerMiddleware` (viewer.ts) AND any consumer that can't mount a
+ * Hono sub-app (e.g. a cursedshell plugin's `defineService`, whose routes are pure
+ * data, or an app with a bespoke transport). One primitive per concern: the
+ * middleware is now a thin HTTP wrapper over these functions.
+ *
+ * Every path is read-only and injection-safe: table names are validated against
+ * `sqlite_master` before interpolation, all values are bound, and ad-hoc SQL is
+ * gated by {@link isReadOnlySql} (SELECT/WITH only). Authn/authz is the caller's job.
+ */
+/** A sane admin page-size window. */
+const MAX_PAGE = 1000;
+/** Clamp a requested page size into `[1, MAX_PAGE]`, falling back when unparseable. */
+export function clampLimit(raw, fallback) {
+    return clampPageLimit(raw, { max: MAX_PAGE, fallback });
+}
+/** Clamp an offset to a non-negative integer (0 when unparseable). */
+export function clampOffset(raw) {
+    return clampPageLimit(raw, { min: 0, max: Number.POSITIVE_INFINITY, fallback: 0 });
+}
+/** Is `name` an actual table in this DB? (The injection guard for `SELECT * FROM`.) */
+export function isKnownTable(db, name) {
+    const row = db
+        .query("SELECT COUNT(*) AS n FROM sqlite_master WHERE type='table' AND name = ?")
+        .get(name);
+    return (row?.n ?? 0) > 0;
+}
+/** Double-quote a name already proven to exist in `sqlite_master`. */
+export function quoteIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/** User tables (FTS shadow + `sqlite_*` internals excluded) with row counts. */
+export function listSqliteTables(db) {
+    const names = db
+        .query("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name")
+        .all()
+        .map((r) => r.name);
+    return names.map((name) => ({
+        name,
+        count: db.query(`SELECT COUNT(*) AS n FROM ${quoteIdent(name)}`).get()?.n ?? 0,
+    }));
+}
+export class UnknownTableError extends Error {
+    table;
+    constructor(table) {
+        super(`Unknown table: ${table}`);
+        this.table = table;
+        this.name = 'UnknownTableError';
+    }
+}
+/**
+ * A clamped, paginated window over one table. Throws {@link UnknownTableError} for a
+ * table that isn't in `sqlite_master` (callers map that to a 404).
+ */
+export function readSqliteTable(db, table, opts = {}) {
+    if (!isKnownTable(db, table))
+        throw new UnknownTableError(table);
+    const limit = clampLimit(opts.limit, 50);
+    const offset = clampOffset(opts.offset);
+    const items = db
+        .query(`SELECT * FROM ${quoteIdent(table)} LIMIT ? OFFSET ?`)
+        .all(limit, offset);
+    const total = db.query(`SELECT COUNT(*) AS n FROM ${quoteIdent(table)}`).get()?.n ?? 0;
+    return { items, total, limit, offset };
+}
+export class NotReadOnlyError extends Error {
+    constructor() {
+        super('Only read-only SELECT/WITH queries are allowed');
+        this.name = 'NotReadOnlyError';
+    }
+}
+/**
+ * Run an ad-hoc read-only query with bound params. Throws {@link NotReadOnlyError}
+ * for anything the {@link isReadOnlySql} guard rejects (non-SELECT, stacked
+ * statements, PRAGMA, …); SQLite errors (bad column/table) propagate as `Error`.
+ */
+export function runReadonlySqlite(db, sql, params = []) {
+    if (typeof sql !== 'string' || !isReadOnlySql(sql))
+        throw new NotReadOnlyError();
+    return db.query(sql).all(...params);
+}

package/dist/server/sqlite/export.d.ts

@@ -0,0 +1,32 @@
+import type { Database } from 'bun:sqlite';
+/**
+ * Export primitives for `bun:sqlite` — the missing "get the data out" half of the
+ * SQLite toolkit. Table export composes the ONE canonical serializers (`toCsv` from
+ * `cwip/csv`, `JSON.stringify` for JSON — no third CSV/JSON path); snapshot export
+ * reuses the `VACUUM INTO` primitive (see `backup.ts`) to produce a portable `.sqlite`.
+ *
+ * These return in-memory payloads (text / bytes) rather than streaming to a Response,
+ * so they're transport-agnostic: a cursedshell plugin returns them over its JSON RPC
+ * (base64 for bytes), a Hono app streams them as a `Content-Disposition: attachment`
+ * download. Admin-scale — a whole-DB snapshot is base64'd through JSON, fine for
+ * typical DB sizes; very large DBs should stream a file route instead.
+ */
+export type TableExportFormat = 'csv' | 'json';
+export interface TableExport {
+    filename: string;
+    mime: string;
+    text: string;
+}
+/** All rows of one table serialized to CSV or JSON. Throws {@link UnknownTableError}. */
+export declare function exportSqliteTable(db: Database, table: string, format: TableExportFormat): TableExport;
+export interface SnapshotExport {
+    filename: string;
+    mime: string;
+    bytes: Uint8Array;
+}
+/**
+ * A compact, WAL-merged copy of the whole database as `.sqlite` bytes, via
+ * `VACUUM INTO` a throwaway temp file (the same primitive `createSqliteBackupService`
+ * uses). The temp file is always removed.
+ */
+export declare function exportSqliteSnapshot(db: Database): SnapshotExport;

package/dist/server/sqlite/export.js

@@ -0,0 +1,42 @@
+import { readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { toCsv } from 'cwip/csv';
+import { isKnownTable, quoteIdent, UnknownTableError } from './browse';
+/** All rows of one table serialized to CSV or JSON. Throws {@link UnknownTableError}. */
+export function exportSqliteTable(db, table, format) {
+    if (!isKnownTable(db, table))
+        throw new UnknownTableError(table);
+    const rows = db.query(`SELECT * FROM ${quoteIdent(table)}`).all();
+    if (format === 'json') {
+        return {
+            filename: `${table}.json`,
+            mime: 'application/json',
+            text: JSON.stringify(rows, null, 2),
+        };
+    }
+    return {
+        filename: `${table}.csv`,
+        mime: 'text/csv',
+        // toCsv needs at least the columns; an empty table yields an empty string, which
+        // is a valid (header-less) CSV for a zero-row export.
+        text: toCsv(rows),
+    };
+}
+/**
+ * A compact, WAL-merged copy of the whole database as `.sqlite` bytes, via
+ * `VACUUM INTO` a throwaway temp file (the same primitive `createSqliteBackupService`
+ * uses). The temp file is always removed.
+ */
+export function exportSqliteSnapshot(db) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const tmp = join(tmpdir(), `cb-export-${stamp}-${Math.random().toString(36).slice(2)}.sqlite`);
+    try {
+        db.run('VACUUM INTO ?', [tmp]);
+        const bytes = new Uint8Array(readFileSync(tmp));
+        return { filename: `snapshot-${stamp}.sqlite`, mime: 'application/x-sqlite3', bytes };
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+}

package/dist/server/sqlite/fts5.d.ts

@@ -0,0 +1,106 @@
+import type { Database } from 'bun:sqlite';
+export interface FtsTableSpec {
+    /** The FTS5 virtual table to create, e.g. `'notes_fts'`. */
+    table: string;
+    /** The source ("content") table whose text it indexes, e.g. `'notes'`. */
+    contentTable: string;
+    /** The content table's rowid/primary-key column. Default: `'id'`. */
+    contentRowid?: string;
+    /** Indexed columns — must exist on the content table, in this order. */
+    columns: string[];
+    /**
+     * FTS5 tokenizer directive. Default: `unicode61 remove_diacritics 2` (case- and
+     * accent-folding, the right default for human text). Pass e.g. `'porter unicode61'`
+     * for stemming, or `'trigram'` for substring search.
+     */
+    tokenize?: string;
+}
+/**
+ * Build the DDL for one external-content FTS5 table and its three sync triggers
+ * (insert/update/delete), as a single multi-statement string ready for `db.run()`.
+ *
+ * External content (`content=<table>, content_rowid=<pk>`) means the FTS index stores
+ * only the inverted index, never a second copy of the text — the triggers mirror every
+ * write into the index. This is the canonical pattern from the SQLite FTS5 docs,
+ * generated once so apps don't repeat it per table.
+ */
+export declare function buildFtsSchema(spec: FtsTableSpec): string;
+/** Create every table in `specs` and its triggers on `db` (one `db.run` per spec). */
+export declare function applyFtsSchema(db: Database, ...specs: FtsTableSpec[]): void;
+export interface FtsResult {
+    /** The content row's rowid (its `content_rowid` value). */
+    rowid: number;
+    /** FTS5 bm25 relevance — lower (more negative) is more relevant. */
+    rank: number;
+    /** Present only when `snippet` was requested: a truncated, match-marked excerpt. */
+    snippet?: string;
+    /** Present only when `highlight` was requested: the full column with matches marked. */
+    highlight?: string;
+}
+export interface FtsSnippetOpts {
+    /** FTS column index to excerpt; `-1` (default) auto-picks the best-matching column. */
+    column?: number;
+    /** Wraps each match, default `'<b>'`. */
+    startMatch?: string;
+    /** Closes each match, default `'</b>'`. */
+    endMatch?: string;
+    /** Inserted where text is trimmed, default `'…'`. */
+    ellipsis?: string;
+    /** Max tokens in the excerpt (1–64), default `16`. */
+    maxTokens?: number;
+}
+export interface FtsHighlightOpts {
+    /** FTS column index to return (required — `highlight()` has no auto column). */
+    column: number;
+    /** Wraps each match, default `'<b>'`. */
+    startMatch?: string;
+    /** Closes each match, default `'</b>'`. */
+    endMatch?: string;
+}
+export interface FtsSearchOpts {
+    /** The FTS5 table to query, e.g. `'notes_fts'`. */
+    table: string;
+    /** Raw user query — sanitized into a prefix-match expression before MATCH. */
+    query: string;
+    /** Page size, default `20`. */
+    limit?: number;
+    /** Row offset, default `0`. */
+    offset?: number;
+    /** Request a `snippet(...)` excerpt column. */
+    snippet?: FtsSnippetOpts;
+    /** Request a `highlight(...)` column. */
+    highlight?: FtsHighlightOpts;
+}
+export interface Fts5Search {
+    /** Ranked search; returns `[]` for an empty/operator-only query (never throws on it). */
+    search(opts: FtsSearchOpts): FtsResult[];
+    /** Rebuild one FTS index from its content table (post-ETL / after `clear`). */
+    rebuild(table: string): void;
+    /** Rebuild every table passed to {@link createFts5Search} (`tables` option). */
+    rebuildAll(): void;
+    /** Empty an FTS index (the `'delete-all'` command) — pair with `rebuild` for bulk loads. */
+    clear(table: string): void;
+    /** Merge the index's b-tree segments (the `'optimize'` command) for faster queries. */
+    optimize(table: string): void;
+}
+/**
+ * Build a ranked-search facade over the FTS5 tables named in `opts.tables` (the set
+ * `rebuildAll()` iterates). The `db` handle is the same one the app uses — one
+ * connection, one WAL.
+ */
+export declare function createFts5Search(db: Database, opts?: {
+    tables?: string[];
+}): Fts5Search;
+/**
+ * Convert arbitrary user input into a safe FTS5 MATCH expression: every run of
+ * letters/digits/underscore becomes a quoted prefix token (`"term"*`), joined by
+ * spaces (FTS5's implicit AND). All FTS5 operators (`" * : ^ ( ) - + NEAR …`) are
+ * dropped with the surrounding punctuation, so the query can neither inject syntax
+ * nor raise a parse error. Returns `''` when nothing searchable remains.
+ *
+ * Examples: `hello` → `"hello"*`; `hello world` → `"hello"* "world"*` (both must
+ * match); `DROP TABLE` → `"DROP"* "TABLE"*` (a literal search, harmless).
+ */
+export declare function sanitizeFtsQuery(raw: string, opts?: {
+    mode?: 'all' | 'any';
+}): string;

package/dist/server/sqlite/fts5.js

@@ -0,0 +1,154 @@
+/**
+ * FTS5 full-text search for `bun:sqlite` — the from-scratch replacement for the apps'
+ * hand-rolled `LIKE '%' || ? || '%'` search. Three pieces:
+ *
+ *  1. {@link buildFtsSchema} — generates the `CREATE VIRTUAL TABLE` + the three
+ *     external-content sync triggers for one indexed table. Apps call it from a
+ *     migration instead of hand-writing the (highly repetitive) trigger SQL 4×.
+ *  2. {@link createFts5Search} — a ranked query builder (bm25 `rank`, `snippet`,
+ *     `highlight`) over those tables, plus the FTS5 maintenance commands
+ *     (`rebuild`/`clear`/`optimize`) the ETL and bulk importers need.
+ *  3. {@link sanitizeFtsQuery} — turns arbitrary user input into a safe AND-of-prefix
+ *     FTS5 MATCH expression (no operator injection, no parse errors).
+ *
+ * FTS5 is compiled into `bun:sqlite` (NOT `node:sqlite`, which omits it). Everything
+ * here is app-agnostic: the indexed table names are a *constructor option*, never
+ * hard-coded — ca and ru index different tables.
+ */
+/** A safe, unquoted SQL identifier (table/column name). */
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertIdent(name, what) {
+    if (!IDENT.test(name)) {
+        throw new Error(`Invalid ${what}: ${JSON.stringify(name)} (expected a plain SQL identifier)`);
+    }
+    return name;
+}
+/** Double-quote an identifier (validated first, so the quoting can't be escaped out of). */
+const q = (name) => `"${name}"`;
+/** Single-quote a string literal for inlining (doubles embedded quotes). */
+const lit = (s) => `'${s.replace(/'/g, "''")}'`;
+/** Coerce to a bounded non-negative integer for inlining (snippet token counts, etc.). */
+const int = (n, fallback) => Number.isFinite(n) ? Math.trunc(n) : fallback;
+/**
+ * Build the DDL for one external-content FTS5 table and its three sync triggers
+ * (insert/update/delete), as a single multi-statement string ready for `db.run()`.
+ *
+ * External content (`content=<table>, content_rowid=<pk>`) means the FTS index stores
+ * only the inverted index, never a second copy of the text — the triggers mirror every
+ * write into the index. This is the canonical pattern from the SQLite FTS5 docs,
+ * generated once so apps don't repeat it per table.
+ */
+export function buildFtsSchema(spec) {
+    const table = assertIdent(spec.table, 'fts table name');
+    const content = assertIdent(spec.contentTable, 'content table name');
+    const rowid = assertIdent(spec.contentRowid ?? 'id', 'content rowid column');
+    if (spec.columns.length === 0) {
+        throw new Error(`buildFtsSchema(${table}): at least one indexed column is required`);
+    }
+    const cols = spec.columns.map((c) => assertIdent(c, 'indexed column'));
+    const tokenize = spec.tokenize ?? 'unicode61 remove_diacritics 2';
+    const colList = cols.map(q).join(', ');
+    const newVals = cols.map((c) => `new.${q(c)}`).join(', ');
+    const oldVals = cols.map((c) => `old.${q(c)}`).join(', ');
+    // `INSERT INTO <fts>(<fts>, rowid, …) VALUES('delete', …)` is FTS5's documented way
+    // to remove the prior term rows for a content row before re-indexing it.
+    return `
+CREATE VIRTUAL TABLE IF NOT EXISTS ${q(table)} USING fts5(
+  ${colList},
+  content=${q(content)},
+  content_rowid=${q(rowid)},
+  tokenize=${lit(tokenize)}
+);
+CREATE TRIGGER IF NOT EXISTS ${q(`${table}_ai`)} AFTER INSERT ON ${q(content)} BEGIN
+  INSERT INTO ${q(table)}(rowid, ${colList}) VALUES (new.${q(rowid)}, ${newVals});
+END;
+CREATE TRIGGER IF NOT EXISTS ${q(`${table}_ad`)} AFTER DELETE ON ${q(content)} BEGIN
+  INSERT INTO ${q(table)}(${q(table)}, rowid, ${colList}) VALUES ('delete', old.${q(rowid)}, ${oldVals});
+END;
+CREATE TRIGGER IF NOT EXISTS ${q(`${table}_au`)} AFTER UPDATE ON ${q(content)} BEGIN
+  INSERT INTO ${q(table)}(${q(table)}, rowid, ${colList}) VALUES ('delete', old.${q(rowid)}, ${oldVals});
+  INSERT INTO ${q(table)}(rowid, ${colList}) VALUES (new.${q(rowid)}, ${newVals});
+END;`.trim();
+}
+/** Create every table in `specs` and its triggers on `db` (one `db.run` per spec). */
+export function applyFtsSchema(db, ...specs) {
+    for (const spec of specs)
+        db.run(buildFtsSchema(spec));
+}
+function snippetExpr(table, o) {
+    const col = int(o.column ?? -1, -1);
+    const start = lit(o.startMatch ?? '<b>');
+    const end = lit(o.endMatch ?? '</b>');
+    const ell = lit(o.ellipsis ?? '…');
+    const tokens = Math.min(64, Math.max(1, int(o.maxTokens ?? 16, 16)));
+    return `snippet(${q(table)}, ${col}, ${start}, ${end}, ${ell}, ${tokens}) AS snippet`;
+}
+function highlightExpr(table, o) {
+    const col = Math.max(0, int(o.column, 0));
+    const start = lit(o.startMatch ?? '<b>');
+    const end = lit(o.endMatch ?? '</b>');
+    return `highlight(${q(table)}, ${col}, ${start}, ${end}) AS highlight`;
+}
+/**
+ * Build a ranked-search facade over the FTS5 tables named in `opts.tables` (the set
+ * `rebuildAll()` iterates). The `db` handle is the same one the app uses — one
+ * connection, one WAL.
+ */
+export function createFts5Search(db, opts = {}) {
+    const tables = (opts.tables ?? []).map((t) => assertIdent(t, 'fts table name'));
+    const facade = {
+        search(o) {
+            const match = sanitizeFtsQuery(o.query);
+            if (!match)
+                return [];
+            const table = assertIdent(o.table, 'fts table name');
+            const projection = ['rowid', 'rank'];
+            if (o.snippet)
+                projection.push(snippetExpr(table, o.snippet));
+            if (o.highlight)
+                projection.push(highlightExpr(table, o.highlight));
+            const sql = `SELECT ${projection.join(', ')} FROM ${q(table)} WHERE ${q(table)} MATCH ? ORDER BY rank LIMIT ? OFFSET ?`;
+            return db
+                .query(sql)
+                .all(match, Math.max(0, int(o.limit ?? 20, 20)), Math.max(0, int(o.offset ?? 0, 0)));
+        },
+        rebuild(table) {
+            const t = assertIdent(table, 'fts table name');
+            db.run(`INSERT INTO ${q(t)}(${q(t)}) VALUES('rebuild')`);
+        },
+        rebuildAll() {
+            for (const t of tables)
+                facade.rebuild(t);
+        },
+        clear(table) {
+            const t = assertIdent(table, 'fts table name');
+            db.run(`INSERT INTO ${q(t)}(${q(t)}) VALUES('delete-all')`);
+        },
+        optimize(table) {
+            const t = assertIdent(table, 'fts table name');
+            db.run(`INSERT INTO ${q(t)}(${q(t)}) VALUES('optimize')`);
+        },
+    };
+    return facade;
+}
+// ── Query sanitization ─────────────────────────────────────────────────────────
+/**
+ * Convert arbitrary user input into a safe FTS5 MATCH expression: every run of
+ * letters/digits/underscore becomes a quoted prefix token (`"term"*`), joined by
+ * spaces (FTS5's implicit AND). All FTS5 operators (`" * : ^ ( ) - + NEAR …`) are
+ * dropped with the surrounding punctuation, so the query can neither inject syntax
+ * nor raise a parse error. Returns `''` when nothing searchable remains.
+ *
+ * Examples: `hello` → `"hello"*`; `hello world` → `"hello"* "world"*` (both must
+ * match); `DROP TABLE` → `"DROP"* "TABLE"*` (a literal search, harmless).
+ */
+export function sanitizeFtsQuery(raw, opts = {}) {
+    const tokens = raw.match(/[\p{L}\p{N}_]+/gu);
+    if (!tokens || tokens.length === 0)
+        return '';
+    // 'all' (default) = AND-of-prefix — precision, right for search-as-you-type.
+    // 'any' = OR-of-prefix — recall, right for retrieval from a natural-language
+    // question where requiring every word ("what do I have about…") matches nothing;
+    // bm25 still ranks docs hitting more/rarer terms first.
+    return tokens.map((t) => `"${t}"*`).join(opts.mode === 'any' ? ' OR ' : ' ');
+}

package/dist/server/sqlite/health.d.ts

@@ -0,0 +1,44 @@
+import type { Database } from 'bun:sqlite';
+/**
+ * DB-layer health probes for `bun:sqlite`. Each is a small, self-describing descriptor
+ * — `name` + `description` + an async `check()` returning a status — so it can be
+ * rendered in an operator console and drive readiness from one source.
+ *
+ * The shape is intentionally dependency-free (it does NOT import cwip's health types):
+ * apps adapt a descriptor into cwip's `HealthCheck` registry with a trivial map, e.g.
+ *
+ * ```ts
+ * registry.register(...createSqliteHealthChecks(db, {}).map((p) => async () => {
+ *   const r = await p.check();
+ *   return { id: p.name, title: p.description, category: 'Database',
+ *            severity: 'warn', status: r.status, detail: r.message ?? '', remediation: [] };
+ * }));
+ * ```
+ *
+ * `status` values (`ok`/`warn`/`error`) already line up with cwip's `HealthStatus`.
+ */
+export type SqliteHealthStatus = 'ok' | 'warn' | 'error';
+export interface SqliteHealthResult {
+    status: SqliteHealthStatus;
+    /** Human-readable detail for the current status. */
+    message?: string;
+}
+export interface SqliteHealthCheck {
+    /** Stable id, e.g. `'sqlite:integrity'`. */
+    name: string;
+    /** Short human description. */
+    description: string;
+    check(): Promise<SqliteHealthResult>;
+}
+export interface SqliteHealthOpts {
+    /** Warn when the DB file exceeds this many bytes. Default: 500 MB. */
+    maxSizeBytes?: number;
+    /** Warn when the WAL holds more than this many pages. Default: 1000. */
+    maxWalPages?: number;
+}
+/**
+ * Build the SQLite health probes for `db`. Use `quick_check` (fast, still catches
+ * corruption) in the loop; expose the exhaustive `integrity_check` as an
+ * admin-triggered action elsewhere.
+ */
+export declare function createSqliteHealthChecks(db: Database, opts?: SqliteHealthOpts): SqliteHealthCheck[];

package/dist/server/sqlite/health.js

@@ -0,0 +1,52 @@
+const BYTES_PER_MB = 1_048_576;
+const mb = (bytes) => `${(bytes / BYTES_PER_MB).toFixed(1)}MB`;
+/**
+ * Build the SQLite health probes for `db`. Use `quick_check` (fast, still catches
+ * corruption) in the loop; expose the exhaustive `integrity_check` as an
+ * admin-triggered action elsewhere.
+ */
+export function createSqliteHealthChecks(db, opts = {}) {
+    const maxSizeBytes = opts.maxSizeBytes ?? 500 * BYTES_PER_MB;
+    const maxWalPages = opts.maxWalPages ?? 1000;
+    return [
+        {
+            name: 'sqlite:integrity',
+            description: 'SQLite quick_check integrity',
+            async check() {
+                const row = db.query('PRAGMA quick_check').get();
+                const outcome = row ? Object.values(row)[0] : undefined;
+                return outcome === 'ok'
+                    ? { status: 'ok', message: 'ok' }
+                    : { status: 'error', message: outcome ?? 'unknown' };
+            },
+        },
+        {
+            name: 'sqlite:size',
+            description: 'DB file size within threshold',
+            async check() {
+                const info = db
+                    .query('SELECT page_count, page_size FROM pragma_page_count(), pragma_page_size()')
+                    .get();
+                const bytes = (info?.page_count ?? 0) * (info?.page_size ?? 4096);
+                return bytes > maxSizeBytes
+                    ? { status: 'warn', message: `DB is ${mb(bytes)} (threshold: ${mb(maxSizeBytes)})` }
+                    : { status: 'ok', message: mb(bytes) };
+            },
+        },
+        {
+            name: 'sqlite:wal',
+            description: 'WAL checkpoint lag',
+            async check() {
+                // PRAGMA wal_checkpoint returns one row {busy, log, checkpointed}; `log` is the
+                // total WAL pages, or -1 when the DB is not in WAL mode (treat as 0).
+                const row = db
+                    .query('PRAGMA wal_checkpoint(PASSIVE)')
+                    .get();
+                const pages = row && row.log > 0 ? row.log : 0;
+                return pages > maxWalPages
+                    ? { status: 'warn', message: `WAL has ${pages} pages (threshold: ${maxWalPages})` }
+                    : { status: 'ok', message: `${pages} WAL pages` };
+            },
+        },
+    ];
+}

package/dist/server/sqlite/import.d.ts

@@ -0,0 +1,36 @@
+import { Database } from 'bun:sqlite';
+/**
+ * Write-side SQLite primitives — the counterpart to the read-only `browse.ts` /
+ * `export.ts`. Both surfaces are deliberately scoped: row import into an EXISTING
+ * table and whole-DB snapshot restore. No arbitrary DDL, no schema mutation — the
+ * table must already exist, and only its real columns are written.
+ *
+ * Every operation runs inside a transaction so a mid-operation failure rolls the DB
+ * back atomically (stronger than a copy-aside snapshot). Foreign-key enforcement is
+ * suspended for the bulk replace/restore and always restored afterward.
+ */
+export type ImportMode = 'append' | 'replace';
+export interface ImportResult {
+    inserted: number;
+}
+/**
+ * Insert already-parsed rows into an existing table. Unknown keys are dropped (only
+ * columns that actually exist on the table are written); `replace` clears the table
+ * first. Returns the number of rows inserted. Throws {@link UnknownTableError} for a
+ * table not in `sqlite_master`.
+ */
+export declare function importRowsIntoSqliteTable(db: Database, table: string, rows: Record<string, unknown>[], opts?: {
+    mode?: ImportMode;
+}): ImportResult;
+export interface RestoreResult {
+    restoredTables: string[];
+    totalRows: number;
+}
+/**
+ * Restore a `.sqlite` snapshot into the live DB, table by table. For every table
+ * present in BOTH the snapshot and the target, the target's rows are replaced by the
+ * snapshot's (via `ATTACH` + `INSERT … SELECT`). Tables that exist only in the
+ * snapshot (or only in the target) are left untouched — this is a data restore, not
+ * a schema migration. Atomic: any failure rolls the whole restore back.
+ */
+export declare function restoreSqliteSnapshot(db: Database, bytes: Uint8Array): RestoreResult;

package/dist/server/sqlite/import.js

@@ -0,0 +1,108 @@
+import { Database } from 'bun:sqlite';
+import { withForeignKeysOff } from 'cwip/sqlite';
+import { rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { isKnownTable, quoteIdent, UnknownTableError } from './browse';
+/** Real column names of a table, in declared order. */
+function tableColumns(db, table) {
+    return db
+        .query(`PRAGMA table_info(${quoteIdent(table)})`)
+        .all()
+        .map((r) => r.name);
+}
+/**
+ * Insert already-parsed rows into an existing table. Unknown keys are dropped (only
+ * columns that actually exist on the table are written); `replace` clears the table
+ * first. Returns the number of rows inserted. Throws {@link UnknownTableError} for a
+ * table not in `sqlite_master`.
+ */
+export function importRowsIntoSqliteTable(db, table, rows, opts = {}) {
+    if (!isKnownTable(db, table))
+        throw new UnknownTableError(table);
+    const mode = opts.mode ?? 'append';
+    const valid = new Set(tableColumns(db, table));
+    // Columns to write = table columns present in at least one row (preserve order).
+    const cols = tableColumns(db, table).filter((c) => rows.some((r) => c in r && valid.has(c)));
+    const runImport = db.transaction(() => {
+        if (mode === 'replace')
+            db.run(`DELETE FROM ${quoteIdent(table)}`);
+        if (rows.length === 0 || cols.length === 0)
+            return 0;
+        const placeholders = cols.map(() => '?').join(', ');
+        const colList = cols.map(quoteIdent).join(', ');
+        const stmt = db.prepare(`INSERT INTO ${quoteIdent(table)} (${colList}) VALUES (${placeholders})`);
+        let inserted = 0;
+        for (const row of rows) {
+            stmt.run(...cols.map((c) => normalizeValue(row[c])));
+            inserted++;
+        }
+        return inserted;
+    });
+    const inserted = mode === 'replace' ? withForeignKeysOff(db, runImport) : runImport();
+    return { inserted };
+}
+/** bun:sqlite binds string/number/bigint/boolean/null/Uint8Array; coerce the rest. */
+function normalizeValue(v) {
+    if (v === undefined || v === null)
+        return null;
+    if (typeof v === 'string' ||
+        typeof v === 'number' ||
+        typeof v === 'bigint' ||
+        typeof v === 'boolean' ||
+        v instanceof Uint8Array) {
+        return v;
+    }
+    // Objects/arrays → JSON text (the pragmatic choice for a foreign-format import).
+    return JSON.stringify(v);
+}
+/**
+ * Restore a `.sqlite` snapshot into the live DB, table by table. For every table
+ * present in BOTH the snapshot and the target, the target's rows are replaced by the
+ * snapshot's (via `ATTACH` + `INSERT … SELECT`). Tables that exist only in the
+ * snapshot (or only in the target) are left untouched — this is a data restore, not
+ * a schema migration. Atomic: any failure rolls the whole restore back.
+ */
+export function restoreSqliteSnapshot(db, bytes) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const tmp = join(tmpdir(), `cb-restore-${stamp}-${Math.random().toString(36).slice(2)}.sqlite`);
+    writeFileSync(tmp, bytes);
+    try {
+        // Validate it opens as SQLite and enumerate its user tables.
+        const snap = new Database(tmp, { readonly: true });
+        let snapTables;
+        try {
+            snapTables = snap
+                .query("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")
+                .all()
+                .map((r) => r.name);
+        }
+        finally {
+            snap.close();
+        }
+        const targets = snapTables.filter((t) => isKnownTable(db, t));
+        let totalRows = 0;
+        withForeignKeysOff(db, () => {
+            db.run('ATTACH DATABASE ? AS restore_src', [tmp]);
+            try {
+                const run = db.transaction(() => {
+                    for (const t of targets) {
+                        const q = quoteIdent(t);
+                        db.run(`DELETE FROM main.${q}`);
+                        db.run(`INSERT INTO main.${q} SELECT * FROM restore_src.${q}`);
+                        totalRows +=
+                            db.query(`SELECT COUNT(*) AS n FROM main.${q}`).get()?.n ?? 0;
+                    }
+                });
+                run();
+            }
+            finally {
+                db.run('DETACH DATABASE restore_src');
+            }
+        });
+        return { restoredTables: targets, totalRows };
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+}