@skillsmith/core 0.4.8 → 0.4.10

package/dist/src/db/createDatabase.js

@@ -0,0 +1,139 @@
+/**
+ * SMI-2180: Database Factory with Auto-Detection
+ *
+ * Creates database connections with automatic driver selection:
+ * 1. Try native better-sqlite3 first (fastest, requires native module)
+ * 2. Fall back to sql.js WASM (cross-platform, no native compilation)
+ *
+ * This enables the MCP server to work on any platform without Docker.
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect best driver
+ * const db = await createDatabaseAsync('~/.skillsmith/skills.db')
+ *
+ * // Force specific driver
+ * const db = createDatabaseSync(path)  // better-sqlite3 only
+ * ```
+ */
+import { createBetterSqlite3Database, isBetterSqlite3Available, } from './drivers/betterSqlite3Driver.js';
+import { createSqlJsDatabase, isSqlJsAvailable } from './drivers/sqljsDriver.js';
+/**
+ * Detect which database drivers are available
+ * @returns Array of driver info objects
+ */
+export function detectAvailableDrivers() {
+    const drivers = [];
+    // Check better-sqlite3
+    if (isBetterSqlite3Available()) {
+        drivers.push({ type: 'better-sqlite3', available: true });
+    }
+    else {
+        drivers.push({
+            type: 'better-sqlite3',
+            available: false,
+            reason: 'Native module not available (binary incompatibility or not installed)',
+        });
+    }
+    // Check sql.js (WASM - always available in Node.js)
+    if (isSqlJsAvailable()) {
+        drivers.push({ type: 'sql.js', available: true });
+    }
+    else {
+        drivers.push({
+            type: 'sql.js',
+            available: false,
+            reason: 'sql.js package not installed',
+        });
+    }
+    return drivers;
+}
+/**
+ * Get the best available driver type
+ * @returns The driver type to use, or null if none available
+ */
+export function getBestDriver() {
+    // Prefer native for performance
+    if (isBetterSqlite3Available()) {
+        return 'better-sqlite3';
+    }
+    // Fall back to sql.js WASM
+    if (isSqlJsAvailable()) {
+        return 'sql.js';
+    }
+    return null;
+}
+/**
+ * Create a database connection synchronously using better-sqlite3
+ *
+ * Use this when you know native modules are available (e.g., in Docker).
+ * For cross-platform code, use createDatabaseAsync instead.
+ *
+ * @param path - Path to database file, or ':memory:' for in-memory
+ * @param options - Database connection options
+ * @returns Database instance
+ * @throws Error if better-sqlite3 is not available
+ */
+export function createDatabaseSync(path = ':memory:', options) {
+    if (!isBetterSqlite3Available()) {
+        throw new Error('[Skillsmith] Native SQLite module (better-sqlite3) is not available. ' +
+            'This may be due to:\n' +
+            '  - Binary compiled for a different platform (Linux vs macOS)\n' +
+            '  - Node.js version mismatch\n' +
+            '  - Missing native build tools\n\n' +
+            'Solutions:\n' +
+            '  - Run in Docker: docker compose --profile dev up -d\n' +
+            '  - Rebuild native module: npm rebuild better-sqlite3\n' +
+            '  - Use createDatabaseAsync() for automatic WASM fallback');
+    }
+    return createBetterSqlite3Database(path, options);
+}
+/**
+ * Create a database connection with automatic driver selection
+ *
+ * This is the recommended way to create database connections for
+ * cross-platform compatibility. It will:
+ * 1. Try better-sqlite3 native module first (fastest)
+ * 2. Fall back to sql.js WASM if native is unavailable
+ *
+ * @param path - Path to database file, or ':memory:' for in-memory
+ * @param options - Database connection options
+ * @returns Promise resolving to Database instance
+ * @throws Error if no database driver is available
+ */
+export async function createDatabaseAsync(path = ':memory:', options) {
+    // Try native first
+    if (isBetterSqlite3Available()) {
+        return createBetterSqlite3Database(path, options);
+    }
+    // Fall back to sql.js WASM
+    if (isSqlJsAvailable()) {
+        console.warn('[Skillsmith] Native SQLite unavailable, using WASM driver');
+        return await createSqlJsDatabase(path, options);
+    }
+    throw new Error('[Skillsmith] No SQLite driver available.\n\n' +
+        'Neither better-sqlite3 (native) nor sql.js (WASM) could be loaded.\n\n' +
+        'Solutions:\n' +
+        '  - Run in Docker: docker compose --profile dev up -d\n' +
+        '  - Rebuild native module: npm rebuild better-sqlite3\n' +
+        '  - Install sql.js: npm install sql.js');
+}
+/**
+ * @deprecated Use createDatabaseAsync() instead for cross-platform support.
+ *
+ * createDatabase() only works with native better-sqlite3 and will fail on
+ * platforms where native modules aren't available (e.g., macOS without Docker).
+ *
+ * Migration:
+ * ```typescript
+ * // Before (synchronous, native only)
+ * const db = createDatabase(path)
+ *
+ * // After (async, with automatic WASM fallback)
+ * const db = await createDatabaseAsync(path)
+ * ```
+ *
+ * This alias is maintained for backward compatibility with existing code.
+ */
+export const createDatabase = createDatabaseSync;
+//# sourceMappingURL=createDatabase.js.map

package/dist/src/db/createDatabase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createDatabase.js","sourceRoot":"","sources":["../../../src/db/createDatabase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,kCAAkC,CAAA;AACzC,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAgBhF;;;GAGG;AACH,MAAM,UAAU,sBAAsB;IACpC,MAAM,OAAO,GAAiB,EAAE,CAAA;IAEhC,uBAAuB;IACvB,IAAI,wBAAwB,EAAE,EAAE,CAAC;QAC/B,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAC3D,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,gBAAgB;YACtB,SAAS,EAAE,KAAK;YAChB,MAAM,EAAE,uEAAuE;SAChF,CAAC,CAAA;IACJ,CAAC;IAED,oDAAoD;IACpD,IAAI,gBAAgB,EAAE,EAAE,CAAC;QACvB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACnD,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,KAAK;YAChB,MAAM,EAAE,8BAA8B;SACvC,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa;IAC3B,gCAAgC;IAChC,IAAI,wBAAwB,EAAE,EAAE,CAAC;QAC/B,OAAO,gBAAgB,CAAA;IACzB,CAAC;IAED,2BAA2B;IAC3B,IAAI,gBAAgB,EAAE,EAAE,CAAC;QACvB,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe,UAAU,EAAE,OAAyB;IACrF,IAAI,CAAC,wBAAwB,EAAE,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,uEAAuE;YACrE,uBAAuB;YACvB,iEAAiE;YACjE,gCAAgC;YAChC,oCAAoC;YACpC,cAAc;YACd,yDAAyD;YACzD,yDAAyD;YACzD,2DAA2D,CAC9D,CAAA;IACH,CAAC;IAED,OAAO,2BAA2B,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;AACnD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAe,UAAU,EACzB,OAAyB;IAEzB,mBAAmB;IACnB,IAAI,wBAAwB,EAAE,EAAE,CAAC;QAC/B,OAAO,2BAA2B,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IACnD,CAAC;IAED,2BAA2B;IAC3B,IAAI,gBAAgB,EAAE,EAAE,CAAC;QACvB,OAAO,CAAC,IAAI,CAAC,2DAA2D,CAAC,CAAA;QACzE,OAAO,MAAM,mBAAmB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IACjD,CAAC;IAED,MAAM,IAAI,KAAK,CACb,8CAA8C;QAC5C,wEAAwE;QACxE,cAAc;QACd,yDAAyD;QACzD,yDAAyD;QACzD,wCAAwC,CAC3C,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,kBAAkB,CAAA"}

package/dist/src/db/database-interface.d.ts

@@ -0,0 +1,141 @@
+/**
+ * SMI-2180: Database Abstraction Layer
+ *
+ * Provides a unified interface for SQLite operations that works with both:
+ * - better-sqlite3 (native, synchronous) - used in Docker/Linux
+ * - sql.js (WASM, async) - used on macOS/WebContainers
+ *
+ * This abstraction enables cross-platform MCP server execution without
+ * requiring native module compilation.
+ *
+ * @see docs/issues/mcp-server-native-module-fix-wasm.md
+ */
+/**
+ * Result of a database write operation (INSERT, UPDATE, DELETE)
+ */
+export interface RunResult {
+    /** Number of rows changed by the operation */
+    changes: number;
+    /** Row ID of the last inserted row (for INSERT operations) */
+    lastInsertRowid: number | bigint;
+}
+/**
+ * A prepared SQL statement that can be executed multiple times with different parameters.
+ *
+ * Type parameter T represents the shape of rows returned by SELECT queries.
+ */
+export interface Statement<T = unknown> {
+    /**
+     * Execute a write operation (INSERT, UPDATE, DELETE)
+     * @param params - Bound parameters for the SQL statement
+     * @returns Result containing changes count and last insert rowid
+     */
+    run(...params: unknown[]): RunResult;
+    /**
+     * Execute a SELECT query and return the first matching row
+     * @param params - Bound parameters for the SQL statement
+     * @returns The first row or undefined if no rows match
+     */
+    get(...params: unknown[]): T | undefined;
+    /**
+     * Execute a SELECT query and return all matching rows
+     * @param params - Bound parameters for the SQL statement
+     * @returns Array of all matching rows
+     */
+    all(...params: unknown[]): T[];
+    /**
+     * Execute a SELECT query and iterate over results
+     * Useful for large result sets to avoid loading all rows into memory
+     * @param params - Bound parameters for the SQL statement
+     * @returns Iterator over matching rows
+     */
+    iterate(...params: unknown[]): IterableIterator<T>;
+    /**
+     * Release resources associated with this prepared statement
+     * Should be called when the statement is no longer needed
+     */
+    finalize(): void;
+    /**
+     * Bind parameters to the statement for later execution
+     * @param params - Parameters to bind
+     * @returns The statement for chaining
+     */
+    bind(...params: unknown[]): this;
+}
+/**
+ * Database connection interface that abstracts SQLite operations.
+ *
+ * Implementations:
+ * - BetterSqlite3Database: Wraps better-sqlite3 for native performance
+ * - SqlJsDatabase: Wraps sql.js for cross-platform WASM support
+ */
+export interface Database {
+    /**
+     * Execute raw SQL without returning results
+     * Useful for DDL statements (CREATE, DROP, ALTER) and multi-statement scripts
+     * @param sql - SQL statement(s) to execute
+     */
+    exec(sql: string): void;
+    /**
+     * Prepare a SQL statement for repeated execution
+     * @param sql - SQL statement with optional parameter placeholders (?)
+     * @returns A prepared statement that can be executed multiple times
+     */
+    prepare<T = unknown>(sql: string): Statement<T>;
+    /**
+     * Execute a function within a transaction
+     * If the function throws, the transaction is rolled back
+     *
+     * Returns a callable function that executes the transaction when called.
+     * For zero-argument functions, call as: db.transaction(fn)()
+     *
+     * @param fn - Function to execute within transaction
+     * @returns A callable transaction function
+     */
+    transaction<T, Args extends unknown[] = []>(fn: (...args: Args) => T): (...args: Args) => T;
+    /**
+     * Execute a PRAGMA statement and return the result
+     * @param pragma - PRAGMA statement (e.g., 'foreign_keys = ON')
+     * @returns The PRAGMA result value, or undefined for set operations
+     */
+    pragma(pragma: string): unknown;
+    /**
+     * Close the database connection and release all resources
+     * For file-based databases, this ensures all changes are persisted
+     */
+    close(): void;
+    /**
+     * Check if the database connection is open
+     */
+    readonly open: boolean;
+    /**
+     * The file path of the database, or ':memory:' for in-memory databases
+     */
+    readonly name: string;
+    /**
+     * Whether the database is in-memory
+     */
+    readonly memory: boolean;
+    /**
+     * Whether the database is read-only
+     */
+    readonly readonly: boolean;
+}
+/**
+ * Options for creating a database connection
+ */
+export interface DatabaseOptions {
+    /** Open database in read-only mode */
+    readonly?: boolean;
+    /** Create database file if it doesn't exist (default: true) */
+    fileMustExist?: boolean;
+    /** Set busy timeout in milliseconds (default: 5000) */
+    timeout?: number;
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+/**
+ * Factory function type for creating database connections
+ */
+export type DatabaseFactory = (path: string, options?: DatabaseOptions) => Database | Promise<Database>;
+//# sourceMappingURL=database-interface.d.ts.map

package/dist/src/db/database-interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-interface.d.ts","sourceRoot":"","sources":["../../../src/db/database-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,eAAe,EAAE,MAAM,GAAG,MAAM,CAAA;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IACpC;;;;OAIG;IACH,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,SAAS,CAAA;IAEpC;;;;OAIG;IACH,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,GAAG,SAAS,CAAA;IAExC;;;;OAIG;IACH,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,CAAA;IAE9B;;;;;OAKG;IACH,OAAO,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAA;IAElD;;;OAGG;IACH,QAAQ,IAAI,IAAI,CAAA;IAEhB;;;;OAIG;IACH,IAAI,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CACjC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;OAIG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAEvB;;;;OAIG;IACH,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;IAE/C;;;;;;;;;OASG;IACH,WAAW,CAAC,CAAC,EAAE,IAAI,SAAS,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,CAAA;IAE3F;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;IAE/B;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAA;IAEb;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IAEtB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IAExB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,eAAe,KACtB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA"}

package/dist/src/db/database-interface.js

@@ -0,0 +1,14 @@
+/**
+ * SMI-2180: Database Abstraction Layer
+ *
+ * Provides a unified interface for SQLite operations that works with both:
+ * - better-sqlite3 (native, synchronous) - used in Docker/Linux
+ * - sql.js (WASM, async) - used on macOS/WebContainers
+ *
+ * This abstraction enables cross-platform MCP server execution without
+ * requiring native module compilation.
+ *
+ * @see docs/issues/mcp-server-native-module-fix-wasm.md
+ */
+export {};
+//# sourceMappingURL=database-interface.js.map

package/dist/src/db/database-interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-interface.js","sourceRoot":"","sources":["../../../src/db/database-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/src/db/drivers/betterSqlite3Driver.d.ts

@@ -0,0 +1,48 @@
+/**
+ * SMI-2180: better-sqlite3 Driver Implementation
+ *
+ * Wraps the better-sqlite3 library to implement the Database abstraction interface.
+ * This driver is used when native modules are available (Docker, Linux, CI).
+ *
+ * better-sqlite3 is synchronous and provides excellent performance for local SQLite.
+ *
+ * @see https://github.com/WiseLibs/better-sqlite3
+ */
+import type BetterSqlite3 from 'better-sqlite3';
+import type { Database, Statement, DatabaseOptions } from '../database-interface.js';
+/**
+ * Wraps a better-sqlite3 Database to implement our Database interface
+ */
+export declare class BetterSqlite3Database implements Database {
+    private readonly db;
+    constructor(db: BetterSqlite3.Database);
+    exec(sql: string): void;
+    prepare<T = unknown>(sql: string): Statement<T>;
+    transaction<T, Args extends unknown[] = []>(fn: (...args: Args) => T): (...args: Args) => T;
+    pragma(pragma: string): unknown;
+    close(): void;
+    get open(): boolean;
+    get name(): string;
+    get memory(): boolean;
+    get readonly(): boolean;
+    /**
+     * Get the underlying better-sqlite3 database instance
+     * Use with caution - this bypasses the abstraction layer
+     */
+    get native(): BetterSqlite3.Database;
+}
+/**
+ * Create a database connection using better-sqlite3
+ *
+ * @param path - Path to database file, or ':memory:' for in-memory database
+ * @param options - Database connection options
+ * @returns A Database instance wrapping better-sqlite3
+ * @throws Error if better-sqlite3 native module is not available
+ */
+export declare function createBetterSqlite3Database(path?: string, options?: DatabaseOptions): BetterSqlite3Database;
+/**
+ * Check if better-sqlite3 native module is available
+ * @returns true if the native module can be loaded
+ */
+export declare function isBetterSqlite3Available(): boolean;
+//# sourceMappingURL=betterSqlite3Driver.d.ts.map

package/dist/src/db/drivers/betterSqlite3Driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"betterSqlite3Driver.d.ts","sourceRoot":"","sources":["../../../../src/db/drivers/betterSqlite3Driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,aAAa,MAAM,gBAAgB,CAAA;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAa,eAAe,EAAE,MAAM,0BAA0B,CAAA;AA0C/F;;GAEG;AACH,qBAAa,qBAAsB,YAAW,QAAQ;IACxC,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,aAAa,CAAC,QAAQ;IAEvD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIvB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAK/C,WAAW,CAAC,CAAC,EAAE,IAAI,SAAS,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC;IAK3F,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI/B,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,OAAO,CAElB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;OAGG;IACH,IAAI,MAAM,IAAI,aAAa,CAAC,QAAQ,CAEnC;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,GAAE,MAAmB,EACzB,OAAO,CAAC,EAAE,eAAe,GACxB,qBAAqB,CAyBvB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAWlD"}

package/dist/src/db/drivers/betterSqlite3Driver.js

@@ -0,0 +1,138 @@
+/**
+ * SMI-2180: better-sqlite3 Driver Implementation
+ *
+ * Wraps the better-sqlite3 library to implement the Database abstraction interface.
+ * This driver is used when native modules are available (Docker, Linux, CI).
+ *
+ * better-sqlite3 is synchronous and provides excellent performance for local SQLite.
+ *
+ * @see https://github.com/WiseLibs/better-sqlite3
+ */
+import { createRequire } from 'node:module';
+// ESM-compatible require for native modules
+const require = createRequire(import.meta.url);
+/**
+ * Wraps a better-sqlite3 Statement to implement our Statement interface
+ */
+class BetterSqlite3Statement {
+    stmt;
+    constructor(stmt) {
+        this.stmt = stmt;
+    }
+    run(...params) {
+        const result = this.stmt.run(...params);
+        return {
+            changes: result.changes,
+            lastInsertRowid: result.lastInsertRowid,
+        };
+    }
+    get(...params) {
+        return this.stmt.get(...params);
+    }
+    all(...params) {
+        return this.stmt.all(...params);
+    }
+    iterate(...params) {
+        return this.stmt.iterate(...params);
+    }
+    finalize() {
+        // better-sqlite3 doesn't require explicit finalization
+        // Statements are automatically cleaned up when garbage collected
+    }
+    bind(...params) {
+        this.stmt.bind(...params);
+        return this;
+    }
+}
+/**
+ * Wraps a better-sqlite3 Database to implement our Database interface
+ */
+export class BetterSqlite3Database {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    exec(sql) {
+        this.db.exec(sql);
+    }
+    prepare(sql) {
+        const stmt = this.db.prepare(sql);
+        return new BetterSqlite3Statement(stmt);
+    }
+    transaction(fn) {
+        // better-sqlite3 transaction returns a wrapped function
+        return this.db.transaction(fn);
+    }
+    pragma(pragma) {
+        return this.db.pragma(pragma);
+    }
+    close() {
+        this.db.close();
+    }
+    get open() {
+        return this.db.open;
+    }
+    get name() {
+        return this.db.name;
+    }
+    get memory() {
+        return this.db.memory;
+    }
+    get readonly() {
+        return this.db.readonly;
+    }
+    /**
+     * Get the underlying better-sqlite3 database instance
+     * Use with caution - this bypasses the abstraction layer
+     */
+    get native() {
+        return this.db;
+    }
+}
+/**
+ * Create a database connection using better-sqlite3
+ *
+ * @param path - Path to database file, or ':memory:' for in-memory database
+ * @param options - Database connection options
+ * @returns A Database instance wrapping better-sqlite3
+ * @throws Error if better-sqlite3 native module is not available
+ */
+export function createBetterSqlite3Database(path = ':memory:', options) {
+    // Dynamic import to avoid loading native module at module evaluation time
+    // This is synchronous because better-sqlite3 is synchronous
+    const Database = require('better-sqlite3');
+    // Build options object, only including defined values
+    // better-sqlite3 doesn't accept undefined for boolean options
+    const dbOptions = {
+        timeout: options?.timeout ?? 5000,
+    };
+    if (options?.readonly !== undefined) {
+        dbOptions.readonly = options.readonly;
+    }
+    if (options?.fileMustExist !== undefined) {
+        dbOptions.fileMustExist = options.fileMustExist;
+    }
+    if (options?.verbose) {
+        dbOptions.verbose = console.log;
+    }
+    const db = new Database(path, dbOptions);
+    return new BetterSqlite3Database(db);
+}
+/**
+ * Check if better-sqlite3 native module is available
+ * @returns true if the native module can be loaded
+ */
+export function isBetterSqlite3Available() {
+    try {
+        const Database = require('better-sqlite3');
+        // Instantiate in-memory DB to trigger dlopen of the native binary.
+        // Catches ABI mismatch (Node upgrade) and platform mismatch (Linux binary on macOS).
+        const testDb = new Database(':memory:');
+        testDb.close();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=betterSqlite3Driver.js.map

package/dist/src/db/drivers/betterSqlite3Driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"betterSqlite3Driver.js","sourceRoot":"","sources":["../../../../src/db/drivers/betterSqlite3Driver.ts"],"names":[],"mappings":"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"}

package/dist/src/db/drivers/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * SMI-2180: Database Driver Exports
+ *
+ * Re-exports all database drivers and utilities.
+ */
+export { BetterSqlite3Database, createBetterSqlite3Database, isBetterSqlite3Available, } from './betterSqlite3Driver.js';
+export { SqlJsDatabaseAdapter, createSqlJsDatabase, isSqlJsAvailable } from './sqljsDriver.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/db/drivers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/db/drivers/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,0BAA0B,CAAA;AAEjC,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/src/db/drivers/index.js

@@ -0,0 +1,8 @@
+/**
+ * SMI-2180: Database Driver Exports
+ *
+ * Re-exports all database drivers and utilities.
+ */
+export { BetterSqlite3Database, createBetterSqlite3Database, isBetterSqlite3Available, } from './betterSqlite3Driver.js';
+export { SqlJsDatabaseAdapter, createSqlJsDatabase, isSqlJsAvailable } from './sqljsDriver.js';
+//# sourceMappingURL=index.js.map

package/dist/src/db/drivers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/db/drivers/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,0BAA0B,CAAA;AAEjC,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/src/db/drivers/sqljsDriver.d.ts

@@ -0,0 +1,91 @@
+/**
+ * SMI-2182: sql.js (WASM) Driver Implementation
+ *
+ * Wraps the sql.js library to implement the Database abstraction interface.
+ * This driver is used when native modules are NOT available (macOS, WebContainers).
+ *
+ * sql.js is a JavaScript implementation of SQLite that runs in WebAssembly.
+ * It requires async initialization but provides cross-platform compatibility.
+ *
+ * Key differences from better-sqlite3:
+ * - Async initialization (WASM loading)
+ * - In-memory by default, manual persistence to file
+ * - Different API for prepared statements
+ *
+ * @see https://github.com/sql-js/sql.js
+ */
+import type { Database, Statement, DatabaseOptions } from '../database-interface.js';
+interface SqlJsDatabase {
+    run(sql: string): void;
+    prepare(sql: string): SqlJsStatement;
+    export(): Uint8Array;
+    close(): void;
+}
+interface SqlJsStatement {
+    bind(params?: SqlJsBindParams): boolean;
+    step(): boolean;
+    get(): SqlJsValue[];
+    getColumnNames(): string[];
+    reset(): void;
+    free(): void;
+}
+type SqlJsValue = string | number | null | Uint8Array;
+type SqlJsBindParams = SqlJsValue[] | Record<string, SqlJsValue>;
+/**
+ * Wraps a sql.js Database to implement our Database interface
+ */
+export declare class SqlJsDatabaseAdapter implements Database {
+    private readonly db;
+    private readonly filePath;
+    private _open;
+    private readonly _memory;
+    private readonly _readonly;
+    private _transactionDepth;
+    constructor(db: SqlJsDatabase, filePath: string, options?: DatabaseOptions);
+    exec(sql: string): void;
+    prepare<T = unknown>(sql: string): Statement<T>;
+    transaction<T, Args extends unknown[] = []>(fn: (...args: Args) => T): (...args: Args) => T;
+    pragma(pragma: string): unknown;
+    close(): void;
+    /**
+     * Persist the in-memory database to file
+     */
+    persist(): void;
+    /**
+     * Export the database as a Uint8Array
+     * Useful for manual persistence or serialization
+     */
+    export(): Uint8Array;
+    get open(): boolean;
+    get name(): string;
+    get memory(): boolean;
+    get readonly(): boolean;
+    /**
+     * Get the underlying sql.js database instance
+     * Use with caution - this bypasses the abstraction layer
+     */
+    get native(): SqlJsDatabase;
+}
+/**
+ * Create a database connection using sql.js (WASM)
+ *
+ * @param path - Path to database file, or ':memory:' for in-memory database
+ * @param options - Database connection options
+ * @returns Promise resolving to a Database instance wrapping sql.js
+ * @throws Error if sql.js WASM module fails to load
+ */
+export declare function createSqlJsDatabase(path?: string, options?: DatabaseOptions): Promise<SqlJsDatabaseAdapter>;
+/**
+ * Check if fts5-sql-bundle (sql.js with FTS5) is available
+ * This always returns true in Node.js since it's a pure JS/WASM module
+ *
+ * Note: We use require.resolve() here instead of dynamic import() because:
+ * 1. This is a synchronous availability check - dynamic import would require async
+ * 2. require.resolve() is fast and doesn't load the module, just checks resolvability
+ * 3. The actual loading in loadSqlJs() uses dynamic import() for proper ESM support
+ *
+ * @returns true if fts5-sql-bundle is loadable in Node.js
+ */
+export declare function isSqlJsAvailable(): boolean;
+export {};
+//# sourceMappingURL=sqljsDriver.d.ts.map

package/dist/src/db/drivers/sqljsDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqljsDriver.d.ts","sourceRoot":"","sources":["../../../../src/db/drivers/sqljsDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAa,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAY/F,UAAU,aAAa;IACrB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAA;IACpC,MAAM,IAAI,UAAU,CAAA;IACpB,KAAK,IAAI,IAAI,CAAA;CACd;AAED,UAAU,cAAc;IACtB,IAAI,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,OAAO,CAAA;IACvC,IAAI,IAAI,OAAO,CAAA;IACf,GAAG,IAAI,UAAU,EAAE,CAAA;IACnB,cAAc,IAAI,MAAM,EAAE,CAAA;IAC1B,KAAK,IAAI,IAAI,CAAA;IACb,IAAI,IAAI,IAAI,CAAA;CACb;AAGD,KAAK,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,UAAU,CAAA;AACrD,KAAK,eAAe,GAAG,UAAU,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;AAqKhE;;GAEG;AACH,qBAAa,oBAAqB,YAAW,QAAQ;IAQjD,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAR3B,OAAO,CAAC,KAAK,CAAO;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,OAAO,CAAC,iBAAiB,CAAI;gBAGV,EAAE,EAAE,aAAa,EACjB,QAAQ,EAAE,MAAM,EACjC,OAAO,CAAC,EAAE,eAAe;IAM3B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIvB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAI/C,WAAW,CAAC,CAAC,EAAE,IAAI,SAAS,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC;IAuC3F,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAsB/B,KAAK,IAAI,IAAI;IAYb;;OAEG;IACH,OAAO,IAAI,IAAI;IAOf;;;OAGG;IACH,MAAM,IAAI,UAAU;IAIpB,IAAI,IAAI,IAAI,OAAO,CAElB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;OAGG;IACH,IAAI,MAAM,IAAI,aAAa,CAE1B;CACF;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,GAAE,MAAmB,EACzB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,oBAAoB,CAAC,CAqB/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAO1C"}