gitnexus 1.6.10-rc.6 → 1.6.10-rc.8

package/dist/cli/analyze.js

@@ -27,7 +27,7 @@ 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 { isHttpMode, safeUrl } from '../core/embeddings/http-client.js';
+import { isHttpEmbeddingDimsError, isHttpEmbeddingError, 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';
@@ -1262,10 +1262,54 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             process.exitCode = 1;
             return;
         }
+        // Malformed GITNEXUS_EMBEDDING_DIMS env var (#2385). readConfig() throws a
+        // plain Error (a config mistake, not an endpoint failure), surfacing here from
+        // httpEmbed()->readConfig() inside the analysis run. Show a clean config
+        // message rather than a raw stack dump. The --embedding-dims CLI flag is
+        // validated up front (EMBEDDING_DIMS_ERROR); this covers the env-var path.
+        // Checked before the endpoint/HF branches: it is a plain Error, so
+        // isHttpEmbeddingError() is false and the HF network heuristic must not claim it.
+        if (isHttpEmbeddingDimsError(msg)) {
+            cliError(`  ${msg.replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'embedding-dims-invalid',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // Custom HTTP embedding endpoint failure (#2385). When a `--embedding-base-url`
+        // is configured, HTTP mode never downloads a model — so a failure talking to
+        // that endpoint must NOT show the huggingface-download guidance. Keyed on the
+        // error *type* (HttpEmbeddingError), not its message text, so it stays correct
+        // regardless of locale or wording. Checked before the HF branch, whose network
+        // heuristic (`fetch failed` / `ECONNREFUSED`) would otherwise also match a
+        // wrapped endpoint-connection error. The header is deliberately neutral: this
+        // type covers both never-reached failures (connection/timeout/DNS) and
+        // reached-but-failed ones (4xx/5xx, dimension/shape mismatch), so it must not
+        // assert "unreachable". The thrown `msg` carries the specific reason (and the
+        // masked URL where one applies), so it is surfaced verbatim.
+        if (isHttpEmbeddingError(err)) {
+            cliError(`  The custom embedding endpoint request failed.\n` +
+                `  ${msg.replace(/\n/g, '\n  ')}\n` +
+                `  Suggestions:\n` +
+                `    1. Verify the endpoint URL is reachable and running ` +
+                `(--embedding-base-url / GITNEXUS_EMBEDDING_URL: host, port, /v1 path).\n` +
+                `    2. Confirm the model name and embedding dimensions match what the endpoint serves.\n` +
+                `    3. Re-run without --embeddings to index without vectors.\n`, { recoveryHint: 'http-embedding-endpoint-error' });
+            process.exitCode = 1;
+            return;
+        }
+        // isHttpMode() is a pure presence probe (URL+MODEL) that never throws — a
+        // malformed GITNEXUS_EMBEDDING_DIMS is handled by the dims branch above — so
+        // no defensive try/catch is needed here (#2385).
+        const inHttpMode = isHttpMode();
         // 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.
-        if (isHfDownloadFailure(msg) || msg.includes('Failed to download embedding model')) {
+        // Gated on !inHttpMode: with a custom endpoint configured no model download
+        // is ever attempted, so a network error there is the endpoint's, handled by
+        // the HttpEmbeddingError branch above — never HF's (#2385).
+        if ((isHfDownloadFailure(msg) || msg.includes('Failed to download embedding model')) &&
+            !inHttpMode) {
             cliError(`  The embedding model could not be downloaded.\n` +
                 `  huggingface.co may be unreachable from your network\n` +
                 `  (e.g. behind a corporate proxy or a regional firewall).\n` +

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' | 'local-embedding-stack-missing' | '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' | 'http-embedding-endpoint-error' | 'embedding-dims-invalid' | '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/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;