codesearch-mcp 0.2.2-alpha → 0.3.0-alpha

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codesearch-mcp",
-  "version": "0.2.2-alpha",
+  "version": "0.3.0-alpha",
   "description": "Local semantic codebase search via MCP — indexes projects into pgvector, exposes search to Claude",
   "license": "MIT",
   "keywords": [
@@ -29,7 +29,7 @@
   "files": [
     "dist/",
     "docker/",
-    "docs/",
+    "docs/architecture.svg",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -42,23 +42,24 @@
     "start:web": "ts-node app.ts web",
     "index:workspace": "ts-node app.ts index",
     "index:reindex": "ts-node app.ts index --reindex",
+    "index:project": "ts-node app.ts index --project",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
     "verify": "tsc --noEmit && vitest run"
   },
   "dependencies": {
-    "@inquirer/prompts": "^8.4.1",
-    "@langchain/textsplitters": "^1.0.1",
-    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@inquirer/prompts": "^8.7.3",
+    "@langchain/textsplitters": "^1.0.2",
+    "@modelcontextprotocol/sdk": "1.32.0",
     "cli-progress": "^3.12.0",
     "drizzle-orm": "^0.45.2",
     "ignore": "^7.0.5",
-    "pg": "^8.13.0",
-    "pino": "^10.3.1",
+    "pg": "^8.23.1",
+    "pino": "^10.4.0",
     "pino-roll": "^4.0.0",
     "ts-morph": "^28.0.0",
-    "zod": "^4.3.6"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@types/cli-progress": "^3.11.6",
@@ -66,6 +67,6 @@
     "@types/pg": "^8.20.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.6.0",
-    "vitest": "^4.1.4"
+    "vitest": "^5.0.5"
   }
 }

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

@@ -1,42 +0,0 @@
-import type { Config } from '../config';
-import type { IChunker, ChunkPiece, ChunkOpts } from '../interfaces/IChunker';
-/**
- * Splits TS/JS source into embeddable pieces aligned to top-level declaration
- * ranges (AST strategy). Falls back to the character-based recursive splitter
- * for schema files, files without symbol analysis, or when strategy is
- * 'character' — that path is byte-for-byte the previous behavior.
- */
-export declare class AstChunker implements IChunker {
-    private config;
-    private readonly jsSplitter;
-    private readonly schemaSplitter;
-    private readonly chunkSize;
-    constructor(config: Config);
-    chunk(code: string, opts: ChunkOpts): Promise<ChunkPiece[]>;
-    private produce;
-    /**
-     * True iff every significant line (blank and comment lines stripped) belongs
-     * to an `import` / re-export statement and at least one is an import or
-     * re-export keyword — so the chunk carries no value/type declaration and is
-     * never a search answer. Any `export const|let|var|function|class|interface|
-     * enum|namespace|default|declare|async function|type X = …` disqualifies
-     * exclusion. Pure. Distinguishes `export { … } from` / `export type { … }`
-     * (re-export → drop) from `export type X = …` (declaration → keep).
-     */
-    static isImportOrReexportOnly(content: string): boolean;
-    /** Character-splitter path for a whole file; line numbers from splitter metadata. */
-    private splitWholeFile;
-    private chunkByAst;
-    /**
-     * Build disjoint, sorted line intervals from symbol ranges. Overlapping /
-     * nested ranges merge into the outermost (a merged region covers any symbol
-     * inside it). Ranges are clamped to the file's line count.
-     */
-    private static buildIntervals;
-    /**
-     * Emit pieces for a 1-based inclusive line region. Whitespace-only gaps are
-     * dropped; regions longer than chunkSize are sub-split with the char splitter,
-     * with sub-piece line numbers offset back to absolute file lines.
-     */
-    private regionPieces;
-}

package/dist/src/services/AstChunker.js

@@ -1,158 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AstChunker = void 0;
-const textsplitters_1 = require("@langchain/textsplitters");
-/**
- * Splits TS/JS source into embeddable pieces aligned to top-level declaration
- * ranges (AST strategy). Falls back to the character-based recursive splitter
- * for schema files, files without symbol analysis, or when strategy is
- * 'character' — that path is byte-for-byte the previous behavior.
- */
-class AstChunker {
-    config;
-    jsSplitter;
-    schemaSplitter;
-    chunkSize;
-    constructor(config) {
-        this.config = config;
-        this.chunkSize = config.indexer.chunkSize;
-        this.jsSplitter = textsplitters_1.RecursiveCharacterTextSplitter.fromLanguage('js', {
-            chunkSize: config.indexer.chunkSize,
-            chunkOverlap: config.indexer.chunkOverlap,
-        });
-        this.schemaSplitter = new textsplitters_1.RecursiveCharacterTextSplitter({
-            chunkSize: config.indexer.chunkSize,
-            chunkOverlap: config.indexer.chunkOverlap,
-            separators: ['\n\n', '\n', ' '],
-        });
-    }
-    async chunk(code, opts) {
-        const pieces = await this.produce(code, opts);
-        // Single post-chunk pass: drop pieces whose only significant content is
-        // import / re-export statements. Both chunk sources — AST "gap" regions and
-        // the whole-file character path for barrel files — can emit these, so we
-        // filter once over the final pieces. Dependency edges are untouched (they
-        // come from analyzeProject → code_dependency, not from chunk text).
-        return pieces.filter(p => !AstChunker.isImportOrReexportOnly(p.content));
-    }
-    async produce(code, opts) {
-        if (opts.isSchemaFile) {
-            return this.splitWholeFile(code, this.schemaSplitter);
-        }
-        if (opts.strategy === 'character' || opts.symbols.length === 0) {
-            return this.splitWholeFile(code, this.jsSplitter);
-        }
-        return this.chunkByAst(code, opts.symbols);
-    }
-    /**
-     * True iff every significant line (blank and comment lines stripped) belongs
-     * to an `import` / re-export statement and at least one is an import or
-     * re-export keyword — so the chunk carries no value/type declaration and is
-     * never a search answer. Any `export const|let|var|function|class|interface|
-     * enum|namespace|default|declare|async function|type X = …` disqualifies
-     * exclusion. Pure. Distinguishes `export { … } from` / `export type { … }`
-     * (re-export → drop) from `export type X = …` (declaration → keep).
-     */
-    static isImportOrReexportOnly(content) {
-        const lines = content
-            .replace(/\/\*[\s\S]*?\*\//g, '') // strip block comments
-            .split('\n')
-            .map(l => l.trim())
-            .filter(l => l !== '' && !l.startsWith('//') && !l.startsWith('*'));
-        if (lines.length === 0)
-            return false;
-        const IMPORT = /^import\b/;
-        const REEXPORT = /^export\s+(\*|type\s+\{|\{)/; // export * | export type { | export {
-        const DISQUALIFY = /^export\s+(default|async\b|function\b|const\b|let\b|var\b|class\b|abstract\b|interface\b|enum\b|namespace\b|declare\b|type\s+[A-Za-z_$])/;
-        const CONTINUATION = /^(\}?\s*from\s+['"][^'"]+['"];?|[{}]|(type\s+)?[A-Za-z_$][\w$]*(\s+as\s+[A-Za-z_$][\w$]*)?,?|['"][^'"]*['"];?)$/;
-        let keywords = 0;
-        for (const line of lines) {
-            if (DISQUALIFY.test(line))
-                return false;
-            if (IMPORT.test(line) || REEXPORT.test(line)) {
-                keywords++;
-                continue;
-            }
-            if (CONTINUATION.test(line))
-                continue;
-            return false; // unrecognized line → real code, keep the chunk
-        }
-        return keywords >= 1;
-    }
-    /** Character-splitter path for a whole file; line numbers from splitter metadata. */
-    async splitWholeFile(code, splitter) {
-        const docs = await splitter.createDocuments([code]);
-        return docs.map((d) => {
-            const from = (d.metadata?.loc?.lines?.from ?? 1);
-            const to = (d.metadata?.loc?.lines?.to ?? from);
-            return { content: d.pageContent, startLine: from, endLine: to };
-        });
-    }
-    async chunkByAst(code, symbols) {
-        const lines = code.split('\n');
-        const total = lines.length;
-        const intervals = AstChunker.buildIntervals(symbols, total);
-        const pieces = [];
-        let cursor = 1;
-        for (const iv of intervals) {
-            if (cursor < iv.start) {
-                pieces.push(...await this.regionPieces(lines, cursor, iv.start - 1, true));
-            }
-            pieces.push(...await this.regionPieces(lines, iv.start, iv.end, false));
-            cursor = iv.end + 1;
-        }
-        if (cursor <= total) {
-            pieces.push(...await this.regionPieces(lines, cursor, total, true));
-        }
-        return pieces;
-    }
-    /**
-     * Build disjoint, sorted line intervals from symbol ranges. Overlapping /
-     * nested ranges merge into the outermost (a merged region covers any symbol
-     * inside it). Ranges are clamped to the file's line count.
-     */
-    static buildIntervals(symbols, total) {
-        const raw = symbols
-            .filter(s => s.line != null && s.line >= 1 && s.line <= total)
-            .map(s => ({
-            start: s.line,
-            end: Math.min(Math.max(s.endLine ?? s.line, s.line), total),
-        }))
-            .sort((a, b) => a.start - b.start || b.end - a.end);
-        const merged = [];
-        for (const iv of raw) {
-            const last = merged[merged.length - 1];
-            if (last && iv.start <= last.end) {
-                last.end = Math.max(last.end, iv.end);
-            }
-            else {
-                merged.push({ ...iv });
-            }
-        }
-        return merged;
-    }
-    /**
-     * Emit pieces for a 1-based inclusive line region. Whitespace-only gaps are
-     * dropped; regions longer than chunkSize are sub-split with the char splitter,
-     * with sub-piece line numbers offset back to absolute file lines.
-     */
-    async regionPieces(lines, start, end, isGap) {
-        const text = lines.slice(start - 1, end).join('\n');
-        if (isGap && text.trim() === '')
-            return [];
-        if (text.length <= this.chunkSize) {
-            return [{ content: text, startLine: start, endLine: end }];
-        }
-        const docs = await this.jsSplitter.createDocuments([text]);
-        return docs.map((d) => {
-            const from = (d.metadata?.loc?.lines?.from ?? 1);
-            const to = (d.metadata?.loc?.lines?.to ?? from);
-            return {
-                content: d.pageContent,
-                startLine: start + from - 1,
-                endLine: start + to - 1,
-            };
-        });
-    }
-}
-exports.AstChunker = AstChunker;

package/docs/web-dashboard.md

@@ -1,206 +0,0 @@
-# Web dashboard (`rag-web`)
-
-A local web UI for configuring and inspecting the RAG server. It provides a
-schema-driven config editor, an overview of indexed projects, and an interactive
-project-dependency graph — all served from a small built-in HTTP server with no
-external framework and no new dependencies (`node:http`).
-
-The dashboard is a thin presentation layer over primitives that already exist:
-config I/O and validation (`src/config-store.ts`), project data
-(`SearcherService.listProjects`), and the graph builder (`src/graph.ts`). It adds
-no business logic of its own beyond request routing and a password-preservation
-merge.
-
----
-
-## Running
-
-```bash
-rag-web                 # http://127.0.0.1:4319
-rag-web --port 8080     # custom port
-npm run start:web       # dev mode (ts-node, no build)
-```
-
-If the `rag-web` binary is not on your `PATH`, either run it from the project
-(`node dist/app.js web`) or register it once with `npm link`.
-
-Keep the terminal open — the server runs until you press `Ctrl+C`. The browser
-can only reach the dashboard while the process is alive.
-
----
-
-## Security model
-
-- **Binds to `127.0.0.1` only.** The server is never exposed on the network;
-  it is a single-user local dev tool, so there is no authentication.
-- **The DB password is never sent to the browser.** `GET /api/config` returns it
-  masked as `********`. On save, if the field is still the mask, the stored
-  password is preserved (`mergeConfigForSave`); a genuinely changed value is
-  written through.
-- **No arbitrary file serving.** Only the known routes below respond; there is no
-  static file handler, so no path-traversal surface.
-
----
-
-## Requirements & failure modes
-
-- Requires a valid `config.json` — `rag-web` goes through the normal container
-  bootstrap and `workspaceRoot` guard. To repair a broken config, use
-  `rag-config edit` (CLI) instead.
-- A failed **DB** connection is non-fatal: the config editor still works; the
-  Projects and Graph tabs show an in-page error.
-- A failed **embedding backend** connection only affects model suggestions (see
-  *Field options*); everything else works.
-
----
-
-## UI tabs
-
-### Config
-A form generated from the config JSON Schema (`buildJsonSchema()` — the same
-schema that powers editor autocomplete on `config.json`). Fields are grouped by
-section and typed automatically:
-
-| Schema shape | Rendered as |
-|---|---|
-| `boolean` | checkbox |
-| `enum` (e.g. `logging.level`) | `<select>` |
-| `integer` / `number` | number input (with sensible `min`/`max`/`step`) |
-| `string` | text input |
-| field in `/api/field-options`, `strict` | `<select>` limited to the list |
-| field in `/api/field-options`, non-strict | text input + `<datalist>` (combobox) |
-
-Two affordances make the effective configuration obvious:
-
-- **Defaults.** Any key left unset shows `↪ using default: <value>` (amber) and
-  the applied value as the input placeholder. A key that *is* set shows a muted
-  `default: <value>` for reference. Source: `GET /api/defaults`
-  (`CONFIG_DEFAULTS`).
-- **Field options.** Fields whose valid values are constrained get a dropdown
-  instead of free text. Source: `GET /api/field-options`. See below.
-
-Saving validates through `parseConfig` and, on failure, shows the validation
-message and highlights the offending fields; on success the config is written
-(with the `$schema` reference preserved) and the form reloads.
-
-### Projects
-Cards for each indexed project from `SearcherService.listProjects()` — name,
-chunk count, and any `.ragmeta.json` metadata (stack, description, relations).
-
-### Graph
-The **full standalone graph page embedded in an `<iframe>`** (`src="/graph"`),
-loaded lazily on first open. `GET /graph` serves the exact same HTML as the
-generated `project-graph.html` (`buildHtml()` in `src/graph.ts`), so the whole
-sidebar comes for free: the node-color legend, the edge-type filter buttons, and
-the project toggle list, plus hover highlighting and auto-fit. The dashboard
-does **not** re-implement vis-network — reusing one page keeps the two graph
-views identical. `GET /api/graph` still returns the raw `{ nodes, edges }` JSON
-(`buildGraphData()`) for programmatic use.
-
----
-
-## Field options (model dropdowns)
-
-Some settings have a constrained set of valid values, so the form offers a list
-rather than free text. `GET /api/field-options` returns
-`{ [dottedKey]: { values: string[], strict: boolean } }`:
-
-- **`embedding.model`, `reranker.model` — non-strict.** `embedding.model`
-  suggests `MODEL_REGISTRY` (`src/constants.ts`) entries plus any model the
-  backend currently serves; `reranker.model` suggests only served models. Both
-  allow free text — a model outside the registry still works (its dimension is
-  probed at index time). Served models come from `IEmbedder.listModels()`,
-  implemented only by `InfinityEmbedder` (2-second-limited `/models` listing);
-  if the backend is unreachable, or the provider doesn't implement `listModels`
-  (`openai-compatible`, `voyage`), the served-model list is empty and the field
-  degrades to registry suggestions only (or plain text for `reranker.model`).
-
-A strict `<select>` preserves an unknown current value as an extra option, so
-saving never silently drops a value that isn't in the list.
-
----
-
-## HTTP API
-
-All routes are served from `127.0.0.1:<port>`.
-
-| Method | Path | Response |
-|---|---|---|
-| `GET`  | `/` | Dashboard HTML (self-contained) |
-| `GET`  | `/api/schema` | JSON Schema of the config (`buildJsonSchema()`) |
-| `GET`  | `/api/defaults` | `CONFIG_DEFAULTS` — dotted key → default value |
-| `GET`  | `/api/field-options` | dotted key → `{ values, strict }` |
-| `GET`  | `/api/config` | Current config, `db.password` masked |
-| `PUT`  | `/api/config` | Save. Body = config JSON. `200 {ok:true, backend:{action,message}}` or `400 {error}`. For `embedding.provider: infinity`, `backend.action` reports whether the Infinity container needed a background recreate (`started`/`already-running`/`not-needed`/`manual-required`/`failed`) — see *Infinity backend recreate* below |
-| `GET`  | `/api/backend-status` | `{ state, message, startedAt, finishedAt }` — progress of the most recent background Infinity recreate this server process started |
-| `GET`  | `/api/projects` | `SearcherService.listProjects()` |
-| `GET`  | `/api/graph` | `{ nodes, edges }` JSON (`buildGraphData()`) |
-| `GET`  | `/graph` | Full interactive graph page (`buildHtml()`), embedded by the Graph tab's iframe |
-
----
-
-## Infinity backend recreate
-
-When a save's `embedding.provider` is `infinity`, the server computes the
-required model set from the **saved** config (freshly re-read from disk, not
-the embedder the process started with) and compares it against what the
-backend currently serves. If a managed container needs to be started or
-recreated to serve the new set, that runs as an in-process background task —
-the `PUT` responds immediately (`action: "started"`) without waiting for it.
-Poll `GET /api/backend-status` for progress (`state: "recreating"` →
-`"ready"`/`"failed"`). Only one `docker compose` run is active at a time; a
-save that arrives while a recreate is already in flight for a managed backend
-responds `already-running`, and at most one follow-up run applies the latest
-such save once the in-flight one finishes. An external (unmanaged) backend
-missing a required model never triggers Docker — the response's `message`
-carries manual `--model-id`/launch instructions instead.
-
----
-
-## Architecture
-
-| File | Responsibility |
-|---|---|
-| `src/commands/WebCommand.ts` | CLI entry. `db.initDb()`, starts the server, keeps `execute()` pending until `SIGINT`/`SIGTERM` (mirrors `McpCommand`), then `server.stop()`. Parses `--port` (default `4319`). |
-| `src/services/WebServerService.ts` | `WebServer(searcher, config, logger, embedder, deps?)` — `node:http` server, routing, the API handlers, and the background Infinity recreate + `/api/backend-status` state. Exports the pure `mergeConfigForSave()` and the `FieldOption` type. |
-| `src/services/infinity-provisioning.ts` | The readiness/recreate primitive the background task delegates to (shared with `InfinityEmbedder` and `rag-setup`) — classification, compose-file rewrite, `docker compose` invocation, readiness polling. |
-| `src/web/dashboard.ts` | `renderDashboardHtml()` — the entire page (HTML + CSS + JS) as one self-contained string, mirroring `graph.ts:buildHtml`. |
-
-Reused primitives (no duplication):
-
-- `readConfigJson` / `parseConfig` / `writeConfigJson` / `buildJsonSchema` /
-  `CONFIG_DEFAULTS` — `src/config-store.ts`
-- `buildGraphData` — `src/graph.ts`
-- `listProjects` — `src/services/SearcherService.ts`
-- `MODEL_REGISTRY` — `src/constants.ts`
-- `evaluateBackend` / `ensureModelSetServed` / `requiredModelSet` — `src/services/infinity-provisioning.ts`
-
-Wiring: `app.ts` detects the `web` mode and dispatches
-`new WebCommand(container, effectiveArgs)`. The command uses the shared
-`Container` services (`db`, `searcher`, `config`, `logger`) — no container
-changes were needed.
-
----
-
-## Extending
-
-- **Constrain another field to a list** — add an entry to `fieldOptions()` in
-  `WebServerService.ts` (`{ values, strict }`). The form renders it automatically
-  (strict → dropdown, non-strict → combobox).
-- **Add a tab / endpoint** — add a route in `WebServer.handle`, a fetch + render
-  in `dashboard.ts`, and a tab button. Keep handlers thin — delegate to a service.
-- **Actions (e.g. trigger reindex)** — deferred by design. This is heavier (a
-  long-running process with live progress, likely via SSE, plus concurrency
-  control) and belongs in its own change rather than the read/config-edit shell.
-
----
-
-## Keep in sync
-
-- `CONFIG_DEFAULTS` (`config-store.ts`) is the **single source of truth** for
-  built-in defaults: `resolvedSchema` in `config.ts` references it in its
-  `.default(...)` calls, so the runtime default and the dashboard-displayed
-  default cannot diverge — no manual sync needed. (A unit test still asserts
-  every key is a valid config key.)
-- `MODEL_REGISTRY` (`constants.ts`) is advisory, not exhaustive — a model
-  outside it still works via the runtime dimension probe at index time.