@tai-io/codesearch 2026.313.1614

package/dist/state/registry.js

@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getRegistryPath } from '../paths.js';
+function readRegistry() {
+    const registryPath = getRegistryPath();
+    try {
+        const data = fs.readFileSync(registryPath, 'utf-8');
+        return JSON.parse(data);
+    }
+    catch {
+        return {};
+    }
+}
+function writeRegistry(registry) {
+    const registryPath = getRegistryPath();
+    const dir = path.dirname(registryPath);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2) + '\n', 'utf-8');
+}
+export function registerProject(absolutePath) {
+    const name = path.basename(absolutePath).toLowerCase();
+    const registry = readRegistry();
+    registry[name] = absolutePath;
+    writeRegistry(registry);
+}
+export function resolveProject(project) {
+    const registry = readRegistry();
+    return registry[project.toLowerCase()];
+}
+export function listProjects() {
+    return readRegistry();
+}
+export function findProjectByPath(dir) {
+    const registry = readRegistry();
+    const normalized = dir.replace(/\\/g, '/').toLowerCase();
+    let best;
+    for (const projPath of Object.values(registry)) {
+        const normProj = projPath.replace(/\\/g, '/').toLowerCase();
+        if (normalized === normProj || normalized.startsWith(normProj + '/')) {
+            if (!best || projPath.length > best.length)
+                best = projPath;
+        }
+    }
+    return best;
+}
+//# sourceMappingURL=registry.js.map

package/dist/state/snapshot.d.ts

@@ -0,0 +1,26 @@
+import type { VectorDB } from '../vectordb/types.js';
+export type CodebaseStatus = 'idle' | 'indexing' | 'indexed' | 'error';
+export interface CodebaseState {
+    path: string;
+    collectionName: string;
+    status: CodebaseStatus;
+    lastIndexed?: string;
+    totalFiles?: number;
+    totalChunks?: number;
+    error?: string;
+    progress?: number;
+    progressMessage?: string;
+}
+export declare class StateManager {
+    private states;
+    getState(normalizedPath: string): CodebaseState | undefined;
+    getAllStates(): CodebaseState[];
+    setIndexing(normalizedPath: string, collectionName: string): void;
+    updateProgress(normalizedPath: string, progress: number, message: string): void;
+    setIndexed(normalizedPath: string, totalFiles: number, totalChunks: number): void;
+    setError(normalizedPath: string, error: string): void;
+    remove(normalizedPath: string): void;
+    hydrate(registry: Record<string, string>, vectordb: VectorDB): Promise<number>;
+}
+export declare function cleanupOrphanedSnapshots(vectordb: VectorDB): Promise<number>;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/state/snapshot.js

@@ -0,0 +1,100 @@
+import { pathToCollectionName } from '../paths.js';
+import { listSnapshotCollections, deleteSnapshotByCollection } from '../vectordb/sqlite.js';
+export class StateManager {
+    states = new Map();
+    getState(normalizedPath) {
+        return this.states.get(normalizedPath);
+    }
+    getAllStates() {
+        return [...this.states.values()];
+    }
+    setIndexing(normalizedPath, collectionName) {
+        this.states.set(normalizedPath, {
+            path: normalizedPath,
+            collectionName,
+            status: 'indexing',
+            progress: 0,
+            progressMessage: 'Starting...',
+        });
+    }
+    updateProgress(normalizedPath, progress, message) {
+        const state = this.states.get(normalizedPath);
+        if (state) {
+            state.progress = progress;
+            state.progressMessage = message;
+        }
+    }
+    setIndexed(normalizedPath, totalFiles, totalChunks) {
+        const state = this.states.get(normalizedPath);
+        if (state) {
+            state.status = 'indexed';
+            state.lastIndexed = new Date().toISOString();
+            state.totalFiles = totalFiles;
+            state.totalChunks = totalChunks;
+            state.progress = 100;
+            state.progressMessage = 'Done';
+        }
+    }
+    setError(normalizedPath, error) {
+        const state = this.states.get(normalizedPath);
+        if (state) {
+            state.status = 'error';
+            state.error = error;
+        }
+    }
+    remove(normalizedPath) {
+        this.states.delete(normalizedPath);
+    }
+    async hydrate(registry, vectordb) {
+        let count = 0;
+        for (const [, projectPath] of Object.entries(registry)) {
+            try {
+                const collectionName = pathToCollectionName(projectPath);
+                const exists = await vectordb.hasCollection(collectionName);
+                if (exists && !this.states.has(projectPath)) {
+                    this.states.set(projectPath, {
+                        path: projectPath,
+                        collectionName,
+                        status: 'indexed',
+                    });
+                    count++;
+                }
+            }
+            catch (err) {
+                console.warn(`Hydration failed for ${projectPath}:`, err);
+            }
+        }
+        return count;
+    }
+}
+export async function cleanupOrphanedSnapshots(vectordb) {
+    let cleaned = 0;
+    try {
+        const collections = listSnapshotCollections();
+        if (collections.length === 0)
+            return 0;
+        const probeResult = await vectordb.hasCollection('__eidetic_connectivity_probe__');
+        if (probeResult) {
+            console.warn('Orphan cleanup skipped: connectivity probe returned unexpected result.');
+            return 0;
+        }
+        for (const collectionName of collections) {
+            try {
+                const exists = await vectordb.hasCollection(collectionName);
+                if (!exists) {
+                    deleteSnapshotByCollection(collectionName);
+                    console.log(`Cleaned orphaned snapshot: ${collectionName}`);
+                    cleaned++;
+                }
+            }
+            catch (err) {
+                console.warn(`Skipping orphan check for ${collectionName}:`, err);
+            }
+        }
+    }
+    catch (err) {
+        console.warn('Orphan cleanup skipped:', err);
+    }
+    return cleaned;
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/tool-schemas.d.ts

@@ -0,0 +1,215 @@
+export declare const TOOL_DEFINITIONS: readonly [{
+    readonly name: "index";
+    readonly description: "Index a codebase directory to enable semantic search using a configurable code splitter.\n\nProvide either `path` (absolute) or `project` (name). Use `list` to see registered projects.\n\nUsage Guidance:\n- Use dryRun=true first to preview what files would be indexed and catch configuration issues before committing to a full index.\n- This tool is typically used when search fails due to an unindexed codebase.\n- If indexing is attempted on an already indexed path, and a conflict is detected, you MUST prompt the user to confirm whether to proceed with a force index.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly description: "Absolute path to the codebase directory to index.";
+            };
+            readonly project: {
+                readonly type: "string";
+                readonly description: "Project name (resolves via registry). Use list to see registered projects.";
+            };
+            readonly force: {
+                readonly type: "boolean";
+                readonly description: "Force re-indexing even if already indexed";
+                readonly default: false;
+            };
+            readonly dryRun: {
+                readonly type: "boolean";
+                readonly description: "Preview what would be indexed without actually indexing. Returns file counts by extension, top directories, estimated cost, and warnings.";
+                readonly default: false;
+            };
+            readonly customExtensions: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Additional file extensions to include beyond defaults (e.g., [\".dart\", \".arb\"]). Extensions should include the dot prefix.";
+                readonly default: readonly [];
+            };
+            readonly customIgnorePatterns: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Additional glob patterns to exclude (e.g., [\"**/Pods/**\", \"**/DerivedData/**\"]).";
+                readonly default: readonly [];
+            };
+        };
+        readonly required: readonly [];
+    };
+}, {
+    readonly name: "search";
+    readonly description: "Search the indexed codebase using natural language queries.\nPrefer over Grep for conceptual/semantic queries — returns ~20 tokens/result vs ~100+ for Grep.\nTry before launching an Explore agent — faster and cheaper for understanding code.\n\nProvide either `path` (absolute) or `project` (name). Use `list` to see registered projects.\n\nWhen to Use:\n- Code search: Find specific functions, classes, or implementations\n- Context-aware assistance: Gather relevant code context before making changes\n- Issue identification: Locate problematic code sections or bugs\n- Code review: Understand existing implementations and patterns\n- Refactoring: Find all related code pieces that need to be updated\n- Feature development: Understand existing architecture and similar implementations\n- Duplicate detection: Identify redundant or duplicated code patterns\n\nIf the codebase is not indexed, this tool will return a clear error message indicating that indexing is required first.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly description: "Absolute path to the codebase directory to search in.";
+            };
+            readonly project: {
+                readonly type: "string";
+                readonly description: "Project name (resolves via registry). Use list to see registered projects.";
+            };
+            readonly query: {
+                readonly type: "string";
+                readonly description: "Natural language query to search for in the codebase";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "Maximum number of results to return";
+                readonly default: 10;
+                readonly maximum: 50;
+            };
+            readonly extensionFilter: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Optional: List of file extensions to filter results (e.g., [\".ts\", \".py\"]).";
+                readonly default: readonly [];
+            };
+            readonly compact: {
+                readonly type: "boolean";
+                readonly description: "Return compact table (file, lines, score, ~tokens) instead of full code snippets. Use Read tool to fetch interesting results. Default: true.";
+                readonly default: true;
+            };
+        };
+        readonly required: readonly ["query"];
+    };
+}, {
+    readonly name: "clear";
+    readonly description: "Clear the search index. Provide either `path` (absolute) or `project` (name). Use `list` to see registered projects.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly description: "Absolute path to the codebase directory to clear.";
+            };
+            readonly project: {
+                readonly type: "string";
+                readonly description: "Project name (resolves via registry). Use list to see registered projects.";
+            };
+        };
+        readonly required: readonly [];
+    };
+}, {
+    readonly name: "list";
+    readonly description: "List all currently indexed codebases with their status. Returns paths, file/chunk counts, and indexing status for all known codebases in this session.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly required: readonly [];
+    };
+}, {
+    readonly name: "cleanup";
+    readonly description: "Remove orphaned vectors for files that no longer exist on disk. Lightweight alternative to re-indexing — no embedding cost.\n\nProvide either `path` (absolute) or `project` (name). Use `list` to see registered projects.\n\nUse `dryRun=true` first to preview which files would be cleaned without making any changes.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly description: "Absolute path to the codebase directory.";
+            };
+            readonly project: {
+                readonly type: "string";
+                readonly description: "Project name (resolves via registry). Use list to see registered projects.";
+            };
+            readonly dryRun: {
+                readonly type: "boolean";
+                readonly description: "List files that would be cleaned without actually deleting any vectors.";
+                readonly default: false;
+            };
+        };
+        readonly required: readonly [];
+    };
+}, {
+    readonly name: "ingest";
+    readonly description: "Cache external documentation (from query-docs, WebFetch, etc.) for cheap semantic search later.\n\nAfter fetching documentation from an external source, call this tool to store it. Subsequent queries about the same library will use lookup (~20 tokens/result) instead of re-fetching (~5K+ tokens).\n\nThe content is split into chunks, embedded, and stored in a vector collection grouped by library. A TTL tracks staleness — stale docs still return results but are flagged.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly content: {
+                readonly type: "string";
+                readonly description: "The full text content of the documentation to cache.";
+            };
+            readonly source: {
+                readonly type: "string";
+                readonly description: "Source URL or identifier (e.g., \"https://docs.langfuse.com/guides/evaluators\" or \"context7:langfuse/hooks\").";
+            };
+            readonly library: {
+                readonly type: "string";
+                readonly description: "Library name (e.g., \"react\", \"langfuse\"). Used for collection grouping.";
+            };
+            readonly topic: {
+                readonly type: "string";
+                readonly description: "Topic within the library (e.g., \"hooks\", \"evaluators\").";
+            };
+            readonly ttlDays: {
+                readonly type: "number";
+                readonly description: "Days before the cached content is considered stale.";
+                readonly default: 7;
+            };
+        };
+        readonly required: readonly ["content", "source", "library", "topic"];
+    };
+}, {
+    readonly name: "lookup";
+    readonly description: "Search cached documentation using natural language queries.\n\nReturns results from previously cached documentation (via ingest). Much cheaper than re-fetching docs (~20 tokens/result vs ~5K+ tokens/fetch).\n\nIf a specific library is provided, searches only that library's collection. Otherwise searches across all cached documentation. Results include staleness indicators.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "Natural language query to search cached documentation.";
+            };
+            readonly library: {
+                readonly type: "string";
+                readonly description: "Optional: limit search to a specific library (e.g., \"langfuse\"). Omit to search all cached docs.";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "Maximum number of results to return.";
+                readonly default: 5;
+                readonly maximum: 20;
+            };
+        };
+        readonly required: readonly ["query"];
+    };
+}, {
+    readonly name: "browse";
+    readonly description: "Show a condensed structural map of the indexed codebase — classes, functions, methods with signatures, grouped by file.\nPrefer over Glob + Read cascades for understanding architecture — one call vs many.\n\nProvide either `path` (absolute) or `project` (name). Use `list` to see registered projects.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly description: "Absolute path to the codebase directory.";
+            };
+            readonly project: {
+                readonly type: "string";
+                readonly description: "Project name (resolves via registry). Use list to see registered projects.";
+            };
+            readonly pathFilter: {
+                readonly type: "string";
+                readonly description: "Glob pattern to filter by file path (e.g., \"src/core/**\", \"**/*.ts\").";
+            };
+            readonly kind: {
+                readonly type: "string";
+                readonly description: "Filter by symbol kind: function, class, interface, method, type, enum, etc.";
+            };
+            readonly maxTokens: {
+                readonly type: "number";
+                readonly description: "Approximate token budget for the output (1 token ≈ 4 chars). Default: 4000.";
+                readonly default: 4000;
+            };
+        };
+        readonly required: readonly [];
+    };
+}];
+//# sourceMappingURL=tool-schemas.d.ts.map

package/dist/tool-schemas.js

@@ -0,0 +1,269 @@
+const INDEX_DOCUMENT_DESCRIPTION = `\
+Cache external documentation (from query-docs, WebFetch, etc.) for cheap semantic search later.
+
+After fetching documentation from an external source, call this tool to store it. \
+Subsequent queries about the same library will use lookup (~20 tokens/result) \
+instead of re-fetching (~5K+ tokens).
+
+The content is split into chunks, embedded, and stored in a vector collection grouped by library. \
+A TTL tracks staleness — stale docs still return results but are flagged.`;
+const SEARCH_DOCUMENTS_DESCRIPTION = `\
+Search cached documentation using natural language queries.
+
+Returns results from previously cached documentation (via ingest). \
+Much cheaper than re-fetching docs (~20 tokens/result vs ~5K+ tokens/fetch).
+
+If a specific library is provided, searches only that library's collection. \
+Otherwise searches across all cached documentation. Results include staleness indicators.`;
+const CLEANUP_DESCRIPTION = `\
+Remove orphaned vectors for files that no longer exist on disk. Lightweight alternative to re-indexing — no embedding cost.
+
+Provide either \`path\` (absolute) or \`project\` (name). Use \`list\` to see registered projects.
+
+Use \`dryRun=true\` first to preview which files would be cleaned without making any changes.`;
+const INDEX_DESCRIPTION = `\
+Index a codebase directory to enable semantic search using a configurable code splitter.
+
+Provide either \`path\` (absolute) or \`project\` (name). Use \`list\` to see registered projects.
+
+Usage Guidance:
+- Use dryRun=true first to preview what files would be indexed and catch configuration issues before committing to a full index.
+- This tool is typically used when search fails due to an unindexed codebase.
+- If indexing is attempted on an already indexed path, and a conflict is detected, \
+you MUST prompt the user to confirm whether to proceed with a force index.`;
+const SEARCH_DESCRIPTION = `\
+Search the indexed codebase using natural language queries.
+Prefer over Grep for conceptual/semantic queries — returns ~20 tokens/result vs ~100+ for Grep.
+Try before launching an Explore agent — faster and cheaper for understanding code.
+
+Provide either \`path\` (absolute) or \`project\` (name). Use \`list\` to see registered projects.
+
+When to Use:
+- Code search: Find specific functions, classes, or implementations
+- Context-aware assistance: Gather relevant code context before making changes
+- Issue identification: Locate problematic code sections or bugs
+- Code review: Understand existing implementations and patterns
+- Refactoring: Find all related code pieces that need to be updated
+- Feature development: Understand existing architecture and similar implementations
+- Duplicate detection: Identify redundant or duplicated code patterns
+
+If the codebase is not indexed, this tool will return a clear error message \
+indicating that indexing is required first.`;
+export const TOOL_DEFINITIONS = [
+    {
+        name: 'index',
+        description: INDEX_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Absolute path to the codebase directory to index.',
+                },
+                project: {
+                    type: 'string',
+                    description: 'Project name (resolves via registry). Use list to see registered projects.',
+                },
+                force: {
+                    type: 'boolean',
+                    description: 'Force re-indexing even if already indexed',
+                    default: false,
+                },
+                dryRun: {
+                    type: 'boolean',
+                    description: 'Preview what would be indexed without actually indexing. Returns file counts by extension, top directories, estimated cost, and warnings.',
+                    default: false,
+                },
+                customExtensions: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Additional file extensions to include beyond defaults (e.g., [".dart", ".arb"]). Extensions should include the dot prefix.',
+                    default: [],
+                },
+                customIgnorePatterns: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Additional glob patterns to exclude (e.g., ["**/Pods/**", "**/DerivedData/**"]).',
+                    default: [],
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'search',
+        description: SEARCH_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Absolute path to the codebase directory to search in.',
+                },
+                project: {
+                    type: 'string',
+                    description: 'Project name (resolves via registry). Use list to see registered projects.',
+                },
+                query: {
+                    type: 'string',
+                    description: 'Natural language query to search for in the codebase',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of results to return',
+                    default: 10,
+                    maximum: 50,
+                },
+                extensionFilter: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional: List of file extensions to filter results (e.g., [".ts", ".py"]).',
+                    default: [],
+                },
+                compact: {
+                    type: 'boolean',
+                    description: 'Return compact table (file, lines, score, ~tokens) instead of full code snippets. Use Read tool to fetch interesting results. Default: true.',
+                    default: true,
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'clear',
+        description: 'Clear the search index. Provide either `path` (absolute) or `project` (name). Use `list` to see registered projects.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Absolute path to the codebase directory to clear.',
+                },
+                project: {
+                    type: 'string',
+                    description: 'Project name (resolves via registry). Use list to see registered projects.',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'list',
+        description: 'List all currently indexed codebases with their status. Returns paths, file/chunk counts, and indexing status for all known codebases in this session.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'cleanup',
+        description: CLEANUP_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Absolute path to the codebase directory.',
+                },
+                project: {
+                    type: 'string',
+                    description: 'Project name (resolves via registry). Use list to see registered projects.',
+                },
+                dryRun: {
+                    type: 'boolean',
+                    description: 'List files that would be cleaned without actually deleting any vectors.',
+                    default: false,
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'ingest',
+        description: INDEX_DOCUMENT_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                content: {
+                    type: 'string',
+                    description: 'The full text content of the documentation to cache.',
+                },
+                source: {
+                    type: 'string',
+                    description: 'Source URL or identifier (e.g., "https://docs.langfuse.com/guides/evaluators" or "context7:langfuse/hooks").',
+                },
+                library: {
+                    type: 'string',
+                    description: 'Library name (e.g., "react", "langfuse"). Used for collection grouping.',
+                },
+                topic: {
+                    type: 'string',
+                    description: 'Topic within the library (e.g., "hooks", "evaluators").',
+                },
+                ttlDays: {
+                    type: 'number',
+                    description: 'Days before the cached content is considered stale.',
+                    default: 7,
+                },
+            },
+            required: ['content', 'source', 'library', 'topic'],
+        },
+    },
+    {
+        name: 'lookup',
+        description: SEARCH_DOCUMENTS_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Natural language query to search cached documentation.',
+                },
+                library: {
+                    type: 'string',
+                    description: 'Optional: limit search to a specific library (e.g., "langfuse"). Omit to search all cached docs.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of results to return.',
+                    default: 5,
+                    maximum: 20,
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'browse',
+        description: 'Show a condensed structural map of the indexed codebase — classes, functions, methods with signatures, grouped by file.\nPrefer over Glob + Read cascades for understanding architecture — one call vs many.\n\nProvide either `path` (absolute) or `project` (name). Use `list` to see registered projects.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Absolute path to the codebase directory.',
+                },
+                project: {
+                    type: 'string',
+                    description: 'Project name (resolves via registry). Use list to see registered projects.',
+                },
+                pathFilter: {
+                    type: 'string',
+                    description: 'Glob pattern to filter by file path (e.g., "src/core/**", "**/*.ts").',
+                },
+                kind: {
+                    type: 'string',
+                    description: 'Filter by symbol kind: function, class, interface, method, type, enum, etc.',
+                },
+                maxTokens: {
+                    type: 'number',
+                    description: 'Approximate token budget for the output (1 token ≈ 4 chars). Default: 4000.',
+                    default: 4000,
+                },
+            },
+            required: [],
+        },
+    },
+];
+//# sourceMappingURL=tool-schemas.js.map