purecontext-mcp 1.1.1 → 1.1.2

package/docs/dev/PHASE22_TASKS.md

@@ -1,371 +0,0 @@
-# Phase 22 — Language Coverage Expansion
-
-**Goal**: Close the language coverage gap with jCodeMunch by adding 14 languages across scripting, infrastructure, schema, and specialized domains — bringing PureContext from 20 to 34 language handlers.
-
-**Scope rationale**: Language coverage is the most mechanical of the parity gaps — each handler is a self-contained module with the same structure. Grouping by domain (scripting, infrastructure, schema, specialized) allows parallel implementation and focused testing. Priority is given to languages with the highest prevalence in real-world projects.
-
-**Priority order** (highest to lowest real-world prevalence):
-1. Bash/Shell — ubiquitous in CI, DevOps, automation
-2. SQL (done in Phase 21, Task 143)
-3. Protocol Buffers — gRPC, microservices
-4. HCL/Terraform — infrastructure as code
-5. GraphQL — API schemas, widely adopted
-6. Groovy — Gradle build files, Jenkins pipelines
-7. Nix — NixOS, Nix flakes
-8. Perl — legacy systems, bioinformatics
-9. Erlang — telco, distributed systems
-10. GDScript — Godot game engine
-11. Gleam — emerging functional language
-12. XML/XUL — config files, legacy web
-13. Objective-C — iOS/macOS legacy
-14. Fortran — scientific computing
-
----
-
-## Task 144: Scripting Languages — Bash and Perl
-
-**Current state**: Shell scripts (`.sh`, `.bash`) and Perl files (`.pl`, `.pm`) are not indexed. Bash is near-universal in CI pipelines and DevOps tooling.
-
-**Deliverables**:
-
-- `src/handlers/bash.ts`:
-  - Extensions: `.sh`, `.bash`, `.zsh`, `.fish`
-  - Grammar: `grammars/tree-sitter-bash.wasm`
-  - Symbols extracted:
-    - Function definitions: `function name()` and `name()` → `kind: 'function'`
-    - Variable declarations at file scope: `readonly VAR=...`, `declare -g VAR=...` → `kind: 'const'`
-  - Signature: `function name([params_from_comment])`
-  - Summary: preceding comment block (lines starting with `#`)
-  - Imports: `source ./file.sh` and `. ./file.sh` → `ImportRecord`
-
-- `src/handlers/perl.ts`:
-  - Extensions: `.pl`, `.pm`, `.t`
-  - Grammar: `grammars/tree-sitter-perl.wasm`
-  - Symbols extracted:
-    - `sub name { ... }` → `kind: 'function'`
-    - `my $var = ...` at file scope → `kind: 'const'` (top-level only)
-    - `package Name;` → `kind: 'class'` (one per file)
-  - Signature: `sub name(signature)` — use prototype comment if present `# sub name(Str $a, Int $b)`
-  - Summary: POD documentation block above sub (`=head2 name` ... `=cut`)
-  - Imports: `use Module::Name` and `require 'file.pl'` → `ImportRecord`
-
-**Key technical notes**:
-- Bash grammar WASM: `tree-sitter-bash` is well-maintained and stable
-- Perl grammar WASM: `tree-sitter-perl` exists; verify WASM compilation is available
-- Bash functions without `function` keyword: `name() { ... }` — ensure both forms are extracted
-- Fish shell syntax differs significantly from bash — handle gracefully (extract functions, skip if grammar unavailable)
-
-**Tests**: `test/handlers/bash.test.ts`, `test/handlers/perl.test.ts`
-- Function extraction (both syntax forms for Bash)
-- Source import extraction
-- Comment-based summary extraction
-- Perl package as class symbol
-- POD docstring extraction
-
-**Verify**:
-```bash
-# index_folder on a repo with .sh and .pl files
-# get_file_outline { filePath: "scripts/deploy.sh" }
-```
-
----
-
-## Task 145: Infrastructure Languages — HCL/Terraform and Nix
-
-**Current state**: Infrastructure-as-code files (`.tf`, `.hcl`) and Nix files (`.nix`) are not indexed. Terraform is the dominant IaC tool; Nix is growing rapidly.
-
-**Deliverables**:
-
-- `src/handlers/terraform.ts`:
-  - Extensions: `.tf`, `.hcl`
-  - Grammar: `grammars/tree-sitter-hcl.wasm`
-  - Symbols extracted:
-    - `resource "type" "name"` → `kind: 'class'`, name: `type.name`
-    - `data "type" "name"` → `kind: 'const'`, name: `data.type.name`
-    - `variable "name"` → `kind: 'const'`, name: `var.name`
-    - `output "name"` → `kind: 'const'`, name: `output.name`
-    - `module "name"` → `kind: 'function'`, name: `module.name`
-    - `locals { key = ... }` → individual `kind: 'const'` per key
-  - Signature: `resource "aws_s3_bucket" "main"` (block header)
-  - Summary: inline comment above the block or `description` attribute if present
-  - Imports: `module` source attributes → `ImportRecord` (local modules only; remote sources stored as external)
-
-- `src/handlers/nix.ts`:
-  - Extensions: `.nix`
-  - Grammar: `grammars/tree-sitter-nix.wasm`
-  - Symbols extracted:
-    - Top-level `name = ...` attribute bindings → `kind: 'const'`
-    - `{ ... }: { ... }` function definitions assigned to top-level attrs → `kind: 'function'`
-    - `stdenv.mkDerivation { name = "..."; }` → `kind: 'class'` with derivation name
-  - Summary: preceding `# comment` line
-  - Imports: `import ./file.nix` and `import <nixpkgs>` → `ImportRecord`
-
-**Key technical notes**:
-- HCL grammar: `tree-sitter-hcl` is the canonical grammar. Verify WASM availability
-- Terraform `.tfvars` files: skip (no meaningful symbols beyond variable values)
-- Nix is functional — most "symbols" are attribute bindings. Focus on top-level bindings only
-- Nix flake `outputs` function: special-case to emit symbols for `packages`, `devShells`, `nixosConfigurations` attributes
-
-**Tests**: `test/handlers/terraform.test.ts`, `test/handlers/nix.test.ts`
-- Resource, data, variable, output, module blocks extracted
-- `description` attribute used as summary
-- Local module imports as ImportRecord
-- Nix derivation extracted as class symbol
-- Top-level attribute bindings extracted
-
-**Verify**:
-```bash
-# index_folder on a Terraform project
-# search_symbols { query: "aws_s3_bucket" }
-```
-
----
-
-## Task 146: Schema Languages — Protocol Buffers and GraphQL
-
-**Current state**: `.proto` and `.graphql` files are not indexed. Both are critical for microservices (gRPC) and API-first development.
-
-**Deliverables**:
-
-- `src/handlers/protobuf.ts`:
-  - Extensions: `.proto`
-  - Grammar: `grammars/tree-sitter-proto.wasm`
-  - Symbols extracted:
-    - `message Name { ... }` → `kind: 'class'`
-    - `service Name { ... }` → `kind: 'interface'`
-    - `rpc MethodName(Request) returns (Response)` → `kind: 'method'` (child of service)
-    - `enum Name { ... }` → `kind: 'enum'`
-    - `extend Message { ... }` → `kind: 'class'`
-  - Signature: `message Name` / `rpc MethodName(InputType) returns (OutputType)`
-  - Summary: preceding `//` comment or block comment
-  - Imports: `import "other.proto"` → `ImportRecord`
-
-- `src/handlers/graphql.ts`:
-  - Extensions: `.graphql`, `.gql`
-  - Grammar: `grammars/tree-sitter-graphql.wasm`
-  - Symbols extracted:
-    - `type Name { ... }` → `kind: 'class'`
-    - `interface Name { ... }` → `kind: 'interface'`
-    - `enum Name { ... }` → `kind: 'enum'`
-    - `input Name { ... }` → `kind: 'class'`
-    - `scalar Name` → `kind: 'type'`
-    - `directive @name` → `kind: 'decorator'`
-    - `query/mutation/subscription name` → `kind: 'function'`
-    - `fragment name on Type` → `kind: 'const'`
-  - Signature: `type Name implements Interface`
-  - Summary: preceding `"""description"""` or `# comment`
-  - Imports: none (GraphQL has no native imports; schema stitching is app-level)
-
-**Key technical notes**:
-- `tree-sitter-proto`: well-maintained; supports proto2 and proto3
-- `tree-sitter-graphql`: stable; handles SDL and executable documents
-- Proto `nested messages`: extract top-level only; nested types can be listed in `frameworkMeta`
-- GraphQL schema files vs operation files: detect from presence of type definitions vs queries — emit appropriate symbol kinds
-
-**Tests**: `test/handlers/protobuf.test.ts`, `test/handlers/graphql.test.ts`
-- Message, service, rpc, enum extraction
-- Proto import as ImportRecord
-- GraphQL type, interface, enum, query extraction
-- Docstring/comment summary extraction
-
-**Verify**:
-```bash
-# index_folder on a gRPC service or GraphQL API project
-# search_symbols { query: "UserService" }
-```
-
----
-
-## Task 147: Specialized Languages — Groovy and Erlang
-
-**Current state**: Groovy (`.groovy`, Gradle `.gradle`) and Erlang (`.erl`, `.hrl`) are not indexed.
-
-**Deliverables**:
-
-- `src/handlers/groovy.ts`:
-  - Extensions: `.groovy`, `.gradle`, `.gradle.kts` (Kotlin Gradle handled by existing Kotlin handler)
-  - Grammar: `grammars/tree-sitter-groovy.wasm`
-  - Symbols extracted:
-    - `class Name { ... }` → `kind: 'class'`
-    - `def methodName(...)` → `kind: 'method'` or `kind: 'function'`
-    - `task taskName { ... }` (Gradle DSL) → `kind: 'function'`
-    - `def VAR = ...` at file/class scope → `kind: 'const'`
-  - Summary: preceding `/** */` Groovydoc block
-  - Imports: `import com.example.Class` → `ImportRecord`
-
-- `src/handlers/erlang.ts`:
-  - Extensions: `.erl`, `.hrl`
-  - Grammar: `grammars/tree-sitter-erlang.wasm`
-  - Symbols extracted:
-    - `function_name(Args) -> ...` → `kind: 'function'`, name: `module:function_name/arity`
-    - `-module(name)` → `kind: 'class'` (one per file)
-    - `-record(name, {...})` → `kind: 'class'`
-    - `-type name() :: ...` → `kind: 'type'`
-    - `-spec function_name(Types) -> Type` → used as signature for the function
-  - Summary: preceding `%% @doc` EDoc comment
-  - Imports: `-import(module, [fun/arity, ...])` → `ImportRecord`
-
-**Key technical notes**:
-- Groovy: the same grammar handles both Groovy scripts and Gradle build files. Gradle DSL keywords (`task`, `plugins`, `dependencies`) should be treated as function symbols
-- Erlang function arity: Erlang has multiple clauses per function — emit one symbol per unique `name/arity` combination, using the first clause's position
-- Erlang OTP behaviours (`-behaviour(gen_server)`) → add to `frameworkMeta`
-
-**Tests**: `test/handlers/groovy.test.ts`, `test/handlers/erlang.test.ts`
-- Class and method extraction
-- Gradle task extraction
-- Groovydoc summary
-- Erlang function with arity in name
-- `-spec` used as signature
-- EDoc comment as summary
-
----
-
-## Task 148: Emerging and Specialized Languages — Gleam, GDScript, XML
-
-**Current state**: Gleam (`.gleam`), GDScript (`.gd`), and XML/XUL (`.xml`, `.xul`) are not indexed.
-
-**Deliverables**:
-
-- `src/handlers/gleam.ts`:
-  - Extensions: `.gleam`
-  - Grammar: `grammars/tree-sitter-gleam.wasm`
-  - Symbols extracted:
-    - `pub fn name(args) -> ReturnType { ... }` → `kind: 'function'`
-    - `fn name(...)` (private) → `kind: 'function'`
-    - `pub type Name { ... }` → `kind: 'class'`
-    - `pub type Name = ...` (type alias) → `kind: 'type'`
-    - `pub const NAME = ...` → `kind: 'const'`
-  - Signature: full type-annotated signature
-  - Summary: preceding `///` doc comment
-  - Imports: `import package/module.{Symbol}` → `ImportRecord`
-
-- `src/handlers/gdscript.ts`:
-  - Extensions: `.gd`
-  - Grammar: `grammars/tree-sitter-gdscript.wasm`
-  - Symbols extracted:
-    - `func name(args) -> ReturnType:` → `kind: 'function'`
-    - `class Name:` (inner classes) → `kind: 'class'`
-    - `var name: Type = value` (class-level) → `kind: 'const'`
-    - `signal name(args)` → `kind: 'function'`
-    - `@export var name` → `kind: 'const'` (with `export: true` in `frameworkMeta`)
-  - Summary: preceding `##` doc comment (GDScript convention)
-  - Imports: `extends ClassName` → `ImportRecord` (class inheritance)
-
-- `src/handlers/xml.ts`:
-  - Extensions: `.xml`, `.xul`, `.svg`, `.plist` (opt-in via config)
-  - Grammar: `grammars/tree-sitter-xml.wasm`
-  - Symbols extracted:
-    - Root element → `kind: 'class'`, name: root tag name
-    - Elements with `id` attribute → `kind: 'const'`, name: `id` value
-    - `<script src="...">` references → `ImportRecord`
-    - XUL: `<command id="...">`, `<keyset>`, `<menuitem id="...">` → `kind: 'const'`
-  - Summary: nearest preceding XML comment `<!-- description -->`
-  - Note: XML indexing is shallow by design — only id-attributed elements and the root
-
-**Key technical notes**:
-- Gleam: `tree-sitter-gleam` is official and well-maintained
-- GDScript: `tree-sitter-godot-resource` or `tree-sitter-gdscript` — verify WASM availability
-- XML: configure an opt-in allowlist (`xmlExtensions` in config) — XML is too broad to index by default
-- SVG files: skip by default (they're images, not code); add `.svg` to `SKIP_EXTENSIONS` unless opted in
-
-**Tests**: `test/handlers/gleam.test.ts`, `test/handlers/gdscript.test.ts`, `test/handlers/xml.test.ts`
-- Function, type, const extraction per handler
-- Import extraction
-- Doc comment summary
-
----
-
-## Task 149: Legacy and Scientific Languages — Objective-C and Fortran
-
-**Current state**: Objective-C (`.m`, `.h`) and Fortran (`.f90`, `.f95`, `.for`) are not indexed.
-
-**Deliverables**:
-
-- `src/handlers/objective-c.ts`:
-  - Extensions: `.m`, `.mm` (Objective-C and Objective-C++)
-  - Grammar: reuse the existing C handler's grammar (`tree-sitter-c.wasm`) — Objective-C is a superset. Add Objective-C-specific node types
-  - OR use `tree-sitter-objc.wasm` if available
-  - Symbols extracted:
-    - `@interface Name : SuperClass` → `kind: 'class'`
-    - `@implementation Name` → merge with corresponding interface if exists
-    - `- (ReturnType)methodName:(Type)arg` → `kind: 'method'`
-    - `+ (ReturnType)classMethod` → `kind: 'method'` (with `isClassMethod: true` in frameworkMeta)
-    - `@property (attrs) Type name` → `kind: 'const'`
-    - `@protocol Name` → `kind: 'interface'`
-  - Signature: full Objective-C method signature including types
-  - Summary: preceding `/** */` or `///` comment
-  - Imports: `#import "File.h"` and `#import <Framework/Header.h>` → `ImportRecord`
-
-- `src/handlers/fortran.ts`:
-  - Extensions: `.f90`, `.f95`, `.f03`, `.f08`, `.for`, `.f`
-  - Grammar: `grammars/tree-sitter-fortran.wasm`
-  - Symbols extracted:
-    - `SUBROUTINE name(args)` → `kind: 'function'`
-    - `FUNCTION name(args) RESULT(res)` → `kind: 'function'`
-    - `MODULE name` → `kind: 'class'`
-    - `TYPE :: name` → `kind: 'type'`
-    - `INTERFACE name` → `kind: 'interface'`
-  - Signature: full declaration with argument types
-  - Summary: preceding `!>` or `!!` Ford-style docstring
-  - Imports: `USE module_name` → `ImportRecord`
-
-**Key technical notes**:
-- Objective-C `.h` header files: index interface declarations; `.m` implementation files may duplicate — prefer the interface signature for display but link both
-- Fortran is case-insensitive — normalize all symbol names to lowercase for consistent search
-- Fortran `CONTAINS` sections: index subroutines inside `CONTAINS` as methods of the parent module/program
-
-**Tests**: `test/handlers/objective-c.test.ts`, `test/handlers/fortran.test.ts`
-- Interface and implementation extraction
-- Instance vs class method distinction
-- Property extraction
-- Fortran subroutine, function, module extraction
-- Case-insensitive name normalization
-
----
-
-## Order of Execution
-
-All tasks in this phase are independent and can be parallelized:
-
-```
-144 (Bash, Perl)           ── high priority (common in CI/DevOps)
-145 (Terraform, Nix)       ── high priority (IaC is widespread)
-146 (Protobuf, GraphQL)    ── high priority (microservices)
-147 (Groovy, Erlang)       ── medium priority
-148 (Gleam, GDScript, XML) ── medium priority
-149 (Objective-C, Fortran) ── lower priority (legacy/specialized)
-```
-
-Each task is self-contained. Grammars should be downloaded and bundled before implementation begins.
-
----
-
-## Grammar Acquisition Checklist
-
-Before starting implementation, verify WASM grammar availability for each language:
-
-| Language | npm package | WASM available | Notes |
-|----------|------------|----------------|-------|
-| Bash | `tree-sitter-bash` | ✓ | Well-maintained |
-| Perl | `tree-sitter-perl` | Verify | May need compilation |
-| HCL/Terraform | `tree-sitter-hcl` | ✓ | Official HashiCorp grammar |
-| Nix | `tree-sitter-nix` | ✓ | Active maintenance |
-| Protocol Buffers | `tree-sitter-proto` | ✓ | Stable |
-| GraphQL | `tree-sitter-graphql` | ✓ | Official |
-| Groovy | `tree-sitter-groovy` | Verify | Less common |
-| Erlang | `tree-sitter-erlang` | ✓ | Maintained |
-| Gleam | `tree-sitter-gleam` | ✓ | Official |
-| GDScript | `tree-sitter-gdscript` | Verify | Community |
-| XML | `tree-sitter-xml` | ✓ | Stable |
-| Objective-C | `tree-sitter-objc` | Verify | May reuse C grammar |
-| Fortran | `tree-sitter-fortran` | ✓ | Available |
-
-For any grammar without a pre-built WASM, either compile from source using the Emscripten toolchain or defer that language.
-
----
-
-## Phase 22 Completion
-
-**Before**: 20 language handlers (TypeScript, JavaScript, Python, Go, Rust, C#, Java, PHP, Ruby, Kotlin, C, C++, Lua, Dart, Swift, Elixir, Haskell, Scala, R, plus SQL from Phase 21).
-
-**After**: 34 language handlers — within 12 of jCodeMunch's 46. The remaining gap consists of niche languages (AutoHotkey, Verse/UEFN, Blade, EJS) that represent a very small fraction of real-world codebases. PureContext now covers virtually all mainstream and semi-mainstream languages used in production systems.

package/docs/dev/PHASE23_TASKS.md

@@ -1,274 +0,0 @@
-# Phase 23 — Cross-Repo Intelligence
-
-**Goal**: Move beyond the single-repo constraint. Let agents search all indexed repos in one query, find semantically similar code using embeddings, detect symbols shared across repo boundaries, and expose repos as first-class MCP Resources.
-
-**Scope rationale**: jCodeMunch is fundamentally single-repo. PureContext's existing HNSW infrastructure and multi-tenant architecture make cross-repo and similarity search achievable with relatively small additions. These capabilities are a qualitative leap — no other MCP code navigation tool offers them.
-
----
-
-## Task 150: Cross-Repo Symbol Search
-
-Extend all search tools to accept an optional list of repo IDs so agents can query across their entire codebase universe in one call.
-
-**Current state**: `search_symbols`, `search_semantic`, and `search_text` each require a single `repoId` parameter. Agents must issue N separate queries to search N repos and merge results themselves.
-
-**Deliverables**:
-
-- Update `src/server/tools/search-symbols.ts`:
-  ```typescript
-  interface SearchSymbolsInput {
-    repoId?: string;       // Single repo — mutually exclusive with repoIds
-    repoIds?: string[];    // Multiple repos — omit both for ALL indexed repos
-    query: string;
-    // ... existing fields ...
-  }
-
-  interface SymbolSearchResult {
-    // ... existing fields ...
-    repoId: string;        // Always present in results
-    repoName: string;      // Human-readable repo name for disambiguation
-  }
-  ```
-- Same change to `src/server/tools/search-semantic.ts` and `src/server/tools/search-text.ts`
-- Resolution logic in `src/core/db/symbol-store.ts`:
-  - If `repoId` → existing single-repo path (no change)
-  - If `repoIds` → `WHERE repo_id IN (?)`
-  - If neither → `WHERE 1=1` (all repos)
-- FTS5 cross-repo: the `fts_symbols` virtual table already stores `repo_id` — include it in the `WHERE` clause
-- Results sorted by relevance score descending across all repos; `repoId` + `repoName` added to each result for disambiguation
-- `_meta` includes `reposSearched: string[]` — list of repo IDs that were included
-
-**Key technical notes**:
-- Multi-repo FTS5: the existing FTS5 table covers all repos — filter is a `WHERE` clause, not schema change
-- For `search_semantic`, HNSW nearest-neighbor search is global by design — filter results post-hoc by `repoIds`
-- Rate limiting: cross-repo queries cost more — apply a 2× token cost multiplier in the rate limiter when `repoIds.length > 1`
-- Tenant isolation must be preserved: only include repos belonging to the authenticated tenant
-- `repoName`: derive from `repos.root_path` basename or a user-provided `name` field (add to `repos` table if not present)
-
-**Tests**: `test/server/cross-repo-search.test.ts`
-- Single `repoId` → backward compatible
-- `repoIds: ["a", "b"]` → results from both repos, each tagged with `repoId`
-- Neither param → all repos searched
-- `repoName` present in all results
-- `_meta.reposSearched` accurate
-- Tenant isolation: repo from another tenant not included
-
-**Verify**:
-```bash
-# search_symbols { repoIds: ["abc", "def"], query: "authenticate" }
-# Results should interleave matches from both repos with repoName labels
-```
-
----
-
-## Task 151: Code Similarity Search
-
-New `search_similar` tool — given a code snippet or an existing symbol ID, find the most semantically similar symbols across any repos using the HNSW embedding index.
-
-**Current state**: `search_semantic` finds symbols matching a natural language *description*. There is no way to say "find me code that looks like *this code*" — passing actual source code as a query produces poor results because the query is embedded as a description, not as code.
-
-**Deliverables**:
-
-- `src/server/tools/search-similar.ts` — new MCP tool:
-  ```typescript
-  interface SearchSimilarInput {
-    repoId?: string;        // Scope results to a specific repo (optional)
-    repoIds?: string[];     // Or multiple repos
-
-    // Exactly one source must be provided:
-    symbolId?: string;      // Use an existing symbol's embedding
-    codeSnippet?: string;   // Embed a raw code snippet on the fly
-
-    limit?: number;         // Default 10, max 50
-    threshold?: number;     // Cosine similarity floor, default 0.75
-    excludeSelf?: boolean;  // Default true — exclude the source symbol
-    kind?: SymbolKind;      // Filter results by kind
-  }
-
-  interface SimilarSymbol {
-    symbolId: string;
-    name: string;
-    kind: SymbolKind;
-    filePath: string;
-    repoId: string;
-    repoName: string;
-    similarity: number;     // 0–1 cosine similarity
-    signature: string;
-    summary: string;
-  }
-
-  interface SearchSimilarOutput {
-    source: 'symbol' | 'snippet';
-    sourceName?: string;    // Symbol name if source is a symbol
-    results: SimilarSymbol[];
-    _meta: ResponseMeta;
-  }
-  ```
-- When `symbolId` provided: load existing embedding from `embeddings` table — no API call
-- When `codeSnippet` provided: embed it using the configured embedding provider (single call); do not persist the embedding
-- HNSW search: use existing `VectorStore.searchSimilar()` with the embedding vector
-- Filter by `repoIds` post-hoc (HNSW is global); filter by `kind` post-hoc
-- `threshold`: drop results below the cosine similarity floor
-- `excludeSelf`: if source is a `symbolId`, remove it from results
-
-**Key technical notes**:
-- `codeSnippet` embedding uses the same `prepareSymbolText` format if possible — but for snippets without a name/summary, embed the raw code directly. Document the difference in behavior
-- This is the killer differentiator vs jCodeMunch: "find all implementations of this pattern across all your repos" is not possible with keyword search
-- Token savings: code similarity eliminates many "read file to understand if it's relevant" steps — the agent gets pre-filtered similar candidates
-- If no semantic index exists for any repo, return a clear error explaining that `search_similar` requires semantic indexing to be enabled
-
-**Tests**: `test/server/search-similar.test.ts`
-- `symbolId` source: load embedding, return nearest neighbors
-- `codeSnippet` source: embed and search (mock embedding provider)
-- `excludeSelf` removes source symbol from results
-- `threshold` filters low-similarity results
-- `kind` filter applied correctly
-- No semantic index → clear error
-- `_meta` includes similarity scores
-
-**Verify**:
-```bash
-# search_similar { symbolId: "abc123def456", limit: 5, threshold: 0.8 }
-# Should return 5 most similar symbols by cosine similarity
-```
-
----
-
-## Task 152: Cross-Repo Dependency Tracking
-
-New `find_cross_repo_usages` tool — detect when source files in one repo reference identifiers that are defined in a different indexed repo (e.g. shared libraries, internal packages).
-
-**Current state**: Dependency graph (`dep_edges`) tracks edges within a single repo only. `find_importers` is scoped to a single repo. There is no way to answer: "which of my other repos use a symbol from this library?"
-
-**Deliverables**:
-
-- `src/server/tools/find-cross-repo-usages.ts` — new MCP tool:
-  ```typescript
-  interface FindCrossRepoUsagesInput {
-    sourceRepoId: string;     // The repo that defines the symbol
-    symbolName: string;       // Symbol name to search for in other repos
-    symbolKind?: SymbolKind;
-    targetRepoIds?: string[]; // Repos to search in (omit for all)
-    limit?: number;           // Default 50
-  }
-
-  interface CrossRepoUsage {
-    targetRepoId: string;
-    targetRepoName: string;
-    filePath: string;
-    lineNumber: number;
-    lineContent: string;
-    importPath?: string;      // The import specifier used, if detectable
-  }
-
-  interface FindCrossRepoUsagesOutput {
-    symbol: string;
-    sourceRepo: string;
-    usageCount: number;
-    reposWithUsages: number;
-    usages: CrossRepoUsage[];
-    _meta: ResponseMeta;
-  }
-  ```
-- Implementation: use the `find_references` infrastructure (Task 131) but scope to target repos
-  1. Look up the symbol in `sourceRepoId` to confirm it exists
-  2. Run word-boundary text search across all `targetRepoIds` (or all repos) using `file_store`
-  3. Filter out the source repo itself
-  4. Return matched file + line + surrounding content
-- Package name detection: check if the import path in the target file matches the source repo name or its npm package name (from `repos` table or `package.json` if cached)
-
-**Key technical notes**:
-- This is a text-based heuristic, not a type-system resolver — it will have false positives for common names
-- For precision, require `symbolKind` filter when the symbol name is generic (e.g. `init`, `new`, `handler`)
-- Performance: cross-repo text search on large installations could be slow — apply a `limit` and short-circuit early
-- Future: cross-repo type resolution would require full TypeScript language server integration (out of scope)
-
-**Tests**: `test/server/find-cross-repo-usages.test.ts`
-- Symbol found in target repo file
-- Source repo excluded from results
-- `targetRepoIds` scope filter respected
-- Common name with `kind` filter reduces false positives
-- Symbol not found in any target repo → empty usages, usageCount: 0
-
-**Verify**:
-```bash
-# find_cross_repo_usages { sourceRepoId: "lib-repo-id", symbolName: "parseConfig", targetRepoIds: ["app-repo-id"] }
-```
-
----
-
-## Task 153: MCP Resources Exposure
-
-Expose indexed repos and their files as MCP Resources — not just tools — so MCP clients that support Resources can browse the index without explicit tool calls.
-
-**Current state**: PureContext registers tools only. The MCP protocol supports Resources (static data) and ResourceTemplates (parameterized URIs), but PureContext does not implement them. Clients like Claude Code that support Resources can offer richer UX (e.g. autocomplete, inline browsing) when Resources are available.
-
-**Deliverables**:
-
-- `src/server/mcp-server.ts` — register Resources:
-  ```typescript
-  // Static resource: list of indexed repos
-  server.resource('purecontext://repos', 'Indexed repositories', async () => ({
-    contents: [{ uri: 'purecontext://repos', mimeType: 'application/json', text: JSON.stringify(await listRepos()) }]
-  }));
-
-  // Resource templates: per-repo outline and file outline
-  server.resourceTemplate(
-    'purecontext://repos/{repoId}/outline',
-    'Repository symbol outline',
-    async ({ repoId }) => ({ contents: [{ uri: ..., mimeType: 'application/json', text: JSON.stringify(await getRepoOutline(repoId)) }] })
-  );
-
-  server.resourceTemplate(
-    'purecontext://repos/{repoId}/files/{filePath}',
-    'File symbol outline',
-    async ({ repoId, filePath }) => ({ ... })
-  );
-
-  server.resourceTemplate(
-    'purecontext://repos/{repoId}/symbols/{symbolId}',
-    'Symbol source code',
-    async ({ repoId, symbolId }) => ({ contents: [{ uri: ..., mimeType: 'text/plain', text: source }] })
-  );
-  ```
-- URI scheme: `purecontext://repos/{repoId}/...`
-- Resources return JSON or plain text depending on content type
-- Resources are read-only — indexing still happens via tools
-- Add resource subscription support: when `file-watcher` detects changes, notify subscribed clients via `server.sendResourceUpdated(uri)`
-
-**Key technical notes**:
-- MCP SDK ≥ 1.29 supports `server.resource()` and `server.resourceTemplate()` — verify SDK version
-- Resources are cached by MCP clients — keep TTL considerations in mind (repo list changes rarely; symbol source changes on re-index)
-- Complement, not replace, tools: Resources give clients a browsable view; tools give agents precise retrieval
-- `filePath` in URIs must be URL-encoded (slashes → `%2F`) in the `files/{filePath}` template
-
-**Tests**: `test/server/mcp-resources.test.ts`
-- `purecontext://repos` returns repo list
-- `purecontext://repos/{repoId}/outline` returns symbol outline
-- `purecontext://repos/{repoId}/symbols/{symbolId}` returns symbol source
-- Unknown repoId → 404 error response
-- Resource notification sent on file change
-
-**Verify**:
-```bash
-# In a MCP client that supports Resources, PureContext repos should appear in the resource browser
-```
-
----
-
-## Order of Execution
-
-```
-150 (cross-repo search)    ── implement first (foundation for 152)
-151 (similarity search)    ── independent (needs HNSW, which exists)
-152 (cross-repo deps)      ── implement after 150 (reuses cross-repo scoping)
-153 (MCP resources)        ── independent
-```
-
----
-
-## Phase 23 Completion
-
-**Before**: PureContext is single-repo. Agents must issue N queries for N repos. No similarity search. No cross-repo dependency tracking. No MCP Resources.
-
-**After**: One query spans all repos. Code similarity search finds structurally similar implementations anywhere in the index — impossible with keyword search. Cross-repo dependencies are visible. PureContext repos appear as browsable Resources in supporting clients. No other MCP code tool offers any of this.