gitnexus 1.6.4-rc.85 → 1.6.4-rc.87

package/dist/cli/ai-context.js

@@ -8,6 +8,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { logger } from '../core/logger.js';
 // ESM equivalent of __dirname
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -235,7 +236,7 @@ Use GitNexus tools to accomplish this task.
         }
         catch (err) {
             // Skip on error, don't fail the whole process
-            console.warn(`Warning: Could not install skill ${skill.name}:`, err);
+            logger.warn({ err }, `Warning: Could not install skill ${skill.name}:`);
         }
     }
     return installedSkills;

package/dist/cli/analyze.js

@@ -19,6 +19,7 @@ import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-si
 import { warnMissingOptionalGrammars } from './optional-grammars.js';
 import { glob } from 'glob';
 import fs from 'fs/promises';
+import { cliError } from './cli-message.js';
 // Capture stderr.write at module load BEFORE anything (LadybugDB native
 // init, progress bar, console redirection) can monkey-patch it. The
 // fatal handlers below MUST reach the user even when the analyze path
@@ -100,7 +101,7 @@ export const analyzeCommand = async (inputPath, options) => {
     if (options?.workerTimeout) {
         const workerTimeoutSeconds = Number(options.workerTimeout);
         if (!Number.isFinite(workerTimeoutSeconds) || workerTimeoutSeconds < 1) {
-            console.error('  --worker-timeout must be at least 1 second.\n');
+            cliError('  --worker-timeout must be at least 1 second.\n');
             process.exitCode = 1;
             return;
         }
@@ -114,7 +115,7 @@ export const analyzeCommand = async (inputPath, options) => {
     if (typeof options?.embeddings === 'string') {
         const parsed = Number(options.embeddings);
         if (!Number.isInteger(parsed) || parsed < 0) {
-            console.error(`  --embeddings expects a non-negative integer (got "${options.embeddings}"). ` +
+            cliError(`  --embeddings expects a non-negative integer (got "${options.embeddings}"). ` +
                 `Pass 0 to disable the safety cap, or omit the value to keep the default.\n`);
             process.exitCode = 1;
             return;
@@ -127,7 +128,7 @@ export const analyzeCommand = async (inputPath, options) => {
             return true;
         const parsed = Number(value);
         if (!Number.isInteger(parsed) || parsed <= 0) {
-            console.error(`  ${optionName} must be a positive integer.\n`);
+            cliError(`  ${optionName} must be a positive integer.\n`);
             process.exitCode = 1;
             return false;
         }
@@ -142,7 +143,7 @@ export const analyzeCommand = async (inputPath, options) => {
     if (options?.embeddingDevice) {
         const allowed = new Set(['auto', 'cpu', 'dml', 'cuda', 'wasm']);
         if (!allowed.has(options.embeddingDevice)) {
-            console.error('  --embedding-device must be one of: auto, cpu, dml, cuda, wasm.\n');
+            cliError('  --embedding-device must be one of: auto, cpu, dml, cuda, wasm.\n');
             process.exitCode = 1;
             return;
         }
@@ -221,7 +222,9 @@ export const analyzeCommand = async (inputPath, options) => {
         stopOnComplete: false,
     }, cliProgress.Presets.shades_grey);
     bar.start(100, 0, { phase: 'Initializing...' });
-    // Graceful SIGINT handling
+    // Graceful SIGINT handling. Pino's default destination is `sync: false`
+    // (buffered) — flush before exit so in-flight records reach stderr.
+    // See `gitnexus/src/core/logger.ts:flushLoggerSync`.
     let aborted = false;
     const sigintHandler = () => {
         if (aborted)
@@ -231,12 +234,22 @@ export const analyzeCommand = async (inputPath, options) => {
         console.log('\n  Interrupted — cleaning up...');
         closeLbug()
             .catch(() => { })
-            .finally(() => process.exit(130));
+            .finally(async () => {
+            const { flushLoggerSync } = await import('../core/logger.js');
+            flushLoggerSync();
+            process.exit(130);
+        });
     };
     process.on('SIGINT', sigintHandler);
-    // Route console output through bar.log() to prevent progress bar corruption
+    // Route console output through bar.log() to prevent progress bar corruption.
+    // This is a deliberate UI pattern (not a logging concern): analyze runs a
+    // long-lived progress bar on stdout; any concurrent console.* write would
+    // overwrite the bar mid-render. We capture originals, swap to barLog for
+    // the lifetime of the run, and restore on completion/error/SIGINT.
     const origLog = console.log.bind(console);
+    // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
     const origWarn = console.warn.bind(console);
+    // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
     const origError = console.error.bind(console);
     let barCurrentValue = 0;
     const barLog = (...args) => {
@@ -245,7 +258,9 @@ export const analyzeCommand = async (inputPath, options) => {
         bar.update(barCurrentValue);
     };
     console.log = barLog;
+    // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
     console.warn = barLog;
+    // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
     console.error = barLog;
     // Track elapsed time per phase
     let lastPhaseLabel = 'Initializing...';
@@ -301,7 +316,9 @@ export const analyzeCommand = async (inputPath, options) => {
             clearInterval(elapsedTimer);
             process.removeListener('SIGINT', sigintHandler);
             console.log = origLog;
+            // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
             console.warn = origWarn;
+            // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
             console.error = origError;
             bar.stop();
             console.log('  Already up to date\n');
@@ -357,7 +374,9 @@ export const analyzeCommand = async (inputPath, options) => {
         clearInterval(elapsedTimer);
         process.removeListener('SIGINT', sigintHandler);
         console.log = origLog;
+        // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
         console.warn = origWarn;
+        // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
         console.error = origError;
         bar.update(100, { phase: 'Done' });
         bar.stop();
@@ -378,19 +397,20 @@ export const analyzeCommand = async (inputPath, options) => {
         clearInterval(elapsedTimer);
         process.removeListener('SIGINT', sigintHandler);
         console.log = origLog;
+        // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
         console.warn = origWarn;
+        // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
         console.error = origError;
         bar.stop();
         const msg = err.message || String(err);
         // Registry name-collision from --name (#829) — surface as an
         // actionable error rather than a generic stack-trace.
         if (err instanceof RegistryNameCollisionError) {
-            console.error(`\n  Registry name collision:\n`);
-            console.error(`    "${err.registryName}" is already used by "${err.existingPath}".\n`);
-            console.error(`  Options:`);
-            console.error(`    • Pick a different alias:  gitnexus analyze --name <alias>`);
-            console.error(`    • Allow the duplicate:     gitnexus analyze --allow-duplicate-name  (leaves "-r ${err.registryName}" ambiguous)`);
-            console.error('');
+            cliError(`\n  Registry name collision:\n` +
+                `    "${err.registryName}" is already used by "${err.existingPath}".\n\n` +
+                `  Options:\n` +
+                `    • Pick a different alias:  gitnexus analyze --name <alias>\n` +
+                `    • Allow the duplicate:     gitnexus analyze --allow-duplicate-name  (leaves "-r ${err.registryName}" ambiguous)\n`, { registryName: err.registryName, existingPath: err.existingPath });
             process.exitCode = 1;
             return;
         }
@@ -423,34 +443,31 @@ export const analyzeCommand = async (inputPath, options) => {
             msg.includes('allocation failed') ||
             msg.includes('heap out of memory') ||
             msg.includes('JavaScript heap')) {
-            console.error('  This error typically occurs on very large repositories.');
-            console.error('  Suggestions:');
-            console.error('    1. Add large vendored/generated directories to .gitnexusignore');
-            console.error('    2. Increase Node.js heap: NODE_OPTIONS="--max-old-space-size=16384"');
-            console.error('    3. Increase stack size: NODE_OPTIONS="--stack-size=4096"');
-            console.error('');
+            cliError(`  This error typically occurs on very large repositories.\n` +
+                `  Suggestions:\n` +
+                `    1. Add large vendored/generated directories to .gitnexusignore\n` +
+                `    2. Increase Node.js heap: NODE_OPTIONS="--max-old-space-size=16384"\n` +
+                `    3. Increase stack size: NODE_OPTIONS="--stack-size=4096"\n`, { recoveryHint: 'large-repo' });
         }
         else if (msg.includes('ERESOLVE') || msg.includes('Could not resolve dependency')) {
             // Note: the original arborist "Cannot destructure property 'package' of
             // 'node.target'" crash happens inside npm *before* gitnexus code runs,
             // so it can't be caught here.  This branch handles dependency-resolution
             // errors that surface at runtime (e.g. dynamic require failures).
-            console.error('  This looks like an npm dependency resolution issue.');
-            console.error('  Suggestions:');
-            console.error('    1. Clear the npm cache:    npm cache clean --force');
-            console.error('    2. Update npm:             npm install -g npm@latest');
-            console.error('    3. Reinstall gitnexus:     npm install -g gitnexus@latest');
-            console.error('    4. Or try npx directly:    npx gitnexus@latest analyze');
-            console.error('');
+            cliError(`  This looks like an npm dependency resolution issue.\n` +
+                `  Suggestions:\n` +
+                `    1. Clear the npm cache:    npm cache clean --force\n` +
+                `    2. Update npm:             npm install -g npm@latest\n` +
+                `    3. Reinstall gitnexus:     npm install -g gitnexus@latest\n` +
+                `    4. Or try npx directly:    npx gitnexus@latest analyze\n`, { recoveryHint: 'npm-resolution' });
         }
         else if (msg.includes('MODULE_NOT_FOUND') ||
             msg.includes('Cannot find module') ||
             msg.includes('ERR_MODULE_NOT_FOUND')) {
-            console.error('  A required module could not be loaded. The installation may be corrupt.');
-            console.error('  Suggestions:');
-            console.error('    1. Reinstall:   npm install -g gitnexus@latest');
-            console.error('    2. Clear cache: npm cache clean --force && npx gitnexus@latest analyze');
-            console.error('');
+            cliError(`  A required module could not be loaded. The installation may be corrupt.\n` +
+                `  Suggestions:\n` +
+                `    1. Reinstall:   npm install -g gitnexus@latest\n` +
+                `    2. Clear cache: npm cache clean --force && npx gitnexus@latest analyze\n`, { recoveryHint: 'module-not-found' });
         }
         process.exitCode = 1;
         return;

package/dist/cli/clean.js

@@ -5,6 +5,7 @@
  * Also unregisters it from the global registry.
  */
 import fs from 'fs/promises';
+import { logger } from '../core/logger.js';
 import { findRepo, unregisterRepo, listRegisteredRepos, assertSafeStoragePath, UnsafeStoragePathError, } from '../storage/repo-manager.js';
 export const cleanCommand = async (options) => {
     // --all flag: clean all indexed repos
@@ -37,7 +38,7 @@ export const cleanCommand = async (options) => {
             }
             catch (err) {
                 if (err instanceof UnsafeStoragePathError) {
-                    console.error(`Refusing to clean ${entry.name}: ${err.message}`);
+                    logger.error(`Refusing to clean ${entry.name}: ${err.message}`);
                     continue;
                 }
                 throw err;
@@ -48,7 +49,7 @@ export const cleanCommand = async (options) => {
                 console.log(`Deleted: ${entry.name} (${entry.storagePath})`);
             }
             catch (err) {
-                console.error(`Failed to delete ${entry.name}:`, err);
+                logger.error({ err }, `Failed to delete ${entry.name}:`);
             }
         }
         return;
@@ -73,6 +74,6 @@ export const cleanCommand = async (options) => {
         console.log(`Deleted: ${repo.storagePath}`);
     }
     catch (err) {
-        console.error('Failed to delete:', err);
+        logger.error({ err }, 'Failed to delete:');
     }
 };

package/dist/cli/cli-message.d.ts

@@ -0,0 +1,15 @@
+/**
+ * User-facing informational message. Use for banners, listening URLs,
+ * and any message the user expects to read in plain text.
+ */
+export declare function cliInfo(msg: string, fields?: Record<string, unknown>): void;
+/**
+ * User-facing warning. Operator-actionable but non-fatal — `cliWarn`
+ * indicates the command can still proceed in some form.
+ */
+export declare function cliWarn(msg: string, fields?: Record<string, unknown>): void;
+/**
+ * User-facing error. Indicates the command cannot proceed; usually
+ * paired with a non-zero exit code at the call site.
+ */
+export declare function cliError(msg: string, fields?: Record<string, unknown>): void;

package/dist/cli/cli-message.js

@@ -0,0 +1,61 @@
+/**
+ * CLI message helpers — for user-facing banners, error guidance, and
+ * recovery hints emitted by `gitnexus` subcommands.
+ *
+ * These functions write **plain text** directly to `process.stderr` AND
+ * tee a structured pino record through the singleton `logger`. Plain text
+ * preserves the human-readable contract for users running `gitnexus`
+ * interactively, redirecting to a file, or piping to `cat`/`grep`. The
+ * structured tee keeps log aggregators happy.
+ *
+ * **Use these for:**
+ *   - User-facing banners ("Server listening on http://...:N")
+ *   - Validation errors ("--worker-timeout must be at least 1 second")
+ *   - Recovery hints ("Suggestions: 1. Clear the npm cache, 2. ...")
+ *   - One-line user notices ("No indexed repositories found.")
+ *
+ * **Do NOT use these for:**
+ *   - Internal diagnostics (worker progress, retry counts, telemetry)
+ *     — use `logger.info`/`warn`/`error` directly. Internal logs only
+ *     need structured fields, not double-output to stderr.
+ *   - High-volume hot paths — every `cliMessage` call writes twice (raw
+ *     + structured). Acceptable for user-facing messages, wasteful for
+ *     ingestion pipeline events.
+ *
+ * Design note: stderr is the right channel even for non-error messages
+ * because GitNexus CLI tools (`query`, `cypher`, `impact`) emit JSON
+ * data on stdout for piping (`gitnexus query | jq`). User banners on
+ * stdout would corrupt that pipeline.
+ */
+import { logger } from '../core/logger.js';
+function writeStderr(msg) {
+    // Direct write — bypassing `console.*` so it cannot be intercepted by
+    // progress-bar redirection (see `cli/analyze.ts:barLog`) or other
+    // routing. The structured tee below still goes through the logger so
+    // log aggregation works either way.
+    process.stderr.write(msg.endsWith('\n') ? msg : msg + '\n');
+}
+/**
+ * User-facing informational message. Use for banners, listening URLs,
+ * and any message the user expects to read in plain text.
+ */
+export function cliInfo(msg, fields) {
+    writeStderr(msg);
+    logger.info(fields ?? {}, msg);
+}
+/**
+ * User-facing warning. Operator-actionable but non-fatal — `cliWarn`
+ * indicates the command can still proceed in some form.
+ */
+export function cliWarn(msg, fields) {
+    writeStderr(msg);
+    logger.warn(fields ?? {}, msg);
+}
+/**
+ * User-facing error. Indicates the command cannot proceed; usually
+ * paired with a non-zero exit code at the call site.
+ */
+export function cliError(msg, fields) {
+    writeStderr(msg);
+    logger.error(fields ?? {}, msg);
+}

package/dist/cli/eval-server.js

@@ -26,6 +26,8 @@
 import http from 'http';
 import { writeSync } from 'node:fs';
 import { LocalBackend } from '../mcp/local/local-backend.js';
+import { logger } from '../core/logger.js';
+import { cliInfo, cliWarn } from './cli-message.js';
 // ─── Text Formatters ──────────────────────────────────────────────────
 // Convert structured JSON results into compact, LLM-friendly text.
 // Design: minimize tokens, maximize actionability.
@@ -274,11 +276,16 @@ export async function evalServerCommand(options) {
     const backend = new LocalBackend();
     const ok = await backend.init();
     if (!ok) {
-        console.error('GitNexus eval-server: No indexed repositories found. Run: gitnexus analyze');
+        // Operator-actionable but the server cannot start; warn-level so log
+        // aggregators don't trip error alerts on a configuration miss. Use
+        // cliWarn so the diagnostic reaches stderr synchronously before
+        // process.exit() — direct logger.warn would be lost to the buffered
+        // pino destination on hard exit (skips beforeExit flush).
+        cliWarn('GitNexus eval-server: No indexed repositories found. Run: gitnexus analyze');
         process.exit(1);
     }
     const repos = await backend.listRepos();
-    console.error(`GitNexus eval-server: ${repos.length} repo(s) loaded: ${repos.map((r) => r.name).join(', ')}`);
+    logger.info({ repoCount: repos.length, repos: repos.map((r) => r.name) }, 'GitNexus eval-server: repos loaded');
     let idleTimer = null;
     function resetIdleTimer() {
         if (idleTimeoutSec <= 0)
@@ -286,7 +293,7 @@ export async function evalServerCommand(options) {
         if (idleTimer)
             clearTimeout(idleTimer);
         idleTimer = setTimeout(async () => {
-            console.error('GitNexus eval-server: Idle timeout reached, shutting down');
+            logger.info({ idleTimeoutSec }, 'GitNexus eval-server: idle timeout reached, shutting down');
             await backend.disconnect();
             process.exit(0);
         }, idleTimeoutSec * 1000);
@@ -351,16 +358,34 @@ export async function evalServerCommand(options) {
         }
     });
     server.listen(port, '127.0.0.1', () => {
-        console.error(`GitNexus eval-server: listening on http://127.0.0.1:${port}`);
-        console.error(`  POST /tool/query    — search execution flows`);
-        console.error(`  POST /tool/context  — 360-degree symbol view`);
-        console.error(`  POST /tool/impact   — blast radius analysis`);
-        console.error(`  POST /tool/cypher   — raw Cypher query`);
-        console.error(`  GET  /health        — health check`);
-        console.error(`  POST /shutdown      — graceful shutdown`);
+        // Plain-text banner for the human watching stderr; structured record
+        // for log aggregation (split into two so the user sees a real banner
+        // not `{"level":30,"msg":"...","port":4747,"endpoints":[...]}`).
+        const bannerLines = [
+            `GitNexus eval-server: listening on http://127.0.0.1:${port}`,
+            `  POST /tool/query    — search execution flows`,
+            `  POST /tool/context  — 360-degree symbol view`,
+            `  POST /tool/impact   — blast radius analysis`,
+            `  POST /tool/cypher   — raw Cypher query`,
+            `  GET  /health        — health check`,
+            `  POST /shutdown      — graceful shutdown`,
+        ];
         if (idleTimeoutSec > 0) {
-            console.error(`  Auto-shutdown after ${idleTimeoutSec}s idle`);
+            bannerLines.push(`  Auto-shutdown after ${idleTimeoutSec}s idle`);
         }
+        cliInfo(bannerLines.join('\n'), {
+            port,
+            host: '127.0.0.1',
+            idleTimeoutSec: idleTimeoutSec > 0 ? idleTimeoutSec : undefined,
+            endpoints: [
+                'POST /tool/query',
+                'POST /tool/context',
+                'POST /tool/impact',
+                'POST /tool/cypher',
+                'GET  /health',
+                'POST /shutdown',
+            ],
+        });
         try {
             // Use fd 1 directly — LadybugDB captures process.stdout (#324)
             writeSync(1, `GITNEXUS_EVAL_SERVER_READY:${port}\n`);
@@ -371,7 +396,7 @@ export async function evalServerCommand(options) {
     });
     resetIdleTimer();
     const shutdown = async () => {
-        console.error('GitNexus eval-server: shutting down...');
+        logger.info('GitNexus eval-server: shutting down...');
         await backend.disconnect();
         server.close();
         process.exit(0);

package/dist/cli/group.js

@@ -1,5 +1,6 @@
 // gitnexus/src/cli/group.ts
 import { createRequire } from 'node:module';
+import { logger } from '../core/logger.js';
 const _require = createRequire(import.meta.url);
 const yaml = _require('js-yaml');
 export function registerGroupCommands(program) {
@@ -42,7 +43,7 @@ export function registerGroupCommands(program) {
         const groupDir = getGroupDir(getDefaultGitnexusDir(), groupName);
         const config = await loadGroupConfig(groupDir);
         if (!(repoPath in config.repos)) {
-            console.error(`Repo path "${repoPath}" not found in group "${groupName}"`);
+            logger.error(`Repo path "${repoPath}" not found in group "${groupName}"`);
             process.exitCode = 1;
             return;
         }
@@ -202,7 +203,7 @@ export function registerGroupCommands(program) {
                 payload.includeTests = true;
             const raw = await backend.getGroupService().groupImpact(payload);
             if (raw && typeof raw === 'object' && 'error' in raw) {
-                console.error(String(raw.error));
+                logger.error(String(raw.error));
                 process.exitCode = 1;
                 return;
             }
@@ -280,7 +281,7 @@ export function registerGroupCommands(program) {
                 unmatchedOnly: Boolean(opts.unmatched),
             });
             if (raw && typeof raw === 'object' && 'error' in raw) {
-                console.error(String(raw.error));
+                logger.error(String(raw.error));
                 process.exitCode = 1;
                 return;
             }

package/dist/cli/mcp.js

@@ -37,11 +37,17 @@ export const mcpCommand = async () => {
     // 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([
+    // Dynamically import heavy backend modules AND the pino logger AFTER
+    // the sentinel installs. The logger is dynamic-imported (rather than
+    // static) to preserve the leaf-only static-import closure documented at
+    // the top of this file — `core/logger.js` itself doesn't write to
+    // stdout at module init, but transitive deps (pino, pino-pretty, the
+    // worker-thread transport) could in theory, and the import-closure
+    // regression test enforces the leaf invariant.
+    const [{ startMCPServer }, { LocalBackend }, { logger }] = await Promise.all([
         import('../mcp/server.js'),
         import('../mcp/local/local-backend.js'),
+        import('../core/logger.js'),
     ]);
     // Missing-optional-grammar warnings are intentionally NOT emitted here.
     // `gitnexus analyze` already warns at index time, filtered by the repo's
@@ -55,10 +61,12 @@ export const mcpCommand = async () => {
     await backend.init();
     const repos = await backend.listRepos();
     if (repos.length === 0) {
-        console.error('GitNexus: No indexed repos yet. Run `gitnexus analyze` in a git repo — the server will pick it up automatically.');
+        // Operator-actionable but the server still starts and serves; warn-level,
+        // not error. Tools will discover newly-analyzed repos via lazy refresh.
+        logger.warn('GitNexus: No indexed repos yet. Run `gitnexus analyze` in a git repo — the server will pick it up automatically.');
     }
     else {
-        console.error(`GitNexus: MCP server starting with ${repos.length} repo(s): ${repos.map((r) => r.name).join(', ')}`);
+        logger.info({ repoCount: repos.length, repos: repos.map((r) => r.name) }, 'GitNexus: MCP server starting');
     }
     // Start MCP server (serves all repos, discovers new ones lazily)
     await startMCPServer(backend);

package/dist/cli/optional-grammars.js

@@ -12,6 +12,7 @@
  * is unavailable instead of silently getting a degraded index.
  */
 import { createRequire } from 'module';
+import { cliWarn } from './cli-message.js';
 const _require = createRequire(import.meta.url);
 const OPTIONAL_GRAMMARS = [
     { name: 'tree-sitter-dart', pkg: 'tree-sitter-dart', extensions: ['.dart'] },
@@ -47,8 +48,12 @@ export function detectMissingOptionalGrammars() {
                 /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.`);
+                // "reinstall" recovery message that wouldn't actually help. cliWarn
+                // writes plain text to stderr AND tees a structured logger.warn
+                // record; the merged repo-wide ESLint pino-migration rule forbids
+                // direct `console.error` in CLI code (only `console.log` is allowed
+                // there for tool-data stdout output).
+                cliWarn(`GitNexus: optional grammar "${g.name}" is installed but failed to load (${msg.slice(0, 200)}). ${g.extensions.join('/')} files will not be parsed.`, { grammar: g.name, extensions: g.extensions, error: msg });
             }
             missing.push({ name: g.name, extensions: g.extensions });
         }
@@ -69,10 +74,14 @@ export function warnMissingOptionalGrammars(opts) {
     if (missing.length === 0)
         return;
     const ctx = opts?.context ? ` [${opts.context}]` : '';
+    // Hoist the optional set into a local so the closure below can narrow
+    // its type; references to `opts?.relevantExtensions` inside `.some()`
+    // lose the outer null-check narrowing and require a non-null assertion.
+    const relevantExtensions = opts?.relevantExtensions;
     for (const g of missing) {
-        if (opts?.relevantExtensions && !g.extensions.some((e) => opts.relevantExtensions.has(e))) {
+        if (relevantExtensions && !g.extensions.some((e) => 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.`);
+        cliWarn(`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.`, { grammar: g.name, extensions: g.extensions, context: opts?.context });
     }
 }

package/dist/cli/remove.js

@@ -26,6 +26,8 @@
  *     here there is no pipeline, so no conflation.)
  */
 import fs from 'fs/promises';
+import { logger } from '../core/logger.js';
+import { cliError } from './cli-message.js';
 import { readRegistry, resolveRegistryEntry, assertSafeStoragePath, unregisterRepo, RegistryNotFoundError, RegistryAmbiguousTargetError, UnsafeStoragePathError, } from '../storage/repo-manager.js';
 export const removeCommand = async (target, options) => {
     // Read the registry snapshot once and pass it to the resolver — this
@@ -41,14 +43,14 @@ export const removeCommand = async (target, options) => {
             // Idempotent: missing target is a no-op warning, not an error.
             // The `availableNames` hint comes from the error itself so users
             // can see what they might have meant.
-            console.warn(`Nothing to remove: ${err.message}`);
+            logger.warn(`Nothing to remove: ${err.message}`);
             return;
         }
         if (err instanceof RegistryAmbiguousTargetError) {
             // Duplicate aliases are allowed via --allow-duplicate-name (#829);
             // refuse to guess which one the user meant — surface the full list
             // and exit non-zero so scripts don't silently pick the wrong repo.
-            console.error(`Error: ${err.message}`);
+            cliError(`Error: ${err.message}`);
             process.exit(1);
         }
         throw err;
@@ -75,7 +77,7 @@ export const removeCommand = async (target, options) => {
     }
     catch (err) {
         if (err instanceof UnsafeStoragePathError) {
-            console.error(`Error: ${err.message}`);
+            cliError(`Error: ${err.message}`);
             process.exit(1);
         }
         throw err;
@@ -93,7 +95,8 @@ export const removeCommand = async (target, options) => {
         console.log(`   Storage: ${entry.storagePath}`);
     }
     catch (err) {
-        console.error(`Failed to remove ${entry.name}:`, err);
+        const msg = err instanceof Error ? err.message : String(err);
+        cliError(`Failed to remove ${entry.name}: ${msg}`, { err });
         process.exit(1);
     }
 };

package/dist/cli/serve.js

@@ -1,15 +1,25 @@
 import { createServer } from '../server/api.js';
-// Catch anything that would cause a silent exit
+import { logger, flushLoggerSync } from '../core/logger.js';
+import { cliError } from './cli-message.js';
+// Catch anything that would cause a silent exit. Pino v10's default
+// destination is `sync: false` (SonicBoom buffered) — call
+// `flushLoggerSync()` between the log and `process.exit(1)` so the crash
+// record is not lost to the unflushed buffer. Worker-thread transports
+// (pino-pretty under TTY) handle their own flush on process exit in v10,
+// so no separate `pino.final` integration is needed (the API was removed
+// in v10 because the transport architecture made it unnecessary).
+//
+// We pass the Error itself in `{ err }` so pino's built-in err serializer
+// captures `type`, `message`, and `stack` as structured fields.
 process.on('uncaughtException', (err) => {
-    console.error('\n[gitnexus serve] Uncaught exception:', err.message);
-    if (process.env.DEBUG)
-        console.error(err.stack);
+    logger.error({ err }, '[gitnexus serve] Uncaught exception');
+    flushLoggerSync();
     process.exit(1);
 });
 process.on('unhandledRejection', (reason) => {
-    console.error('\n[gitnexus serve] Unhandled rejection:', reason?.message || reason);
-    if (process.env.DEBUG)
-        console.error(reason?.stack);
+    const err = reason instanceof Error ? reason : new Error(String(reason));
+    logger.error({ err }, '[gitnexus serve] Unhandled rejection');
+    flushLoggerSync();
     process.exit(1);
 });
 export const serveCommand = async (options) => {
@@ -22,16 +32,24 @@ export const serveCommand = async (options) => {
         await createServer(port, host);
     }
     catch (err) {
-        console.error(`\nFailed to start GitNexus server:\n`);
-        console.error(`  ${err.message || err}\n`);
         if (err.code === 'EADDRINUSE') {
-            console.error(`  Port ${port} is already in use. Either:`);
-            console.error(`    1. Stop the other process using port ${port}`);
-            console.error(`    2. Use a different port: gitnexus serve --port 4748\n`);
+            cliError(`\nFailed to start GitNexus server:\n` +
+                `  ${err.message || err}\n\n` +
+                `  Port ${port} is already in use. Either:\n` +
+                `    1. Stop the other process using port ${port}\n` +
+                `    2. Use a different port: gitnexus serve --port 4748\n`, { code: err.code, port, host });
+        }
+        else {
+            cliError(`\nFailed to start GitNexus server:\n  ${err.message || err}\n`, {
+                code: err.code,
+                port,
+                host,
+            });
         }
         if (err.stack && process.env.DEBUG) {
-            console.error(err.stack);
+            logger.debug({ stack: err.stack }, 'serve start error stack');
         }
+        flushLoggerSync();
         process.exit(1);
     }
 };