gitnexus 1.6.4-rc.17 → 1.6.4-rc.19

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/group/config-parser.js

@@ -14,6 +14,8 @@ const DEFAULT_MATCHING = {
     bm25_threshold: 0.7,
     embedding_threshold: 0.65,
     max_candidates_per_step: 3,
+    exclude_links_paths: [],
+    exclude_links_param_only_paths: false,
 };
 export function parseGroupConfig(yamlContent) {
     const raw = yaml.load(yamlContent, { schema: yaml.JSON_SCHEMA });

package/dist/core/group/matching.d.ts

@@ -1,4 +1,4 @@
-import type { StoredContract, CrossLink } from './types.js';
+import type { StoredContract, CrossLink, MatchingConfig } from './types.js';
 export interface MatchResult {
     matched: CrossLink[];
     unmatched: StoredContract[];
@@ -8,6 +8,6 @@ export interface WildcardMatchResult {
     remaining: StoredContract[];
 }
 export declare function normalizeContractId(id: string): string;
-export declare function buildProviderIndex(contracts: StoredContract[]): Map<string, StoredContract[]>;
-export declare function runExactMatch(contracts: StoredContract[], providerIndex?: Map<string, StoredContract[]>): MatchResult;
+export declare function buildProviderIndex(contracts: StoredContract[], matchingConfig?: MatchingConfig): Map<string, StoredContract[]>;
+export declare function runExactMatch(contracts: StoredContract[], providerIndex?: Map<string, StoredContract[]>, matchingConfig?: MatchingConfig): MatchResult;
 export declare function runWildcardMatch(unmatched: StoredContract[], providerIndex: Map<string, StoredContract[]>): WildcardMatchResult;

package/dist/core/group/matching.js

@@ -1,6 +1,43 @@
 function isGrpcWildcard(cid) {
     return cid.startsWith('grpc::') && cid.endsWith('/*');
 }
+/**
+ * Detect HTTP contracts that are too generic or infrastructure-level to
+ * produce meaningful cross-repo links. These are still extracted (useful
+ * for documentation / route maps) but excluded from cross-link matching.
+ *
+ * Two categories:
+ * 1. Health-check / readiness endpoints — every service has one, matching
+ *    them produces N×M false links.
+ * 2. Param-only paths — routes like `/{param}` or `/{param}/{param}` that
+ *    collapse to a single catch-all after normalization. These match any
+ *    service with a similar shape, producing false positives.
+ *
+ * Both are configurable via matching.exclude_links_paths and
+ * matching.exclude_links_param_only_paths in group.yaml.
+ */
+function buildNoisyContractFilter(matchingConfig) {
+    const excludePaths = matchingConfig?.exclude_links_paths?.length
+        ? new Set(matchingConfig.exclude_links_paths.map((p) => p.replace(/\/+$/, '')))
+        : new Set();
+    const excludeParamOnly = matchingConfig?.exclude_links_param_only_paths === true;
+    return function isNoisyHttpContract(contractId) {
+        if (!contractId.startsWith('http::'))
+            return false;
+        const parts = contractId.split('::');
+        if (parts.length < 3)
+            return false;
+        const pathPart = parts.slice(2).join('::').replace(/\/+$/, '');
+        if (excludePaths.has(pathPart))
+            return true;
+        if (excludeParamOnly) {
+            const segments = pathPart.split('/').filter(Boolean);
+            if (segments.length > 0 && segments.every((s) => s === '{param}'))
+                return true;
+        }
+        return false;
+    };
+}
 export function normalizeContractId(id) {
     const colonIdx = id.indexOf('::');
     if (colonIdx === -1)
@@ -74,8 +111,9 @@ function findMatchingKeys(contractId, index) {
     }
     return [];
 }
-export function buildProviderIndex(contracts) {
-    const providers = contracts.filter((c) => c.role === 'provider');
+export function buildProviderIndex(contracts, matchingConfig) {
+    const isNoisy = buildNoisyContractFilter(matchingConfig);
+    const providers = contracts.filter((c) => c.role === 'provider' && !isNoisy(c.contractId));
     const index = new Map();
     for (const p of providers) {
         const key = normalizeContractId(p.contractId);
@@ -85,10 +123,10 @@ export function buildProviderIndex(contracts) {
     }
     return index;
 }
-export function runExactMatch(contracts, providerIndex) {
-    const index = providerIndex ?? buildProviderIndex(contracts);
-    // Skip gRPC wildcard consumers — they go to wildcard pass only
-    const consumers = contracts.filter((c) => c.role === 'consumer' && !isGrpcWildcard(c.contractId));
+export function runExactMatch(contracts, providerIndex, matchingConfig) {
+    const isNoisy = buildNoisyContractFilter(matchingConfig);
+    const index = providerIndex ?? buildProviderIndex(contracts, matchingConfig);
+    const consumers = contracts.filter((c) => c.role === 'consumer' && !isGrpcWildcard(c.contractId) && !isNoisy(c.contractId));
     const matched = [];
     const matchedConsumerIds = new Set();
     const matchedProviderIds = new Set();
@@ -129,6 +167,8 @@ export function runExactMatch(contracts, providerIndex) {
     const normalUnmatched = contracts.filter((c) => {
         if (isGrpcWildcard(c.contractId))
             return false; // excluded from exact, handled separately
+        if (isNoisy(c.contractId))
+            return false; // excluded from matching — don't surface as unmatched
         const id = `${c.repo}::${c.contractId}`;
         return c.role === 'provider' ? !matchedProviderIds.has(id) : !matchedConsumerIds.has(id);
     });

package/dist/core/group/storage.js

@@ -85,6 +85,8 @@ matching:
   bm25_threshold: 0.7
   embedding_threshold: 0.65
   max_candidates_per_step: 3
+  # exclude_links_paths: [/ping, /health, /healthcheck]
+  # exclude_links_param_only_paths: false
 `;
     await fsp.writeFile(path.join(groupDir, 'group.yaml'), template, 'utf-8');
     return groupDir;

package/dist/core/group/sync.js

@@ -168,7 +168,7 @@ export async function syncGroup(config, opts) {
             console.log(`  manifest: ${manifestCrossLinks.length} cross-links from ${config.links.length} declared links`);
         }
     }
-    const { matched, unmatched } = runExactMatch(autoContracts);
+    const { matched, unmatched } = runExactMatch(autoContracts, undefined, config.matching);
     // Dedupe cross-links. Manifest contracts participate in runExactMatch, so a
     // manifest-declared link can also emit a matchType:'exact' CrossLink with the
     // same endpoints. Prefer the manifest version — it reflects operator intent

package/dist/core/group/types.d.ts

@@ -29,6 +29,24 @@ export interface MatchingConfig {
     bm25_threshold: number;
     embedding_threshold: number;
     max_candidates_per_step: number;
+    /**
+     * HTTP paths to exclude from cross-link matching. Contracts at these paths
+     * are still extracted and visible in the registry, but they don't produce
+     * cross-repo links. Useful for health-check endpoints (`/ping`, `/health`)
+     * that every service exposes and would otherwise create N×M false links.
+     * Trailing slashes are normalized before comparison.
+     * @default []
+     */
+    exclude_links_paths?: string[];
+    /**
+     * When `true`, exclude HTTP routes where every path segment is `{param}`
+     * (e.g. `/{param}`, `/{param}/{param}`) from cross-link matching. Mixed
+     * routes like `/users/{param}` are not affected. These param-only routes
+     * collapse to a single catch-all after normalization and produce false
+     * positives across unrelated services.
+     * @default false
+     */
+    exclude_links_param_only_paths?: boolean;
 }
 export interface SymbolRef {
     filePath: string;

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.17",
+  "version": "1.6.4-rc.19",
   "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",

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;
+});