purecontext-mcp 1.1.1 → 1.1.2

package/docs/dev/PHASE26_TASKS.md

@@ -1,253 +0,0 @@
-# Phase 26 — Enhanced Web UI
-
-**Goal**: Evolve the Web UI from a basic browser into a visual intelligence dashboard — architecture heatmaps, symbol history timelines, test coverage overlays, multi-repo workspaces, and richer dependency graph interaction.
-
-**Scope rationale**: jCodeMunch has no UI at all. PureContext's Web UI (Phase 13) is a significant differentiator. This phase deepens it with visuals that make architecture analysis intuitive and that surface the data computed in Phases 24–25 in a way that non-agent users can also benefit from.
-
----
-
-## Task 163: Architecture Heatmap
-
-Overlay code quality and churn data (from Phases 24–25) onto the file tree, turning it into a visual risk map of the codebase.
-
-**Current state**: The file tree (`src/ui/src/components/FileTree.tsx`) shows directory structure with file extension badges. It has no visual indication of code quality, complexity, or change frequency.
-
-**Deliverables**:
-
-- `src/ui/src/components/HeatmapLegend.tsx` — color scale legend with toggle between `complexity`, `churn`, and `combined` modes
-- `src/ui/src/components/FileTree.tsx` — extend with heatmap support:
-  - Each file node gets a colored left-border or background tint based on the selected metric
-  - Color scale: green (low/good) → yellow (moderate) → orange (high) → red (critical)
-  - Tooltip on hover: "Avg complexity: 8.3 | Churn: 12 commits/90d | 3 critical symbols"
-  - Heatmap mode toggle button in the file tree header
-- `src/ui/src/api/client.ts` — add `api.getQualityMetrics(repoId, scope?)` and `api.getChurnMetrics(repoId, scope?)`
-- `src/server/http-server.ts` — add REST endpoints:
-  - `GET /api/repos/:id/quality?scope=...` → `get_quality_metrics` tool
-  - `GET /api/repos/:id/churn?scope=...&days=...` → `get_churn_metrics` tool
-- Heatmap data is loaded lazily when the user enables heatmap mode (not on initial page load)
-- Directory nodes: aggregate their children's scores (max for critical display, avg for gradient)
-- Color interpolation: use D3's `scaleSequential` with a `RdYlGn` color scale (red-yellow-green)
-
-**Key technical notes**:
-- Heatmap data should be cached in the Zustand store — don't re-fetch on every tree expand
-- If quality metrics are not available for a repo (never calculated), show a banner: "Run analysis to enable heatmap" with a button that triggers re-indexing
-- Three modes: `complexity` (cyclomatic), `churn` (commits/90d), `combined` (weighted: 60% complexity, 40% churn)
-- Colorblind-safe: add an optional pattern overlay (dots = high complexity, stripes = high churn) for accessibility
-
-**Tests**: `test/ui/heatmap.test.ts`
-- HeatmapLegend renders with three mode options
-- FileTree applies correct color class based on score
-- Tooltip content matches mock data
-- Directory aggregation: max of children used for critical display
-
-**Verify**:
-```bash
-npm run dev  # Navigate to repo detail, enable heatmap — file tree should show colored risk indicators
-```
-
----
-
-## Task 164: Symbol Change Timeline
-
-Display the git history of a symbol as an interactive timeline in the symbol view page, showing who changed it, when, and how frequently.
-
-**Current state**: The symbol view page (`src/ui/src/pages/SymbolView.tsx`) shows source code, signature, summary, and related symbols. There is no git history view.
-
-**Deliverables**:
-
-- `src/ui/src/components/SymbolTimeline.tsx` — new component:
-  - Horizontal timeline with commit dots on a date axis (last 12 months or N commits)
-  - Each dot represents a commit; size indicates lines changed
-  - Hover tooltip: author avatar (initials), date, commit message
-  - Click to expand: show the diff summary for that commit (lines added/removed in the symbol's range)
-  - Color coding: dots colored by author (consistent per-author color derived from name hash)
-  - Churn score badge: "12 commits in 90d — Volatile"
-- `src/ui/src/pages/SymbolView.tsx` — add "History" tab alongside "Source" and "Related":
-  - Tab shows `SymbolTimeline` component
-  - Tab is hidden if no git history data available for the repo
-- `src/ui/src/api/client.ts` — add `api.getSymbolHistory(repoId, symbolId, limit?)`
-- `src/server/http-server.ts` — add `GET /api/repos/:id/symbols/:symbolId/history?limit=...`
-- `src/ui/src/api/types.ts` — add `SymbolHistoryResponse`, `SymbolCommit` types
-
-**Key technical notes**:
-- Author color: `hsl(hash(authorEmail) % 360, 70%, 50%)` — deterministic, visually distinct
-- Commit message should be truncated at 60 chars with ellipsis in the timeline dot tooltip
-- If `get_symbol_history` returns no results (non-git repo), the tab is hidden
-- Timeline D3 axis: use `scaleTime` for the x-axis; 12-month window by default, zoom to all-time via button
-- The "diff summary" on commit click is optional (lines +/-) — derive from `linesAdded`/`linesRemoved` stored in git_metadata
-
-**Tests**: `test/ui/symbolTimeline.test.ts`
-- Timeline renders correct number of dots for mock history
-- Tooltip appears on hover with author, date, message
-- Churn score badge shows correct value
-- "History" tab hidden when history empty
-
-**Verify**:
-```bash
-npm run dev  # Navigate to a symbol in a git-indexed repo, click "History" tab
-```
-
----
-
-## Task 165: Test Coverage Overlay
-
-Show which symbols in the file tree and symbol view have associated test coverage, and link directly to the test file/symbol.
-
-**Current state**: PureContext indexes test files (they end up in the symbol index) but does not link test symbols to the production symbols they test. There is no visual coverage indicator anywhere in the UI.
-
-**Deliverables**:
-
-- `src/core/test-mapper.ts` — new module:
-  ```typescript
-  interface TestMapping {
-    symbolId: string;        // Production symbol
-    testSymbolIds: string[]; // Test symbols that reference this production symbol
-    testFilePaths: string[];
-    coverageStatus: 'tested' | 'untested' | 'unknown';
-  }
-
-  async function buildTestMappings(repoId: string, db: Database): Promise<TestMapping[]>
-  ```
-  - Heuristic: test files are in `test/`, `__tests__/`, `spec/`, or end with `.test.ts`, `.spec.ts`
-  - For each test file, find referenced production symbol names via `find_references` logic
-  - Map test → production symbol by name match within the same repo
-  - Store in `provider_metadata` table: `(repoId, 'test-mapper', symbolId)` → `{ testFiles: [...] }`
-- `src/core/index-manager.ts` — run `buildTestMappings` after indexing completes (same pattern as context providers, Task 139)
-- UI components:
-  - `src/ui/src/components/FileTree.tsx` — add coverage dot: green = tested, red = untested, gray = unknown
-  - `src/ui/src/pages/SymbolView.tsx` — add "Tests" section below "Related Symbols": list test files with links to navigate to the test symbol
-  - `src/ui/src/pages/Search.tsx` — add `coverageStatus` filter in the filter panel
-- `src/server/http-server.ts` — `GET /api/repos/:id/coverage?symbolId=...`
-- `src/ui/src/api/client.ts` — add `api.getCoverage(repoId, symbolId?)`
-
-**Key technical notes**:
-- This is a heuristic, not instrumented coverage (no Vitest/Jest integration required) — the goal is "does a test exist that references this symbol?" not "does the test actually execute this code path?"
-- Heuristic accuracy: TypeScript projects with co-located tests achieve ~85% accuracy. Flag this clearly in the UI: "Based on symbol references — not instrumented coverage"
-- `coverageStatus: 'unknown'` for symbols in files where no test heuristic applies (e.g. types, interfaces)
-- Update `buildTestMappings` incrementally on re-index (same as provider pattern)
-
-**Tests**: `test/core/test-mapper.test.ts`
-- Production symbol referenced in test file → `coverageStatus: 'tested'`
-- Symbol with no test references → `coverageStatus: 'untested'`
-- Interface/type → `coverageStatus: 'unknown'`
-- Fixture: `test/fixtures/basic-ts-project/` (already has test files)
-
-**Verify**:
-```bash
-npm run dev  # File tree should show coverage dots; SymbolView should show "Tests" section
-```
-
----
-
-## Task 166: Multi-Repo Workspace Panel
-
-Allow users to manage and search across multiple repos in the Web UI without navigating away from the current view.
-
-**Current state**: The Web UI is single-repo focused. Switching repos requires navigating to the repo list, selecting a different repo, and then navigating back. Cross-repo search from the UI is not possible.
-
-**Deliverables**:
-
-- `src/ui/src/components/WorkspacePanel.tsx` — new collapsible sidebar panel:
-  - Shows all indexed repos as a list with last-indexed date and symbol count
-  - Each repo can be pinned to a "workspace" (persisted in localStorage)
-  - Active workspace = set of pinned repos
-  - "Search all" button triggers cross-repo search across pinned repos
-- `src/ui/src/pages/Search.tsx` — update to support multi-repo mode:
-  - When workspace has > 1 repo, the repo selector becomes a multi-select
-  - Results show repo name badge on each result card
-  - `repoIds` passed to `api.searchSymbols()` (uses Task 150 cross-repo search)
-- `src/ui/src/stores/workspaceStore.ts` — Zustand store:
-  ```typescript
-  interface WorkspaceStore {
-    pinnedRepos: string[];
-    activeRepoId: string | null;
-    pin(repoId: string): void;
-    unpin(repoId: string): void;
-    setActive(repoId: string): void;
-  }
-  ```
-- `src/ui/src/App.tsx` — add workspace panel toggle button in the header (grid icon)
-- `src/ui/src/api/client.ts` — update `searchSymbols` to accept `repoIds?: string[]`
-
-**Key technical notes**:
-- Workspace is UI-only state (localStorage) — no server-side persistence needed
-- The `WorkspacePanel` opens as an overlay sidebar, not replacing the main content area
-- Repos with 0 symbols (failed index) should be visually distinct (gray with error icon)
-- Multi-repo search: use the cross-repo search endpoint from Task 150 — results include `repoName` badge
-
-**Tests**: `test/ui/workspacePanel.test.ts`
-- Pin/unpin repos persists to localStorage
-- Multi-select search sends `repoIds` array
-- Results include repo name badge
-- "Search all" triggers search across all pinned repos
-
-**Verify**:
-```bash
-npm run dev  # Pin 2 repos in the workspace panel, search — results should show from both repos
-```
-
----
-
-## Task 167: Advanced Dependency Graph
-
-Upgrade the existing dependency graph UI with filtering, clustering, minimap navigation, and path highlighting between two nodes.
-
-**Current state**: The dependency graph (`src/ui/src/pages/DependencyGraph.tsx`) shows a force-directed graph using React Flow. It supports focus mode and three layouts but lacks filtering, path highlighting, and navigation aids for large graphs.
-
-**Deliverables**:
-
-- `src/ui/src/components/GraphControls.tsx` — extend with:
-  - **Language filter**: dropdown to show only nodes of a specific language (`*.ts`, `*.py`, etc.)
-  - **Symbol kind filter**: show only files containing routes, or classes, etc.
-  - **Path highlighter**: two-node selector — click "From" + "From" on any node, then "Find Path" — highlights the shortest import path between them
-  - **Minimap**: small overview map (React Flow has built-in `<MiniMap>` component — enable it)
-  - **Cluster by directory**: group nodes into visual clusters by their parent directory
-- `src/ui/src/components/GraphViewer.tsx` — add path highlighting:
-  - BFS from source to target in the current adjacency map (client-side)
-  - Highlighted path: edges turn blue, non-path nodes dim to 20% opacity
-  - "Clear path" button to reset
-- `src/ui/src/components/GraphNode.tsx` — add:
-  - Quality indicator dot: colored ring around node based on heatmap score (if available)
-  - Churn indicator: pulsing animation for hotspot files
-- `src/server/http-server.ts` — no new endpoints needed (uses existing `/api/repos/:id/graph`)
-
-**Key technical notes**:
-- Path finding: BFS on the client-side adjacency map (already built in `GraphViewer`). For disconnected graphs, show "No path found" message
-- Clustering: React Flow supports node groups/subflows — group nodes by `path.dirname(filePath)` 
-- Minimap: React Flow's `<MiniMap>` is available — enable and style to match the theme
-- Performance: filter changes should re-render immediately — filter on client-side data, not re-fetch from server
-- The quality dot and churn pulsing should be opt-in (loaded only when heatmap data is available)
-
-**Tests**: `test/ui/advancedGraph.test.ts`
-- Language filter correctly hides non-matching nodes
-- Path highlighting finds shortest path in test graph
-- "No path found" message when nodes are disconnected
-- Minimap renders
-- Cluster mode groups nodes by directory
-
-**Verify**:
-```bash
-npm run dev  # Dependency graph → language filter → path highlight between two nodes
-```
-
----
-
-## Order of Execution
-
-```
-163 (heatmap)      ── requires Phase 25 Task 158 (quality metrics) and Phase 24 Task 157 (churn) to be useful
-164 (timeline)     ── requires Phase 24 Task 155 (symbol history) to be useful
-165 (test coverage) ── independent (test-mapper runs at index time)
-166 (multi-repo)   ── requires Phase 23 Task 150 (cross-repo search)
-167 (adv. graph)   ── independent (builds on existing graph UI)
-```
-
-Recommended sequence: 167 → 165 → 163 → 164 → 166 (so data from earlier phases is available when UI features land)
-
----
-
-## Phase 26 Completion
-
-**Before**: The Web UI is a capable browser. jCodeMunch has nothing comparable.
-
-**After**: The Web UI is a visual architecture intelligence dashboard. Risk is visible at a glance on the file tree. Symbol history is explorable without leaving the browser. Test coverage is overlaid. Multiple repos are navigable as a single workspace. Dependency paths are traceable with a click. This UI is not just "nice to have" — it's a product differentiator that makes PureContext accessible to non-agent users: architects, tech leads, and code reviewers.

package/docs/dev/PHASE27_TASKS.md

@@ -1,410 +0,0 @@
-# Phase 27 — Distribution & Platform
-
-**Goal**: Remove all friction from PureContext adoption. Let teams share pre-built indexes instantly, auto-reindex on every push, integrate with CI pipelines, browse popular open-source repos without indexing, and access PureContext from their editor without switching to the browser.
-
-**Scope rationale**: A tool with this much capability is only valuable if it's easy to adopt and stays up to date. jCodeMunch requires manual indexing and has no ecosystem integrations. This phase makes PureContext the ambient intelligence layer for any engineering team — always current, available everywhere, zero setup for common OSS repos.
-
----
-
-## Task 168: Index Export & Import
-
-Serialize a repo's index (SQLite rows + HNSW vectors) into a portable bundle that can be shared between team members, stored in CI artifacts, or loaded on a new machine.
-
-**Current state**: Indexes live in `~/.purecontext/indexes/` as SQLite databases. Sharing an index requires copying the raw SQLite file — fragile (path coupling), large (includes all repos in one DB), and undocumented.
-
-**Deliverables**:
-
-- `src/server/tools/export-index.ts` — new MCP tool:
-  ```typescript
-  interface ExportIndexInput {
-    repoId: string;
-    outputPath: string;      // Where to write the .pcx bundle
-    includeSource?: boolean; // Default true — include cached file content
-    includeVectors?: boolean; // Default true — include HNSW embeddings
-    compress?: boolean;       // Default true — gzip the bundle
-  }
-
-  interface ExportIndexOutput {
-    outputPath: string;
-    bundleSize: number;      // Bytes
-    symbolCount: number;
-    fileCount: number;
-    vectorCount: number;
-    repoId: string;
-    exportedAt: string;
-    _meta: ResponseMeta;
-  }
-  ```
-- `src/server/tools/import-index.ts` — new MCP tool:
-  ```typescript
-  interface ImportIndexInput {
-    bundlePath: string;      // Path to .pcx bundle
-    repoPath?: string;       // Override the stored root path (for new machines)
-    merge?: boolean;         // Default false — skip if repo already indexed
-  }
-
-  interface ImportIndexOutput {
-    repoId: string;
-    repoPath: string;
-    symbolCount: number;
-    fileCount: number;
-    alreadyExisted: boolean;
-    _meta: ResponseMeta;
-  }
-  ```
-- Bundle format (`.pcx` — PureContext index):
-  ```
-  header.json          — { version, repoId, repoPath, exportedAt, symbolCount }
-  symbols.json.gz      — Array of SymbolRecord
-  files.json.gz        — Array of FileRecord (with content if includeSource: true)
-  dep_edges.json.gz    — Array of DepEdge
-  vectors.bin.gz       — HNSW index binary (if includeVectors: true)
-  ```
-- Export: query all rows for the repo, serialize to the bundle format, gzip each section
-- Import: decompress, validate header version, upsert rows into local SQLite, load vectors into HNSW
-- Version compatibility: `header.version` must match current schema version; reject older incompatible bundles with a clear error
-- `src/config/cli.ts` — add CLI commands:
-  ```bash
-  npx purecontext-mcp export --repo /path/to/repo --out ./bundle.pcx
-  npx purecontext-mcp import --bundle ./bundle.pcx
-  ```
-
-**Key technical notes**:
-- The bundle is repo-scoped, not full-DB — one repo per bundle for granularity and shareability
-- `repoPath` override on import: needed when the bundle was created on a different machine. Stored root path in `repos` table is updated to the local path
-- Bundle size: for a 10k-file repo with embeddings, expect ~50MB uncompressed, ~15MB compressed
-- The `.pcx` format is versioned — document the schema so third-party tools can consume it
-
-**Tests**: `test/server/export-import.test.ts`
-- Export creates bundle at specified path
-- Import restores all symbols and files
-- `repoPath` override applied correctly on import
-- Version mismatch → clear error
-- `merge: false` → skip if repo exists
-- Round-trip: export then import produces identical symbol count
-
-**Verify**:
-```bash
-npx purecontext-mcp export --repo ./my-project --out /tmp/my-project.pcx
-# Copy to another machine or clone the repo fresh
-npx purecontext-mcp import --bundle /tmp/my-project.pcx
-```
-
----
-
-## Task 169: Pre-Built Index Registry
-
-Publish and serve pre-built indexes for the most popular open-source repositories so users can search them without indexing.
-
-**Current state**: Every user must index a repo before they can search it — even for projects like `expressjs/express` or `facebook/react` that thousands of PureContext users will all index independently.
-
-**Deliverables**:
-
-- `src/server/tools/fetch-public-index.ts` — new MCP tool:
-  ```typescript
-  interface FetchPublicIndexInput {
-    repo: string;           // "owner/repo" format (GitHub)
-    version?: string;       // Git tag or "latest" (default)
-    force?: boolean;        // Re-download even if cached
-  }
-
-  interface FetchPublicIndexOutput {
-    repoId: string;
-    repo: string;
-    version: string;
-    symbolCount: number;
-    cachedAt: string;
-    source: 'cache' | 'registry';
-    _meta: ResponseMeta;
-  }
-  ```
-- Registry URL: `https://registry.purecontext.dev/indexes/{owner}/{repo}/{version}.pcx`
-  - Served from a CDN (Cloudflare R2 or similar)
-  - `latest` resolves to the most recently published version
-- Download flow:
-  1. Check if repo already indexed locally
-  2. Fetch `.pcx` bundle from registry CDN
-  3. Import using Task 168's import logic
-  4. Mark repo as `source: 'registry'` in `repos` table
-- `src/config/cli.ts` — add:
-  ```bash
-  npx purecontext-mcp fetch expressjs/express
-  npx purecontext-mcp list-public  # List available pre-built indexes
-  ```
-- Registry manifest: `https://registry.purecontext.dev/manifest.json` — list of available repos + versions + bundle sizes
-- Initial corpus (publish as part of this task):
-  - `expressjs/express`, `fastify/fastify`, `nestjs/nest`
-  - `facebook/react`, `vuejs/core`, `angular/angular`
-  - `django/django`, `fastapi/fastapi`, `flask/flask`
-  - `golang/go` (stdlib), `tokio-rs/axum`, `spring-projects/spring-boot`
-
-**Key technical notes**:
-- Bundle signing: bundles in the registry should be signed (SHA-256 hash in manifest) and verified on download
-- CDN caching: bundles are immutable per `{repo}/{sha}.pcx` — cache forever. `latest` pointer changes on new publish
-- Update detection: check `repos.git_head` vs registry `latest_sha` — if behind, prompt user to refresh
-- Publishing pipeline: a separate GitHub Action runs on the PureContext infra, indexes popular repos nightly, publishes updated bundles. This is infrastructure work not in this task file
-- Privacy: only public repos are in the registry — no private repo content ever published
-
-**Tests**: `test/server/fetch-public-index.test.ts` (mocked CDN)
-- Download bundle from mocked registry URL
-- Signature verified before import
-- `source: 'registry'` set in repos table
-- Already cached → no re-download (unless `force: true`)
-- Unknown repo → clear error with link to registry manifest
-
-**Verify**:
-```bash
-npx purecontext-mcp fetch expressjs/express
-# Should download and import without cloning — search immediately available
-```
-
----
-
-## Task 170: Webhook Auto-Reindex
-
-HTTP endpoint that receives push webhooks from GitHub/GitLab/Bitbucket and automatically triggers re-indexing of the affected repo.
-
-**Current state**: Indexes go stale after code is pushed. Users must manually call `index_folder` or `index_repo` to refresh. In team environments with shared MCP servers (Phase 18), stale indexes are a usability problem.
-
-**Deliverables**:
-
-- `src/server/http-server.ts` — add webhook endpoint:
-  ```
-  POST /webhooks/github      — GitHub push webhook
-  POST /webhooks/gitlab      — GitLab push webhook
-  POST /webhooks/generic     — Generic JSON webhook
-  ```
-- `src/server/webhooks/github-webhook.ts`:
-  ```typescript
-  interface GitHubPushPayload {
-    ref: string;             // e.g. "refs/heads/main"
-    repository: { full_name: string; clone_url: string; };
-    head_commit: { id: string; };
-    commits: { added: string[]; modified: string[]; removed: string[]; }[];
-  }
-
-  async function handleGitHubPush(
-    payload: GitHubPushPayload,
-    secret: string
-  ): Promise<void>
-  ```
-- HMAC-SHA256 signature verification: GitHub sends `X-Hub-Signature-256` header — verify against configured `WEBHOOK_SECRET`
-- Reindex strategy:
-  1. Look up the repo by `repository.clone_url` or `full_name` in `repos` table
-  2. If found: extract changed file paths from the commits list; run `reindexFiles(repoId, changedPaths)` (incremental)
-  3. If not found: optionally auto-index (`AUTO_INDEX_ON_WEBHOOK=true` env var — default false)
-- GitLab webhook: analogous structure, different payload format; verify with `X-Gitlab-Token`
-- Generic webhook: `POST /webhooks/generic` with body `{ repoPath: string, changedFiles?: string[] }` — useful for custom CI scripts
-- `src/config/config-schema.ts` — add:
-  ```json
-  {
-    "webhooks": {
-      "enabled": true,
-      "secret": "${WEBHOOK_SECRET}",
-      "allowedRepos": ["owner/repo"],  // Optional allowlist
-      "autoIndex": false
-    }
-  }
-  ```
-
-**Key technical notes**:
-- Webhook handler runs the reindex in a non-blocking background task — respond `202 Accepted` immediately
-- Rate limit webhook triggers: max 1 reindex per repo per 60 seconds (debounce rapid pushes)
-- For Docker deployments (Phase 18), the webhook endpoint is already accessible via the HTTP server — just needs to be documented in the Docker setup guide
-- Security: never log the raw webhook payload (may contain sensitive commit messages); verify signature before processing any payload content
-
-**Tests**: `test/server/webhooks.test.ts`
-- GitHub push payload triggers reindex of matched repo
-- Invalid HMAC signature → 403, no reindex
-- Repo not found → 404 (or 202 + auto-index if enabled)
-- Rate limiting: second trigger within 60s → 202 but no reindex
-- GitLab payload parsed correctly
-
-**Verify**:
-```bash
-# Set up a GitHub webhook pointing to https://your-server/webhooks/github
-# Push a commit — the server should log "Incremental reindex triggered for repo X"
-```
-
----
-
-## Task 171: GitHub Actions Integration
-
-Publish a GitHub Actions composite action that indexes a repo, runs anti-pattern checks, posts a blast radius comment on PRs, and uploads the index bundle as an artifact.
-
-**Current state**: CI integration requires manually calling `npx purecontext-mcp` in shell steps. There is no ready-made GitHub Actions action, no PR comment automation, and no artifact upload.
-
-**Deliverables**:
-
-- `action.yml` — GitHub Actions composite action at repo root:
-  ```yaml
-  name: PureContext Analysis
-  description: Index codebase, detect anti-patterns, analyze PR impact
-  inputs:
-    token:
-      description: GitHub token for PR comments
-      required: true
-    anthropic-api-key:
-      description: Optional — enable AI summaries
-      required: false
-    analyze-diff:
-      description: Post blast radius comment on PR
-      default: 'true'
-    detect-antipatterns:
-      description: Fail CI on critical anti-patterns
-      default: 'false'
-    upload-index:
-      description: Upload .pcx bundle as workflow artifact
-      default: 'true'
-  runs:
-    using: composite
-    steps:
-      - name: Index repository
-        run: npx purecontext-mcp index-folder --path ${{ github.workspace }}
-      - name: Analyze diff (on PR)
-        if: github.event_name == 'pull_request' && inputs.analyze-diff == 'true'
-        run: npx purecontext-mcp analyze-diff --diff $(git diff ${{ github.base_ref }}..HEAD)
-      - name: Post PR comment
-        uses: actions/github-script@v7
-        # ... post the analyze-diff output as a PR comment
-      - name: Detect anti-patterns
-        if: inputs.detect-antipatterns == 'true'
-        run: npx purecontext-mcp detect-antipatterns --fail-on-critical
-      - name: Upload index bundle
-        if: inputs.upload-index == 'true'
-        uses: actions/upload-artifact@v4
-        with:
-          name: purecontext-index
-          path: '*.pcx'
-  ```
-- `src/config/cli.ts` — add CLI subcommands used by the action:
-  - `npx purecontext-mcp analyze-diff --diff <patch>` — prints JSON + exits non-zero on critical findings
-  - `npx purecontext-mcp detect-antipatterns --fail-on-critical` — exits non-zero if any `error` severity findings
-  - `npx purecontext-mcp export --auto` — exports current index to `{repoName}-{sha}.pcx`
-- PR comment template (markdown):
-  ```markdown
-  ## PureContext Analysis
-
-  **Impact Summary**: 3 symbols modified, blast radius: 7 files
-  **Review Priority**: 🔴 High (1 signature break detected)
-
-  | Symbol | Change | Blast Radius |
-  |--------|--------|--------------|
-  | `authenticate()` | Signature changed | 5 files |
-  | `parseToken()` | Modified | 2 files |
-
-  <details><summary>Anti-pattern findings (2 warnings)</summary>
-  ...
-  </details>
-  ```
-
-**Key technical notes**:
-- The action should work on both public and private repos — GitHub token is required only for posting PR comments
-- Cache the PureContext index between runs using `actions/cache` keyed on the repo SHA
-- `--fail-on-critical` should produce a non-zero exit code only for `severity: 'error'` findings, not warnings
-- Publish the action to the GitHub Marketplace: `purecontext/analyze-action`
-
-**Tests**: `test/cli/ci-commands.test.ts`
-- `analyze-diff` CLI produces correct JSON output
-- `detect-antipatterns --fail-on-critical` exits non-zero on errors
-- `export --auto` creates correctly named bundle
-
-**Verify**:
-```yaml
-# In a GitHub Actions workflow:
-- uses: purecontext/analyze-action@v1
-  with:
-    token: ${{ secrets.GITHUB_TOKEN }}
-    detect-antipatterns: 'true'
-```
-
----
-
-## Task 172: VS Code Extension
-
-A lightweight VS Code extension that surfaces PureContext inline — symbol outline in the sidebar, inline blast radius on hover, and quick-open search — without requiring users to switch to the browser UI.
-
-**Current state**: PureContext is accessible via the MCP protocol (AI agents) and the Web UI (browser). There is no native editor integration. Developers who want to browse the index while coding must switch contexts.
-
-**Deliverables**:
-
-- `vscode-extension/` — separate directory at project root (published separately as `purecontext.purecontext-vscode`):
-  ```
-  vscode-extension/
-  ├── package.json         — VS Code extension manifest
-  ├── src/
-  │   ├── extension.ts     — Activation, command registration
-  │   ├── client.ts        — HTTP client for PureContext server REST API
-  │   ├── providers/
-  │   │   ├── outline.ts   — TreeDataProvider: file outline in Explorer sidebar
-  │   │   ├── hover.ts     — HoverProvider: blast radius on symbol hover
-  │   │   └── search.ts    — QuickPick: symbol search (Cmd+Shift+P → "PureContext: Search")
-  │   └── views/
-  │       └── symbolPanel.ts — WebviewPanel: show symbol detail
-  └── README.md
-  ```
-- **Sidebar outline** (`TreeDataProvider`):
-  - Shows current file's symbols in the Explorer sidebar panel
-  - Click a symbol → jump to its line in the editor
-  - Symbols grouped by kind with icons
-- **Hover provider** (`HoverProvider`):
-  - On hover over a function/class name: show signature, summary, and "Blast radius: N files" badge
-  - Click the badge → open the Web UI blast radius page for that symbol
-- **Quick-open search** (VS Code QuickPick):
-  - Command palette: "PureContext: Search Symbols"
-  - Debounced input → results from `api.searchSymbols`
-  - Select result → jump to file + line
-- **Configuration** (`contributes.configuration`):
-  ```json
-  {
-    "purecontext.serverUrl": "http://localhost:3000",
-    "purecontext.repoId": "",   // Auto-detect if blank
-    "purecontext.enableHover": true,
-    "purecontext.enableOutline": true
-  }
-  ```
-- The extension communicates with PureContext via the existing REST API (`http-server.ts`) — no new server changes needed
-- Publish to VS Code Marketplace: `vsce package && vsce publish`
-
-**Key technical notes**:
-- The extension requires the PureContext server to be running (MCP server mode or `--server` flag from Phase 18)
-- Auto-detect `repoId`: use `GET /api/repos` and match against the open workspace folder path
-- No bundled Node.js or tree-sitter — the extension is purely a UI client over HTTP
-- Hover information is cached for 30 seconds per symbol to avoid hammering the server while the user is reading code
-- The extension should gracefully degrade when the server is not running (disable features, show status bar message "PureContext: offline")
-
-**Tests**: Manual testing only for this task (VS Code extension testing infrastructure is complex)
-- Sidebar outline shows correct symbols for a TypeScript file
-- Hover shows blast radius count
-- Quick-open search returns results in < 200ms
-
-**Verify**:
-```bash
-cd vscode-extension && npm install && npm run build
-# Install the VSIX in VS Code, open a PureContext-indexed project
-# Verify sidebar outline, hover, and search work
-```
-
----
-
-## Order of Execution
-
-```
-168 (export/import)       ── must come first — 169 and 171 depend on it
-169 (public registry)     ── depends on 168 (uses import logic)
-170 (webhook)             ── independent
-171 (GitHub Actions)      ── depends on 168 (uses export), benefits from 156 (analyze_diff)
-172 (VS Code extension)   ── independent (uses existing REST API)
-```
-
-Recommended sequence: 168 → 170 → 172 → 169 → 171
-
----
-
-## Phase 27 Completion
-
-**Before**: PureContext requires manual indexing, has no CI integration, no editor plugin, no way to share indexes, and no zero-setup path for popular OSS repos.
-
-**After**: Indexes are shareable artifacts. Popular OSS repos are available instantly from the registry. Every git push triggers an automatic reindex. CI pipelines get anti-pattern checks and PR impact comments. VS Code users get PureContext inline without a browser. The adoption barrier for a new team member drops from "set up and index" to "install and go."
-
-This is the distribution layer that turns a powerful tool into a platform — and positions PureContext as the standard for code intelligence in AI-native development workflows.