gitnexus 1.6.10-rc.2 → 1.6.10-rc.4

package/README.md

@@ -220,6 +220,7 @@ gitnexus analyze [path]          # Index a repository (or update stale index)
 gitnexus analyze --repair-fts    # Fast path: rebuild/verify only FTS indexes on existing index data
 gitnexus analyze --force         # Full rebuild: re-parse + graph rebuild + FTS rebuild
 gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
+gitnexus embeddings install      # Fetch the optional local embedding stack on demand (--cuda, --force)
 gitnexus analyze --skills        # Generate repo-specific skill files from detected communities
 gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
 gitnexus analyze --skip-skills   # Skip installing .claude/skills/gitnexus/ skill files
@@ -420,16 +421,37 @@ If `npm install -g gitnexus` fails on native modules:
 npm install -g gitnexus
 ```
 
+### Installation fails behind an HTTP proxy (`onnxruntime-node` postinstall)
+
+`onnxruntime-node`'s postinstall downloads optional CUDA GPU binaries from `api.nuget.org` — outside the npm registry, so registry mirrors don't cover it, and its proxy layer (`global-agent`) ignores the standard `HTTP_PROXY`/`HTTPS_PROXY` variables and rejects 302 redirects ([#2370](https://github.com/abhigyanpatwari/GitNexus/issues/2370)).
+
+Since the packages are optional dependencies, a failed download no longer breaks `npm install -g gitnexus` — npm skips the embedding stack and everything else works. The stack then **self-heals on demand**: the first `gitnexus analyze --embeddings` (or an explicit `gitnexus embeddings install`) fetches it through your configured npm registry — mirrors and proxies apply, no NuGet download involved — into `~/.gitnexus/embedding-runtime`.
+
+```bash
+# heal a proxy-degraded install manually (CPU embeddings; registry-only)
+gitnexus embeddings install
+
+# reinstall into the prefix even when the stack already resolves
+gitnexus embeddings install --force
+
+# CUDA GPU hosts: also fetch GPU binaries (NuGet; set the proxy global-agent reads)
+GLOBAL_AGENT_HTTPS_PROXY=<proxy-url> gitnexus embeddings install --cuda
+```
+
+The prefix defaults to `~/.gitnexus/embedding-runtime`; set `GITNEXUS_EMBEDDING_RUNTIME_DIR` to install it elsewhere (e.g. a writable path in a container).
+
+> **Node requirement for the on-demand prefix:** the self-heal loads the prefixed packages via `module.registerHooks`, available on Node **≥ 22.15** (on the 22.x line) or **≥ 23.5** (on the 23.x line). On an older Node the packages install but can't be loaded from the prefix — reinstall them into the install itself instead (works on every supported Node): `ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus` (Windows: `set ONNXRUNTIME_NODE_INSTALL=skip && npm install -g gitnexus`). Skipping only the CUDA download keeps full CPU embeddings (CPU embeddings don't need it). Check the result any time with `gitnexus doctor` (Embeddings → Support line).
+
 ### Analyze warns about unavailable FTS or VECTOR extensions
 
-GitNexus uses optional DuckDB extensions for BM25 and vector search. The `gitnexus serve` and MCP read paths only ever try to `LOAD` the extensions — they never block on a network install. The `analyze` command, by default, attempts one bounded out-of-process `INSTALL` if `LOAD` fails and proceeds even when that install times out, so the index is always written to disk; BM25/vector search degrade gracefully until the extensions become available.
+GitNexus uses optional DuckDB extensions for BM25 and vector search. The `gitnexus serve` and MCP read paths only ever try to `LOAD` the extensions — they never block on a network install. The `analyze` command, by default, attempts one bounded out-of-process install if `LOAD` fails (a plain `INSTALL` to download a missing extension, escalating to `FORCE INSTALL` only when the `LOAD` error shows the existing file is broken or truncated, so a permanent non-file failure does not re-download on every run) and proceeds even when that install times out, so the index is always written to disk; BM25/vector search degrade gracefully until the extensions become available.
 
 Configure the behavior with these environment variables:
 
 | Variable                                     | Values                       | Default             | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | -------------------------------------------- | ---------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GITNEXUS_LBUG_EXTENSION_INSTALL`            | `auto`, `load-only`, `never` | `auto`              | `auto` runs one bounded INSTALL if LOAD fails. `load-only` only uses already-installed extensions (recommended for offline / firewalled environments). `never` skips optional extensions entirely.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer             | `15000`             | Wall-clock budget for the out-of-process `INSTALL` child before it is killed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `GITNEXUS_LBUG_EXTENSION_INSTALL`            | `auto`, `load-only`, `never` | `auto`              | `auto` runs one bounded install if LOAD fails — a plain `INSTALL`, escalating to `FORCE INSTALL` only when the LOAD error shows the present extension file is broken. `load-only` only uses already-installed extensions (recommended for offline / firewalled environments). `never` skips optional extensions entirely.                                                                                                                                                                                                                                                                                                                                                                                 |
+| `GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer             | `15000`             | Wall-clock budget for the out-of-process extension-install child before it is killed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `GITNEXUS_FTS_STEMMER`                       | supported LadybugDB stemmer  | `porter`            | Stemmer used when rebuilding BM25/FTS indexes. Use `none` for CJK-heavy repositories, or a language stemmer such as `german`, `french`, or `spanish` when that better matches repository comments and identifiers. Re-run `gitnexus analyze --repair-fts` after changing it.                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `GITNEXUS_FTS_CJK_SEGMENTATION`              | `none`, `bigram`             | `none`              | `bigram` inserts overlapping character-bigram boundaries into Chinese/Japanese Han-ideograph spans in `content`/`description` before FTS indexing, so LadybugDB's space-only tokenizer can see sub-phrase word boundaries. Scoped to CJK Unified Ideographs only — Japanese Hiragana/Katakana and Korean Hangul are not currently segmented. Unlike `GITNEXUS_FTS_STEMMER`, this rewrites stored text — enabling it on an already-indexed repo requires a full `gitnexus analyze --force`; neither `--repair-fts` nor a plain incremental `analyze` applies it to previously-indexed files. Set the same value wherever `analyze` and search-serving processes (CLI query, MCP server, web server) run. |
 | `GITNEXUS_WAL_CHECKPOINT_THRESHOLD`          | integer `>= -1`              | `67108864` (64 MiB) | LadybugDB WAL auto-checkpoint threshold during analyze (bytes). Auto-checkpoint remains enabled; `-1` keeps Ladybug's stock ~16 MiB. Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments.                                                                                                                                                                                                                                                                                                                                                                                                                |

package/dist/cli/analyze.js

@@ -27,8 +27,9 @@ import { cliError } from './cli-message.js';
 import { EMBEDDING_DIMS_ERROR, normalizeEmbeddingDims } from './embedding-dims.js';
 import { formatElapsed } from './format-elapsed.js';
 import { isHfDownloadFailure } from '../core/embeddings/hf-env.js';
-import { safeUrl } from '../core/embeddings/http-client.js';
-import { isLocalEmbeddingRuntimeBlockerMessage } from '../core/embeddings/runtime-support.js';
+import { isHttpMode, safeUrl } from '../core/embeddings/http-client.js';
+import { isLocalEmbeddingRuntimeBlockerMessage, isMissingLocalEmbeddingStackMessage, localEmbeddingPrefixUnloadableMessage, localEmbeddingStackMissingMessage, } from '../core/embeddings/runtime-support.js';
+import { ANALYZE_EMBEDDING_INSTALL_TIMEOUT_MS, getEmbeddingInstallTimeoutMs, getEmbeddingRuntimeDir, installEmbeddingRuntime, isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
 import { warnIfNpm11NpxRisk } from './resolve-invocation.js';
 // Capture stderr.write at module load BEFORE anything (LadybugDB native
 // init, progress bar, console redirection) can monkey-patch it. The
@@ -797,6 +798,52 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
         console.log('  Note: custom HTTP embeddings require BOTH --embedding-base-url and --embedding-model ' +
             '(or the matching env vars). Falling back to local ONNX embeddings.\n');
     }
+    // On-demand embedding runtime (#2370): when the optional stack was pruned at
+    // install time (proxy-blocked NuGet download in onnxruntime-node's
+    // postinstall), heal it here instead of failing later in the pipeline. The
+    // install goes through the user's npm registry config (mirrors/proxies
+    // apply) with --ignore-scripts, so no NuGet download is attempted. Runs
+    // before bar.start() like the sibling validations above.
+    if (embeddingsEnabled && !isHttpMode()) {
+        const resolved = resolveEmbeddingRuntime();
+        // Resolved-but-unloadable (a populated prefix on a Node with no
+        // module.registerHooks), or nothing installed on such a Node: fail fast with
+        // capability guidance instead of dying mid-pipeline over an unusable prefix
+        // or downloading a runtime the loader can't reach. A package-sourced stack
+        // never needs the hook, so it is excluded. --embeddings was explicitly
+        // requested and this failure is deterministic, so fail fast rather than
+        // silently degrading to BM25 (distinct from a transient install timeout).
+        if (!isPrefixRuntimeLoadable() && (resolved === null || resolved.source === 'runtime-prefix')) {
+            cliError(`  ${localEmbeddingPrefixUnloadableMessage().replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'local-embedding-stack-missing',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // On-demand embedding runtime (#2370): when the optional stack was pruned at
+        // install time (proxy-blocked NuGet download in onnxruntime-node's
+        // postinstall), heal it here instead of failing later in the pipeline. The
+        // install goes through the user's npm registry config (mirrors/proxies
+        // apply) with --ignore-scripts, so no NuGet download is attempted.
+        if (resolved === null) {
+            console.log(`  Local embedding runtime is not installed (optional packages were skipped at install time).\n` +
+                `  Downloading it now from your npm registry into ${getEmbeddingRuntimeDir()} …\n` +
+                `  (one-time; rerun manually anytime with \`gitnexus embeddings install\`)\n`);
+            try {
+                // Short deadline (env override still wins): analyze is interactive, so a
+                // blackholed proxy must not stall the whole index run for the 10-minute
+                // default — fail over to the guidance below instead.
+                await installEmbeddingRuntime({}, getEmbeddingInstallTimeoutMs(ANALYZE_EMBEDDING_INSTALL_TIMEOUT_MS));
+                console.log('  Embedding runtime installed.\n');
+            }
+            catch (err) {
+                cliError(`  Could not install the embedding runtime: ${err instanceof Error ? err.message : String(err)}\n\n` +
+                    `  ${localEmbeddingStackMissingMessage().replace(/\n/g, '\n  ')}\n`, { recoveryHint: 'local-embedding-stack-missing' });
+                process.exitCode = 1;
+                return;
+            }
+        }
+    }
     if (options.repairFts && options.force) {
         cliError('  Cannot combine `--repair-fts` with `--force`. ' +
             'Use `--repair-fts` for fast FTS-only repair, or `--force` for a full rebuild.\n');
@@ -1203,6 +1250,18 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             process.exitCode = 1;
             return;
         }
+        // The optional embedding stack (@huggingface/transformers → onnxruntime-node)
+        // was pruned at install time — usually a proxy-blocked NuGet download during
+        // onnxruntime-node's postinstall (#2370). Checked before the generic
+        // module-not-found "installation may be corrupt" hint below, which would
+        // otherwise misdiagnose a deliberate optional-dependency skip.
+        if (isMissingLocalEmbeddingStackMessage(msg)) {
+            cliError(`  ${msg.replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'local-embedding-stack-missing',
+            });
+            process.exitCode = 1;
+            return;
+        }
         // HF download failure — show clean guidance without the raw stack trace.
         // Checked before writeFatalToStderr so the user sees one focused message
         // rather than a stack-trace dump followed by a second remediation block.

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

@@ -12,7 +12,7 @@ import { type CliMessageKey, type CliMessageVars } from './i18n/index.js';
  * Consumers can import this type to narrow log-record `recoveryHint`
  * fields without restating the literal list.
  */
-export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'local-embedding-unsupported' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
+export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'local-embedding-unsupported' | 'local-embedding-stack-missing' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
 /**
  * Common shape for the optional structured-field bag passed to
  * `cliError`/`cliWarn`/`cliInfo`. Typed so the `recoveryHint` slot is

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,6 +15,10 @@ 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;

package/dist/cli/doctor.js

@@ -1,9 +1,10 @@
 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 } from '../core/lbug/native-check.js';
 import { getExtensionInstallPolicy } from '../core/lbug/extension-loader.js';
 import { t } from './i18n/index.js';
 function isCombiningMark(codePoint) {
@@ -64,6 +65,25 @@ 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 };
 }
 export const doctorCommand = async () => {
@@ -88,7 +108,15 @@ 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}`);
+    // 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}`);
+    }
     console.log(`  ${label('doctor.labels.vectorIndex', 18)}${capabilities.vector}`);
     console.log(`  ${label('doctor.labels.semanticMode', 18)}${capabilities.semanticMode}`);
     // Surface the optional-extension install policy so offline users can see

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/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',
@@ -143,6 +145,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',

package/dist/cli/i18n/en.d.ts

@@ -117,6 +117,8 @@ export declare const en: {
     readonly 'help.command.list.description': "List all indexed repositories";
     readonly 'help.command.status.description': "Show index status for current repo";
     readonly 'help.command.doctor.description': "Show runtime platform capabilities and embedding configuration";
+    readonly 'help.command.embeddings.description': "Manage the on-demand local embedding runtime";
+    readonly 'help.command.embeddings.install.description': "Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.";
     readonly 'help.command.clean.description': "Delete GitNexus index for current repo";
     readonly 'help.command.remove.description': "Delete the GitNexus index for a registered repo (by alias, name, or absolute path). Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.";
     readonly 'help.command.wiki.description': "Generate repository wiki from knowledge graph";
@@ -220,6 +222,8 @@ export declare const en: {
     readonly 'help.option.check.cycles': "Detect circular imports and fail when any are found";
     readonly 'help.option.evalServer.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)";
     readonly 'help.option.evalServer.idleTimeout': "Auto-shutdown after N seconds idle (0 = disabled)";
+    readonly 'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)";
+    readonly 'help.option.embeddings.install.force': "Install into the runtime prefix even when the stack already resolves";
     readonly 'help.option.group.create.force': "Overwrite existing group";
     readonly 'help.option.group.sync.skipEmbeddings': "Exact + BM25 only (no embedding fallback)";
     readonly 'help.option.group.sync.exactOnly': "Exact match only";

package/dist/cli/i18n/en.js

@@ -117,6 +117,8 @@ export const en = {
     'help.command.list.description': 'List all indexed repositories',
     'help.command.status.description': 'Show index status for current repo',
     'help.command.doctor.description': 'Show runtime platform capabilities and embedding configuration',
+    'help.command.embeddings.description': 'Manage the on-demand local embedding runtime',
+    'help.command.embeddings.install.description': 'Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.',
     'help.command.clean.description': 'Delete GitNexus index for current repo',
     'help.command.remove.description': 'Delete the GitNexus index for a registered repo (by alias, name, or absolute path). Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.',
     'help.command.wiki.description': 'Generate repository wiki from knowledge graph',
@@ -220,6 +222,8 @@ export const en = {
     'help.option.check.cycles': 'Detect circular imports and fail when any are found',
     'help.option.evalServer.host': 'Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)',
     'help.option.evalServer.idleTimeout': 'Auto-shutdown after N seconds idle (0 = disabled)',
+    'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)",
+    'help.option.embeddings.install.force': 'Install into the runtime prefix even when the stack already resolves',
     'help.option.group.create.force': 'Overwrite existing group',
     'help.option.group.sync.skipEmbeddings': 'Exact + BM25 only (no embedding fallback)',
     'help.option.group.sync.exactOnly': 'Exact match only',

package/dist/cli/i18n/resources.d.ts

@@ -118,6 +118,8 @@ export declare const cliResources: {
         readonly 'help.command.list.description': "List all indexed repositories";
         readonly 'help.command.status.description': "Show index status for current repo";
         readonly 'help.command.doctor.description': "Show runtime platform capabilities and embedding configuration";
+        readonly 'help.command.embeddings.description': "Manage the on-demand local embedding runtime";
+        readonly 'help.command.embeddings.install.description': "Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.";
         readonly 'help.command.clean.description': "Delete GitNexus index for current repo";
         readonly 'help.command.remove.description': "Delete the GitNexus index for a registered repo (by alias, name, or absolute path). Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.";
         readonly 'help.command.wiki.description': "Generate repository wiki from knowledge graph";
@@ -221,6 +223,8 @@ export declare const cliResources: {
         readonly 'help.option.check.cycles': "Detect circular imports and fail when any are found";
         readonly 'help.option.evalServer.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)";
         readonly 'help.option.evalServer.idleTimeout': "Auto-shutdown after N seconds idle (0 = disabled)";
+        readonly 'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)";
+        readonly 'help.option.embeddings.install.force': "Install into the runtime prefix even when the stack already resolves";
         readonly 'help.option.group.create.force': "Overwrite existing group";
         readonly 'help.option.group.sync.skipEmbeddings': "Exact + BM25 only (no embedding fallback)";
         readonly 'help.option.group.sync.exactOnly': "Exact match only";
@@ -360,6 +364,8 @@ export declare const cliResources: {
         'help.command.list.description': string;
         'help.command.status.description': string;
         'help.command.doctor.description': string;
+        'help.command.embeddings.description': string;
+        'help.command.embeddings.install.description': string;
         'help.command.clean.description': string;
         'help.command.remove.description': string;
         'help.command.wiki.description': string;
@@ -463,6 +469,8 @@ export declare const cliResources: {
         'help.option.check.cycles': string;
         'help.option.evalServer.host': string;
         'help.option.evalServer.idleTimeout': string;
+        'help.option.embeddings.install.cuda': string;
+        'help.option.embeddings.install.force': string;
         'help.option.group.create.force': string;
         'help.option.group.sync.skipEmbeddings': string;
         'help.option.group.sync.exactOnly': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -117,6 +117,8 @@ export declare const zhCN: {
     'help.command.list.description': string;
     'help.command.status.description': string;
     'help.command.doctor.description': string;
+    'help.command.embeddings.description': string;
+    'help.command.embeddings.install.description': string;
     'help.command.clean.description': string;
     'help.command.remove.description': string;
     'help.command.wiki.description': string;
@@ -220,6 +222,8 @@ export declare const zhCN: {
     'help.option.check.cycles': string;
     'help.option.evalServer.host': string;
     'help.option.evalServer.idleTimeout': string;
+    'help.option.embeddings.install.cuda': string;
+    'help.option.embeddings.install.force': string;
     'help.option.group.create.force': string;
     'help.option.group.sync.skipEmbeddings': string;
     'help.option.group.sync.exactOnly': string;

package/dist/cli/i18n/zh-CN.js

@@ -117,6 +117,8 @@ export const zhCN = {
     'help.command.list.description': '列出所有已索引仓库',
     'help.command.status.description': '显示当前仓库的索引状态',
     'help.command.doctor.description': '显示运行平台能力和嵌入配置',
+    'help.command.embeddings.description': '管理按需安装的本地嵌入运行时',
+    'help.command.embeddings.install.description': '按需安装本地嵌入组件（@huggingface/transformers + onnxruntime-node）。修复 npm 跳过可选包的安装（例如在 HTTP 代理后，#2370）。仅从你配置的 npm registry 下载 — 镜像和代理均生效。',
     'help.command.clean.description': '删除当前仓库的 GitNexus 索引',
     'help.command.remove.description': '删除已注册仓库的 GitNexus 索引（按别名、名称或绝对路径）。与 `clean` 不同，不要求位于仓库内；未知目标会幂等处理。',
     'help.command.wiki.description': '从知识图谱生成仓库 Wiki',
@@ -220,6 +222,8 @@ export const zhCN = {
     'help.option.check.cycles': '检测循环导入，并在发现循环时失败',
     'help.option.evalServer.host': '绑定地址（默认：127.0.0.1；用 0.0.0.0 暴露到所有网卡）',
     'help.option.evalServer.idleTimeout': '空闲 N 秒后自动关闭（0 = 禁用）',
+    'help.option.embeddings.install.cuda': '同时下载 CUDA GPU 二进制文件（运行 onnxruntime-node 的 NuGet postinstall；代理后请设置 GLOBAL_AGENT_HTTPS_PROXY）',
+    'help.option.embeddings.install.force': '即使嵌入组件已可解析，也强制安装到运行时目录',
     'help.option.group.create.force': '覆盖现有仓库组',
     'help.option.group.sync.skipEmbeddings': '仅使用 exact + BM25（不使用嵌入回退）',
     'help.option.group.sync.exactOnly': '仅精确匹配',

package/dist/cli/index.js

@@ -153,6 +153,17 @@ program
     .command('doctor')
     .description('Show runtime platform capabilities and embedding configuration')
     .action(createLazyAction(() => import('./doctor.js'), 'doctorCommand'));
+program
+    .command('embeddings')
+    .description('Manage the on-demand local embedding runtime')
+    .command('install')
+    .description('Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. ' +
+    'Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). ' +
+    'Downloads only from your configured npm registry — mirrors and proxies apply.')
+    .option('--cuda', "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; " +
+    'set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)')
+    .option('--force', 'Install into the runtime prefix even when the stack already resolves')
+    .action(createLazyAction(() => import('./embeddings.js'), 'embeddingsInstallCommand'));
 program
     .command('clean')
     .description('Delete GitNexus index for current repo')

package/dist/core/embeddings/embedder.js

@@ -16,8 +16,9 @@ import { DEFAULT_EMBEDDING_CONFIG } from './types.js';
 import { isHttpMode, getHttpDimensions, httpEmbed } from './http-client.js';
 import { resolveEmbeddingConfig } from './config.js';
 import { applyHfEnvOverrides, isHfDownloadFailure, withHfDownloadRetry } from './hf-env.js';
-import { getLocalEmbeddingRuntimeBlocker } from './runtime-support.js';
+import { getLocalEmbeddingRuntimeBlocker, getMissingLocalEmbeddingStackMessage, } from './runtime-support.js';
 import { ensureOnnxRuntimeCommonResolvable } from './onnxruntime-common-resolver.js';
+import { ensureEmbeddingStackResolvable } from './runtime-install.js';
 import { ensureOnnxRuntimeNodeMatchesSystem, isEffectiveCudaAvailable, } from './onnxruntime-node-resolver.js';
 import { logger } from '../logger.js';
 // Module-level state for singleton pattern
@@ -73,6 +74,11 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
         try {
             // Lazy-load transformers.js only after the runtime guard has passed, so
             // unsupported platforms never reach the native ONNX import (#1515).
+            // Registered FIRST so it sits last in the hook chain (registerHooks runs
+            // the most recent hook first): when the optional stack was pruned at
+            // install time (#2370), its bare specifiers fall back to the on-demand
+            // runtime prefix.
+            ensureEmbeddingStackResolvable();
             // Under pnpm-strict / `pnpm dlx`, transformers' phantom `onnxruntime-common`
             // import is unresolvable; register the fallback resolver first (#307).
             ensureOnnxRuntimeCommonResolvable();
@@ -82,7 +88,15 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
             // to the CUDA-13 build before transformers imports them. No-op on matching
             // layouts, non-CUDA, Windows/DirectML, and macOS.
             ensureOnnxRuntimeNodeMatchesSystem();
-            const { pipeline, env } = await import('@huggingface/transformers');
+            // The stack is an optionalDependency: npm prunes it when onnxruntime-node's
+            // postinstall can't reach api.nuget.org (#2370). Rethrow with actionable
+            // reinstall guidance instead of a raw ERR_MODULE_NOT_FOUND.
+            const { pipeline, env } = await import('@huggingface/transformers').catch((err) => {
+                const missing = getMissingLocalEmbeddingStackMessage(err);
+                if (missing)
+                    throw new Error(missing);
+                throw err;
+            });
             // Configure transformers.js environment
             env.allowLocalModels = false;
             // Bridge user-controlled env vars to transformers.js: HF_HOME →

package/dist/core/embeddings/node-module-compat.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The single access point for `module.registerHooks` (#2372).
+ *
+ * `module.registerHooks` — the synchronous ESM/CJS resolution-hook API the
+ * embedding-stack resolvers rely on — was added in Node 22.15.0 (and 23.5.0 on
+ * the 23.x line). The gitnexus engines floor is `>=22.0.0`, which admits Node
+ * 22.0–22.14 AND 23.0–23.4, where the export is absent.
+ *
+ * In this `"type": "module"` package, a *static named* import of a missing
+ * builtin export (`import { registerHooks } from 'node:module'`) is a
+ * `SyntaxError` at ESM link time — thrown before any `typeof registerHooks`
+ * guard in the module body can run, so every module carrying that import fails
+ * to load on those Node versions. This module owns the only namespace import of
+ * `node:module` and hands callers a value-or-`undefined` they guard at runtime,
+ * so the graceful-degradation path is finally reachable.
+ *
+ * `@types/node` types `registerHooks` as always-present, so `nodeModule.registerHooks`
+ * would type as defined while being `undefined` at runtime on older Node. The
+ * `Partial` narrow surfaces the real optionality without an `any` cast.
+ */
+import * as nodeModule from 'node:module';
+/** `module.registerHooks` if this Node exposes it (>=22.15 / >=23.5), else `undefined`. */
+export declare const getRegisterHooks: () => typeof nodeModule.registerHooks | undefined;

package/dist/core/embeddings/node-module-compat.js

@@ -0,0 +1,23 @@
+/**
+ * The single access point for `module.registerHooks` (#2372).
+ *
+ * `module.registerHooks` — the synchronous ESM/CJS resolution-hook API the
+ * embedding-stack resolvers rely on — was added in Node 22.15.0 (and 23.5.0 on
+ * the 23.x line). The gitnexus engines floor is `>=22.0.0`, which admits Node
+ * 22.0–22.14 AND 23.0–23.4, where the export is absent.
+ *
+ * In this `"type": "module"` package, a *static named* import of a missing
+ * builtin export (`import { registerHooks } from 'node:module'`) is a
+ * `SyntaxError` at ESM link time — thrown before any `typeof registerHooks`
+ * guard in the module body can run, so every module carrying that import fails
+ * to load on those Node versions. This module owns the only namespace import of
+ * `node:module` and hands callers a value-or-`undefined` they guard at runtime,
+ * so the graceful-degradation path is finally reachable.
+ *
+ * `@types/node` types `registerHooks` as always-present, so `nodeModule.registerHooks`
+ * would type as defined while being `undefined` at runtime on older Node. The
+ * `Partial` narrow surfaces the real optionality without an `any` cast.
+ */
+import * as nodeModule from 'node:module';
+/** `module.registerHooks` if this Node exposes it (>=22.15 / >=23.5), else `undefined`. */
+export const getRegisterHooks = () => nodeModule.registerHooks;

package/dist/core/embeddings/onnxruntime-common-resolver.js

@@ -57,11 +57,12 @@
  * as before — fine on hoisted layouts. Any failure during installation is
  * swallowed.
  */
-import { registerHooks, createRequire } from 'node:module';
+import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { join } from 'node:path';
 import { getEffectiveOnnxRuntimeNodeDir } from './onnxruntime-node-resolver.js';
 import { logger } from '../logger.js';
+import { getRegisterHooks } from './node-module-compat.js';
 let attempted = false;
 /**
  * Compute the file: URL the hook redirects `onnxruntime-common` to.
@@ -98,8 +99,10 @@ export const ensureOnnxRuntimeCommonResolvable = () => {
     // initEmbedder() call, and the hook is process-global — once is enough.
     attempted = true;
     try {
-        // Node < 22.15 (the gitnexus engines floor is >= 22.0.0): no synchronous
-        // hooks API. Degrade gracefully — the import still works on hoisted layouts.
+        // Node < 22.15 / < 23.5 (the gitnexus engines floor is >= 22.0.0): no
+        // synchronous hooks API. Degrade gracefully — the import still works on
+        // hoisted layouts.
+        const registerHooks = getRegisterHooks();
         if (typeof registerHooks !== 'function')
             return;
         const redirectUrl = resolveOnnxRuntimeCommonUrl();