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

package/dist/src/graph.js

@@ -33,10 +33,80 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildGraphData = buildGraphData;
+exports.buildGraphViews = buildGraphViews;
+exports.buildHtml = buildHtml;
 exports.generateProjectGraph = generateProjectGraph;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const file_utils_1 = require("./file-utils");
+const EMPTY_META = { description: null, stack: null, notes: null, relations: null };
+/**
+ * Build the project graph data (nodes + relation edges) from a project list.
+ * Pure apart from reading each project's `.ragmeta.json`. Shared by the console
+ * graph, the graph views, and the web dashboard's `/api/graph`.
+ */
+function buildGraphData(projects) {
+    const nodes = projects.map(p => {
+        const meta = (0, file_utils_1.readRagMeta)(p.path);
+        return { name: p.name, ...(typeof meta === 'object' ? meta : EMPTY_META) };
+    });
+    return { nodes, edges: buildEdges(nodes) };
+}
+/**
+ * Split a project list into graph tabs. A project whose name contains a `/`
+ * belongs to a nested Nx repo (`<repo>/<sub-project>`); everything else is a
+ * flat top-level project.
+ *
+ * - **Workspace** tab: flat projects + one node per Nx repo (collapsed to a
+ *   single `nxRepo` node); edges from `.ragmeta.json` relations.
+ * - **One tab per Nx repo**: its sub-projects as nodes, with edges between them
+ *   taken from real import dependencies (`projectEdges`, from `code_dependency`).
+ *
+ * Returns the Workspace view first, then repo views sorted by name.
+ */
+function buildGraphViews(projects, projectEdges, workspaceRoot) {
+    const flat = [];
+    const groups = new Map();
+    for (const p of projects) {
+        const slash = p.name.indexOf('/');
+        if (slash > 0) {
+            const repo = p.name.slice(0, slash);
+            let list = groups.get(repo);
+            if (!list) {
+                list = [];
+                groups.set(repo, list);
+            }
+            list.push(p);
+        }
+        else {
+            flat.push(p);
+        }
+    }
+    const repoNames = [...groups.keys()].sort();
+    // Workspace: flat projects + one collapsed node per repo (reads repo-root ragmeta).
+    const workspaceProjects = [
+        ...flat,
+        ...repoNames.map(repo => ({ name: repo, path: path.join(workspaceRoot, repo) })),
+    ];
+    const ws = buildGraphData(workspaceProjects);
+    const repoSet = new Set(repoNames);
+    for (const n of ws.nodes)
+        if (repoSet.has(n.name))
+            n.nxRepo = true;
+    const workspace = { name: 'Workspace', nodes: ws.nodes, edges: ws.edges };
+    // Per-repo: sub-project nodes + intra-repo import edges.
+    const repoViews = repoNames.map(repo => {
+        const subs = groups.get(repo);
+        const { nodes } = buildGraphData(subs);
+        const names = new Set(subs.map(s => s.name));
+        const edges = projectEdges
+            .filter(e => names.has(e.from) && names.has(e.to))
+            .map(e => ({ from: e.from, to: e.to, label: 'imports' }));
+        return { name: repo, nodes, edges };
+    });
+    return [workspace, ...repoViews];
+}
 function buildEdges(nodes) {
     const edges = [];
     for (const node of nodes) {
@@ -50,49 +120,68 @@ function buildEdges(nodes) {
     }
     return edges;
 }
-function escHtml(s) {
-    return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
-function printConsole(nodes, edges, workspacePath) {
-    if (edges.length === 0)
-        return;
-    console.log('\n=== Project Relations ===');
-    const grouped = new Map();
-    for (const e of edges) {
-        if (!grouped.has(e.from))
-            grouped.set(e.from, []);
-        grouped.get(e.from).push(e);
-    }
-    for (const [from, fromEdges] of grouped) {
-        const byLabel = new Map();
-        for (const e of fromEdges) {
-            if (!byLabel.has(e.label))
-                byLabel.set(e.label, []);
-            byLabel.get(e.label).push(e);
+function printConsole(views, workspacePath) {
+    const workspace = views[0];
+    const repoViews = views.slice(1);
+    if (workspace.edges.length > 0) {
+        console.log('\n=== Project Relations ===');
+        const grouped = new Map();
+        for (const e of workspace.edges) {
+            if (!grouped.has(e.from))
+                grouped.set(e.from, []);
+            grouped.get(e.from).push(e);
         }
-        for (const [label, labelEdges] of byLabel) {
-            const targets = labelEdges.map(e => e.to).join(', ');
-            console.log(`  ${from.padEnd(30)} → ${targets.padEnd(30)} [${label}]`);
+        for (const [from, fromEdges] of grouped) {
+            const byLabel = new Map();
+            for (const e of fromEdges) {
+                if (!byLabel.has(e.label))
+                    byLabel.set(e.label, []);
+                byLabel.get(e.label).push(e);
+            }
+            for (const [label, labelEdges] of byLabel) {
+                const targets = labelEdges.map(e => e.to).join(', ');
+                console.log(`  ${from.padEnd(30)} → ${targets.padEnd(30)} [${label}]`);
+            }
         }
     }
-    console.log(`\n  Full graph: file://${path.join(workspacePath, 'project-graph.html')}`);
+    for (const v of repoViews) {
+        console.log(`  Nx repo ${v.name.padEnd(24)} ${v.nodes.length} projects · ${v.edges.length} internal edges`);
+    }
+    if (workspace.edges.length > 0 || repoViews.length > 0) {
+        console.log(`\n  Full graph: file://${path.join(workspacePath, 'project-graph.html')}`);
+    }
 }
-function buildHtml(nodes, edges) {
-    const visNodes = nodes.map(n => ({
+/** Prepare a view for vis-network: colored nodes (+ synthetic nodes for unknown edge targets) and indexed edges. */
+function viewToVis(view) {
+    const nodes = view.nodes.map(n => ({
         id: n.name,
         label: n.name,
         title: [n.description, n.stack].filter(Boolean).join('\n') || n.name,
-        color: n.relations ? '#4A90D9' : '#A8C7E8',
+        color: n.nxRepo ? '#B57EDC' : (n.relations ? '#4A90D9' : '#A8C7E8'),
+        ...(n.nxRepo ? { borderWidth: 3 } : {}),
     }));
-    const known = new Set(nodes.map(n => n.name));
-    for (const e of edges) {
-        if (!known.has(e.to)) {
-            visNodes.push({ id: e.to, label: e.to, title: e.to, color: '#E8A838' });
-            known.add(e.to);
+    const known = new Set(view.nodes.map(n => n.name));
+    for (const e of view.edges) {
+        for (const end of [e.from, e.to]) {
+            if (!known.has(end)) {
+                nodes.push({ id: end, label: end, title: end, color: '#E8A838' });
+                known.add(end);
+            }
         }
     }
-    const visEdges = edges.map((e, i) => ({ id: i, from: e.from, to: e.to, label: e.label, arrows: 'to' }));
-    const allLabels = [...new Set(edges.map(e => e.label))].sort();
+    const edges = view.edges.map((e, i) => ({ id: i, from: e.from, to: e.to, label: e.label, arrows: 'to' }));
+    const labels = [...new Set(view.edges.map(e => e.label))].sort();
+    return { name: view.name, nodes, edges, labels };
+}
+/**
+ * Render the full interactive graph page (vis-network + inner tabs, edge-type
+ * filters, legend, project toggle list). Used for the standalone
+ * `project-graph.html` and served by the web dashboard at `GET /graph` (embedded
+ * via iframe) so both share one implementation. Tab 0 is the Workspace view;
+ * double-clicking an Nx-repo node opens that repo's tab.
+ */
+function buildHtml(views) {
+    const visViews = views.map(viewToVis);
     return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -104,7 +193,10 @@ function buildHtml(nodes, edges) {
     body { font-family: system-ui, sans-serif; background: #1a1a2e; color: #eee; display: flex; flex-direction: column; height: 100vh; }
     #header { padding: 14px 20px; background: #16213e; border-bottom: 1px solid #0f3460; display: flex; align-items: center; gap: 20px; flex-shrink: 0; }
     #header h1 { font-size: 16px; font-weight: 600; white-space: nowrap; }
-    #header p  { font-size: 12px; color: #888; }
+    #count { font-size: 12px; color: #888; }
+    #view-tabs { display: flex; gap: 6px; flex-wrap: wrap; }
+    .view-tab { padding: 5px 12px; border-radius: 8px; border: 1px solid #2a3f6a; background: transparent; color: #88aabb; font-size: 12px; cursor: pointer; }
+    .view-tab.active { background: #4A90D9; border-color: #4A90D9; color: #fff; }
     #filters  { display: flex; gap: 8px; flex-wrap: wrap; margin-left: auto; }
     .filter-btn {
       padding: 4px 10px; border-radius: 12px; border: 1px solid #4A90D9;
@@ -133,77 +225,50 @@ function buildHtml(nodes, edges) {
   <div id="header">
     <div>
       <h1>Project Graph</h1>
-      <p>${nodes.length} projects · ${edges.length} edges · ${new Date().toLocaleString()}</p>
-    </div>
-    <div id="filters">
-      ${allLabels.map(l => `<button class="filter-btn" data-label="${escHtml(l)}">${escHtml(l)}</button>`).join('\n      ')}
+      <p id="count"></p>
     </div>
+    <div id="view-tabs"></div>
+    <div id="filters"></div>
   </div>
   <div id="main">
     <div id="network"></div>
     <div id="legend">
       <h3>Nodes</h3>
+      <div class="entry"><span class="dot" style="background:#B57EDC"></span>Nx repo (double-click to open)</div>
       <div class="entry"><span class="dot" style="background:#4A90D9"></span>has .ragmeta.json</div>
-      <div class="entry"><span class="dot" style="background:#5a5a7a"></span>no .ragmeta.json</div>
+      <div class="entry"><span class="dot" style="background:#A8C7E8"></span>no .ragmeta.json</div>
       <div class="entry"><span class="dot" style="background:#E8A838"></span>not indexed</div>
-      <div id="hint">Drag to rearrange.<br>Edge buttons — toggle type.<br>Projects — toggle node.</div>
+      <div id="hint">Drag to rearrange.<br>Edge buttons — toggle type.<br>Projects — toggle node.<br>Double-click an Nx repo to open it.</div>
       <div id="project-list">
         <h3>Projects</h3>
-        ${visNodes.map(n => `<button class="proj-btn" data-node="${escHtml(n.id)}"><span class="proj-dot" style="background:${escHtml(n.color)}"></span>${escHtml(n.label)}</button>`).join('\n        ')}
+        <div id="proj-list-body"></div>
       </div>
     </div>
   </div>
   <script>
-    const allEdges = ${JSON.stringify(visEdges)};
-    const nodesDs = new vis.DataSet(${JSON.stringify(visNodes)});
-    const edgesDs = new vis.DataSet(allEdges);
+    const VIEWS = ${JSON.stringify(visViews)};
 
-    const network = new vis.Network(
-      document.getElementById('network'),
-      { nodes: nodesDs, edges: edgesDs },
-      {
-        nodes: {
-          shape: 'box',
-          font: { color: '#fff', size: 13 },
-          borderWidth: 2,
-          shadow: true,
-          margin: { top: 8, bottom: 8, left: 12, right: 12 },
-        },
-        edges: {
-          font: { color: '#aaa', size: 11, align: 'middle', strokeWidth: 0, background: '#1a1a2e' },
-          color: { color: '#4A90D9', highlight: '#7eb8f7', hover: '#7eb8f7' },
-          smooth: { type: 'curvedCW', roundness: 0.2 },
-          arrows: { to: { scaleFactor: 0.6 } },
-          selectionWidth: 2,
-        },
-        physics: {
-          solver: 'barnesHut',
-          barnesHut: {
-            gravitationalConstant: -18000,
-            springConstant:        0.025,
-            springLength:          280,
-            damping:               0.25,
-          },
-          stabilization: { iterations: 400, updateInterval: 25 },
-        },
-        interaction: { hover: true, tooltipDelay: 80, dragNodes: true },
-      }
-    );
-
-    network.on('stabilizationIterationsDone', () => {
-      network.fit({ animation: { duration: 600, easingFunction: 'easeInOutQuad' } });
-      setTimeout(() => network.setOptions({ physics: { enabled: false } }), 650);
-    });
-
-    network.on('hoverEdge', ({ edge }) => {
-      edgesDs.update({ id: edge, font: { color: '#fff', size: 16, background: '#16213e', strokeWidth: 0 } });
-    });
-    network.on('blurEdge', ({ edge }) => {
-      edgesDs.update({ id: edge, font: { color: '#aaa', size: 11, background: '#1a1a2e', strokeWidth: 0 } });
-    });
+    const NET_OPTIONS = {
+      nodes: { shape: 'box', font: { color: '#fff', size: 13 }, borderWidth: 2, shadow: true, margin: { top: 8, bottom: 8, left: 12, right: 12 } },
+      edges: {
+        font: { color: '#aaa', size: 11, align: 'middle', strokeWidth: 0, background: '#1a1a2e' },
+        color: { color: '#4A90D9', highlight: '#7eb8f7', hover: '#7eb8f7' },
+        smooth: { type: 'curvedCW', roundness: 0.2 },
+        arrows: { to: { scaleFactor: 0.6 } },
+        selectionWidth: 2,
+      },
+      physics: {
+        solver: 'barnesHut',
+        barnesHut: { gravitationalConstant: -18000, springConstant: 0.025, springLength: 280, damping: 0.25 },
+        stabilization: { iterations: 400, updateInterval: 25 },
+      },
+      interaction: { hover: true, tooltipDelay: 80, dragNodes: true },
+    };
 
-    const activeLabels = new Set(${JSON.stringify(allLabels)});
-    const hiddenNodes  = new Set();
+    let active = -1;
+    let network = null;
+    let nodesDs = null, edgesDs = null, allEdges = [];
+    let activeLabels = new Set(), hiddenNodes = new Set();
 
     function refreshEdges() {
       const visible = allEdges.filter(e =>
@@ -213,46 +278,100 @@ function buildHtml(nodes, edges) {
       edgesDs.add(visible);
     }
 
-    document.querySelectorAll('.filter-btn').forEach(btn => {
-      btn.addEventListener('click', () => {
-        const label = btn.dataset.label;
-        if (activeLabels.has(label)) { activeLabels.delete(label); btn.classList.add('off'); }
-        else                         { activeLabels.add(label);    btn.classList.remove('off'); }
-        refreshEdges();
+    function renderTabs() {
+      const bar = document.getElementById('view-tabs');
+      bar.innerHTML = '';
+      if (VIEWS.length < 2) return; // only Workspace — no tab bar needed
+      VIEWS.forEach((v, i) => {
+        const b = document.createElement('button');
+        b.className = 'view-tab' + (i === active ? ' active' : '');
+        b.textContent = v.name;
+        b.addEventListener('click', () => selectView(i));
+        bar.appendChild(b);
       });
-    });
+    }
 
-    document.querySelectorAll('.proj-btn').forEach(btn => {
-      btn.addEventListener('click', () => {
-        const id = btn.dataset.node;
-        if (hiddenNodes.has(id)) {
-          hiddenNodes.delete(id);
-          nodesDs.update({ id, hidden: false });
-          btn.classList.remove('off');
-        } else {
-          hiddenNodes.add(id);
-          nodesDs.update({ id, hidden: true });
-          btn.classList.add('off');
-        }
-        refreshEdges();
+    function renderFilters() {
+      const f = document.getElementById('filters');
+      f.innerHTML = '';
+      VIEWS[active].labels.forEach(label => {
+        const b = document.createElement('button');
+        b.className = 'filter-btn';
+        b.textContent = label;
+        b.addEventListener('click', () => {
+          if (activeLabels.has(label)) { activeLabels.delete(label); b.classList.add('off'); }
+          else                         { activeLabels.add(label);    b.classList.remove('off'); }
+          refreshEdges();
+        });
+        f.appendChild(b);
       });
-    });
+    }
+
+    function renderProjectList() {
+      const body = document.getElementById('proj-list-body');
+      body.innerHTML = '';
+      VIEWS[active].nodes.forEach(n => {
+        const b = document.createElement('button');
+        b.className = 'proj-btn';
+        const dot = document.createElement('span');
+        dot.className = 'proj-dot';
+        dot.style.background = n.color;
+        b.appendChild(dot);
+        b.appendChild(document.createTextNode(n.label));
+        b.addEventListener('click', () => {
+          if (hiddenNodes.has(n.id)) { hiddenNodes.delete(n.id); nodesDs.update({ id: n.id, hidden: false }); b.classList.remove('off'); }
+          else                       { hiddenNodes.add(n.id);    nodesDs.update({ id: n.id, hidden: true  }); b.classList.add('off'); }
+          refreshEdges();
+        });
+        body.appendChild(b);
+      });
+    }
+
+    function selectView(i) {
+      active = i;
+      const v = VIEWS[i];
+      activeLabels = new Set(v.labels);
+      hiddenNodes = new Set();
+      allEdges = v.edges;
+      nodesDs = new vis.DataSet(v.nodes);
+      edgesDs = new vis.DataSet(v.edges);
+
+      if (!network) {
+        network = new vis.Network(document.getElementById('network'), { nodes: nodesDs, edges: edgesDs }, NET_OPTIONS);
+        network.on('stabilizationIterationsDone', () => {
+          network.fit({ animation: { duration: 600, easingFunction: 'easeInOutQuad' } });
+          setTimeout(() => network.setOptions({ physics: { enabled: false } }), 650);
+        });
+        network.on('hoverEdge', ({ edge }) => edgesDs.update({ id: edge, font: { color: '#fff', size: 16, background: '#16213e', strokeWidth: 0 } }));
+        network.on('blurEdge',  ({ edge }) => edgesDs.update({ id: edge, font: { color: '#aaa', size: 11, background: '#1a1a2e', strokeWidth: 0 } }));
+        network.on('doubleClick', params => {
+          if (!params.nodes.length) return;
+          const idx = VIEWS.findIndex(vv => vv.name === params.nodes[0]);
+          if (idx >= 0 && idx !== active) selectView(idx);
+        });
+      } else {
+        network.setOptions({ physics: { enabled: true } });
+        network.setData({ nodes: nodesDs, edges: edgesDs });
+      }
+
+      document.getElementById('count').textContent = v.nodes.length + ' nodes · ' + v.edges.length + ' edges';
+      renderTabs();
+      renderFilters();
+      renderProjectList();
+    }
+
+    selectView(0);
   </script>
 </body>
 </html>`;
 }
-// Single entry point — reads meta once, prints console summary and writes HTML
-function generateProjectGraph(projects, workspacePath) {
-    const EMPTY = { description: null, stack: null, notes: null, relations: null };
-    const nodes = projects.map(p => {
-        const meta = (0, file_utils_1.readRagMeta)(p.path);
-        return { name: p.name, ...(typeof meta === 'object' ? meta : EMPTY) };
-    });
-    const edges = buildEdges(nodes);
-    printConsole(nodes, edges, workspacePath);
+// Single entry point — builds the tabbed views, prints a console summary, writes the HTML.
+function generateProjectGraph(projects, projectEdges, workspacePath) {
+    const views = buildGraphViews(projects, projectEdges, workspacePath);
+    printConsole(views, workspacePath);
     const htmlPath = path.join(workspacePath, 'project-graph.html');
     try {
-        fs.writeFileSync(htmlPath, buildHtml(nodes, edges), 'utf-8');
+        fs.writeFileSync(htmlPath, buildHtml(views), 'utf-8');
     }
     catch (err) {
         console.error(`  ⚠ Could not write project-graph.html: ${err.message}`);

package/dist/src/help.js

@@ -46,22 +46,37 @@ function printHelp(command) {
             console.log('  get <key>               Print a single value');
             console.log('  set <key> <value>       Set a value');
             console.log('  reset <key>             Remove key (falls back to built-in default)');
+            console.log('  edit                    Open config in $EDITOR (with schema validation)');
             console.log('');
             console.log('Keys:');
             console.log('  db.host, db.port, db.user, db.password, db.name');
-            console.log('  ollama.host, ollama.model');
+            console.log('  embedding.provider, embedding.baseURL, embedding.apiKey, embedding.model,');
+            console.log('  embedding.dimensions, embedding.batchSize');
             console.log('  indexing.chunkSize, indexing.chunkOverlap, indexing.embedBatchSize');
             console.log('  search.similarityThreshold, search.defaultLimit, search.maxLimit');
-            console.log('  search.autoTranslate, search.translateModel');
-            console.log('  reranker.enabled, reranker.model, reranker.url, reranker.overfetch');
+            console.log('  reranker.enabled, reranker.provider, reranker.baseURL, reranker.apiKey,');
+            console.log('  reranker.model, reranker.url, reranker.overfetch');
             console.log('  logging.level, logging.dir');
-            console.log('  workspaceRoot');
+            console.log('  workspaceRoot  (API keys: use env:VAR_NAME → ~/.config/codesearch-mcp/.env)');
+            break;
+        case 'rag-web':
+        case 'web':
+            console.log('Usage: rag-web [--port N]');
+            console.log('');
+            console.log('Start a local web dashboard (config editor, project overview,');
+            console.log('dependency graph) on http://127.0.0.1:<port>.');
+            console.log('Requires a valid config.json — repair a broken one with rag-config edit.');
+            console.log('');
+            console.log('Options:');
+            console.log('  --port N          Listen port (default 4319)');
+            console.log('  -h, --help        Show this help message');
             break;
         default:
             console.log('Usage: rag-index [--reindex] [--select]');
             console.log('       rag-mcp');
             console.log('       rag-setup');
-            console.log('       rag-config <show|get|set|reset>');
+            console.log('       rag-config <show|get|set|reset|edit>');
+            console.log('       rag-web [--port N]');
             console.log('');
             console.log('Run any command with -h or --help for details.');
     }

package/dist/src/interfaces/IAstParser.d.ts

@@ -26,18 +26,35 @@ export interface CallEdge {
     line: number | null;
     col: number | null;
 }
+/**
+ * Line range of a named scope used only to compute a chunk's owning declaration
+ * (`ownerPath`). Method/constructor/accessor ranges carry their enclosing class
+ * as `container`; top-level declarations use `container: null`. These are NOT
+ * persisted to `code_symbol` — they exist only for chunk ownership.
+ */
+export interface OwnerRange {
+    name: string;
+    container: string | null;
+    line: number;
+    endLine: number;
+}
 export interface FileAnalysis {
     edges: DepEdge[];
     symbols: SymbolEntry[];
     calls: CallEdge[];
+    /** Method/accessor/constructor ranges for owner-path resolution (Phase 2). */
+    ownerRanges?: OwnerRange[];
+}
+export interface AnalyzeProjectOpts {
+    skipDependencyResolution?: boolean;
+    /** Path to root tsconfig (e.g. tsconfig.base.json) for workspace-wide path aliases */
+    rootTsConfigPath?: string;
 }
 export interface IAstParser {
     /**
      * @deprecated Use analyzeProject instead for project-wide context.
      */
     analyzeFile(filePath: string, serviceName: string, projectRoot?: string): Promise<FileAnalysis>;
-    analyzeProject(filePaths: string[], serviceName: string, projectRoot?: string, opts?: {
-        skipDependencyResolution?: boolean;
-    }): Promise<Map<string, FileAnalysis>>;
+    analyzeProject(filePaths: string[], serviceName: string, projectRoot?: string, opts?: AnalyzeProjectOpts): Promise<Map<string, FileAnalysis>>;
     clearCache(projectRoot?: string): void;
 }

package/dist/src/interfaces/IChunker.d.ts

@@ -0,0 +1,24 @@
+import type { SymbolEntry } from './IAstParser';
+/** One embeddable unit of source with its 1-based inclusive line range. */
+export interface ChunkPiece {
+    content: string;
+    startLine: number;
+    endLine: number;
+}
+export interface ChunkOpts {
+    /** 'ast' = symbol-aligned boundaries; 'character' = fixed-size recursive splitter. */
+    strategy: 'ast' | 'character';
+    /** Schema files (.prisma/.graphql/.gql) always use the schema separator splitter. */
+    isSchemaFile: boolean;
+    /** Top-level symbol ranges for the file; may be empty (no analysis available). */
+    symbols: SymbolEntry[];
+}
+export interface IChunker {
+    /**
+     * Split source into embeddable pieces. AST strategy aligns boundaries to
+     * top-level declaration ranges and never emits a piece longer than the
+     * configured chunk size; falls back to the character splitter for schema
+     * files, empty-symbol files, or when strategy is 'character'.
+     */
+    chunk(code: string, opts: ChunkOpts): Promise<ChunkPiece[]>;
+}

package/dist/src/interfaces/IChunker.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/interfaces/IDatabase.d.ts

@@ -0,0 +1,27 @@
+import type { DrizzleDb, DrizzleTx } from '../services/DatabaseService';
+/** Single-row record of which embedding model built the current index. */
+export interface IndexMeta {
+    provider: string;
+    model: string;
+    dimensions: number;
+}
+/**
+ * Database abstraction — services depend on this interface
+ * rather than the concrete DatabaseService.
+ */
+export interface IDatabase {
+    readonly orm: DrizzleDb;
+    query<T = any>(sql: string, params?: any[]): Promise<T>;
+    transaction<T>(fn: (tx: DrizzleTx) => Promise<T>): Promise<T>;
+    initDb(): Promise<void>;
+    initDbWithSchema(): Promise<void>;
+    destroy(): Promise<void>;
+    /** Read the single `index_meta` row, or null when absent (table missing → null). */
+    readIndexMeta(): Promise<IndexMeta | null>;
+    /** Upsert the single `index_meta` row. */
+    writeIndexMeta(meta: IndexMeta): Promise<void>;
+    /** Create `code_chunk` (+ HNSW/service indexes) at `dimensions` if absent. */
+    ensureChunkTable(dimensions: number): Promise<void>;
+    /** Drop and recreate `code_chunk` at `dimensions` (dimension change). */
+    recreateChunkTable(dimensions: number): Promise<void>;
+}

package/dist/src/interfaces/IDatabase.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/interfaces/IEmbedder.d.ts

@@ -1,5 +1,18 @@
+export type InputType = 'query' | 'document';
 export interface IEmbedder {
-    embed(text: string): Promise<number[]>;
-    translate?(text: string, model: string): Promise<string>;
+    /**
+     * The vector width this embedder produces, when known without a probe:
+     * `embedding.dimensions` override → model registry, else `0` for models whose
+     * width is only knowable by embedding once (see `resolveDimension`). Read by
+     * `SearcherService.assertIndexMatches` to catch a dimension change on the
+     * search side (skipped when `0`). Indexing resolves the true width via
+     * `resolveDimension` (which probes when needed), not this field.
+     */
+    readonly dimensions: number;
+    embed(text: string, inputType?: InputType): Promise<number[]>;
+    /** One vector per input, in input order. The indexing path. */
+    embedBatch(texts: string[], inputType?: InputType): Promise<number[][]>;
     rerank?(query: string, documents: string[], topN: number): Promise<number[]>;
+    listModels?(): Promise<string[]>;
+    ensureModelAvailable?(): Promise<void>;
 }

package/dist/src/interfaces/ILogger.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Logger abstraction — allows services to depend on a contract
+ * rather than the concrete pino-based LoggerService.
+ */
+export interface ILogger {
+    debug(msg: string, data?: Record<string, unknown>): void;
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+}

package/dist/src/interfaces/ILogger.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/interfaces/IMcpToolHandler.d.ts

@@ -0,0 +1,22 @@
+/**
+ * MCP Tool Handler interface — each tool implements this contract.
+ * Follows the Open/Closed Principle: new tools are added by implementing
+ * this interface and registering them, not by modifying McpServer.
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface ToolResponse {
+    [key: string]: unknown;
+    isError?: boolean;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}
+export interface IMcpToolHandler {
+    definition(): ToolDefinition;
+    handle(args: Record<string, unknown>): Promise<ToolResponse>;
+}

package/dist/src/interfaces/IMcpToolHandler.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });