Add WASM fallbacks for tree-sitter and SQLite, fix installer

Replace native tree-sitter with web-tree-sitter + tree-sitter-wasms for
universal cross-platform support. Add node-sqlite3-wasm as a fallback
when better-sqlite3 native bindings aren't available. Move better-sqlite3
and sqlite-vss to optionalDependencies so installs never fail.

Fix installer to use npx fallback when global npm install fails, so MCP
config, hooks, and quick-start instructions all work without the bare
codegraph command in PATH.

Fix tests: update schema version expectation, fix db test paths and
method names, extract MAX_OUTPUT_LENGTH as module constant, normalize
Windows path separators in import resolver.

src/db/index.ts

@@ -4,20 +4,22 @@
  * Handles SQLite database initialization and connection management.
  */
 
-import Database from 'better-sqlite3';
+import { SqliteDatabase, createDatabase } from './sqlite-adapter';
 import * as fs from 'fs';
 import * as path from 'path';
 import { SchemaVersion } from '../types';
 import { runMigrations, getCurrentVersion, CURRENT_SCHEMA_VERSION } from './migrations';
 
+export { SqliteDatabase, getActiveBackend } from './sqlite-adapter';
+
 /**
  * Database connection wrapper with lifecycle management
  */
 export class DatabaseConnection {
-  private db: Database.Database;
+  private db: SqliteDatabase;
   private dbPath: string;
 
-  private constructor(db: Database.Database, dbPath: string) {
+  private constructor(db: SqliteDatabase, dbPath: string) {
     this.db = db;
     this.dbPath = dbPath;
   }
@@ -33,7 +35,7 @@ export class DatabaseConnection {
     }
 
     // Create and configure database
-    const db = new Database(dbPath);
+    const db = createDatabase(dbPath);
 
     // Enable foreign keys and WAL mode for better performance
     db.pragma('foreign_keys = ON');
@@ -71,7 +73,7 @@ export class DatabaseConnection {
       throw new Error(`Database not found: ${dbPath}`);
     }
 
-    const db = new Database(dbPath);
+    const db = createDatabase(dbPath);
 
     // Enable foreign keys and WAL mode
     db.pragma('foreign_keys = ON');
@@ -99,7 +101,7 @@ export class DatabaseConnection {
   /**
    * Get the underlying database instance
    */
-  getDb(): Database.Database {
+  getDb(): SqliteDatabase {
     return this.db;
   }
 

src/db/migrations.ts

@@ -4,7 +4,7 @@
  * Schema versioning and migration support.
  */
 
-import Database from 'better-sqlite3';
+import { SqliteDatabase } from './sqlite-adapter';
 
 /**
  * Current schema version
@@ -17,7 +17,7 @@ export const CURRENT_SCHEMA_VERSION = 2;
 interface Migration {
   version: number;
   description: string;
-  up: (db: Database.Database) => void;
+  up: (db: SqliteDatabase) => void;
 }
 
 /**
@@ -50,7 +50,7 @@ const migrations: Migration[] = [
 /**
  * Get the current schema version from the database
  */
-export function getCurrentVersion(db: Database.Database): number {
+export function getCurrentVersion(db: SqliteDatabase): number {
   try {
     const row = db
       .prepare('SELECT MAX(version) as version FROM schema_versions')
@@ -65,7 +65,7 @@ export function getCurrentVersion(db: Database.Database): number {
 /**
  * Record a migration as applied
  */
-function recordMigration(db: Database.Database, version: number, description: string): void {
+function recordMigration(db: SqliteDatabase, version: number, description: string): void {
   db.prepare(
     'INSERT INTO schema_versions (version, applied_at, description) VALUES (?, ?, ?)'
   ).run(version, Date.now(), description);
@@ -74,7 +74,7 @@ function recordMigration(db: Database.Database, version: number, description: st
 /**
  * Run all pending migrations
  */
-export function runMigrations(db: Database.Database, fromVersion: number): void {
+export function runMigrations(db: SqliteDatabase, fromVersion: number): void {
   const pending = migrations.filter((m) => m.version > fromVersion);
 
   if (pending.length === 0) {
@@ -96,7 +96,7 @@ export function runMigrations(db: Database.Database, fromVersion: number): void
 /**
  * Check if the database needs migration
  */
-export function needsMigration(db: Database.Database): boolean {
+export function needsMigration(db: SqliteDatabase): boolean {
   const current = getCurrentVersion(db);
   return current < CURRENT_SCHEMA_VERSION;
 }
@@ -104,7 +104,7 @@ export function needsMigration(db: Database.Database): boolean {
 /**
  * Get list of pending migrations
  */
-export function getPendingMigrations(db: Database.Database): Migration[] {
+export function getPendingMigrations(db: SqliteDatabase): Migration[] {
   const current = getCurrentVersion(db);
   return migrations
     .filter((m) => m.version > current)
@@ -115,7 +115,7 @@ export function getPendingMigrations(db: Database.Database): Migration[] {
  * Get migration history from database
  */
 export function getMigrationHistory(
-  db: Database.Database
+  db: SqliteDatabase
 ): Array<{ version: number; appliedAt: number; description: string | null }> {
   const rows = db
     .prepare('SELECT version, applied_at, description FROM schema_versions ORDER BY version')

src/db/queries.ts

@@ -4,7 +4,7 @@
  * Prepared statements for CRUD operations on the knowledge graph.
  */
 
-import Database from 'better-sqlite3';
+import { SqliteDatabase, SqliteStatement } from './sqlite-adapter';
 import {
   Node,
   Edge,
@@ -143,7 +143,7 @@ function rowToFileRecord(row: FileRow): FileRecord {
  * Query builder for the knowledge graph database
  */
 export class QueryBuilder {
-  private db: Database.Database;
+  private db: SqliteDatabase;
 
   // Node cache for frequently accessed nodes (LRU-style, max 1000 entries)
   private nodeCache: Map<string, Node> = new Map();
@@ -151,30 +151,30 @@ export class QueryBuilder {
 
   // Prepared statements (lazily initialized)
   private stmts: {
-    insertNode?: Database.Statement;
-    updateNode?: Database.Statement;
-    deleteNode?: Database.Statement;
-    deleteNodesByFile?: Database.Statement;
-    getNodeById?: Database.Statement;
-    getNodesByFile?: Database.Statement;
-    getNodesByKind?: Database.Statement;
-    insertEdge?: Database.Statement;
-    upsertFile?: Database.Statement;
-    deleteEdgesBySource?: Database.Statement;
-    deleteEdgesByTarget?: Database.Statement;
-    getEdgesBySource?: Database.Statement;
-    getEdgesByTarget?: Database.Statement;
-    insertFile?: Database.Statement;
-    updateFile?: Database.Statement;
-    deleteFile?: Database.Statement;
-    getFileByPath?: Database.Statement;
-    getAllFiles?: Database.Statement;
-    insertUnresolved?: Database.Statement;
-    deleteUnresolvedByNode?: Database.Statement;
-    getUnresolvedByName?: Database.Statement;
+    insertNode?: SqliteStatement;
+    updateNode?: SqliteStatement;
+    deleteNode?: SqliteStatement;
+    deleteNodesByFile?: SqliteStatement;
+    getNodeById?: SqliteStatement;
+    getNodesByFile?: SqliteStatement;
+    getNodesByKind?: SqliteStatement;
+    insertEdge?: SqliteStatement;
+    upsertFile?: SqliteStatement;
+    deleteEdgesBySource?: SqliteStatement;
+    deleteEdgesByTarget?: SqliteStatement;
+    getEdgesBySource?: SqliteStatement;
+    getEdgesByTarget?: SqliteStatement;
+    insertFile?: SqliteStatement;
+    updateFile?: SqliteStatement;
+    deleteFile?: SqliteStatement;
+    getFileByPath?: SqliteStatement;
+    getAllFiles?: SqliteStatement;
+    insertUnresolved?: SqliteStatement;
+    deleteUnresolvedByNode?: SqliteStatement;
+    getUnresolvedByName?: SqliteStatement;
   } = {};
 
-  constructor(db: Database.Database) {
+  constructor(db: SqliteDatabase) {
     this.db = db;
   }
 

src/db/sqlite-adapter.ts

@@ -0,0 +1,227 @@
+/**
+ * SQLite Adapter
+ *
+ * Provides a unified interface over better-sqlite3 (native) and
+ * node-sqlite3-wasm (WASM fallback) for universal cross-platform support.
+ */
+
+export interface SqliteStatement {
+  run(...params: any[]): { changes: number; lastInsertRowid: number | bigint };
+  get(...params: any[]): any;
+  all(...params: any[]): any[];
+}
+
+export interface SqliteDatabase {
+  prepare(sql: string): SqliteStatement;
+  exec(sql: string): void;
+  pragma(str: string): any;
+  transaction<T>(fn: (...args: any[]) => T): (...args: any[]) => T;
+  close(): void;
+  readonly open: boolean;
+}
+
+export type SqliteBackend = 'native' | 'wasm';
+
+let activeBackend: SqliteBackend | null = null;
+
+/**
+ * Get the currently active SQLite backend.
+ */
+export function getActiveBackend(): SqliteBackend | null {
+  return activeBackend;
+}
+
+/**
+ * Translate @named parameters (better-sqlite3 style) to positional ? params
+ * for node-sqlite3-wasm, which only supports positional binding.
+ *
+ * Returns the rewritten SQL and an ordered list of parameter names.
+ * If no named params are found, returns null for paramOrder (positional mode).
+ */
+function translateNamedParams(sql: string): { sql: string; paramOrder: string[] | null } {
+  const paramOrder: string[] = [];
+  const rewritten = sql.replace(/@(\w+)/g, (_match, name: string) => {
+    paramOrder.push(name);
+    return '?';
+  });
+  if (paramOrder.length === 0) {
+    return { sql, paramOrder: null };
+  }
+  return { sql: rewritten, paramOrder };
+}
+
+/**
+ * Convert better-sqlite3-style params to a positional array for node-sqlite3-wasm.
+ *
+ * Handles three calling conventions:
+ * - Named object: run({ id: '1', name: 'a' }) → positional array via paramOrder
+ * - Positional args: run('a', 'b') → ['a', 'b']
+ * - No args: run() → undefined
+ */
+function resolveParams(params: any[], paramOrder: string[] | null): any {
+  if (params.length === 0) return undefined;
+
+  // If paramOrder exists and first arg is a plain object, do named→positional translation
+  if (paramOrder && params.length === 1 && params[0] !== null && typeof params[0] === 'object' && !Array.isArray(params[0]) && !(params[0] instanceof Buffer) && !(params[0] instanceof Uint8Array)) {
+    const obj = params[0];
+    return paramOrder.map(name => obj[name]);
+  }
+
+  // Positional: single value or already an array
+  if (params.length === 1) return params[0];
+  return params;
+}
+
+/**
+ * Wraps node-sqlite3-wasm to match the better-sqlite3 interface.
+ *
+ * Key differences handled:
+ * - better-sqlite3 uses @named params; node-sqlite3-wasm uses positional ? only
+ * - better-sqlite3 uses variadic args: stmt.run(a, b, c)
+ * - node-sqlite3-wasm uses a single array/object: stmt.run([a, b, c])
+ * - node-sqlite3-wasm has `isOpen` instead of `open`
+ * - node-sqlite3-wasm doesn't have a `pragma()` method
+ * - node-sqlite3-wasm doesn't have a `transaction()` method
+ */
+class WasmDatabaseAdapter implements SqliteDatabase {
+  private _db: any;
+  // Track raw WASM statements so we can finalize them on close.
+  // node-sqlite3-wasm won't release its file lock if statements are left open.
+  private _openStmts = new Set<any>();
+
+  constructor(dbPath: string) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { Database } = require('node-sqlite3-wasm');
+    this._db = new Database(dbPath);
+  }
+
+  get open(): boolean {
+    return this._db.isOpen;
+  }
+
+  prepare(sql: string): SqliteStatement {
+    const { sql: rewrittenSql, paramOrder } = translateNamedParams(sql);
+    const stmt = this._db.prepare(rewrittenSql);
+    this._openStmts.add(stmt);
+    return {
+      run(...params: any[]) {
+        const resolved = resolveParams(params, paramOrder);
+        const result = resolved !== undefined ? stmt.run(resolved) : stmt.run();
+        return {
+          changes: result?.changes ?? 0,
+          lastInsertRowid: result?.lastInsertRowid ?? 0,
+        };
+      },
+      get(...params: any[]) {
+        const resolved = resolveParams(params, paramOrder);
+        return resolved !== undefined ? stmt.get(resolved) : stmt.get();
+      },
+      all(...params: any[]) {
+        const resolved = resolveParams(params, paramOrder);
+        return resolved !== undefined ? stmt.all(resolved) : stmt.all();
+      },
+    };
+  }
+
+  exec(sql: string): void {
+    this._db.exec(sql);
+  }
+
+  pragma(str: string): any {
+    const trimmed = str.trim();
+
+    // Write pragma: "key = value"
+    if (trimmed.includes('=')) {
+      const eqIdx = trimmed.indexOf('=');
+      const key = trimmed.substring(0, eqIdx).trim();
+      const value = trimmed.substring(eqIdx + 1).trim();
+
+      // WAL is not supported in WASM SQLite — use DELETE journal mode
+      if (key === 'journal_mode' && value.toUpperCase() === 'WAL') {
+        this._db.exec('PRAGMA journal_mode = DELETE');
+        return;
+      }
+
+      // mmap is not available in WASM — silently skip
+      if (key === 'mmap_size') {
+        return;
+      }
+
+      // synchronous = NORMAL is unsafe without WAL — use FULL
+      if (key === 'synchronous' && value.toUpperCase() === 'NORMAL') {
+        this._db.exec('PRAGMA synchronous = FULL');
+        return;
+      }
+
+      this._db.exec(`PRAGMA ${key} = ${value}`);
+      return;
+    }
+
+    // Read pragma: "key" — return the value
+    const stmt = this._db.prepare(`PRAGMA ${trimmed}`);
+    const result = stmt.get();
+    stmt.finalize();
+    return result;
+  }
+
+  transaction<T>(fn: (...args: any[]) => T): (...args: any[]) => T {
+    return (...args: any[]) => {
+      this._db.exec('BEGIN');
+      try {
+        const result = fn(...args);
+        this._db.exec('COMMIT');
+        return result;
+      } catch (error) {
+        this._db.exec('ROLLBACK');
+        throw error;
+      }
+    };
+  }
+
+  close(): void {
+    // Finalize all tracked statements before closing.
+    // node-sqlite3-wasm won't release its directory-based file lock
+    // if any prepared statements remain open.
+    for (const stmt of this._openStmts) {
+      try { stmt.finalize(); } catch { /* already finalized */ }
+    }
+    this._openStmts.clear();
+    this._db.close();
+  }
+}
+
+/**
+ * Create a database connection. Tries native better-sqlite3 first,
+ * falls back to node-sqlite3-wasm.
+ */
+export function createDatabase(dbPath: string): SqliteDatabase {
+  let nativeError: string | undefined;
+  let wasmError: string | undefined;
+
+  // Try native better-sqlite3 first
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const Database = require('better-sqlite3');
+    const db = new Database(dbPath);
+    activeBackend = 'native';
+    return db as SqliteDatabase;
+  } catch (error) {
+    nativeError = error instanceof Error ? error.message : String(error);
+  }
+
+  // Fall back to WASM
+  try {
+    const db = new WasmDatabaseAdapter(dbPath);
+    activeBackend = 'wasm';
+    console.warn('[CodeGraph] Using WASM SQLite backend (native better-sqlite3 unavailable)');
+    return db;
+  } catch (error) {
+    wasmError = error instanceof Error ? error.message : String(error);
+  }
+
+  throw new Error(
+    `Failed to load any SQLite backend.\n` +
+    `  Native (better-sqlite3): ${nativeError}\n` +
+    `  WASM (node-sqlite3-wasm): ${wasmError}`
+  );
+}