clast-ai 0.1.2 → 0.2.1

package/plugin/server.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// Starts the clast MCP server for the Claude Code plugin. A plugin is installed by cloning the
+// repository, which has no build output, so the server is taken from the first place that has one:
+//   1. this checkout, when it has been built (a development clone),
+//   2. a global `clast-ai` of the same minor version that is at least as new as the plugin,
+//   3. `npx clast-ai@<plugin version>` (downloaded on first use, cached afterwards).
+// Standard input and output are passed straight through: they carry the MCP protocol.
+//
+// After the server is up it also runs `clast-ai migrate --apply --auto` in the background. That
+// removes, once per version, what an older install left behind (hand-made MCP registrations that
+// would list every tool twice, the v0.1 index file), so installing or upgrading the plugin is
+// all a user has to do.
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const version = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version;
+const [major, minor, patch] = version.split('.').map(Number);
+const windows = process.platform === 'win32';
+const log = msg => process.stderr.write(`[clast plugin] ${msg}\n`);
+
+function pick() {
+  const local = join(root, 'dist', 'cli.js');
+  if (existsSync(local) && existsSync(join(root, 'node_modules'))) {
+    return { command: process.execPath, args: [local], shell: false, what: 'local build' };
+  }
+  const probe = windows
+    ? spawnSync('clast-ai --version', { encoding: 'utf8', shell: true, windowsHide: true })
+    : spawnSync('clast-ai', ['--version'], { encoding: 'utf8', windowsHide: true });
+  const found = probe.status === 0 ? probe.stdout.trim() : '';
+  const [fMajor, fMinor, fPatch] = found.split('.').map(Number);
+  if (found && fMajor === major && fMinor === minor && fPatch >= patch) {
+    return { command: 'clast-ai', args: [], shell: windows, what: `global clast-ai ${found}` };
+  }
+  if (found) log(`global clast-ai is ${found}, the plugin is ${version}: using npx instead (npm install -g clast-ai updates it)`);
+  return { command: 'npx', args: ['-y', `clast-ai@${version}`], shell: windows, what: `npx clast-ai@${version}` };
+}
+
+/** Run the chosen clast-ai with extra arguments. Through a shell (.cmd shims on Windows) the command is one string of fixed words. */
+function run(choice, extra, options) {
+  const args = [...choice.args, ...extra];
+  return choice.shell
+    ? spawn([choice.command, ...args].join(' '), { ...options, shell: true, windowsHide: true })
+    : spawn(choice.command, args, { ...options, windowsHide: true });
+}
+
+if (Number(process.versions.node.split('.')[0]) < 22) {
+  log(`Node.js 22.22 or newer is required (this is ${process.versions.node}).`);
+  process.exit(1);
+}
+const choice = pick();
+log(`starting ${choice.what}`);
+const child = run(choice, [], { stdio: 'inherit' });
+child.on('error', err => {
+  log(`could not start the server: ${err.message}. Install it with: npm install -g clast-ai`);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
+for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => child.kill(sig));
+
+// Clean up after older installs, without holding up or disturbing the server (no shared stdio).
+if (process.env.CLAST_NO_MIGRATE !== '1') {
+  try {
+    const cleanup = run(choice, ['migrate', '--apply', '--auto'], { stdio: 'ignore', detached: !windows });
+    cleanup.on('error', () => {});
+    cleanup.unref();
+  } catch {
+    // Never let the cleanup stop the server.
+  }
+}

package/skills/audit/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: audit
+description: Produce a factual inventory of a code base for due diligence or onboarding - size, languages, structure, endpoints, database access, dependencies, largest hot spots and dead code.
+argument-hint: "[path]"
+disable-model-invocation: true
+allowed-tools: mcp__plugin_clast_clast__clast_stats, mcp__plugin_clast_clast__clast_overview, mcp__plugin_clast_clast__clast_unused, mcp__plugin_clast_clast__clast_file_summary, mcp__plugin_clast_clast__clast_grep, Grep, Read, Glob
+---
+
+Produce an inventory of this code base. Scope: `$ARGUMENTS` (the whole project when empty; pass it as
+`path` to every call below).
+
+Gather the facts with these calls. They are independent, so issue them together:
+
+- `clast_stats` what=inventory: files, lines, languages, production vs tests vs vendored, symbols by
+  kind, longest functions.
+- `clast_overview`: the main directories and what lives in them.
+- `clast_stats` what=endpoints: HTTP / RPC routes by framework and by directory, and outbound client
+  calls.
+- `clast_stats` what=database: SQL, schema, ORM models, migrations, query call sites by receiver.
+- `clast_stats` what=imports: external dependencies by how many files use them.
+- `clast_unused` with the default limit: only the totals and the largest files matter here.
+
+Then write the report:
+
+1. **Size and shape**: lines and files per language, share of tests, vendored or generated code.
+2. **Structure**: the top-level areas with one line each on what they contain.
+3. **Interfaces**: number of endpoints by framework and area; outbound calls.
+4. **Data**: tables or models, migrations, where queries are issued from, the most-used models.
+5. **Dependencies**: the most-used external packages; anything unusual (several libraries for the same
+   job, very old or abandoned-looking packages if the manifest shows versions).
+6. **Maintainability signals**: the longest functions and largest files, the share of code used only
+   by tests, the amount of unused code.
+7. **Caveats**: endpoint and database figures come from pattern matching; dead code is judged by name.
+   Spot-check one figure from each of sections 3 and 4 with a Grep and state whether it matched.
+
+Use exact numbers from the tools; do not estimate or tally by hand. Keep it to what was measured: no
+opinions on quality that the numbers do not support.

package/skills/deadcode/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: deadcode
+description: Find dead code (unused functions, methods and types) in the project or under a path, verify the candidates, and offer to remove them.
+argument-hint: "[path]"
+disable-model-invocation: true
+allowed-tools: mcp__plugin_clast_clast__clast_unused, mcp__plugin_clast_clast__clast_call_graph, mcp__plugin_clast_clast__clast_references, mcp__plugin_clast_clast__clast_grep, Grep, Read
+---
+
+Find dead code. Scope: `$ARGUMENTS` (the whole project when empty).
+
+1. Call `clast_unused` with `path` set to the scope (omit it for the whole project). On a large
+   project start with the default limit; raise it only if the user wants the full list.
+2. The result has groups. Treat them differently:
+   - **unused**: the name is never referenced, or only by other unused code. Strong candidates.
+   - **probably unused**: the name is called, but every call binds to another definition. Check each
+     with `clast_call_graph` before reporting it.
+   - **used only by tests**: dead in production; removing it means removing the tests too. Report, do
+     not propose deleting without asking.
+   - **name appears in a string, config or template**: may be reached by reflection, routing or a
+     template. Open the cited location and say what it is.
+   - symbols marked `exported`: unused inside this project. In an application that is dead code; in a
+     library it may be public API. Say which case applies here (look for a published package, a
+     public header directory, or an API surface file).
+3. Verify before you present: for the candidates you intend to recommend (at most about 15), run one
+   Grep for the bare name across the repository and drop any that turn up in build files, scripts,
+   generated code or documentation that shows it is an entry point.
+4. Report as a short table grouped by file: symbol, lines, size, and why it is considered unused. Give
+   the total number of removable lines. State the limits in one sentence: the check is by name, so
+   members with common names (`get`, `run`) are never listed, and code reached only through reflection
+   can be listed wrongly.
+5. Do not delete anything yet. Ask which of the candidates to remove. When the user confirms, delete
+   them (and helpers that only they used), then build or run the tests the project has to confirm
+   nothing broke, and report the result.

package/skills/explore/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: explore
+description: >
+  How to get the most out of the clast code index: which tool answers which question, and the habits
+  that save round trips. Use when navigating, reviewing or about to change code in a repository that
+  has the clast MCP tools, especially for multi-step questions (call chains, subclasses, impact, counts,
+  dead code) or code described by behaviour instead of by name.
+---
+
+# Using the clast code index well
+
+Clast answers structural questions in one call. It does not replace Grep for "where is this exact
+name" or Read for code you are about to edit: measured against plain grep, clast wins on questions that
+take several hops, on counting, on dead code and on finding code by what it does; simple lookups are a
+tie. Use it where it wins.
+
+## Pick the tool by question
+
+| Question | Tool |
+|----------|------|
+| What is in this repo / directory / file? | `clast_overview`, then `clast_file_summary` |
+| Where is the code that does X (no name known)? | `clast_search` with a short description of the behaviour |
+| Show me X, I am about to edit X | `clast_get_context` (that symbol's source, callers, callees) |
+| Who calls X, through how many levels? | `clast_call_graph` (`depth` 2-3, `within` to scope) |
+| What implements / extends / overrides X? | `clast_hierarchy` |
+| What else must change with X, and which tests do I run? | `clast_impact` |
+| How many X? How big? Endpoints, database access, dependencies? | `clast_stats` (never tally search results by hand) |
+| What is unused? What did a refactor leave behind? | `clast_unused` |
+| What did my diff touch? | `clast_changes` |
+| Every use of an identifier, or a string / config key | `clast_references`, `clast_grep` |
+
+## Habits that save round trips
+
+- One call, not a loop: `clast_search` and `clast_get_context` take arrays of names; `clast_call_graph`
+  and `clast_hierarchy` take a `depth`.
+- Address symbols precisely: `Class.method`, `path/file.ext:name`, `path/file.ext:123`. A bare name
+  with several definitions returns the candidates; pick one, do not guess.
+- Read the symbol, not the file: `clast_get_context` returns exactly the definition's lines.
+- An edge marked `?` was matched by name only (the receiver's type is unknown). Verify it with a quick
+  Grep or Read before you rely on it; unmarked edges are resolved through types and imports.
+- Callers of a method include calls through its interface or base class, not calls bound to an override
+  in a subclass. For every implementation's callers ask for the interface or base method.
+- Before a signature change: `clast_impact` lists the overrides and declarations that change with it,
+  the callers by file and line, and the tests that reach it even when none names it.
+- `clast_unused` lists candidates judged by name. Members with common names (`get`, `run`) are never
+  listed, and reflection or framework wiring can keep a listed symbol alive: confirm with the compiler
+  or the tests before deleting.
+- Narrow with `path` (and `within` for call graphs) on large repositories; results and run time shrink.
+- The index follows file changes, including your own edits. There is no need to reindex.
+- If a tool says a name is not defined in the project, it is external or built at run time:
+  `clast_references` and `clast_grep` still find its uses.
+
+Slash commands in this plugin: `/clast:deadcode [path]`, `/clast:impact <symbol>`, `/clast:audit [path]`,
+`/clast:status`.

package/skills/impact/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: impact
+description: Show what a change to one function, method or type affects - what must change with it, every caller, and the tests to run.
+argument-hint: "<symbol>"
+disable-model-invocation: true
+allowed-tools: mcp__plugin_clast_clast__clast_impact, mcp__plugin_clast_clast__clast_search, mcp__plugin_clast_clast__clast_get_context, mcp__plugin_clast_clast__clast_call_graph, mcp__plugin_clast_clast__clast_hierarchy, Grep, Read
+---
+
+Assess the impact of changing `$ARGUMENTS`.
+
+1. If no symbol was given, ask which one. If the name is ambiguous, `clast_impact` lists the
+   candidates: pick the one the user means (ask when it is not obvious) and address it as
+   `Container.name` or `path/file.ext:name`.
+2. Call `clast_impact` for the symbol (default depth 3).
+3. Report, in this order and without padding:
+   - **Changes together**: declarations, overrides, implementations and overloads of the same member.
+   - **Direct callers**: by file with line numbers. Callers marked `?` are name-only matches: check
+     each with a quick Read of the cited line and say whether it is a real caller.
+   - **Reach**: how many functions in how many files depend on it indirectly, by area.
+   - **Tests to run**: the test files, split into those that call it directly and those that reach it
+     through callers. Give the project's command to run exactly those tests if you can tell what it is.
+   - If no test reaches it, say so plainly: that is the main risk of the change.
+4. End with a one-line verdict on the size of the change (local, moderate, wide) and what to edit
+   first. Do not start editing unless the user asks.

package/skills/status/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: status
+description: Show the state of the clast index for this project - files, symbols, languages, whether it is up to date.
+disable-model-invocation: true
+allowed-tools: mcp__plugin_clast_clast__clast_status, mcp__plugin_clast_clast__clast_reindex
+---
+
+Call `clast_status` and report in a few lines: files and symbols indexed, languages, whether the index
+is up to date or still building, and where the database is. If the index is still building, say how
+far it is. If the status shows a problem (no files, a failed run), say so and offer to run
+`clast_reindex`; do not reindex unasked.

package/src/cli.ts

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+// More I/O threads: the startup scan stats every source file, which is the
+// dominant warm-start cost. Must be set before the first async fs call.
+process.env.UV_THREADPOOL_SIZE ??= '16';
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { Clast } from './engine.js';
+import { SourceParser } from './parser/index.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, type StatsArgs } from './tools/stats.js';
+import { VERSION } from './version.js';
+
+const HELP = `clast-ai ${VERSION} - code index for LLM agents
+
+usage: clast-ai [command] [args] [--root <dir>]
+
+  (no command), serve        run the MCP server on stdio (what Claude Code launches)
+  index [--force]            build / update the index
+  status                     index statistics
+  overview [path]            repository map
+  outline <path>             file or directory outline
+  search <query...>          ranked symbol search   [--kind k] [--path p] [--lang l] [--limit n]
+  symbol <name...>           source + callers + callees of a symbol   [--path p] [--max-lines n] [--no-body]
+  callers <name>             who calls it   [--depth n] [--limit n] [--within path] [--no-tests|--tests] [--uncertain]
+  callees <name>             what it calls  [--depth n] [--limit n]
+  hierarchy <name>           supertypes / subtypes / overrides   [--depth n] [--limit n] [--within path]
+  refs <name>                all references to an identifier   [--path p] [--limit n]
+  grep <pattern>             text search with enclosing symbols   [--regex] [--path p] [--limit n]
+  changes [base]             symbols touched by the git diff and their impact
+  impact <name>              what must change with it, who reaches it, which tests to run   [--depth n] [--limit n]
+  unused [path]              dead code   [--kind k] [--lang l] [--limit n] [--no-exported]
+  stats [what] [name]        exact counts: inventory | symbols | subtypes | calls | text | imports | endpoints | database
+                             [--kind k] [--on receiver] [--path p] [--lang l] [--group-by g] [--depth n] [--limit n] [--tests]
+  migrate [--apply]          find (and with --apply remove) what older installs left behind: duplicate
+                             MCP registrations next to the plugin, the v0.1 index file
+  parse <file> [--json]      debug: show what the extractor produces for a file
+  ast <file>                 debug: dump the tree-sitter syntax tree
+
+Query commands refresh the index incrementally first (skip with --no-scan).`;
+
+const CLI_NAMES: Record<string, string> = {
+  clast_search: 'clast-ai search',
+  clast_get_context: 'clast-ai symbol',
+  clast_call_graph: 'clast-ai callers / callees',
+  clast_references: 'clast-ai refs',
+  clast_hierarchy: 'clast-ai hierarchy',
+  clast_file_summary: 'clast-ai outline',
+  clast_overview: 'clast-ai overview',
+  clast_grep: 'clast-ai grep',
+  clast_changes: 'clast-ai changes',
+  clast_stats: 'clast-ai stats',
+  clast_impact: 'clast-ai impact',
+  clast_unused: 'clast-ai unused',
+  clast_reindex: 'clast-ai index',
+  clast_status: 'clast-ai status',
+};
+
+interface Parsed {
+  positional: string[];
+  flags: Map<string, string | true>;
+}
+
+const BOOLEAN_FLAGS = new Set([
+  'force', 'json', 'regex', 'no-body', 'no-scan', 'no-tests', 'tests', 'uncertain', 'help', 'version', 'all', 'no-exported', 'apply', 'auto',
+]);
+
+function parseArgs(argv: string[]): Parsed {
+  const positional: string[] = [];
+  const flags = new Map<string, string | true>();
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq !== -1) flags.set(a.slice(2, eq), a.slice(eq + 1));
+      else if (BOOLEAN_FLAGS.has(a.slice(2)) || i + 1 >= argv.length) flags.set(a.slice(2), true);
+      else flags.set(a.slice(2), argv[++i]!);
+    } else if (a === '-h') flags.set('help', true);
+    else positional.push(a);
+  }
+  return { positional, flags };
+}
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0] && !argv[0].startsWith('-') ? argv[0] : undefined;
+  const { positional, flags } = parseArgs(cmd ? argv.slice(1) : argv);
+  const str = (k: string): string | undefined => {
+    const v = flags.get(k);
+    return typeof v === 'string' ? v : undefined;
+  };
+  const num = (k: string): number | undefined => {
+    const v = str(k);
+    return v !== undefined && /^\d+$/.test(v) ? Number(v) : undefined;
+  };
+
+  if (flags.has('version')) return void console.log(VERSION);
+  if (flags.has('help') || cmd === 'help') return void console.log(HELP);
+
+  if (cmd === undefined || cmd === 'serve') {
+    if (str('root')) process.env.CLAST_PROJECT_DIR = resolve(str('root')!);
+    const { startServer } = await import('./server/index.js');
+    await startServer();
+    return;
+  }
+
+  if (cmd === 'migrate') {
+    const { migrate } = await import('./migrate.js');
+    const out = await migrate({ apply: flags.has('apply'), auto: flags.has('auto'), force: flags.has('force'), cwd: str('root') });
+    if (out) console.log(out);
+    return;
+  }
+
+  if (cmd === 'parse' || cmd === 'ast') {
+    const file = positional[0];
+    if (!file) throw new Error(`usage: clast-ai ${cmd} <file>`);
+    const source = readFileSync(file, 'utf-8');
+    const parser = new SourceParser();
+    if (cmd === 'ast') return void console.log(await parser.dumpTree(file, source));
+    const ex = await parser.extract(file, source);
+    if (!ex) throw new Error('unsupported file type');
+    if (flags.has('json')) return void console.log(JSON.stringify(ex, null, 1));
+    for (const s of ex.symbols) {
+      console.log(
+        `${String(s.startLine).padStart(5)}-${String(s.endLine).padEnd(5)} ${s.kind.padEnd(11)} ${s.qname}` +
+          `${s.exported ? ' [exported]' : ''}\n${' '.repeat(12)}sig: ${s.signature}` +
+          (s.doc ? `\n${' '.repeat(12)}doc: ${s.doc.split('\n')[0]}` : '')
+      );
+    }
+    console.log(`\ncalls (${ex.calls.length}):`);
+    for (const c of ex.calls) {
+      const caller = c.caller >= 0 ? ex.symbols[c.caller]!.qname : '<file>';
+      console.log(`  ${caller} -> ${c.receiver ? c.receiver + '.' : ''}${c.name} @${c.line}${c.count > 1 ? ' x' + c.count : ''}`);
+    }
+    console.log(`\nimports (${ex.imports.length}):`);
+    for (const i of ex.imports) console.log(`  ${i.source} {${i.names.join(', ')}} @${i.line}`);
+    console.log(`\nheritage (${ex.heritage.length}):`);
+    for (const h of ex.heritage) console.log(`  ${ex.symbols[h.symbol]!.qname} ${h.kind} ${h.name}`);
+    console.log(`\nidentifiers: ${ex.occ.length} distinct, parse errors: ${ex.hadError}`);
+    return;
+  }
+
+  const root = resolve(str('root') ?? process.env.CLAST_PROJECT_DIR ?? process.cwd());
+  const clast = new Clast(root);
+  const ctx = new ToolContext(clast);
+  try {
+    if (cmd === 'index') {
+      const target = positional[0];
+      if (target) {
+        // Convenience: `clast-ai index <dir>` indexes another directory.
+        clast.close();
+        const other = new Clast(resolve(target));
+        const octx = new ToolContext(other);
+        console.log(await reindex(octx, { force: flags.has('force') }));
+        other.close();
+        return;
+      }
+      console.log(await reindex(ctx, { force: flags.has('force') }));
+      return;
+    }
+
+    if (!flags.has('no-scan')) await clast.indexer.indexAll();
+    const includeTests = flags.has('no-tests') ? false : flags.has('tests') ? true : undefined;
+    let out: string;
+    switch (cmd) {
+      case 'status':
+        out = await status(ctx);
+        break;
+      case 'overview':
+      case 'map':
+        out = await overview(ctx, { path: positional[0] });
+        break;
+      case 'outline':
+      case 'file':
+        out = await fileSummary(ctx, { path: positional[0] ?? '.', members: flags.has('all') ? 'all' : 'auto' });
+        break;
+      case 'search':
+        out = await search(ctx, {
+          query: positional.join(' '), kind: str('kind'), path: str('path'), lang: str('lang'), limit: num('limit'),
+        });
+        break;
+      case 'symbol':
+      case 'context':
+        out = await getContext(ctx, {
+          name: positional, path: str('path'), maxLines: num('max-lines'), includeBody: !flags.has('no-body'),
+        });
+        break;
+      case 'callers':
+      case 'callees':
+      case 'graph':
+        out = await callGraph(ctx, {
+          name: positional[0] ?? '', path: str('path'),
+          direction: cmd === 'graph' ? 'both' : cmd,
+          depth: num('depth'), limit: num('limit'), includeTests, within: str('within'), uncertain: flags.has('uncertain'),
+        });
+        break;
+      case 'hierarchy':
+      case 'types':
+        out = await hierarchy(ctx, {
+          name: positional[0] ?? '', path: str('path'), depth: num('depth'), limit: num('limit'), within: str('within'),
+          direction: str('direction') as 'supertypes' | 'subtypes' | 'both' | undefined,
+        });
+        break;
+      case 'refs':
+      case 'references':
+        out = await references(ctx, { name: positional[0] ?? '', path: str('path'), limit: num('limit'), includeTests });
+        break;
+      case 'grep':
+        out = await grep(ctx, {
+          pattern: positional.join(' '), regex: flags.has('regex'), path: str('path'), lang: str('lang'),
+          limit: num('limit'), includeTests,
+        });
+        break;
+      case 'changes':
+        out = await changes(ctx, { base: positional[0] });
+        break;
+      case 'impact':
+        out = await impact(ctx, { name: positional.join(' '), path: str('path'), depth: num('depth'), limit: num('limit') });
+        break;
+      case 'unused':
+      case 'dead':
+        out = await unused(ctx, {
+          path: positional[0] ?? str('path'), lang: str('lang'), kind: str('kind'), limit: num('limit'),
+          exported: flags.has('no-exported') ? false : undefined,
+        });
+        break;
+      case 'stats':
+      case 'count': {
+        const WHATS = ['inventory', 'symbols', 'subtypes', 'calls', 'text', 'imports', 'endpoints', 'database'];
+        const hasWhat = WHATS.includes(positional[0] ?? '');
+        out = await stats(ctx, {
+          what: hasWhat ? (positional[0] as StatsArgs['what']) : undefined,
+          name: (hasWhat ? positional.slice(1) : positional).join(' ') || undefined,
+          kind: str('kind'), on: str('on'), path: str('path'), lang: str('lang'),
+          groupBy: str('group-by') as StatsArgs['groupBy'], depth: num('depth'), limit: num('limit'),
+          includeTests: includeTests === true,
+        });
+        break;
+      }
+      default:
+        console.error(`unknown command: ${cmd}\n\n${HELP}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Tool hints name MCP tools; say the same thing in CLI terms here.
+    console.log(
+      out
+        .replace(/clast_[a-z_]+/g, t => CLI_NAMES[t] ?? t)
+        .replace(/\buncertain=true\b/g, '--uncertain')
+        .replace(/\bincludeTests=true\b/g, '--tests')
+        .replace(/\braise maxLines\b/g, 'raise --max-lines')
+    );
+    if (out.startsWith('error:')) process.exitCode = 1;
+  } finally {
+    try { clast.close(); } catch { /* closed above */ }
+  }
+}
+
+main().catch(err => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/src/config/defaults.ts

@@ -1,7 +1,18 @@
 export interface ClastConfig {
+  /** Language ids to index. Empty = all supported languages. */
   languages: string[];
+  /** Directory / file names (or gitignore-style patterns) to skip. */
   ignoredPaths: string[];
+  /** Honour .gitignore files (root and nested). */
+  respectGitignore: boolean;
+  /** Index location, relative to the project root unless absolute. */
   dbPath: string;
+  /** Files larger than this many bytes are skipped (generated / vendored blobs). */
+  maxFileSize: number;
+  /** Safety cap on the number of source files indexed (e.g. when started in a home directory). */
+  maxFiles: number;
+  /** Parser worker threads for bulk indexing. 0 = auto, 1 = no workers. */
+  workers: number;
   llm: {
     endpoint: string;
     model: string;
@@ -13,39 +24,47 @@ export interface ClastConfig {
     debounceMs: number;
     enabled: boolean;
   };
-  maxBodySize: number;
 }
 
+export const DEFAULT_IGNORED = [
+  'node_modules',
+  '.git',
+  '.hg',
+  '.svn',
+  'dist',
+  'build',
+  'out',
+  '__pycache__',
+  '.venv',
+  'venv',
+  '.clast',
+  'vendor',
+  'target',
+  '.next',
+  '.nuxt',
+  'coverage',
+  '.idea',
+  '.vscode-test',
+  '.gradle',
+  '.tox',
+  '.mypy_cache',
+  '.pytest_cache',
+  'bower_components',
+  'Pods',
+  '*.min.js',
+  '*.min.css',
+  '*.bundle.js',
+  '*.d.ts.map',
+];
+
 export const DEFAULT_CONFIG: ClastConfig = {
-  languages: [
-    'typescript',
-    'javascript',
-    'python',
-    'java',
-    'csharp',
-    'go',
-    'rust',
-    'c',
-    'cpp',
-    'ruby',
-    'php',
-  ],
-  ignoredPaths: [
-    'node_modules',
-    '.git',
-    'dist',
-    'build',
-    'out',
-    '__pycache__',
-    '.venv',
-    'venv',
-    '.clast',
-    'vendor',
-    'target',
-    '.next',
-    'coverage',
-  ],
-  dbPath: '.clast/clast.db',
+  languages: [],
+  ignoredPaths: DEFAULT_IGNORED,
+  respectGitignore: true,
+  dbPath: '.clast/index.db',
+  maxFileSize: 1_000_000,
+  maxFiles: 150_000,
+  workers: 0,
   llm: {
     endpoint: 'http://localhost:11434/v1',
     model: '',
@@ -54,8 +73,7 @@ export const DEFAULT_CONFIG: ClastConfig = {
     alwaysGenerate: false,
   },
   watch: {
-    debounceMs: 300,
+    debounceMs: 200,
     enabled: true,
   },
-  maxBodySize: 2000,
 };