clast-ai 0.1.2 → 0.2.1

package/src/server/index.ts

@@ -1,109 +1,420 @@
-#!/usr/bin/env node
-
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { z } from 'zod';
 
-import { loadConfig, resolveDbPath } from '../config/index.js';
-import { ClastDatabase } from '../db/index.js';
-import { ParserManager } from '../parser/index.js';
+import { Clast } from '../engine.js';
 import { FileWatcher } from '../watcher/index.js';
-import { LlmClient } from '../llm/index.js';
 import { CommentGenerator } from '../llm/comment-generator.js';
-import { registerAllTools } from './register-tools.js';
+import { SYMBOL_KINDS } from '../types.js';
+import { findSymbols } from '../query/resolve.js';
+import { symLine } from '../query/format.js';
+import { ToolContext } from '../tools/context.js';
+import { callGraph, getContext, hierarchy, search } from '../tools/search.js';
+import { changes, fileSummary, grep, overview, references, reindex, status } from '../tools/explore.js';
+import { impact, unused } from '../tools/impact.js';
+import { stats } from '../tools/stats.js';
+import { VERSION } from '../version.js';
+
+const INSTRUCTIONS = `Clast is a pre-built, always-fresh code index for this repository. One call answers what otherwise takes several grep + read round trips, with exact file:line locations. Use it first for code navigation:
+- Unfamiliar repo or directory -> clast_overview, then clast_file_summary.
+- Where is X / what is it called -> clast_search (names, partial names, Class.method, or words describing behaviour).
+- Show me X, or before editing X -> clast_get_context (source of that symbol plus callers and callees).
+- Who calls X -> clast_call_graph (depth N), clast_references (every use, including types and imports).
+- Before changing or deleting X: what else must change, and which tests to run -> clast_impact.
+- Dead code, cleanup after a refactor -> clast_unused.
+- What implements / extends / overrides X, which base class to extend -> clast_hierarchy.
+- How many X, how big, what is it made of -> clast_stats (exact totals; do not count search results by hand).
+- Strings, comments, config keys -> clast_grep. After a change -> clast_changes (touched symbols, affected callers, tests).
+
+When implementing a change: find the sibling implementations with clast_hierarchy or clast_search, read one with clast_get_context, and list every caller or switch you must update with clast_call_graph / clast_references before editing.
+Most tools take several names at once (arrays). Symbols: name, Container.name, or path/to/file.ext:name. "?" marks a name-based guess. The index follows file changes, including your own edits.`;
+
+const text = (t: string) => ({ content: [{ type: 'text' as const, text: t }] });
+
+const READ_ONLY = { readOnlyHint: true, idempotentHint: true, openWorldHint: false } as const;
+
+// Claude Code defers MCP tools behind its tool search by default. Measured on vscode and OnAir
+// (bench/ab.mjs): with the tools deferred the agent answered every question with Grep and never
+// called clast (0 of 60 sessions); loaded up front it used clast in 8 of 10. This asks the client
+// to keep the navigation tools loaded.
+const ALWAYS_LOAD = { 'anthropic/alwaysLoad': true } as const;
 
-async function main() {
-  // Determine project root
+export async function startServer(): Promise<void> {
   const projectRoot = resolve(
-    process.env.CLAST_PROJECT_DIR ??
-    process.env.CLAUDE_PROJECT_DIR ??
-    process.cwd()
+    process.env.CLAST_PROJECT_DIR ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
   );
+  const log = (msg: string): void => {
+    console.error(`[clast] ${msg}`);
+  };
+  log(`v${VERSION} project root: ${projectRoot}`);
 
-  console.error(`[clast] Project root: ${projectRoot}`);
+  const clast = new Clast(projectRoot);
+  const ctx = new ToolContext(clast);
+  const watcher = new FileWatcher(clast.indexer, clast.config.watch.debounceMs);
+  const commentGen = new CommentGenerator(clast.db, clast.config, ctx.lines);
 
-  // Load configuration
-  const config = loadConfig(projectRoot);
-  console.error(`[clast] Config loaded. Languages: ${config.languages.join(', ')}`);
+  const server = new McpServer({ name: 'clast', version: VERSION }, { instructions: INSTRUCTIONS });
 
-  // Open database (async — sql.js uses WASM)
-  const dbPath = resolveDbPath(projectRoot, config);
-  console.error(`[clast] Database: ${dbPath}`);
-  const db = await ClastDatabase.open(dbPath);
+  const names = z.union([z.string(), z.array(z.string()).max(20)]);
+  const guard = <A>(fn: (args: A) => Promise<string>, gated = true) => async (args: A) => {
+    try {
+      if (gated) {
+        const building = await ctx.gate();
+        if (building) return text(building);
+      }
+      return text(await fn(args));
+    } catch (err) {
+      log(`tool error: ${err instanceof Error ? err.stack ?? err.message : err}`);
+      return { ...text(`error: ${err instanceof Error ? err.message : String(err)}`), isError: true };
+    }
+  };
 
-  // Create parser (async — web-tree-sitter uses WASM)
-  const parser = new ParserManager(config);
-  await parser.init();
+  server.registerTool(
+    'clast_search',
+    {
+      title: 'Search symbols',
+      description:
+        'Ranked symbol search. Query by exact, partial or abbreviated name ("parseConf", "pcfg"), typo, "Class.method", or plain words describing behaviour (matched against names, signatures, docs and the identifiers used in function bodies). Returns kind, qualified name, file:line, signature and doc summary. Prefer over grep for finding definitions. Array = several searches.',
+      inputSchema: {
+        query: names.describe('Name, partial name, Container.name, or descriptive words. Array = several searches.'),
+        kind: z.enum(SYMBOL_KINDS as [string, ...string[]]).optional().describe('Only this kind of symbol'),
+        path: z.string().optional().describe('Only symbols in files under / matching this path (e.g. "src/db" or "parser.ts")'),
+        lang: z.string().optional().describe('Only this language id (typescript, python, go, ...)'),
+        exported: z.boolean().optional().describe('Only exported / public symbols'),
+        limit: z.number().int().min(1).max(100).default(10).describe('Max results per query'),
+      },
+      annotations: READ_ONLY,
+      _meta: ALWAYS_LOAD,
+    },
+    guard(args => search(ctx, args))
+  );
 
-  // Create watcher
-  const watcher = new FileWatcher(projectRoot, config, db, parser);
+  server.registerTool(
+    'clast_get_context',
+    {
+      title: 'Symbol source and context',
+      description:
+        'One symbol in one call: its exact source with line numbers plus callers, callees, overloads, overrides and, for classes, members and sub/supertypes. Use INSTEAD of reading a whole file, and before editing a symbol. Address as "name", "Class.method", "path/file.ext:name" or "path/file.ext:<line>". Array = several symbols.',
+      inputSchema: {
+        name: names.describe('Symbol name, Container.name, or path:name. Array = several symbols.'),
+        path: z.string().optional().describe('Disambiguate by file or directory path'),
+        includeBody: z.boolean().default(true).describe('Include source code (false = signature + docs only)'),
+        maxLines: z.number().int().min(5).max(2000).default(120).describe('Max source lines per symbol; large classes fall back to a member outline'),
+        includeCalls: z.boolean().default(true).describe('Include callers and callees'),
+      },
+      annotations: READ_ONLY,
+      _meta: ALWAYS_LOAD,
+    },
+    guard(args => getContext(ctx, args))
+  );
 
-  // Create LLM client + comment generator
-  const llmClient = new LlmClient(config.llm.endpoint, config.llm.model, config.llm.apiKey);
-  const commentGen = new CommentGenerator(llmClient, db.queries, config);
+  server.registerTool(
+    'clast_call_graph',
+    {
+      title: 'Call graph',
+      description:
+        'Callers and/or callees as a tree with file:line per edge; depth > 1 follows the chain. Use for the blast radius before a change (every caller to update) or to trace a path. Resolved by receiver type, imports and inheritance; "?" marks name-only matches. Test callers are summarised. Library names list their call sites.',
+      inputSchema: {
+        name: z.string().describe('Symbol name, Container.name, or path:name'),
+        path: z.string().optional().describe('Disambiguate by file or directory path'),
+        direction: z.enum(['callers', 'callees', 'both']).default('both'),
+        depth: z.number().int().min(1).max(6).default(1).describe('Levels to traverse (1 = direct only; 2-3 to follow a chain)'),
+        limit: z.number().int().min(1).max(2000).default(50).describe('Max nodes per direction'),
+        includeTests: z.boolean().optional().describe('true = list test callers in full, false = drop them; default: one summary line naming the test files'),
+        within: z.string().optional().describe('Only callers located under this path (e.g. "src/server")'),
+        uncertain: z.boolean().default(false).describe('List every unconfirmed caller instead of a short summary'),
+      },
+      annotations: READ_ONLY,
+      _meta: ALWAYS_LOAD,
+    },
+    guard(args => callGraph(ctx, args))
+  );
 
-  if (llmClient.isConfigured) {
-    console.error(`[clast] LLM configured: ${config.llm.model} @ ${config.llm.endpoint}`);
-  } else {
-    console.error('[clast] LLM not configured (comment generation disabled)');
-  }
+  server.registerTool(
+    'clast_hierarchy',
+    {
+      title: 'Type hierarchy',
+      description:
+        'Supertypes and all direct and indirect subtypes of a class, interface, struct or trait as a tree (including Go interface satisfaction). For a method: the same method on related types (declaration, overrides, implementations). Use for "what implements X", "which classes override Y", "which base class do the others extend".',
+      inputSchema: {
+        name: z.string().describe('Type or method: name, Container.name, or path:name'),
+        path: z.string().optional().describe('Disambiguate by file or directory path'),
+        direction: z.enum(['supertypes', 'subtypes', 'both']).default('both'),
+        depth: z.number().int().min(1).max(8).default(3).describe('Levels to expand'),
+        limit: z.number().int().min(1).max(1000).default(80).describe('Max lines per direction'),
+        within: z.string().optional().describe('Only subtypes / overrides located under this path'),
+      },
+      annotations: READ_ONLY,
+      _meta: ALWAYS_LOAD,
+    },
+    guard(args => hierarchy(ctx, args))
+  );
 
-  // Create MCP server
-  const server = new McpServer({
-    name: 'clast',
-    version: '0.1.0',
-  });
+  server.registerTool(
+    'clast_references',
+    {
+      title: 'Find references',
+      description:
+        'Every use of an identifier (calls, type annotations, imports, assignments) grouped by file, each line with its enclosing function/class. Matches real identifiers only, not substrings, strings or comments. Use for variables, types, fields, constants and enum members, or when clast_call_graph is too narrow.',
+      inputSchema: {
+        name: z.string().describe('Identifier (or Container.name; matching is by the last name segment)'),
+        path: z.string().optional().describe('Only references in files under / matching this path'),
+        limit: z.number().int().min(1).max(500).default(40).describe('Max reference lines'),
+        includeTests: z.boolean().default(true),
+      },
+      annotations: READ_ONLY,
+      _meta: ALWAYS_LOAD,
+    },
+    guard(args => references(ctx, args))
+  );
 
-  // Register all tools
-  registerAllTools(server, db, parser, watcher, commentGen, projectRoot);
+  server.registerTool(
+    'clast_file_summary',
+    {
+      title: 'File or directory outline',
+      description:
+        'Outline of a file: symbols as a tree of signatures with line ranges and doc summaries, plus its imports and importers. Use INSTEAD of reading a file to learn its structure. For a directory: its files with main symbols and sub-directories with sizes. Partial paths work ("db/queries").',
+      inputSchema: {
+        path: z.string().describe('File or directory path (relative; partial paths are matched)'),
+        members: z
+          .enum(['auto', 'all', 'callable'])
+          .default('auto')
+          .describe('Whether to list fields/properties/constants inside classes (auto hides them in very large files)'),
+        limit: z.number().int().min(20).max(5000).default(300).describe('Max outline lines for a file'),
+      },
+      annotations: READ_ONLY,
+      _meta: ALWAYS_LOAD,
+    },
+    guard(args => fileSummary(ctx, args))
+  );
 
-  // Perform initial index
-  console.error('[clast] Starting initial index...');
-  const indexResult = await parser.fullIndex(projectRoot, db, (file, current, total) => {
-    if (current % 50 === 0 || current === total) {
-      console.error(`[clast] Indexing: ${current}/${total} files`);
-    }
-  });
-  console.error(
-    `[clast] Index complete: ${indexResult.filesProcessed} files, ` +
-    `${indexResult.nodesFound} nodes, ${indexResult.edgesResolved} edges resolved ` +
-    `(${indexResult.durationMs}ms)`
+  server.registerTool(
+    'clast_overview',
+    {
+      title: 'Repository map',
+      description:
+        'Map of the repository or a sub-directory: languages, layout with sizes, most referenced classes/functions, hub files, entry points. Call first in an unfamiliar codebase.',
+      inputSchema: {
+        path: z.string().optional().describe('Sub-directory to map (default: whole repository)'),
+      },
+      annotations: READ_ONLY,
+      _meta: ALWAYS_LOAD,
+    },
+    guard(args => overview(ctx, args))
   );
 
-  // Start file watcher
-  watcher.start();
-  watcher.on('indexed', ({ filePath, nodesFound }: { filePath: string; nodesFound: number }) => {
-    console.error(`[clast] Updated: ${filePath} (${nodesFound} nodes)`);
-  });
-  watcher.on('deleted', ({ filePath }: { filePath: string }) => {
-    console.error(`[clast] Removed: ${filePath}`);
-  });
-  watcher.on('error', ({ filePath, error }: { filePath: string; error: Error }) => {
-    console.error(`[clast] Error processing ${filePath}:`, error.message);
-  });
+  server.registerTool(
+    'clast_grep',
+    {
+      title: 'Text search with symbol context',
+      description:
+        'Text search over all text files (literal or regex, smart-case); each hit is labelled with its enclosing function/class. Use for strings, comments, error messages and config keys; for identifiers prefer clast_search / clast_references.',
+      inputSchema: {
+        pattern: z.string().describe('Text to find (literal unless regex=true)'),
+        regex: z.boolean().default(false).describe('Interpret pattern as a JavaScript regular expression'),
+        path: z.string().optional().describe('Only files under / matching this path'),
+        lang: z.string().optional().describe('Only this language id'),
+        caseSensitive: z.boolean().optional().describe('Default: case-insensitive unless the pattern contains uppercase'),
+        limit: z.number().int().min(1).max(500).default(50).describe('Max matching lines'),
+        includeTests: z.boolean().default(true),
+      },
+      annotations: READ_ONLY,
+      _meta: ALWAYS_LOAD,
+    },
+    guard(args => grep(ctx, args))
+  );
+
+  server.registerTool(
+    'clast_stats',
+    {
+      title: 'Count and aggregate',
+      description:
+        'Exact counts for "how many ..." questions, grouped by directory, file, kind or name; do not tally search results by hand. what = inventory (size, languages, production vs tests, symbols by kind, longest functions), symbols (name pattern "*Receiver|*Service" and/or kind), subtypes (direct and indirect subclasses / implementers), calls (call sites of "query|execute", optionally on a receiver), text (regex), imports (external dependencies), endpoints (route declarations of common web frameworks), database (SQL, schema, ORM models, query calls; heuristic).',
+      inputSchema: {
+        what: z.enum(['inventory', 'symbols', 'subtypes', 'calls', 'text', 'imports', 'endpoints', 'database']).optional()
+          .describe('What to count (default inventory, or symbols when name is given)'),
+        name: z.string().optional().describe('symbols: name pattern with * and | ; subtypes: base type; calls: called name(s); text: regular expression'),
+        kind: z.string().optional().describe('symbols: only these kinds, comma separated (class, interface, function, method, ...)'),
+        on: z.string().optional().describe('calls: only on receivers / receiver types matching this pattern'),
+        path: z.string().optional().describe('Only files under / matching this path'),
+        lang: z.string().optional().describe('Only this language id'),
+        groupBy: z.enum(['dir', 'file', 'kind', 'lang', 'name', 'container', 'callee', 'caller', 'receiver', 'match']).optional()
+          .describe('Grouping of the main table (default dir)'),
+        depth: z.number().int().min(1).max(12).optional().describe('Directory depth for groupBy=dir (default 2)'),
+        limit: z.number().int().min(1).max(500).optional().describe('Rows per table (default 25)'),
+        includeTests: z.boolean().optional().describe('Include tests/examples in the tables (default: counted separately)'),
+      },
+      annotations: READ_ONLY,
+      _meta: ALWAYS_LOAD,
+    },
+    guard(args => stats(ctx, args))
+  );
 
-  if (watcher.isActive) {
-    console.error('[clast] File watcher active');
-  }
+  server.registerTool(
+    'clast_impact',
+    {
+      title: 'Impact of changing a symbol',
+      description:
+        'Before changing a signature, behaviour or deleting a symbol: one answer with the declarations / overrides / implementations that must change together, every direct caller by file and line, how far the change reaches through indirect callers, and the test files to run (those that call it directly or through its callers).',
+      inputSchema: {
+        name: z.string().describe('Symbol: name, Container.name, or path:name'),
+        path: z.string().optional().describe('Disambiguate by file or directory path'),
+        depth: z.number().int().min(1).max(6).optional().describe('Caller levels to follow (default 3)'),
+        limit: z.number().int().min(1).max(500).optional().describe('Max lines per section (default 30)'),
+      },
+      annotations: READ_ONLY,
+      _meta: ALWAYS_LOAD,
+    },
+    guard(args => impact(ctx, args))
+  );
+
+  server.registerTool(
+    'clast_unused',
+    {
+      title: 'Unused code',
+      description:
+        'Dead code: functions, methods and types that nothing references (or that only other unused code references), grouped by file with line ranges; plus code used only by tests, and names that only appear in strings or comments. Entry points, decorated / attribute-marked symbols and overrides of library types are left out. Use after a refactor or to clean up a directory.',
+      inputSchema: {
+        path: z.string().optional().describe('Only judge symbols under / matching this path'),
+        lang: z.string().optional().describe('Only this language id'),
+        kind: z.string().optional().describe('Kinds to judge, comma separated (default function, method, class, struct, interface, trait, enum, type)'),
+        exported: z.boolean().optional().describe('false: leave out exported / public symbols'),
+        limit: z.number().int().min(1).max(1000).optional().describe('Max symbols listed (default 60)'),
+      },
+      annotations: READ_ONLY,
+      _meta: ALWAYS_LOAD,
+    },
+    guard(args => unused(ctx, args))
+  );
 
-  // Connect to stdio transport
+  server.registerTool(
+    'clast_changes',
+    {
+      title: 'Changed symbols and impact',
+      description:
+        'Map the current git diff to code structure: which functions/classes were touched (uncommitted changes by default, or relative to a base ref such as "main"), which callers outside the change may be affected, and which test files exercise the changed symbols. Use when reviewing a change, before committing, or to decide which tests to run.',
+      inputSchema: {
+        base: z.string().optional().describe('Git ref to diff against (default HEAD = uncommitted changes; e.g. "main", "HEAD~3")'),
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    guard(args => changes(ctx, args))
+  );
+
+  server.registerTool(
+    'clast_status',
+    {
+      title: 'Index status',
+      description: 'Index statistics and health: files, symbols, languages, whether indexing is in progress, watcher state.',
+      inputSchema: {},
+      annotations: READ_ONLY,
+    },
+    guard(() => status(ctx, watcher), false)
+  );
+
+  server.registerTool(
+    'clast_reindex',
+    {
+      title: 'Re-index',
+      description:
+        'Re-scan the repository (incremental: only changed files are re-parsed) or force re-index one file. Rarely needed - the index follows file changes automatically and re-checks files when they are queried. Use force=true to rebuild from scratch.',
+      inputSchema: {
+        path: z.string().optional().describe('Single file to re-index (default: whole repository)'),
+        force: z.boolean().default(false).describe('Re-parse every file even if unchanged'),
+      },
+      annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    guard(args => reindex(ctx, args), false)
+  );
+
+  server.registerTool(
+    'clast_comment',
+    {
+      title: 'Get or generate documentation',
+      description:
+        'Return the documentation comment of a symbol. With generate=true and a local LLM configured (llm.model in clast.config.json), generates and stores a doc comment for undocumented symbols.',
+      inputSchema: {
+        name: z.string().describe('Symbol name, Container.name, or path:name'),
+        generate: z.boolean().default(false).describe('Generate with the configured LLM if no comment exists'),
+      },
+      annotations: { readOnlyHint: false, openWorldHint: true },
+    },
+    guard(async ({ name, generate }: { name: string; generate: boolean }) => {
+      await ctx.ready();
+      const matches = findSymbols(ctx.db, name);
+      if (matches.length === 0) return `"${name}": no symbol with this name.`;
+      const out: string[] = [];
+      for (const sym of matches.slice(0, 5)) {
+        out.push(symLine(sym));
+        const stored = commentGen.stored(sym);
+        if (sym.doc) out.push(sym.doc);
+        else if (stored) out.push(`[generated] ${stored}`);
+        else if (generate) {
+          if (!commentGen.isAvailable) out.push('(no comment; LLM not configured - set llm.model in clast.config.json)');
+          else out.push((await commentGen.generate(sym)) ?? '(generation failed; see server log)');
+        } else out.push('(no comment)');
+      }
+      return out.join('\n');
+    })
+  );
+
+  // Connect first so the client never waits on indexing; the index builds
+  // (or revalidates) in the background and tools report progress meanwhile.
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error('[clast] MCP server running on stdio');
-
-  // Graceful shutdown
-  const shutdown = () => {
-    console.error('[clast] Shutting down...');
-    watcher.stop();
-    db.close();
-    process.exit(0);
-  };
+  log('MCP server running on stdio');
+
+  clast.indexer
+    .indexAll()
+    .then(r => {
+      const s = clast.db.stats();
+      log(
+        `index ready: scanned ${r.scanned}, parsed ${r.parsed}, removed ${r.removed} in ${r.durationMs}ms ` +
+          `(${s.files} files, ${s.symbols} symbols)`
+      );
+    })
+    .catch(err => log(`indexing failed: ${err instanceof Error ? err.stack : err}`))
+    .finally(() => {
+      if (clast.config.watch.enabled) {
+        try {
+          watcher.start();
+          log('file watcher active');
+        } catch (err) {
+          log(`watcher failed to start: ${err instanceof Error ? err.message : err}`);
+        }
+      }
+    });
 
+  watcher.on('error', ({ filePath, error }: { filePath: string; error: Error }) => {
+    log(`watch error ${filePath}: ${error.message}`);
+  });
+
+  let closing = false;
+  const shutdown = (): void => {
+    if (closing) return;
+    closing = true;
+    watcher
+      .stop()
+      .catch(() => undefined)
+      .finally(() => {
+        try { clast.close(); } catch { /* already closed */ }
+        process.exit(0);
+      });
+  };
   process.on('SIGINT', shutdown);
   process.on('SIGTERM', shutdown);
+  // The client closing stdin is the normal way an MCP server is stopped.
+  process.stdin.on('close', shutdown);
 }
 
-main().catch((err) => {
-  console.error('[clast] Fatal error:', err);
-  process.exit(1);
-});
+// Backwards compatibility: configurations written for 0.1.x launch this file
+// directly (`node dist/server/index.js`). Keep that working.
+const invoked = process.argv[1] ? pathToFileURL(process.argv[1]).href : '';
+if (invoked === import.meta.url) {
+  startServer().catch(err => {
+    console.error('[clast] Fatal error:', err);
+    process.exit(1);
+  });
+}

package/src/tools/context.ts

@@ -0,0 +1,82 @@
+import type { Clast } from '../engine.js';
+import { LineCache } from '../query/format.js';
+import { Resolver } from '../query/resolve.js';
+
+/**
+ * Per-engine state shared by all tool implementations.
+ */
+export class ToolContext {
+  readonly lines: LineCache;
+  private resolverGen = -1;
+  private resolverCache: Resolver | null = null;
+  /** How long a query waits for an in-flight bulk index before answering from a partial index. */
+  waitMs = 8000;
+
+  constructor(readonly clast: Clast) {
+    this.lines = new LineCache(clast.root);
+  }
+
+  get db() {
+    return this.clast.db;
+  }
+
+  get indexer() {
+    return this.clast.indexer;
+  }
+
+  /** Resolver whose caches are valid for the current database generation. */
+  get resolver(): Resolver {
+    if (!this.resolverCache || this.resolverGen !== this.db.generation) {
+      this.resolverCache = new Resolver(this.db);
+      this.resolverGen = this.db.generation;
+    }
+    return this.resolverCache;
+  }
+
+  /**
+   * Called at the start of every query tool. Waits briefly for a running
+   * bulk index; returns a note to prepend when results may be incomplete.
+   */
+  async ready(): Promise<string> {
+    if (!this.indexer.isIndexing) return '';
+    const done = await this.indexer.whenIdle(this.waitMs);
+    if (done) return '';
+    const p = this.indexer.progress;
+    return `note: index is still being built (${p.done}/${p.total} files parsed) - results may be incomplete; retry shortly.\n\n`;
+  }
+
+  /**
+   * Gate for query tools: waits briefly for a running index. If a FIRST-TIME
+   * build is still going after that, returns a message to send instead of
+   * running the query (the half-loaded index has no lookup indexes yet, so a
+   * query would be slow and incomplete). Otherwise returns null.
+   */
+  async gate(): Promise<string | null> {
+    if (!this.indexer.isIndexing) return null;
+    const done = await this.indexer.whenIdle(this.waitMs);
+    if (done || !this.indexer.coldBuild) return null;
+    const p = this.indexer.progress;
+    const pct = p.total ? Math.floor((100 * p.done) / p.total) : 0;
+    return (
+      `clast is building its index for the first time (${p.done}/${p.total} files, ${pct}%). ` +
+      `This takes seconds to about half a minute depending on repository size; call again shortly. ` +
+      `(Later sessions start from the saved index and are ready immediately.)`
+    );
+  }
+
+  /** Re-index any of these files that changed on disk since they were indexed. */
+  async fresh(paths: Iterable<string>): Promise<void> {
+    const list = [...paths];
+    const updated = await this.indexer.ensureFresh(list);
+    if (updated > 0) {
+      for (const p of list) this.lines.invalidate(p);
+    }
+  }
+}
+
+/** Accept `"a"`, `["a", "b"]` or `"a, b"` for batched lookups. */
+export function toList(value: string | string[] | undefined, splitCommas = false): string[] {
+  if (value === undefined) return [];
+  const arr = Array.isArray(value) ? value : splitCommas ? value.split(',') : [value];
+  return arr.map(s => s.trim()).filter(Boolean);
+}