purecontext-mcp 1.1.1 → 1.1.2

package/docs/dev/PHASE20_TASKS.md

@@ -1,280 +0,0 @@
-# Phase 20 — Tool Capability Enhancements
-
-**Goal**: Sharpen four existing rough edges: search transparency (debug mode), symbol source precision (context lines + drift detection), GitHub API indexing without cloning, and Gemini Flash as a summarization backend.
-
-**Scope rationale**: These are quality-of-life improvements that close behavioural gaps vs jCodeMunch. Search debug mode is essential for tuning and trust. `context_lines` is frequently needed by agents reading symbol boundaries. Hash drift detection catches stale caches before they cause bugs. GitHub API indexing removes the clone requirement for remote repos. Gemini support broadens the summarization options beyond Anthropic + OpenAI-compatible.
-
----
-
-## Task 135: Search Debug Mode
-
-Add an optional `debug: true` parameter to `search_symbols` and `search_semantic` that returns a per-result score breakdown so users can understand and tune relevance.
-
-**Current state**: Both search tools return ranked results with no explanation of *why* a result ranked where it did. When results are surprising, there is no way to diagnose the scoring.
-
-**Deliverables**:
-
-- Update `src/server/tools/search-symbols.ts`:
-  ```typescript
-  interface SearchSymbolsInput {
-    // ... existing fields ...
-    debug?: boolean;  // Default false
-  }
-
-  interface SymbolSearchResult {
-    // ... existing fields ...
-    _score?: {            // Only present when debug: true
-      total: number;
-      nameExact: number;
-      namePrefix: number;
-      nameFuzzy: number;
-      signatureMatch: number;
-      summaryMatch: number;
-      kindBoost: number;
-      recencyBoost: number;
-    };
-  }
-  ```
-- Update `src/server/tools/search-semantic.ts`:
-  ```typescript
-  interface SearchSemanticInput {
-    // ... existing fields ...
-    debug?: boolean;
-  }
-
-  interface SemanticSearchResult {
-    // ... existing fields ...
-    _score?: {
-      total: number;
-      vectorSimilarity: number;       // Cosine similarity from HNSW
-      keywordBoost: number;           // FTS5 overlap bonus
-      nameMatch: number;              // Exact/prefix name match bonus
-      hybridWeight: number;           // α blending factor used
-    };
-  }
-  ```
-- Thread `debug` flag through to the FTS5 scorer in `src/core/db/symbol-store.ts` and the HNSW retriever in the semantic search pipeline
-- Score fields should be raw (not normalised) so they are comparable across calls
-- When `debug: false` (default), the `_score` key is omitted entirely — no overhead
-
-**Key technical notes**:
-- Score components should reflect the actual weights used in the ranking algorithm, not reconstructed post-hoc
-- For FTS5, expose the BM25 score plus each field's contribution (name, signature, summary, keywords columns)
-- For HNSW, expose the raw cosine distance converted to similarity, plus the keyword re-ranking delta
-- Keep debug output deterministic — same query must produce same scores for the same index state
-
-**Tests**: `test/server/search-debug.test.ts`
-- `search_symbols` with `debug: true` returns `_score` on each result
-- `search_symbols` with `debug: false` omits `_score`
-- `search_semantic` with `debug: true` returns vector + keyword scores
-- Score components sum correctly to `total`
-
-**Verify**:
-```bash
-# search_symbols { repoId: "...", query: "parseSymbol", debug: true }
-# Each result should include _score breakdown
-```
-
----
-
-## Task 136: `context_lines` and `verify` Parameters on `get_symbol_source` and `get_symbols`
-
-Extend symbol retrieval with surrounding context lines and optional content hash drift detection.
-
-**Current state**: `get_symbol_source` returns the exact bytes of a symbol — no surrounding context. There is no way to verify whether the cached symbol bytes still match the file on disk.
-
-**Deliverables**:
-
-- Update `src/server/tools/get-symbol-source.ts`:
-  ```typescript
-  interface GetSymbolSourceInput {
-    repoId: string;
-    symbolId: string;
-    contextLines?: number;  // Lines before and after symbol. Default 0, max 50
-    verify?: boolean;       // Re-hash file from disk. Default false
-  }
-
-  interface GetSymbolSourceOutput {
-    // ... existing fields ...
-    contextLines?: number;  // Echoed back
-    hashDrift?: boolean;    // Only present when verify: true
-    diskHash?: string;      // Only present when verify: true and hashDrift: true
-    cachedHash?: string;    // Only present when verify: true and hashDrift: true
-  }
-  ```
-- `get_symbols` (Task 133) should also support both parameters — implement the shared logic once in a helper
-
-- Create `src/core/symbol-source-helper.ts`:
-  ```typescript
-  export function expandWithContextLines(
-    fileContent: Buffer,
-    startByte: number,
-    endByte: number,
-    contextLines: number
-  ): { expandedContent: string; expandedStartLine: number; expandedEndLine: number }
-
-  export async function verifyContentHash(
-    filePath: string,
-    cachedHash: string
-  ): Promise<{ drift: boolean; diskHash: string }>
-  ```
-- `expandWithContextLines`: split file content on `\n`, find lines containing `startByte`/`endByte`, expand by N lines in each direction, re-join
-- `verifyContentHash`: read file from disk, SHA-256 hash it, compare to `cachedHash` from `files` table
-
-**Key technical notes**:
-- `contextLines` max 50 to prevent accidentally returning entire files
-- When `contextLines > 0`, include line numbers in the output (same format as `get_file_content`)
-- `verify` reads the file from disk — only use when content freshness matters. Document the performance cost in the tool description
-- Hash drift does NOT auto-trigger re-indexing — it only reports. Let the caller decide (e.g. call `index_folder` again)
-
-**Tests**: `test/server/symbol-context.test.ts`
-- `contextLines: 3` returns 3 lines before and after symbol
-- `contextLines: 0` returns bare symbol (backward compatible)
-- `contextLines > 50` → clamped to 50 with warning in `_meta`
-- `verify: true` with matching hash → `hashDrift: false`
-- `verify: true` with modified file → `hashDrift: true` + both hashes returned
-- `verify: false` → no `hashDrift` field
-
-**Verify**:
-```bash
-# get_symbol_source { repoId: "...", symbolId: "abc123", contextLines: 5, verify: true }
-```
-
----
-
-## Task 137: GitHub API Indexing
-
-Extend `index_repo` to support indexing a GitHub repository via the GitHub Contents API — no local clone required.
-
-**Current state**: `index_repo` clones the repository using git and indexes the local clone. This requires git to be installed, adequate disk space, and works poorly for large repos or CI environments without persistent storage.
-
-**Deliverables**:
-
-- Update `src/server/tools/index-repo.ts` to detect GitHub URLs and route to the API path:
-  ```typescript
-  interface IndexRepoInput {
-    url: string;              // git clone URL or https://github.com/owner/repo
-    branch?: string;          // Default: repo's default branch
-    useGitHubApi?: boolean;   // Force GitHub API mode (auto-detected for github.com URLs)
-    githubToken?: string;     // Override GITHUB_TOKEN env var
-  }
-  ```
-- Create `src/core/github-api-fetcher.ts`:
-  ```typescript
-  interface GitHubApiFetcher {
-    listFiles(owner: string, repo: string, branch: string): Promise<GitHubTreeEntry[]>
-    fetchFile(owner: string, repo: string, sha: string): Promise<Buffer>
-    getDefaultBranch(owner: string, repo: string): Promise<string>
-    getCommitSha(owner: string, repo: string, branch: string): Promise<string>
-  }
-  ```
-- GitHub API strategy:
-  1. `GET /repos/{owner}/{repo}` — get default branch + metadata
-  2. `GET /repos/{owner}/{repo}/git/trees/{branch}?recursive=1` — get full file tree
-  3. Filter to indexable extensions using existing `file-discovery.ts` logic
-  4. Fetch file content via `GET /repos/{owner}/{repo}/contents/{path}` (base64 encoded) or blob SHA
-  5. Incremental re-index: store `git_tree_sha` in `repos` table; on next call, compare to avoid re-fetching unchanged files (use blob SHA from tree API)
-- Auto-detect GitHub API mode: if `url` matches `github.com/{owner}/{repo}`, use API. Otherwise use git clone
-- Respect `GITHUB_TOKEN` env var for authentication (higher rate limits: 5000 req/hr vs 60)
-- Rate limit handling: detect 403/429, retry with exponential backoff + jitter
-
-**Key technical notes**:
-- GitHub tree API returns the full recursive file list in one call — use this for file discovery, not individual directory listings
-- Blob SHA from the tree response is the incremental key — store in `files` table as `remote_sha` alongside the content hash
-- File size limit: skip files > 500KB (same as local indexing default)
-- Store fetched file content in `file_store` — same path as local indexing so all other tools work identically
-- Private repos require a `GITHUB_TOKEN` — surface a clear error if the token is missing and the repo returns 404/403
-
-**Tests**: `test/core/github-api-fetcher.test.ts` (mocked HTTP)
-- Full file list fetched from tree API
-- Incremental: unchanged blob SHA skips re-fetch
-- Rate limit retry with backoff
-- Missing token on private repo → clear error
-- URL parsing: `github.com/owner/repo`, `https://github.com/owner/repo`, `git@github.com:owner/repo.git`
-
-**Verify**:
-```bash
-# index_repo { url: "https://github.com/expressjs/express", useGitHubApi: true }
-```
-
----
-
-## Task 138: Gemini Flash Summarization Backend
-
-Add Google Gemini Flash as a summarization backend option alongside the existing Anthropic and OpenAI-compatible providers.
-
-**Current state**: `src/summarizer/ai-summarizer.ts` supports Anthropic (Messages API) and OpenAI-compatible endpoints (covers Ollama, LM Studio, etc.). Gemini requires a different SDK/API call structure.
-
-**Deliverables**:
-
-- Update `src/summarizer/ai-summarizer.ts` to support a `gemini` provider:
-  ```typescript
-  type SummarizerProvider = 'anthropic' | 'openai-compatible' | 'gemini';
-
-  interface SummarizerConfig {
-    provider: SummarizerProvider;
-    model?: string;              // Default per provider: claude-haiku-4-5 / gpt-4o-mini / gemini-2.0-flash
-    apiKey?: string;
-    baseUrl?: string;            // For openai-compatible only
-    maxConcurrency?: number;
-  }
-  ```
-- Create `src/summarizer/providers/gemini-provider.ts`:
-  - Use the Gemini REST API directly (no SDK dependency): `POST https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent`
-  - Auth: `?key={GOOGLE_API_KEY}` query parameter
-  - Request format: `{ contents: [{ parts: [{ text: prompt }] }] }`
-  - Response: `candidates[0].content.parts[0].text`
-  - Default model: `gemini-2.0-flash`
-- Config schema update (`src/config/config-schema.ts`):
-  ```json
-  {
-    "summarizer": {
-      "provider": "gemini",
-      "model": "gemini-2.0-flash",
-      "apiKey": "${GOOGLE_API_KEY}"
-    }
-  }
-  ```
-- Auto-detection: if `GOOGLE_API_KEY` is set and no other provider is configured, use Gemini
-- Same batch processing, concurrency controls, and fallback logic as existing providers
-
-**Key technical notes**:
-- Use `https.request` (same pattern as the Anthropic provider) — no new dependencies
-- Gemini Flash is priced similarly to Claude Haiku — document the cost trade-offs in config comments
-- The prompt template is identical across providers — Gemini receives the same symbol signature + docstring input
-- Error mapping: Gemini quota errors (429) should trigger the same backoff as Anthropic overload errors
-
-**Tests**: `test/summarizer/gemini-provider.test.ts` (mocked HTTP)
-- Successful summarization call
-- Auth via `GOOGLE_API_KEY` env var
-- 429 → retry with backoff
-- Malformed response → falls back to docstring
-- Auto-detection when `GOOGLE_API_KEY` set
-
-**Verify**:
-```bash
-GOOGLE_API_KEY=... npx purecontext-mcp config --check
-# Should report: summarizer provider: gemini (gemini-2.0-flash)
-```
-
----
-
-## Order of Execution
-
-```
-135 (search debug)         ── independent
-136 (context_lines/verify) ── implement helper first, then wire into get_symbol_source
-                              Task 133 (get_symbols) from Phase 19 should also use this helper
-137 (GitHub API indexing)  ── independent
-138 (Gemini backend)       ── independent
-```
-
-Task 136's `symbol-source-helper.ts` should be shared with Task 133 (`get_symbols`) — implement 136 first if doing sequentially.
-
----
-
-## Phase 20 Completion
-
-**Before**: Search is a black box; symbol source is exact bytes only; indexing requires git clone; summarization limited to Anthropic + OpenAI-compatible.
-
-**After**: Search results carry score breakdowns for tuning and trust. Agents can request surrounding context lines and detect cache drift. GitHub repos can be indexed via API without cloning. Gemini Flash is a first-class summarization backend. PureContext reaches behavioural parity with jCodeMunch on all tool-level capability gaps.

package/docs/dev/PHASE21_TASKS.md

@@ -1,355 +0,0 @@
-# Phase 21 — Ecosystem & Data Tools
-
-**Goal**: Add a context provider plugin framework, a dbt provider, a `search_columns` tool, an OpenAPI/Swagger handler, and a SQL language handler with dbt Jinja preprocessing — bringing PureContext to full parity with jCodeMunch's ecosystem and data-engineering capabilities.
-
-**Scope rationale**: Data engineering is a high-value niche where jCodeMunch has meaningful differentiation. The context provider framework is the architectural foundation — everything else in this phase plugs into it. OpenAPI/Swagger and SQL are common in real backends and data pipelines; not supporting them is a conspicuous gap.
-
----
-
-## Task 139: Context Provider Framework
-
-Build the plugin architecture that allows ecosystem-specific metadata (dbt, Terraform, database catalogs, etc.) to enrich indexed symbols automatically after the core indexing pipeline completes.
-
-**Current state**: Framework adapters (`src/adapters/`) handle AST-level symbol extraction. There is no post-indexing enrichment layer for ecosystem metadata that lives outside the source files themselves (e.g. schema.yml descriptions, Terraform variable docs, OpenAPI tags).
-
-**Deliverables**:
-
-- `src/providers/provider-registry.ts` — auto-discover and activate providers
-- `src/core/types.ts` — add `ContextProvider` interface:
-  ```typescript
-  interface ContextProvider {
-    name: string;
-    description: string;
-
-    /** Return true if this provider applies to the given project root */
-    detect(projectRoot: string): Promise<boolean>;
-
-    /** Called once after full indexing completes for a repo */
-    enrich(
-      repoId: string,
-      projectRoot: string,
-      db: Database
-    ): Promise<EnrichmentResult>;
-  }
-
-  interface EnrichmentResult {
-    symbolsEnriched: number;
-    metadataAdded: Record<string, unknown>;  // Provider-specific stats
-  }
-  ```
-- `src/core/db/schema.ts` — add `provider_metadata` table:
-  ```sql
-  CREATE TABLE IF NOT EXISTS provider_metadata (
-    repo_id       TEXT NOT NULL,
-    provider_name TEXT NOT NULL,
-    entity_key    TEXT NOT NULL,  -- e.g. model name, file path
-    metadata      TEXT NOT NULL,  -- JSON blob
-    updated_at    INTEGER NOT NULL,
-    PRIMARY KEY (repo_id, provider_name, entity_key)
-  );
-  ```
-- `src/core/index-manager.ts` — after core indexing completes, run all activated providers:
-  ```typescript
-  // After symbol extraction and summarization:
-  const providers = await providerRegistry.detectAll(projectRoot);
-  for (const provider of providers) {
-    const result = await provider.enrich(repoId, projectRoot, db);
-    logger.info(`Provider ${provider.name}: enriched ${result.symbolsEnriched} symbols`);
-  }
-  ```
-- Provider enrichment updates `framework_meta` on affected `symbols` rows and writes to `provider_metadata`
-- `src/config/config-schema.ts` — add optional `providers` config block:
-  ```json
-  {
-    "providers": {
-      "dbt": { "enabled": true, "schemaDir": "models" },
-      "terraform": { "enabled": false }
-    }
-  }
-  ```
-- Default: all providers are auto-detected (no config needed). Config allows disabling or overriding paths
-
-**Key technical notes**:
-- Providers run in series after indexing, not during AST parsing — they read the already-indexed symbols from the DB and annotate them
-- Providers must be idempotent: re-running enrichment on an already-enriched repo should produce the same result
-- Provider errors must not fail the indexing operation — log at `warn` and continue
-- The `provider_metadata` table is the storage layer; `symbols.framework_meta` is the search-visible enrichment
-
-**Tests**: `test/providers/provider-registry.test.ts`
-- `detect()` returns false for non-matching project
-- Provider runs after indexing
-- Provider failure does not abort indexing
-- Idempotent re-enrichment
-
-**Verify**:
-```bash
-# index_folder { path: "/path/to/dbt-project" }
-# Should log: "Provider dbt: enriched N symbols"
-```
-
----
-
-## Task 140: dbt Context Provider
-
-Implement the dbt context provider that auto-detects dbt projects, parses `schema.yml` column metadata and doc blocks, and enriches indexed SQL symbols with descriptions, tags, and column-level metadata.
-
-**Current state**: No dbt awareness exists. dbt SQL models, when indexed (after Task 143), will have symbol records but no descriptions, column metadata, or tags from schema.yml.
-
-**Deliverables**:
-
-- `src/providers/dbt-provider.ts` — implements `ContextProvider`:
-  ```typescript
-  class DbtProvider implements ContextProvider {
-    name = 'dbt';
-    description = 'Enriches dbt models with schema.yml descriptions and column metadata';
-
-    async detect(projectRoot: string): Promise<boolean> {
-      // Check for dbt_project.yml
-    }
-
-    async enrich(repoId: string, projectRoot: string, db: Database): Promise<EnrichmentResult>
-  }
-  ```
-- Detection: presence of `dbt_project.yml` in `projectRoot`
-- Schema parsing: recursively find all `schema.yml` / `schema.yaml` files under `models/` directory
-  - Parse YAML (use `js-yaml` — already a common dependency; add if not present)
-  - Extract per-model: `description`, `tags`, `meta`, `columns[]` (name + description + tags)
-  - Extract per-source: `description`, `tables[]` with column metadata
-- Doc block parsing: find `{% docs model_name %}...{% enddocs %}` in `.md` files
-- Enrichment logic:
-  - Match schema.yml model names to `symbols` rows where `name = model_name AND kind = 'function'` (SQL models are indexed as functions)
-  - Update `symbols.summary` with model description if currently empty or auto-generated
-  - Update `symbols.framework_meta` with `{ columns: [...], tags: [...], meta: {...} }`
-  - Write full column metadata to `provider_metadata` table keyed by `(repoId, 'dbt', modelName)`
-- `src/core/db/symbol-store.ts` — add `updateSymbolMeta(id, summary, frameworkMeta)` if not present
-
-**Key technical notes**:
-- YAML parsing: `js-yaml` handles the dbt schema.yml format. Watch for multi-document YAML files
-- Column metadata lives in `provider_metadata`, not `symbols` — it's too wide for a symbol row
-- Only overwrite `summary` if it was auto-generated (check for presence of a sentinel prefix) — never overwrite a human-written docstring
-- Tags from schema.yml should be added to the FTS5 `keywords` column for searchability
-
-**Tests**: `test/providers/dbt-provider.test.ts`
-- Detection: `dbt_project.yml` present → true; absent → false
-- Schema.yml with models, columns, tags parsed correctly
-- Doc block extraction
-- Symbol summary updated with model description
-- `provider_metadata` rows written correctly
-- Uses fixture: `test/fixtures/dbt-project/`
-
-**Verify**:
-```bash
-# After indexing a dbt project, search_symbols should return models with descriptions
-# provider_metadata should have column metadata rows
-```
-
----
-
-## Task 141: `search_columns` Tool
-
-Search column metadata across dbt/SQLMesh models — find columns by name, description, or tag without reading entire schema files.
-
-**Current state**: No column-level search exists. Users/agents must read entire `schema.yml` files to find column information. jCodeMunch benchmarks this tool at 77% fewer tokens than grep.
-
-**Deliverables**:
-
-- `src/server/tools/search-columns.ts` — new MCP tool:
-  ```typescript
-  interface SearchColumnsInput {
-    repoId: string;
-    query: string;           // Search column names and descriptions
-    modelFilter?: string;    // Optional: only search within this model name
-    tagFilter?: string[];    // Optional: only columns with these tags
-    limit?: number;          // Default 20, max 100
-  }
-
-  interface ColumnResult {
-    modelName: string;
-    modelFilePath: string;
-    columnName: string;
-    columnDescription: string;
-    tags: string[];
-    dataType?: string;       // If present in schema.yml
-    meta?: Record<string, unknown>;
-  }
-
-  interface SearchColumnsOutput {
-    query: string;
-    totalResults: number;
-    columns: ColumnResult[];
-    _meta: ResponseMeta;
-  }
-  ```
-- Query logic: search `provider_metadata` table where `provider_name = 'dbt'`, parse JSON metadata, filter columns by name/description match
-- Use SQLite `json_each` to query within the JSON metadata blob efficiently:
-  ```sql
-  SELECT pm.entity_key as model_name, s.file_path, col.value as col_data
-  FROM provider_metadata pm, json_each(pm.metadata, '$.columns') col
-  WHERE pm.repo_id = ? AND pm.provider_name = 'dbt'
-    AND (col.value->>'name' LIKE ? OR col.value->>'description' LIKE ?)
-  ```
-- `modelFilter`: add `AND pm.entity_key = ?`
-- `tagFilter`: filter post-query in application code (JSON array membership check)
-- Token savings: compare returned column metadata size vs full schema.yml files
-
-**Key technical notes**:
-- This tool returns useful results only when the dbt provider (Task 140) has been run — return a clear hint if `provider_metadata` has no dbt rows for the repo
-- SQLite JSON functions (`json_each`, `->>`): available since SQLite 3.38 — check minimum version and document
-- The search is substring-based (LIKE), not FTS5. This is intentional — column names are short and precision matters more than recall
-
-**Tests**: `test/server/search-columns.test.ts`
-- Query matching column name
-- Query matching column description
-- `modelFilter` narrows to one model
-- `tagFilter` narrows by tag
-- No dbt metadata → helpful error with hint to run dbt provider
-- Returns `_meta` with token savings
-
-**Verify**:
-```bash
-# search_columns { repoId: "...", query: "customer_id" }
-# Should return all models with a column named/described as customer_id
-```
-
----
-
-## Task 142: OpenAPI/Swagger Language Handler
-
-Index OpenAPI and Swagger specification files, extracting API paths as function symbols and schema definitions as class symbols.
-
-**Current state**: `.openapi.yaml`, `.swagger.json`, and similar API spec files are skipped by the indexer. They are common in modern backends and contain critical API surface information.
-
-**Deliverables**:
-
-- `src/handlers/openapi.ts` — implements `LanguageHandler`:
-  ```typescript
-  class OpenApiHandler implements LanguageHandler {
-    extensions() { return ['.yaml', '.yml', '.json']; }
-    // Detection: only activate when file content contains 'openapi:' or 'swagger:' key
-  }
-  ```
-- Since OpenAPI/Swagger files are structured data (YAML/JSON), not code, this handler does **not** use tree-sitter. Instead, parse with `js-yaml` / `JSON.parse` and extract symbols directly:
-  ```typescript
-  interface OpenApiExtractor {
-    extractPaths(spec: OpenApiSpec): SymbolRecord[]     // paths → kind: 'function'
-    extractSchemas(spec: OpenApiSpec): SymbolRecord[]   // components.schemas → kind: 'class'
-    extractTags(spec: OpenApiSpec): string[]
-  }
-  ```
-- Path symbol extraction:
-  - Each `paths['/endpoint'][method]` becomes one `SymbolRecord`
-  - `name`: `METHOD /endpoint` (e.g. `GET /users/{id}`)
-  - `kind`: `'function'`
-  - `signature`: `operationId?: string` or auto-generated from method+path
-  - `summary`: `operation.summary` or `operation.description`
-  - `frameworkMeta`: `{ method, path, tags, parameters: [...], requestBody: {...} }`
-- Schema symbol extraction:
-  - Each `components.schemas[Name]` → `SymbolRecord` with `kind: 'class'`
-  - `name`: schema name
-  - `signature`: `interface SchemaName` with top-level properties listed
-  - `summary`: schema `description`
-  - `frameworkMeta`: `{ properties: [...], required: [...] }`
-- File detection: the handler's `extensions()` returns `.yaml/.yml/.json` which overlap with other files. Add a `detect(content: Buffer): boolean` method that checks for `openapi:` or `swagger:` at root level before committing to parse
-- `grammarPath()` returns `null` for this handler (no tree-sitter grammar needed)
-- `extractImports()` returns `[]` (OpenAPI files have no imports)
-
-**Key technical notes**:
-- OpenAPI 3.x and Swagger 2.x are both supported — detect via `openapi: 3.x.x` vs `swagger: '2.0'`
-- Large specs with 200+ paths should still complete quickly — JSON/YAML parsing is fast
-- `startByte`/`endByte` for each symbol: find the key in the raw file content using string search (since we're not using tree-sitter byte offsets). Use `Buffer.indexOf` to find the path/schema name key in the serialized file
-- Register in `src/handlers/handler-registry.ts` with lower priority than exact extension matches (YAML handler should not conflict with Vue SFC handler)
-
-**Tests**: `test/handlers/openapi.test.ts`
-- OpenAPI 3.x path extraction (GET, POST, DELETE)
-- Swagger 2.0 path extraction
-- Schema component extraction
-- Non-OpenAPI YAML file → `detect()` returns false
-- Summary from `operation.summary`
-- `frameworkMeta` contains method, path, tags
-
-**Verify**:
-```bash
-# index_folder on a project with openapi.yaml
-# search_symbols { query: "GET /users" } should return the path symbol
-```
-
----
-
-## Task 143: SQL Language Handler with dbt Jinja Preprocessing
-
-Add a SQL language handler that indexes `.sql` files, with dbt Jinja template preprocessing to strip/replace template blocks before parsing.
-
-**Current state**: `.sql` files are not indexed. dbt projects contain hundreds of SQL model files that are currently invisible to PureContext.
-
-**Deliverables**:
-
-- `src/handlers/sql.ts` — implements `LanguageHandler`:
-  ```typescript
-  class SqlHandler implements LanguageHandler {
-    extensions() { return ['.sql']; }
-    grammarPath() { return 'grammars/tree-sitter-sql.wasm'; }
-  }
-  ```
-- Download and bundle `tree-sitter-sql.wasm` (from `@matthijs/tree-sitter-sql` or equivalent) in `grammars/`
-- dbt Jinja preprocessing — create `src/handlers/sql-jinja-preprocessor.ts`:
-  ```typescript
-  function preprocessJinja(source: Buffer): Buffer {
-    // Replace {{ ref('model') }} → 'model'
-    // Replace {{ source('schema', 'table') }} → 'schema.table'
-    // Replace {% if ... %}...{% endif %} → (empty or stub)
-    // Replace {% set var = ... %} → (empty)
-    // Replace {{ var }} → 'var'
-    // Result must be valid SQL parseable by tree-sitter-sql
-  }
-  ```
-- Symbol extraction from SQL AST:
-  - `CREATE TABLE / VIEW / MATERIALIZED VIEW name` → `kind: 'class'`
-  - `CREATE FUNCTION / PROCEDURE name` → `kind: 'function'`
-  - `WITH cte_name AS (...)` CTEs → `kind: 'const'`
-  - For dbt model files (no explicit CREATE statement), the file itself is the model → emit one symbol: `kind: 'function'`, `name: stem(filePath)`
-- Macro extraction from dbt macro files:
-  - `{% macro macro_name(...) %}` → `kind: 'function'`
-  - `{% test test_name(...) %}` → `kind: 'function'`
-  - `{% snapshot snapshot_name %}` → `kind: 'class'`
-- Import extraction: `{{ ref('model_name') }}` and `{{ source('schema', 'table') }}` become `ImportRecord` entries for the dependency graph
-
-**Key technical notes**:
-- dbt files often have no SQL DDL — just a SELECT. The handler must detect this pattern and emit the model-file symbol
-- Jinja preprocessing must be applied before passing source to tree-sitter — tree-sitter-sql cannot parse Jinja syntax
-- After preprocessing, store the *original* source in `file_store` (not the preprocessed version) so `get_file_content` returns the real file
-- Regex-based Jinja stripping is sufficient — a full Jinja parser is not needed for symbol extraction purposes
-- The dbt provider (Task 140) runs *after* this handler and enriches the extracted symbols with schema.yml metadata
-
-**Tests**: `test/handlers/sql.test.ts`
-- Plain SQL: `CREATE TABLE`, `CREATE FUNCTION`, CTEs extracted
-- dbt model file (SELECT only): model symbol emitted with filename as name
-- dbt macro file: macro symbols extracted
-- Jinja preprocessing: `ref()` and `source()` replaced, resulting SQL is valid
-- Import records from `ref()` calls
-
-**Verify**:
-```bash
-# index_folder on a dbt project
-# get_repo_outline should show SQL files indexed
-# search_symbols { query: "orders" } should return the orders.sql model
-```
-
----
-
-## Order of Execution
-
-```
-139 (Context Provider Framework)  ──▶  140 (dbt Provider)  ──▶  141 (search_columns)
-142 (OpenAPI Handler)              ── independent
-143 (SQL Handler)                  ── independent (but dbt Provider enriches SQL symbols, so 143 before 140 in practice)
-```
-
-Recommended sequence: 139 → 143 → 140 → 141 → 142
-
----
-
-## Phase 21 Completion
-
-**Before**: No ecosystem metadata, no column search, no SQL or OpenAPI indexing, no context enrichment plugins.
-
-**After**: A pluggable context provider framework that any data tool can hook into. dbt projects are fully indexed — SQL models with descriptions, tags, and column metadata from schema.yml. API spec files are indexed with paths and schemas as searchable symbols. `search_columns` closes the last major workflow gap vs jCodeMunch. PureContext reaches full feature parity.