Merge pull request #27 from mars167/feat/code-context-engine-runtime

feat: introduce code context runtime foundation

Author: mars167

AGENTS.md

@@ -1,87 +1,68 @@
-# PROJECT KNOWLEDGE BASE
+# Code Context Engine Knowledge Base
 
-**Generated:** 2026-02-02 01:45
-**Commit:** bd3baf8
-**Branch:** refactor/cli-commands-architecture
+## Overview
 
-## OVERVIEW
-git-ai CLI + MCP server. TypeScript implementation for AI-powered Git operations with semantic search and graph-based code analysis. Indices stored in `.git-ai/`.
+Code Context Engine is a TypeScript local runtime for agent-oriented code retrieval and context construction. The runtime is the product core. CLI and MCP are thin adapters retained only where they help local debugging or agent integration.
 
-## STRUCTURE
-```
-git-ai-cli-v2/
-├── src/
-│   ├── cli/          # CLI command architecture (NEW: registry + handlers + schemas)
-│   │   ├── types.ts        # Core types, executeHandler
-│   │   ├── registry.ts     # Handler registry (20 commands)
-│   │   ├── helpers.ts      # Shared utilities
-│   │   ├── schemas/        # Zod validation schemas
-│   │   ├── handlers/       # Business logic handlers
-│   │   └── commands/       # Commander.js wrappers
-│   ├── commands/     # Command aggregator (ai.ts only)
-│   ├── core/         # Indexing, graph, storage, parsers
-│   └── mcp/          # MCP server implementation
-├── test/             # Node test runner tests
-├── dist/             # Build output
-└── .git-ai/          # Indices (LanceDB)
+## Structure
+
+```text
+src/
+  index.ts                 public runtime entry
+  domain/                  stable agent-facing contracts
+  retrieval/
+    runtime.ts             createCodeContextEngine()
+    lexical/               lexical-first retrieval
+    symbol/                higher-level navigation capabilities
+  tasks/
+    review/                review context builders
+    impact/                impact analysis
+    tests/                 test discovery and mapping
+    implementation/        implementation context
+    extensions/            extension point discovery
+    diff/                  diff parsing and analysis
+  core/                    parsers, indexers, LanceDB, CozoDB, repo-map
+  cli/                     thin local adapter
+  commands/                ai command aggregation
+  mcp/                     thin MCP adapter
+bin/
+  code-context-engine.ts   package CLI entry
 ```
 
-## WHERE TO LOOK
-| Task | Location |
+## Where To Look
+
+| Need | Location |
 |------|----------|
-| CLI commands | `src/cli/commands/*.ts` (new architecture) |
-| CLI handlers | `src/cli/handlers/*.ts` (business logic) |
-| CLI schemas | `src/cli/schemas/*.ts` (Zod validation) |
-| Handler registry | `src/cli/registry.ts` (all 20 commands) |
-| Command aggregator | `src/commands/ai.ts` (entry point) |
-| Indexing logic | `src/core/indexer.ts`, `src/core/indexerIncremental.ts` |
-| Graph queries | `src/core/cozo.ts`, `src/core/astGraph.ts` |
-| Semantic search | `src/core/semantic.ts`, `src/core/sq8.ts` |
-| Repo map | `src/core/repoMap.ts` |
-| MCP tools | `src/mcp/`, `src/core/graph.ts` |
-| Language parsers | `src/core/parser/*.ts` |
+| Runtime API | `src/index.ts`, `src/retrieval/runtime.ts` |
+| Stable contracts | `src/domain/*.ts` |
+| Lexical retrieval | `src/retrieval/lexical/*.ts` |
+| Symbol navigation | `src/retrieval/symbol/*.ts` |
+| Task builders | `src/tasks/**/*` |
+| MCP thin adapter | `src/mcp/server.ts`, `src/mcp/tools/taskTools.ts`, `src/mcp/handlers/taskHandlers.ts` |
+| CLI thin adapter | `src/commands/ai.ts`, `src/cli/commands/*` |
+| Core indexing and graph | `src/core/*` |
 
-## CODE MAP
-| Symbol | Type | Location | Role |
-|--------|------|----------|------|
-| `indexer` | fn | `core/indexer.ts` | Full repository indexing |
-| `incrementalIndexer` | fn | `core/indexerIncremental.ts` | Incremental updates |
-| `GitAiService` | class | `mcp/index.ts` | MCP entry point |
-| `cozoQuery` | fn | `core/cozo.ts` | Graph DB queries |
-| `semanticSearch` | fn | `core/semantic.ts` | Vector similarity |
-| `repoMap` | fn | `core/repoMap.ts` | PageRank-based repo overview |
-| `resolveGitRoot` | fn | `core/git.ts` | Repo boundary detection |
+## Primary Entry Points
 
-## CONVENTIONS
-- **strict: true** TypeScript - no implicit any
-- **Imports**: Node built-ins → external deps → internal modules
-- **Formatting**: 2 spaces, single quotes, trailing commas
-- **Errors**: Structured JSON logging via `createLogger`
-- **CLI output**: JSON on stdout, logs on stderr
-- **External inputs**: Use `unknown`, narrow early
+- `createCodeContextEngine()` is the main product entry point.
+- `code-context-engine ai serve` starts the thin MCP adapter.
+- `code-context-engine ai index --overwrite` rebuilds local index state.
 
-## ANTI-PATTERNS (THIS PROJECT)
-- Never suppress type errors (`as any`, `@ts-ignore`)
-- Never throw raw strings - throw `Error` objects
-- Never commit without explicit request
-- No empty catch blocks
+## Thin MCP Surface
 
-## UNIQUE STYLES
-- `.git-ai/` directory for all index data (not config files)
-- MCP tools require explicit `path` argument
-- Multi-language parser architecture (TS, Go, Rust, Python, C, Markdown, YAML)
-- PageRank-based repo-map for code importance scoring
+- `check_index`
+- `rebuild_index`
+- `read_file`
+- `repo_map`
+- `lexical_search`
+- `implementation_context`
+- `find_tests`
+- `find_impact`
+- `find_extension_points`
+- `review_context_for_diff`
 
-## COMMANDS
-```bash
-npm i              # Install dependencies
-npm run build      # Build to dist/
-npm run start      # Dev run (e.g., --help)
-npm test           # Build + node --test
-node dist/bin/git-ai.js --help  # Validate packaged output
-```
+## Retrieval Policy
 
-## NOTES
-- Indices auto-update on git operations
-- `checkIndex` gates symbol/semantic/graph queries
-- MCP server exposes git-ai tools for external IDEs
+- lexical / symbol first
+- graph expand second
+- semantic rerank last