purecontext-mcp 1.2.0 → 1.5.0

package/LANGUAGE-SUPPORT.md

@@ -0,0 +1,144 @@
+# Language Support
+
+PureContext indexes **34 languages** out of the box, plus a small set of regex-based handlers for stylesheets. Every grammar is bundled as a WASM file — no separate install, no native compilation, no language servers to start. When you point it at a polyglot repo, all handlers run in parallel.
+
+This page is the user-facing tour: what's supported, what gets pulled out, and what to expect from each major category. For parameter-level details (every node kind, every signature shape), see the [reference manual](docs/07-language-support.md).
+
+---
+
+## The full list
+
+### Web and application languages
+
+| Language | Extensions | What you get |
+|----------|-----------|-------------|
+| TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` | functions, classes, methods, consts, types, interfaces, enums — full type annotations in signatures |
+| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | functions, classes, methods, exported consts |
+| Python | `.py` | functions, classes, methods, module-level consts — docstrings used as summaries |
+| PHP | `.php` | functions, classes, interfaces, traits, enums, methods, properties, constants — PHP 8 attributes supported |
+| Ruby | `.rb` | functions, classes, methods, modules, constants |
+| Go | `.go` | functions, methods (bare names, no receiver prefix), structs, interfaces, consts, types — unexported names are skipped |
+| Java | `.java` | classes, interfaces, enums, methods (including package-private), inner classes |
+| Kotlin | `.kt`, `.kts` | functions, extension functions, classes, interfaces, objects, enums, typealiases — KDoc summaries |
+| C# | `.cs` | classes, interfaces, enums, structs, records, methods, properties, consts |
+| Scala | `.scala`, `.sc` | classes, traits, objects, case classes, functions, methods, types, enums |
+| Dart | `.dart` | classes, mixins, extensions, enums, functions, methods — `_`-prefixed names are skipped |
+| Swift | `.swift` | classes, structs, protocols, actors, extensions, methods, enums |
+| Elixir | `.ex`, `.exs` | modules, functions, macros, structs, protocols |
+| Haskell | `.hs`, `.lhs` | functions, data types, typeclasses, instances, type aliases, newtypes |
+| Lua | `.lua` | functions, methods, consts |
+| R | `.r`, `.R`, `.Rmd` | functions, consts, S3/S4/R6 classes — Roxygen2 doc comments |
+| Perl | `.pl`, `.pm` | functions, packages |
+| Groovy | `.groovy` | functions, classes, methods |
+| Erlang | `.erl`, `.hrl` | functions, modules |
+| Gleam | `.gleam` | functions, types |
+
+### Systems languages
+
+| Language | Extensions | What you get |
+|----------|-----------|-------------|
+| C | `.c`, `.h` | functions, structs, enums, macros, types — `static` functions skipped (translation-unit internal) |
+| C++ | `.cpp`, `.cxx`, `.cc`, `.hpp`, `.hxx`, `.hh` | All C kinds plus namespaces, templates, template classes with export macros |
+| Rust | `.rs` | functions, methods (bare names), structs, enums, traits, consts, types — `pub` filter for impl methods |
+| Fortran | `.f90`, `.f95`, `.for`, `.f` | functions, subroutines, modules |
+| Objective-C | `.m`, `.h` | functions, classes, methods |
+
+### Scripting and game
+
+| Language | Extensions | What you get |
+|----------|-----------|-------------|
+| Bash | `.sh`, `.bash` | functions |
+| GDScript | `.gd` | functions, classes, signals |
+
+### Infrastructure and config
+
+| Language | Extensions | What you get |
+|----------|-----------|-------------|
+| Terraform / HCL | `.tf`, `.hcl` | resources, modules, variables, outputs |
+| Nix | `.nix` | functions, attributes |
+
+### Data and API
+
+| Language | Extensions | What you get |
+|----------|-----------|-------------|
+| SQL | `.sql` | tables, views, functions, procedures |
+| Protobuf | `.proto` | messages, services, enums, RPCs |
+| GraphQL | `.graphql`, `.gql` | types, queries, mutations, subscriptions, fragments |
+| OpenAPI / YAML | `.yaml`, `.yml` | endpoints, schemas (OpenAPI detected by content) |
+| XML | `.xml` | elements (configurable patterns — opt-in) |
+
+### Stylesheets (regex-based, no WASM grammar)
+
+CSS-family languages don't have a stable tree-sitter grammar, so PureContext extracts a focused subset using regex. Only named, reusable constructs are indexed — plain selectors are skipped because they would flood the index with noise.
+
+| Language | Extensions | What you get |
+|----------|-----------|-------------|
+| SCSS / SASS | `.scss`, `.sass` | `@mixin`, `@function`, top-level `$variables`, `%placeholders`, `@keyframes` |
+| LESS | `.less` | `.mixin(@params)`, top-level `@variables`, `@keyframes` |
+| CSS | `.css` | `--custom-properties` (opt-in via `indexing.cssVariables: true`) |
+
+---
+
+## What gets indexed for every language
+
+Regardless of language, every symbol you find through `search_symbols` carries:
+
+- **Name** — the identifier as it appears in source
+- **Kind** — function, class, method, route, component, etc.
+- **Byte offsets** — `startByte` / `endByte` for precise source retrieval; no need to re-read the whole file to grab a function body
+- **Signature** — a one-line declaration with the full type information available in that language
+- **Summary** — sourced from the docstring/JSDoc/Javadoc/Roxygen comment if present, otherwise inferred from framework context (route path, ORM table, etc.), otherwise a one-line AI summary, otherwise the signature itself
+- **Import / dependency edges** — used by the dependency graph, blast radius, and cycle detection tools
+
+The summary chain (docstring → framework inference → AI → signature fallback) is what makes search across an undocumented codebase still work. See [AI Summaries](AI-SUMMARIES.md) for how to enable LLM summaries on legacy projects.
+
+---
+
+## What is filtered out automatically
+
+Some things you don't want in the index — they bloat it and pollute search results. PureContext excludes:
+
+- Standard build and dependency directories: `node_modules/`, `.git/`, `dist/`, `build/`, `target/`, `.next/`, `.nuxt/`, `.claude/`
+- Lock files (`*.lock`) and environment files (`.env*`)
+- Binary files (detected by null-byte scanning of the first 8 KB — works without a hardcoded extension list)
+- Files larger than 1 MB (raise the limit with `maxFileSizeBytes` in config)
+- Secret files: `*.pem`, `*.key`, `id_rsa`, `credentials.json`, `serviceAccountKey*.json`
+
+It also respects language-level visibility:
+
+- **Go**: unexported names (lowercase first letter)
+- **C**: `static` functions (translation-unit internal)
+- **Java / C# / PHP**: `private` members
+- **Dart**: `_`-prefixed names
+
+Public API tools (`get_public_api`) rely on these rules being applied consistently — they assume the index already reflects what is externally visible.
+
+---
+
+## Known limitations
+
+- **TypeScript `.tsx`** uses a separate `tree-sitter-tsx` grammar from `.ts`. Both are bundled.
+- **Python stubs** (`.pyi`) are not indexed — only `.py` files.
+- **Terraform** `dynamic` blocks with complex expressions may not be fully extracted.
+- **XML** element extraction uses configurable patterns rather than indexing every tag — turn it on per project if you need it.
+- **CSS** custom properties (`--foo`) are off by default; enable with `indexing.cssVariables: true` when you have a design system worth indexing.
+
+---
+
+## Adding a new language
+
+If a grammar you care about is missing, the path to support is straightforward:
+
+1. Add a new file in `src/handlers/`, implementing `LanguageHandler`
+2. Bundle the `.wasm` grammar in `grammars/`
+3. Register the handler in the language dispatcher
+4. Add tests against fixture files in `test/handlers/`
+
+Regex-only handlers (like SCSS) skip step 2 entirely — they return `null` from `grammarPath()`.
+
+See `docs/25-architecture-overview.md` for the three-layer design (Core → Handlers → Adapters) and the conventions every handler follows.
+
+---
+
+→ Full parameter-level reference: [docs/07-language-support.md](docs/07-language-support.md)
+→ Adapter layer that adds framework-specific symbols on top: [FRAMEWORK-ADAPTERS.md](FRAMEWORK-ADAPTERS.md)

package/README.md

@@ -18,8 +18,12 @@ But token savings are the mechanism, not the point. The point is that AI gets be
 ## Quick start
 
 ```bash
-# Connect to Claude Code (no global install needed)
+# 1. Connect to Claude Code (no global install needed)
 claude mcp add purecontext-mcp -- npx purecontext-mcp
+
+# 2. Inside your project, install the workflow rules
+#    (auto-detects Claude / Cursor / Windsurf / Continue / Cline / Roo Code / VS Code / Claude Desktop)
+npx purecontext-mcp install all
 ```
 
 Then in a Claude Code conversation:
@@ -54,6 +58,8 @@ The guide explains what PureContext does, why each feature exists, and how to us
 | [Visualizing Code Structure](VISUALIZING-CODE.md) | Mermaid/DOT diagrams, architecture snapshots |
 | [AST-Level Search](AST-SEARCH.md) | Node types, signatures, decorators, complexity |
 | [Code Intelligence](CODE-INTELLIGENCE.md) | Entry points, public API, TODOs, coverage |
+| [Language Support](LANGUAGE-SUPPORT.md) | All 34 supported languages and what's extracted |
+| [Framework Adapters](FRAMEWORK-ADAPTERS.md) | Vue, React, Django, Spring, Rails, Flutter, ORMs, and more |
 | [Using PureContext with a Team](TEAM-SETUP.md) | Shared server, enterprise setup |
 
 **Real-world workflows:**
@@ -77,9 +83,39 @@ You should start from docs/README.md.
 
 ## What it indexes
 
-**34 languages** including TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, Kotlin, Swift, Dart, C, C++, Elixir, Haskell, Scala, R, Bash, Terraform, Protobuf, GraphQL, SQL, and more.
+### Languages
+
+**34 languages** via bundled tree-sitter WASM grammars — no separate install required.
+
+| Category | Languages |
+|----------|-----------|
+| Web / Application | TypeScript, JavaScript, Python, PHP, Ruby, Go, Java, Kotlin, C#, Scala, Dart, Swift, Elixir, Haskell, Lua, R, Perl, Groovy, Erlang, Gleam |
+| Systems | C, C++, Rust, Fortran, Objective-C |
+| Scripting & Game | Bash, GDScript |
+| Infrastructure & Config | Terraform / HCL, Nix |
+| Data & API | SQL, Protobuf, GraphQL, OpenAPI / YAML, XML |
+| Styling (regex-based) | SCSS, SASS, LESS, CSS |
+
+→ [Language Support guide](LANGUAGE-SUPPORT.md) · [Full reference](docs/07-language-support.md)
+
+### Frameworks
+
+**Framework-aware extraction** — routes, components, hooks, models, ORM entities, and middleware are pulled out as first-class symbols (not just functions and classes).
+
+| Stack | Frameworks |
+|-------|-----------|
+| JavaScript / TypeScript | Vue 3, React, Nuxt, Next.js (Pages + App Router), Angular, NestJS, Express, Fastify |
+| Python | Django, FastAPI, Flask |
+| Go | Gin, Echo, Fiber |
+| PHP | Laravel, Symfony |
+| Ruby | Rails, Sinatra |
+| Java | Spring Boot, Micronaut, Quarkus |
+| Kotlin | Ktor, Spring (Kotlin) |
+| Rust | Axum, Actix-web, Rocket |
+| Mobile | Flutter |
+| ORMs | Hibernate, SQLAlchemy, Django ORM, Prisma, TypeORM |
 
-**Framework-aware extraction** for Vue, React, Nuxt, Next.js, Angular, NestJS, Express, Fastify, Django, FastAPI, Flask, Gin, Rails, Laravel, Spring Boot, and more. Routes, components, hooks, models, and middleware are extracted as first-class symbols.
+→ [Framework Adapters guide](FRAMEWORK-ADAPTERS.md) · [Full reference](docs/08-framework-adapters.md)
 
 ---
 
@@ -180,22 +216,66 @@ If your team runs a shared PureContext server, connect with an HTTP transport in
 
 Installing PureContext gives your agent the tools. Adding the agent instructions tells it *how* to use them — which tool to pick for each task, in what order, and what to avoid.
 
-Two instruction files are provided at the repository root:
+Without these instructions, an agent may default to reading entire files rather than using `search_symbols`, or may not know to call `list_repos` first to get the repository ID required by every tool.
+
+### One-command install (recommended)
 
-**`AGENT_INSTRUCTIONS_SHORT.md`** — ~2 KB. The mandatory workflow, tool selection table, core rules, and common patterns. Use this for agents with limited system prompt space.
+Run this once inside your project directory:
 
-**`AGENT_INSTRUCTIONS.md`** — ~15 KB. Adds detailed parameter notes, every usage pattern, decision trees, and anti-patterns. Use this for complex multi-step workflows.
+```bash
+npx purecontext-mcp install all
+```
 
-**Claude Code** — add to your project's `CLAUDE.md`:
+This auto-detects which AI coding tools you have set up in the project and writes the PureContext workflow rules to the right place for each. Re-running is safe — every writer is idempotent (managed blocks are marked and replaced rather than appended).
+
+When no `--scope` flag is given, the CLI prompts you to choose where to install:
+
+```
+Where should PureContext be installed?
+  1) Local  — this project only
+  2) Global — all projects (user-level config)
+  3) Both
+```
+
+Pass `--scope` to skip the prompt:
 
 ```bash
-cat AGENT_INSTRUCTIONS_SHORT.md >> CLAUDE.md
+npx purecontext-mcp install all --scope=local    # this project only
+npx purecontext-mcp install all --scope=global   # user-level, all projects
+npx purecontext-mcp install all --scope=both     # both places at once
 ```
 
-**Cursor** — paste into `.cursorrules` or via Cursor Settings → Rules.
+For a single tool:
 
-**Windsurf** — paste into your workspace memory or rules configuration.
+```bash
+npx purecontext-mcp install <tool> --scope=global
+```
 
-**Any other agent** — paste into whatever system prompt or memory configuration it supports.
+To preview without writing files:
 
-Without these instructions, an agent may default to reading entire files rather than using `search_symbols`, or may not know to call `list_repos` first to get the repository ID required by every tool.
+```bash
+npx purecontext-mcp install all --dry-run
+npx purecontext-mcp install --list      # show which IDEs were detected
+```
+
+Supported tools and where each one writes:
+
+| Tool | Local | Global |
+|------|-------|--------|
+| `claude` | `CLAUDE.md` in project | `~/.claude/CLAUDE.md` + hooks |
+| `cursor` | `.cursor/rules/purecontext.mdc` | `~/.cursor/rules/purecontext.mdc` |
+| `windsurf` | `.windsurfrules` | `~/.windsurfrules` |
+| `continue` | `.continue/config.json` | `~/.continue/config.json` |
+| `cline` | `.clinerules` | local only |
+| `roo-code` | `.roo/rules-code.md` | local only |
+| `vscode` | `.github/copilot-instructions.md` | local only |
+| `claude-desktop` | always global | always global |
+
+### Manual install
+
+If you'd rather paste the rules yourself, two instruction files are at the repository root:
+
+- **`AGENT_INSTRUCTIONS_SHORT.md`** — ~2 KB. Mandatory workflow, tool selection table, core rules.
+- **`AGENT_INSTRUCTIONS.md`** — ~15 KB. Adds parameter notes, decision trees, anti-patterns.
+
+Paste the contents into whatever system prompt, memory, or rules configuration your agent uses.

package/USER-GUIDE.md

@@ -46,6 +46,14 @@ For parameter-level documentation — every tool input, output, and flag — see
 
 ---
 
+## Language and framework coverage
+
+- [Language Support](LANGUAGE-SUPPORT.md) — All 34 supported languages plus regex-based stylesheet handlers: what's extracted, what's filtered, and known limitations
+
+- [Framework Adapters](FRAMEWORK-ADAPTERS.md) — Routes, components, and ORM entities pulled out as first-class symbols for Vue, React, Nuxt, Next.js, Angular, NestJS, Django, FastAPI, Flask, Spring Boot, Rails, Laravel, Flutter, and more
+
+---
+
 ## For teams and enterprise
 
 - [Using PureContext with a Team](team-setup.md) — Why a shared server is fundamentally different from local use, how to set it up, how to keep the index current automatically, and what enterprise deployments need to consider

package/dist/cli/hooks.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `purecontext-mcp hooks --install` / `hooks --list`
+ * `purecontext-mcp hook-pretooluse|hook-posttooluse|hook-precompact|hook-worktree-create|hook-worktree-remove`
+ *
+ * Merges hook entries into ~/.claude/settings.json using CLI-style commands
+ * (npx purecontext-mcp hook-*) so no scripts need to be copied to ~/.claude/hooks/.
+ * Also injects PureContext agent instructions into ~/.claude/CLAUDE.md.
+ */
+export declare function cmdHooksInstall(): void;
+export declare function cmdHooksList(): void;
+export declare function mergeSettings(): void;
+export declare function injectClaudeMd(): void;
+/** PreToolUse: warn before Edit/Write/MultiEdit. */
+export declare function cmdHookPreToolUse(): Promise<void>;
+/** PostToolUse: re-index the repo after Edit/Write/MultiEdit. */
+export declare function cmdHookPostToolUse(): Promise<void>;
+/** PreCompact: inject session snapshot before context compaction. */
+export declare function cmdHookPreCompact(): Promise<void>;
+/** WorktreeCreate: auto-index a new agent worktree. */
+export declare function cmdHookWorktreeCreate(): Promise<void>;
+/** WorktreeRemove: fires when an agent worktree is removed. No-op for now. */
+export declare function cmdHookWorktreeRemove(): Promise<void>;
+/** TaskCompleted: surface post-task diagnostics and remind about available tools. */
+export declare function cmdHookTaskCompleted(): Promise<void>;
+/** SubagentStart: inject condensed repo orientation for spawned subagents. */
+export declare function cmdHookSubagentStart(): Promise<void>;
+export declare function runHooksCommand(args: string[]): void;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/cli/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/cli/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0IH,wBAAgB,eAAe,IAAI,IAAI,CAetC;AAED,wBAAgB,YAAY,IAAI,IAAI,CAenC;AAID,wBAAgB,aAAa,IAAI,IAAI,CAoDpC;AA6BD,wBAAgB,cAAc,IAAI,IAAI,CAuBrC;AAuCD,oDAAoD;AACpD,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAoBvD;AAED,iEAAiE;AACjE,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CA8BxD;AA6DD,qEAAqE;AACrE,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAgBvD;AAED,uDAAuD;AACvD,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB3D;AAED,8EAA8E;AAC9E,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAG3D;AAyED,qFAAqF;AACrF,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAwC1D;AAED,8EAA8E;AAC9E,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CA8C1D;AAID,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAUpD"}