devlensio 0.4.3 → 0.6.0

package/README.md

@@ -1,134 +1,274 @@
-# devlensio — the DevLens analysis engine
+# `devlensio` — The DevLens Analysis Engine
 
 [![npm: devlensio](https://img.shields.io/badge/npm-devlensio-cb3837?logo=npm)](https://www.npmjs.com/package/devlensio)
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 
-The core engine behind [DevLens](https://github.com/devlensio/devlensOSS). It turns a TypeScript / JavaScript / React / Next.js / Node.js repository into a **typed code graph** — nodes (components, hooks, functions, stores, routes, files, …) joined by typed edges — scores every node by architectural importance, optionally **summarizes** each node with an LLM (technical / business / security), and exposes a **traversal/query API**.
+The core engine behind [DevLens](https://github.com/devlensio/devlensOSS) — the codebase visualizer. It turns a TypeScript / JavaScript / React / Next.js / Node.js repository into a **typed code graph** with functional summaries, technical summaries, and security analysis on every node.
 
-`devlensio` is a **library + local server**. The user-facing tools — the `devlens` CLI, the MCP server, the Agent Skill, and the Web UI — live in [DevLens OSS](https://github.com/devlensio/devlensOSS) and consume this package.
+The user-facing tools — CLI, MCP server, Agent Skill, and Web UI — all live in [DevLens OSS](https://github.com/devlensio/devlensOSS) and consume this package.
 
 ---
 
-## Install
+## What it does
 
-```bash
-npm install devlensio
-# or: bun add devlensio
+```
+Repo path
+   │
+[1] Fingerprint     → detect language, framework, router, state manager, data layer
+[2] Route detection → extract routes (Next.js, React Router, Express, Fastify, Koa)
+[3] AST parsing      → walk every .ts/.tsx/.js/.jsx → extract nodes with types
+[4] Edge detection   → map CALLS, IMPORTS, PROP_PASS, WRITES_TO, and 12 more edge types
+[5] Scoring          → multi-pass importance scoring (no AI, deterministic)
+[6] Clustering       → assign cohesive clusters
+[7] Summarize (opt)  → topological LLM summaries — functional + technical + security
+   │
+   ▼
+Graph saved to ~/.devlens  →  queried via the traversal API / CLI / MCP / UI
 ```
 
-Requires Node 18+ (or Bun). An LLM provider key is needed only for summarization, not for structural analysis.
+Structural analysis is fast and deterministic. Summarization is the only step that calls an LLM — and unchanged nodes are reused across commits (90%+ free on re-runs).
 
 ---
 
-## What it does (the pipeline)
+## Install
 
-```
-Repo path
-   │
-[1] Fingerprint     detect language, framework, router, state manager, data layer, databases
-[2] Filesystem scan extract routes (Next.js app/pages, Express, Fastify, Koa)
-[3] Parse (ts-morph) walk every .ts/.tsx/.js/.jsx → nodes (typed params, return types, prop types)
-[4] Edge detection  many detectors → CALLS, IMPORTS, READS_FROM, WRITES_TO, PROP_PASS, EMITS,
-                    LISTENS, WRAPPED_BY, GUARDS, HANDLES, TESTS, USES, NEXTJS_API_CALL
-[5] Scoring         multi-pass importance scoring + noise filtering (no AI)
-[6] Clustering      cohesive cluster assignment
-[7] Summarize       (optional) topologically-ordered LLM summaries, checkpoint/resume, MapReduce
-   │
-   ▼
-Graph persisted to ~/.devlens  →  queried via the traversal API / CLI / MCP / UI
+```bash
+npm install devlensio
+# or
+bun add devlensio
 ```
 
-Structural analysis is fast and deterministic; summarization is the only step that calls an LLM and reuses unchanged nodes across commits.
+Requires Node 18+ (or Bun). An LLM provider key is only needed for AI summarization — structural analysis works offline.
 
 ---
 
 ## Public API
 
-```ts
+```typescript
 import {
-  analyzePipeline,        // build the graph (nodes, edges, scores)
-  runSummarization,       // generate technical/business/security summaries
-  computeClusters,        // cohesive clustering
-  buildGraphIndex,        // index nodes+edges for traversal
-  getBlastRadius,         // upstream dependents ("what breaks if I change this")
-  getKHop,                // downstream dependencies ("what this needs")
-  getSubgraph,            // cohesive cluster around a seed
-  findCycles,             // circular-dependency groups
-  resolveConfig, initConfig,   // LLM provider config (~/.devlens/config.json)
-  storage, queue,         // file-based graph storage + job queue singletons
+  analyzePipeline,        // Build a graph from a repo
+  runSummarization,       // Generate AI summaries (functional, technical, security)
+  buildGraphIndex,        // Index nodes + edges for traversal
+  getBlastRadius,         // Upstream dependents — "what breaks if I change this?"
+  getKHop,                // Downstream dependencies — "what does this depend on?"
+  getSubgraph,            // Cohesive cluster around a seed node
+  findCycles,             // Circular dependency groups
+  resolveConfig,          // Resolve active provider config (flat)
+  initConfig,             // LLM provider config
+  loadCatalog,            // Provider catalog (name, label, protocol, baseUrl, requiresKey)
+  findProvider,           // Look up a provider by name in the catalog
+  listModels,             // Fetch live model list from a provider's models endpoint
+  resolveAllProviders,    // Get all configured providers + active pointer
+  setActiveProvider,      // Switch the active provider by composite key
+  removeProviderConfig,   // Remove a provider entry (refuses active entry)
+  writeConfig,            // Upsert a provider entry and mark it active
 } from "devlensio";
 
-// Analyze a repo → graph
-const result = await analyzePipeline("/path/to/repo", /* isGithubRepo */ false);
-// result.allNodes, result.allEdges, result.nodeScores
+// Analyze a repo
+const result = await analyzePipeline("/path/to/repo");
 
-// Query the graph
-const index  = buildGraphIndex(result.allNodes, result.allEdges);
+// Traverse the graph
+const index = buildGraphIndex(result.allNodes, result.allEdges);
 const impact = getBlastRadius(index, "src/auth/login.ts::login", { radius: 2 });
 const cycles = findCycles(result.allNodes, result.allEdges);
+
+// Discover providers and their models
+const catalog = loadCatalog();
+const deepseekModels = await listModels({
+  protocol: "openai",
+  baseUrl: "https://api.deepseek.com",
+  apiKey: "...",
+});
+
+// Multi-provider management
+const allProviders = resolveAllProviders();
+// → { active: "openai:deepseek", providers: [{ provider:"openai", providerName:"deepseek", ... }] }
+
+setActiveProvider("openai:deepseek");   // Switch active provider
+removeProviderConfig("anthropic:anthropic"); // Remove entry (throws if active)
+
+// Upsert a provider entry (marks it active)
+writeConfig({
+  summarization: {
+    provider: "openai",
+    providerName: "deepseek",
+    model: "deepseek-chat",
+    baseUrl: "https://api.deepseek.com",
+    batchSize: 50,
+  },
+});
 ```
 
-Also exported: all core types (`CodeNode`, `CodeEdge`, `NodeType`, `EdgeType`, …), config helpers (`maskConfig`, `writeConfig`), pre-scan helpers (`readPackageDependencies`, `categorizeLibrary`), and `EDGE_LABELS`. See `dist/index.d.ts` for the full surface.
+Also exported: all core types (`CodeNode`, `CodeEdge`, `NodeType`, `EdgeType`, `CatalogProvider`, `ProviderConfigEntry`, `SummarizationConfig`, …) and config helpers. See `dist/index.d.ts` for the full surface.
+
+---
+
+## Node & edge types
+
+**Node types**
+
+| Type | What it represents |
+| :-- | :-- |
+| `COMPONENT` | React / UI component |
+| `HOOK` | React custom hook |
+| `FUNCTION` | Plain function |
+| `STATE_STORE` | State management (Zustand, Redux, etc.) |
+| `UTILITY` | Utility / helper module |
+| `FILE` | File-level node |
+| `ROUTE` | Application route |
+| `TEST` | Test file |
+| `THIRD_PARTY` | External dependency |
+
+**Edge types**
 
-### Node & edge types
+`CALLS`, `IMPORTS`, `READS_FROM`, `WRITES_TO`, `PROP_PASS`, `EMITS`, `LISTENS`, `WRAPPED_BY`, `GUARDS`, `HANDLES`, `TESTS`, `USES`, `NEXTJS_API_CALL`, `NAVIGATES_TO`
 
-- **Node types:** `COMPONENT`, `HOOK`, `FUNCTION`, `STATE_STORE`, `UTILITY`, `FILE`, `ROUTE`, `TEST`, `STORY`, `THIRD_PARTY` (+ internal `GHOST`).
-- **Edge types:** `CALLS`, `IMPORTS`, `READS_FROM`, `WRITES_TO`, `PROP_PASS`, `EMITS`, `LISTENS`, `WRAPPED_BY`, `GUARDS`, `HANDLES`, `TESTS`, `USES`, `NEXTJS_API_CALL` (frontend `fetch`/`axios`/`useSWR` call site → Next.js API route).
-- Each node carries an importance score and (after summarization) a technical summary, a business summary, and a security assessment (`none|low|medium|high` + notes).
+Each node carries: **importance score** + **functional summary** + **technical summary** + **security assessment** (severity + notes).
 
 ---
 
 ## Configuration
 
-Summarization config lives in `~/.devlens/config.json` (set via `initConfig`/`writeConfig`, or env vars loaded with dotenv). Supported providers: **Anthropic**, **OpenAI**, **OpenRouter**, **Gemini**, **Ollama** (local).
+### Provider model: protocol vs brand
+
+The engine splits provider identity into two orthogonal concerns:
+
+| Field | Meaning | Values |
+| :-- | :-- | :-- |
+| `provider` | Wire protocol (`"openai"` or `"anthropic"`) — routes to the correct SDK | `"openai"` / `"anthropic"` |
+| `providerName` | Brand identity — picks `baseUrl` + key rules from the catalog, or a custom name | Any string (e.g. `"deepseek"`, `"my-gateway"`) |
+
+### Multi-provider storage
+
+`~/.devlens/config.json` now holds a **registry** of all configured providers, keyed by composite key (`${protocol}:${providerName}`), with one marked `active`:
+
+```json
+{
+  "summarization": {
+    "active": "openai:deepseek",
+    "providers": {
+      "openai:deepseek": {
+        "provider": "openai",
+        "providerName": "deepseek",
+        "model": "deepseek-chat",
+        "apiKey": "sk-...",
+        "baseUrl": "https://api.deepseek.com",
+        "batchSize": 50
+      },
+      "anthropic:anthropic": {
+        "provider": "anthropic",
+        "providerName": "anthropic",
+        "model": "claude-haiku-4-5",
+        "apiKey": "sk-...",
+        "baseUrl": "https://api.anthropic.com",
+        "batchSize": 50
+      }
+    }
+  }
+}
+```
+
+Key behaviours:
+- **Saving a provider upserts it into the registry and marks it active** — previous entries are preserved.
+- **Switching active is a separate operation** (`setActiveProvider()`) that rewrites only the `active` pointer.
+- **Removing a provider** (`removeProviderConfig()`) refuses to delete the active entry — switch first.
+- **Legacy flat configs auto-migrate** to the multi-provider format on first load.
+
+### Environment variables
 
 ```env
-LLM_PROVIDER=openrouter        # ollama | openai | anthropic | openrouter | gemini
-LLM_MODEL=grok-4.1-fast
-LLM_API_KEY=your_api_key       # not needed for ollama
-LLM_BASE_URL=                  # e.g. http://localhost:11434 for Ollama
+DEVLENS_LLM_PROVIDER=openai          # Wire protocol — "openai" | "anthropic"
+DEVLENS_LLM_PROVIDER_NAME=deepseek   # Brand — picks baseUrl + key rules from catalog
+DEVLENS_LLM_MODEL=deepseek-chat
+DEVLENS_LLM_KEY=your_key
+DEVLENS_LLM_BASE_URL=                # Override base URL (optional)
+```
+
+### Config resolution priority
+
+```
+request headers (cloud)  >  config.json  >  env vars  >  catalog defaults  >  code defaults
+```
+
+### Provider catalog
+
+A built-in catalog ships with the engine (`providers.default.json`) — no config required for known providers. Models are **never hardcoded** in the catalog; they are discovered dynamically from each provider's `/models` endpoint at runtime.
+
+**Built-in providers:** DeepSeek, OpenAI, Anthropic, Google Gemini, Groq, Mistral, xAI Grok, OpenRouter, Ollama (local).
+
+Extend or override via `~/.devlens/providers.json` (deep-merged by `name`):
+
+```json
+{
+  "version": 2,
+  "providers": [
+    {
+      "name": "my-gateway",
+      "label": "My Gateway",
+      "protocol": "openai",
+      "baseUrl": "http://localhost:8080/v1",
+      "requiresKey": false
+    }
+  ]
+}
 ```
 
-Graphs and config are stored under `~/.devlens` and shared with all DevLens tools.
+**Custom providers** can be added at any time — no engine update needed. Any provider not in the catalog is saved with its user-specified `baseUrl`, `protocol`, and `providerName`.
 
 ---
 
-## Repo layout
+## How model discovery works
+
+The engine exposes `listModels()` — a pure function with **two** lister branches matching the two protocols:
+
+| Protocol | Endpoint | Covers |
+| :-- | :-- | :-- |
+| `openai` | `GET {baseUrl}/models` | openai, deepseek, groq, mistral, xai, gemini, openrouter, ollama, custom OpenAI-style |
+| `anthropic` | `GET {baseUrl}/v1/models` (paginated) | anthropic, custom Anthropic-style |
+
+A custom-model entry is always available — essential for OpenRouter's huge catalog and as a fallback when listing fails.
+
+---
+
+## Repository layout
 
 ```
 src/
-├── fingerprint/   # detect framework, language, router, state, data layer, databases
-├── filesystem/    # route detection (Next.js app/pages, Express, Fastify, Koa)
-├── parser/        # ts-morph AST extraction → nodes
-├── graph/         # edge detectors, traversal API, third-party libs, lookup maps
-├── scoring/       # multi-pass importance scoring + noise filtering
-├── clustering/    # cohesive cluster computation
-├── summarizer/    # LLM summarization (technical/business/security), prompts, checkpoints
-├── pipeline/      # analyzePipeline — orchestrates the whole analysis
-├── jobs/          # job queue, concurrency, SSE progress events
-├── storage/       # file-based graph persistence (~/.devlens)
-├── config/        # provider config resolution
-├── server/        # HTTP API server (consumed by the DevLens Web UI)
-└── debug/         # exportGraph and dev utilities
+├── fingerprint/    # Detect framework, language, router, state, data layer
+├── filesystem/     # Route detection (Next.js, React Router, Express, etc.)
+├── parser/         # AST extraction → nodes (ts-morph)
+├── graph/          # Edge detectors, traversal API, lookup maps
+├── scoring/        # Multi-pass importance scoring + noise filtering
+├── clustering/     # Cohesive cluster computation
+├── summarizer/     # LLM summarization pipeline, prompts, checkpoints
+│   └── providers/  # Generic OpenAI & Anthropic clients, model discovery
+├── pipeline/       # analyzePipeline — orchestrates everything
+├── jobs/           # Job queue, concurrency, SSE progress
+├── storage/        # File-based graph persistence (~/.devlens)
+├── config/         # Provider config resolution (types, catalog, writer, env)
+├── server/         # HTTP API server (consumed by Web UI)
+└── debug/          # Export and dev utilities
 ```
 
 ---
 
 ## Scripts
 
-| Script | Does |
+| Command | What it does |
 | :-- | :-- |
-| `bun run dev` | watch-mode HTTP server (`src/server/index.ts`) |
-| `bun run start` | run the HTTP server |
-| `bun run build` | `tsc --project tsconfig.build.json` → `dist/` (the published artifact) |
-| `bun test` | run the test suite |
-| `bun run export-graph` | dump a graph for debugging |
+| `bun run dev` | Watch-mode HTTP server |
+| `bun run start` | Run the HTTP server |
+| `bun run build` | Build `dist/` (the published artifact) |
+| `bun test` | Run the test suite |
+| `bun run export-graph` | Dump a graph for debugging |
 
 ---
 
 ## Relationship to DevLens OSS
 
-`devlensio` is published to npm and consumed by [DevLens OSS](https://github.com/devlensio/devlensOSS), which provides the `devlens` CLI (`@devlensio/cli`), the MCP server, the `/devlens` Agent Skill, and the Web UI on top of this engine. The CLI binaries bundle whatever version of `devlensio` resolves at build time, so engine fixes ship to users after a `devlensio` release **and** a bump of the dependency pin in DevLens OSS.
+`devlensio` is published to npm and consumed by [DevLens OSS](https://github.com/devlensio/devlensOSS), which provides the CLI, MCP server, Agent Skill, and Web UI on top of this engine.
+
+The CLI binaries bundle whatever version of `devlensio` resolves at build time — so engine fixes ship to users after a `devlensio` release **and** a bump of the dependency pin in DevLens OSS.
 
 ---
 

package/dist/config/index.d.ts

@@ -1,10 +1,22 @@
-import { type DevLensConfig } from "./types.js";
+import { type DevLensConfig, type ProviderConfigEntry } 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 { maskConfig, writeConfig, atomicWrite } 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";
+export type { ProviderConfigEntry, MultiProviderStorage } from "./types.js";
+export { makeProviderKey, parseProviderKey } from "./types.js";
+export interface AllProvidersResult {
+    active: string;
+    providers: ProviderConfigEntry[];
+}
+/** Return ALL configured providers (from disk) — for the frontend settings UI. */
+export declare function resolveAllProviders(): AllProvidersResult;
+/** Switch the active provider by composite key. */
+export declare function setActiveProvider(key: string): void;
+/** Remove a provider entry by composite key. Cannot remove the active provider. */
+export declare function removeProvider(key: string): void;

package/dist/config/index.js

@@ -1,6 +1,9 @@
-import { OLLAMA_DEFAULTS, ANTHROPIC_DEFAULTS } from "./types.js";
+import { OLLAMA_DEFAULTS, ANTHROPIC_DEFAULTS, makeProviderKey } from "./types.js";
 import { loadFileConfig } from "./providers/file.js";
 import { applyRequestHeaders } from "./providers/request.js";
+import { atomicWrite } from "./writer.js";
+import { CONFIG_FILE } from "./providers/paths.js";
+import fs from "fs";
 //  Ollama Detection 
 //
 // Pings Ollama's default endpoint at server startup.
@@ -72,7 +75,79 @@ export function resolveConfig(req) {
     // Step 4 — apply header overrides for cloud users
     return applyRequestHeaders(fileConfig, req);
 }
-export { maskConfig, writeConfig } from "./writer.js";
+export { maskConfig, writeConfig, atomicWrite } 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";
+export { makeProviderKey, parseProviderKey } from "./types.js";
+/** Read the raw multi-provider storage from config.json (no defaults applied). */
+function readProviderStorage() {
+    if (!fs.existsSync(CONFIG_FILE))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
+        const s = raw?.summarization;
+        // Detect multi-provider format
+        if (s && typeof s === "object" && s.providers && typeof s.providers === "object" && typeof s.active === "string") {
+            return s;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Return ALL configured providers (from disk) — for the frontend settings UI. */
+export function resolveAllProviders() {
+    const storage = readProviderStorage();
+    if (storage) {
+        return {
+            active: storage.active,
+            providers: Object.values(storage.providers),
+        };
+    }
+    // Fallback: use the resolved active config to synthesise one entry
+    const config = loadFileConfig(ANTHROPIC_DEFAULTS);
+    const key = makeProviderKey(config.summarization.provider, config.summarization.providerName ?? config.summarization.provider);
+    return {
+        active: key,
+        providers: [{
+                provider: config.summarization.provider,
+                providerName: config.summarization.providerName ?? config.summarization.provider,
+                model: config.summarization.model,
+                apiKey: config.summarization.apiKey,
+                baseUrl: config.summarization.baseUrl,
+                batchSize: config.summarization.batchSize,
+            }],
+    };
+}
+/** Switch the active provider by composite key. */
+export function setActiveProvider(key) {
+    const storage = readProviderStorage();
+    if (!storage)
+        throw new Error("No multi-provider config found. Save a provider first.");
+    if (!storage.providers[key])
+        throw new Error(`Provider "${key}" not found in config.`);
+    storage.active = key;
+    if (!fs.existsSync(CONFIG_FILE))
+        throw new Error("Config file missing.");
+    const raw = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
+    raw.summarization = storage;
+    atomicWrite(CONFIG_FILE, JSON.stringify(raw, null, 2));
+}
+/** Remove a provider entry by composite key. Cannot remove the active provider. */
+export function removeProvider(key) {
+    const storage = readProviderStorage();
+    if (!storage)
+        throw new Error("No multi-provider config found.");
+    if (!storage.providers[key])
+        throw new Error(`Provider "${key}" not found.`);
+    if (storage.active === key)
+        throw new Error(`Cannot remove the active provider. Switch to another provider first.`);
+    delete storage.providers[key];
+    if (!fs.existsSync(CONFIG_FILE))
+        throw new Error("Config file missing.");
+    const raw = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
+    raw.summarization = storage;
+    atomicWrite(CONFIG_FILE, JSON.stringify(raw, null, 2));
+}

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

@@ -0,0 +1,27 @@
+export interface CatalogProvider {
+    name: string;
+    label: string;
+    protocol: "openai" | "anthropic";
+    baseUrl: string;
+    requiresKey: boolean;
+}
+/** Same shape as CatalogProvider — input type for saveProvider. */
+export type CatalogProviderInput = CatalogProvider;
+export declare function loadCatalog(): CatalogProvider[];
+export declare function findProvider(name: string): CatalogProvider | undefined;
+/** Returns only the user's overrides (not merged with defaults). */
+export declare function listUserProviders(): CatalogProvider[];
+/**
+ * Upsert a provider entry in the user's providers.json.
+ * Validates the entry before writing. Returns the entry as written.
+ * The user file only stores the override layer — never the merged result.
+ */
+export declare function saveProvider(entry: CatalogProviderInput): CatalogProvider;
+/**
+ * Remove a user override entry by name.
+ * Returns true if an entry was removed, false if it wasn't present.
+ * Only removes entries from the user file — default providers cannot be removed.
+ */
+export declare function removeProvider(name: string): boolean;
+/** Delete the entire user providers.json — catalog reverts to shipped defaults. */
+export declare function resetUserCatalog(): void;

package/dist/config/providers/catalog.js

@@ -0,0 +1,130 @@
+import fs from "fs";
+import path from "path";
+import { CONFIG_DIR } from "./paths.js";
+import { DEFAULT_PROVIDERS } from "./providers.default.js";
+// ─── Paths ───────────────────────────────────────────────────────────────────
+const USER_CATALOG_FILE = path.join(CONFIG_DIR, "providers.json");
+// ─── Atomic write helper ─────────────────────────────────────────────────────
+// Matches the existing pattern in writer.ts and fileStorage.ts.
+function atomicWrite(filePath, content) {
+    const tmp = `${filePath}.tmp`;
+    fs.writeFileSync(tmp, content, "utf-8");
+    fs.renameSync(tmp, filePath);
+}
+// ─── Validation ──────────────────────────────────────────────────────────────
+const VALID_PROTOCOLS = new Set(["openai", "anthropic"]);
+const RESERVED_NAMES = new Set(["__custom__"]);
+function validateProvider(entry) {
+    const { name, label, protocol, baseUrl, requiresKey } = entry;
+    if (typeof name !== "string" || !/^[a-z0-9-]+$/.test(name) || name.length === 0) {
+        throw new Error(`Invalid provider name: "${name}". Must be non-empty, lowercase alphanumeric with hyphens.`);
+    }
+    if (RESERVED_NAMES.has(name)) {
+        throw new Error(`"${name}" is a reserved name and cannot be used as a provider name.`);
+    }
+    if (typeof label !== "string" || label.trim().length === 0) {
+        throw new Error("Provider label is required and must be non-empty.");
+    }
+    if (!VALID_PROTOCOLS.has(protocol)) {
+        throw new Error(`Protocol must be "openai" or "anthropic", got "${protocol}".`);
+    }
+    if (typeof baseUrl !== "string" || baseUrl.length === 0) {
+        throw new Error("baseUrl is required.");
+    }
+    try {
+        const parsed = new URL(baseUrl);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            throw new Error();
+        }
+    }
+    catch {
+        throw new Error(`baseUrl must be a valid http(s) URL, got "${baseUrl}".`);
+    }
+    if (typeof requiresKey !== "boolean") {
+        throw new Error("requiresKey must be a boolean.");
+    }
+}
+// ─── Read user file (unmerged, warn on malformed) ────────────────────────────
+function readUserFile() {
+    if (!fs.existsSync(USER_CATALOG_FILE))
+        return [];
+    try {
+        const raw = fs.readFileSync(USER_CATALOG_FILE, "utf-8");
+        const parsed = JSON.parse(raw);
+        return parsed.providers ?? [];
+    }
+    catch {
+        console.warn(`DevLens: ~/.devlens/providers.json contains invalid JSON. ` +
+            `Treating it as empty.`);
+        return [];
+    }
+}
+// ─── Ensure CONFIG_DIR exists ───────────────────────────────────────────────
+function ensureConfigDir() {
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+}
+// ─── Public read API ─────────────────────────────────────────────────────────
+export function loadCatalog() {
+    const defaults = DEFAULT_PROVIDERS;
+    const userProviders = readUserFile();
+    if (userProviders.length === 0)
+        return defaults;
+    const merged = new Map();
+    for (const p of defaults)
+        merged.set(p.name, p);
+    for (const p of userProviders) {
+        merged.set(p.name, { ...p });
+    }
+    return [...merged.values()];
+}
+export function findProvider(name) {
+    return loadCatalog().find(p => p.name === name);
+}
+/** Returns only the user's overrides (not merged with defaults). */
+export function listUserProviders() {
+    return readUserFile();
+}
+// ─── Public write API ────────────────────────────────────────────────────────
+/**
+ * Upsert a provider entry in the user's providers.json.
+ * Validates the entry before writing. Returns the entry as written.
+ * The user file only stores the override layer — never the merged result.
+ */
+export function saveProvider(entry) {
+    validateProvider(entry);
+    const existing = readUserFile();
+    const idx = existing.findIndex(p => p.name === entry.name);
+    const clean = { name: entry.name, label: entry.label, protocol: entry.protocol, baseUrl: entry.baseUrl, requiresKey: entry.requiresKey };
+    if (idx >= 0) {
+        existing[idx] = clean;
+    }
+    else {
+        existing.push(clean);
+    }
+    ensureConfigDir();
+    atomicWrite(USER_CATALOG_FILE, JSON.stringify({ version: 2, providers: existing }, null, 2));
+    return clean;
+}
+/**
+ * Remove a user override entry by name.
+ * Returns true if an entry was removed, false if it wasn't present.
+ * Only removes entries from the user file — default providers cannot be removed.
+ */
+export function removeProvider(name) {
+    const existing = readUserFile();
+    const idx = existing.findIndex(p => p.name === name);
+    if (idx === -1)
+        return false;
+    existing.splice(idx, 1);
+    ensureConfigDir();
+    atomicWrite(USER_CATALOG_FILE, JSON.stringify({ version: 2, providers: existing }, null, 2));
+    return true;
+}
+/** Delete the entire user providers.json — catalog reverts to shipped defaults. */
+export function resetUserCatalog() {
+    if (fs.existsSync(USER_CATALOG_FILE)) {
+        fs.unlinkSync(USER_CATALOG_FILE);
+    }
+}

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

@@ -1,8 +1,8 @@
 import { type DevLensConfig } from "../types.js";
-export declare const CONFIG_DIR: string;
-export declare const CONFIG_FILE: string;
+export { CONFIG_DIR, CONFIG_FILE } from "./paths.js";
 export declare const ENV: {
     readonly LLM_PROVIDER: "DEVLENS_LLM_PROVIDER";
+    readonly LLM_PROVIDER_NAME: "DEVLENS_LLM_PROVIDER_NAME";
     readonly LLM_MODEL: "DEVLENS_LLM_MODEL";
     readonly LLM_KEY: "DEVLENS_LLM_KEY";
     readonly LLM_BASE_URL: "DEVLENS_LLM_BASE_URL";
@@ -16,4 +16,6 @@ export declare const ENV: {
     readonly NEO4J_PASSWORD: "DEVLENS_NEO4J_PASSWORD";
     readonly NEO4J_STORECODE: "NEO4J_STORE_CODE";
 };
+/** Public — reads the raw config.json as a plain object. Used by multi-provider helpers. */
+export declare function readRawConfigFile(): Record<string, unknown>;
 export declare function loadFileConfig(defaults?: DevLensConfig): DevLensConfig;