gitnexus 1.6.4-rc.16 → 1.6.4-rc.18

package/README.md

@@ -296,6 +296,25 @@ If `npm install -g gitnexus` fails on native modules:
 npm install -g gitnexus
 ```
 
+### Analyze warns about unavailable FTS or VECTOR extensions
+
+GitNexus uses optional DuckDB extensions for BM25 and vector search. The `gitnexus serve` and MCP read paths only ever try to `LOAD` the extensions — they never block on a network install. The `analyze` command, by default, attempts one bounded out-of-process `INSTALL` if `LOAD` fails and proceeds even when that install times out, so the index is always written to disk; BM25/vector search degrade gracefully until the extensions become available.
+
+Configure the behavior with two environment variables:
+
+| Variable | Values | Default | Effect |
+|----------|--------|---------|--------|
+| `GITNEXUS_LBUG_EXTENSION_INSTALL` | `auto`, `load-only`, `never` | `auto` | `auto` runs one bounded INSTALL if LOAD fails. `load-only` only uses already-installed extensions (recommended for offline / firewalled environments). `never` skips optional extensions entirely. |
+| `GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer | `15000` | Wall-clock budget for the out-of-process `INSTALL` child before it is killed. |
+
+```bash
+# Offline/airgapped: never reach the network for extensions
+GITNEXUS_LBUG_EXTENSION_INSTALL=load-only npx gitnexus analyze
+
+# Slow network: give extension downloads more time
+GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS=30000 npx gitnexus analyze
+```
+
 ### Analysis runs out of memory
 
 For very large repositories:

package/dist/core/embeddings/embedding-pipeline.js

@@ -132,8 +132,11 @@ export const batchInsertEmbeddings = async (executeWithReusedStatement, updates)
 
  */
 const createVectorIndex = async (executeQuery) => {
-    // Delegate to the adapter which tracks loaded state and handles DB reconnect resets
-    await loadVectorExtension();
+    // Delegate to the adapter which tracks loaded state and handles DB reconnect resets.
+    // If the optional VECTOR extension cannot be loaded, semantic search degrades gracefully.
+    if (!(await loadVectorExtension())) {
+        return;
+    }
     try {
         await executeQuery(CREATE_VECTOR_INDEX_QUERY);
     }

package/dist/core/lbug/extension-loader.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Lifecycle policy for an optional DuckDB extension.
+ *
+ * - `auto`     — try `LOAD`, fall back to one bounded out-of-process `INSTALL`
+ *                attempt per process if `LOAD` fails. Default for analyze.
+ * - `load-only`— try `LOAD` only; never spawn an installer. Used by serve/MCP
+ *                read paths so user queries never block on a network install.
+ * - `never`    — skip the extension entirely. Operators can use this to
+ *                forcibly disable optional search features.
+ */
+export type ExtensionInstallPolicy = 'auto' | 'load-only' | 'never';
+export interface ExtensionInstallResult {
+    success: boolean;
+    timedOut: boolean;
+    message: string;
+}
+/** Snapshot of one optional extension's resolved capability state. */
+export interface ExtensionCapability {
+    name: string;
+    loaded: boolean;
+    /** Human-readable reason when `loaded` is false. */
+    reason?: string;
+}
+/** Per-call overrides applied on top of `ExtensionManager` defaults. */
+export interface ExtensionEnsureOptions {
+    policy?: ExtensionInstallPolicy;
+    installTimeoutMs?: number;
+}
+export interface ExtensionManagerOptions {
+    policy?: ExtensionInstallPolicy;
+    installTimeoutMs?: number;
+    installExtension?: (extensionName: string, timeoutMs: number) => Promise<ExtensionInstallResult>;
+    warn?: (message: string) => void;
+}
+export declare const getExtensionInstallTimeoutMs: () => number;
+export declare const getExtensionInstallChildProcessArgs: (extensionName: string) => string[];
+/**
+ * Run `INSTALL <extension>` in a short-lived child Node process so the parent
+ * event loop is never blocked by DuckDB's synchronous network call.
+ *
+ * The child opens its own scratch LadybugDB, executes the install, and exits.
+ * If the child exceeds `timeoutMs` the parent kills it with SIGKILL and
+ * resolves with `timedOut: true`.
+ */
+export declare const installDuckDbExtensionOutOfProcess: (extensionName: string, timeoutMs?: number) => Promise<ExtensionInstallResult>;
+/**
+ * Centralized lifecycle manager for optional LadybugDB extensions.
+ *
+ * Always tries `LOAD EXTENSION <name>` first — it is per-connection,
+ * idempotent, and never touches the network. If `LOAD` fails and the active
+ * policy permits, the manager runs a single bounded out-of-process `INSTALL`
+ * attempt per process and retries `LOAD`. Capability outcomes are cached so
+ * unavailable extensions degrade search features without ever blocking
+ * subsequent analyze or query calls.
+ *
+ * Policy precedence (most specific wins):
+ *   per-call `opts.policy` → constructor `options.policy` → env → `auto`
+ */
+export declare class ExtensionManager {
+    private readonly options;
+    private readonly capabilities;
+    private readonly installAttempted;
+    private readonly warnedKeys;
+    constructor(options?: ExtensionManagerOptions);
+    /** Reset cached capability and install state. Test-only. */
+    reset(): void;
+    /** Snapshot of currently-known optional extension capabilities. */
+    getCapabilities(): ExtensionCapability[];
+    /**
+     * Ensure an optional extension is loaded on the supplied connection.
+     *
+     * Returns `true` when the extension is usable on `query`, `false` when it
+     * is unavailable. Never throws on install failure — analyze and query
+     * paths are expected to degrade gracefully.
+     */
+    ensure(query: (sql: string) => Promise<unknown>, name: string, label: string, opts?: ExtensionEnsureOptions): Promise<boolean>;
+    private tryLoad;
+    private markLoaded;
+    private markUnavailable;
+}
+/** Process-wide singleton shared by core and pool adapters. */
+export declare const extensionManager: ExtensionManager;
+/** Snapshot of which optional DuckDB extensions are loaded in this process. */
+export declare const getExtensionCapabilities: () => ExtensionCapability[];
+/** Test-only: clear the singleton's cached capability and install state. */
+export declare const resetExtensionState: () => void;

package/dist/core/lbug/extension-loader.js

@@ -0,0 +1,184 @@
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'node:url';
+const DEFAULT_EXTENSION_INSTALL_TIMEOUT_MS = 15_000;
+const EXTENSION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
+const alreadyAvailable = (message) => message.includes('already loaded') ||
+    message.includes('already installed') ||
+    message.includes('already exists');
+const resolvePolicyFromEnv = () => {
+    const raw = process.env.GITNEXUS_LBUG_EXTENSION_INSTALL;
+    if (raw === 'load-only' || raw === 'never' || raw === 'auto')
+        return raw;
+    return 'auto';
+};
+export const getExtensionInstallTimeoutMs = () => {
+    const raw = process.env.GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS;
+    const parsed = raw ? Number(raw) : NaN;
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_EXTENSION_INSTALL_TIMEOUT_MS;
+};
+export const getExtensionInstallChildProcessArgs = (extensionName) => {
+    const childScript = new URL('../../../scripts/install-duckdb-extension.mjs', import.meta.url);
+    return [fileURLToPath(childScript), extensionName];
+};
+/**
+ * Run `INSTALL <extension>` in a short-lived child Node process so the parent
+ * event loop is never blocked by DuckDB's synchronous network call.
+ *
+ * The child opens its own scratch LadybugDB, executes the install, and exits.
+ * If the child exceeds `timeoutMs` the parent kills it with SIGKILL and
+ * resolves with `timedOut: true`.
+ */
+export const installDuckDbExtensionOutOfProcess = async (extensionName, timeoutMs = getExtensionInstallTimeoutMs()) => {
+    if (!EXTENSION_NAME_PATTERN.test(extensionName)) {
+        throw new Error(`Invalid DuckDB extension name: ${extensionName}`);
+    }
+    return await new Promise((resolve) => {
+        const child = spawn(process.execPath, getExtensionInstallChildProcessArgs(extensionName), {
+            env: {
+                ...process.env,
+                GITNEXUS_LBUG_EXTENSION_NAME: extensionName,
+            },
+            stdio: ['ignore', 'ignore', 'pipe'],
+            windowsHide: true,
+        });
+        let stderr = '';
+        child.stderr?.setEncoding('utf8');
+        child.stderr?.on('data', (chunk) => {
+            stderr = (stderr + chunk).slice(-4000);
+        });
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill('SIGKILL');
+            resolve({
+                success: false,
+                timedOut: true,
+                message: `INSTALL ${extensionName} timed out after ${timeoutMs}ms`,
+            });
+        }, timeoutMs);
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ success: false, timedOut: false, message: err.message });
+        });
+        child.on('exit', (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                success: code === 0,
+                timedOut: false,
+                message: code === 0
+                    ? `INSTALL ${extensionName} completed`
+                    : `INSTALL ${extensionName} failed with ${signal ?? `exit code ${code}`}${stderr ? `: ${stderr.trim()}` : ''}`,
+            });
+        });
+    });
+};
+/**
+ * Centralized lifecycle manager for optional LadybugDB extensions.
+ *
+ * Always tries `LOAD EXTENSION <name>` first — it is per-connection,
+ * idempotent, and never touches the network. If `LOAD` fails and the active
+ * policy permits, the manager runs a single bounded out-of-process `INSTALL`
+ * attempt per process and retries `LOAD`. Capability outcomes are cached so
+ * unavailable extensions degrade search features without ever blocking
+ * subsequent analyze or query calls.
+ *
+ * Policy precedence (most specific wins):
+ *   per-call `opts.policy` → constructor `options.policy` → env → `auto`
+ */
+export class ExtensionManager {
+    options;
+    capabilities = new Map();
+    installAttempted = new Map();
+    warnedKeys = new Set();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** Reset cached capability and install state. Test-only. */
+    reset() {
+        this.capabilities.clear();
+        this.installAttempted.clear();
+        this.warnedKeys.clear();
+    }
+    /** Snapshot of currently-known optional extension capabilities. */
+    getCapabilities() {
+        return Array.from(this.capabilities.values());
+    }
+    /**
+     * Ensure an optional extension is loaded on the supplied connection.
+     *
+     * Returns `true` when the extension is usable on `query`, `false` when it
+     * is unavailable. Never throws on install failure — analyze and query
+     * paths are expected to degrade gracefully.
+     */
+    async ensure(query, name, label, opts = {}) {
+        if (!EXTENSION_NAME_PATTERN.test(name)) {
+            throw new Error(`Invalid DuckDB extension name: ${name}`);
+        }
+        const policy = opts.policy ?? this.options.policy ?? resolvePolicyFromEnv();
+        const timeoutMs = opts.installTimeoutMs ?? this.options.installTimeoutMs ?? getExtensionInstallTimeoutMs();
+        const warn = this.options.warn ?? console.warn;
+        if (policy === 'never') {
+            this.markUnavailable(name, label, 'extension install policy is "never"', warn);
+            return false;
+        }
+        if (await this.tryLoad(query, name)) {
+            this.markLoaded(name);
+            return true;
+        }
+        if (policy === 'load-only') {
+            this.markUnavailable(name, label, 'load-only policy: extension not pre-installed', warn);
+            return false;
+        }
+        let install = this.installAttempted.get(name);
+        if (!install) {
+            const installFn = this.options.installExtension ?? installDuckDbExtensionOutOfProcess;
+            install = await installFn(name, timeoutMs);
+            this.installAttempted.set(name, install);
+        }
+        if (!install.success) {
+            this.markUnavailable(name, label, install.message, warn);
+            return false;
+        }
+        if (await this.tryLoad(query, name)) {
+            this.markLoaded(name);
+            return true;
+        }
+        this.markUnavailable(name, label, `LOAD ${name} failed after successful INSTALL`, warn);
+        return false;
+    }
+    async tryLoad(query, name) {
+        try {
+            await query(`LOAD EXTENSION ${name}`);
+            return true;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return alreadyAvailable(msg);
+        }
+    }
+    markLoaded(name) {
+        this.capabilities.set(name, { name, loaded: true });
+    }
+    markUnavailable(name, label, reason, warn) {
+        this.capabilities.set(name, { name, loaded: false, reason });
+        const key = `${name}:${reason}`;
+        if (this.warnedKeys.has(key))
+            return;
+        this.warnedKeys.add(key);
+        warn(`GitNexus: ${label} extension unavailable; continuing without ${label} features. ${reason}`);
+    }
+}
+/** Process-wide singleton shared by core and pool adapters. */
+export const extensionManager = new ExtensionManager();
+/** Snapshot of which optional DuckDB extensions are loaded in this process. */
+export const getExtensionCapabilities = () => extensionManager.getCapabilities();
+/** Test-only: clear the singleton's cached capability and install state. */
+export const resetExtensionState = () => extensionManager.reset();

package/dist/core/lbug/lbug-adapter.d.ts

@@ -1,6 +1,7 @@
 import lbug from '@ladybugdb/core';
 import { KnowledgeGraph } from '../graph/types.js';
 import type { CachedEmbedding } from '../embeddings/types.js';
+import { type ExtensionEnsureOptions } from './extension-loader.js';
 /** Factory for creating WriteStreams — injectable for testing. */
 export type WriteStreamFactory = (filePath: string) => import('fs').WriteStream;
 /** Result of splitting the relationship CSV into per-label-pair files. */
@@ -122,23 +123,24 @@ export declare const deleteNodesForFile: (filePath: string, dbPath?: string) =>
 }>;
 export declare const getEmbeddingTableName: () => string;
 /**
- * Load the FTS extension (required before using FTS functions).
+ * Load the FTS extension on the supplied connection (or the singleton
+ * writable connection when none is given).
  *
- * Safe to call multiple times — when invoked without arguments, tracks loaded
- * state via module-level `ftsLoaded`. When invoked with an explicit
- * connection, loads on that connection and returns whether the load
- * succeeded — letting callers (e.g. the pool adapter) track their own state.
- *
- * Tries `LOAD EXTENSION fts` first so previously-cached installs skip the
- * network entirely; falls back to `INSTALL` + `LOAD` only when the extension
- * hasn't been cached yet.
+ * Delegates to the shared `ExtensionManager` so install policy (auto /
+ * load-only / never), out-of-process bounded INSTALL, and capability
+ * caching are owned in one place. The module-level `ftsLoaded` flag is
+ * kept purely as a per-call short-circuit on the singleton writable
+ * connection so repeated callers (e.g. createFTSIndex) avoid an extra
+ * `LOAD` round-trip per invocation. Pool adapter callers pass
+ * `{ policy: 'load-only' }` so query paths never block on a network install.
  */
-export declare const loadFTSExtension: (targetConn?: lbug.Connection) => Promise<boolean>;
+export declare const loadFTSExtension: (targetConn?: lbug.Connection, opts?: ExtensionEnsureOptions) => Promise<boolean>;
 /**
- * Load the VECTOR extension (required before using QUERY_VECTOR_INDEX).
- * Safe to call multiple times -- tracks loaded state via module-level vectorExtensionLoaded.
+ * Load the VECTOR extension on the supplied connection (or the singleton
+ * writable connection when none is given). See `loadFTSExtension` for the
+ * policy / capability contract — the same `ExtensionManager` owns both.
  */
-export declare const loadVectorExtension: () => Promise<void>;
+export declare const loadVectorExtension: (targetConn?: lbug.Connection, opts?: ExtensionEnsureOptions) => Promise<boolean>;
 /**
  * Create a full-text search index on a table
  * @param tableName - The node table name (e.g., 'File', 'CodeSymbol')

package/dist/core/lbug/lbug-adapter.js

@@ -7,6 +7,7 @@ import path from 'path';
 import lbug from '@ladybugdb/core';
 import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, STALE_HASH_SENTINEL, } from './schema.js';
 import { streamAllCSVsToDisk } from './csv-generator.js';
+import { extensionManager } from './extension-loader.js';
 /**
  * Split a relationship CSV into per-label-pair files on disk.
  *
@@ -287,7 +288,8 @@ const doInitLbug = async (dbPath) => {
             }
         }
     }
-    // Load query extensions once per core adapter session.
+    // Load query extensions once per core adapter session. Missing optional
+    // extensions degrade search features but must not block analyze completion.
     await loadFTSExtension();
     await loadVectorExtension();
     currentDbPath = dbPath;
@@ -1024,18 +1026,18 @@ export const getEmbeddingTableName = () => EMBEDDING_TABLE_NAME;
 // Full-Text Search (FTS) Functions
 // ============================================================================
 /**
- * Load the FTS extension (required before using FTS functions).
+ * Load the FTS extension on the supplied connection (or the singleton
+ * writable connection when none is given).
  *
- * Safe to call multiple times — when invoked without arguments, tracks loaded
- * state via module-level `ftsLoaded`. When invoked with an explicit
- * connection, loads on that connection and returns whether the load
- * succeeded — letting callers (e.g. the pool adapter) track their own state.
- *
- * Tries `LOAD EXTENSION fts` first so previously-cached installs skip the
- * network entirely; falls back to `INSTALL` + `LOAD` only when the extension
- * hasn't been cached yet.
+ * Delegates to the shared `ExtensionManager` so install policy (auto /
+ * load-only / never), out-of-process bounded INSTALL, and capability
+ * caching are owned in one place. The module-level `ftsLoaded` flag is
+ * kept purely as a per-call short-circuit on the singleton writable
+ * connection so repeated callers (e.g. createFTSIndex) avoid an extra
+ * `LOAD` round-trip per invocation. Pool adapter callers pass
+ * `{ policy: 'load-only' }` so query paths never block on a network install.
  */
-export const loadFTSExtension = async (targetConn) => {
+export const loadFTSExtension = async (targetConn, opts = {}) => {
     const useModuleState = targetConn === undefined;
     if (useModuleState && ftsLoaded)
         return true;
@@ -1043,61 +1045,28 @@ export const loadFTSExtension = async (targetConn) => {
     if (!c) {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
     }
-    const markLoaded = () => {
-        if (useModuleState)
-            ftsLoaded = true;
-        return true;
-    };
-    try {
-        // Try loading locally first (no network required)
-        await c.query('LOAD EXTENSION fts');
-        return markLoaded();
-    }
-    catch {
-        // Fall back to install + load (requires network)
-        try {
-            await c.query('INSTALL fts');
-            await c.query('LOAD EXTENSION fts');
-            return markLoaded();
-        }
-        catch (err) {
-            const msg = err?.message || '';
-            if (msg.includes('already loaded') ||
-                msg.includes('already installed') ||
-                msg.includes('already exists')) {
-                return markLoaded();
-            }
-            console.error('GitNexus: FTS extension load failed:', msg);
-            return false;
-        }
-    }
+    const loaded = await extensionManager.ensure((sql) => c.query(sql), 'fts', 'FTS', opts);
+    if (loaded && useModuleState)
+        ftsLoaded = true;
+    return loaded;
 };
 /**
- * Load the VECTOR extension (required before using QUERY_VECTOR_INDEX).
- * Safe to call multiple times -- tracks loaded state via module-level vectorExtensionLoaded.
+ * Load the VECTOR extension on the supplied connection (or the singleton
+ * writable connection when none is given). See `loadFTSExtension` for the
+ * policy / capability contract — the same `ExtensionManager` owns both.
  */
-export const loadVectorExtension = async () => {
-    if (vectorExtensionLoaded)
-        return;
-    if (!conn) {
+export const loadVectorExtension = async (targetConn, opts = {}) => {
+    const useModuleState = targetConn === undefined;
+    if (useModuleState && vectorExtensionLoaded)
+        return true;
+    const c = targetConn ?? conn;
+    if (!c) {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
     }
-    try {
-        await conn.query('INSTALL VECTOR');
-        await conn.query('LOAD EXTENSION VECTOR');
+    const loaded = await extensionManager.ensure((sql) => c.query(sql), 'VECTOR', 'VECTOR', opts);
+    if (loaded && useModuleState)
         vectorExtensionLoaded = true;
-    }
-    catch (err) {
-        const msg = err?.message || '';
-        if (msg.includes('already loaded') ||
-            msg.includes('already installed') ||
-            msg.includes('already exists')) {
-            vectorExtensionLoaded = true;
-        }
-        else {
-            console.error('GitNexus: VECTOR extension load failed:', msg);
-        }
-    }
+    return loaded;
 };
 /**
  * Create a full-text search index on a table
@@ -1110,7 +1079,9 @@ export const createFTSIndex = async (tableName, indexName, properties, stemmer =
     if (!conn) {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
     }
-    await loadFTSExtension();
+    if (!(await loadFTSExtension())) {
+        return;
+    }
     const propList = properties.map((p) => `'${p}'`).join(', ');
     const query = `CALL CREATE_FTS_INDEX('${tableName}', '${indexName}', [${propList}], stemmer := '${stemmer}')`;
     try {

package/dist/core/lbug/pool-adapter.js

@@ -16,7 +16,7 @@
  */
 import fs from 'fs/promises';
 import lbug from '@ladybugdb/core';
-import { loadFTSExtension } from './lbug-adapter.js';
+import { loadFTSExtension, loadVectorExtension } from './lbug-adapter.js';
 const pool = new Map();
 const poolCloseListeners = new Set();
 /**
@@ -284,19 +284,14 @@ async function doInitLbug(repoId, dbPath) {
     // Load FTS extension once per shared Database.
     // Done BEFORE pool registration so no concurrent checkout can grab
     // the connection while the async FTS load is in progress.
+    // policy: 'load-only' — the read pool must never trigger a network
+    // install; analyze owns extension installation. If LOAD fails, search
+    // features degrade gracefully and the user-facing query path proceeds.
     if (!shared.ftsLoaded) {
-        shared.ftsLoaded = await loadFTSExtension(available[0]);
+        shared.ftsLoaded = await loadFTSExtension(available[0], { policy: 'load-only' });
     }
-    // Load VECTOR extension once per shared Database for semantic search support.
     if (!shared.vectorLoaded) {
-        try {
-            await available[0].query('INSTALL VECTOR');
-            await available[0].query('LOAD EXTENSION VECTOR');
-            shared.vectorLoaded = true;
-        }
-        catch {
-            // VECTOR extension may not be available
-        }
+        shared.vectorLoaded = await loadVectorExtension(available[0], { policy: 'load-only' });
     }
     // Register pool entry only after all connections are pre-warmed and FTS is
     // loaded.  Concurrent executeQuery calls see either "not initialized"
@@ -349,20 +344,14 @@ export async function initLbugWithDb(repoId, existingDb, dbPath) {
     finally {
         preWarmActive = false;
     }
-    // Load FTS extension if not already loaded on this Database
+    // Load FTS extension if not already loaded on this Database.
+    // policy: 'load-only' — same contract as initLbug above; the read pool
+    // must not block on a network install during query execution.
     if (!shared.ftsLoaded) {
-        shared.ftsLoaded = await loadFTSExtension(available[0]);
+        shared.ftsLoaded = await loadFTSExtension(available[0], { policy: 'load-only' });
     }
-    // Load VECTOR extension for semantic search support
     if (!shared.vectorLoaded) {
-        try {
-            await available[0].query('INSTALL VECTOR');
-            await available[0].query('LOAD EXTENSION VECTOR');
-            shared.vectorLoaded = true;
-        }
-        catch {
-            // VECTOR extension may not be available
-        }
+        shared.vectorLoaded = await loadVectorExtension(available[0], { policy: 'load-only' });
     }
     pool.set(repoId, {
         db: existingDb,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.4-rc.16",
+  "version": "1.6.4-rc.18",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -47,7 +47,7 @@
     "test:integration": "vitest run test/integration",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "postinstall": "node scripts/patch-tree-sitter-swift.cjs && node scripts/build-tree-sitter-proto.cjs",
+    "postinstall": "node scripts/patch-tree-sitter-swift.cjs && node scripts/build-tree-sitter-dart.cjs && node scripts/build-tree-sitter-proto.cjs",
     "prepare": "node scripts/build.js",
     "prepack": "node scripts/build.js"
   },
@@ -88,7 +88,7 @@
   "optionalDependencies": {
     "node-addon-api": "^8.0.0",
     "node-gyp-build": "^4.8.0",
-    "tree-sitter-dart": "git+https://github.com/UserNobody14/tree-sitter-dart.git#80e23c07b64494f7e21090bb3450223ef0b192f4",
+    "tree-sitter-dart": "file:./vendor/tree-sitter-dart",
     "tree-sitter-kotlin": "^0.3.8",
     "tree-sitter-proto": "file:./vendor/tree-sitter-proto",
     "tree-sitter-swift": "^0.6.0"

package/scripts/build-tree-sitter-dart.cjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const dartDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-dart');
+const bindingGyp = path.join(dartDir, 'binding.gyp');
+const bindingNode = path.join(dartDir, 'build', 'Release', 'tree_sitter_dart_binding.node');
+
+try {
+  if (!fs.existsSync(bindingGyp) || fs.existsSync(bindingNode)) {
+    process.exit(0);
+  }
+
+  try {
+    require.resolve('node-addon-api');
+    require.resolve('node-gyp-build');
+  } catch (resolveErr) {
+    console.warn(
+      '[tree-sitter-dart] Skipping build: hoisted build deps not resolvable (%s).',
+      resolveErr.message,
+    );
+    console.warn(
+      '[tree-sitter-dart] Dart parsing will be unavailable. Install without --no-optional and with scripts enabled to build.',
+    );
+    process.exit(0);
+  }
+
+  console.log('[tree-sitter-dart] Building native binding...');
+  execSync('npx node-gyp rebuild', {
+    cwd: dartDir,
+    stdio: 'pipe',
+    timeout: 180000,
+  });
+  console.log('[tree-sitter-dart] Native binding built successfully');
+} catch (err) {
+  console.warn('[tree-sitter-dart] Could not build native binding:', err.message);
+  console.warn(
+    '[tree-sitter-dart] Dart parsing will be unavailable. Non-Dart functionality is unaffected.',
+  );
+  process.exit(0);
+}

package/scripts/install-duckdb-extension.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const EXTENSION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
+
+async function installDuckDbExtension(extensionName) {
+  if (!extensionName || !EXTENSION_NAME_PATTERN.test(extensionName)) {
+    throw new Error(`Invalid DuckDB extension name: ${extensionName ?? '<missing>'}`);
+  }
+
+  const require = createRequire(import.meta.url);
+  const lbugModule = require('@ladybugdb/core');
+  const lbug = lbugModule.default ?? lbugModule;
+
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-ext-install-'));
+  const dbPath = path.join(tmpDir, 'install.lbug');
+  let db;
+  let conn;
+
+  try {
+    db = new lbug.Database(dbPath);
+    conn = new lbug.Connection(db);
+    await conn.query(`INSTALL ${extensionName}`);
+  } finally {
+    if (conn) await conn.close().catch(() => {});
+    if (db) await db.close().catch(() => {});
+    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+installDuckDbExtension(process.argv[2] ?? process.env.GITNEXUS_LBUG_EXTENSION_NAME).catch((err) => {
+  console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
+  process.exitCode = 1;
+});