devlensio 0.2.0

package/dist/clustering/index.d.ts

@@ -0,0 +1,27 @@
+import type { CodeEdge, CodeNode } from "../types.js";
+export interface ClusterNode {
+    nodeId: string;
+    rank: number;
+}
+export interface ClusterFile {
+    filePath: string;
+    nodeIds: ClusterNode[];
+}
+export interface Cluster {
+    id: string;
+    label: string;
+    files: ClusterFile[];
+    nodeCount: number;
+    topNodes: string[];
+}
+export interface InterClusterEdge {
+    from: string;
+    to: string;
+    weight: number;
+}
+export interface ClusterResult {
+    clusters: Cluster[];
+    interClusterEdges: InterClusterEdge[];
+    clusterMembership: Record<string, string>;
+}
+export declare function computeClusters(allNodes: CodeNode[], allEdges: CodeEdge[], nodeScores: Record<string, number>): ClusterResult;

package/dist/clustering/index.js

@@ -0,0 +1,149 @@
+//Ranked BFS with Shared Node isolation
+const BFS_TYPES = new Set(["CALLS", "PROP_PASS", "GUARDS", "EMITS", "LISTENS"]);
+export function computeClusters(allNodes, allEdges, nodeScores) {
+    const adjList = new Map();
+    const inDegree = new Map();
+    const nodeMap = new Map();
+    const fileContentMap = new Map();
+    // 1. Initialize Maps and File-to-Node relationships
+    for (const node of allNodes) {
+        adjList.set(node.id, []);
+        inDegree.set(node.id, 0);
+        nodeMap.set(node.id, node);
+        const path = node.filePath || "external-dependencies";
+        if (!fileContentMap.has(path))
+            fileContentMap.set(path, []);
+        fileContentMap.get(path).push(node.id);
+    }
+    // 2. Build Adjacency List for Bloom Traversal
+    for (const edge of allEdges) {
+        if (!BFS_TYPES.has(edge.type))
+            continue;
+        adjList.get(edge.from)?.push(edge.to);
+        inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);
+    }
+    const membership = new Map(); // nodeId -> clusterId
+    const ranks = new Map(); // nodeId -> rank
+    const queue = [];
+    let clusterPosition = 1;
+    // Helper: Register a node and all its file-siblings into a cluster
+    const startClusterFromNode = (rootId, manualClusterId) => {
+        if (membership.has(rootId))
+            return;
+        const clusterId = manualClusterId || `CLUSTER_${clusterPosition++}`;
+        const rootNode = nodeMap.get(rootId);
+        // STICKY LOGIC: Draft all nodes in the same file to keep file-integrity
+        const siblings = fileContentMap.get(rootNode?.filePath || "") || [];
+        const targets = siblings.length > 0 ? siblings : [rootId];
+        for (const id of targets) {
+            if (!membership.has(id)) {
+                membership.set(id, clusterId);
+                ranks.set(id, 0);
+                queue.push({ nodeId: id, clusterId, rank: 0 });
+            }
+        }
+        console.log(clusterId, rootId);
+    };
+    // 3. PHASE 1: Seed Entry Points (Structural Entry)
+    allNodes
+        .filter((n) => inDegree.get(n.id) === 0)
+        .sort((a, b) => (nodeScores[b.id] ?? 0) - (nodeScores[a.id] ?? 0))
+        .forEach((n) => startClusterFromNode(n.id));
+    const maxClusterLevel = 4;
+    // 4. PHASE 2: Main BFS Propagation (The Bloom)
+    while (queue.length > 0) {
+        const { nodeId, clusterId, rank } = queue.shift();
+        const currentNode = nodeMap.get(nodeId);
+        for (const childId of adjList.get(nodeId) ?? []) {
+            const childNode = nodeMap.get(childId);
+            const existingCluster = membership.get(childId);
+            const isFileBoundary = currentNode?.type === "FILE" || childNode?.type === "FILE";
+            const nextRank = (rank >= maxClusterLevel || isFileBoundary) ? rank : rank + 1;
+            if (!existingCluster) {
+                membership.set(childId, clusterId);
+                ranks.set(childId, nextRank);
+                queue.push({ nodeId: childId, clusterId, rank: nextRank });
+            }
+            else if (existingCluster !== clusterId && existingCluster !== "SHARED_CORE" && clusterId !== "SHARED_CORE") {
+                membership.set(childId, "SHARED_CORE");
+                ranks.set(childId, nextRank);
+                queue.push({ nodeId: childId, clusterId: "SHARED_CORE", rank: nextRank });
+            }
+        }
+    }
+    // 6. Assemble Temporary Groups
+    const tempGroups = new Map(); // clusterId -> path -> nodes
+    for (const node of allNodes) {
+        const cId = membership.get(node.id) || "MISC";
+        if (!tempGroups.has(cId))
+            tempGroups.set(cId, new Map());
+        const fileMap = tempGroups.get(cId);
+        const path = node.filePath || "external";
+        if (!fileMap.has(path))
+            fileMap.set(path, []);
+        fileMap.get(path).push({ nodeId: node.id, rank: ranks.get(node.id) ?? 0 });
+    }
+    // 7. PHASE 4: Refine & Consolidate (Remove single-node utility clusters)
+    const finalClusters = [];
+    const miscFiles = [];
+    const MIN_CLUSTER_SIZE = 3;
+    for (const [cId, fileMap] of tempGroups) {
+        const clusterFiles = [];
+        let totalNodesInCluster = 0;
+        for (const [path, nodes] of fileMap) {
+            clusterFiles.push({
+                filePath: path,
+                nodeIds: nodes.sort((a, b) => a.rank - b.rank)
+            });
+            totalNodesInCluster += nodes.length;
+        }
+        const isUtility = totalNodesInCluster < MIN_CLUSTER_SIZE && cId !== "SHARED_CORE";
+        if (isUtility) {
+            // Re-route membership to MISC cluster
+            clusterFiles.forEach(cf => cf.nodeIds.forEach(n => membership.set(n.nodeId, "UTILS_STORES")));
+            miscFiles.push(...clusterFiles);
+        }
+        else {
+            const allIds = clusterFiles.flatMap(f => f.nodeIds.map(n => n.nodeId));
+            const sortedByScore = allIds.sort((a, b) => (nodeScores[b] ?? 0) - (nodeScores[a] ?? 0));
+            finalClusters.push({
+                id: cId,
+                label: cId === "SHARED_CORE" ? "Shared Core" : (nodeMap.get(sortedByScore[0])?.name || cId),
+                files: clusterFiles,
+                nodeCount: totalNodesInCluster,
+                topNodes: sortedByScore.slice(0, 5),
+            });
+        }
+    }
+    // Add consolidated Utility cluster
+    if (miscFiles.length > 0) {
+        const miscIds = miscFiles.flatMap(f => f.nodeIds.map(n => n.nodeId));
+        finalClusters.push({
+            id: "UTILS_STORES",
+            label: "Singletons, Utilities & Global Stores",
+            files: miscFiles,
+            nodeCount: miscIds.length,
+            topNodes: miscIds.sort((a, b) => (nodeScores[b] ?? 0) - (nodeScores[a] ?? 0)).slice(0, 5)
+        });
+    }
+    // 8. Inter-Cluster Edges
+    const interClusterEdges = [];
+    const edgeTracker = new Map();
+    for (const edge of allEdges) {
+        const fromC = membership.get(edge.from);
+        const toC = membership.get(edge.to);
+        if (fromC && toC && fromC !== toC) {
+            const key = `${fromC}->${toC}`;
+            edgeTracker.set(key, (edgeTracker.get(key) ?? 0) + 1);
+        }
+    }
+    edgeTracker.forEach((weight, key) => {
+        const [from, to] = key.split("->");
+        interClusterEdges.push({ from, to, weight });
+    });
+    return {
+        clusters: finalClusters,
+        interClusterEdges,
+        clusterMembership: Object.fromEntries(membership),
+    };
+}

package/dist/config/index.d.ts

@@ -0,0 +1,10 @@
+import { type DevLensConfig } from "./types.js";
+export declare function detectOllama(): Promise<boolean>;
+export declare function initConfig(): Promise<void>;
+export declare function resolveConfig(req?: Request): DevLensConfig;
+export type { DevLensConfig } from "./types.js";
+export type { SafeConfig } from "./writer.js";
+export { maskConfig, writeConfig } from "./writer.js";
+export { CONFIG_FILE, CONFIG_DIR, ENV } from "./providers/file.js";
+export { sanitizeHeaders, CONFIG_HEADERS } from "./types.js";
+export { OLLAMA_DEFAULTS, ANTHROPIC_DEFAULTS } from "./types.js";

package/dist/config/index.js

@@ -0,0 +1,78 @@
+import { OLLAMA_DEFAULTS, ANTHROPIC_DEFAULTS } from "./types.js";
+import { loadFileConfig } from "./providers/file.js";
+import { applyRequestHeaders } from "./providers/request.js";
+//  Ollama Detection 
+//
+// Pings Ollama's default endpoint at server startup.
+// Used by resolveConfig() to choose which defaults to fall back to:
+//   - Ollama running  → OLLAMA_DEFAULTS (free, private, zero API cost)
+//   - Ollama absent   → ANTHROPIC_DEFAULTS (user must set apiKey)
+//
+// Uses a short timeout — we don't want server startup to hang for 30 seconds
+// if Ollama is not installed. 2 seconds is enough for a local HTTP ping.
+//
+// Called ONCE at startup and the result is cached — see `cachedDefaults` below.
+const OLLAMA_PING_URL = "http://localhost:11434";
+const OLLAMA_PING_TIMEOUT_MS = 2000;
+export async function detectOllama() {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), OLLAMA_PING_TIMEOUT_MS);
+        const res = await fetch(OLLAMA_PING_URL, {
+            signal: controller.signal,
+            method: "GET",
+        });
+        clearTimeout(timeout);
+        return res.ok;
+    }
+    catch {
+        // Ollama not running, not installed, or timed out — all treated the same
+        return false;
+    }
+}
+//  Startup Initialization 
+//
+// detectOllama() is called once when the server starts (in server/index.ts).
+// The result is stored here so resolveConfig() doesn't ping Ollama on
+// every single request — that would be slow and noisy.
+//
+// initConfig() must be called before any request is handled.
+// Until it is called, resolveConfig() falls back to ANTHROPIC_DEFAULTS safely.
+let cachedDefaults = ANTHROPIC_DEFAULTS;
+let initialized = false;
+export async function initConfig() {
+    if (initialized)
+        return;
+    const ollamaRunning = await detectOllama();
+    if (ollamaRunning) {
+        cachedDefaults = OLLAMA_DEFAULTS;
+        console.log("⚡ Ollama detected — using local LLM defaults");
+        console.log(`   Summarization: ${OLLAMA_DEFAULTS.summarization.model}`);
+        console.log(`   Embedding:     ${OLLAMA_DEFAULTS.embedding.model}`);
+    }
+    else {
+        cachedDefaults = ANTHROPIC_DEFAULTS;
+        console.log("☁️  Ollama not detected — using Anthropic defaults");
+        console.log("   Add an apiKey to ~/.devlens/config.json to enable summarization");
+        console.log(`   Or set ${(await import("./providers/file.js")).ENV.LLM_KEY}=your-key`);
+    }
+    initialized = true;
+}
+// This function reads config.json fresh on every call —
+// so if the user edits settings in the UI, the next job picks up the change
+// without requiring a server restart.
+export function resolveConfig(req) {
+    // Step 1 — load file config merged with detected defaults + env vars
+    const fileConfig = loadFileConfig(cachedDefaults);
+    if (!req)
+        return fileConfig;
+    // In local mode, ignore headers even if present
+    if (fileConfig.deploymentMode !== "cloud")
+        return fileConfig;
+    // Step 4 — apply header overrides for cloud users
+    return applyRequestHeaders(fileConfig, req);
+}
+export { maskConfig, writeConfig } from "./writer.js";
+export { CONFIG_FILE, CONFIG_DIR, ENV } from "./providers/file.js";
+export { sanitizeHeaders, CONFIG_HEADERS } from "./types.js";
+export { OLLAMA_DEFAULTS, ANTHROPIC_DEFAULTS } from "./types.js";

package/dist/config/providers/file.d.ts

@@ -0,0 +1,19 @@
+import { type DevLensConfig } from "../types.js";
+export declare const CONFIG_DIR: string;
+export declare const CONFIG_FILE: string;
+export declare const ENV: {
+    readonly LLM_PROVIDER: "DEVLENS_LLM_PROVIDER";
+    readonly LLM_MODEL: "DEVLENS_LLM_MODEL";
+    readonly LLM_KEY: "DEVLENS_LLM_KEY";
+    readonly LLM_BASE_URL: "DEVLENS_LLM_BASE_URL";
+    readonly BATCH_SIZE: "DEVLENS_BATCH_SIZE";
+    readonly EMBED_PROVIDER: "DEVLENS_EMBED_PROVIDER";
+    readonly EMBED_MODEL: "DEVLENS_EMBED_MODEL";
+    readonly EMBED_KEY: "DEVLENS_EMBED_KEY";
+    readonly EMBED_BASE_URL: "DEVLENS_EMBED_BASE_URL";
+    readonly NEO4J_URL: "DEVLENS_NEO4J_URL";
+    readonly NEO4J_USER: "DEVLENS_NEO4J_USER";
+    readonly NEO4J_PASSWORD: "DEVLENS_NEO4J_PASSWORD";
+    readonly NEO4J_STORECODE: "NEO4J_STORE_CODE";
+};
+export declare function loadFileConfig(defaults?: DevLensConfig): DevLensConfig;

package/dist/config/providers/file.js

@@ -0,0 +1,215 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { ANTHROPIC_DEFAULTS, } from "../types.js";
+// ─── Constants ────────────────────────────────────────────────────────────────
+export const CONFIG_DIR = path.join(os.homedir(), ".devlens");
+export const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+// ─── Environment Variable Names ───────────────────────────────────────────────
+//
+// For Docker users who prefer env vars over config files.
+// A Docker user running Ollama in the same network would set:
+//   DEVLENS_LLM_PROVIDER=ollama
+//   DEVLENS_LLM_BASE_URL=http://ollama:11434
+//
+// Priority: config file wins over env vars.
+// Env vars only fill fields that the config file left empty.
+export const ENV = {
+    // Summarization
+    LLM_PROVIDER: "DEVLENS_LLM_PROVIDER", //here DEVLENS_LLM_PROVIDER is the actual env variable
+    LLM_MODEL: "DEVLENS_LLM_MODEL",
+    LLM_KEY: "DEVLENS_LLM_KEY",
+    LLM_BASE_URL: "DEVLENS_LLM_BASE_URL",
+    BATCH_SIZE: "DEVLENS_BATCH_SIZE",
+    // Embedding
+    EMBED_PROVIDER: "DEVLENS_EMBED_PROVIDER",
+    EMBED_MODEL: "DEVLENS_EMBED_MODEL",
+    EMBED_KEY: "DEVLENS_EMBED_KEY",
+    EMBED_BASE_URL: "DEVLENS_EMBED_BASE_URL",
+    // Neo4j
+    NEO4J_URL: "DEVLENS_NEO4J_URL",
+    NEO4J_USER: "DEVLENS_NEO4J_USER",
+    NEO4J_PASSWORD: "DEVLENS_NEO4J_PASSWORD",
+    NEO4J_STORECODE: "NEO4J_STORE_CODE"
+};
+// ─── Deep Merge ───────────────────────────────────────────────────────────────
+//
+// Merges user's partial config on top of defaults.
+// Does NOT mutate either argument — returns a new object.
+//
+// Example:
+//   base:    { summarization: { provider: "anthropic", model: "haiku", batchSize: 50 } }
+//   partial: { summarization: { apiKey: "sk-ant-..." } }
+//   result:  { summarization: { provider: "anthropic", model: "haiku",
+//                               batchSize: 50, apiKey: "sk-ant-..." } }
+function deepMerge(base, partial) {
+    return {
+        deploymentMode: partial.deploymentMode ?? base.deploymentMode,
+        summarization: {
+            ...base.summarization,
+            ...partial.summarization,
+        },
+        embedding: {
+            ...base.embedding,
+            ...partial.embedding,
+        },
+        // Neo4j: if user provides any neo4j fields, merge on top of base.
+        // If user provides nothing, keep base (which may be undefined).
+        neo4j: partial.neo4j
+            ? { ...(base.neo4j ?? {}), ...partial.neo4j }
+            : base.neo4j,
+    };
+}
+// ─── Env Var Application ──────────────────────────────────────────────────────
+//
+// Applies environment variables onto an already-merged config.
+// Only fills fields that are still empty after the file merge.
+// Config file always wins — env vars never override explicit file values.
+//
+// This runs AFTER deepMerge so the priority is:
+//   config file > env vars > defaults
+function applyEnvVars(config) {
+    const s = config.summarization;
+    const e = config.embedding;
+    return {
+        ...config,
+        summarization: {
+            ...s,
+            // Only inject env var if config file didn't already set this field
+            provider: s.provider !== ANTHROPIC_DEFAULTS.summarization.provider
+                ? s.provider
+                : process.env[ENV.LLM_PROVIDER] ?? s.provider,
+            model: s.model ?? process.env[ENV.LLM_MODEL],
+            apiKey: s.apiKey ?? process.env[ENV.LLM_KEY],
+            baseUrl: s.baseUrl ?? process.env[ENV.LLM_BASE_URL],
+            batchSize: s.batchSize ?? (parseInt(process.env[ENV.BATCH_SIZE] ?? "", 10) ?? s.batchSize),
+        },
+        embedding: {
+            ...e,
+            provider: e.provider !== ANTHROPIC_DEFAULTS.embedding.provider
+                ? e.provider
+                : process.env[ENV.EMBED_PROVIDER] ?? e.provider,
+            model: e.model ?? process.env[ENV.EMBED_MODEL],
+            apiKey: e.apiKey ?? process.env[ENV.EMBED_KEY],
+            baseUrl: e.baseUrl ?? process.env[ENV.EMBED_BASE_URL],
+        },
+        // Neo4j: only build from env vars if config file didn't set it
+        // AND all three required env vars are present
+        neo4j: config.neo4j ?? buildNeo4jFromEnv(),
+    };
+}
+// Builds a Neo4jConfig purely from env vars.
+// Returns undefined if any of the three required vars is missing —
+// we never create a partial Neo4j config.
+function buildNeo4jFromEnv() {
+    const url = process.env[ENV.NEO4J_URL];
+    const username = process.env[ENV.NEO4J_USER];
+    const password = process.env[ENV.NEO4J_PASSWORD];
+    const storeRawCode = process.env[ENV.NEO4J_STORECODE] == "true";
+    if (!url || !username || !password)
+        return undefined;
+    return { url, username, password, storeRawCode };
+}
+// ─── Validation ───────────────────────────────────────────────────────────────
+//
+// Only validates what cannot have a sensible default.
+// apiKey is required for all cloud providers (anthropic, openai, openrouter, gemini).
+// ollama needs no apiKey — it uses baseUrl.
+// managed never needs an apiKey — platform provides it via request headers.
+//
+// Error messages are actionable — they tell the user exactly how to fix the problem.
+const PROVIDERS_NEEDING_KEY = new Set([
+    "anthropic",
+    "openai",
+    "openrouter",
+    "gemini",
+]);
+function validate(config) {
+    const { summarization, embedding } = config;
+    // Summarization apiKey
+    if (PROVIDERS_NEEDING_KEY.has(summarization.provider) &&
+        !summarization.apiKey) {
+        throw new Error(`DevLens config error: summarization.apiKey is required when provider is "${summarization.provider}".\n` +
+            `  Fix option 1 — add to ${CONFIG_FILE}:\n` +
+            `    { "summarization": { "apiKey": "your-key-here" } }\n` +
+            `  Fix option 2 — set environment variable:\n` +
+            `    ${ENV.LLM_KEY}=your-key-here \n` +
+            `Fix option 3 - Skip Summarization`);
+    }
+    // Embedding apiKey — only validate if the user explicitly configured embedding.
+    // If the user only set summarization, embedding may still be at default (openai
+    // with no key) which is fine — embedding is only needed for vector search (cloud).
+    const rawFile = readFileConfig();
+    const userSetEmbedding = !!rawFile.embedding?.provider;
+    if (userSetEmbedding &&
+        PROVIDERS_NEEDING_KEY.has(embedding.provider) &&
+        !embedding.apiKey) {
+        throw new Error(`DevLens config error: embedding.apiKey is required when provider is "${embedding.provider}".\n` +
+            `  Fix option 1 — add to ${CONFIG_FILE}:\n` +
+            `    { "embedding": { "apiKey": "your-key-here" } }\n` +
+            `  Fix option 2 — set environment variable:\n` +
+            `    ${ENV.EMBED_KEY}=your-key-here`);
+    }
+    // Neo4j — if any field is provided, all three must be present
+    if (config.neo4j) {
+        const { url, username, password } = config.neo4j;
+        if (!url || !username || !password) {
+            throw new Error(`DevLens config error: neo4j config is incomplete.\n` +
+                `  All three fields are required: url, username, password.\n` +
+                `  Fix option 1 — update ${CONFIG_FILE}:\n` +
+                `    { "neo4j": { "url": "bolt://localhost:7687", "username": "neo4j", "password": "..." } }\n` +
+                `  Fix option 2 — set environment variables:\n` +
+                `    ${ENV.NEO4J_URL}=bolt://localhost:7687\n` +
+                `    ${ENV.NEO4J_USER}=neo4j\n` +
+                `    ${ENV.NEO4J_PASSWORD}=your-password`);
+        }
+    }
+    // Ollama baseUrl format
+    if (summarization.provider === "ollama") {
+        const base = summarization.baseUrl ?? "http://localhost:11434";
+        if (!base.startsWith("http://") && !base.startsWith("https://")) {
+            throw new Error(`DevLens config error: summarization.baseUrl must start with http:// or https://.\n` +
+                `  Got: "${base}"`);
+        }
+    }
+}
+// ─── readFileConfig ───────────────────────────────────────────────────────────
+//
+// Reads ~/.devlens/config.json and returns a PartialConfig.
+// Returns empty object if file doesn't exist — first run, caller uses defaults.
+// Throws a clear parse error if file exists but contains invalid JSON.
+function readFileConfig() {
+    if (!fs.existsSync(CONFIG_FILE)) {
+        return {}; // first run — no config file yet
+    }
+    const raw = fs.readFileSync(CONFIG_FILE, "utf-8");
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`DevLens config error: ${CONFIG_FILE} contains invalid JSON.\n` +
+            `  Fix the syntax and restart DevLens.\n` +
+            `  Tip: use a JSON validator at https://jsonlint.com`);
+    }
+}
+// ─── loadFileConfig ───────────────────────────────────────────────────────────
+//
+// Public entry point — called by resolveConfig() in config/index.ts.
+//
+// Takes the active defaults (chosen by detectOllama() in index.ts):
+//   - OLLAMA_DEFAULTS    if Ollama is running at startup
+//   - ANTHROPIC_DEFAULTS if Ollama is not detected
+//
+// Steps:
+//   1. Read ~/.devlens/config.json  (partial — only what user set)
+//   2. Deep merge onto provided defaults
+//   3. Apply env vars for any still-missing fields
+//   4. Validate — throw clear errors for anything missing or invalid
+//   5. Return fully resolved DevLensConfig — never partial, never undefined fields
+export function loadFileConfig(defaults = ANTHROPIC_DEFAULTS) {
+    const partial = readFileConfig();
+    const merged = deepMerge(defaults, partial);
+    const withEnv = applyEnvVars(merged);
+    validate(withEnv);
+    return withEnv;
+}

package/dist/config/providers/request.d.ts

@@ -0,0 +1,2 @@
+import { type DevLensConfig } from "../types.js";
+export declare function applyRequestHeaders(base: DevLensConfig, req: Request): DevLensConfig;

package/dist/config/providers/request.js

@@ -0,0 +1,72 @@
+import { CONFIG_HEADERS } from "../types.js";
+// ─ applyRequestHeaders 
+//
+// Public — called by resolveConfig() in config/index.ts AFTER loadFileConfig().
+//
+// Takes the fully resolved file config as a base and overrides only the fields
+// that are explicitly present in the request headers.
+//
+// Headers that are absent = keep the file config value unchanged.
+// Headers that are present = override the file config value.
+//
+// This means a cloud user who only sends x-llm-key gets everything else
+// (model, batchSize, etc.) from their file config or defaults.
+//
+// IMPORTANT: This function must never be called in local deploymentMode.
+// The guard lives in resolveConfig() in index.ts — not here.
+// This function trusts that its caller checked deploymentMode first.
+//
+// Priority after this runs:
+//   request headers > file config > env vars > defaults
+export function applyRequestHeaders(base, req) {
+    const h = req.headers;
+    // Helper — reads a header, returns undefined if absent or empty string
+    function get(name) {
+        const val = h.get(name);
+        return (val && val.trim() !== "") ? val.trim() : undefined;
+    }
+    //  Summarization overrides ─
+    const provider = get(CONFIG_HEADERS.PROVIDER);
+    const model = get(CONFIG_HEADERS.MODEL);
+    const apiKey = get(CONFIG_HEADERS.API_KEY);
+    const baseUrl = get(CONFIG_HEADERS.BASE_URL);
+    const batchSize = get(CONFIG_HEADERS.BATCH_SIZE);
+    //  Embedding overrides ─
+    const embedProvider = get(CONFIG_HEADERS.EMBED_PROVIDER);
+    const embedModel = get(CONFIG_HEADERS.EMBED_MODEL);
+    const embedKey = get(CONFIG_HEADERS.EMBED_KEY);
+    const embedBaseUrl = get(CONFIG_HEADERS.EMBED_BASE_URL);
+    //  Neo4j overrides ─
+    const neo4jUrl = get(CONFIG_HEADERS.NEO4J_URL);
+    const neo4jUser = get(CONFIG_HEADERS.NEO4J_USER);
+    const neo4jPassword = get(CONFIG_HEADERS.NEO4J_PASSWORD);
+    const neo4jStoreCode = get(CONFIG_HEADERS.NEO4J_STORECODE) == "true";
+    // Build the final config — only override what headers explicitly provided
+    const result = {
+        // deploymentMode is never overridden by headers —
+        // it is set by the server at startup, not by the cloud backend
+        deploymentMode: base.deploymentMode,
+        summarization: {
+            ...base.summarization,
+            ...(provider && { provider: provider }),
+            ...(model && { model }),
+            ...(apiKey && { apiKey }),
+            ...(baseUrl && { baseUrl }),
+            ...(batchSize && { batchSize: parseInt(batchSize, 10) }),
+        },
+        embedding: {
+            ...base.embedding,
+            ...(embedProvider && { provider: embedProvider }),
+            ...(embedModel && { model: embedModel }),
+            ...(embedKey && { apiKey: embedKey }),
+            ...(embedBaseUrl && { baseUrl: embedBaseUrl }),
+        },
+        // Neo4j: only override if ALL THREE headers are present
+        // Partial Neo4j config from headers is never valid —
+        // if only one header is sent we keep the base neo4j config untouched
+        neo4j: (neo4jUrl && neo4jUser && neo4jPassword)
+            ? { url: neo4jUrl, username: neo4jUser, password: neo4jPassword, storeRawCode: neo4jStoreCode }
+            : base.neo4j,
+    };
+    return result;
+}

package/dist/config/types.d.ts

@@ -0,0 +1,46 @@
+export type LLMProvider = "anthropic" | "openai" | "openrouter" | "gemini" | "ollama" | "managed";
+export type EmbeddingProvider = "openai" | "anthropic" | "openrouter" | "gemini" | "ollama" | "managed";
+export type DeploymentMode = "local" | "cloud";
+export interface SummarizationConfig {
+    provider: LLMProvider;
+    model: string;
+    apiKey?: string;
+    baseUrl?: string;
+    batchSize: number;
+}
+export interface EmbeddingConfig {
+    provider: EmbeddingProvider;
+    model: string;
+    apiKey?: string;
+    baseUrl?: string;
+}
+export interface Neo4jConfig {
+    url: string;
+    username: string;
+    password: string;
+    storeRawCode: boolean;
+}
+export interface DevLensConfig {
+    deploymentMode: DeploymentMode;
+    summarization: SummarizationConfig;
+    embedding: EmbeddingConfig;
+    neo4j?: Neo4jConfig;
+}
+export declare const OLLAMA_DEFAULTS: DevLensConfig;
+export declare const ANTHROPIC_DEFAULTS: DevLensConfig;
+export declare const CONFIG_HEADERS: {
+    readonly PROVIDER: "x-llm-provider";
+    readonly MODEL: "x-llm-model";
+    readonly API_KEY: "x-llm-key";
+    readonly BASE_URL: "x-llm-base-url";
+    readonly BATCH_SIZE: "x-batch-size";
+    readonly EMBED_PROVIDER: "x-embed-provider";
+    readonly EMBED_MODEL: "x-embed-model";
+    readonly EMBED_KEY: "x-embed-key";
+    readonly EMBED_BASE_URL: "x-embed-base-url";
+    readonly NEO4J_URL: "x-neo4j-url";
+    readonly NEO4J_USER: "x-neo4j-user";
+    readonly NEO4J_PASSWORD: "x-neo4j-password";
+    readonly NEO4J_STORECODE: "false";
+};
+export declare function sanitizeHeaders(headers: Record<string, string>): Record<string, string>;