@mars167/git-ai 2.3.0

package/skills/git-ai-mcp/references/tools.md

@@ -0,0 +1,263 @@
+# git-ai MCP Tools Reference
+
+Complete documentation for all git-ai MCP tools.
+
+## Index Management
+
+### check_index
+
+Check if repository index is ready and compatible.
+
+```js
+check_index({ path: "/abs/path/to/repo" })
+```
+
+**Returns:** Index status, compatibility info, and recommendations.
+
+**When to use:** Before any search or graph operation.
+
+### rebuild_index
+
+Rebuild the repository index from scratch.
+
+```js
+rebuild_index({ path: "/abs/path/to/repo" })
+```
+
+**Parameters:**
+- `path` (required): Absolute path to repository root
+- `overwrite` (optional): Whether to overwrite existing index (default: true)
+- `dim` (optional): Vector dimension (default: 256)
+
+**Note:** Can be slow for large repositories. Use when index is missing or incompatible.
+
+### pack_index / unpack_index
+
+Package index for storage or distribution.
+
+```js
+pack_index({ path: "/repo", lfs: true })  // Pack with LFS tracking
+unpack_index({ path: "/repo" })            // Restore from archive
+```
+
+## Search Tools
+
+### repo_map
+
+Get a high-level overview of repository structure.
+
+```js
+repo_map({
+  path: "/abs/path/to/repo",
+  max_files: 20,      // Top files by importance
+  max_symbols: 5      // Top symbols per file
+})
+```
+
+**When to use:** First contact with a repository, before large changes.
+
+### search_symbols
+
+Search for symbols by name pattern.
+
+```js
+search_symbols({
+  path: "/repo",
+  query: "handleRequest",
+  mode: "substring",   // substring | prefix | wildcard | regex | fuzzy
+  limit: 50,
+  case_insensitive: false
+})
+```
+
+**Modes:**
+- `substring`: Match anywhere in name (default)
+- `prefix`: Match start of name
+- `wildcard`: Use `*` and `?` wildcards
+- `regex`: Full regex support
+- `fuzzy`: Typo-tolerant matching
+
+### semantic_search
+
+Search code by meaning using vector similarity.
+
+```js
+semantic_search({
+  path: "/repo",
+  query: "user authentication and session management",
+  topk: 10,
+  lang: "auto"  // auto | all | java | ts
+})
+```
+
+**When to use:** Understanding functional intent, finding conceptually related code.
+
+## AST Graph Tools
+
+### ast_graph_find
+
+Find symbols by name prefix in the AST graph.
+
+```js
+ast_graph_find({
+  path: "/repo",
+  prefix: "handle",
+  limit: 50
+})
+```
+
+### ast_graph_callers
+
+Find all functions that call a given function.
+
+```js
+ast_graph_callers({
+  path: "/repo",
+  name: "authenticateUser",
+  limit: 200
+})
+```
+
+**When to use:** Impact analysis before refactoring, understanding usage patterns.
+
+### ast_graph_callees
+
+Find all functions called by a given function.
+
+```js
+ast_graph_callees({
+  path: "/repo",
+  name: "processOrder",
+  limit: 200
+})
+```
+
+**When to use:** Understanding implementation details, dependency analysis.
+
+### ast_graph_chain
+
+Trace complete call chain in either direction.
+
+```js
+ast_graph_chain({
+  path: "/repo",
+  name: "handlePayment",
+  direction: "downstream",  // downstream | upstream
+  max_depth: 3,
+  limit: 500
+})
+```
+
+**Directions:**
+- `downstream`: What does this function call? (implementation details)
+- `upstream`: Who calls this function? (usage/impact)
+
+**When to use:** Complex flow analysis, understanding system architecture.
+
+### ast_graph_children
+
+List direct children in AST containment (file → symbols, class → methods).
+
+```js
+ast_graph_children({
+  path: "/repo",
+  id: "src/auth/service.ts",
+  as_file: true  // Treat id as file path
+})
+```
+
+### ast_graph_refs
+
+Find all references to a name (calls, new expressions, type references).
+
+```js
+ast_graph_refs({
+  path: "/repo",
+  name: "UserService",
+  limit: 200
+})
+```
+
+## DSR Tools (Deterministic Semantic Records)
+
+### dsr_context
+
+Get repository Git context and DSR directory state.
+
+```js
+dsr_context({ path: "/repo" })
+```
+
+**Returns:** Branch info, commit status, DSR availability.
+
+### dsr_generate
+
+Generate DSR for a specific commit.
+
+```js
+dsr_generate({
+  path: "/repo",
+  commit: "HEAD"  // or specific commit hash
+})
+```
+
+**When to use:** Before querying history for commits without DSR.
+
+### dsr_symbol_evolution
+
+Track how a symbol changed over time.
+
+```js
+dsr_symbol_evolution({
+  path: "/repo",
+  symbol: "authenticateUser",
+  limit: 50,
+  contains: false,  // true for substring match
+  all: false        // true to traverse all refs, not just HEAD
+})
+```
+
+**Returns:** List of changes with:
+- `commit`: Commit hash
+- `operation`: add | modify | delete | rename
+- `risk_level`: low | medium | high
+- `details`: Change description
+
+**When to use:** Understanding design evolution, finding when/why something changed.
+
+### dsr_rebuild_index
+
+Rebuild DSR index from DSR files.
+
+```js
+dsr_rebuild_index({ path: "/repo" })
+```
+
+## File Operations
+
+### read_file
+
+Read file content with optional line range.
+
+```js
+read_file({
+  path: "/repo",
+  file: "src/auth/service.ts",  // Relative to repo root
+  start_line: 1,
+  end_line: 200
+})
+```
+
+**Best practice:** Use with `start_line`/`end_line` for large files.
+
+### list_files
+
+List repository files by glob pattern.
+
+```js
+list_files({
+  path: "/repo",
+  pattern: "src/**/*.ts",
+  limit: 500
+})
+```

package/templates/agents/common/documents/Fix EISDIR error and enable multi-language indexing.md

@@ -0,0 +1,14 @@
+The user encountered an `EISDIR: illegal operation on a directory, read` error when running `git-ai ai index`. This is caused by the file globbing logic inadvertently matching directories (likely due to a directory name matching the file extension pattern or default glob behavior), and then trying to read them as files.
+
+Additionally, the current indexer implementation (`src/core/indexer.ts` and `src/core/lancedb.ts`) only supports `java` and `ts`, missing the newly added languages (C, Go, Python, PHP, Rust).
+
+I will fix the error and enable full multi-language support by:
+
+1.  **Updating `src/core/lancedb.ts`**: Expand the `IndexLang` type and `ALL_INDEX_LANGS` array to include `c`, `go`, `python`, `php`, and `rust`.
+2.  **Updating `src/core/indexer.ts`**:
+    *   Modify the `glob` pattern to include extensions for all supported languages (`.c`, `.h`, `.go`, `.py`, `.php`, `.rs`).
+    *   **Crucial Fix**: Add `nodir: true` to the `glob` options to ensure only files are returned, preventing the `EISDIR` error.
+    *   Update `inferIndexLang` to correctly map file extensions to the new `IndexLang` types.
+    *   Add an extra `fs.stat` check before parsing as a safety net.
+
+This will resolve the crash and enable indexing for the full polyglot stack.

package/templates/agents/common/documents/Fix git-ai index error in CodaGraph directory.md

@@ -0,0 +1,13 @@
+The error is caused by `ts-node` (running in development mode) failing to find type definitions for `tree-sitter-php` when executed from the `CodaGraph` directory. This happens because `tree-sitter-php` (v0.20.0) does not include built-in TypeScript definitions, unlike the other language parsers (C, Go, Python, Rust) which are newer versions (v0.21+) or include types.
+
+Although `src/modules.d.ts` exists, `ts-node` is not picking it up correctly in this execution context.
+
+I will fix this by:
+1.  Explicitly referencing the type declaration file in `src/core/parser/php.ts` using a triple-slash directive. This ensures TypeScript always loads the definitions regardless of the working directory.
+2.  Updating `src/modules.d.ts` to remove unnecessary declarations for other languages (C, Go, Python, Rust) since they already provide official types, keeping only the necessary one for PHP.
+3.  Verifying the fix by running the index command again.
+
+Implementation Steps:
+1.  **Edit `src/core/parser/php.ts`**: Add `/// <reference path="../../modules.d.ts" />` to the top of the file.
+2.  **Edit `src/modules.d.ts`**: Remove declarations for C, Go, Python, and Rust; keep only `tree-sitter-php`.
+3.  **Verify**: Run the index command in the `CodaGraph` directory to confirm success.

package/templates/agents/common/skills/git-ai-mcp/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: git-ai-mcp
+description: |
+  Efficient codebase understanding and navigation using git-ai MCP tools. Use when working with code repositories that have git-ai indexed, including: (1) Understanding project structure and architecture, (2) Searching for symbols, functions, or semantic concepts, (3) Analyzing code relationships and call graphs, (4) Tracking symbol evolution and change history via DSR, (5) Reading and navigating code files. Triggers: "understand this project", "find function X", "who calls X", "what does X call", "history of X", "where is X implemented".
+---
+
+# git-ai MCP Skill
+
+Guide for using git-ai MCP tools to understand and navigate codebases efficiently.
+
+## Overview
+
+git-ai provides semantic code understanding through:
+
+- **Hyper RAG**: Vector + Graph + DSR retrieval
+- **AST Analysis**: Symbol relationships and call graphs
+- **DSR**: Deterministic Semantic Records for change tracking
+
+## Workflow
+
+Understanding a codebase involves these steps:
+
+1. Get global view (run `repo_map`)
+2. Check index status (run `check_index`, rebuild if needed)
+3. Locate code (run `search_symbols` or `semantic_search`)
+4. Analyze relationships (run `ast_graph_callers/callees/chain`)
+5. Trace history (run `dsr_symbol_evolution`)
+6. Read code (run `read_file`)
+
+## Tool Selection
+
+| Task | Tool | Key Parameters |
+|------|------|----------------|
+| Project overview | `repo_map` | `path`, `max_files: 20` |
+| Find by name | `search_symbols` | `path`, `query`, `mode: substring` |
+| Find by meaning | `semantic_search` | `path`, `query`, `topk: 10` |
+| Who calls X | `ast_graph_callers` | `path`, `name` |
+| What X calls | `ast_graph_callees` | `path`, `name` |
+| Call chain | `ast_graph_chain` | `path`, `name`, `direction`, `max_depth` |
+| Symbol history | `dsr_symbol_evolution` | `path`, `symbol`, `limit` |
+| Read code | `read_file` | `path`, `file`, `start_line`, `end_line` |
+| Index health | `check_index` | `path` |
+| Rebuild index | `rebuild_index` | `path` |
+
+## Critical Rules
+
+**MUST follow:**
+
+1. **Always pass `path` explicitly** - Never rely on implicit working directory
+2. **Check index before search** - Run `check_index` before using search/graph tools
+3. **Read before modify** - Use `read_file` to understand code before making changes
+4. **Use DSR for history** - Never manually parse git log; use `dsr_symbol_evolution`
+
+**NEVER do:**
+
+- Assume symbol locations without searching
+- Modify files without reading them first
+- Search when index is missing or incompatible
+- Ignore DSR risk levels (high risk = extra review needed)
+
+## Examples
+
+**Find authentication code:**
+```js
+semantic_search({ path: "/repo", query: "user authentication logic", topk: 10 })
+```
+
+**Find who calls a function:**
+```js
+ast_graph_callers({ path: "/repo", name: "handleRequest", limit: 50 })
+```
+
+**Trace call chain upstream:**
+```js
+ast_graph_chain({ path: "/repo", name: "processOrder", direction: "upstream", max_depth: 3 })
+```
+
+**View symbol history:**
+```js
+dsr_symbol_evolution({ path: "/repo", symbol: "authenticateUser", limit: 50 })
+```
+
+## References
+
+- **Tool details**: See [references/tools.md](references/tools.md) for complete tool documentation
+- **Constraints**: See [references/constraints.md](references/constraints.md) for behavioral rules

package/templates/agents/common/skills/git-ai-mcp/references/constraints.md

@@ -0,0 +1,143 @@
+# git-ai MCP Behavioral Constraints
+
+Rules and constraints for using git-ai MCP tools effectively and safely.
+
+## Must-Follow Rules (Error Level)
+
+### 1. explicit_path
+
+**Rule:** Every MCP tool call MUST include an explicit `path` parameter.
+
+**Why:** Ensures atomic, reproducible calls. Never rely on process state or working directory.
+
+**Good:**
+```js
+search_symbols({ path: "/abs/path/to/repo", query: "handleRequest" })
+```
+
+**Bad:**
+```js
+search_symbols({ query: "handleRequest" })  // Missing path!
+```
+
+### 2. check_index_first
+
+**Rule:** Before using `search_symbols`, `semantic_search`, or any `ast_graph_*` tool, MUST call `check_index` to verify index is ready.
+
+**Why:** These tools depend on the index. Searching with a missing/incompatible index gives unreliable results.
+
+**Workflow:**
+```js
+// Step 1: Check index
+const status = check_index({ path: "/repo" })
+
+// Step 2: Rebuild if needed
+if (!status.compatible) {
+  rebuild_index({ path: "/repo" })
+}
+
+// Step 3: Now safe to search
+search_symbols({ path: "/repo", query: "..." })
+```
+
+### 3. understand_before_modify
+
+**Rule:** Before modifying any file, MUST:
+1. Use `search_symbols` to locate the code
+2. Use `read_file` to understand the implementation
+3. Use `ast_graph_callers` to assess impact
+4. Only then make changes
+
+**Why:** Prevents breaking changes and ensures informed modifications.
+
+### 4. use_dsr_for_history
+
+**Rule:** When tracing symbol history, MUST use `dsr_symbol_evolution`. NEVER manually parse git log or diff.
+
+**Why:** DSR provides structured, semantic change information that raw git commands don't.
+
+## Warning-Level Rules
+
+### 5. repo_map_before_large_change
+
+**Rule:** Before large refactoring or architectural changes, use `repo_map` to understand project structure.
+
+**Why:** Provides context for planning changes and identifying affected areas.
+
+### 6. respect_dsr_risk
+
+**Rule:** When DSR reports `risk_level: high`, exercise extra caution. Operations like `delete` and `rename` require additional review.
+
+**Risk levels:**
+- `low`: Safe, routine changes
+- `medium`: Review recommended
+- `high`: Extra scrutiny required
+
+## Recommended Practices
+
+### prefer_semantic_search
+
+For understanding functional intent, prefer `semantic_search` over `search_symbols`.
+
+**Use `semantic_search` when:**
+- Looking for conceptual functionality
+- Query is in natural language
+- Exact name is unknown
+
+**Use `search_symbols` when:**
+- Exact or partial name is known
+- Looking for specific identifiers
+
+### use_call_chain_for_complex_flow
+
+For complex flows spanning multiple functions, use `ast_graph_chain` instead of manually chaining `callers`/`callees` calls.
+
+```js
+// Good: Single call for complete chain
+ast_graph_chain({ path: "/repo", name: "processPayment", direction: "upstream", max_depth: 5 })
+
+// Avoid: Manual recursive calls
+ast_graph_callers({ path: "/repo", name: "processPayment" })
+// then for each result...
+ast_graph_callers({ path: "/repo", name: result.name })
+// etc.
+```
+
+### incremental_dsr_generation
+
+Generate DSR on-demand for specific commits rather than batch-generating for entire history.
+
+```js
+// Good: Generate for specific commit when needed
+dsr_generate({ path: "/repo", commit: "abc123" })
+
+// Avoid: Generating for all historical commits upfront
+```
+
+## Prohibited Actions
+
+| Action | Reason |
+|--------|--------|
+| Assume symbol location without searching | Always confirm via search |
+| Modify unread files | Must read and understand first |
+| Manual git log parsing for history | Use DSR tools instead |
+| Search with missing index | Rebuild index first |
+| Ignore high risk DSR warnings | Requires extra review |
+| Omit `path` parameter | Every call must be explicit |
+
+## Tool-Specific Constraints
+
+| Tool | Precondition | Required Params |
+|------|--------------|-----------------|
+| `repo_map` | None | `path` |
+| `check_index` | None | `path` |
+| `rebuild_index` | None | `path` |
+| `search_symbols` | `check_index` passed | `path`, `query` |
+| `semantic_search` | `check_index` passed | `path`, `query` |
+| `ast_graph_callers` | `check_index` passed | `path`, `name` |
+| `ast_graph_callees` | `check_index` passed | `path`, `name` |
+| `ast_graph_chain` | `check_index` passed | `path`, `name` |
+| `dsr_context` | None | `path` |
+| `dsr_generate` | None | `path`, `commit` |
+| `dsr_symbol_evolution` | DSR exists for commits | `path`, `symbol` |
+| `read_file` | None | `path`, `file` |