gitnexus 1.6.9 → 1.6.10-rc.10

package/dist/cli/uninstall.js

@@ -33,7 +33,7 @@ import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { fileURLToPath } from 'url';
 import { parseTree, modify, applyEdits, findNodeAtLocation, parse as parseJsonc, } from 'jsonc-parser';
-import { getEditorTargets, detectIndentation } from './editor-targets.js';
+import { getEditorTargets, detectIndentation, isEnoent } from './editor-targets.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const execFileAsync = promisify(execFile);
@@ -50,7 +50,13 @@ async function removeJsoncKey(filePath, keyPath, dryRun) {
     try {
         raw = await fs.readFile(filePath, 'utf-8');
     }
-    catch {
+    catch (err) {
+        // ENOENT = genuinely not configured. Any other read failure (EACCES,
+        // locks) must not report 'missing' — the file may hold a real gitnexus
+        // entry the dry-run would then deny exists. Rethrow into the caller's
+        // per-file catch.
+        if (!isEnoent(err))
+            throw err;
         return 'missing';
     }
     if (raw.trim().length === 0)
@@ -88,7 +94,12 @@ async function removeHookEntries(filePath, eventNames, commandNeedle, dryRun) {
     try {
         raw = await fs.readFile(filePath, 'utf-8');
     }
-    catch {
+    catch (err) {
+        // Masking a non-ENOENT read failure as 'missing' would also let the
+        // caller delete the hook scriptDir while the unreadable settings file
+        // still references it. Rethrow into the hook uninstaller's catch.
+        if (!isEnoent(err))
+            throw err;
         return { status: 'missing', count: 0 };
     }
     if (raw.trim().length === 0)
@@ -323,8 +334,15 @@ async function uninstallCodex(result, dryRun, configPath, tomlSection) {
     try {
         raw = await fs.readFile(configPath, 'utf-8');
     }
-    catch {
-        result.skipped.push('Codex MCP (not configured)');
+    catch (err) {
+        // Catch locally: this call site has no surrounding try, so a rethrow
+        // would abort the hooks/skills cleanup that runs after Codex.
+        if (isEnoent(err)) {
+            result.skipped.push('Codex MCP (not configured)');
+        }
+        else {
+            result.errors.push(`Codex: ${err instanceof Error ? err.message : String(err)}`);
+        }
         return;
     }
     if (!raw.includes(`[${tomlSection}]`)) {
@@ -369,20 +387,50 @@ export const uninstallCommand = async (options) => {
         console.log('  Dry run — nothing will be changed. Re-run with --force to apply.');
         console.log('');
     }
-    const result = { removed: [], skipped: [], errors: [] };
+    const result = { removed: [], skipped: [], errors: [], corruptLegacy: false };
     // ─── MCP server entries (JSONC editors) ──────────────────────────
+    // Sweep legacyFiles too: setup writes into the first existing file of the
+    // editor's priority chain, so the gitnexus entry may live in a deprecated
+    // location (e.g. CodeBuddy's ~/.codebuddy/mcp.json).
     for (const target of targets.mcpJsonc) {
-        try {
-            const status = await removeJsoncKey(target.file, target.keyPath, dryRun);
-            if (status === 'removed')
-                result.removed.push(`${target.label} MCP server — ${target.keyPath.join('.')} in ${target.file}`);
-            else if (status === 'corrupt')
-                result.errors.push(`${target.label}: ${path.basename(target.file)} is corrupt — left untouched`);
-            else
-                result.skipped.push(`${target.label} MCP (not configured)`);
+        let removedAny = false;
+        let erroredAny = false;
+        let corruptLegacyAny = false;
+        for (const file of [target.file, ...(target.legacyFiles ?? [])]) {
+            try {
+                const status = await removeJsoncKey(file, target.keyPath, dryRun);
+                if (status === 'removed') {
+                    removedAny = true;
+                    result.removed.push(`${target.label} MCP server — ${target.keyPath.join('.')} in ${file}`);
+                }
+                else if (status === 'corrupt') {
+                    if (file === target.file) {
+                        // The primary path is where gitnexus itself writes — corruption
+                        // there is an error worth failing the command over.
+                        erroredAny = true;
+                        result.errors.push(`${target.label}: ${path.basename(file)} is corrupt — left untouched`);
+                    }
+                    else {
+                        // Legacy chain files are vendor locations gitnexus may never have
+                        // touched (e.g. a corrupt ~/.codebuddy.json from an old install).
+                        // Report informationally without failing uninstall. Deliberate
+                        // asymmetry: an UNREADABLE (non-ENOENT) legacy file still errors —
+                        // that's an environmental problem worth surfacing, while corrupt-
+                        // but-readable proves there is no removable gitnexus entry.
+                        corruptLegacyAny = true;
+                        result.corruptLegacy = true;
+                        result.skipped.push(`${target.label} MCP (legacy ${path.basename(file)} is corrupt — left untouched)`);
+                    }
+                }
+            }
+            catch (err) {
+                erroredAny = true;
+                result.errors.push(`${target.label}: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
-        catch (err) {
-            result.errors.push(`${target.label}: ${err.message}`);
+        // A corrupt legacy file makes "not configured" unknowable — suppress it.
+        if (!removedAny && !erroredAny && !corruptLegacyAny) {
+            result.skipped.push(`${target.label} MCP (not configured)`);
         }
     }
     await uninstallCodex(result, dryRun, targets.codex.configFile, targets.codex.tomlSection);
@@ -425,6 +473,12 @@ export const uninstallCommand = async (options) => {
         for (const name of result.removed)
             console.log(`    - ${name}`);
     }
+    else if (result.errors.length > 0 || result.corruptLegacy) {
+        // Errors (corrupt primary files, unreadable configs) or corrupt legacy
+        // configs make "not configured" unknowable — claiming it right above an
+        // Errors block would be a contradiction users learn to distrust.
+        console.log('  Nothing removed.');
+    }
     else {
         console.log('  Nothing to remove — GitNexus is not configured in any detected editor.');
     }

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/http-client.d.ts

@@ -11,7 +11,13 @@
  * via `AbortSignal.timeout` on the underlying fetch.
  */
 /**
- * Check whether HTTP embedding mode is active (env vars are set).
+ * Whether HTTP embedding mode is active — i.e. both `GITNEXUS_EMBEDDING_URL` and
+ * `GITNEXUS_EMBEDDING_MODEL` are set. A pure presence probe: it deliberately does
+ * NOT call {@link readConfig}, so it never throws on a malformed
+ * `GITNEXUS_EMBEDDING_DIMS`. This lets its ~13 call sites (analyze, doctor,
+ * run-analyze, embedder, mcp) probe the mode without a defensive try/catch; the
+ * DIMS value is validated where it is actually used (`readConfig` in
+ * `httpEmbed`/`httpEmbedQuery`), surfacing a recognizable config error. See #2385.
  */
 export declare const isHttpMode: () => boolean;
 /**
@@ -26,6 +32,27 @@ export declare const getHttpDimensions: () => number | undefined;
  * custom-endpoint confirmation can mask the same way.
  */
 export declare const safeUrl: (url: string) => string;
+/**
+ * Error thrown by this module's HTTP embedding path (`httpEmbedBatch` /
+ * `httpEmbed` / `httpEmbedQuery`) for any endpoint failure — a
+ * connection/timeout/DNS error, an open circuit, a non-OK status, an
+ * unparseable or wrong-shape response body, an empty response, or a dimension
+ * mismatch.
+ *
+ * Carrying a distinct type (rather than a plain `Error`) lets the CLI tell a
+ * *custom endpoint* failure apart from a HuggingFace *model download* failure
+ * without matching message text: the two share the same underlying network
+ * substrings (`fetch failed`, `ECONNREFUSED`, …), which is exactly why
+ * `isNetworkFetchError` in `hf-env.ts` cannot tell them apart. Keying on the
+ * type instead of the message is also locale-proof and survives message
+ * rewording. The human-readable `.message` (built with `safeUrl` and the
+ * underlying reason) is what the CLI surfaces to the user. See #2385.
+ */
+export declare class HttpEmbeddingError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * Embed texts via the HTTP backend, splitting into batches.
  * Reads config from env vars on every call.

package/dist/core/embeddings/http-client.js

@@ -17,10 +17,26 @@ const HTTP_RETRY_BACKOFF_MS = 1_000;
 const HTTP_BATCH_SIZE = 64;
 const DEFAULT_DIMS = 384;
 const HTTP_BREAKER_KEY = 'embeddings-http';
+/**
+ * Stable lead of the {@link readConfig} malformed-`GITNEXUS_EMBEDDING_DIMS`
+ * error. `readConfig` throws a plain `Error` (not an {@link HttpEmbeddingError})
+ * because this is a *config* mistake, not an endpoint failure — so the CLI
+ * recognizes it by this lead ({@link isHttpEmbeddingDimsError}) and prints a
+ * clean config message instead of a raw stack dump. See #2385.
+ */
+const EMBEDDING_DIMS_ENV_ERROR_LEAD = 'GITNEXUS_EMBEDDING_DIMS must be a positive integer';
+/**
+ * @internal Exported for the CLI analyze error handler. True when `message` is
+ * the {@link readConfig} malformed-DIMS config error (a plain `Error`).
+ */
+export const isHttpEmbeddingDimsError = (message) => message.includes(EMBEDDING_DIMS_ENV_ERROR_LEAD);
 /**
  * Build config from the current process.env snapshot.
  * Returns null when GITNEXUS_EMBEDDING_URL + GITNEXUS_EMBEDDING_MODEL are unset.
  * Not cached — env vars are read fresh so late configuration takes effect.
+ * Validates GITNEXUS_EMBEDDING_DIMS and throws on a malformed value; callers
+ * that only need to know whether HTTP mode is *configured* must use
+ * {@link isHttpMode} (a presence probe that never throws), not this.
  */
 const readConfig = () => {
     const baseUrl = process.env.GITNEXUS_EMBEDDING_URL;
@@ -31,11 +47,11 @@ const readConfig = () => {
     let dimensions;
     if (rawDims !== undefined) {
         if (!/^\d+$/.test(rawDims)) {
-            throw new Error(`GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${rawDims}"`);
+            throw new Error(`${EMBEDDING_DIMS_ENV_ERROR_LEAD}, got "${rawDims}"`);
         }
         const parsed = parseInt(rawDims, 10);
         if (parsed <= 0) {
-            throw new Error(`GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${rawDims}"`);
+            throw new Error(`${EMBEDDING_DIMS_ENV_ERROR_LEAD}, got "${rawDims}"`);
         }
         dimensions = parsed;
     }
@@ -47,9 +63,15 @@ const readConfig = () => {
     };
 };
 /**
- * Check whether HTTP embedding mode is active (env vars are set).
+ * Whether HTTP embedding mode is active — i.e. both `GITNEXUS_EMBEDDING_URL` and
+ * `GITNEXUS_EMBEDDING_MODEL` are set. A pure presence probe: it deliberately does
+ * NOT call {@link readConfig}, so it never throws on a malformed
+ * `GITNEXUS_EMBEDDING_DIMS`. This lets its ~13 call sites (analyze, doctor,
+ * run-analyze, embedder, mcp) probe the mode without a defensive try/catch; the
+ * DIMS value is validated where it is actually used (`readConfig` in
+ * `httpEmbed`/`httpEmbedQuery`), surfacing a recognizable config error. See #2385.
  */
-export const isHttpMode = () => readConfig() !== null;
+export const isHttpMode = () => Boolean(process.env.GITNEXUS_EMBEDDING_URL && process.env.GITNEXUS_EMBEDDING_MODEL);
 /**
  * Return the configured embedding dimensions for HTTP mode, or undefined
  * if HTTP mode is not active or no explicit dimensions are set.
@@ -70,6 +92,63 @@ export const safeUrl = (url) => {
         return '<invalid-url>';
     }
 };
+/**
+ * Strip credentials from an underlying transport error message before it is
+ * surfaced. A credential-bearing endpoint URL (`https://user:secret@host/v1`)
+ * makes undici throw `TypeError: Request cannot be constructed from a URL that
+ * includes credentials: <that full URL>`; interpolating `err.message` verbatim
+ * would re-leak the secret to stderr + logs even though the URL argument is
+ * already masked with {@link safeUrl}. First swap the exact configured `url` for
+ * its masked form, then strip any residual `scheme://userinfo@` the transport may
+ * have echoed in a normalized (non-exact) form. See #2385.
+ */
+const sanitizeReason = (reason, url) => reason
+    .split(url)
+    .join(safeUrl(url))
+    .replace(/([a-z][a-z0-9+.-]*:\/\/)[^/@\s]*@/gi, '$1');
+/**
+ * Error thrown by this module's HTTP embedding path (`httpEmbedBatch` /
+ * `httpEmbed` / `httpEmbedQuery`) for any endpoint failure — a
+ * connection/timeout/DNS error, an open circuit, a non-OK status, an
+ * unparseable or wrong-shape response body, an empty response, or a dimension
+ * mismatch.
+ *
+ * Carrying a distinct type (rather than a plain `Error`) lets the CLI tell a
+ * *custom endpoint* failure apart from a HuggingFace *model download* failure
+ * without matching message text: the two share the same underlying network
+ * substrings (`fetch failed`, `ECONNREFUSED`, …), which is exactly why
+ * `isNetworkFetchError` in `hf-env.ts` cannot tell them apart. Keying on the
+ * type instead of the message is also locale-proof and survives message
+ * rewording. The human-readable `.message` (built with `safeUrl` and the
+ * underlying reason) is what the CLI surfaces to the user. See #2385.
+ */
+export class HttpEmbeddingError extends Error {
+    constructor(message, options) {
+        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = 'HttpEmbeddingError';
+    }
+}
+/**
+ * @internal Exported for the CLI analyze error handler and unit tests.
+ *
+ * Type-guard for {@link HttpEmbeddingError}. The `name` fallback keeps the
+ * check working across module-realm boundaries where `instanceof` can fail
+ * (two loaded copies of the class) — mirroring the codebase's existing
+ * `err.name === 'TimeoutError'` idiom. Matches on the stable class
+ * discriminator, never on the human-readable (potentially localized) message.
+ */
+export const isHttpEmbeddingError = (err) => err instanceof HttpEmbeddingError || (err instanceof Error && err.name === 'HttpEmbeddingError');
+/**
+ * Runtime guard for a single response item. The `Array.isArray(data.data)` shape
+ * check only validates the outer array — a 200 body like `{"data":[null]}` passes
+ * it, then crashes at `new Float32Array(item.embedding)` (`httpEmbed`) or
+ * `items[0].embedding` (`httpEmbedQuery`) with a raw `TypeError` that escapes the
+ * typed boundary, landing on the CLI's generic stack-dump path — the exact class
+ * #2385 closes. Validate each item so every wrong-shape body stays classifiable.
+ */
+const isEmbeddingItem = (item) => typeof item === 'object' &&
+    item !== null &&
+    Array.isArray(item.embedding);
 /**
  * Send a single batch of texts to the embedding endpoint with retry.
  *
@@ -111,23 +190,36 @@ const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensi
     }
     catch (err) {
         if (err instanceof CircuitOpenError) {
-            throw new Error(`Embedding endpoint circuit open (${safeUrl(url)}, batch ${batchIndex}): retry in ${Math.ceil(err.retryAfterMs / 1000)}s`);
+            throw new HttpEmbeddingError(`Embedding endpoint circuit open (${safeUrl(url)}, batch ${batchIndex}): retry in ${Math.ceil(err.retryAfterMs / 1000)}s`, { cause: err });
         }
         if (err instanceof DOMException && err.name === 'TimeoutError') {
-            throw new Error(`Embedding request timed out after ${HTTP_TIMEOUT_MS}ms (${safeUrl(url)}, batch ${batchIndex})`);
+            throw new HttpEmbeddingError(`Embedding request timed out after ${HTTP_TIMEOUT_MS}ms (${safeUrl(url)}, batch ${batchIndex})`, { cause: err });
         }
         if (err instanceof ResilientFetchExhaustedError) {
-            throw new Error(`Embedding endpoint returned ${err.response.status} (${safeUrl(url)}, batch ${batchIndex})`);
+            throw new HttpEmbeddingError(`Embedding endpoint returned ${err.response.status} (${safeUrl(url)}, batch ${batchIndex})`, { cause: err });
         }
-        const reason = err instanceof Error ? err.message : String(err);
-        throw new Error(`Embedding request failed (${safeUrl(url)}, batch ${batchIndex}): ${reason}`);
+        const reason = sanitizeReason(err instanceof Error ? err.message : String(err), url);
+        throw new HttpEmbeddingError(`Embedding request failed (${safeUrl(url)}, batch ${batchIndex}): ${reason}`, { cause: err });
     }
     if (!resp.ok) {
         // resilientFetch already retried 5xx/429; any non-OK response here is
         // a terminal client error (4xx other than 429).
-        throw new Error(`Embedding endpoint returned ${resp.status} (${safeUrl(url)}, batch ${batchIndex})`);
+        throw new HttpEmbeddingError(`Embedding endpoint returned ${resp.status} (${safeUrl(url)}, batch ${batchIndex})`);
+    }
+    // A reachable-but-wrong endpoint (e.g. a captive portal or a non-embeddings
+    // service) can answer 200 with an HTML/truncated body. Parse inside the
+    // typed-error boundary so that lands as an endpoint failure the CLI can
+    // classify, not a raw SyntaxError/TypeError on the generic stack-dump path.
+    let data;
+    try {
+        data = (await resp.json());
+    }
+    catch (err) {
+        throw new HttpEmbeddingError(`Embedding endpoint returned an unparseable response (${safeUrl(url)}, batch ${batchIndex})`, { cause: err });
+    }
+    if (!Array.isArray(data?.data) || !data.data.every(isEmbeddingItem)) {
+        throw new HttpEmbeddingError(`Embedding endpoint returned an unexpected response shape (${safeUrl(url)}, batch ${batchIndex})`);
     }
-    const data = (await resp.json());
     return data.data;
 };
 /**
@@ -150,7 +242,7 @@ export const httpEmbed = async (texts) => {
         const batchIndex = Math.floor(i / HTTP_BATCH_SIZE);
         const items = await httpEmbedBatch(url, batch, config.model, config.apiKey, batchIndex, config.dimensions);
         if (items.length !== batch.length) {
-            throw new Error(`Embedding endpoint returned ${items.length} vectors for ${batch.length} texts ` +
+            throw new HttpEmbeddingError(`Embedding endpoint returned ${items.length} vectors for ${batch.length} texts ` +
                 `(${safeUrl(url)}, batch ${batchIndex})`);
         }
         for (const item of items) {
@@ -162,7 +254,7 @@ export const httpEmbed = async (texts) => {
                 const hint = config.dimensions
                     ? 'Update GITNEXUS_EMBEDDING_DIMS to match your model output.'
                     : `Set GITNEXUS_EMBEDDING_DIMS=${vec.length} to match your model output.`;
-                throw new Error(`Embedding dimension mismatch: endpoint returned ${vec.length}d vector, ` +
+                throw new HttpEmbeddingError(`Embedding dimension mismatch: endpoint returned ${vec.length}d vector, ` +
                     `but expected ${expected}d. ${hint}`);
             }
             allVectors.push(vec);
@@ -184,7 +276,7 @@ export const httpEmbedQuery = async (text) => {
     const url = `${config.baseUrl}/embeddings`;
     const items = await httpEmbedBatch(url, [text], config.model, config.apiKey, 0, config.dimensions);
     if (!items.length) {
-        throw new Error(`Embedding endpoint returned empty response (${safeUrl(url)})`);
+        throw new HttpEmbeddingError(`Embedding endpoint returned empty response (${safeUrl(url)})`);
     }
     const embedding = items[0].embedding;
     // Same dimension checks as httpEmbed — catch mismatches before they
@@ -194,7 +286,7 @@ export const httpEmbedQuery = async (text) => {
         const hint = config.dimensions
             ? 'Update GITNEXUS_EMBEDDING_DIMS to match your model output.'
             : `Set GITNEXUS_EMBEDDING_DIMS=${embedding.length} to match your model output.`;
-        throw new Error(`Embedding dimension mismatch: endpoint returned ${embedding.length}d vector, ` +
+        throw new HttpEmbeddingError(`Embedding dimension mismatch: endpoint returned ${embedding.length}d vector, ` +
             `but expected ${expected}d. ${hint}`);
     }
     return embedding;

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();

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

@@ -51,12 +51,14 @@
  * loaded (the probe uses CJS `require.resolve`, which an ESM hook does not
  * affect) — keeping probe and runtime consistent.
  */
-import { registerHooks, createRequire } from 'node:module';
+import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { logger } from '../logger.js';
+import { getEmbeddingRuntimeDir } from './runtime-install.js';
+import { getRegisterHooks } from './node-module-compat.js';
 const require = createRequire(import.meta.url);
 /**
  * Read a shared object's NEEDED entries, tolerating ldd's non-zero exit when a
@@ -152,7 +154,18 @@ const resolveDefaultOrtNodeDir = () => {
         return dirname(createRequire(transformersMain).resolve('onnxruntime-node/package.json'));
     }
     catch {
-        return null;
+        // On-demand runtime prefix (#2370): when the optional stack was pruned at
+        // install time and fetched on demand, the copy that actually loads (via
+        // ensureEmbeddingStackResolvable's fallback hook) lives in the prefix — so
+        // it IS the effective default and must be the one the CUDA probe inspects.
+        try {
+            const prefixRequire = createRequire(join(getEmbeddingRuntimeDir(), 'noop.js'));
+            const transformersMain = prefixRequire.resolve('@huggingface/transformers');
+            return dirname(createRequire(transformersMain).resolve('onnxruntime-node/package.json'));
+        }
+        catch {
+            return null;
+        }
     }
 };
 /** gitnexus' own direct top-level onnxruntime-node dir. */
@@ -161,7 +174,19 @@ const resolveOurOrtNodeDir = () => {
         return dirname(require.resolve('onnxruntime-node/package.json'));
     }
     catch {
-        return null;
+        // On-demand runtime prefix (#2370): when gitnexus' own onnxruntime-node was
+        // pruned at install time and fetched on demand, the prefix copy IS our
+        // effective top-level build — so the CUDA-major redirect must be able to
+        // target it (mirrors resolveDefaultOrtNodeDir's fallback above). Without
+        // this, `embeddings install --cuda` on a pruned install downloads the GPU
+        // binaries but the probe still can't see them and embeddings run on CPU.
+        try {
+            const prefixRequire = createRequire(join(getEmbeddingRuntimeDir(), 'noop.js'));
+            return dirname(prefixRequire.resolve('onnxruntime-node/package.json'));
+        }
+        catch {
+            return null;
+        }
     }
 };
 let cached = null;
@@ -176,7 +201,7 @@ const decide = () => {
     // major is still probed: a CUDA-12 host on Node 22.0–22.14 whose default
     // build already matches must keep auto-selecting the GPU exactly as it did
     // before this redirect existed.
-    const canRedirect = typeof registerHooks === 'function';
+    const canRedirect = typeof getRegisterHooks() === 'function';
     const systemMajor = detectSystemCudaMajor();
     // `defaultDir` resolving is NOT a precondition for checking `ourDir` below —
     // if transformers' own resolution fails outright (defaultMajor stays null),
@@ -264,8 +289,9 @@ export const ensureOnnxRuntimeNodeMatchesSystem = () => {
         return;
     attempted = true;
     try {
+        const registerHooks = getRegisterHooks();
         if (typeof registerHooks !== 'function')
-            return; // Node < 22.15: graceful no-op
+            return; // Node < 22.15 / < 23.5: graceful no-op
         const d = decide();
         if (!d.redirect || !d.effectiveDir)
             return;