codesearch-mcp 0.0.17-alpha.1 → 0.1.0-alpha

package/dist/src/services/VoyageEmbedder.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VoyageEmbedder = void 0;
+const LoggerService_1 = require("./LoggerService");
+const config_1 = require("../config");
+const reranker_1 = require("./reranker");
+const http_retry_1 = require("./http-retry");
+const constants_1 = require("../constants");
+/**
+ * Voyage AI embedder. Voyage's schema differs from OpenAI's: `input` is an array
+ * of strings, `input_type` (`query` | `document`) is required for best quality,
+ * and the optional `output_dimension` requests Matryoshka truncation. Response
+ * is `{ data: [{ embedding, index }] }`.
+ */
+class VoyageEmbedder {
+    config;
+    logger;
+    dimensions;
+    rerank;
+    url;
+    doFetch;
+    baseDelayMs;
+    constructor(config, logger = LoggerService_1.LoggerService.silent(), deps = {}) {
+        this.config = config;
+        this.logger = logger;
+        const base = config.embedding.baseURL.replace(/\/+$/, '');
+        this.url = /\/embeddings$/.test(base) ? base : `${base}/embeddings`;
+        this.doFetch = deps.fetchImpl ?? fetch;
+        this.baseDelayMs = deps.baseDelayMs;
+        this.dimensions = config.embedding.dimensions ?? (0, constants_1.registryDimension)(config.embedding.model) ?? 0;
+        this.rerank = (0, reranker_1.makeReranker)(config, logger, deps);
+    }
+    async embed(text, inputType) {
+        const [v] = await this.embedBatch([text], inputType);
+        return v;
+    }
+    async embedBatch(texts, inputType = 'document') {
+        if (texts.length === 0)
+            return [];
+        return (0, http_retry_1.withRetry)(async () => {
+            const headers = { 'Content-Type': 'application/json' };
+            const apiKey = (0, config_1.resolveEnvRef)(this.config.embedding.apiKey);
+            if (apiKey)
+                headers['Authorization'] = `Bearer ${apiKey}`;
+            const body = {
+                model: this.config.embedding.model,
+                input: texts,
+                input_type: inputType,
+            };
+            if (this.config.embedding.dimensions != null)
+                body.output_dimension = this.config.embedding.dimensions;
+            const res = await this.doFetch(this.url, {
+                method: 'POST',
+                headers,
+                signal: AbortSignal.timeout(120_000),
+                body: JSON.stringify(body),
+            });
+            if (!res.ok) {
+                const errBody = (await res.text().catch(() => res.statusText)).slice(0, 200);
+                throw new http_retry_1.HttpError(res.status, `Voyage embeddings request failed: ${res.status} ${errBody}`);
+            }
+            const data = await res.json();
+            if (!Array.isArray(data.data) || data.data.length !== texts.length) {
+                throw new Error(`Voyage embeddings response returned ${data.data?.length ?? 0} vectors for ${texts.length} inputs`);
+            }
+            return [...data.data]
+                .sort((a, b) => (a.index ?? 0) - (b.index ?? 0))
+                .map(d => d.embedding);
+        }, { logger: this.logger, baseDelayMs: this.baseDelayMs, label: 'voyage-embed' });
+    }
+}
+exports.VoyageEmbedder = VoyageEmbedder;

package/dist/src/services/WebServerService.d.ts

@@ -0,0 +1,77 @@
+import type { Config } from '../config';
+import type { ISearcher } from '../interfaces';
+import type { IEmbedder } from '../interfaces';
+import type { ILogger } from '../interfaces';
+import { type JsonConfig } from '../config-store';
+/**
+ * Per-field choice lists for the config form. `strict` → render a dropdown that
+ * only accepts a listed value (e.g. the embedding model, tied to the vector
+ * dimension). Non-strict → a combobox: the values are suggestions but free text
+ * is still allowed (e.g. any Ollama model the user has pulled).
+ */
+export interface FieldOption {
+    values: string[];
+    strict: boolean;
+}
+/** Placeholder shown to the browser instead of a real secret. */
+export declare const PASSWORD_MASK = "********";
+/**
+ * Merge a config submitted from the browser with the stored one. Any secret
+ * field (DB password, embedding/reranker API keys) still holding the mask means
+ * the user did not change it — restore the stored value rather than overwrite it
+ * with the placeholder. `env:` references are not masked and round-trip as-is.
+ * Pure — no I/O. Exported for unit testing.
+ */
+export declare function mergeConfigForSave(incoming: JsonConfig, existing: JsonConfig | null): JsonConfig;
+/**
+ * Return a copy of the config with raw secrets (DB password, raw API keys)
+ * replaced by the mask, so real secrets never reach the browser. `env:`
+ * references are left verbatim — they are not secret and the dashboard shows
+ * them as "set via <VAR>". The masked value round-trips through
+ * `mergeConfigForSave`. Pure — no I/O. Exported for unit testing.
+ */
+export declare function maskConfig(cfg: JsonConfig): JsonConfig;
+/**
+ * Local HTTP dashboard. Serves a schema-driven config editor, a project
+ * overview, and the dependency graph. Bind to 127.0.0.1 only — no auth.
+ */
+export declare class WebServer {
+    private readonly searcher;
+    private readonly config;
+    private readonly logger;
+    private readonly embedder;
+    private server?;
+    constructor(searcher: ISearcher, config: Config, logger: ILogger, embedder: IEmbedder);
+    start(port: number, host: string): Promise<void>;
+    stop(): Promise<void>;
+    /** The bound address once started (e.g. `.port` after listen(0)); null otherwise. */
+    address(): {
+        port: number;
+    } | null;
+    private handle;
+    private maskedConfig;
+    private saveConfig;
+    /**
+     * Choice lists for model fields. Both are non-strict comboboxes (free text
+     * allowed): the embedding model suggests the known registry models plus any
+     * locally-installed models; the reranker model suggests installed models.
+     * Backends beyond the registry (e.g. arbitrary HuggingFace models on Infinity)
+     * still work — their dimension is probed at index time.
+     */
+    private fieldOptions;
+    private installedModels;
+    /** Tabbed graph views (Workspace + one per nested Nx repo). */
+    private graphViews;
+    /** `/api/graph` — the Workspace view's raw `{ nodes, edges }` (back-compat). */
+    private graphData;
+    /**
+     * The full interactive graph page — the same HTML as the standalone
+     * `project-graph.html` (inner tabs, filters, legend, project toggles). The
+     * dashboard's Graph tab embeds this via an iframe rather than re-implementing
+     * vis-network.
+     */
+    private graphPage;
+    private readBody;
+    private json;
+    private html;
+}

package/dist/src/services/WebServerService.js

@@ -0,0 +1,267 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebServer = exports.PASSWORD_MASK = void 0;
+exports.mergeConfigForSave = mergeConfigForSave;
+exports.maskConfig = maskConfig;
+const http = __importStar(require("http"));
+const path = __importStar(require("path"));
+const config_store_1 = require("../config-store");
+const constants_1 = require("../constants");
+const graph_1 = require("../graph");
+const dashboard_1 = require("../web/dashboard");
+/** Placeholder shown to the browser instead of a real secret. */
+exports.PASSWORD_MASK = '********';
+const MAX_BODY = 1_000_000; // 1 MB — config payloads are tiny
+/** A secret worth masking: a non-empty string that is not an `env:` reference. */
+function isRawSecret(v) {
+    return typeof v === 'string' && v !== '' && !v.startsWith('env:');
+}
+/**
+ * Merge a config submitted from the browser with the stored one. Any secret
+ * field (DB password, embedding/reranker API keys) still holding the mask means
+ * the user did not change it — restore the stored value rather than overwrite it
+ * with the placeholder. `env:` references are not masked and round-trip as-is.
+ * Pure — no I/O. Exported for unit testing.
+ */
+function mergeConfigForSave(incoming, existing) {
+    const merged = JSON.parse(JSON.stringify(incoming ?? {}));
+    const restore = (grp, field) => {
+        const g = merged[grp];
+        if (g && g[field] === exports.PASSWORD_MASK) {
+            const prev = existing?.[grp]?.[field];
+            if (prev !== undefined)
+                g[field] = prev;
+            else
+                delete g[field];
+        }
+    };
+    restore('db', 'password');
+    restore('embedding', 'apiKey');
+    restore('reranker', 'apiKey');
+    return merged;
+}
+/**
+ * Return a copy of the config with raw secrets (DB password, raw API keys)
+ * replaced by the mask, so real secrets never reach the browser. `env:`
+ * references are left verbatim — they are not secret and the dashboard shows
+ * them as "set via <VAR>". The masked value round-trips through
+ * `mergeConfigForSave`. Pure — no I/O. Exported for unit testing.
+ */
+function maskConfig(cfg) {
+    const clone = JSON.parse(JSON.stringify(cfg ?? {}));
+    if (clone.db?.password)
+        clone.db.password = exports.PASSWORD_MASK;
+    if (isRawSecret(clone.embedding?.apiKey))
+        clone.embedding.apiKey = exports.PASSWORD_MASK;
+    if (isRawSecret(clone.reranker?.apiKey))
+        clone.reranker.apiKey = exports.PASSWORD_MASK;
+    return clone;
+}
+/**
+ * Local HTTP dashboard. Serves a schema-driven config editor, a project
+ * overview, and the dependency graph. Bind to 127.0.0.1 only — no auth.
+ */
+class WebServer {
+    searcher;
+    config;
+    logger;
+    embedder;
+    server;
+    constructor(searcher, config, logger, embedder) {
+        this.searcher = searcher;
+        this.config = config;
+        this.logger = logger;
+        this.embedder = embedder;
+    }
+    async start(port, host) {
+        this.server = http.createServer((req, res) => {
+            this.handle(req, res).catch(err => {
+                this.logger.error('WebServer: request failed', { reason: err instanceof Error ? err.message : String(err) });
+                if (!res.headersSent) {
+                    res.writeHead(500);
+                    res.end('Internal error');
+                }
+            });
+        });
+        await new Promise((resolve, reject) => {
+            this.server.once('error', reject);
+            this.server.listen(port, host, () => resolve());
+        });
+        this.logger.info('WebServer: listening', { host, port });
+    }
+    async stop() {
+        if (!this.server)
+            return;
+        await new Promise(resolve => this.server.close(() => resolve()));
+        this.server = undefined;
+    }
+    /** The bound address once started (e.g. `.port` after listen(0)); null otherwise. */
+    address() {
+        const a = this.server?.address();
+        return a && typeof a === 'object' ? { port: a.port } : null;
+    }
+    async handle(req, res) {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        const p = url.pathname;
+        const m = req.method ?? 'GET';
+        if (m === 'GET' && p === '/')
+            return this.html(res, (0, dashboard_1.renderDashboardHtml)());
+        if (m === 'GET' && p === '/api/schema')
+            return this.json(res, 200, (0, config_store_1.buildJsonSchema)());
+        if (m === 'GET' && p === '/api/defaults')
+            return this.json(res, 200, config_store_1.CONFIG_DEFAULTS);
+        if (m === 'GET' && p === '/api/field-options')
+            return this.json(res, 200, await this.fieldOptions());
+        if (m === 'GET' && p === '/api/config')
+            return this.json(res, 200, this.maskedConfig());
+        if (m === 'PUT' && p === '/api/config')
+            return this.saveConfig(req, res);
+        if (m === 'GET' && p === '/api/projects')
+            return this.json(res, 200, await this.searcher.listProjects());
+        if (m === 'GET' && p === '/api/graph')
+            return this.json(res, 200, await this.graphData());
+        if (m === 'GET' && p === '/graph')
+            return this.html(res, await this.graphPage());
+        this.json(res, 404, { error: 'Not found' });
+    }
+    maskedConfig() {
+        return maskConfig((0, config_store_1.readConfigJson)() ?? {});
+    }
+    async saveConfig(req, res) {
+        let body;
+        try {
+            body = await this.readBody(req);
+        }
+        catch (e) {
+            // Distinguish the size limit from other stream errors.
+            return this.json(res, 413, { error: e instanceof Error ? e.message : 'Request body too large' });
+        }
+        let incoming;
+        try {
+            incoming = JSON.parse(body);
+        }
+        catch {
+            return this.json(res, 400, { error: 'Invalid JSON body' });
+        }
+        const merged = mergeConfigForSave(incoming, (0, config_store_1.readConfigJson)());
+        let validated;
+        try {
+            validated = (0, config_store_1.parseConfig)(merged);
+        }
+        catch (e) {
+            return this.json(res, 400, { error: e instanceof Error ? e.message : String(e) });
+        }
+        (0, config_store_1.writeConfigJson)(validated);
+        this.logger.info('WebServer: config updated');
+        this.json(res, 200, { ok: true });
+    }
+    /**
+     * Choice lists for model fields. Both are non-strict comboboxes (free text
+     * allowed): the embedding model suggests the known registry models plus any
+     * locally-installed models; the reranker model suggests installed models.
+     * Backends beyond the registry (e.g. arbitrary HuggingFace models on Infinity)
+     * still work — their dimension is probed at index time.
+     */
+    async fieldOptions() {
+        const installed = await this.installedModels();
+        const registryModels = Object.keys(constants_1.MODEL_REGISTRY);
+        return {
+            'embedding.model': { values: [...new Set([...registryModels, ...installed])], strict: false },
+            'reranker.model': { values: installed, strict: false },
+        };
+    }
+    async installedModels() {
+        try {
+            return (await this.embedder.listModels?.()) ?? [];
+        }
+        catch (err) {
+            this.logger.warn('WebServer: could not list models', { reason: err instanceof Error ? err.message : String(err) });
+            return [];
+        }
+    }
+    /** Tabbed graph views (Workspace + one per nested Nx repo). */
+    async graphViews() {
+        const projects = (await this.searcher.listProjects()).map(p => ({
+            name: p.serviceName,
+            // Real project root (resolved via discovery — handles nested-monorepo
+            // names). Fall back to the flat assumption if listProjects omits it.
+            path: p.path ?? path.join(this.config.workspaceRoot, p.serviceName),
+        }));
+        const projectEdges = await this.searcher.getProjectEdges();
+        return (0, graph_1.buildGraphViews)(projects, projectEdges, this.config.workspaceRoot);
+    }
+    /** `/api/graph` — the Workspace view's raw `{ nodes, edges }` (back-compat). */
+    async graphData() {
+        const views = await this.graphViews();
+        return { nodes: views[0].nodes, edges: views[0].edges };
+    }
+    /**
+     * The full interactive graph page — the same HTML as the standalone
+     * `project-graph.html` (inner tabs, filters, legend, project toggles). The
+     * dashboard's Graph tab embeds this via an iframe rather than re-implementing
+     * vis-network.
+     */
+    async graphPage() {
+        return (0, graph_1.buildHtml)(await this.graphViews());
+    }
+    readBody(req) {
+        return new Promise((resolve, reject) => {
+            let data = '';
+            let tooLarge = false;
+            req.on('data', chunk => {
+                if (tooLarge)
+                    return; // stop growing `data`; keep the socket alive so the 413 flushes
+                data += chunk;
+                if (data.length > MAX_BODY) {
+                    tooLarge = true;
+                    reject(new Error('Request body too large (max 1 MB)'));
+                }
+            });
+            req.on('end', () => resolve(data));
+            req.on('error', reject);
+        });
+    }
+    json(res, status, body) {
+        const s = JSON.stringify(body);
+        res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(s) });
+        res.end(s);
+    }
+    html(res, body) {
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(body);
+    }
+}
+exports.WebServer = WebServer;

package/dist/src/services/http-retry.d.ts

@@ -0,0 +1,19 @@
+import type { ILogger } from '../interfaces/ILogger';
+export declare class HttpError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+export interface RetryOpts {
+    /** Total attempts including the first (default 4). */
+    attempts?: number;
+    /** Base backoff in ms; grows exponentially (default 500). Set 0 in tests. */
+    baseDelayMs?: number;
+    logger?: ILogger;
+    label?: string;
+}
+/**
+ * Run `fn` with bounded exponential backoff on HTTP 429/5xx and network errors.
+ * Re-throws the last error once attempts are exhausted or the error is not
+ * transient.
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOpts): Promise<T>;

package/dist/src/services/http-retry.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpError = void 0;
+exports.withRetry = withRetry;
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'HttpError';
+    }
+}
+exports.HttpError = HttpError;
+function sleep(ms) {
+    return ms > 0 ? new Promise(r => setTimeout(r, ms)) : Promise.resolve();
+}
+/** True for transient failures worth retrying (rate limit / server error / network / timeout). */
+function isRetryable(err) {
+    if (err instanceof HttpError)
+        return err.status === 429 || (err.status >= 500 && err.status <= 599);
+    // A request timeout (AbortSignal.timeout) rejects with a DOMException named
+    // 'TimeoutError' — the most common transient cloud failure, so retry it.
+    if (err != null && typeof err === 'object' && err.name === 'TimeoutError')
+        return true;
+    // Network-level errors (fetch throws) are transient too.
+    return err instanceof TypeError;
+}
+/**
+ * Run `fn` with bounded exponential backoff on HTTP 429/5xx and network errors.
+ * Re-throws the last error once attempts are exhausted or the error is not
+ * transient.
+ */
+async function withRetry(fn, opts = {}) {
+    const attempts = opts.attempts ?? 4;
+    const base = opts.baseDelayMs ?? 500;
+    let lastErr;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (attempt >= attempts || !isRetryable(err))
+                break;
+            const delay = base * Math.pow(2, attempt - 1);
+            opts.logger?.warn('http-retry: transient failure, retrying', {
+                label: opts.label, attempt, attempts, delayMs: delay,
+                reason: err instanceof Error ? err.message : String(err),
+            });
+            await sleep(delay);
+        }
+    }
+    throw lastErr;
+}

package/dist/src/services/reranker.d.ts

@@ -0,0 +1,15 @@
+import type { Config } from '../config';
+import type { ILogger } from '../interfaces/ILogger';
+/**
+ * Build a rerank function from `config.reranker`, or return `undefined` when
+ * reranking is disabled / unconfigured. Targets an OpenAI-compatible `/rerank`
+ * endpoint returning `{ results: [{ index }] }` (Infinity, TEI, vLLM,
+ * Jina/Cohere-shape). Ollama has NO rerank API, so it is not a valid backend
+ * here — the embedding provider is independent of the rerank server
+ * (`reranker.baseURL`), so Ollama embeddings + an Infinity reranker is fine.
+ * Returns original indices into `documents`, best-first.
+ */
+export declare function makeReranker(config: Config, logger: ILogger, deps?: {
+    fetchImpl?: typeof fetch;
+    baseDelayMs?: number;
+}): ((query: string, documents: string[], topN: number) => Promise<number[]>) | undefined;

package/dist/src/services/reranker.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeReranker = makeReranker;
+const config_1 = require("../config");
+const http_retry_1 = require("./http-retry");
+/**
+ * Build a rerank function from `config.reranker`, or return `undefined` when
+ * reranking is disabled / unconfigured. Targets an OpenAI-compatible `/rerank`
+ * endpoint returning `{ results: [{ index }] }` (Infinity, TEI, vLLM,
+ * Jina/Cohere-shape). Ollama has NO rerank API, so it is not a valid backend
+ * here — the embedding provider is independent of the rerank server
+ * (`reranker.baseURL`), so Ollama embeddings + an Infinity reranker is fine.
+ * Returns original indices into `documents`, best-first.
+ */
+function makeReranker(config, logger, deps = {}) {
+    const r = config.reranker;
+    if (!r.enabled)
+        return undefined;
+    if (!r.model) {
+        logger.warn('reranker: enabled=true but reranker.model is not set — reranking disabled');
+        return undefined;
+    }
+    const doFetch = deps.fetchImpl ?? fetch;
+    return async (query, documents, topN) => {
+        return (0, http_retry_1.withRetry)(async () => {
+            const headers = { 'Content-Type': 'application/json' };
+            const apiKey = (0, config_1.resolveEnvRef)(r.apiKey);
+            if (apiKey)
+                headers['Authorization'] = `Bearer ${apiKey}`;
+            const res = await doFetch(r.url, {
+                method: 'POST',
+                headers,
+                signal: AbortSignal.timeout(30_000),
+                body: JSON.stringify({ model: r.model, query, documents, top_n: topN, truncate: true }),
+            });
+            if (!res.ok) {
+                const body = (await res.text().catch(() => res.statusText)).slice(0, 200);
+                throw new http_retry_1.HttpError(res.status, `rerank failed: ${res.status} ${body}`);
+            }
+            const data = await res.json();
+            return data.results.map(x => x.index);
+        }, { logger, baseDelayMs: deps.baseDelayMs, label: 'rerank' });
+    };
+}

package/dist/src/setup.d.ts

@@ -1,2 +1,8 @@
 import type { LoggerService } from './services/LoggerService';
+/**
+ * Default answer for the "start Docker containers?" prompt: no only when both
+ * the database and the embedding backend are already reachable. Pure — exported
+ * for unit testing.
+ */
+export declare function dockerPromptDefault(dbReachable: boolean, embReachable: boolean): 'y' | 'n';
 export declare function runSetup(logger?: LoggerService): Promise<void>;