codesearch-mcp 0.0.7-alpha → 0.0.9-alpha

package/dist/app.js

@@ -36,6 +36,14 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 require("./src/env-loader");
 const path = __importStar(require("path"));
+const help_1 = require("./src/help");
+function formatEta(sec) {
+    if (sec < 60)
+        return `${sec}s`;
+    const m = Math.floor(sec / 60);
+    const s = sec % 60;
+    return s > 0 ? `${m}m ${s}s` : `${m}m`;
+}
 function printSummary(allStats) {
     const cols = { name: 30, num: 8 };
     const line = '─'.repeat(cols.name + cols.num * 5 + 5);
@@ -54,6 +62,16 @@ function printSummary(allStats) {
         elapsedSec: acc.elapsedSec + s.elapsedSec,
     }), { indexed: 0, skipped: 0, failed: 0, chunks: 0, elapsedSec: 0 });
     console.log('TOTAL'.padEnd(cols.name), String(total.indexed).padStart(cols.num), String(total.skipped).padStart(cols.num), String(total.failed).padStart(cols.num), String(total.chunks).padStart(cols.num), String(total.elapsedSec.toFixed(1)).padStart(cols.num));
+    // Reprint warnings at the end — progress bar activity scrolls per-project warnings out of
+    // view, so we collect them on IndexStats and surface them here as an explicit section.
+    // const projectsWithWarnings = allStats.filter(s => s.warnings.length > 0);
+    // if (projectsWithWarnings.length > 0) {
+    //   console.log('\n=== Warnings ===');
+    //   for (const s of projectsWithWarnings) {
+    //     console.log(`\n${s.serviceName}:`);
+    //     for (const w of s.warnings) console.log(`  ⚠ ${w}`);
+    //   }
+    // }
 }
 async function main() {
     const argv1 = path.basename(process.argv[1] ?? '');
@@ -62,6 +80,10 @@ async function main() {
     const isSetup = argv1 === 'rag-setup' || process.argv[2] === 'setup';
     const isBackfill = argv1 === 'rag-index' && process.argv[2] === 'backfill';
     const mode = isBackfill ? 'backfill' : isIndex ? 'index' : isMcp ? 'mcp' : isSetup ? 'setup' : (process.argv[2] ?? '');
+    if (process.argv.includes('--help') || process.argv.includes('-h')) {
+        (0, help_1.printHelp)(argv1 !== 'app.js' ? argv1 : mode);
+        process.exit(0);
+    }
     if (mode === 'index') {
         const { initDbWithSchema } = await Promise.resolve().then(() => __importStar(require('./src/db')));
         const { discoverProjects, scanAndIndex } = await Promise.resolve().then(() => __importStar(require('./src/indexer')));
@@ -82,27 +104,41 @@ async function main() {
         process.env.WORKSPACE_ROOT ??= workspacePath;
         await initDbWithSchema();
         setupInterrupt();
-        const discovered = discoverProjects(workspacePath);
-        const projects = await selectProjects(discovered, workspacePath, forceSelect);
-        if (projects.length === 0) {
-            teardownInterrupt();
-            process.exit(0);
-        }
-        const allStats = [];
-        if (force)
-            console.log('Reindex mode: all files will be re-indexed.');
-        for (const proj of projects) {
+        try {
+            const { collectFiles, loadIgnore } = await Promise.resolve().then(() => __importStar(require('./src/file-utils')));
+            const discovered = discoverProjects(workspacePath);
+            const projects = await selectProjects(discovered, workspacePath, forceSelect);
+            if (projects.length === 0)
+                process.exit(0);
+            const filesPerProject = projects.map(p => collectFiles(p.path, loadIgnore(p.path), p.path));
+            const totalFiles = filesPerProject.reduce((sum, f) => sum + f.length, 0);
+            console.log(`\n${projects.length} projects — ${totalFiles} files total`);
+            if (force)
+                console.log('Reindex mode: all files will be re-indexed.');
+            const allStats = [];
+            for (let i = 0; i < projects.length; i++) {
+                if (signal.aborted)
+                    break;
+                const stats = await scanAndIndex(projects[i].path, projects[i].name, force, signal, filesPerProject[i]);
+                allStats.push(stats);
+                const remaining = projects.length - allStats.length;
+                if (remaining > 0 && !signal.aborted) {
+                    const doneFiles = allStats.reduce((s, r) => s + r.indexed + r.skipped + r.failed, 0);
+                    const elapsedSec = allStats.reduce((s, r) => s + r.elapsedSec, 0);
+                    const leftFiles = filesPerProject.slice(allStats.length).reduce((sum, f) => sum + f.length, 0);
+                    const eta = doneFiles > 0 ? formatEta(Math.round(elapsedSec / doneFiles * leftFiles)) : '?';
+                    console.log(`  ${allStats.length}/${projects.length} projects done — ${remaining} left (~${leftFiles} files) — ETA ~${eta}`);
+                }
+            }
             if (signal.aborted)
-                break;
-            const stats = await scanAndIndex(proj.path, proj.name, force, signal);
-            allStats.push(stats);
+                console.log('\nIndexing interrupted.');
+            printSummary(allStats);
+            if (!signal.aborted)
+                generateProjectGraph(projects, workspacePath);
+        }
+        finally {
+            teardownInterrupt();
         }
-        teardownInterrupt();
-        if (signal.aborted)
-            console.log('\nIndexing interrupted.');
-        printSummary(allStats);
-        if (!signal.aborted)
-            generateProjectGraph(projects, workspacePath);
         process.exit(0);
     }
     else if (mode === 'mcp') {
@@ -125,8 +161,8 @@ async function main() {
         await runSetup();
     }
     else if (mode === 'backfill') {
-        const { initDbWithSchema, db, CodeDependency } = await Promise.resolve().then(() => __importStar(require('./src/db')));
-        const { extractImportEdges } = await Promise.resolve().then(() => __importStar(require('./src/ast')));
+        const { initDbWithSchema, db } = await Promise.resolve().then(() => __importStar(require('./src/db')));
+        const { collectDepEdges, writeDepEdges } = await Promise.resolve().then(() => __importStar(require('./src/indexer')));
         const { config } = await Promise.resolve().then(() => __importStar(require('./src/config')));
         const fs = await Promise.resolve().then(() => __importStar(require('fs')));
         const path = await Promise.resolve().then(() => __importStar(require('path')));
@@ -141,16 +177,8 @@ async function main() {
                 skipped++;
                 continue;
             }
-            const rawEdges = await extractImportEdges(absPath, serviceName, projectRoot);
-            const edges = rawEdges
-                .filter(e => e.toFile.startsWith(config.workspaceRoot))
-                .map(e => ({ ...e, fromFile: path.relative(config.workspaceRoot, e.fromFile), toFile: path.relative(config.workspaceRoot, e.toFile) }));
-            await db.transaction(async (manager) => {
-                await manager.delete(CodeDependency, { project: serviceName, fromFile: filePath });
-                if (edges.length > 0) {
-                    await manager.createQueryBuilder().insert().into(CodeDependency).values(edges).execute();
-                }
-            });
+            const edges = await collectDepEdges(absPath, serviceName, projectRoot);
+            await writeDepEdges(serviceName, filePath, edges);
             totalEdges += edges.length;
             processed++;
             if (processed % 50 === 0)
@@ -161,11 +189,13 @@ async function main() {
         process.exit(0);
     }
     else {
-        console.log('Usage: rag-index [path] [--reindex] [--select]');
-        console.log('       rag-index backfill');
-        console.log('       rag-mcp');
-        console.log('       rag-setup');
-        process.exit(1);
+        // No command → show help and exit cleanly. Unknown command → error + help + exit 1.
+        const hasUnknownArg = mode !== '';
+        const out = hasUnknownArg ? console.error : console.log;
+        if (hasUnknownArg)
+            out(`Unknown command: ${mode}\n`);
+        (0, help_1.printHelp)('default');
+        process.exit(hasUnknownArg ? 1 : 0);
     }
 }
 main().catch(err => { console.error(err); process.exit(1); });

package/dist/src/ast.js

@@ -37,23 +37,19 @@ exports.extractImportEdges = extractImportEdges;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const ts_morph_1 = require("ts-morph");
-// Per-project ts-morph instances keyed by tsconfig.json path ('' = no tsconfig fallback).
+// Per-project ts-morph instances keyed by projectRoot. Each project gets its own instance so that
+// projects without a tsconfig (key previously shared as '') don't leak files into each other.
 // Loading the tsconfig gives ts-morph the compilerOptions.paths needed to resolve aliases like @core/*.
 const morphProjects = new Map();
-// Secondary cache: projectRoot → tsconfig key. Avoids one fs.existsSync per file after first lookup.
-const projectRootKeys = new Map();
 const FALLBACK_OPTS = { skipAddingFilesFromTsConfig: true, skipFileDependencyResolution: false, compilerOptions: { allowJs: true, noEmit: true } };
 function getMorphProject(projectRoot) {
-    if (!projectRootKeys.has(projectRoot)) {
+    if (!morphProjects.has(projectRoot)) {
         const tsconfigPath = path.join(projectRoot, 'tsconfig.json');
-        projectRootKeys.set(projectRoot, fs.existsSync(tsconfigPath) ? tsconfigPath : '');
-    }
-    const key = projectRootKeys.get(projectRoot);
-    if (!morphProjects.has(key)) {
+        const hasTsconfig = fs.existsSync(tsconfigPath);
         let project;
         try {
-            const opts = key
-                ? { tsConfigFilePath: key, skipAddingFilesFromTsConfig: true, skipFileDependencyResolution: false }
+            const opts = hasTsconfig
+                ? { tsConfigFilePath: tsconfigPath, skipAddingFilesFromTsConfig: true, skipFileDependencyResolution: false }
                 : FALLBACK_OPTS;
             project = new ts_morph_1.Project(opts);
         }
@@ -61,9 +57,9 @@ function getMorphProject(projectRoot) {
             // tsconfig is invalid — fall back so other files in the project can still be processed
             project = new ts_morph_1.Project(FALLBACK_OPTS);
         }
-        morphProjects.set(key, project);
+        morphProjects.set(projectRoot, project);
     }
-    return morphProjects.get(key);
+    return morphProjects.get(projectRoot);
 }
 // Extract import edges from a TS/JS file using ts-morph.
 // projectRoot must be the project root (where tsconfig.json lives) for alias resolution to work.

package/dist/src/config.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.config = void 0;
 const zod_1 = require("zod");
+const constants_1 = require("./constants");
 const schema = zod_1.z.object({
     // required — no defaults, process exits if missing
     DB_HOST: zod_1.z.string(),
@@ -11,7 +12,7 @@ const schema = zod_1.z.object({
     DB_NAME: zod_1.z.string(),
     // optional with defaults
     OLLAMA_HOST: zod_1.z.string().url().default('http://localhost:11434'),
-    OLLAMA_MODEL: zod_1.z.string().default('bge-m3'),
+    OLLAMA_MODEL: zod_1.z.string().default(constants_1.DEFAULT_EMBED_MODEL),
     CHUNK_SIZE: zod_1.z.coerce.number().default(1500),
     CHUNK_OVERLAP: zod_1.z.coerce.number().default(200),
     EMBED_BATCH_SIZE: zod_1.z.coerce.number().default(5),

package/dist/src/constants.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_EMBED_MODEL = "bge-m3";

package/dist/src/constants.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_EMBED_MODEL = void 0;
+// Embedding model is tied to the vector column dimension (bge-m3 → 1024).
+// Change both together: update this constant, drop/recreate the `embedding` column,
+// and re-run indexing.
+exports.DEFAULT_EMBED_MODEL = 'bge-m3';

package/dist/src/db/init.js

@@ -7,7 +7,8 @@ const data_source_1 = require("./data-source");
 async function initDb() {
     await data_source_1.db.initialize();
 }
-// For indexer — connect + create schema only if tables don't exist yet
+// For indexer — connect + create schema only if tables don't exist yet.
+// All secondary indexes use IF NOT EXISTS so existing installs pick up new indexes on re-run.
 async function initDbWithSchema() {
     await data_source_1.db.initialize();
     // code_chunk table
@@ -24,6 +25,9 @@ async function initDbWithSchema() {
       ON code_chunk USING hnsw (embedding vector_cosine_ops)
     `);
     }
+    // Composite btree for all per-service lookups (scanAndIndex stale-sweep, ingest upsert, search filter).
+    // Applied idempotently so existing installs pick it up on next indexing run.
+    await data_source_1.db.query(`CREATE INDEX IF NOT EXISTS idx_code_chunk_service_file ON code_chunk ("serviceName", "filePath")`);
     // code_dependency table
     const [{ existsDep }] = await data_source_1.db.query(`
     SELECT EXISTS (
@@ -43,8 +47,16 @@ async function initDbWithSchema() {
         "depType"   TEXT NOT NULL
       )
     `);
-        await data_source_1.db.query(`CREATE INDEX idx_dep_from    ON code_dependency ("fromFile")`);
-        await data_source_1.db.query(`CREATE INDEX idx_dep_to      ON code_dependency ("toFile")`);
-        await data_source_1.db.query(`CREATE INDEX idx_dep_project ON code_dependency (project)`);
     }
+    // Composite indexes for the two query shapes used everywhere:
+    //   WHERE project = $1 AND "fromFile" = $2   (get_dependencies, ingest delete-by-from)
+    //   WHERE project = $1 AND "toFile"   = $2   (get_dependents, stale-file sweep)
+    // IF NOT EXISTS lets existing installs upgrade without a manual migration.
+    await data_source_1.db.query(`CREATE INDEX IF NOT EXISTS idx_dep_project_from ON code_dependency (project, "fromFile")`);
+    await data_source_1.db.query(`CREATE INDEX IF NOT EXISTS idx_dep_project_to   ON code_dependency (project, "toFile")`);
+    // Drop redundant legacy single-column indexes (covered by the composites above).
+    // Safe on fresh installs too — DROP IF EXISTS is a no-op when absent.
+    await data_source_1.db.query(`DROP INDEX IF EXISTS idx_dep_from`);
+    await data_source_1.db.query(`DROP INDEX IF EXISTS idx_dep_to`);
+    await data_source_1.db.query(`DROP INDEX IF EXISTS idx_dep_project`);
 }

package/dist/src/help.d.ts

@@ -0,0 +1 @@
+export declare function printHelp(command: string): void;

package/dist/src/help.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printHelp = printHelp;
+function printHelp(command) {
+    switch (command) {
+        case 'rag-index':
+        case 'index':
+            console.log('Usage: rag-index [path] [options]');
+            console.log('       rag-index backfill');
+            console.log('');
+            console.log('Index a workspace of JS/TS projects into the vector database.');
+            console.log('');
+            console.log('Arguments:');
+            console.log('  path              Path to workspace (defaults to WORKSPACE_ROOT env var)');
+            console.log('');
+            console.log('Options:');
+            console.log('  --reindex         Force re-index all files (ignores cached mtimes)');
+            console.log('  --select          Interactively select which projects to index');
+            console.log('  -h, --help        Show this help message');
+            console.log('');
+            console.log('Subcommands:');
+            console.log('  backfill          Populate dependency graph for already-indexed files');
+            break;
+        case 'rag-mcp':
+        case 'mcp':
+            console.log('Usage: rag-mcp');
+            console.log('');
+            console.log('Start the MCP server for semantic code search.');
+            console.log('Requires WORKSPACE_ROOT to be set (run rag-setup first).');
+            console.log('');
+            console.log('Options:');
+            console.log('  -h, --help        Show this help message');
+            break;
+        case 'rag-setup':
+        case 'setup':
+            console.log('Usage: rag-setup');
+            console.log('');
+            console.log('Interactive setup: configure DB, Ollama, and WORKSPACE_ROOT.');
+            console.log('Run once before using rag-index or rag-mcp.');
+            console.log('');
+            console.log('Options:');
+            console.log('  -h, --help        Show this help message');
+            break;
+        default:
+            console.log('Usage: rag-index [path] [--reindex] [--select]');
+            console.log('       rag-index backfill');
+            console.log('       rag-mcp');
+            console.log('       rag-setup');
+            console.log('');
+            console.log('Run any command with -h or --help for details.');
+    }
+}

package/dist/src/indexer.d.ts

@@ -1,3 +1,4 @@
+import { CodeDependency } from './db';
 export interface IndexStats {
     serviceName: string;
     indexed: number;
@@ -5,9 +6,12 @@ export interface IndexStats {
     failed: number;
     chunks: number;
     elapsedSec: number;
+    warnings: string[];
 }
 export declare function discoverProjects(rootDir: string): {
     name: string;
     path: string;
 }[];
-export declare function scanAndIndex(dir: string, serviceName: string, force?: boolean, signal?: AbortSignal): Promise<IndexStats>;
+export declare function collectDepEdges(absFilePath: string, serviceName: string, projectRoot: string): Promise<Omit<CodeDependency, 'id'>[]>;
+export declare function writeDepEdges(serviceName: string, relFilePath: string, edges: Omit<CodeDependency, 'id'>[], manager?: import('typeorm').EntityManager): Promise<void>;
+export declare function scanAndIndex(dir: string, serviceName: string, force?: boolean, signal?: AbortSignal, preCollectedFiles?: string[]): Promise<IndexStats>;

package/dist/src/indexer.js

@@ -34,17 +34,18 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.discoverProjects = discoverProjects;
+exports.collectDepEdges = collectDepEdges;
+exports.writeDepEdges = writeDepEdges;
 exports.scanAndIndex = scanAndIndex;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const textsplitters_1 = require("@langchain/textsplitters");
-const ollama_1 = require("ollama");
 const cli_progress_1 = require("cli-progress");
 const db_1 = require("./db");
 const ast_1 = require("./ast");
 const config_1 = require("./config");
+const ollama_1 = require("./ollama");
 const file_utils_1 = require("./file-utils");
-const ollama = new ollama_1.Ollama({ host: config_1.config.ollama.host });
 // JS/TS splitter uses language-aware separators (functions, classes, blocks)
 const jsSplitter = textsplitters_1.RecursiveCharacterTextSplitter.fromLanguage('js', {
     chunkSize: config_1.config.indexer.chunkSize,
@@ -69,12 +70,39 @@ function discoverProjects(rootDir) {
 }
 // Embed a pre-formatted prompt (caller is responsible for prefix and context)
 async function embedText(prompt) {
-    const { embedding } = await ollama.embeddings({
+    const { embedding } = await ollama_1.ollama.embeddings({
         model: config_1.config.ollama.model,
         prompt,
     });
     return embedding;
 }
+// Shared helpers for dependency edge writes — used by ingestFile (incremental) and backfill CLI.
+// Extract edges via ts-morph (disk I/O) and normalize to workspace-relative paths.
+// Call this OUTSIDE any DB transaction — disk/AST work must not hold a DB connection open.
+async function collectDepEdges(absFilePath, serviceName, projectRoot) {
+    const rawEdges = await (0, ast_1.extractImportEdges)(absFilePath, serviceName, projectRoot);
+    return rawEdges
+        .filter(e => e.toFile.startsWith(config_1.config.workspaceRoot))
+        .map(e => ({
+        ...e,
+        fromFile: path.relative(config_1.config.workspaceRoot, e.fromFile),
+        toFile: path.relative(config_1.config.workspaceRoot, e.toFile),
+    }));
+}
+// Replace edge rows for a file. When `manager` is provided, runs inside that transaction;
+// otherwise opens its own. Keeps delete + insert atomic either way.
+async function writeDepEdges(serviceName, relFilePath, edges, manager) {
+    const run = async (mgr) => {
+        await mgr.delete(db_1.CodeDependency, { project: serviceName, fromFile: relFilePath });
+        if (edges.length > 0) {
+            await mgr.createQueryBuilder().insert().into(db_1.CodeDependency).values(edges).execute();
+        }
+    };
+    if (manager)
+        await run(manager);
+    else
+        await db_1.db.transaction(run);
+}
 // Ingest a single file: skip if unchanged, otherwise delete old chunks and re-index.
 // Returns status and chunk count. Never throws — failures are caught and reported.
 async function ingestFile(filePath, serviceName, mtimeMs, projectRoot) {
@@ -90,14 +118,7 @@ async function ingestFile(filePath, serviceName, mtimeMs, projectRoot) {
             return { status: 'skipped', chunks: 0 };
         }
         // Extract import edges before the transaction — disk I/O must not hold a DB connection open
-        const rawEdges = await (0, ast_1.extractImportEdges)(filePath, serviceName, projectRoot);
-        const edges = rawEdges
-            .filter(e => e.toFile.startsWith(config_1.config.workspaceRoot))
-            .map(e => ({
-            ...e,
-            fromFile: path.relative(config_1.config.workspaceRoot, e.fromFile),
-            toFile: path.relative(config_1.config.workspaceRoot, e.toFile),
-        }));
+        const edges = await collectDepEdges(filePath, serviceName, projectRoot);
         // Read and embed outside the transaction — Ollama calls must not hold a DB transaction open
         const code = fs.readFileSync(filePath, 'utf-8');
         const chunks = await getSplitter(filePath).createDocuments([code]);
@@ -129,14 +150,7 @@ async function ingestFile(filePath, serviceName, mtimeMs, projectRoot) {
                     .values(records.slice(i, i + config_1.config.indexer.batchSize))
                     .execute();
             }
-            await manager.delete(db_1.CodeDependency, { project: serviceName, fromFile: relFilePath });
-            if (edges.length > 0) {
-                await manager.createQueryBuilder()
-                    .insert()
-                    .into(db_1.CodeDependency)
-                    .values(edges)
-                    .execute();
-            }
+            await writeDepEdges(serviceName, relFilePath, edges, manager);
         });
         return { status: 'indexed', chunks: chunks.length };
     }
@@ -149,48 +163,58 @@ async function ingestFile(filePath, serviceName, mtimeMs, projectRoot) {
 // Removes chunks for deleted files, skips unchanged files, re-indexes modified ones.
 // Pass force=true to invalidate all cached mtimes and force full re-index (e.g. after embedding strategy change).
 // Pass signal to support graceful interruption — stops between files, never mid-transaction.
-async function scanAndIndex(dir, serviceName, force = false, signal) {
+async function scanAndIndex(dir, serviceName, force = false, signal, preCollectedFiles) {
     const startTime = Date.now();
     const repo = db_1.db.getRepository(db_1.CodeChunk);
-    // Clean up chunks whose source files no longer exist on disk
+    // Force mode: wipe lastModified so all files are treated as changed
+    if (force) {
+        await db_1.db.query(`UPDATE code_chunk SET "lastModified" = NULL WHERE "serviceName" = $1`, [serviceName]);
+    }
+    const files = preCollectedFiles ?? (0, file_utils_1.collectFiles)(dir, (0, file_utils_1.loadIgnore)(dir), dir);
+    // Clean up chunks for files no longer in the collected set — covers both deleted files and
+    // files newly excluded by .ragignore (they exist on disk but should no longer be indexed).
+    const collectedRelPaths = new Set(files.map(f => path.relative(config_1.config.workspaceRoot, f)));
     const dbPaths = await db_1.db.query(`SELECT DISTINCT "filePath" FROM code_chunk WHERE "serviceName" = $1`, [serviceName]);
     for (const { filePath } of dbPaths) {
-        if (!fs.existsSync(path.join(config_1.config.workspaceRoot, filePath))) {
+        if (!collectedRelPaths.has(filePath)) {
             await repo.delete({ serviceName, filePath });
-            // Remove dependency edges on both sides — this file no longer exists as importer or target
             await db_1.db.query(`DELETE FROM code_dependency WHERE project = $1 AND "fromFile" = $2`, [serviceName, filePath]);
             await db_1.db.query(`DELETE FROM code_dependency WHERE project = $1 AND "toFile" = $2`, [serviceName, filePath]);
             console.log(`  Removed stale: ${path.basename(filePath)}`);
         }
     }
-    // Force mode: wipe lastModified so all files are treated as changed
-    if (force) {
-        await db_1.db.query(`UPDATE code_chunk SET "lastModified" = NULL WHERE "serviceName" = $1`, [serviceName]);
-    }
-    const ig = (0, file_utils_1.loadIgnore)(dir);
-    const files = (0, file_utils_1.collectFiles)(dir, ig, dir);
     const bar = new cli_progress_1.SingleBar({
-        format: `{serviceName} {bar} {percentage}% | {value}/{total} | {filename}`,
+        format: `{serviceName} {bar} {percentage}% | {value}/{total} | ETA {eta_formatted} | {filename}`,
         barCompleteChar: '█',
         barIncompleteChar: '░',
         hideCursor: true,
         clearOnComplete: false,
     }, cli_progress_1.Presets.shades_grey);
+    const warnings = [];
     console.log(`\nIndexing ${serviceName}: ${files.length} files`);
     const meta = (0, file_utils_1.readRagMeta)(dir);
     if (meta === null && fs.existsSync(path.join(dir, '.ragmeta.json'))) {
-        console.log(`  ⚠ .ragmeta.json found but invalid JSON`);
+        const msg = `.ragmeta.json found but invalid JSON`;
+        console.log(`  ⚠ ${msg}`);
+        warnings.push(msg);
     }
     else if (meta) {
         const parts = [meta.description, meta.stack && `[${meta.stack}]`].filter(Boolean).join(' ');
         console.log(`  ✓ .ragmeta.json: ${parts || '(no fields)'}`);
     }
     else {
-        console.log(`  ⚠ No .ragmeta.json — add {"description":"...","stack":"...","notes":"..."} so list_projects can describe this project`);
+        const msg = `No .ragmeta.json — add {"description":"...","stack":"...","notes":"..."} so list_projects can describe this project`;
+        console.log(`  ⚠ ${msg}`);
+        warnings.push(msg);
+    }
+    if (!fs.existsSync(path.join(dir, '.ragignore'))) {
+        const msg = `No .ragignore — create one to exclude generated/codegen files (e.g. src/gql/graphql.ts, **/__snapshots__/**)`;
+        console.log(`  ⚠ ${msg}`);
+        warnings.push(msg);
     }
     bar.start(files.length, 0, { serviceName, filename: '' });
     const stats = {
-        serviceName, indexed: 0, skipped: 0, failed: 0, chunks: 0, elapsedSec: 0,
+        serviceName, indexed: 0, skipped: 0, failed: 0, chunks: 0, elapsedSec: 0, warnings,
     };
     for (const filePath of files) {
         if (signal?.aborted) {
@@ -212,6 +236,7 @@ async function scanAndIndex(dir, serviceName, force = false, signal) {
         bar.increment();
     }
     bar.stop();
+    process.stdout.write('\x1B[J'); // erase any blank lines cli-progress left below the bar
     stats.elapsedSec = Math.round((Date.now() - startTime) / 100) / 10;
     return stats;
 }

package/dist/src/mcp.js

@@ -1,11 +1,54 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startMCP = startMCP;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const config_1 = require("./config");
 const searcher_1 = require("./searcher");
+const PKG_VERSION = (() => {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
 const SERVER_INSTRUCTIONS = `
 You have access to a local semantic code search server. Use these tools to navigate unfamiliar codebases.
 
@@ -14,13 +57,18 @@ You have access to a local semantic code search server. Use these tools to navig
 - **list_projects** — call this first to see what projects are indexed and their exact names.
 - **search_codebase** — semantic search across indexed source files. Returns file path, line number, and a code chunk.
 - **read_file_range** — read a specific line range from any indexed file. Use this to expand context around a search result.
+- **get_dependencies** — show what files a given file imports (direct or transitive). Use to understand what a file depends on.
+- **get_dependents** — show which files import a given file (reverse graph). Use before refactoring to find all callers.
 
 ## Recommended workflow
 
 1. Use \`list_projects\` to discover available projects before filtering by \`project\`.
 2. Use \`search_codebase\` to find relevant code by meaning.
-3. If a result looks **truncated or incomplete** (e.g. you see only the middle of a function), call \`read_file_range\` with the returned \`file_path\` and lines around \`startLine\` to get the full picture.
+3. If a result looks **truncated or incomplete** (e.g. you see only the middle of a function), call \`read_file_range\` with the returned \`file_path\` and \`start_line\` set to the **Line** number shown in the result. Example: if the result shows **Line:** 150, pass \`start_line: 150\`.
 4. For exploratory searches where you expect results to span chunk boundaries, pass \`include_neighbors: true\` to automatically include the chunk before and after each match.
+5. Use \`find_symbol\` when you know the exact name of a function or class and want its definition location immediately — faster than semantic search.
+6. Use \`list_files\` to explore project structure (src/, components/, etc.) before diving into files.
+7. Use \`read_file\` to read a complete file when you have its absolute path from \`search_codebase\` results.
 
 ## When to use read_file_range vs include_neighbors
 
@@ -39,6 +87,9 @@ Lower score = better match (cosine distance). Results above the configured thres
 
 - **get_dependencies** — show what files a given file imports (direct or transitive). Use when you need to understand what a file depends on.
 - **get_dependents** — show which files import a given file (reverse graph). Use before refactoring to find all callers and avoid breaking changes.
+- **find_symbol** — find where a symbol (function, class, type, interface, variable) is defined by exact name. Faster than semantic search when you know the name.
+- **list_files** — browse the directory tree of a project path. Use to understand project structure before reading files.
+- **read_file** — read a complete file by absolute path with line numbers. Truncates at max_lines with a hint to continue.
 
 Both tools require \`file_path\` (as returned by \`search_codebase\`) and \`project\` (from \`list_projects\`). Pass \`transitive: true\` for the full dependency chain.
 `.trim();
@@ -79,7 +130,7 @@ function formatChunk(r, label) {
     return `${label ? `*(${label})*\n` : ''}**File:** ${r.filePath}\n**Project:** ${r.serviceName}\n**Line:** ${r.startLine}\n\`\`\`\n${r.content}\n\`\`\``;
 }
 async function startMCP() {
-    const server = new index_js_1.Server({ name: 'local-rag', version: '1.0.0' }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
+    const server = new index_js_1.Server({ name: 'local-rag', version: PKG_VERSION }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
     server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         tools: [
             {
@@ -108,8 +159,8 @@ async function startMCP() {
                     type: 'object',
                     properties: {
                         file_path: { type: 'string', description: 'File path as returned by search_codebase' },
-                        start_line: { type: 'number', description: 'First line to read (1-based, inclusive). Default: 1' },
-                        end_line: { type: 'number', description: 'Last line to read (1-based, inclusive). Default: start_line + 99' },
+                        start_line: { type: 'number', description: 'First line to read (1-based). Use the **Line** number from search_codebase results. Default: 1.' },
+                        end_line: { type: 'number', description: 'Last line to read (1-based, inclusive). Default: start_line + 99.' },
                     },
                     required: ['file_path'],
                 },
@@ -136,12 +187,51 @@ async function startMCP() {
                     properties: {
                         file_path: { type: 'string', description: 'File path as returned by search_codebase' },
                         project: { type: 'string', description: 'Project name (use list_projects to find it)' },
-                        symbol: { type: 'string', description: 'Filter to a specific exported symbol name. When the graph returns no results, also triggers a text-search fallback to find runtime usages (e.g. via singleton or container).' },
+                        symbol: { type: 'string', description: 'Exported symbol name. Two behaviors: (1) if graph dependents exist, narrows them to imports of this symbol; (2) if the import graph returns zero results, triggers a whole-word text-search fallback (grep -F -w) across all .ts/.tsx/.js/.jsx files in the project to find runtime usages — DI containers, singletons, dynamic lookups, string references. Capped at 200 matches.' },
                         transitive: { type: 'boolean', description: 'Include transitive (indirect) dependents. Default: false.' },
                     },
                     required: ['file_path', 'project'],
                 },
             },
+            {
+                name: 'find_symbol',
+                description: 'Find TypeScript/JavaScript symbol definitions (functions, classes, types, interfaces, variables) by exact name. Use when you know the symbol name and want its definition location fast.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string', description: 'Exact symbol name (case-sensitive, whole-word match)' },
+                        project: { type: 'string', description: 'Limit search to this project (optional). Use list_projects to find names.' },
+                        kind: { type: 'string', enum: ['function', 'class', 'type', 'interface', 'variable', 'all'], description: 'Symbol kind filter. Default: all.' },
+                    },
+                    required: ['name'],
+                },
+            },
+            {
+                name: 'list_files',
+                description: 'List files and directories in a project path as an indented tree. Use to understand project structure before reading files.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        path: { type: 'string', description: 'Directory path relative to the project root (e.g. "src/components" or "." for root)' },
+                        project: { type: 'string', description: 'Project name (from list_projects)' },
+                        depth: { type: 'number', description: 'Tree depth: 1 = immediate children only, up to 5. Default: 2.' },
+                        pattern: { type: 'string', description: 'Optional filename filter (substring or extension like ".ts"). Only matching files are shown.' },
+                    },
+                    required: ['path', 'project'],
+                },
+            },
+            {
+                name: 'read_file',
+                description: 'Read a file from the workspace by absolute path (as returned by search_codebase). Returns contents with line numbers. Truncates at max_lines with a hint to continue with read_file_range.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        file_path: { type: 'string', description: 'Absolute path to the file (as returned in filePath by search_codebase)' },
+                        max_lines: { type: 'number', description: 'Maximum lines to return (default 300, max 1000)' },
+                    },
+                    required: ['file_path'],
+                },
+            },
         ],
     }));
     server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
@@ -203,18 +293,17 @@ async function startMCP() {
                 const endLine = Number(req.params.arguments?.end_line) || startLine + 99;
                 const range = await (0, searcher_1.readFileRange)(filePath, startLine, endLine);
                 if (!range.ok) {
-                    const message = range.reason === 'not_indexed'
-                        ? `File is not indexed: ${filePath}. Run indexing first.`
-                        : `File was deleted from disk after indexing: ${filePath}. Re-run indexing to update.`;
+                    const message = range.reason === 'invalid_path' ? `Invalid file path (outside workspace): ${filePath}` :
+                        range.reason === 'not_indexed' ? `File is not indexed: ${filePath}. Run indexing first.` :
+                            `File was deleted from disk after indexing: ${filePath}. Re-run indexing to update.`;
                     return { content: [{ type: 'text', text: message }] };
                 }
                 const numbered = range.lines.map((line, i) => `${startLine + i}: ${line}`).join('\n');
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `**File:** ${range.filePath}\n**Lines:** ${range.startLine}–${range.endLine}\n\`\`\`\n${numbered}\n\`\`\``,
-                        }],
-                };
+                let text = `**File:** ${range.filePath}\n**Lines:** ${range.startLine}–${range.endLine}\n\`\`\`\n${numbered}\n\`\`\``;
+                if (range.hasMore) {
+                    text += `\n\n[file has more lines — call read_file_range again with start_line: ${range.endLine + 1}]`;
+                }
+                return { content: [{ type: 'text', text }] };
             }
             if (req.params.name === 'get_dependencies') {
                 const filePath = String(req.params.arguments?.file_path);
@@ -256,6 +345,54 @@ async function startMCP() {
                 }
                 return { content: [{ type: 'text', text: header + fallbackLines.join('\n') }] };
             }
+            if (req.params.name === 'find_symbol') {
+                const name = String(req.params.arguments?.name ?? '');
+                const project = req.params.arguments?.project ? String(req.params.arguments.project) : null;
+                const rawKind = req.params.arguments?.kind;
+                const validKinds = ['function', 'class', 'type', 'interface', 'variable', 'all'];
+                const kind = validKinds.includes(rawKind) ? rawKind : 'all';
+                const { hits, truncated } = (0, searcher_1.findSymbol)(name, project, kind);
+                if (hits.length === 0) {
+                    return { content: [{ type: 'text', text: `No definitions found for symbol: ${name}` }] };
+                }
+                const lines = [];
+                if (truncated)
+                    lines.push(`*(truncated to ${hits.length} results)*\n`);
+                for (const h of hits) {
+                    lines.push(`**${h.kind}** \`${h.filePath}\` line ${h.line}, col ${h.column}`);
+                    lines.push(`\`\`\`\n${h.signature}\n\`\`\``);
+                }
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            }
+            if (req.params.name === 'list_files') {
+                const relPath = String(req.params.arguments?.path ?? '.');
+                const project = String(req.params.arguments?.project ?? '');
+                const rawDepth = Number(req.params.arguments?.depth);
+                const depth = isNaN(rawDepth) || rawDepth < 1 ? 2 : Math.min(5, rawDepth);
+                const pattern = req.params.arguments?.pattern ? String(req.params.arguments.pattern) : null;
+                const { tree, error } = (0, searcher_1.listFiles)(relPath, project, depth, pattern);
+                if (error) {
+                    return { content: [{ type: 'text', text: `list_files error: ${error}` }] };
+                }
+                return { content: [{ type: 'text', text: `**${project}/${relPath}**\n\`\`\`\n${tree}\n\`\`\`` }] };
+            }
+            if (req.params.name === 'read_file') {
+                const filePath = String(req.params.arguments?.file_path ?? '');
+                const rawMax = Number(req.params.arguments?.max_lines);
+                const maxLines = isNaN(rawMax) || rawMax < 1 ? 300 : Math.min(1000, rawMax);
+                const result = await (0, searcher_1.readFileAbsolute)(filePath, maxLines);
+                if (!result.ok) {
+                    const message = result.reason === 'invalid_path' ? `Invalid path (outside workspace): ${filePath}` :
+                        `File not found on disk: ${filePath}`;
+                    return { content: [{ type: 'text', text: message }] };
+                }
+                const numbered = result.lines.map((line, i) => `${i + 1}: ${line}`).join('\n');
+                let text = `**File:** ${result.filePath}\n**Lines:** 1–${result.endLine}\n\`\`\`\n${numbered}\n\`\`\``;
+                if (result.hasMore) {
+                    text += `\n\n[truncated: file has more lines — use read_file_range with file_path: "${result.filePath}", start_line: ${result.endLine + 1} to continue]`;
+                }
+                return { content: [{ type: 'text', text }] };
+            }
             throw new Error(`Unknown tool: ${req.params.name}`);
         }
         catch (err) {

package/dist/src/ollama.d.ts

@@ -0,0 +1,2 @@
+import { Ollama } from 'ollama';
+export declare const ollama: Ollama;

package/dist/src/ollama.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ollama = void 0;
+const ollama_1 = require("ollama");
+const config_1 = require("./config");
+exports.ollama = new ollama_1.Ollama({ host: config_1.config.ollama.host });

package/dist/src/project-selector.js

@@ -45,8 +45,16 @@ function loadLines(filePath) {
         .map(l => l.trim())
         .filter(l => l && !l.startsWith('#')));
 }
+// Write the set if non-empty, otherwise delete the file so state is deterministic.
+// Previously .ragskip could be left stale (last entry removed but file not rewritten);
+// treating both files the same way avoids that drift.
 function saveLines(filePath, names) {
-    fs.writeFileSync(filePath, [...names].sort().join('\n') + '\n');
+    if (names.size > 0) {
+        fs.writeFileSync(filePath, [...names].sort().join('\n') + '\n');
+    }
+    else if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+    }
 }
 function loadConfig(workspaceDir) {
     return {
@@ -56,8 +64,7 @@ function loadConfig(workspaceDir) {
 }
 function saveConfig(workspaceDir, config) {
     saveLines(path.join(workspaceDir, '.ragprojects'), config.included);
-    if (config.skipped.size > 0)
-        saveLines(path.join(workspaceDir, '.ragskip'), config.skipped);
+    saveLines(path.join(workspaceDir, '.ragskip'), config.skipped);
 }
 async function selectProjects(allProjects, workspaceDir, forceSelect) {
     const config = loadConfig(workspaceDir);

package/dist/src/searcher.d.ts

@@ -1,5 +1,4 @@
-export type { Relations } from './file-utils';
-export type { ProjectMeta } from './file-utils';
+import { type ProjectMeta } from './file-utils';
 export interface ChunkRow {
     serviceName: string;
     filePath: string;
@@ -20,9 +19,10 @@ export type FileRangeResult = {
     startLine: number;
     endLine: number;
     lines: string[];
+    hasMore: boolean;
 } | {
     ok: false;
-    reason: 'not_indexed' | 'not_on_disk';
+    reason: 'not_indexed' | 'not_on_disk' | 'invalid_path';
 };
 export interface DependencyRow {
     fromFile: string;
@@ -37,7 +37,6 @@ export declare function prepareQuery(raw: string): Promise<{
     query: string;
     translated: boolean;
 }>;
-import type { ProjectMeta } from './file-utils';
 export interface ProjectRow extends ProjectMeta {
     serviceName: string;
     chunks: number;
@@ -55,4 +54,21 @@ export declare function grepSymbol(symbol: string, project: string, excludeFile:
     matches: GrepMatch[];
     truncated: boolean;
 };
+export type SymbolKind = 'function' | 'class' | 'type' | 'interface' | 'variable' | 'all';
+export interface SymbolHit {
+    filePath: string;
+    line: number;
+    column: number;
+    kind: Exclude<SymbolKind, 'all'>;
+    signature: string;
+}
+export declare function findSymbol(name: string, project: string | null, kind: SymbolKind): {
+    hits: SymbolHit[];
+    truncated: boolean;
+};
+export declare function listFiles(relativePath: string, project: string, depth: number, pattern: string | null): {
+    tree: string;
+    error?: string;
+};
+export declare function readFileAbsolute(absPath: string, maxLines: number): Promise<FileRangeResult>;
 export declare function readFileRange(filePath: string, startLine: number, endLine: number): Promise<FileRangeResult>;

package/dist/src/searcher.js

@@ -40,22 +40,25 @@ exports.fetchNeighbors = fetchNeighbors;
 exports.getDependencies = getDependencies;
 exports.getDependents = getDependents;
 exports.grepSymbol = grepSymbol;
+exports.findSymbol = findSymbol;
+exports.listFiles = listFiles;
+exports.readFileAbsolute = readFileAbsolute;
 exports.readFileRange = readFileRange;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
 const child_process_1 = require("child_process");
-const ollama_1 = require("ollama");
 const db_1 = require("./db");
 const config_1 = require("./config");
+const ollama_1 = require("./ollama");
 const file_utils_1 = require("./file-utils");
-const ollama = new ollama_1.Ollama({ host: config_1.config.ollama.host });
 // Detect non-English input by presence of non-ASCII characters (Cyrillic, etc.)
 function isNonEnglish(text) {
     return /[^\x00-\x7F]/.test(text);
 }
 // Translate query to English using a local Ollama model
 async function translateToEnglish(text) {
-    const response = await ollama.chat({
+    const response = await ollama_1.ollama.chat({
         model: config_1.config.search.translateModel,
         messages: [{ role: 'user', content: `Translate the following text to English. Return only the translation, no explanations:\n${text}` }],
     });
@@ -81,7 +84,7 @@ async function listProjects() {
 }
 // Embed query and run vector similarity search
 async function searchChunks(query, limit, project) {
-    const { embedding } = await ollama.embeddings({ model: config_1.config.ollama.model, prompt: query });
+    const { embedding } = await ollama_1.ollama.embeddings({ model: config_1.config.ollama.model, prompt: query });
     const params = [`[${embedding}]`, config_1.config.search.similarityThreshold, limit];
     let projectFilter = '';
     if (project) {
@@ -97,20 +100,32 @@ async function searchChunks(query, limit, project) {
      ORDER BY embedding <=> $1
      LIMIT $3`, params);
 }
-// Fetch the chunk immediately before and after each result in the same file (Small-to-Big)
+// Fetch the chunk immediately before and after each result in the same file (Small-to-Big).
+// Single query with LATERAL joins — avoids 2N round-trips.
 async function fetchNeighbors(results) {
-    return Promise.all(results.map(async (result) => {
-        const [prevRows, nextRows] = await Promise.all([
-            db_1.db.query(`SELECT "serviceName", "filePath", "startLine", content
-         FROM code_chunk
-         WHERE "filePath" = $1 AND "startLine" < $2
-         ORDER BY "startLine" DESC LIMIT 1`, [result.filePath, result.startLine]),
-            db_1.db.query(`SELECT "serviceName", "filePath", "startLine", content
-         FROM code_chunk
-         WHERE "filePath" = $1 AND "startLine" > $2
-         ORDER BY "startLine" ASC LIMIT 1`, [result.filePath, result.startLine]),
-        ]);
-        return { result, prevChunk: prevRows[0] ?? null, nextChunk: nextRows[0] ?? null };
+    if (results.length === 0)
+        return [];
+    const values = results.map((_, i) => `(${i}, $${i * 2 + 1}, $${i * 2 + 2}::int)`).join(',');
+    const params = results.flatMap(r => [r.filePath, r.startLine]);
+    const rows = await db_1.db.query(`SELECT r.idx,
+            prev."serviceName" AS prev_sn, prev."filePath" AS prev_fp, prev."startLine" AS prev_sl, prev.content AS prev_c,
+            next."serviceName" AS next_sn, next."filePath" AS next_fp, next."startLine" AS next_sl, next.content AS next_c
+     FROM (VALUES ${values}) r(idx, fp, sl)
+     LEFT JOIN LATERAL (
+       SELECT "serviceName", "filePath", "startLine", content
+       FROM code_chunk WHERE "filePath" = r.fp AND "startLine" < r.sl
+       ORDER BY "startLine" DESC LIMIT 1
+     ) prev ON true
+     LEFT JOIN LATERAL (
+       SELECT "serviceName", "filePath", "startLine", content
+       FROM code_chunk WHERE "filePath" = r.fp AND "startLine" > r.sl
+       ORDER BY "startLine" ASC LIMIT 1
+     ) next ON true
+     ORDER BY r.idx`, params);
+    return rows.map((row, i) => ({
+        result: results[i],
+        prevChunk: row.prev_fp ? { serviceName: row.prev_sn, filePath: row.prev_fp, startLine: row.prev_sl, content: row.prev_c } : null,
+        nextChunk: row.next_fp ? { serviceName: row.next_sn, filePath: row.next_fp, startLine: row.next_sl, content: row.next_c } : null,
     }));
 }
 // Return all files imported by filePath (direct or transitive)
@@ -228,15 +243,204 @@ function grepSymbol(symbol, project, excludeFile) {
     });
     return { matches: all.slice(0, GREP_MAX_RESULTS), truncated: all.length > GREP_MAX_RESULTS };
 }
+const FIND_SYMBOL_LIMIT = 50;
+const FIND_SYMBOL_RAW_LIMIT = FIND_SYMBOL_LIMIT * 10;
+function buildFindSymbolPattern(name, kind) {
+    const patterns = {
+        function: `(export[[:space:]]+)?(async[[:space:]]+)?function[[:space:]]+${name}[[:space:](<]`,
+        class: `(export[[:space:]]+)?(abstract[[:space:]]+)?class[[:space:]]+${name}[[:space:]{<]`,
+        type: `(export[[:space:]]+)?type[[:space:]]+${name}[[:space:]=<]`,
+        interface: `(export[[:space:]]+)?interface[[:space:]]+${name}[[:space:]{<]`,
+        variable: `(export[[:space:]]+)?(const|let|var)[[:space:]]+${name}[[:space:]=:]`,
+    };
+    if (kind === 'all')
+        return Object.values(patterns).join('|');
+    return patterns[kind];
+}
+function inferKind(line, name) {
+    const before = line.slice(0, line.indexOf(name));
+    if (/\bfunction\s+$/.test(before))
+        return 'function';
+    if (/\bclass\s+$/.test(before))
+        return 'class';
+    if (/\binterface\s+$/.test(before))
+        return 'interface';
+    if (/\btype\s+$/.test(before))
+        return 'type';
+    return 'variable';
+}
+function findSymbol(name, project, kind) {
+    if (!/^[\w$]+$/.test(name))
+        throw new Error('Invalid symbol name');
+    const searchDir = project
+        ? path.join(config_1.config.workspaceRoot, project)
+        : config_1.config.workspaceRoot;
+    const pattern = buildFindSymbolPattern(name, kind);
+    const result = (0, child_process_1.spawnSync)('grep', [
+        '-rn', '-E',
+        '-m', String(FIND_SYMBOL_RAW_LIMIT),
+        '--include=*.ts', '--include=*.tsx', '--include=*.js', '--include=*.jsx',
+        ...GREP_EXCLUDE_DIRS,
+        pattern,
+        searchDir,
+    ], { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
+    if (result.error) {
+        console.error(`[findSymbol] grep failed: ${result.error.message}`);
+        return { hits: [], truncated: false };
+    }
+    if (!result.stdout)
+        return { hits: [], truncated: false };
+    const hits = [];
+    for (const raw of result.stdout.split('\n')) {
+        if (hits.length >= FIND_SYMBOL_LIMIT)
+            break;
+        // grep -n format: "/abs/path/file.ts:42:   export function Foo(...)"
+        // File paths can contain colons on some systems, so split carefully:
+        // find first colon after a path separator, use lastIndexOf on the line number part
+        const m = raw.match(/^(.+?):(\d+):(.*)$/);
+        if (!m)
+            continue;
+        const [, absFile, lineNumStr, matchedLine] = m;
+        const lineNum = parseInt(lineNumStr, 10);
+        if (isNaN(lineNum))
+            continue;
+        const col = matchedLine.indexOf(name);
+        if (col === -1)
+            continue;
+        hits.push({
+            filePath: path.relative(config_1.config.workspaceRoot, absFile),
+            line: lineNum,
+            column: col + 1,
+            kind: inferKind(matchedLine, name),
+            signature: matchedLine.trim(),
+        });
+    }
+    return { hits, truncated: hits.length >= FIND_SYMBOL_LIMIT };
+}
+// ── list_files ────────────────────────────────────────────────────────────────
+function walkDir(absDir, currentDepth, maxDepth, pattern, lines) {
+    let entries;
+    try {
+        entries = fs.readdirSync(absDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort((a, b) => {
+        const ad = a.isDirectory() ? 0 : 1;
+        const bd = b.isDirectory() ? 0 : 1;
+        if (ad !== bd)
+            return ad - bd;
+        return a.name.localeCompare(b.name);
+    });
+    for (const entry of entries) {
+        if (file_utils_1.IGNORE_DIRS.has(entry.name))
+            continue;
+        const indent = '  '.repeat(currentDepth);
+        if (entry.isDirectory()) {
+            lines.push(`${indent}${entry.name}/`);
+            if (currentDepth < maxDepth) {
+                walkDir(path.join(absDir, entry.name), currentDepth + 1, maxDepth, pattern, lines);
+            }
+        }
+        else {
+            if (pattern && !entry.name.includes(pattern))
+                continue;
+            lines.push(`${indent}${entry.name}`);
+        }
+    }
+}
+function listFiles(relativePath, project, depth, pattern) {
+    const projectRoot = path.join(config_1.config.workspaceRoot, project);
+    const resolvedTarget = path.resolve(projectRoot, relativePath);
+    const resolvedProject = path.resolve(projectRoot);
+    if (resolvedTarget !== resolvedProject && !resolvedTarget.startsWith(resolvedProject + path.sep)) {
+        return { tree: '', error: 'Path escapes project root' };
+    }
+    if (!fs.existsSync(resolvedTarget)) {
+        return { tree: '', error: `Path not found: ${relativePath}` };
+    }
+    if (!fs.statSync(resolvedTarget).isDirectory()) {
+        return { tree: '', error: `Not a directory: ${relativePath}` };
+    }
+    const clampedDepth = Math.min(5, Math.max(1, depth));
+    const lines = [];
+    walkDir(resolvedTarget, 0, clampedDepth - 1, pattern, lines);
+    if (lines.length === 0) {
+        return { tree: pattern ? `No files matching "${pattern}" found.` : '(empty directory)' };
+    }
+    return { tree: lines.join('\n') };
+}
+// ── readFileAbsolute ──────────────────────────────────────────────────────────
+// Variant of readFileRange that accepts an absolute path and skips the DB index check.
+// Used by the read_file MCP tool, which receives absolute paths from search_codebase.
+async function readFileAbsolute(absPath, maxLines) {
+    const resolvedRoot = path.resolve(config_1.config.workspaceRoot);
+    const resolved = path.resolve(absPath);
+    if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + path.sep)) {
+        return { ok: false, reason: 'invalid_path' };
+    }
+    if (!fs.existsSync(resolved))
+        return { ok: false, reason: 'not_on_disk' };
+    const lines = [];
+    const stream = fs.createReadStream(resolved, { encoding: 'utf-8' });
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    let lineNo = 0;
+    let hasMore = false;
+    try {
+        for await (const line of rl) {
+            lineNo++;
+            if (lineNo <= maxLines)
+                lines.push(line);
+            if (lineNo >= maxLines) {
+                hasMore = true;
+                rl.close();
+                stream.destroy();
+                break;
+            }
+        }
+    }
+    catch (err) {
+        rl.close();
+        stream.destroy();
+        throw err;
+    }
+    const relPath = path.relative(resolvedRoot, resolved);
+    return { ok: true, filePath: relPath, startLine: 1, endLine: lineNo, lines, hasMore };
+}
 // Read a line range from a file that is present in the index
 async function readFileRange(filePath, startLine, endLine) {
+    // Defensive: reject paths that escape the workspace root (e.g. "../../etc/passwd")
+    const resolvedRoot = path.resolve(config_1.config.workspaceRoot);
+    const absPath = path.resolve(resolvedRoot, filePath);
+    if (absPath !== resolvedRoot && !absPath.startsWith(resolvedRoot + path.sep)) {
+        return { ok: false, reason: 'invalid_path' };
+    }
     const [{ exists }] = await db_1.db.query(`SELECT EXISTS (SELECT 1 FROM code_chunk WHERE "filePath" = $1) AS exists`, [filePath]);
     if (!exists)
         return { ok: false, reason: 'not_indexed' };
-    const absPath = path.join(config_1.config.workspaceRoot, filePath);
     if (!fs.existsSync(absPath))
         return { ok: false, reason: 'not_on_disk' };
-    const all = fs.readFileSync(absPath, 'utf-8').split('\n');
-    const lines = all.slice(startLine - 1, endLine);
-    return { ok: true, filePath, startLine, endLine: Math.min(endLine, all.length), lines };
+    // Stream line-by-line — avoids loading entire file into memory.
+    // Stops reading as soon as we pass endLine.
+    const lines = [];
+    const stream = fs.createReadStream(absPath, { encoding: 'utf-8' });
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    let lineNo = 0;
+    let lastRead = 0;
+    let hasMore = false;
+    for await (const line of rl) {
+        lineNo++;
+        lastRead = lineNo;
+        if (lineNo >= startLine && lineNo <= endLine)
+            lines.push(line);
+        if (lineNo >= endLine) {
+            hasMore = true;
+            rl.close();
+            stream.destroy();
+            break;
+        }
+    }
+    // If we broke out early, lastRead is endLine. If file was shorter, lastRead is file length.
+    return { ok: true, filePath, startLine, endLine: Math.min(endLine, lastRead), lines, hasMore };
 }

package/dist/src/setup.js

@@ -39,6 +39,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const child_process_1 = require("child_process");
+const constants_1 = require("./constants");
 const CONFIG_DIR = path.join(os.homedir(), '.config', 'codesearch-mcp');
 const CONFIG_FILE = path.join(CONFIG_DIR, '.env');
 const DOCKER_COMPOSE_SRC = path.join(__dirname, '..', '..', 'docker', 'docker-compose.yml');
@@ -133,8 +134,18 @@ async function setupLocalDocker(ollamaHost) {
     }
     await waitForDb('localhost', 5433, 'dev', 'dev', 'rag');
     await waitForOllama(ollamaHost);
-    console.log('Pulling bge-m3 model (this may take a while)...');
-    (0, child_process_1.spawnSync)('docker', ['exec', 'codesearch-mcp-ollama-1', 'ollama', 'pull', 'bge-m3'], { stdio: 'inherit' });
+    // Resolve the ollama container ID via compose — compose project name (and thus the
+    // default container name) depends on the parent directory, so hardcoding it breaks when
+    // users install via npm -g or move the compose file around.
+    const ollamaId = (0, child_process_1.spawnSync)('docker', ['compose', '-f', DOCKER_COMPOSE_DST, 'ps', '-q', 'ollama'], { encoding: 'utf-8' })
+        .stdout?.trim();
+    if (!ollamaId) {
+        console.error('Could not resolve ollama container ID from compose. Pull the model manually:');
+        console.error(`  docker exec <ollama-container> ollama pull ${constants_1.DEFAULT_EMBED_MODEL}`);
+        process.exit(1);
+    }
+    console.log(`Pulling ${constants_1.DEFAULT_EMBED_MODEL} model (this may take a while)...`);
+    (0, child_process_1.spawnSync)('docker', ['exec', ollamaId, 'ollama', 'pull', constants_1.DEFAULT_EMBED_MODEL], { stdio: 'inherit' });
     return {
         DB_HOST: 'localhost',
         DB_PORT: '5433',
@@ -166,13 +177,12 @@ async function setupRemoteDb(rl) {
 async function runSetup() {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     console.log('=== codesearch-mcp setup ===\n');
-    const dbChoice = await ask(rl, 'Database type:\n  1. Local Docker (auto-start)\n  2. Remote (Supabase, Railway, self-hosted)\n\nEnter choice (1): ');
+    const dbChoice = await ask(rl, 'Infrastructure:\n  1. Local Docker (auto-start PostgreSQL + Ollama)\n  2. Remote (Supabase, Railway, self-hosted DB + local Ollama)\n\nEnter choice (1): ');
     const useDocker = (dbChoice.trim() || '1') === '1';
     const defaultWorkspace = path.join(os.homedir(), 'Projects');
     const workspaceInput = await ask(rl, `\nWorkspace root — directory that contains all your projects\n  Example: ${os.homedir()}/WebstormProjects\n  Path (${defaultWorkspace}): `);
     const workspaceRoot = expandHome(workspaceInput.trim() || defaultWorkspace);
     const ollamaHost = await prompt(rl, 'Ollama API URL', 'http://localhost:11434');
-    const ollamaModel = await prompt(rl, 'Embedding model', 'bge-m3');
     const dbVars = useDocker
         ? await setupLocalDocker(ollamaHost)
         : await setupRemoteDb(rl);
@@ -180,7 +190,6 @@ async function runSetup() {
         ...dbVars,
         WORKSPACE_ROOT: workspaceRoot,
         OLLAMA_HOST: ollamaHost,
-        OLLAMA_MODEL: ollamaModel,
     });
     rl.close();
     console.log('\nInitializing database schema...');

package/docker/docker-compose.yml

@@ -7,6 +7,8 @@ services:
       POSTGRES_DB: rag
     ports:
       - "5433:5432"
+    volumes:
+      - ${HOME}/.local/share/codesearch-mcp/pgdata:/var/lib/postgresql/data
 
   ollama:
     image: ollama/ollama

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codesearch-mcp",
-  "version": "0.0.7-alpha",
+  "version": "0.0.9-alpha",
   "description": "Local semantic codebase search via MCP — indexes projects into pgvector, exposes search to Claude",
   "license": "MIT",
   "main": "dist/app.js",