purecontext-mcp 1.5.2 → 1.11.0

package/docs/26-troubleshooting.md

@@ -1,234 +1,249 @@
-# Troubleshooting
-
-
----
-
-## Health check
-
-Before investigating any problem, run the health check:
-
-```bash
-purecontext-mcp --health
-```
-
-```json
-{
-  "status": "ok",
-  "version": "1.x.x",
-  "uptime": 0,
-  "nodeVersion": "20.11.0",
-  "platform": "linux",
-  "indexDir": "/home/user/.purecontext/indexes",
-  "repoCount": 3,
-  "grammars": {
-    "tree-sitter-typescript.wasm": true,
-    "tree-sitter-javascript.wasm": true
-  }
-}
-```
-
-In HTTP mode:
-
-```bash
-curl http://localhost:3000/health
-```
-
-A non-zero exit code (CLI) or non-200 response (HTTP) indicates something is wrong.
-
----
-
-## Debug logging
-
-```bash
-purecontext-mcp --log-level debug
-# or
-LOG_LEVEL=debug purecontext-mcp
-```
-
-Debug logs show: file-by-file parsing progress, hash cache hits/misses, worker thread activity, query plan details, rate limit decisions.
-
-**Use in production only temporarily** — debug logs are verbose and may include file paths.
-
----
-
-## Common errors
-
-### "Repo not indexed" / "Index not found"
-
-The repository has not been indexed yet, or the `repoId` belongs to a different installation.
-
-```
-Fix: Call index_folder with the correct path.
-     Use resolve_repo to check if the path is indexed.
-```
-
----
-
-### "Grammar file not found"
-
-A `.wasm` grammar file is missing from the `grammars/` directory.
-
-```bash
-# Check which grammars are present:
-purecontext-mcp config --check
-
-# Fix: reinstall the package
-npm install -g purecontext-mcp
-# or
-npm rebuild purecontext-mcp
-```
-
----
-
-### "better-sqlite3 bindings failed to load"
-
-The native `better-sqlite3` binary doesn't match your Node.js version or platform.
-
-```bash
-# Fix: rebuild the native module
-cd $(npm root -g)/purecontext-mcp
-npm rebuild better-sqlite3
-
-# If that fails, install build tools first:
-# macOS: xcode-select --install
-# Linux: apt install python3 make g++
-# Windows: npm install -g windows-build-tools
-```
-
----
-
-### Missing symbols after indexing
-
-Check this list in order:
-
-1. **Is the file excluded?** Check `excludePatterns` and built-in exclusions (node_modules, dist, .env, etc.)
-2. **Is the file too large?** Files > `maxFileSizeBytes` (default 1 MB) are skipped
-3. **Is it a secret file?** `.pem`, `.key`, `credentials.json` etc. are always excluded
-4. **Is it a private symbol?** Go unexported names, C `static` functions, Java/C# `private` members are excluded by design
-5. **Is the language supported?** Check [Language Support](07-language-support.md)
-6. **Did the adapter detect?** Run `purecontext-mcp config --check` — check "Detected adapters" for your project
-
-Force a specific adapter if auto-detection fails:
-```json
-{ "adapters": ["vue", "nuxt"] }
-```
-
----
-
-### Adapter not activating
-
-Run `purecontext-mcp config --check` and look at the detected adapters. Common detection requirements:
-
-| Framework | Detection file |
-|-----------|---------------|
-| Vue | `vue` in `package.json` dependencies |
-| Nuxt | `nuxt.config.ts` at project root |
-| Django | `manage.py` at project root |
-| Rails | `gem 'rails'` in `Gemfile` |
-| Gin | `github.com/gin-gonic/gin` in `go.mod` |
-| Spring Boot | `spring-boot-starter` in `pom.xml` |
-
----
-
-### Incremental re-index not triggering
-
-The file watcher uses a 2-second debounce. For manual force re-index:
-
-```
-Call index_folder again — it skips unchanged files via content hashing.
-```
-
-If the watcher seems stuck on Linux:
-
-```bash
-# Check inotify limit
-cat /proc/sys/fs/inotify/max_user_watches
-
-# Increase if needed
-echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
-sudo sysctl -p
-```
-
----
-
-### HTTP transport not accessible
-
-1. **Check `http.host`** — default is `127.0.0.1` (loopback only). Set to `0.0.0.0` for network access.
-2. **Check CORS** — `http.corsOrigins` must include the browser's origin.
-3. **Check auth** — if `http.auth.enabled: true`, all requests need `Authorization: Bearer <token>`.
-4. **Check firewall** — port 3000 must be open from the client's perspective.
-
----
-
-### Semantic search not working
-
-1. Verify `semantic.enabled: true` in config
-2. Verify a provider is configured: `semantic.provider` is not `"none"`
-3. Check if the repo meets the threshold: lower `semantic.threshold` for small repos
-4. Verify the API key: test it with a direct API call
-5. Re-index — the HNSW index is built during indexing, not at query time
-
----
-
-### Config validation errors
-
-```bash
-purecontext-mcp config --check
-```
-
-Reports all schema violations with field names and expected types.
-
----
-
-### Rate limit errors (HTTP mode)
-
-`429 Too Many Requests` — the API key has hit its per-second token limit.
-
-Check the `Retry-After` header for when to retry. If limits are too low for your use case, ask the server admin to raise `rateLimit.maxTokens` or `rateLimit.refillRate` for your key.
-
----
-
-### "git not found" when using `index_repo`
-
-```bash
-# Verify git is installed and on PATH
-git --version
-
-# Install if missing:
-# macOS: xcode-select --install
-# Linux: apt install git
-# Windows: https://git-scm.com/download/win
-```
-
----
-
-### Indexing is slow
-
-- First index is always slower — subsequent runs are incremental (hash-based)
-- AI summarization (`allowRemoteAI: true`) adds API latency — disable during testing
-- Semantic indexing adds API latency — disable if not needed
-- For large repos (> 10k files): increase `workerThreads` in config
-
----
-
-## Re-indexing from scratch
-
-```
-Use invalidate_cache tool with your repoId, then call index_folder again.
-```
-
-Or manually:
-
-```bash
-rm ~/.purecontext/indexes/<repoId>.db
-rm -rf ~/.purecontext/indexes/<repoId>/
-```
-
-Then call `index_folder` — a clean full index will be built.
-
----
-
-## Getting more help
-
-- **GitHub Issues:** Report bugs with version, OS, Node.js version, error log, and approximate repo size
-- **`--log-level debug`** output is the most useful information to include in a bug report
+# Troubleshooting
+
+
+---
+
+## Health check
+
+Before investigating any problem, run the health check:
+
+```bash
+purecontext-mcp --health
+```
+
+```json
+{
+  "status": "ok",
+  "version": "1.x.x",
+  "uptime": 0,
+  "nodeVersion": "20.11.0",
+  "platform": "linux",
+  "indexDir": "/home/user/.purecontext/indexes",
+  "repoCount": 3,
+  "grammars": {
+    "tree-sitter-typescript.wasm": true,
+    "tree-sitter-javascript.wasm": true
+  }
+}
+```
+
+In HTTP mode:
+
+```bash
+curl http://localhost:3000/health
+```
+
+A non-zero exit code (CLI) or non-200 response (HTTP) indicates something is wrong.
+
+---
+
+## Debug logging
+
+```bash
+purecontext-mcp --log-level debug
+# or
+LOG_LEVEL=debug purecontext-mcp
+```
+
+Debug logs show: file-by-file parsing progress, hash cache hits/misses, worker thread activity, query plan details, rate limit decisions.
+
+**Use in production only temporarily** — debug logs are verbose and may include file paths.
+
+---
+
+## Common errors
+
+### "Repo not indexed" / "Index not found"
+
+The repository has not been indexed yet, or the `repoId` belongs to a different installation.
+
+```
+Fix: Call index_folder with the correct path.
+     Use resolve_repo to check if the path is indexed.
+```
+
+---
+
+### "Grammar file not found"
+
+A `.wasm` grammar file is missing from the `grammars/` directory.
+
+```bash
+# Check which grammars are present:
+purecontext-mcp config --check
+
+# Fix: reinstall the package
+npm install -g purecontext-mcp
+# or
+npm rebuild purecontext-mcp
+```
+
+---
+
+### "better-sqlite3 bindings failed to load" / native ABI mismatch
+
+The native `better-sqlite3` binary doesn't match your Node.js version or platform — e.g. `NODE_MODULE_VERSION 127 … requires 108` (an ABI mismatch, common under Volta or other per-project Node managers).
+
+**You usually don't need to do anything.** As of 1.10.0, PureContext automatically falls back to a pure-WASM SQLite engine when the native addon can't load, so it keeps working — you'll see `SQLite backend: WASM (@sqlite.org/sqlite-wasm)` in the logs. The fallback is full-featured (FTS5 included), just slower on large indexes.
+
+To restore the faster native engine, rebuild it for your current Node:
+
+```bash
+# Fix: rebuild the native module for the current Node
+cd $(npm root -g)/purecontext-mcp
+npm rebuild better-sqlite3
+
+# If that fails, install build tools first:
+# macOS: xcode-select --install
+# Linux: apt install python3 make g++
+# Windows: npm install -g windows-build-tools
+```
+
+---
+
+### "MCP error -32000: Connection closed" / server won't connect
+
+The MCP host shows this when the server process exits during startup. Two most common causes:
+
+1. **Node < 18.** PureContext requires Node ≥ 18. As of 1.10.0 it prints a clear "requires Node.js >= 18" message and exits, instead of failing opaquely. Run the command directly to see it: `node <…>/dist/bin.js --version`. Fix: upgrade Node (20 or 22 LTS recommended).
+2. **The server inherited the wrong Node** (Volta/nvm picked a project-pinned version). An MCP server is a global tool — pin it to your global Node so it doesn't inherit a project's pin. Re-run `npx purecontext-mcp install claude` and use the printed `claude mcp add … --scope user -- <node> <launcher>` command.
+
+A native ABI mismatch no longer causes this (the WASM fallback handles it), so a remaining `-32000` is almost always cause #1 or #2.
+
+---
+
+### Missing symbols after indexing
+
+Check this list in order:
+
+1. **Is the file excluded?** Check `excludePatterns` and built-in exclusions (node_modules, dist, .env, etc.)
+2. **Is the file too large?** Files > `maxFileSizeBytes` (default 1 MB) are skipped
+3. **Is it a secret file?** `.pem`, `.key`, `credentials.json` etc. are always excluded
+4. **Is it a private symbol?** Go unexported names, C `static` functions, Java/C# `private` members are excluded by design
+5. **Is the language supported?** Check [Language Support](07-language-support.md)
+6. **Did the adapter detect?** Run `purecontext-mcp config --check` — check "Detected adapters" for your project
+
+Force a specific adapter if auto-detection fails:
+```json
+{ "adapters": ["vue", "nuxt"] }
+```
+
+---
+
+### Adapter not activating
+
+Run `purecontext-mcp config --check` and look at the detected adapters. Common detection requirements:
+
+| Framework | Detection file |
+|-----------|---------------|
+| Vue | `vue` in `package.json` dependencies |
+| Nuxt | `nuxt.config.ts` at project root |
+| Django | `manage.py` at project root |
+| Rails | `gem 'rails'` in `Gemfile` |
+| Gin | `github.com/gin-gonic/gin` in `go.mod` |
+| Spring Boot | `spring-boot-starter` in `pom.xml` |
+
+---
+
+### Incremental re-index not triggering
+
+The file watcher uses a 2-second debounce. For manual force re-index:
+
+```
+Call index_folder again — it skips unchanged files via content hashing.
+```
+
+If the watcher seems stuck on Linux:
+
+```bash
+# Check inotify limit
+cat /proc/sys/fs/inotify/max_user_watches
+
+# Increase if needed
+echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
+sudo sysctl -p
+```
+
+---
+
+### HTTP transport not accessible
+
+1. **Check `http.host`** — default is `127.0.0.1` (loopback only). Set to `0.0.0.0` for network access.
+2. **Check CORS** — `http.corsOrigins` must include the browser's origin.
+3. **Check auth** — if `http.auth.enabled: true`, all requests need `Authorization: Bearer <token>`.
+4. **Check firewall** — port 3000 must be open from the client's perspective.
+
+---
+
+### Semantic search not working
+
+1. Verify `semantic.enabled: true` in config
+2. Verify a provider is configured: `semantic.provider` is not `"none"`
+3. Check if the repo meets the threshold: lower `semantic.threshold` for small repos
+4. Verify the API key: test it with a direct API call
+5. Re-index — the HNSW index is built during indexing, not at query time
+
+---
+
+### Config validation errors
+
+```bash
+purecontext-mcp config --check
+```
+
+Reports all schema violations with field names and expected types.
+
+---
+
+### Rate limit errors (HTTP mode)
+
+`429 Too Many Requests` — the API key has hit its per-second token limit.
+
+Check the `Retry-After` header for when to retry. If limits are too low for your use case, ask the server admin to raise `rateLimit.maxTokens` or `rateLimit.refillRate` for your key.
+
+---
+
+### "git not found" when using `index_repo`
+
+```bash
+# Verify git is installed and on PATH
+git --version
+
+# Install if missing:
+# macOS: xcode-select --install
+# Linux: apt install git
+# Windows: https://git-scm.com/download/win
+```
+
+---
+
+### Indexing is slow
+
+- First index is always slower — subsequent runs are incremental (hash-based)
+- AI summarization (`allowRemoteAI: true`) adds API latency — disable during testing
+- Semantic indexing adds API latency — disable if not needed
+- For large repos (> 10k files): increase `workerThreads` in config
+
+---
+
+## Re-indexing from scratch
+
+```
+Use invalidate_cache tool with your repoId, then call index_folder again.
+```
+
+Or manually:
+
+```bash
+rm ~/.purecontext/indexes/<repoId>.db
+rm -rf ~/.purecontext/indexes/<repoId>/
+```
+
+Then call `index_folder` — a clean full index will be built.
+
+---
+
+## Getting more help
+
+- **GitHub Issues:** Report bugs with version, OS, Node.js version, error log, and approximate repo size
+- **`--log-level debug`** output is the most useful information to include in a bug report

package/grammars/README.md

@@ -0,0 +1,88 @@
+# Bundled tree-sitter grammars (`*.wasm`)
+
+PureContext parses source with **`web-tree-sitter` (WASM) on every supported Node
+version** — there is no native parsing path (see `src/core/parse-dispatcher.ts`).
+All language handlers load a precompiled `.wasm` grammar from this directory via
+`grammarPath()`; e.g. `src/handlers/dart.ts` → `tree-sitter-dart.wasm`.
+
+These `.wasm` files are **committed to the repo and shipped in the npm package**
+(`grammars/` is in `package.json` `files`). Because of this, the per-language
+`tree-sitter-*` npm packages are **not** runtime or build dependencies — they are
+only *sources* used to regenerate a `.wasm` when a grammar needs an update.
+
+Keeping them out of `package.json` is deliberate: every `tree-sitter-*` package is
+a native addon that triggers `node-gyp` at install time, which requires platform
+C/C++ build tools (MSVC on Windows, etc.). Listing them as dependencies made
+`npm ci` — in CI and for end users running `npm install purecontext-mcp` — fail on
+any machine without a toolchain. The committed `.wasm` files make installation
+toolchain-free.
+
+> The one genuinely-native dependency is `better-sqlite3`, which ships prebuilt
+> binaries (no `node-gyp`) for Node 18/20/22 and falls back to
+> `@sqlite.org/sqlite-wasm` otherwise. That split is intentional and unrelated to
+> tree-sitter.
+
+## Grammar → source package
+
+| `.wasm` file                  | npm source package           | version  |
+|-------------------------------|------------------------------|----------|
+| `tree-sitter-bash.wasm`       | `tree-sitter-bash`           | ^0.23.3  |
+| `tree-sitter-c.wasm`          | `tree-sitter-c`              | ^0.23.2  |
+| `tree-sitter-cpp.wasm`        | `tree-sitter-cpp`            | ^0.23.4  |
+| `tree-sitter-csharp.wasm`     | `tree-sitter-c-sharp`        | ^0.23.1  |
+| `tree-sitter-dart.wasm`       | `tree-sitter-dart`           | ^1.0.0   |
+| `tree-sitter-elixir.wasm`     | `tree-sitter-elixir`         | ^0.3.5   |
+| `tree-sitter-go.wasm`         | `tree-sitter-go`             | ^0.23.4  |
+| `tree-sitter-haskell.wasm`    | `tree-sitter-haskell`        | ^0.23.1  |
+| `tree-sitter-java.wasm`       | `tree-sitter-java`           | ^0.23.5  |
+| `tree-sitter-javascript.wasm` | `tree-sitter-javascript`     | ^0.25.0  |
+| `tree-sitter-kotlin.wasm`     | `tree-sitter-kotlin`         | ^0.3.8   |
+| `tree-sitter-lua.wasm`        | `tree-sitter-lua`            | ^2.0.0   |
+| `tree-sitter-perl.wasm`       | `tree-sitter-perl`           | ^1.0.0   |
+| `tree-sitter-php.wasm`        | `tree-sitter-php`            | ^0.23.12 |
+| `tree-sitter-python.wasm`     | `tree-sitter-python`         | ^0.23.6  |
+| `tree-sitter-r.wasm`          | `@davisvaughan/tree-sitter-r`| ^1.2.0   |
+| `tree-sitter-ruby.wasm`       | `tree-sitter-ruby`           | ^0.23.1  |
+| `tree-sitter-rust.wasm`       | `tree-sitter-rust`           | ^0.24.0  |
+| `tree-sitter-scala.wasm`      | `tree-sitter-scala`          | ^0.24.0  |
+| `tree-sitter-swift.wasm`      | `tree-sitter-swift`          | ^0.7.1   |
+| `tree-sitter-tsx.wasm`        | `tree-sitter-typescript` (`tsx/` subdir)        | ^0.23.2 |
+| `tree-sitter-typescript.wasm` | `tree-sitter-typescript` (`typescript/` subdir) | ^0.23.2 |
+
+Notes:
+- `tree-sitter-typescript` is a multi-grammar package: it produces **two** `.wasm`
+  files, one from its `typescript/` subdirectory and one from `tsx/`.
+- The `tree-sitter.wasm` runtime core is *not* in this table — it ships inside the
+  `web-tree-sitter` package and is located at runtime (`parse-dispatcher.ts`).
+
+## Regenerating a `.wasm`
+
+You only need this when bumping a grammar version or adding a language. It needs
+[Emscripten](https://emscripten.org/) (`emcc` on `PATH`) or Docker, which the
+`tree-sitter` CLI uses to compile the grammar to WASM.
+
+```bash
+# 1. Install the tree-sitter CLI and the single grammar you are rebuilding.
+#    (Do NOT add these to package.json — install them ad hoc.)
+npm i -g tree-sitter-cli@0.23      # match the CLI to the grammar's ABI
+npm i tree-sitter-dart@1.0.0       # the grammar source you want to rebuild
+
+# 2. Build the grammar to WASM from its package directory.
+#    tree-sitter CLI >= 0.23:
+tree-sitter build --wasm node_modules/tree-sitter-dart
+#    (older CLI used the now-deprecated `tree-sitter build-wasm` form)
+
+# 3. Move the produced tree-sitter-dart.wasm into this directory, overwriting
+#    the committed copy, then commit it.
+mv tree-sitter-dart.wasm grammars/
+
+# 4. For multi-grammar packages, point the CLI at each subdirectory:
+tree-sitter build --wasm node_modules/tree-sitter-typescript/typescript
+tree-sitter build --wasm node_modules/tree-sitter-typescript/tsx
+
+# 5. Sanity-check the new grammar loads and parses:
+npm run build && npm test
+```
+
+After regenerating, uninstall the ad-hoc grammar package so it doesn't leak back
+into `package.json` / the lockfile.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "purecontext-mcp",
-  "version": "1.5.2",
-  "description": "Token-efficient source code navigation MCP server for AI agents",
+  "version": "1.11.0",
+  "description": "Change-aware code intelligence for AI coding agents (MCP): blast radius, temporal co-change, and per-symbol risk before the edit — built on token-efficient code navigation",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -33,7 +33,6 @@
     "scripts/check-sqlite.js",
     "README.md",
     "AGENT_INSTRUCTIONS.md",
-    "AGENT_INSTRUCTIONS_SHORT.md",
     "AGENT_REFERENCE.md",
     "AI-SUMMARIES.md",
     "AST-SEARCH.md",
@@ -69,7 +68,7 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "purecontext-mcp": "./dist/index.js"
+    "purecontext-mcp": "./dist/bin.js"
   },
   "scripts": {
     "build": "npm run build:server && npm run build:ui",
@@ -88,8 +87,12 @@
     "prepublishOnly": "npm run build && npm test",
     "postinstall": "node scripts/check-sqlite.js"
   },
+  "overrides": {
+    "shell-quote": "1.8.4"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@types/js-yaml": "^4.0.9",
     "better-sqlite3": "^11.9.0",
     "chokidar": "^3.6.0",
@@ -97,23 +100,10 @@
     "ignore": "^7.0.5",
     "js-yaml": "^4.1.1",
     "minimatch": "^9.0.9",
-    "tree-sitter-c": "^0.23.2",
-    "tree-sitter-c-sharp": "^0.23.1",
-    "tree-sitter-dart": "^1.0.0",
-    "tree-sitter-go": "^0.23.4",
-    "tree-sitter-haskell": "^0.23.1",
-    "tree-sitter-java": "^0.23.5",
-    "tree-sitter-javascript": "^0.25.0",
-    "tree-sitter-kotlin": "^0.3.8",
-    "tree-sitter-python": "^0.23.6",
-    "tree-sitter-rust": "^0.24.0",
-    "tree-sitter-swift": "^0.7.1",
-    "tree-sitter-typescript": "^0.23.2",
     "web-tree-sitter": "^0.22.6",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@davisvaughan/tree-sitter-r": "^1.2.0",
     "@playwright/test": "^1.59.1",
     "@types/better-sqlite3": "^7.6.8",
     "@types/node": "^20.19.39",
@@ -124,14 +114,6 @@
     "gpt-tokenizer": "^2.9.0",
     "node-gyp": "^11.0.0",
     "prebuildify": "^6.0.1",
-    "tree-sitter-bash": "^0.23.3",
-    "tree-sitter-cpp": "^0.23.4",
-    "tree-sitter-elixir": "^0.3.5",
-    "tree-sitter-lua": "^2.0.0",
-    "tree-sitter-perl": "^1.0.0",
-    "tree-sitter-php": "^0.23.12",
-    "tree-sitter-ruby": "^0.23.1",
-    "tree-sitter-scala": "^0.24.0",
     "tsx": "^4.21.0",
     "typescript": "^5.5.0",
     "vitest": "^1.6.0"