gitnexus 1.6.8-rc.29 → 1.6.8-rc.30

package/dist/cli/analyze-config.js

@@ -85,6 +85,16 @@ const KEY_SPECS = {
     // built-in convention set, is otherwise invisible to route_map consumers.
     // Listing it here adds it to the cross-file consumer scan.
     fetchWrappers: { target: 'fetchWrappers', kind: 'string-array' },
+    // Auth token AND dims are intentionally CLI/env-only — no embeddingAuthToken
+    // or embeddingDims key here:
+    //   - the token keeps secrets out of a committed .gitnexusrc;
+    //   - dims cannot take effect from .gitnexusrc anyway — schema.ts reads
+    //     GITNEXUS_EMBEDDING_DIMS at module-load (before .gitnexusrc is loaded in
+    //     analyzeCommandImpl), so a config value would size nothing and silently
+    //     mismatch the vector column. Use --embedding-dims or GITNEXUS_EMBEDDING_DIMS.
+    // (URL/MODEL are safe as config keys: they are read lazily at runtime, not at module-load.)
+    embeddingBaseUrl: { target: 'embeddingBaseUrl', kind: 'string' },
+    embeddingModel: { target: 'embeddingModel', kind: 'string' },
 };
 /** Top-level container key for the nested form; not itself an `AnalyzeOptions` field. */
 const NESTED_KEY = 'analyze';

package/dist/cli/analyze.d.ts

@@ -115,6 +115,14 @@ export interface AnalyzeOptions {
      * outside the built-in convention still produces `route_map` consumers.
      */
     fetchWrappers?: string[];
+    /** OpenAI-compatible embeddings base URL (incl. /v1). Overrides GITNEXUS_EMBEDDING_URL. */
+    embeddingBaseUrl?: string;
+    /** Embedding model name. Overrides GITNEXUS_EMBEDDING_MODEL. */
+    embeddingModel?: string;
+    /** Bearer token for the embeddings endpoint. Overrides GITNEXUS_EMBEDDING_API_KEY. Never logged. */
+    embeddingAuthToken?: string;
+    /** Embedding vector dimensions (positive integer string). Overrides GITNEXUS_EMBEDDING_DIMS. */
+    embeddingDims?: string;
 }
 /**
  * Whether the post-index skill step should run.

package/dist/cli/analyze.js

@@ -23,8 +23,10 @@ import { warnMissingOptionalGrammars, getOptionalGrammarExtensions } from './opt
 import { glob } from 'glob';
 import fs from 'fs/promises';
 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 { warnIfNpm11NpxRisk } from './resolve-invocation.js';
 // Capture stderr.write at module load BEFORE anything (LadybugDB native
@@ -446,6 +448,10 @@ const ANALYZE_CLI_ENV_KEYS = [
     'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE',
     'GITNEXUS_EMBEDDING_DEVICE',
     'GITNEXUS_ANALYZE_PROGRESS_ACTIVE',
+    'GITNEXUS_EMBEDDING_URL',
+    'GITNEXUS_EMBEDDING_MODEL',
+    'GITNEXUS_EMBEDDING_API_KEY',
+    'GITNEXUS_EMBEDDING_DIMS',
 ];
 const snapshotAnalyzeEnv = () => {
     const snap = {};
@@ -690,6 +696,95 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
         }
         process.env.GITNEXUS_EMBEDDING_DEVICE = options.embeddingDevice;
     }
+    // --- Custom HTTP embedding endpoint flags (override GITNEXUS_EMBEDDING_* env vars) ---
+    const anyHttpEmbedFlag = options.embeddingBaseUrl !== undefined ||
+        options.embeddingModel !== undefined ||
+        options.embeddingAuthToken !== undefined ||
+        options.embeddingDims !== undefined;
+    if (options.embeddingBaseUrl !== undefined) {
+        const url = options.embeddingBaseUrl.trim();
+        if (url.length === 0) {
+            cliError('  --embedding-base-url must not be empty.\n');
+            process.exitCode = 1;
+            return;
+        }
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            cliError(`  --embedding-base-url is not a valid URL: "${url}".\n`);
+            process.exitCode = 1;
+            return;
+        }
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            cliError('  --embedding-base-url must use http:// or https://.\n');
+            process.exitCode = 1;
+            return;
+        }
+        // http-client strips trailing slashes; store as given (trimmed).
+        process.env.GITNEXUS_EMBEDDING_URL = url;
+    }
+    if (options.embeddingModel !== undefined) {
+        const model = options.embeddingModel.trim();
+        if (model.length === 0) {
+            cliError('  --embedding-model must not be empty.\n');
+            process.exitCode = 1;
+            return;
+        }
+        process.env.GITNEXUS_EMBEDDING_MODEL = model;
+    }
+    if (options.embeddingAuthToken !== undefined) {
+        const token = options.embeddingAuthToken.trim();
+        if (token.length === 0) {
+            cliError('  --embedding-auth-token must not be empty.\n');
+            process.exitCode = 1;
+            return;
+        }
+        // Never log the token value.
+        process.env.GITNEXUS_EMBEDDING_API_KEY = token;
+    }
+    // Validate + normalize dims through the same shared helper the preAction
+    // hook uses, so the CLI path, this direct/programmatic-call path, schema.ts
+    // (parseInt) and http-client (/^\d+$/) all agree on one canonical value.
+    if (options.embeddingDims !== undefined) {
+        const dims = normalizeEmbeddingDims(options.embeddingDims);
+        if (dims === null) {
+            cliError(`  ${EMBEDDING_DIMS_ERROR}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        process.env.GITNEXUS_EMBEDDING_DIMS = dims;
+    }
+    // Custom-endpoint UX, emitting at most ONE message that reflects THIS run's
+    // intent (not ambient env). Order matters — the first matching branch wins:
+    //   1. flags given but --embeddings absent: the endpoint won't be used, so
+    //      say only that (no contradictory "Using…" line).
+    //   2. embeddings enabled + a complete endpoint (flags or env): confirm it,
+    //      masking the URL via safeUrl() since a base URL may carry credentials
+    //      in userinfo (http://user:pass@host) or a query token (?api_key=…)
+    //      that must not land in stdout/CI logs. The auth token is never printed.
+    //   3. embeddings enabled but only one of URL/MODEL supplied via flags:
+    //      http-client.isHttpMode() needs BOTH, so warn about the fallback.
+    // Gating on embeddingsEnabled also stops the old behaviour of printing
+    // "Using custom embedding endpoint" on every analyze run whenever the env
+    // vars happened to be set.
+    if (anyHttpEmbedFlag && !embeddingsEnabled) {
+        console.log('  Note: --embedding-* flags only apply when --embeddings is also passed; ' +
+            'no embeddings will be generated this run.\n');
+    }
+    else if (embeddingsEnabled &&
+        process.env.GITNEXUS_EMBEDDING_URL &&
+        process.env.GITNEXUS_EMBEDDING_MODEL) {
+        console.log(`  Using custom embedding endpoint: ${safeUrl(process.env.GITNEXUS_EMBEDDING_URL)} ` +
+            `(model: ${process.env.GITNEXUS_EMBEDDING_MODEL})\n`);
+    }
+    else if (embeddingsEnabled &&
+        anyHttpEmbedFlag &&
+        (process.env.GITNEXUS_EMBEDDING_URL || process.env.GITNEXUS_EMBEDDING_MODEL)) {
+        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');
+    }
     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');

package/dist/cli/embedding-dims.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Strict positive-integer normalization for the `--embedding-dims` flag /
+ * `GITNEXUS_EMBEDDING_DIMS` value.
+ *
+ * Single source of truth shared by two write paths:
+ *   1. the `analyze` `preAction` hook (CLI path) — it must set the env var
+ *      BEFORE `schema.ts` reads `GITNEXUS_EMBEDDING_DIMS` at module-load time
+ *      (the static import chain `analyze.ts → run-analyze.ts → schema.ts`
+ *      bakes `FLOAT[dims]` into the vector-table DDL), and
+ *   2. `analyzeCommandImpl` (direct / programmatic-call path, which bypasses
+ *      the commander hook).
+ *
+ * Keep this module dependency-free. `index.ts` imports it eagerly, so pulling
+ * in anything that transitively loads `schema.ts` (e.g. `analyze.ts`) — or
+ * even `cli-message.ts`, which drags in the logger + i18n — would defeat the
+ * lazy `import('./analyze.js')` the hook exists to enable. Callers print the
+ * error themselves (the hook to stderr, the impl via `cliError`).
+ *
+ * Trim-then-validate, matching the sibling URL/MODEL/TOKEN flags: surrounding
+ * whitespace is tolerated, but the remaining value must be all digits and
+ * `> 0`. This rejects scientific notation (`1e3`), hex (`0x10`), fractions
+ * (`3.5`), signs (`+5`/`-5`), and trailing junk (`4096x`) so the three
+ * downstream readers — `schema.ts` (`parseInt`), `http-client.ts` (`/^\d+$/`),
+ * and this helper — all agree on one canonical value. Without it, `1e3` parsed
+ * to `FLOAT[1]` at module-load but requested 1000-dim vectors at runtime.
+ */
+/** Shared error message so both call sites surface identical wording. */
+export declare const EMBEDDING_DIMS_ERROR = "--embedding-dims must be a positive integer.";
+/**
+ * Returns the canonical positive-integer string (e.g. `"007"` → `"7"`), or
+ * `null` when the input is not a strict positive integer.
+ */
+export declare const normalizeEmbeddingDims: (raw: string) => string | null;

package/dist/cli/embedding-dims.js

@@ -0,0 +1,39 @@
+/**
+ * Strict positive-integer normalization for the `--embedding-dims` flag /
+ * `GITNEXUS_EMBEDDING_DIMS` value.
+ *
+ * Single source of truth shared by two write paths:
+ *   1. the `analyze` `preAction` hook (CLI path) — it must set the env var
+ *      BEFORE `schema.ts` reads `GITNEXUS_EMBEDDING_DIMS` at module-load time
+ *      (the static import chain `analyze.ts → run-analyze.ts → schema.ts`
+ *      bakes `FLOAT[dims]` into the vector-table DDL), and
+ *   2. `analyzeCommandImpl` (direct / programmatic-call path, which bypasses
+ *      the commander hook).
+ *
+ * Keep this module dependency-free. `index.ts` imports it eagerly, so pulling
+ * in anything that transitively loads `schema.ts` (e.g. `analyze.ts`) — or
+ * even `cli-message.ts`, which drags in the logger + i18n — would defeat the
+ * lazy `import('./analyze.js')` the hook exists to enable. Callers print the
+ * error themselves (the hook to stderr, the impl via `cliError`).
+ *
+ * Trim-then-validate, matching the sibling URL/MODEL/TOKEN flags: surrounding
+ * whitespace is tolerated, but the remaining value must be all digits and
+ * `> 0`. This rejects scientific notation (`1e3`), hex (`0x10`), fractions
+ * (`3.5`), signs (`+5`/`-5`), and trailing junk (`4096x`) so the three
+ * downstream readers — `schema.ts` (`parseInt`), `http-client.ts` (`/^\d+$/`),
+ * and this helper — all agree on one canonical value. Without it, `1e3` parsed
+ * to `FLOAT[1]` at module-load but requested 1000-dim vectors at runtime.
+ */
+/** Shared error message so both call sites surface identical wording. */
+export const EMBEDDING_DIMS_ERROR = '--embedding-dims must be a positive integer.';
+/**
+ * Returns the canonical positive-integer string (e.g. `"007"` → `"7"`), or
+ * `null` when the input is not a strict positive integer.
+ */
+export const normalizeEmbeddingDims = (raw) => {
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed) || parseInt(trimmed, 10) <= 0) {
+        return null;
+    }
+    return String(parseInt(trimmed, 10));
+};

package/dist/cli/index.js

@@ -4,6 +4,7 @@
 import { Command } from 'commander';
 import { createRequire } from 'node:module';
 import { createLazyAction, createLbugLazyAction } from './lazy-action.js';
+import { EMBEDDING_DIMS_ERROR, normalizeEmbeddingDims } from './embedding-dims.js';
 import { registerGroupCommands } from './group.js';
 import { localizeCliHelp } from './help-i18n.js';
 import { t } from './i18n/index.js';
@@ -24,6 +25,14 @@ program
     .description('Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors')
     .option('-f, --force', 'Apply the changes (default is a dry-run preview)')
     .action(createLazyAction(() => import('./uninstall.js'), 'uninstallCommand'));
+// Baseline of GITNEXUS_EMBEDDING_DIMS captured by the analyze preAction hook
+// before it overwrites the var, so the postAction hook can restore it. The
+// analyzeCommand env snapshot is taken AFTER this hook runs, so it cannot undo
+// the hook's write on its own — without this restore a CLI --embedding-dims
+// would leak into a later in-process program.parseAsync (tests / long-running
+// hosts). Single-shot CLI exits the process, making the restore a no-op there.
+let dimsEnvBaseline;
+let dimsEnvCaptured = false;
 program
     .command('analyze [path]')
     .description('Index a repository (full analysis)')
@@ -63,7 +72,53 @@ program
     .option('--embedding-batch-size <n>', 'Number of nodes per embedding batch')
     .option('--embedding-sub-batch-size <n>', 'Number of chunks per embedding model call')
     .option('--embedding-device <device>', 'Embedding device: auto, cpu, dml, cuda, or wasm')
+    .option('--embedding-base-url <url>', 'OpenAI-compatible embeddings base URL including the /v1 suffix ' +
+    '(e.g. http://10.219.32.29:11434/v1 for Ollama). Overrides GITNEXUS_EMBEDDING_URL.')
+    .option('--embedding-model <model>', 'Embedding model name (e.g. qwen3-embedding:8b). Overrides GITNEXUS_EMBEDDING_MODEL.')
+    .option('--embedding-auth-token <token>', 'Bearer token for the embeddings endpoint (omit for unauthenticated servers like Ollama). ' +
+    'Overrides GITNEXUS_EMBEDDING_API_KEY.')
+    .option('--embedding-dims <number>', 'Embedding vector dimensions (positive integer; e.g. 4096 for Qwen3-Embedding-8B). ' +
+    'Must match what the index was built with. Overrides GITNEXUS_EMBEDDING_DIMS.')
     .addHelpText('after', () => t('help.analyze.environment'))
+    .hook('preAction', (thisCommand) => {
+    // ONLY GITNEXUS_EMBEDDING_DIMS must be set here: schema.ts reads it at
+    // module-load time during the lazy import('./analyze.js') below (via the
+    // static chain analyze.ts → run-analyze.ts → schema.ts), so deferring to
+    // analyzeCommandImpl would be too late. URL / MODEL / API_KEY are read
+    // lazily at runtime (readConfig), so analyzeCommandImpl is their sole
+    // setter — keeping them out of this hook means they fall under the impl's
+    // env snapshot/restore and don't leak across in-process invocations.
+    const dimsOpt = thisCommand.opts()['embeddingDims'];
+    if (dimsOpt !== undefined) {
+        // Validate + normalize BEFORE writing the env var: schema.ts throws on a
+        // bad value at module-load, which — on the synchronous program.parse()
+        // path, before the analyze fatal-handlers are installed — would surface
+        // as a raw unhandled rejection instead of this friendly message.
+        const dims = normalizeEmbeddingDims(String(dimsOpt));
+        if (dims === null) {
+            process.stderr.write(`\n  ${EMBEDDING_DIMS_ERROR}\n\n`);
+            process.exit(1);
+        }
+        dimsEnvBaseline = process.env.GITNEXUS_EMBEDDING_DIMS;
+        dimsEnvCaptured = true;
+        process.env.GITNEXUS_EMBEDDING_DIMS = dims;
+    }
+})
+    .hook('postAction', () => {
+    // Restore the pre-hook GITNEXUS_EMBEDDING_DIMS so a CLI override doesn't
+    // persist into a later program.parseAsync in the same process. (Fires on a
+    // microtask after a successful parse; the crash path never reaches here,
+    // but the hook validates dims before writing, so there's nothing to undo.)
+    if (!dimsEnvCaptured)
+        return;
+    dimsEnvCaptured = false;
+    if (dimsEnvBaseline === undefined) {
+        delete process.env.GITNEXUS_EMBEDDING_DIMS;
+    }
+    else {
+        process.env.GITNEXUS_EMBEDDING_DIMS = dimsEnvBaseline;
+    }
+})
     .action(createLbugLazyAction(() => import('./analyze.js'), 'analyzeCommand'));
 program
     .command('index [path...]')

package/dist/core/embeddings/http-client.d.ts

@@ -19,6 +19,13 @@ export declare const isHttpMode: () => boolean;
  * if HTTP mode is not active or no explicit dimensions are set.
  */
 export declare const getHttpDimensions: () => number | undefined;
+/**
+ * Return a safe representation of a URL for logs and error messages.
+ * Strips query string (may contain tokens) and userinfo (may contain
+ * credentials), keeping protocol + host + path. Exported so the CLI's
+ * custom-endpoint confirmation can mask the same way.
+ */
+export declare const safeUrl: (url: string) => string;
 /**
  * Embed texts via the HTTP backend, splitting into batches.
  * Reads config from env vars on every call.

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

@@ -56,10 +56,12 @@ export const isHttpMode = () => readConfig() !== null;
  */
 export const getHttpDimensions = () => readConfig()?.dimensions;
 /**
- * Return a safe representation of a URL for error messages.
- * Strips query string (may contain tokens) and userinfo.
+ * Return a safe representation of a URL for logs and error messages.
+ * Strips query string (may contain tokens) and userinfo (may contain
+ * credentials), keeping protocol + host + path. Exported so the CLI's
+ * custom-endpoint confirmation can mask the same way.
  */
-const safeUrl = (url) => {
+export const safeUrl = (url) => {
     try {
         const u = new URL(url);
         return `${u.protocol}//${u.host}${u.pathname}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.8-rc.29",
+  "version": "1.6.8-rc.30",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",