gitnexus 1.6.4-rc.80 → 1.6.4-rc.81

package/dist/cli/analyze.js

@@ -16,6 +16,8 @@ import { getStoragePaths, getGlobalRegistryPath, RegistryNameCollisionError, Ana
 import { getGitRoot, hasGitDir } from '../storage/git.js';
 import { runFullAnalysis } from '../core/run-analyze.js';
 import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-size.js';
+import { warnMissingOptionalGrammars } from './optional-grammars.js';
+import { glob } from 'glob';
 import fs from 'fs/promises';
 // Capture stderr.write at module load BEFORE anything (LadybugDB native
 // init, progress bar, console redirection) can monkey-patch it. The
@@ -173,6 +175,31 @@ export const analyzeCommand = async (inputPath, options) => {
     if (!repoHasGit) {
         console.log('  Warning: no .git directory found \u2014 commit-tracking and incremental updates disabled.\n');
     }
+    // If the target repo contains files an optional grammar would parse but
+    // that grammar's native binding is absent, warn before analysis so users
+    // learn why those files end up unparsed instead of silently getting a
+    // degraded index.
+    try {
+        const matches = await glob(['**/*.dart', '**/*.proto'], {
+            cwd: repoPath,
+            ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**'],
+            dot: false,
+            nodir: true,
+            absolute: false,
+        });
+        if (matches.length > 0) {
+            const present = new Set();
+            for (const m of matches) {
+                const ext = path.extname(m).toLowerCase();
+                if (ext)
+                    present.add(ext);
+            }
+            warnMissingOptionalGrammars({ context: 'analyze', relevantExtensions: present });
+        }
+    }
+    catch {
+        // Best-effort warning \u2014 never block analyze on the precheck.
+    }
     // KuzuDB migration cleanup is handled by runFullAnalysis internally.
     // Note: --skills is handled after runFullAnalysis using the returned pipelineResult.
     if (process.env.GITNEXUS_NO_GITIGNORE) {

package/dist/cli/mcp.d.ts

@@ -4,5 +4,26 @@
  * Starts the MCP server in standalone mode.
  * Loads all indexed repos from the global registry.
  * No longer depends on cwd — works from any directory.
+ *
+ * IMPORTANT: this module's static-import closure is intentionally tiny
+ * (one chain: `mcp/stdio-context.js` → `mcp/stdio-capture.js`, which is a
+ * leaf with zero non-`node:` imports). All heavy backend modules
+ * (`startMCPServer`, `LocalBackend`, `warnMissingOptionalGrammars`) load
+ * via `await import(...)` AFTER `installGlobalStdoutSentinel()` runs.
+ *
+ * This closes the ESM-evaluation-order window where native init banners
+ * from `@ladybugdb/core` (or any future heavy import) could reach raw
+ * stdout before the sentinel exists. Codex's adversarial review on
+ * PR #1383 found that even with the sentinel-install call as the first
+ * statement of `mcpCommand`, ESM evaluates static imports of THIS module
+ * before the function body runs — so any native side effects during
+ * those imports happen before the sentinel can intercept them.
+ *
+ * If you find yourself adding a static `import` to this file, ask
+ * whether the imported module (or anything it transitively imports)
+ * touches `process.stdout` or loads a native binding at module init. If
+ * either is true, switch it to a dynamic `await import(...)` inside
+ * `mcpCommand` after the sentinel install. The regression test at
+ * `gitnexus/test/integration/mcp/import-closure.test.ts` enforces this.
  */
 export declare const mcpCommand: () => Promise<void>;

package/dist/cli/mcp.js

@@ -4,21 +4,50 @@
  * Starts the MCP server in standalone mode.
  * Loads all indexed repos from the global registry.
  * No longer depends on cwd — works from any directory.
+ *
+ * IMPORTANT: this module's static-import closure is intentionally tiny
+ * (one chain: `mcp/stdio-context.js` → `mcp/stdio-capture.js`, which is a
+ * leaf with zero non-`node:` imports). All heavy backend modules
+ * (`startMCPServer`, `LocalBackend`, `warnMissingOptionalGrammars`) load
+ * via `await import(...)` AFTER `installGlobalStdoutSentinel()` runs.
+ *
+ * This closes the ESM-evaluation-order window where native init banners
+ * from `@ladybugdb/core` (or any future heavy import) could reach raw
+ * stdout before the sentinel exists. Codex's adversarial review on
+ * PR #1383 found that even with the sentinel-install call as the first
+ * statement of `mcpCommand`, ESM evaluates static imports of THIS module
+ * before the function body runs — so any native side effects during
+ * those imports happen before the sentinel can intercept them.
+ *
+ * If you find yourself adding a static `import` to this file, ask
+ * whether the imported module (or anything it transitively imports)
+ * touches `process.stdout` or loads a native binding at module init. If
+ * either is true, switch it to a dynamic `await import(...)` inside
+ * `mcpCommand` after the sentinel install. The regression test at
+ * `gitnexus/test/integration/mcp/import-closure.test.ts` enforces this.
  */
-import { startMCPServer } from '../mcp/server.js';
-import { LocalBackend } from '../mcp/local/local-backend.js';
+import { installGlobalStdoutSentinel } from '../mcp/stdio-context.js';
 export const mcpCommand = async () => {
-    // Prevent unhandled errors from crashing the MCP server process.
-    // LadybugDB lock conflicts and transient errors should degrade gracefully.
-    process.on('uncaughtException', (err) => {
-        console.error(`GitNexus MCP: uncaught exception — ${err.message}`);
-        // Process is in an undefined state after uncaughtException — exit after flushing
-        setTimeout(() => process.exit(1), 100);
-    });
-    process.on('unhandledRejection', (reason) => {
-        const msg = reason instanceof Error ? reason.message : String(reason);
-        console.error(`GitNexus MCP: unhandled rejection — ${msg}`);
-    });
+    // Install the global stdout sentinel as the very first thing — before
+    // ANY other module loads. The static-import closure above is leaf-only
+    // (stdio-context → stdio-capture, zero non-`node:` deps), so this is
+    // also the first chance any code in this process has to write to stdout.
+    installGlobalStdoutSentinel();
+    // uncaughtException/unhandledRejection handlers are owned by
+    // startMCPServer (gitnexus/src/mcp/server.ts) so the server's shutdown
+    // path runs cleanly with full stack traces. Registering duplicates here
+    // would only produce noisy double-logging on the same exception.
+    // Now safe to dynamically import the heavy backend modules. Anything
+    // they emit to stdout during evaluation will route through the sentinel.
+    const [{ startMCPServer }, { LocalBackend }] = await Promise.all([
+        import('../mcp/server.js'),
+        import('../mcp/local/local-backend.js'),
+    ]);
+    // Missing-optional-grammar warnings are intentionally NOT emitted here.
+    // `gitnexus analyze` already warns at index time, filtered by the repo's
+    // actual extensions, and a repo can only be served by MCP after analyze
+    // has run. Repeating an unconditional warning at every MCP startup is
+    // pure noise for users whose indexed repos don't use Dart/Proto.
     // Initialize multi-repo backend from registry.
     // The server starts even with 0 repos — tools call refreshRepos() lazily,
     // so repos indexed after the server starts are discovered automatically.

package/dist/cli/optional-grammars.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Optional grammar availability check.
+ *
+ * tree-sitter-dart and tree-sitter-proto are optionalDependencies that
+ * require a `node-gyp rebuild` at install time. The build can be skipped
+ * via GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or it can
+ * silently soft-fail when the C++ toolchain is missing.
+ *
+ * Either path produces the same observable: the .node binding is absent
+ * at runtime. This helper detects that condition and surfaces a single
+ * stderr line per missing grammar so users learn why .dart/.proto support
+ * is unavailable instead of silently getting a degraded index.
+ */
+export interface MissingGrammar {
+    name: string;
+    extensions: string[];
+}
+/**
+ * Returns the list of optional grammars whose native binding cannot be
+ * loaded. Actually `require()`s the package — `require.resolve` would
+ * locate the entry path even when the `.node` binding is absent (the
+ * `file:` package directory is installed regardless of postinstall
+ * outcome), giving false negatives for the exact users we want to warn:
+ * those who installed with `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` or whose
+ * native rebuild soft-failed for missing toolchain.
+ *
+ * Node's module cache memoizes `require()` for us — calling this multiple
+ * times is cheap. The catch distinguishes "missing" (MODULE_NOT_FOUND or
+ * the typical node-gyp-build "could not find any binding" pattern) from
+ * "broken" (SyntaxError, EACCES, native crash). Broken bindings surface a
+ * separate stderr line so users get an actionable message instead of a
+ * misleading "reinstall" hint.
+ */
+export declare function detectMissingOptionalGrammars(): MissingGrammar[];
+/**
+ * Log a one-line stderr warning for each missing grammar. Safe to call
+ * unconditionally — silent if all grammars are present.
+ *
+ * `relevantExtensions`, if provided, filters the warning to grammars whose
+ * extensions appear in the set (e.g. an analyze run can pass the set of
+ * extensions actually present in the target repo so users without any
+ * .dart/.proto files don't see noise).
+ */
+export declare function warnMissingOptionalGrammars(opts?: {
+    context?: string;
+    relevantExtensions?: ReadonlySet<string>;
+}): void;

package/dist/cli/optional-grammars.js

@@ -0,0 +1,78 @@
+/**
+ * Optional grammar availability check.
+ *
+ * tree-sitter-dart and tree-sitter-proto are optionalDependencies that
+ * require a `node-gyp rebuild` at install time. The build can be skipped
+ * via GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or it can
+ * silently soft-fail when the C++ toolchain is missing.
+ *
+ * Either path produces the same observable: the .node binding is absent
+ * at runtime. This helper detects that condition and surfaces a single
+ * stderr line per missing grammar so users learn why .dart/.proto support
+ * is unavailable instead of silently getting a degraded index.
+ */
+import { createRequire } from 'module';
+const _require = createRequire(import.meta.url);
+const OPTIONAL_GRAMMARS = [
+    { name: 'tree-sitter-dart', pkg: 'tree-sitter-dart', extensions: ['.dart'] },
+    { name: 'tree-sitter-proto', pkg: 'tree-sitter-proto', extensions: ['.proto'] },
+];
+/**
+ * Returns the list of optional grammars whose native binding cannot be
+ * loaded. Actually `require()`s the package — `require.resolve` would
+ * locate the entry path even when the `.node` binding is absent (the
+ * `file:` package directory is installed regardless of postinstall
+ * outcome), giving false negatives for the exact users we want to warn:
+ * those who installed with `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` or whose
+ * native rebuild soft-failed for missing toolchain.
+ *
+ * Node's module cache memoizes `require()` for us — calling this multiple
+ * times is cheap. The catch distinguishes "missing" (MODULE_NOT_FOUND or
+ * the typical node-gyp-build "could not find any binding" pattern) from
+ * "broken" (SyntaxError, EACCES, native crash). Broken bindings surface a
+ * separate stderr line so users get an actionable message instead of a
+ * misleading "reinstall" hint.
+ */
+export function detectMissingOptionalGrammars() {
+    const missing = [];
+    for (const g of OPTIONAL_GRAMMARS) {
+        try {
+            _require(g.pkg);
+        }
+        catch (err) {
+            const code = err?.code;
+            const msg = err instanceof Error ? err.message : String(err);
+            const looksMissing = code === 'MODULE_NOT_FOUND' ||
+                code === 'ERR_MODULE_NOT_FOUND' ||
+                /could not find|no native build|prebuilds/i.test(msg);
+            if (!looksMissing) {
+                // Present but broken — surface so the user doesn't get a misleading
+                // "reinstall" recovery message that wouldn't actually help.
+                console.error(`GitNexus: optional grammar "${g.name}" is installed but failed to load (${msg.slice(0, 200)}). ${g.extensions.join('/')} files will not be parsed.`);
+            }
+            missing.push({ name: g.name, extensions: g.extensions });
+        }
+    }
+    return missing;
+}
+/**
+ * Log a one-line stderr warning for each missing grammar. Safe to call
+ * unconditionally — silent if all grammars are present.
+ *
+ * `relevantExtensions`, if provided, filters the warning to grammars whose
+ * extensions appear in the set (e.g. an analyze run can pass the set of
+ * extensions actually present in the target repo so users without any
+ * .dart/.proto files don't see noise).
+ */
+export function warnMissingOptionalGrammars(opts) {
+    const missing = detectMissingOptionalGrammars();
+    if (missing.length === 0)
+        return;
+    const ctx = opts?.context ? ` [${opts.context}]` : '';
+    for (const g of missing) {
+        if (opts?.relevantExtensions && !g.extensions.some((e) => opts.relevantExtensions.has(e))) {
+            continue;
+        }
+        console.error(`GitNexus${ctx}: optional grammar "${g.name}" is unavailable — ${g.extensions.join('/')} files will not be parsed. Reinstall without GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (and ensure python3, make, g++) to enable.`);
+    }
+}

package/dist/cli/setup.js

@@ -9,6 +9,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
 import { execFile, execFileSync } from 'child_process';
+import { createRequire } from 'module';
 import { promisify } from 'util';
 import { fileURLToPath } from 'url';
 import { glob } from 'glob';
@@ -17,6 +18,18 @@ import { getGlobalDir } from '../storage/repo-manager.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const execFileAsync = promisify(execFile);
+// Pin the npx fallback to the installed version. Reason: setup.ts writes
+// a config that persists in the user's editor and is invoked on every MCP
+// connect. Pinning to the installed version means subsequent invocations
+// skip the npm-registry metadata roundtrip (and stay reproducible until
+// the user upgrades). Static configs and READMEs intentionally use
+// `gitnexus@latest` since they're quickstart docs, not persisted state.
+const _require = createRequire(import.meta.url);
+const _pkg = _require('../../package.json');
+if (typeof _pkg.version !== 'string' || !_pkg.version) {
+    throw new Error('gitnexus/package.json#version is missing or not a string — cannot generate MCP fallback config.');
+}
+const NPX_REF = `gitnexus@${_pkg.version}`;
 /**
  * Resolve the absolute path to the `gitnexus` binary if it's installed
  * globally (or via npm -g / yarn global). Returns null when not found.
@@ -51,8 +64,10 @@ function resolveGitnexusBin() {
  * The MCP server entry for all editors.
  *
  * Prefers the globally-installed `gitnexus` binary (starts in ~1 s) over
- * `npx -y gitnexus@latest` (cold-cache install of native deps can take
- * >60 s, exceeding Claude Code's 30 s MCP connection timeout).
+ * `npx -y gitnexus@<version>` (cold-cache install of native deps can take
+ * >60 s, exceeding Claude Code's 30 s MCP connection timeout). The fallback
+ * version is read from gitnexus/package.json#version at module load so the
+ * persisted user config matches the installed package.
  *
  * Falls back to npx when the binary isn't on PATH — e.g. first-time
  * users who ran `npx gitnexus analyze` but haven't done `npm i -g`.
@@ -66,12 +81,12 @@ function getMcpEntry() {
     if (process.platform === 'win32') {
         return {
             command: 'cmd',
-            args: ['/c', 'npx', '-y', 'gitnexus@latest', 'mcp'],
+            args: ['/c', 'npx', '-y', NPX_REF, 'mcp'],
         };
     }
     return {
         command: 'npx',
-        args: ['-y', 'gitnexus@latest', 'mcp'],
+        args: ['-y', NPX_REF, 'mcp'],
     };
 }
 /**
@@ -84,9 +99,9 @@ function getOpenCodeMcpEntry() {
         return { type: 'local', command: [bin, 'mcp'] };
     }
     if (process.platform === 'win32') {
-        return { type: 'local', command: ['cmd', '/c', 'npx', '-y', 'gitnexus@latest', 'mcp'] };
+        return { type: 'local', command: ['cmd', '/c', 'npx', '-y', NPX_REF, 'mcp'] };
     }
-    return { type: 'local', command: ['npx', '-y', 'gitnexus@latest', 'mcp'] };
+    return { type: 'local', command: ['npx', '-y', NPX_REF, 'mcp'] };
 }
 /**
  * Detect indentation style from file content.

package/dist/core/embeddings/embedder.js

@@ -139,7 +139,7 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
             applyHfEnvOverrides(env);
             const isDev = process.env.NODE_ENV === 'development';
             if (isDev) {
-                console.log(`🧠 Loading embedding model: ${finalConfig.modelId}`);
+                console.error(`🧠 Loading embedding model: ${finalConfig.modelId}`);
             }
             const progressCallback = onProgress
                 ? (data) => {
@@ -161,16 +161,16 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
             for (const device of devicesToTry) {
                 try {
                     if (isDev && device === 'dml') {
-                        console.log('🔧 Trying DirectML (DirectX12) GPU backend...');
+                        console.error('🔧 Trying DirectML (DirectX12) GPU backend...');
                     }
                     else if (isDev && device === 'cuda') {
-                        console.log('🔧 Trying CUDA GPU backend...');
+                        console.error('🔧 Trying CUDA GPU backend...');
                     }
                     else if (isDev && device === 'cpu') {
-                        console.log('🔧 Using CPU backend...');
+                        console.error('🔧 Using CPU backend...');
                     }
                     else if (isDev && device === 'wasm') {
-                        console.log('🔧 Using WASM backend (slower)...');
+                        console.error('🔧 Using WASM backend (slower)...');
                     }
                     embedderInstance = await pipeline('feature-extraction', finalConfig.modelId, {
                         device: device,
@@ -190,15 +190,15 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
                             : device === 'cuda'
                                 ? 'GPU (CUDA)'
                                 : device.toUpperCase();
-                        console.log(`✅ Using ${label} backend`);
-                        console.log('✅ Embedding model loaded successfully');
+                        console.error(`✅ Using ${label} backend`);
+                        console.error('✅ Embedding model loaded successfully');
                     }
                     return embedderInstance;
                 }
                 catch (deviceError) {
                     if (isDev && (device === 'cuda' || device === 'dml')) {
                         const gpuType = device === 'dml' ? 'DirectML' : 'CUDA';
-                        console.log(`⚠️  ${gpuType} not available, falling back to CPU...`);
+                        console.error(`⚠️  ${gpuType} not available, falling back to CPU...`);
                     }
                     // Continue to next device in list
                     if (device === devicesToTry[devicesToTry.length - 1]) {

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

@@ -112,7 +112,7 @@ const queryEmbeddableNodes = async (executeQuery) => {
         }
         catch (error) {
             if (isDev) {
-                console.warn(`Query for ${label} nodes failed:`, error);
+                console.error(`Query for ${label} nodes failed:`, error);
             }
         }
     }
@@ -151,7 +151,7 @@ const createVectorIndex = async (executeQuery) => {
     }
     catch (error) {
         if (isDev) {
-            console.warn('Vector index creation warning:', error);
+            console.error('Vector index creation warning:', error);
         }
         return false;
     }
@@ -176,7 +176,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
     try {
         const vectorAvailable = await ensureVectorExtensionAvailable();
         if (!vectorAvailable && isDev)
-            console.warn(vectorUnavailableMessage);
+            console.error(vectorUnavailableMessage);
         // Phase 1: Load embedding model
         onProgress({
             phase: 'loading-model',
@@ -199,7 +199,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
             modelDownloadPercent: 100,
         });
         if (isDev) {
-            console.log('🔍 Querying embeddable nodes...');
+            console.error('🔍 Querying embeddable nodes...');
         }
         // Phase 2: Query embeddable nodes
         let nodes = await queryEmbeddableNodes(executeQuery);
@@ -237,7 +237,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
             // (Kuzu forbids SET on vector-indexed properties; DELETE-then-INSERT is the sanctioned pattern)
             if (staleNodeIds.length > 0) {
                 if (isDev) {
-                    console.log(`🔄 Deleting ${staleNodeIds.length} stale embedding rows for re-embed`);
+                    console.error(`🔄 Deleting ${staleNodeIds.length} stale embedding rows for re-embed`);
                 }
                 try {
                     await executeWithReusedStatement(`MATCH (e:${EMBEDDING_TABLE_NAME} {nodeId: $nodeId}) DELETE e`, staleNodeIds.map((nodeId) => ({ nodeId })));
@@ -253,12 +253,12 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
                 }
             }
             if (isDev) {
-                console.log(`📦 Incremental embeddings: ${beforeCount} total, ${existingEmbeddings.size} cached, ${staleNodeIds.length} stale, ${nodes.length} to embed`);
+                console.error(`📦 Incremental embeddings: ${beforeCount} total, ${existingEmbeddings.size} cached, ${staleNodeIds.length} stale, ${nodes.length} to embed`);
             }
         }
         const totalNodes = nodes.length;
         if (isDev) {
-            console.log(`📊 Found ${totalNodes} embeddable nodes`);
+            console.error(`📊 Found ${totalNodes} embeddable nodes`);
         }
         if (totalNodes === 0) {
             // Ensure the vector index exists even when no new nodes need embedding.
@@ -324,7 +324,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
                     }
                     catch (chunkErr) {
                         if (isDev) {
-                            console.warn(`⚠️ AST chunking failed for ${node.label} "${node.name}" (${node.filePath}), falling back to character-based chunking:`, chunkErr);
+                            console.error(`⚠️ AST chunking failed for ${node.label} "${node.name}" (${node.filePath}), falling back to character-based chunking:`, chunkErr);
                         }
                         chunks = characterChunk(node.content, startLine, endLine, chunkSize, overlap);
                     }
@@ -382,7 +382,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
             totalNodes,
         });
         if (isDev) {
-            console.log('📇 Creating vector index...');
+            console.error('📇 Creating vector index...');
         }
         const vectorIndexReady = await createVectorIndex(executeQuery);
         onProgress({
@@ -392,7 +392,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
             totalNodes,
         });
         if (isDev) {
-            console.log(`✅ Embedding pipeline complete! (${totalChunks} chunks from ${totalNodes} nodes)`);
+            console.error(`✅ Embedding pipeline complete! (${totalChunks} chunks from ${totalNodes} nodes)`);
         }
         return {
             nodesProcessed: totalNodes,

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

@@ -125,7 +125,7 @@ export class ExtensionManager {
         }
         const policy = opts.policy ?? this.options.policy ?? resolvePolicyFromEnv();
         const timeoutMs = opts.installTimeoutMs ?? this.options.installTimeoutMs ?? getExtensionInstallTimeoutMs();
-        const warn = this.options.warn ?? console.warn;
+        const warn = this.options.warn ?? console.error;
         if (policy === 'never') {
             this.markUnavailable(name, label, 'extension install policy is "never"', warn);
             return false;

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

@@ -274,7 +274,7 @@ const doInitLbug = async (dbPath) => {
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             if (!msg.includes('already exists')) {
-                console.warn(`⚠️ Schema creation warning: ${msg.slice(0, 120)}`);
+                console.error(`[gitnexus:lbug] schema creation warning: ${msg.slice(0, 120)}`);
             }
         }
     }
@@ -889,13 +889,13 @@ export const fetchExistingEmbeddingHashes = async (execQuery) => {
                     if (nodeId)
                         map.set(nodeId, STALE_HASH_SENTINEL);
                 }
-                console.log(`[embed] ${map.size} nodes in legacy DB (missing chunk-aware columns) — all treated as stale`);
+                console.error(`[gitnexus:embed] ${map.size} nodes in legacy DB (missing chunk-aware columns) — all treated as stale`);
                 return map;
             }
             catch (fallbackErr) {
                 const fallbackMsg = fallbackErr?.message ?? '';
                 if (isMissingColumnOrTableError(fallbackMsg)) {
-                    console.log(`[embed] CodeEmbedding table not yet present — full embedding run (${fallbackMsg})`);
+                    console.error(`[gitnexus:embed] CodeEmbedding table not yet present — full embedding run (${fallbackMsg})`);
                     return undefined;
                 }
                 throw fallbackErr;

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

@@ -31,9 +31,7 @@ type PoolCloseListener = (repoId: string) => void;
  * listener (handy for tests).
  */
 export declare function addPoolCloseListener(listener: PoolCloseListener): () => void;
-/** Saved real stdout/stderr write — used to silence native module output without race conditions */
-export declare const realStdoutWrite: any;
-export declare const realStderrWrite: any;
+export { realStdoutWrite, realStderrWrite, setActiveStdoutWrite } from '../../mcp/stdio-capture.js';
 /**
  * Touch a repo to reset its idle timeout.
  * Call this during long-running operations to prevent the connection from being closed.
@@ -90,4 +88,3 @@ export declare const isLbugReady: (repoId: string) => boolean;
 export declare const CYPHER_WRITE_RE: RegExp;
 /** Check if a Cypher query contains write operations */
 export declare function isWriteQuery(query: string): boolean;
-export {};

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

@@ -38,9 +38,20 @@ const IDLE_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
 /** Max connections per repo (caps concurrent queries per repo) */
 const MAX_CONNS_PER_REPO = 8;
 let idleTimer = null;
-/** Saved real stdout/stderr write — used to silence native module output without race conditions */
-export const realStdoutWrite = process.stdout.write.bind(process.stdout);
-export const realStderrWrite = process.stderr.write.bind(process.stderr);
+// Stdout-capture state lives in `gitnexus/src/mcp/stdio-capture.ts` — a leaf
+// module with zero non-`node:` imports. We re-export the same symbols here
+// so the existing test mock seam (`gitnexus/src/mcp/core/lbug-adapter.ts`
+// re-exports * from this file, and 8+ test files use that path with
+// `vi.mock(...)`) continues to work without churn. The source of truth is
+// the leaf module; this re-export is a compatibility shim.
+//
+// Why the leaf module exists: Codex's adversarial review on PR #1383 found
+// that putting this state in pool-adapter.ts pulled `@ladybugdb/core` into
+// `cli/mcp.ts`'s static-import closure (via stdio-context → pool-adapter →
+// @ladybugdb/core), corrupting stdout in the pre-sentinel window. Routing
+// through the leaf breaks that chain.
+export { realStdoutWrite, realStderrWrite, setActiveStdoutWrite } from '../../mcp/stdio-capture.js';
+import { getActiveStdoutWrite } from '../../mcp/stdio-capture.js';
 let stdoutSilenceCount = 0;
 /** True while pre-warming connections — prevents watchdog from prematurely restoring stdout */
 let preWarmActive = false;
@@ -155,13 +166,15 @@ let activeQueryCount = 0;
  */
 export function silenceStdout() {
     if (stdoutSilenceCount++ === 0) {
+        // eslint-disable-next-line no-restricted-syntax -- silencing infrastructure; replacement is a no-op
         process.stdout.write = (() => true);
     }
 }
 export function restoreStdout() {
     if (--stdoutSilenceCount <= 0) {
         stdoutSilenceCount = 0;
-        process.stdout.write = realStdoutWrite;
+        // eslint-disable-next-line no-restricted-syntax -- restoring the active stdout-write handler is the silencing API contract
+        process.stdout.write = getActiveStdoutWrite();
     }
 }
 // Safety watchdog: restore stdout if it gets stuck silenced (e.g. native crash
@@ -171,7 +184,8 @@ export function restoreStdout() {
 setInterval(() => {
     if (stdoutSilenceCount > 0 && !preWarmActive && activeQueryCount === 0) {
         stdoutSilenceCount = 0;
-        process.stdout.write = realStdoutWrite;
+        // eslint-disable-next-line no-restricted-syntax -- watchdog recovery for stuck silencing
+        process.stdout.write = getActiveStdoutWrite();
     }
 }, 1000).unref();
 function createConnection(db) {

package/dist/core/tree-sitter/parser-loader.js

@@ -114,10 +114,10 @@ const logFailure = (key, result) => {
         return;
     logged.add(key);
     const message = `[gitnexus] ${result.note} (${result.error.message})`;
-    if (result.severity === 'error')
-        console.error(message);
-    else
-        console.warn(message);
+    // Both severities go to stderr — console.warn writes to stderr too, but
+    // console.error is the stdout-safe channel we standardize on across
+    // MCP-reachable code so the ESLint rule covers this directory.
+    console.error(message);
 };
 export const resolveLanguageKey = (language, filePath) => language === SupportedLanguages.TypeScript && filePath?.endsWith('.tsx')
     ? `${language}:tsx`

package/dist/mcp/compatible-stdio-transport.js

@@ -1,5 +1,6 @@
 import process from 'node:process';
 import { JSONRPCMessageSchema } from '@modelcontextprotocol/sdk/types.js';
+import { withMcpWrite } from './stdio-context.js';
 function deserializeMessage(raw) {
     return JSONRPCMessageSchema.parse(JSON.parse(raw));
 }
@@ -185,7 +186,12 @@ export class CompatibleStdioServerTransport {
                 reject(error);
             };
             this._stdout.on('error', onError);
-            if (this._stdout.write(payload)) {
+            // Tag the write with the MCP transport context so the sentinel
+            // (server.ts createStdoutSentinel Proxy) recognizes it as a legitimate
+            // JSON-RPC frame and passes it through to the real stdout instead of
+            // redirecting to stderr.
+            const writeOk = withMcpWrite(() => this._stdout.write(payload));
+            if (writeOk) {
                 this._stdout.removeListener('error', onError);
                 resolve();
             }

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

@@ -1,5 +1,11 @@
 /**
  * LadybugDB connection pool — re-exported from core.
- * Prefer importing from `../../core/lbug/pool-adapter.js` in new code.
+ *
+ * KEEP THIS FILE. It is intentionally a shim re-export of
+ * `../../core/lbug/pool-adapter.js`. The MCP test suite uses this path as
+ * a vi.mock seam so unit tests can stub LadybugDB without affecting other
+ * importers of `core/lbug/pool-adapter.js` (which is shared with the
+ * analyze pipeline). New non-test code MAY import from `pool-adapter.js`
+ * directly, but the shim must continue to exist for the mock seam to work.
  */
 export * from '../../core/lbug/pool-adapter.js';

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

@@ -1,5 +1,11 @@
 /**
  * LadybugDB connection pool — re-exported from core.
- * Prefer importing from `../../core/lbug/pool-adapter.js` in new code.
+ *
+ * KEEP THIS FILE. It is intentionally a shim re-export of
+ * `../../core/lbug/pool-adapter.js`. The MCP test suite uses this path as
+ * a vi.mock seam so unit tests can stub LadybugDB without affecting other
+ * importers of `core/lbug/pool-adapter.js` (which is shared with the
+ * analyze pipeline). New non-test code MAY import from `pool-adapter.js`
+ * directly, but the shim must continue to exist for the mock seam to work.
  */
 export * from '../../core/lbug/pool-adapter.js';

package/dist/mcp/server.js

@@ -15,7 +15,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CompatibleStdioServerTransport } from './compatible-stdio-transport.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { GITNEXUS_TOOLS } from './tools.js';
-import { realStdoutWrite } from './core/lbug-adapter.js';
+import { installGlobalStdoutSentinel } from './stdio-context.js';
 import { getResourceDefinitions, getResourceTemplates, readResource } from './resources.js';
 /**
  * Next-step hints appended to tool responses.
@@ -247,19 +247,30 @@ Follow these steps:
  */
 export async function startMCPServer(backend) {
     const server = createMCPServer(backend);
-    // Use the shared stdout reference captured at module-load time by the
-    // lbug-adapter.  Avoids divergence if anything patches stdout between
-    // module load and server start.
-    const _safeStdout = new Proxy(process.stdout, {
+    // Idempotent global sentinel install. cli/mcp.ts calls this first thing
+    // (before warnMissingOptionalGrammars / backend.init can emit to stdout);
+    // calling again here is a safety net for direct callers of startMCPServer
+    // (tests, future entry points). The transport's _safeStdout Proxy is a
+    // second layer that guarantees transport writes reach the sentinel even
+    // if anything else re-replaces process.stdout.write later. Tagged
+    // transport writes (wrapped in withMcpWrite by compatible-stdio-transport.send)
+    // pass through to the captured realStdoutWrite; untagged writes reaching
+    // the Proxy or process.stdout get redirected to stderr with the
+    // [mcp:stdout-redirect] prefix. See stdio-context.ts.
+    const sentinel = installGlobalStdoutSentinel();
+    const safeStdout = new Proxy(process.stdout, {
         get(target, prop, receiver) {
             if (prop === 'write')
-                return realStdoutWrite;
+                return sentinel.write;
             const val = Reflect.get(target, prop, receiver);
             return typeof val === 'function' ? val.bind(target) : val;
         },
     });
-    const transport = new CompatibleStdioServerTransport(process.stdin, _safeStdout);
+    const transport = new CompatibleStdioServerTransport(process.stdin, safeStdout);
     await server.connect(transport);
+    // Surface the redirect counter on shutdown so users see the volume of
+    // stray writes even when individual payloads were truncated/suppressed.
+    process.on('exit', () => sentinel.flushSummary());
     // Graceful shutdown helper
     let shuttingDown = false;
     const shutdown = async (exitCode = 0) => {

package/dist/mcp/stdio-capture.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Stdio capture — leaf module with zero non-`node:` imports.
+ *
+ * Owns the singleton state that the MCP stdout sentinel needs:
+ *   - `realStdoutWrite` / `realStderrWrite`: process.stdout.write /
+ *     process.stderr.write captured at module load, BEFORE anything else
+ *     can rebind them.
+ *   - `activeStdoutWrite`: the write handler that silenceStdout/restoreStdout
+ *     cycles in pool-adapter restore to. Defaults to `realStdoutWrite`;
+ *     `installGlobalStdoutSentinel` (in stdio-context.ts) registers the
+ *     sentinel here at MCP startup so silence/restore preserves the sentinel.
+ *
+ * This module exists separately from `pool-adapter.ts` (which previously
+ * owned the same state) so that `cli/mcp.ts`'s static-import closure does
+ * NOT transitively pull in `@ladybugdb/core`. Codex's adversarial review on
+ * PR #1383 found that the prior structure left a pre-sentinel window where
+ * native-module init banners could reach raw stdout: `cli/mcp.ts` →
+ * `mcp/stdio-context.ts` → `core/lbug/pool-adapter.ts` → `@ladybugdb/core`.
+ * Routing the sentinel state through this leaf module breaks that chain.
+ *
+ * **Constraint:** keep this module a leaf. No non-`node:` imports — adding
+ * any would re-introduce the import-time stdout-corruption hazard.
+ */
+type StdoutWrite = typeof process.stdout.write;
+/** Captured at module load, before any rebinding. */
+export declare const realStdoutWrite: StdoutWrite;
+export declare const realStderrWrite: typeof process.stderr.write;
+/**
+ * Register a wrapper (e.g., the MCP sentinel) as the active stdout write.
+ * silenceStdout/restoreStdout cycles in pool-adapter will preserve the
+ * wrapper instead of unwinding to the raw realStdoutWrite. Returns the
+ * previous value so callers can chain or restore.
+ */
+export declare function setActiveStdoutWrite(fn: StdoutWrite): StdoutWrite;
+/**
+ * Read the currently-active stdout write handler. Used by pool-adapter's
+ * restoreStdout and watchdog so silence/restore preserves the sentinel.
+ */
+export declare function getActiveStdoutWrite(): StdoutWrite;
+export {};

package/dist/mcp/stdio-capture.js

@@ -0,0 +1,53 @@
+/**
+ * Stdio capture — leaf module with zero non-`node:` imports.
+ *
+ * Owns the singleton state that the MCP stdout sentinel needs:
+ *   - `realStdoutWrite` / `realStderrWrite`: process.stdout.write /
+ *     process.stderr.write captured at module load, BEFORE anything else
+ *     can rebind them.
+ *   - `activeStdoutWrite`: the write handler that silenceStdout/restoreStdout
+ *     cycles in pool-adapter restore to. Defaults to `realStdoutWrite`;
+ *     `installGlobalStdoutSentinel` (in stdio-context.ts) registers the
+ *     sentinel here at MCP startup so silence/restore preserves the sentinel.
+ *
+ * This module exists separately from `pool-adapter.ts` (which previously
+ * owned the same state) so that `cli/mcp.ts`'s static-import closure does
+ * NOT transitively pull in `@ladybugdb/core`. Codex's adversarial review on
+ * PR #1383 found that the prior structure left a pre-sentinel window where
+ * native-module init banners could reach raw stdout: `cli/mcp.ts` →
+ * `mcp/stdio-context.ts` → `core/lbug/pool-adapter.ts` → `@ladybugdb/core`.
+ * Routing the sentinel state through this leaf module breaks that chain.
+ *
+ * **Constraint:** keep this module a leaf. No non-`node:` imports — adding
+ * any would re-introduce the import-time stdout-corruption hazard.
+ */
+/** Captured at module load, before any rebinding. */
+// eslint-disable-next-line no-restricted-syntax -- this IS the captured-real-write infrastructure used by the MCP sentinel
+export const realStdoutWrite = process.stdout.write.bind(process.stdout);
+export const realStderrWrite = process.stderr.write.bind(process.stderr);
+/**
+ * The function `restoreStdout` (and the watchdog) in pool-adapter restore
+ * *to* when un-silencing. Defaults to the captured real write; the MCP
+ * server registers its sentinel here at startMCPServer (via
+ * installGlobalStdoutSentinel) so silenceStdout cycles preserve the sentinel
+ * instead of unwinding to raw stdout.
+ */
+let activeStdoutWrite = realStdoutWrite;
+/**
+ * Register a wrapper (e.g., the MCP sentinel) as the active stdout write.
+ * silenceStdout/restoreStdout cycles in pool-adapter will preserve the
+ * wrapper instead of unwinding to the raw realStdoutWrite. Returns the
+ * previous value so callers can chain or restore.
+ */
+export function setActiveStdoutWrite(fn) {
+    const prev = activeStdoutWrite;
+    activeStdoutWrite = fn;
+    return prev;
+}
+/**
+ * Read the currently-active stdout write handler. Used by pool-adapter's
+ * restoreStdout and watchdog so silence/restore preserves the sentinel.
+ */
+export function getActiveStdoutWrite() {
+    return activeStdoutWrite;
+}

package/dist/mcp/stdio-context.d.ts

@@ -0,0 +1,47 @@
+/**
+ * MCP Stdio Context — AsyncLocalStorage-tagged transport-write detection.
+ *
+ * The MCP stdio transport writes JSON-RPC frames to stdout. Per spec, the
+ * server MUST NOT write anything to stdout that is not a valid MCP message.
+ * Stray writes from dependency code corrupt the protocol and present to
+ * clients as a hung handshake or `MCP error -32000`.
+ *
+ * This module provides:
+ *   - withMcpWrite(fn): runs fn inside an AsyncLocalStorage context tagged
+ *     `mcp: true`. The transport wraps every send() in this so its writes
+ *     are recognizable as legitimate.
+ *   - isMcpWrite(): true when called inside withMcpWrite.
+ *   - createStdoutSentinel({...}): a write function suitable for installing
+ *     in a Proxy over process.stdout. Tagged writes pass through to the real
+ *     stdout; untagged writes are redirected to stderr with a [mcp:stdout-redirect]
+ *     prefix, truncated to maxBytes per redirect, and rate-limited to maxRedirects
+ *     per process so a stray loop cannot flood client logs.
+ *
+ * The sentinel is correctness-by-construction: it identifies legitimate
+ * writes by *who* called write(), not by inspecting the bytes. A byte-shape
+ * heuristic ("starts with {, ends with \n") would falsely reject Content-Length
+ * frames (which start with C and end with }) and misclassify multi-chunk writes.
+ */
+export declare function withMcpWrite<T>(fn: () => T): T;
+export declare function isMcpWrite(): boolean;
+type WriteFn = typeof process.stdout.write;
+export interface SentinelOptions {
+    realStdoutWrite: WriteFn;
+    realStderrWrite: WriteFn;
+    /** Maximum bytes of payload to surface per redirect. Defaults to 200. */
+    maxBytes?: number;
+    /** Maximum number of redirects per process before suppression. Defaults to 10. */
+    maxRedirects?: number;
+}
+export interface SentinelStats {
+    redirected: number;
+    suppressed: number;
+}
+export interface Sentinel {
+    write: WriteFn;
+    stats: () => SentinelStats;
+    flushSummary: () => void;
+}
+export declare function createStdoutSentinel(opts: SentinelOptions): Sentinel;
+export declare function installGlobalStdoutSentinel(): Sentinel;
+export {};

package/dist/mcp/stdio-context.js

@@ -0,0 +1,145 @@
+/**
+ * MCP Stdio Context — AsyncLocalStorage-tagged transport-write detection.
+ *
+ * The MCP stdio transport writes JSON-RPC frames to stdout. Per spec, the
+ * server MUST NOT write anything to stdout that is not a valid MCP message.
+ * Stray writes from dependency code corrupt the protocol and present to
+ * clients as a hung handshake or `MCP error -32000`.
+ *
+ * This module provides:
+ *   - withMcpWrite(fn): runs fn inside an AsyncLocalStorage context tagged
+ *     `mcp: true`. The transport wraps every send() in this so its writes
+ *     are recognizable as legitimate.
+ *   - isMcpWrite(): true when called inside withMcpWrite.
+ *   - createStdoutSentinel({...}): a write function suitable for installing
+ *     in a Proxy over process.stdout. Tagged writes pass through to the real
+ *     stdout; untagged writes are redirected to stderr with a [mcp:stdout-redirect]
+ *     prefix, truncated to maxBytes per redirect, and rate-limited to maxRedirects
+ *     per process so a stray loop cannot flood client logs.
+ *
+ * The sentinel is correctness-by-construction: it identifies legitimate
+ * writes by *who* called write(), not by inspecting the bytes. A byte-shape
+ * heuristic ("starts with {, ends with \n") would falsely reject Content-Length
+ * frames (which start with C and end with }) and misclassify multi-chunk writes.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+// Import from the leaf module, NOT `core/lbug/pool-adapter.js`. pool-adapter
+// pulls in `@ladybugdb/core`, which would put the native module in
+// `cli/mcp.ts`'s static-import closure — exactly the pre-sentinel window
+// Codex's adversarial review flagged on PR #1383.
+import { realStdoutWrite, realStderrWrite, setActiveStdoutWrite } from './stdio-capture.js';
+const store = new AsyncLocalStorage();
+export function withMcpWrite(fn) {
+    return store.run({ mcp: true }, fn);
+}
+export function isMcpWrite() {
+    return store.getStore()?.mcp === true;
+}
+const REDIRECT_PREFIX = '[mcp:stdout-redirect] ';
+const STARTUP_WARNING = '[mcp:stdout-redirect] sentinel triggered — stray write redirected to stderr; subsequent redirects logged at exit\n';
+function chunkToBuffer(chunk) {
+    if (chunk === undefined || chunk === null)
+        return Buffer.alloc(0);
+    if (Buffer.isBuffer(chunk))
+        return chunk;
+    if (typeof chunk === 'string')
+        return Buffer.from(chunk, 'utf8');
+    // Plain Uint8Array (e.g. from a TypedArray-using producer): copy bytes
+    // verbatim instead of falling through to String(chunk), which produces
+    // garbage like "1,2,3,...".
+    if (chunk instanceof Uint8Array)
+        return Buffer.from(chunk);
+    return Buffer.from(String(chunk), 'utf8');
+}
+/**
+ * Node Writable.write contract: the completion callback, when present, is
+ * always the last argument. Match exactly that — don't try to peer past
+ * earlier arguments — so future overload shapes (e.g. an options object)
+ * do not silently break callback delivery.
+ */
+function extractCallback(rest) {
+    const last = rest[rest.length - 1];
+    return typeof last === 'function' ? last : undefined;
+}
+export function createStdoutSentinel(opts) {
+    const maxBytes = opts.maxBytes ?? 200;
+    const maxRedirects = opts.maxRedirects ?? 10;
+    let redirected = 0;
+    let suppressed = 0;
+    let warningEmitted = false;
+    const stderr = (s) => opts.realStderrWrite(s);
+    const write = (chunk, ...rest) => {
+        if (isMcpWrite()) {
+            return opts.realStdoutWrite(chunk, ...rest);
+        }
+        if (!warningEmitted) {
+            warningEmitted = true;
+            stderr(STARTUP_WARNING);
+        }
+        if (redirected < maxRedirects) {
+            redirected += 1;
+            const buf = chunkToBuffer(chunk);
+            const truncated = buf.length > maxBytes ? buf.subarray(0, maxBytes) : buf;
+            stderr(REDIRECT_PREFIX);
+            if (truncated.length > 0)
+                stderr(truncated);
+            if (buf.length > maxBytes) {
+                stderr(` (+${buf.length - maxBytes} bytes truncated)`);
+            }
+            if (truncated.length === 0 || truncated[truncated.length - 1] !== 0x0a) {
+                stderr('\n');
+            }
+        }
+        else {
+            suppressed += 1;
+        }
+        // Honor the Writable.write callback contract — fire async to match
+        // Node's "next-tick" semantics so callers never observe sync reentry.
+        const cb = extractCallback(rest);
+        if (cb) {
+            process.nextTick(() => cb(null));
+        }
+        return true;
+    };
+    return {
+        write,
+        stats: () => ({ redirected, suppressed }),
+        flushSummary: () => {
+            if (redirected === 0 && suppressed === 0)
+                return;
+            stderr(`[mcp:stdout-redirect] summary: ${redirected} redirected, ${suppressed} suppressed beyond cap\n`);
+        },
+    };
+}
+/**
+ * Install the sentinel as the global stdout interceptor — idempotent.
+ *
+ * Does three things in order:
+ *   1. Creates the sentinel from the captured `realStdoutWrite` / `realStderrWrite`.
+ *   2. Replaces `process.stdout.write` with `sentinel.write`.
+ *   3. Registers `sentinel.write` as the "active" handler in pool-adapter
+ *      so silenceStdout/restoreStdout cycles preserve the sentinel
+ *      instead of unwinding to raw stdout.
+ *
+ * Idempotent — callers may invoke it multiple times safely (cli/mcp.ts at
+ * the top of mcpCommand, and startMCPServer). The earliest caller wins;
+ * subsequent calls return the same sentinel handle. Call this BEFORE any
+ * other startup work that might emit to stdout: native module loads,
+ * `_require()`-style grammar detection, repo registry reads, embedder
+ * pipeline initialization. Anything written before the sentinel is in
+ * place reaches raw stdout uncaught.
+ *
+ * Returns the sentinel handle so the earliest caller can register
+ * `process.on('exit', sentinel.flushSummary)`.
+ */
+let _installedSentinel = null;
+export function installGlobalStdoutSentinel() {
+    if (_installedSentinel)
+        return _installedSentinel;
+    const sentinel = createStdoutSentinel({ realStdoutWrite, realStderrWrite });
+    // eslint-disable-next-line no-restricted-syntax -- installing the global sentinel is the API contract
+    process.stdout.write = sentinel.write;
+    setActiveStdoutWrite(sentinel.write);
+    _installedSentinel = sentinel;
+    return sentinel;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.4-rc.80",
+  "version": "1.6.4-rc.81",
   "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",
@@ -44,6 +44,7 @@
     "dev": "tsx watch src/cli/index.ts",
     "test": "vitest run",
     "test:unit": "vitest run test/unit",
+    "pretest:integration": "node scripts/build.js",
     "test:integration": "vitest run test/integration",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",

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

@@ -3,6 +3,17 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
+// Opt-out: skip the native rebuild entirely. Dart parsing becomes
+// unavailable but `npm install gitnexus` finishes much faster on machines
+// without a C++ toolchain. Strict `=== '1'` only — '=true', '=yes', '=0'
+// (read as a string), and any other value all fall through to the rebuild.
+if (process.env.GITNEXUS_SKIP_OPTIONAL_GRAMMARS === '1') {
+  console.warn(
+    '[tree-sitter-dart] Skipping build (GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1). Dart parsing will be unavailable until reinstalled without the env var.',
+  );
+  process.exit(0);
+}
+
 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');

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

@@ -34,6 +34,17 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
+// Opt-out: skip the native rebuild entirely. Proto parsing becomes
+// unavailable but `npm install gitnexus` finishes much faster on machines
+// without a C++ toolchain. Strict `=== '1'` only — '=true', '=yes', '=0'
+// (read as a string), and any other value all fall through to the rebuild.
+if (process.env.GITNEXUS_SKIP_OPTIONAL_GRAMMARS === '1') {
+  console.warn(
+    '[tree-sitter-proto] Skipping build (GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1). Proto parsing will be unavailable until reinstalled without the env var.',
+  );
+  process.exit(0);
+}
+
 const protoDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-proto');
 const bindingGyp = path.join(protoDir, 'binding.gyp');
 const bindingNode = path.join(protoDir, 'build', 'Release', 'tree_sitter_proto_binding.node');