gitnexus 1.6.9 → 1.6.10-aptos.0

package/dist/cli/doctor.d.ts

@@ -1,3 +1,4 @@
+import { type EmbeddingRuntimeResolution } from '../core/embeddings/runtime-install.js';
 export declare function displayWidth(value: string): number;
 export declare function padDisplayEnd(value: string, columns: number): string;
 /**
@@ -14,8 +15,25 @@ export declare function localEmbeddingDoctorStatus(opts: {
     httpMode: boolean;
     platform?: NodeJS.Platform;
     arch?: NodeJS.Architecture;
+    /** Injectable for tests; defaults to probing the real install. */
+    resolution?: EmbeddingRuntimeResolution | null;
+    /** Injectable for tests; defaults to this Node's registerHooks capability. */
+    prefixLoadable?: boolean;
 }): {
     status: string;
     detail: string | null;
 };
+/**
+ * Page-size lines for the `doctor` Runtime section (#1231). Pure so the
+ * warning gate can be unit-tested without running the whole command (the
+ * `localEmbeddingDoctorStatus` precedent above) — but takes the probed
+ * values as plain params rather than injectable probes, because `undefined`
+ * is a *meaningful* pageSize state here (probe unavailable / win32) and
+ * would collide with a "not provided → use default" DI convention.
+ *
+ * Returns 0 lines (page size unknown), 1 line (page size), or 2 lines
+ * (page size + non-4K warning when the installed @ladybugdb/core does not
+ * detect the OS page size at runtime).
+ */
+export declare function pageSizeDoctorLines(pageSize: number | undefined, ladybugVersion: string | undefined): string[];
 export declare const doctorCommand: () => Promise<void>;

package/dist/cli/doctor.js

@@ -1,9 +1,12 @@
 import { getRuntimeCapabilities, getRuntimeFingerprint } from '../core/platform/capabilities.js';
 import { resolveEmbeddingConfig } from '../core/embeddings/config.js';
 import { isHttpMode } from '../core/embeddings/http-client.js';
-import { getLocalEmbeddingRuntimeBlocker } from '../core/embeddings/runtime-support.js';
+import { getLocalEmbeddingRuntimeBlocker, localEmbeddingPrefixUnloadableMessage, localEmbeddingStackMissingMessage, } from '../core/embeddings/runtime-support.js';
+import { isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
 import { cudaRedirectDoctorStatus } from '../core/embeddings/onnxruntime-node-resolver.js';
-import { checkLbugNative } from '../core/lbug/native-check.js';
+import { checkLbugNative, probeFtsExtensionLoad, probeVectorExtensionLoad, } from '../core/lbug/native-check.js';
+import { getOsPageSize, isPageSizeAwareLadybug } from '../core/lbug/lbug-config.js';
+import { diagnoseExtensionLoad } from '../core/lbug/extension-load-error.js';
 import { getExtensionInstallPolicy } from '../core/lbug/extension-loader.js';
 import { t } from './i18n/index.js';
 function isCombiningMark(codePoint) {
@@ -64,8 +67,54 @@ export function localEmbeddingDoctorStatus(opts) {
     if (blocker) {
         return { status: `✗ local embeddings unavailable on ${platform}/${arch}`, detail: blocker };
     }
+    // The stack is an optionalDependency — npm prunes it when onnxruntime-node's
+    // postinstall can't download its CUDA binaries (proxy/firewall, #2370).
+    const resolution = opts.resolution !== undefined ? opts.resolution : resolveEmbeddingRuntime();
+    if (resolution === null) {
+        return {
+            status: '✗ optional embedding stack not installed',
+            detail: localEmbeddingStackMissingMessage(),
+        };
+    }
+    // A prefix-sourced stack needs module.registerHooks to load; on Node < 22.15 /
+    // < 23.5 it is present but unreachable (#2372). Report loadability, not bare
+    // presence, so the diagnostic stops claiming a ✓ the loader can't honour.
+    const prefixLoadable = opts.prefixLoadable ?? isPrefixRuntimeLoadable();
+    if (resolution.source === 'runtime-prefix' && !prefixLoadable) {
+        return {
+            status: '✗ embedding stack installed in the prefix but not loadable on this Node',
+            detail: localEmbeddingPrefixUnloadableMessage(),
+        };
+    }
     return { status: '✓ local embeddings supported', detail: null };
 }
+/**
+ * Page-size lines for the `doctor` Runtime section (#1231). Pure so the
+ * warning gate can be unit-tested without running the whole command (the
+ * `localEmbeddingDoctorStatus` precedent above) — but takes the probed
+ * values as plain params rather than injectable probes, because `undefined`
+ * is a *meaningful* pageSize state here (probe unavailable / win32) and
+ * would collide with a "not provided → use default" DI convention.
+ *
+ * Returns 0 lines (page size unknown), 1 line (page size), or 2 lines
+ * (page size + non-4K warning when the installed @ladybugdb/core does not
+ * detect the OS page size at runtime).
+ */
+export function pageSizeDoctorLines(pageSize, ladybugVersion) {
+    if (pageSize === undefined)
+        return [];
+    const lines = [`  ${padDisplayEnd('page size', 10)}${pageSize}`];
+    if (pageSize > 4096 && !isPageSizeAwareLadybug(ladybugVersion)) {
+        // Don't assert "< 0.18.0" as fact when the version is unresolvable
+        // (#2424 review R2) — name the unknown state instead.
+        const versionClause = ladybugVersion === undefined
+            ? 'an unknown @ladybugdb/core version (may predate 0.18.0)'
+            : `@ladybugdb/core < 0.18.0`;
+        lines.push(`  ${padDisplayEnd('', 10)}⚠ non-4K page size with ${versionClause} — ` +
+            `'gitnexus analyze' may fail during COPY (#1231). Upgrade gitnexus (npm install -g gitnexus@latest).`);
+    }
+    return lines;
+}
 export const doctorCommand = async () => {
     const fingerprint = getRuntimeFingerprint();
     const capabilities = getRuntimeCapabilities();
@@ -76,6 +125,13 @@ export const doctorCommand = async () => {
     console.log(`  ${label('doctor.labels.node', 10)}${fingerprint.node}`);
     console.log(`  ${label('doctor.labels.gitnexus', 10)}${fingerprint.gitnexus}`);
     console.log(`  ${label('doctor.labels.ladybugdb', 10)}${fingerprint.ladybugdb ?? 'unknown'}`);
+    // OS page size next to the LadybugDB version because the two interact:
+    // @ladybugdb/core < 0.18.0 assumed 4 KiB pages in its buffer manager and
+    // crashes mid-COPY on 16 KiB/64 KiB-page kernels (#1231). Literal label
+    // (like the 'native' line below) to avoid adding i18n keys.
+    for (const line of pageSizeDoctorLines(getOsPageSize(), fingerprint.ladybugdb)) {
+        console.log(line);
+    }
     const nativeCheck = checkLbugNative();
     if (nativeCheck.ok) {
         console.log(`  ${padDisplayEnd('native', 10)}✓ lbugjs.node loaded`);
@@ -88,9 +144,44 @@ export const doctorCommand = async () => {
     console.log('');
     console.log(t('doctor.capabilities'));
     console.log(`  ${label('doctor.labels.graphStore', 18)}${capabilities.graph}`);
-    console.log(`  ${label('doctor.labels.fullTextSearch', 18)}${capabilities.fts}`);
-    console.log(`  ${label('doctor.labels.vectorIndex', 18)}${capabilities.vector}`);
-    console.log(`  ${label('doctor.labels.semanticMode', 18)}${capabilities.semanticMode}`);
+    // Live LOAD probe, not the static platform capability — the static value
+    // said "available" while analyze failed to load the extension (#2374).
+    const ftsProbe = nativeCheck.ok
+        ? await probeFtsExtensionLoad()
+        : { loaded: false, reason: 'LadybugDB native module (lbugjs.node) failed to load' };
+    console.log(`  ${label('doctor.labels.fullTextSearch', 18)}${ftsProbe.loaded ? 'available' : 'unavailable'}`);
+    if (!ftsProbe.loaded && ftsProbe.reason) {
+        console.log(`  ${padDisplayEnd('', 18)}${ftsProbe.reason}`);
+        // Add an actionable remedy for recognized failure classes (#2374). The
+        // Windows missing-dependency case is the point of this: the raw error 126
+        // ("specified module could not be found") is opaque, so name the fix (VC++
+        // redist, then OpenSSL) instead of leaving the user to reinstall in vain.
+        // `unknown`'s remedy is "run doctor", which would be circular here.
+        const { kind, remedy } = diagnoseExtensionLoad(ftsProbe.reason);
+        if (kind !== 'unknown') {
+            console.log(`  ${padDisplayEnd('', 18)}${remedy}`);
+        }
+    }
+    // Live LOAD probe for VECTOR too (#2623). The static capability is just
+    // `platform !== 'win32'`, so it printed "available" on the very machines
+    // where analyze was failing to load the extension — the same contradiction
+    // #2374 fixed for FTS above, and exactly what #2623's reporter saw while
+    // every incremental analyze died on an unloaded VECTOR extension.
+    const vectorProbe = nativeCheck.ok
+        ? await probeVectorExtensionLoad()
+        : { loaded: false, reason: 'LadybugDB native module (lbugjs.node) failed to load' };
+    console.log(`  ${label('doctor.labels.vectorIndex', 18)}${vectorProbe.loaded ? 'available' : 'unavailable'}`);
+    if (!vectorProbe.loaded && vectorProbe.reason) {
+        console.log(`  ${padDisplayEnd('', 18)}${vectorProbe.reason}`);
+        const { kind, remedy } = diagnoseExtensionLoad(vectorProbe.reason, 'VECTOR');
+        if (kind !== 'unknown') {
+            console.log(`  ${padDisplayEnd('', 18)}${remedy}`);
+        }
+    }
+    // Semantic mode follows the probe, not the platform: without a loadable
+    // VECTOR extension the index can be neither built nor queried, so search is
+    // really on exact scan no matter what the platform would allow.
+    console.log(`  ${label('doctor.labels.semanticMode', 18)}${vectorProbe.loaded ? capabilities.semanticMode : 'exact-scan'}`);
     // Surface the optional-extension install policy so offline users can see
     // whether analyze/query will reach the network (extension.ladybugdb.com).
     // Literal label (like the 'native' line) to avoid adding i18n keys.

package/dist/cli/editor-targets.d.ts

@@ -15,7 +15,7 @@
  * implementations remain behaviourally symmetrical on top of this shared
  * structure.
  */
-export type EditorId = 'cursor' | 'claude' | 'antigravity' | 'opencode' | 'codex';
+export type EditorId = 'cursor' | 'claude' | 'antigravity' | 'opencode' | 'codebuddy' | 'qoder' | 'codex';
 /** An editor whose MCP config is a JSONC document (server keyed by name). */
 export interface McpJsoncTarget {
     id: EditorId;
@@ -29,6 +29,14 @@ export interface McpJsoncTarget {
      * without either side needing a cast.
      */
     keyPath: string[];
+    /**
+     * Older config locations the editor still reads when `file` is absent
+     * (CodeBuddy reads only the FIRST existing file in its priority chain).
+     * Setup writes into the first existing candidate of [file, ...legacyFiles]
+     * so it never shadows a user's servers living in a deprecated file;
+     * uninstall sweeps all of them.
+     */
+    legacyFiles?: string[];
 }
 /** Codex stores MCP config as a TOML table, not JSONC. */
 export interface CodexMcpTarget {
@@ -58,7 +66,7 @@ export interface HookTarget {
     scriptDir: string;
 }
 export interface EditorTargets {
-    /** JSONC-format MCP entries: Cursor, Claude Code, Antigravity, OpenCode. */
+    /** JSONC-format MCP entries: Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder. */
     mcpJsonc: McpJsoncTarget[];
     /** Codex MCP (TOML). */
     codex: CodexMcpTarget;
@@ -80,6 +88,13 @@ export declare function mcpTarget(id: EditorId, home?: string): McpJsoncTarget;
 export declare function skillTarget(id: EditorId, home?: string): SkillTarget;
 /** Look up a single hook target by editor id (throws if unknown). */
 export declare function hookTarget(id: EditorId, home?: string): HookTarget;
+/**
+ * True when err is a Node fs error with code ENOENT (file/dir absent).
+ * Shared by setup and uninstall: both must swallow ONLY absence when reading
+ * editor configs — any other read/stat failure (EACCES, EIO) is surfaced so an
+ * unreadable config is never treated as empty and rewritten gitnexus-only.
+ */
+export declare function isEnoent(err: unknown): boolean;
 /**
  * Detect indentation style from file content so JSONC edits preserve the file's
  * existing formatting. Shared by setup (writes) and uninstall (removes).

package/dist/cli/editor-targets.js

@@ -50,6 +50,26 @@ export function getEditorTargets(home = os.homedir()) {
             // OpenCode nests servers under `mcp`, not `mcpServers`.
             keyPath: ['mcp', 'gitnexus'],
         },
+        {
+            id: 'codebuddy',
+            label: 'CodeBuddy',
+            // Recommended user-scope path per https://www.codebuddy.ai/docs/cli/mcp;
+            // CodeBuddy reads only the first existing file in this priority chain.
+            file: path.join(home, '.codebuddy', '.mcp.json'),
+            legacyFiles: [
+                path.join(home, '.codebuddy', 'mcp.json'), // deprecated
+                path.join(home, '.codebuddy.json'), // legacy
+            ],
+            keyPath: ['mcpServers', 'gitnexus'],
+        },
+        {
+            id: 'qoder',
+            label: 'Qoder',
+            // Qoder's documented user-scope MCP config (https://docs.qoder.com/cli/using-cli);
+            // the IDE manages MCP via its Settings UI with no documented file path.
+            file: path.join(home, '.qoder.json'),
+            keyPath: ['mcpServers', 'gitnexus'],
+        },
     ];
     const codex = {
         id: 'codex',
@@ -66,6 +86,10 @@ export function getEditorTargets(home = os.homedir()) {
         },
         { id: 'cursor', label: 'Cursor', dir: path.join(home, '.cursor', 'skills') },
         { id: 'opencode', label: 'OpenCode', dir: path.join(home, '.config', 'opencode', 'skills') },
+        { id: 'codebuddy', label: 'CodeBuddy', dir: path.join(home, '.codebuddy', 'skills') },
+        // Qoder skills live at ~/.qoder/skills/{name}/SKILL.md
+        // (https://docs.qoder.com/extensions/skills).
+        { id: 'qoder', label: 'Qoder', dir: path.join(home, '.qoder', 'skills') },
         // Codex reads skills from ~/.agents/skills (not ~/.codex).
         { id: 'codex', label: 'Codex', dir: path.join(home, '.agents', 'skills') },
     ];
@@ -78,6 +102,17 @@ export function getEditorTargets(home = os.homedir()) {
             needle: 'gitnexus-hook',
             scriptDir: path.join(home, '.claude', 'hooks', 'gitnexus'),
         },
+        {
+            id: 'codex',
+            label: 'Codex',
+            // Codex hooks use Claude Code's exact {hooks: {Event: [...]}} JSON shape
+            // and hookSpecificOutput response contract, in a dedicated hooks.json
+            // (https://developers.openai.com/codex/hooks).
+            settingsFile: path.join(home, '.codex', 'hooks.json'),
+            events: ['PreToolUse', 'PostToolUse'],
+            needle: 'gitnexus-hook',
+            scriptDir: path.join(home, '.codex', 'hooks', 'gitnexus'),
+        },
         {
             id: 'antigravity',
             label: 'Antigravity',
@@ -110,6 +145,15 @@ export function hookTarget(id, home) {
         throw new Error(`No hook target for editor "${id}"`);
     return t;
 }
+/**
+ * True when err is a Node fs error with code ENOENT (file/dir absent).
+ * Shared by setup and uninstall: both must swallow ONLY absence when reading
+ * editor configs — any other read/stat failure (EACCES, EIO) is surfaced so an
+ * unreadable config is never treated as empty and rewritten gitnexus-only.
+ */
+export function isEnoent(err) {
+    return err?.code === 'ENOENT';
+}
 /**
  * Detect indentation style from file content so JSONC edits preserve the file's
  * existing formatting. Shared by setup (writes) and uninstall (removes).

package/dist/cli/embeddings.d.ts

@@ -0,0 +1,12 @@
+export interface EmbeddingsInstallOptions {
+    cuda?: boolean;
+    force?: boolean;
+}
+/**
+ * `gitnexus embeddings install [--cuda] [--force]` — fetch the optional local
+ * embedding stack on demand (#2370). Goes through the user's npm registry
+ * config (mirrors/proxies apply); with --cuda it additionally runs
+ * onnxruntime-node's postinstall to download the CUDA GPU binaries from NuGet
+ * (set GLOBAL_AGENT_HTTPS_PROXY behind a proxy).
+ */
+export declare const embeddingsInstallCommand: (options?: EmbeddingsInstallOptions) => Promise<void>;

package/dist/cli/embeddings.js

@@ -0,0 +1,49 @@
+import { cliError, cliInfo, cliWarn } from './cli-message.js';
+import { getEmbeddingRuntimeDir, getEmbeddingStackSpecs, installEmbeddingRuntime, isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
+import { localEmbeddingPrefixUnloadableMessage } from '../core/embeddings/runtime-support.js';
+/**
+ * `gitnexus embeddings install [--cuda] [--force]` — fetch the optional local
+ * embedding stack on demand (#2370). Goes through the user's npm registry
+ * config (mirrors/proxies apply); with --cuda it additionally runs
+ * onnxruntime-node's postinstall to download the CUDA GPU binaries from NuGet
+ * (set GLOBAL_AGENT_HTTPS_PROXY behind a proxy).
+ */
+export const embeddingsInstallCommand = async (options = {}) => {
+    const resolved = resolveEmbeddingRuntime();
+    if (resolved?.source === 'package' && !options.force) {
+        cliInfo('The embedding stack is already installed with gitnexus itself — nothing to do.\n' +
+            '(Use --force to install a copy into the runtime prefix anyway.)');
+        return;
+    }
+    const specs = Object.entries(getEmbeddingStackSpecs())
+        .map(([name, spec]) => `${name}@${spec}`)
+        .join(', ');
+    cliInfo(`Installing ${specs} into ${getEmbeddingRuntimeDir()} …`);
+    cliInfo(options.cuda
+        ? 'CUDA mode: onnxruntime-node will download GPU binaries from NuGet ' +
+            '(set GLOBAL_AGENT_HTTPS_PROXY=<proxy-url> behind a proxy).'
+        : 'CPU mode: install scripts are skipped — only your npm registry is contacted.');
+    try {
+        await installEmbeddingRuntime({ cuda: options.cuda, onOutput: (line) => cliInfo(`  ${line}`) });
+    }
+    catch (err) {
+        cliError(`${err instanceof Error ? err.message : String(err)}\n`, {
+            recoveryHint: 'local-embedding-stack-missing',
+        });
+        process.exitCode = 1;
+        return;
+    }
+    const postInstall = resolveEmbeddingRuntime();
+    if (postInstall === null) {
+        cliInfo('✗ Install completed but the stack still does not resolve — check the output above.');
+        process.exitCode = 1;
+        return;
+    }
+    if (postInstall.source === 'runtime-prefix' && !isPrefixRuntimeLoadable()) {
+        // The packages are in the prefix, but this Node has no module.registerHooks
+        // to load them — don't claim readiness the loader can't honour.
+        cliWarn(`${localEmbeddingPrefixUnloadableMessage()}\n`);
+        return;
+    }
+    cliInfo('✓ Embedding runtime installed. `gitnexus analyze --embeddings` is ready.');
+};

package/dist/cli/eval-server.d.ts

@@ -16,7 +16,8 @@
  * Usage:
  *   gitnexus eval-server                        # default port 4848, binds 127.0.0.1
  *   gitnexus eval-server --port 4848            # explicit port
- *   gitnexus eval-server --host 0.0.0.0         # reachable from other VMs / containers
+ *   GITNEXUS_AUTH_TOKEN=... gitnexus eval-server --host 0.0.0.0
+ *   GITNEXUS_AUTH_TOKEN=... gitnexus eval-server --host devbox.local
  *   gitnexus eval-server --idle-timeout 300     # auto-shutdown after 300s idle
  *
  * READY signal format: GITNEXUS_EVAL_SERVER_READY:<host>:<port>
@@ -42,6 +43,27 @@ export interface EvalServerOptions {
  * address (127.0.0.1 or ::1) at bind time rather than forcing IPv4.
  */
 export declare function validateHost(raw: string): string | null;
+type EvalServerHostLookup = (hostname: string) => Promise<string>;
+/** Resolve a DNS bind name once so validation and listen() use the same concrete address. */
+export declare function resolveEvalServerBindHost(raw: string, resolveHostname?: EvalServerHostLookup): Promise<string | null>;
+/** Resolve the bearer token from the shell, then .env.local, then .env. */
+export declare function resolveEvalServerAuthToken(env: NodeJS.ProcessEnv, cwd?: string): string | undefined;
+/** True only for literal loopback addresses; DNS names are resolved before this check. */
+export declare function isEvalServerLoopbackHost(host: string): boolean;
+/**
+ * Resolve the bearer token for a concrete bind host. An unreadable `.env` /
+ * `.env.local` only matters when the binding actually requires a token, so
+ * loopback binds degrade to a warning instead of refusing to start; any
+ * non-loopback bind keeps the fail-closed error.
+ */
+export declare function resolveEvalServerAuthTokenForHost(host: string, env: NodeJS.ProcessEnv, cwd?: string): {
+    token?: string;
+    warning?: string;
+};
+/** Refuse exposure of the eval-server query surface without authentication. */
+export declare function assertSecureEvalServerBinding(host: string, authToken: string | undefined): void;
+/** Validate the exact Bearer header while keeping token comparison constant-time. */
+export declare function isEvalServerBearerAuthorized(authorization: string | string[] | undefined, authToken: string | undefined): boolean;
 export declare function formatQueryResult(result: any): string;
 export declare function formatContextResult(result: any): string;
 export declare function formatImpactResult(result: any): string;

package/dist/cli/eval-server.js

@@ -16,7 +16,8 @@
  * Usage:
  *   gitnexus eval-server                        # default port 4848, binds 127.0.0.1
  *   gitnexus eval-server --port 4848            # explicit port
- *   gitnexus eval-server --host 0.0.0.0         # reachable from other VMs / containers
+ *   GITNEXUS_AUTH_TOKEN=... gitnexus eval-server --host 0.0.0.0
+ *   GITNEXUS_AUTH_TOKEN=... gitnexus eval-server --host devbox.local
  *   gitnexus eval-server --idle-timeout 300     # auto-shutdown after 300s idle
  *
  * READY signal format: GITNEXUS_EVAL_SERVER_READY:<host>:<port>
@@ -30,8 +31,11 @@
  */
 import http from 'http';
 import crypto from 'node:crypto';
+import { lookup } from 'node:dns/promises';
 import { isIPv4, isIPv6 } from 'node:net';
-import { writeSync } from 'node:fs';
+import { readFileSync, writeSync } from 'node:fs';
+import path from 'node:path';
+import { parseEnv } from 'node:util';
 import { LocalBackend, } from '../mcp/local/local-backend.js';
 import { logger } from '../core/logger.js';
 import { cliInfo, cliWarn, cliError } from './cli-message.js';
@@ -50,6 +54,86 @@ export function validateHost(raw) {
         return raw;
     return null;
 }
+function isHostname(raw) {
+    if (!raw || raw.length > 253 || /^[\d.]+$/.test(raw))
+        return false;
+    return raw
+        .split('.')
+        .every((label) => label.length > 0 &&
+        label.length <= 63 &&
+        /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(label));
+}
+/** Resolve a DNS bind name once so validation and listen() use the same concrete address. */
+export async function resolveEvalServerBindHost(raw, resolveHostname = async (hostname) => (await lookup(hostname, { family: 4 })).address) {
+    const directHost = validateHost(raw);
+    if (directHost && directHost !== 'localhost')
+        return directHost;
+    if (directHost !== 'localhost' && !isHostname(raw))
+        return null;
+    try {
+        const address = await resolveHostname(raw);
+        return isIPv4(address) ? address : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readAuthTokenFile(filePath) {
+    try {
+        return parseEnv(readFileSync(filePath, 'utf8')).GITNEXUS_AUTH_TOKEN?.trim() || undefined;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw new Error(`Unable to read eval-server authentication from ${filePath}`, { cause: error });
+    }
+}
+/** Resolve the bearer token from the shell, then .env.local, then .env. */
+export function resolveEvalServerAuthToken(env, cwd = process.cwd()) {
+    if (Object.hasOwn(env, 'GITNEXUS_AUTH_TOKEN')) {
+        return env.GITNEXUS_AUTH_TOKEN?.trim() || undefined;
+    }
+    return (readAuthTokenFile(path.join(cwd, '.env.local')) ?? readAuthTokenFile(path.join(cwd, '.env')));
+}
+/** True only for literal loopback addresses; DNS names are resolved before this check. */
+export function isEvalServerLoopbackHost(host) {
+    return host === 'localhost' || host === '::1' || (isIPv4(host) && host.startsWith('127.'));
+}
+/**
+ * Resolve the bearer token for a concrete bind host. An unreadable `.env` /
+ * `.env.local` only matters when the binding actually requires a token, so
+ * loopback binds degrade to a warning instead of refusing to start; any
+ * non-loopback bind keeps the fail-closed error.
+ */
+export function resolveEvalServerAuthTokenForHost(host, env, cwd = process.cwd()) {
+    try {
+        return { token: resolveEvalServerAuthToken(env, cwd) };
+    }
+    catch (error) {
+        if (isEvalServerLoopbackHost(host)) {
+            const reason = error instanceof Error ? error.message : String(error);
+            return { warning: `${reason} Continuing without authentication on loopback host ${host}.` };
+        }
+        throw error;
+    }
+}
+/** Refuse exposure of the eval-server query surface without authentication. */
+export function assertSecureEvalServerBinding(host, authToken) {
+    if (!authToken && !isEvalServerLoopbackHost(host)) {
+        throw new Error(`Refusing to start eval-server on non-loopback host ${host} without authentication. ` +
+            'Set GITNEXUS_AUTH_TOKEN or bind to 127.0.0.1, localhost, or ::1.');
+    }
+}
+/** Validate the exact Bearer header while keeping token comparison constant-time. */
+export function isEvalServerBearerAuthorized(authorization, authToken) {
+    if (!authToken)
+        return true;
+    const expected = Buffer.from(`Bearer ${authToken}`, 'utf8');
+    const supplied = typeof authorization === 'string' ? Buffer.from(authorization, 'utf8') : null;
+    const sameLength = supplied?.length === expected.length;
+    const candidate = sameLength && supplied ? supplied : Buffer.alloc(expected.length);
+    return crypto.timingSafeEqual(candidate, expected) && sameLength;
+}
 // ─── Text Formatters ──────────────────────────────────────────────────
 // Convert structured JSON results into compact, LLM-friendly text.
 // Design: minimize tokens, maximize actionability.
@@ -545,15 +629,38 @@ export async function evalServerCommand(options) {
     const port = parseInt(options?.port || '4848');
     const idleTimeoutSec = parseInt(options?.idleTimeout || '0');
     const rawHost = options?.host ?? '127.0.0.1';
-    const host = validateHost(rawHost);
+    const host = await resolveEvalServerBindHost(rawHost);
     if (!host) {
         cliError(`Invalid --host value "${rawHost}":\n` +
-            `  Must be an IP address or "localhost".\n\n` +
+            `  Must be an IP address or a hostname that resolves to a local IPv4 address.\n\n` +
             `  Examples:\n` +
             `    gitnexus eval-server --host 127.0.0.1    (loopback only, default)\n` +
-            `    gitnexus eval-server --host 0.0.0.0      (all network interfaces)\n` +
-            `    gitnexus eval-server --host 192.168.1.5  (specific interface)\n` +
-            `    gitnexus eval-server --host localhost     (OS-resolved loopback)\n`, { flag: '--host', value: rawHost });
+            `    GITNEXUS_AUTH_TOKEN=... gitnexus eval-server --host 0.0.0.0\n` +
+            `    GITNEXUS_AUTH_TOKEN=... gitnexus eval-server --host 192.168.1.5\n` +
+            `    gitnexus eval-server --host localhost     (resolved IPv4 loopback)\n` +
+            `    GITNEXUS_AUTH_TOKEN=... gitnexus eval-server --host devbox.local\n`, { flag: '--host', value: rawHost });
+        process.exit(1);
+    }
+    let authToken;
+    try {
+        const resolved = resolveEvalServerAuthTokenForHost(host, process.env);
+        authToken = resolved.token;
+        if (resolved.warning)
+            cliWarn(resolved.warning);
+    }
+    catch (error) {
+        cliError(error instanceof Error
+            ? error.message
+            : 'Unable to read eval-server authentication configuration.');
+        process.exit(1);
+    }
+    try {
+        assertSecureEvalServerBinding(host, authToken);
+    }
+    catch (error) {
+        cliError(error instanceof Error ? error.message : 'Refusing insecure eval-server binding.', {
+            host,
+        });
         process.exit(1);
     }
     const backend = new LocalBackend();
@@ -589,6 +696,13 @@ export async function evalServerCommand(options) {
     // shut down locally without a token.)
     const shutdownToken = crypto.randomBytes(24).toString('hex');
     const server = http.createServer(async (req, res) => {
+        if (!isEvalServerBearerAuthorized(req.headers.authorization, authToken)) {
+            res.setHeader('Content-Type', 'application/json');
+            res.setHeader('WWW-Authenticate', 'Bearer');
+            res.writeHead(401);
+            res.end(JSON.stringify({ error: 'Unauthorized' }));
+            return;
+        }
         resetIdleTimer();
         try {
             // Health check
@@ -680,7 +794,7 @@ export async function evalServerCommand(options) {
                         `  Run \`ip addr\` (Linux) or \`ipconfig\` (Windows) to list available addresses.\n\n`) +
                 `  Common fixes:\n` +
                 `    gitnexus eval-server --host 127.0.0.1  (loopback, this machine only)\n` +
-                `    gitnexus eval-server --host 0.0.0.0    (all interfaces, reachable from other VMs)\n`, { code: err.code, port, host });
+                `    GITNEXUS_AUTH_TOKEN=... gitnexus eval-server --host 0.0.0.0\n`, { code: err.code, port, host });
         }
         else if (err.code === 'EACCES') {
             cliError(`\nGitNexus eval-server failed to start:\n` +
@@ -723,6 +837,9 @@ export async function evalServerCommand(options) {
             `  GET  /health        — health check`,
             `  POST /shutdown      — graceful shutdown`,
         ];
+        if (authToken) {
+            bannerLines.push('  Bearer authentication enabled');
+        }
         if (idleTimeoutSec > 0) {
             bannerLines.push(`  Auto-shutdown after ${idleTimeoutSec}s idle`);
         }
@@ -730,6 +847,7 @@ export async function evalServerCommand(options) {
             port: boundPort,
             host,
             idleTimeoutSec: idleTimeoutSec > 0 ? idleTimeoutSec : undefined,
+            authEnabled: Boolean(authToken),
             endpoints: [
                 'POST /tool/query',
                 'POST /tool/context',

package/dist/cli/help-i18n.js

@@ -17,6 +17,8 @@ const COMMAND_DESCRIPTION_KEYS = {
     list: 'help.command.list.description',
     status: 'help.command.status.description',
     doctor: 'help.command.doctor.description',
+    embeddings: 'help.command.embeddings.description',
+    'embeddings install': 'help.command.embeddings.install.description',
     clean: 'help.command.clean.description',
     remove: 'help.command.remove.description',
     wiki: 'help.command.wiki.description',
@@ -73,6 +75,7 @@ const OPTION_DESCRIPTION_KEYS = {
     'mcp|--auth-token <token>': 'help.option.mcp.authToken',
     'serve|-p, --port <port>': 'help.option.port',
     'serve|--host <host>': 'help.option.serve.host',
+    'status|--json': 'help.option.status.json',
     'uninstall|-f, --force': 'help.option.uninstall.force',
     'clean|-f, --force': 'help.option.force.confirmation',
     'clean|--all': 'help.option.clean.all',
@@ -90,6 +93,7 @@ const OPTION_DESCRIPTION_KEYS = {
     'wiki|--concurrency <n>': 'help.option.wiki.concurrency',
     'wiki|--timeout <seconds>': 'help.option.wiki.timeout',
     'wiki|--retries <n>': 'help.option.wiki.retries',
+    'wiki|--allow-insecure-connection <host>': 'help.option.wiki.allowInsecureConnection',
     'wiki|--gist': 'help.option.wiki.gist',
     'wiki|-v, --verbose': 'help.option.verbose',
     'wiki|--review': 'help.option.wiki.review',
@@ -143,6 +147,8 @@ const OPTION_DESCRIPTION_KEYS = {
     'eval-server|-p, --port <port>': 'help.option.port',
     'eval-server|--host <host>': 'help.option.evalServer.host',
     'eval-server|--idle-timeout <seconds>': 'help.option.evalServer.idleTimeout',
+    'embeddings install|--cuda': 'help.option.embeddings.install.cuda',
+    'embeddings install|--force': 'help.option.embeddings.install.force',
     'group create|--force': 'help.option.group.create.force',
     'group sync|--skip-embeddings': 'help.option.group.sync.skipEmbeddings',
     'group sync|--exact-only': 'help.option.group.sync.exactOnly',