@clawchatsai/connector 0.0.1

package/dist/index.js

@@ -0,0 +1,544 @@
+/**
+ * @shellchat/tunnel — OpenClaw plugin entry point
+ *
+ * Registers ShellChat as a gateway plugin, providing:
+ * - Local HTTP API bridge via createApp()
+ * - WebRTC DataChannel for browser connections
+ * - Signaling client for NAT traversal
+ * - Gateway bridge for local OpenClaw communication
+ *
+ * Spec: specs/multitenant-p2p.md sections 6.1-6.2
+ */
+import * as fs from 'node:fs';
+import * as http from 'node:http';
+import * as path from 'node:path';
+import { SignalingClient } from './signaling-client.js';
+import { WebRTCPeerManager } from './webrtc-peer.js';
+import { dispatchRpc } from './shim.js';
+import { checkForUpdates, performUpdate } from './updater.js';
+// Inline from shared/api-version.ts to avoid rootDir conflict
+const CURRENT_API_VERSION = 1;
+export const PLUGIN_ID = 'tunnel';
+export const PLUGIN_VERSION = '0.0.1';
+/** Max DataChannel message size (~256KB, leave room for envelope) */
+const MAX_DC_MESSAGE_SIZE = 256 * 1024;
+/** Active DataChannel connections: connectionId → send function */
+const connectedClients = new Map();
+let app = null;
+let signaling = null;
+let webrtcPeer = null;
+let healthServer = null;
+// ---------------------------------------------------------------------------
+// Config helpers
+// ---------------------------------------------------------------------------
+const CONFIG_DIR = path.join(process.env.HOME || '/root', '.openclaw', 'shellchat');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+const RUNTIME_FILE = path.join(CONFIG_DIR, 'runtime.json');
+function loadConfig() {
+    try {
+        const raw = fs.readFileSync(CONFIG_FILE, 'utf8');
+        const cfg = JSON.parse(raw);
+        if (!cfg.userId || !cfg.apiKey || !cfg.serverUrl) {
+            return null;
+        }
+        return cfg;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Service lifecycle
+// ---------------------------------------------------------------------------
+async function startShellChat(ctx, api) {
+    const config = loadConfig();
+    if (!config) {
+        ctx.logger.info('ShellChat not configured. Run: openclaw shellchat setup <token>');
+        return;
+    }
+    // 1. Check for updates
+    const update = await checkForUpdates();
+    if (update) {
+        ctx.logger.info(`Update available: ${update.current} → ${update.latest}`);
+        if (ctx._forceUpdate) {
+            try {
+                await performUpdate();
+                ctx.logger.info(`Updated to ${update.latest}. Requesting graceful restart...`);
+                api.runtime.requestRestart?.('shellchat update');
+                return; // will restart with new version
+            }
+            catch (e) {
+                ctx.logger.error(`Auto-update failed: ${e.message}`);
+            }
+        }
+    }
+    // 2. Resolve gateway token: runtime API → config file → error
+    const gwCfg = api.config;
+    const gwAuth = gwCfg?.['gateway']?.['auth'];
+    const gatewayToken = gwAuth?.['token'] || config.gatewayToken || '';
+    if (!gatewayToken) {
+        ctx.logger.error('No gateway token available. Re-run: openclaw shellchat setup <token>');
+        return;
+    }
+    // 3. Import server.js and create app instance with plugin paths
+    const dataDir = path.join(ctx.stateDir, 'shellchat', 'data');
+    const uploadsDir = path.join(ctx.stateDir, 'shellchat', 'uploads');
+    // Dynamic import of server.js (plain JS, no type declarations)
+    // @ts-expect-error — server.js is plain JS with no .d.ts
+    const serverModule = await import('../server.js');
+    app = serverModule.createApp({
+        dataDir,
+        uploadsDir,
+        gatewayUrl: 'ws://localhost:18789',
+        authToken: '', // P2P: DataChannel is the auth boundary (signaling authenticates both sides)
+        gatewayToken, // For WS auth to local OpenClaw gateway
+    });
+    // 4. Connect createApp's gateway client (handles persistence + event relay)
+    app.gatewayClient.connect();
+    // Wire DataChannel clients as broadcast targets so they receive gateway events
+    app.gatewayClient.addBroadcastTarget((data) => {
+        for (const [id, client] of connectedClients) {
+            try {
+                client.send(JSON.stringify({ type: 'gateway-event', payload: data }));
+            }
+            catch {
+                connectedClients.delete(id);
+            }
+        }
+    });
+    // 5. Connect to signaling server
+    signaling = new SignalingClient(config.serverUrl, config.userId, config.apiKey);
+    signaling.on('connected', () => {
+        ctx.logger.info('Connected to signaling server');
+    });
+    signaling.on('auth-rejected', (reason) => {
+        ctx.logger.error(`Signaling auth rejected: ${reason}`);
+    });
+    signaling.on('version-rejected', (current, minimum) => {
+        ctx.logger.error(`Plugin version ${current} rejected, minimum: ${minimum}`);
+    });
+    signaling.on('force-update', async (targetVersion) => {
+        ctx.logger.info(`Force update to ${targetVersion} requested`);
+        try {
+            await performUpdate();
+            ctx.logger.info('Update complete, requesting restart');
+            api.runtime.requestRestart?.('forced update');
+        }
+        catch (e) {
+            ctx.logger.error(`Force update failed: ${e.message}`);
+        }
+    });
+    signaling.on('account-suspended', (reason) => {
+        ctx.logger.error(`Account suspended: ${reason}`);
+        broadcastToClients({ type: 'account-suspended', reason });
+    });
+    // 6. Initialize WebRTC peer manager
+    webrtcPeer = new WebRTCPeerManager();
+    webrtcPeer.on('datachannel', (dc, connectionId) => {
+        ctx.logger.info(`Browser connected via DataChannel: ${connectionId}`);
+        setupDataChannelHandler(dc, connectionId, ctx);
+        signaling?.reportConnectionCount(webrtcPeer?.activeCount ?? 0);
+    });
+    webrtcPeer.on('datachannel-closed', (connectionId) => {
+        ctx.logger.info(`Browser disconnected: ${connectionId}`);
+        connectedClients.delete(connectionId);
+        signaling?.reportConnectionCount(webrtcPeer?.activeCount ?? 0);
+    });
+    // Wire signaling ICE events to peer manager
+    signaling.on('ice-offer', async (offer) => {
+        if (!webrtcPeer)
+            return;
+        try {
+            const answer = await webrtcPeer.handleOffer(offer);
+            signaling?.sendIceAnswer(answer.connectionId, answer.sdp, answer.candidates);
+        }
+        catch (e) {
+            ctx.logger.error(`ICE offer handling failed: ${e.message}`);
+        }
+    });
+    // ICE servers arrive before offers — buffer them
+    signaling.on('ice-servers', (data) => {
+        webrtcPeer?.setIceServers(data);
+    });
+    // Trickle ICE candidates from browser → plugin
+    signaling.on('ice-candidate', (data) => {
+        webrtcPeer?.handleIceCandidate(data.connectionId, data.candidate);
+    });
+    // Trickle ICE candidates from plugin → browser
+    webrtcPeer.on('ice-candidate-local', (data) => {
+        signaling?.sendIceCandidate(data.connectionId, data.candidate);
+    });
+    await signaling.connect();
+    // 7. Start health endpoint for CLI status queries
+    healthServer = http.createServer((req, res) => {
+        if (req.url === '/status' && req.method === 'GET') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                version: PLUGIN_VERSION,
+                pid: process.pid,
+                uptime: process.uptime(),
+                gateway: { connected: app?.gatewayClient?.connected ?? false },
+                signaling: { connected: signaling?.isConnected ?? false },
+                clients: { active: connectedClients.size },
+            }));
+        }
+        else {
+            res.writeHead(404);
+            res.end();
+        }
+    });
+    healthServer.listen(0, '127.0.0.1', () => {
+        const addr = healthServer.address();
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+        fs.writeFileSync(RUNTIME_FILE, JSON.stringify({
+            pid: process.pid,
+            healthPort: addr.port,
+            startedAt: new Date().toISOString(),
+        }, null, 2), { mode: 0o600 });
+        ctx.logger.info(`Health endpoint on 127.0.0.1:${addr.port}`);
+    });
+    ctx.logger.info('ShellChat service started');
+}
+async function stopShellChat(ctx) {
+    ctx.logger.info('ShellChat service stopping...');
+    // 0. Tear down health endpoint
+    if (healthServer) {
+        healthServer.close();
+        healthServer = null;
+    }
+    try {
+        fs.unlinkSync(RUNTIME_FILE);
+    }
+    catch { /* already gone */ }
+    // 1. Notify connected browsers and close DataChannels
+    for (const [id, client] of connectedClients) {
+        try {
+            client.send(JSON.stringify({ type: 'gateway-shutdown' }));
+        }
+        catch { /* already closed */ }
+        connectedClients.delete(id);
+    }
+    // 2. Close all WebRTC peer connections
+    webrtcPeer?.closeAll();
+    webrtcPeer = null;
+    // 3. Disconnect from signaling server
+    signaling?.disconnect();
+    signaling = null;
+    // 4. Close SQLite databases
+    app?.shutdown();
+    app = null;
+    ctx.logger.info('ShellChat service stopped');
+}
+// ---------------------------------------------------------------------------
+// DataChannel message handler (spec section 6.4)
+// ---------------------------------------------------------------------------
+function setupDataChannelHandler(dc, connectionId, ctx) {
+    connectedClients.set(connectionId, dc);
+    dc.onMessage(async (data) => {
+        console.log(`[DC:${connectionId}] Received: ${data.substring(0, 200)}`);
+        let msg;
+        try {
+            msg = JSON.parse(data);
+        }
+        catch {
+            dc.send(JSON.stringify({ type: 'error', message: 'Invalid JSON' }));
+            return;
+        }
+        switch (msg['type']) {
+            case 'rpc':
+                await handleRpcMessage(dc, msg, ctx);
+                break;
+            case 'gateway-msg':
+                // Forward to local OpenClaw gateway via createApp's gateway client
+                if (app?.gatewayClient && typeof msg['payload'] === 'string') {
+                    app.gatewayClient.sendToGateway(msg['payload']);
+                }
+                break;
+            default:
+                dc.send(JSON.stringify({ type: 'error', message: 'unknown message type' }));
+        }
+    });
+    dc.onClosed(() => {
+        connectedClients.delete(connectionId);
+    });
+}
+async function handleRpcMessage(dc, msg, ctx) {
+    if (!app) {
+        dc.send(JSON.stringify({
+            type: 'rpc-res',
+            id: msg['id'],
+            status: 503,
+            body: { error: 'Plugin not ready' },
+        }));
+        return;
+    }
+    // API version compatibility check
+    const apiVersion = msg['apiVersion'];
+    if (apiVersion && apiVersion > CURRENT_API_VERSION) {
+        dc.send(JSON.stringify({
+            type: 'rpc-res',
+            id: msg['id'],
+            status: 426,
+            body: {
+                error: 'upgrade_required',
+                pluginVersion: PLUGIN_VERSION,
+                message: 'Your gateway plugin needs an update.',
+            },
+        }));
+        return;
+    }
+    const rpcReq = {
+        id: msg['id'] || '',
+        method: msg['method'] || 'GET',
+        url: msg['url'] || '/',
+        headers: msg['headers'] || { 'content-type': 'application/json' },
+        body: msg['body'] != null ? JSON.stringify(msg['body']) : undefined,
+    };
+    try {
+        const response = await dispatchRpc(rpcReq, app.handleRequest);
+        const responseMsg = {
+            type: 'rpc-res',
+            id: response.id,
+            status: response.status,
+            body: response.body,
+        };
+        const responseStr = JSON.stringify(responseMsg);
+        if (responseStr.length > MAX_DC_MESSAGE_SIZE) {
+            sendChunked(dc, response.id, response.status, response.body);
+        }
+        else {
+            dc.send(responseStr);
+        }
+    }
+    catch (e) {
+        ctx.logger.error(`RPC error: ${e.message}`);
+        dc.send(JSON.stringify({
+            type: 'rpc-res',
+            id: msg['id'],
+            status: 500,
+            body: { error: 'Internal plugin error' },
+        }));
+    }
+}
+function sendChunked(dc, id, status, body) {
+    const data = typeof body === 'string' ? body : JSON.stringify(body);
+    const chunkSize = MAX_DC_MESSAGE_SIZE - 200; // room for envelope
+    const totalChunks = Math.ceil(data.length / chunkSize);
+    for (let i = 0; i < totalChunks; i++) {
+        dc.send(JSON.stringify({
+            type: 'rpc-chunk',
+            id,
+            status,
+            index: i,
+            total: totalChunks,
+            data: data.slice(i * chunkSize, (i + 1) * chunkSize),
+        }));
+    }
+}
+// ---------------------------------------------------------------------------
+// Broadcast helper
+// ---------------------------------------------------------------------------
+function broadcastToClients(msg) {
+    const data = JSON.stringify(msg);
+    for (const [id, client] of connectedClients) {
+        try {
+            client.send(data);
+        }
+        catch {
+            connectedClients.delete(id);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Status helper
+// ---------------------------------------------------------------------------
+function formatStatus() {
+    const lines = [];
+    lines.push(`ShellChat Plugin v${PLUGIN_VERSION}`);
+    lines.push(`Gateway: ${app?.gatewayClient?.connected ? 'connected' : 'disconnected'}`);
+    lines.push(`Signaling: ${signaling?.isConnected ? 'connected' : 'disconnected'}`);
+    lines.push(`Clients: ${connectedClients.size}`);
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// CLI handlers
+// ---------------------------------------------------------------------------
+async function handleSetup(token) {
+    // Decode base64 token
+    let tokenData;
+    try {
+        const decoded = Buffer.from(token, 'base64').toString('utf8');
+        tokenData = JSON.parse(decoded);
+    }
+    catch {
+        console.error('Invalid setup token. Check that you copied it correctly.');
+        return;
+    }
+    if (new Date(tokenData.expiresAt) < new Date()) {
+        console.error('Setup token has expired. Generate a new one from shellchat.example.com.');
+        return;
+    }
+    console.log('Setting up ShellChat...');
+    console.log(`  Server: ${tokenData.serverUrl}`);
+    // Generate API key for signaling server auth
+    const { randomBytes } = await import('node:crypto');
+    const apiKey = randomBytes(32).toString('hex');
+    // Read gateway token from OpenClaw config
+    let gatewayToken = '';
+    try {
+        const openclawConfigPath = path.join(process.env.HOME || '/root', '.openclaw', 'openclaw.json');
+        const openclawConfig = JSON.parse(fs.readFileSync(openclawConfigPath, 'utf8'));
+        gatewayToken = openclawConfig.gateway?.auth?.token || openclawConfig.auth?.token || openclawConfig.token || '';
+    }
+    catch {
+        console.error('Could not read gateway token from ~/.openclaw/openclaw.json');
+        console.error('Make sure OpenClaw is installed and configured.');
+        return;
+    }
+    if (!gatewayToken) {
+        console.error('No gateway token found in ~/.openclaw/openclaw.json');
+        return;
+    }
+    // Connect to signaling server to complete setup
+    const { WebSocket } = await import('ws');
+    const ws = new WebSocket(tokenData.serverUrl);
+    await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            ws.close();
+            reject(new Error('Setup timed out'));
+        }, 30_000);
+        ws.on('open', () => {
+            ws.send(JSON.stringify({
+                type: 'setup',
+                setupSecret: tokenData.setupSecret,
+                apiKey,
+            }));
+        });
+        ws.on('message', (raw) => {
+            const msg = JSON.parse(raw.toString());
+            if (msg.type === 'setup-complete') {
+                clearTimeout(timeout);
+                console.log(`  User: ${msg.userId}`);
+                // Save config
+                const config = {
+                    userId: msg.userId,
+                    serverUrl: tokenData.serverUrl,
+                    apiKey,
+                    gatewayToken,
+                    schemaVersion: 1,
+                    installedAt: new Date().toISOString(),
+                };
+                fs.mkdirSync(CONFIG_DIR, { recursive: true });
+                fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+                // Create data directories
+                const dataDir = path.join(CONFIG_DIR, 'data');
+                const uploadsDir = path.join(CONFIG_DIR, 'uploads');
+                fs.mkdirSync(dataDir, { recursive: true });
+                fs.mkdirSync(uploadsDir, { recursive: true });
+                console.log('  ShellChat is ready!');
+                console.log('  Open shellchat.example.com in your browser to start chatting.');
+                ws.close();
+                resolve();
+            }
+            else if (msg.type === 'setup-error') {
+                clearTimeout(timeout);
+                ws.close();
+                reject(new Error(`Setup failed: ${msg.reason}`));
+            }
+        });
+        ws.on('error', (err) => {
+            clearTimeout(timeout);
+            reject(err);
+        });
+    });
+}
+async function handleStatus() {
+    // CLI runs in a separate process — module-level vars are null here.
+    // Query the live service via the health endpoint instead.
+    let runtime;
+    try {
+        runtime = JSON.parse(fs.readFileSync(RUNTIME_FILE, 'utf8'));
+    }
+    catch {
+        console.log('ShellChat: offline (service not running)');
+        return;
+    }
+    // Verify PID is alive
+    try {
+        process.kill(runtime.pid, 0);
+    }
+    catch {
+        console.log('ShellChat: offline (stale runtime file)');
+        try {
+            fs.unlinkSync(RUNTIME_FILE);
+        }
+        catch { /* ignore */ }
+        return;
+    }
+    // Query health endpoint
+    try {
+        const body = await new Promise((resolve, reject) => {
+            const req = http.get(`http://127.0.0.1:${runtime.healthPort}/status`, (res) => {
+                let data = '';
+                res.on('data', (chunk) => { data += chunk; });
+                res.on('end', () => resolve(data));
+            });
+            req.on('error', reject);
+            req.setTimeout(3000, () => { req.destroy(); reject(new Error('timeout')); });
+        });
+        const status = JSON.parse(body);
+        console.log(`ShellChat Plugin v${status.version}`);
+        console.log(`Uptime: ${Math.floor(status.uptime)}s`);
+        console.log(`Gateway: ${status.gateway.connected ? 'connected' : 'disconnected'}`);
+        console.log(`Signaling: ${status.signaling.connected ? 'connected' : 'disconnected'}`);
+        console.log(`Clients: ${status.clients.active}`);
+    }
+    catch {
+        console.log('ShellChat: offline (could not reach service)');
+    }
+}
+async function handleReset() {
+    try {
+        fs.rmSync(CONFIG_DIR, { recursive: true, force: true });
+        console.log('ShellChat data removed. Plugin disconnected.');
+    }
+    catch (e) {
+        console.error(`Reset failed: ${e.message}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Plugin definition
+// ---------------------------------------------------------------------------
+const plugin = {
+    id: PLUGIN_ID,
+    name: 'ShellChat',
+    description: 'Connects your gateway to ShellChat via WebRTC P2P',
+    register(api) {
+        // Background service: signaling + gateway bridge + future WebRTC
+        api.registerService({
+            id: 'shellchat-service',
+            start: (ctx) => startShellChat(ctx, api),
+            stop: (ctx) => stopShellChat(ctx),
+        });
+        // CLI commands
+        api.registerCli((ctx) => {
+            const cmd = ctx.program.command('shellchat');
+            cmd.command('setup <token>')
+                .description('Set up ShellChat with a setup token')
+                .action((token) => handleSetup(String(token)));
+            cmd.command('status')
+                .description('Show ShellChat connection status')
+                .action(() => handleStatus());
+            cmd.command('reset')
+                .description('Disconnect and remove all ShellChat data')
+                .action(() => handleReset());
+        });
+        // Slash command for status from any channel
+        api.registerCommand({
+            name: 'shellchat',
+            description: 'Show ShellChat tunnel status',
+            handler: () => ({ text: formatStatus() }),
+        });
+    },
+};
+export default plugin;

package/dist/migrate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Schema migration runner for the ShellChat plugin SQLite database.
+ *
+ * - Tracks schema version in a `_schema_version` table
+ * - Runs migrations sequentially from current version to target
+ * - Creates a backup before migrating (if not `:memory:` and currentVersion > 0)
+ * - Wraps all migrations in a transaction with rollback on error
+ */
+import type Database from 'better-sqlite3';
+export declare const SCHEMA_VERSION = 1;
+/**
+ * Run all pending migrations against the given database.
+ *
+ * Safe to call on every startup — exits early if already up to date.
+ */
+export declare function runMigrations(db: Database): void;

package/dist/migrate.js

@@ -0,0 +1,114 @@
+/**
+ * Schema migration runner for the ShellChat plugin SQLite database.
+ *
+ * - Tracks schema version in a `_schema_version` table
+ * - Runs migrations sequentially from current version to target
+ * - Creates a backup before migrating (if not `:memory:` and currentVersion > 0)
+ * - Wraps all migrations in a transaction with rollback on error
+ */
+import * as fs from 'node:fs';
+export const SCHEMA_VERSION = 1;
+const migrations = [
+    {
+        version: 1,
+        up: (db) => {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS threads (
+          id TEXT PRIMARY KEY,
+          session_key TEXT UNIQUE NOT NULL,
+          title TEXT DEFAULT 'New chat',
+          pinned INTEGER DEFAULT 0,
+          pin_order INTEGER DEFAULT 0,
+          model TEXT,
+          last_session_id TEXT,
+          sort_order INTEGER DEFAULT 0,
+          unread_count INTEGER DEFAULT 0,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        );
+
+        CREATE TABLE IF NOT EXISTS messages (
+          id TEXT PRIMARY KEY,
+          thread_id TEXT NOT NULL,
+          role TEXT NOT NULL,
+          content TEXT NOT NULL,
+          status TEXT DEFAULT 'sent',
+          metadata TEXT,
+          seq INTEGER,
+          timestamp INTEGER NOT NULL,
+          created_at INTEGER NOT NULL,
+          FOREIGN KEY (thread_id) REFERENCES threads(id) ON DELETE CASCADE
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_messages_thread ON messages(thread_id, timestamp);
+        CREATE INDEX IF NOT EXISTS idx_messages_dedup ON messages(thread_id, role, timestamp);
+
+        CREATE TABLE IF NOT EXISTS unread_messages (
+          thread_id TEXT NOT NULL,
+          message_id TEXT NOT NULL,
+          created_at INTEGER NOT NULL,
+          PRIMARY KEY (thread_id, message_id),
+          FOREIGN KEY (thread_id) REFERENCES threads(id) ON DELETE CASCADE
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_unread_thread ON unread_messages(thread_id);
+
+        CREATE VIRTUAL TABLE messages_fts USING fts5(
+          content, content=messages, content_rowid=rowid,
+          tokenize='porter unicode61'
+        );
+
+        CREATE TRIGGER messages_ai AFTER INSERT ON messages BEGIN
+          INSERT INTO messages_fts(rowid, content) VALUES (new.rowid, new.content);
+        END;
+      `);
+        },
+    },
+];
+/**
+ * Run all pending migrations against the given database.
+ *
+ * Safe to call on every startup — exits early if already up to date.
+ */
+export function runMigrations(db) {
+    // Ensure the version-tracking table exists
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS _schema_version (
+      version INTEGER NOT NULL
+    );
+  `);
+    // Read the current schema version (0 = fresh database)
+    const row = db.prepare('SELECT version FROM _schema_version LIMIT 1').get();
+    const currentVersion = row?.version ?? 0;
+    if (currentVersion >= SCHEMA_VERSION) {
+        return;
+    }
+    // Create a backup before migrating an existing database
+    const dbPath = db.name;
+    if (currentVersion > 0 && dbPath !== ':memory:') {
+        const backupPath = `${dbPath}.backup-v${currentVersion}`;
+        fs.copyFileSync(dbPath, backupPath);
+    }
+    // Run all pending migrations inside a single transaction
+    const migrate = db.transaction(() => {
+        for (const migration of migrations) {
+            if (migration.version > currentVersion) {
+                migration.up(db);
+            }
+        }
+        // Record the new schema version
+        if (row === undefined) {
+            db.prepare('INSERT INTO _schema_version (version) VALUES (?)').run(SCHEMA_VERSION);
+        }
+        else {
+            db.prepare('UPDATE _schema_version SET version = ?').run(SCHEMA_VERSION);
+        }
+    });
+    try {
+        migrate();
+    }
+    catch (err) {
+        // better-sqlite3 transactions automatically roll back on throw
+        throw err;
+    }
+}