@mars167/git-ai 2.3.0

package/docs/zh-CN/troubleshooting.md

@@ -0,0 +1,19 @@
+# 排障
+
+## MCP 启动后无响应
+stdio server 正常行为是“等待客户端连接”。如果你在终端直接运行，看起来像卡住是正常的。
+
+## search_symbols/semantic_search 查不到结果
+- 先在仓库执行：`git-ai ai index --overwrite`（或仅更新变更：`git-ai ai index --incremental --staged`）
+- 如果你是通过 MCP 客户端启动且 cwd 不在仓库目录：
+  - MCP tools 的 `path` 为必传：每次 MCP tool 调用都显式传 `path: "/ABS/PATH/TO/REPO"`（保证调用原子性）
+
+## Windows / Linux 安装失败
+- Node 版本需 >= 18，且架构为 x64/arm64（LanceDB N-API 预编译包支持的范围）
+- 若报 `node-gyp` / 编译错误，通常来自 `tree-sitter` 系列原生扩展：
+  - Windows：安装 Visual Studio Build Tools（C++）与 Python
+  - Linux：安装 build-essential 与 python3
+
+## hooks 没生效
+- 运行 `git-ai ai hooks status` 确认 `core.hooksPath` 是 `.githooks`
+- 确认 `.githooks/*` 在 macOS/Linux 上有可执行权限

package/docs/zh-CN/windows-setup.md

@@ -0,0 +1,67 @@
+# Windows 开发与安装指引
+
+**简体中文** | [English](../windows-setup.md)
+
+本指引介绍如何在 Windows 上设置 `git-ai` 的开发环境，特别是针对多语言支持（C、Go、Python、Rust）。
+
+## 前置条件
+
+1.  **Node.js**: 从 [nodejs.org](https://nodejs.org/) 安装 Node.js (推荐 LTS 版本)。
+2.  **Git**: 从 [git-scm.com](https://git-scm.com/) 安装 Git for Windows。
+
+## 原生依赖构建工具
+
+`git-ai` 依赖以下包含原生绑定的库：
+*   `tree-sitter`: 用于代码解析 (C++)
+*   `cozo-node`: 图数据库引擎 (Rust/C++)
+
+虽然这些库通常提供预编译二进制包，但在某些环境（如 Node 版本不匹配或特定系统架构）下可能需要从源码编译。因此建议准备好编译环境。
+
+### 选项 1: 通过管理员 PowerShell 安装 (推荐)
+
+以管理员身份打开 PowerShell 并运行：
+
+```powershell
+npm install --global --production windows-build-tools
+```
+
+*注意：此包有时会过时或有问题。如果卡住或失败，请使用选项 2。*
+
+### 选项 2: 手动安装
+
+1.  **Python**: 从 [python.org](https://www.python.org/) 或 Microsoft Store 安装 Python 3。
+2.  **Visual Studio Build Tools**:
+    *   下载 [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)。
+    *   运行安装程序并选择 **"Desktop development with C++" (使用 C++ 的桌面开发)** 工作负载。
+    *   确保选中 "MSVC ... C++ x64/x86 build tools" 和 "Windows 10/11 SDK"。
+
+## 安装
+
+满足前置条件后：
+
+```bash
+git clone https://github.com/mars167/git-ai-cli.git
+cd git-ai-cli-v2
+npm install
+npm run build
+```
+
+## 运行示例
+
+要验证对不同语言的支持，可以运行解析测试：
+
+```bash
+npx ts-node test/verify_parsing.ts
+```
+
+要完整开发多语言示例，你可能需要安装各自的语言运行时：
+
+*   **C**: 安装 MinGW 或使用 MSVC (cl.exe)。
+*   **Go**: 从 [go.dev](https://go.dev/dl/) 安装。
+*   **Python**: [python.org](https://www.python.org/)。
+*   **Rust**: 通过 [rustup.rs](https://rustup.rs/) 安装。
+
+## 排障
+
+*   **node-gyp 错误**: 确保 Python 和 Visual Studio Build Tools 已正确安装并在 PATH 中。你可以配置 npm 使用特定 python 版本：`npm config set python python3`。
+*   **路径问题**: 如果全局运行，确保 `git-ai` 二进制文件或 `npm bin` 在你的 PATH 中。

package/install.sh

@@ -0,0 +1,183 @@
+#!/bin/bash
+#
+# git-ai Quick Install Script
+# 
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/mars167/git-ai-cli/main/install.sh | bash
+#
+# Or with options:
+#   curl -fsSL https://raw.githubusercontent.com/mars167/git-ai-cli/main/install.sh | bash -s -- --with-skill
+#
+# This script installs:
+#   1. git-ai CLI tool (via npm)
+#   2. Optionally: git-ai-mcp skill for AI agents
+#
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+BOLD='\033[1m'
+
+# Banner
+print_banner() {
+    echo -e "${CYAN}"
+    echo '   ____   _   _             _    ___ '
+    echo '  / ___| (_) | |_          / \  |_ _|'
+    echo ' | |  _  | | | __|  ___   / _ \  | | '
+    echo ' | |_| | | | | |_  |___| / ___ \ | | '
+    echo '  \____| |_|  \__|      /_/   \_\___|'
+    echo -e "${NC}"
+    echo -e "${BOLD}Semantic Code Understanding for AI Agents${NC}"
+    echo ""
+}
+
+# Logging functions
+info() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+success() {
+    echo -e "${GREEN}[OK]${NC} $1"
+}
+
+warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+    exit 1
+}
+
+# Check if command exists
+command_exists() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+# Parse arguments
+INSTALL_SKILL=false
+GLOBAL_INSTALL=true
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --with-skill|-s)
+            INSTALL_SKILL=true
+            shift
+            ;;
+        --local|-l)
+            GLOBAL_INSTALL=false
+            shift
+            ;;
+        --help|-h)
+            echo "Usage: install.sh [OPTIONS]"
+            echo ""
+            echo "Options:"
+            echo "  --with-skill, -s    Also install git-ai-mcp skill for AI agents"
+            echo "  --local, -l         Install locally instead of globally"
+            echo "  --help, -h          Show this help message"
+            exit 0
+            ;;
+        *)
+            warn "Unknown option: $1"
+            shift
+            ;;
+    esac
+done
+
+# Main installation
+main() {
+    print_banner
+    
+    # Check prerequisites
+    info "Checking prerequisites..."
+    
+    if ! command_exists node; then
+        error "Node.js is required but not installed. Please install Node.js 18+ first."
+    fi
+    
+    NODE_VERSION=$(node -v | cut -d'v' -f2 | cut -d'.' -f1)
+    if [ "$NODE_VERSION" -lt 18 ]; then
+        error "Node.js 18+ is required. Current version: $(node -v)"
+    fi
+    success "Node.js $(node -v) detected"
+    
+    if ! command_exists npm; then
+        error "npm is required but not installed."
+    fi
+    success "npm $(npm -v) detected"
+    
+    # Install git-ai
+    info "Installing git-ai CLI..."
+    
+    if [ "$GLOBAL_INSTALL" = true ]; then
+        npm install -g git-ai
+        success "git-ai installed globally"
+    else
+        npm install git-ai
+        success "git-ai installed locally"
+    fi
+    
+    # Verify installation
+    if command_exists git-ai; then
+        success "git-ai $(git-ai --version 2>/dev/null || echo 'installed')"
+    else
+        warn "git-ai command not found in PATH. You may need to restart your terminal."
+    fi
+    
+    # Install skill if requested
+    if [ "$INSTALL_SKILL" = true ]; then
+        info "Installing git-ai-mcp skill..."
+        
+        if ! command_exists npx; then
+            warn "npx not found. Skipping skill installation."
+        else
+            # Check if skills CLI is available
+            if npx skills --version >/dev/null 2>&1; then
+                npx skills add mars167/git-ai-cli@git-ai-mcp -g -y
+                success "git-ai-mcp skill installed"
+            else
+                info "Installing skills CLI..."
+                npx skills add mars167/git-ai-cli@git-ai-mcp -g -y
+                success "git-ai-mcp skill installed"
+            fi
+        fi
+    fi
+    
+    # Print next steps
+    echo ""
+    echo -e "${GREEN}${BOLD}Installation Complete!${NC}"
+    echo ""
+    echo -e "${BOLD}Quick Start:${NC}"
+    echo ""
+    echo "  1. Initialize index in your project:"
+    echo -e "     ${CYAN}cd your-project${NC}"
+    echo -e "     ${CYAN}git-ai ai index --overwrite${NC}"
+    echo ""
+    echo "  2. Search code semantically:"
+    echo -e "     ${CYAN}git-ai ai semantic \"user authentication\"${NC}"
+    echo ""
+    echo "  3. Analyze call graphs:"
+    echo -e "     ${CYAN}git-ai ai graph callers functionName${NC}"
+    echo ""
+    
+    if [ "$INSTALL_SKILL" = false ]; then
+        echo -e "${BOLD}For AI Agent Integration:${NC}"
+        echo ""
+        echo "  Install the MCP skill for Claude/Cursor/etc:"
+        echo -e "     ${CYAN}curl -fsSL https://raw.githubusercontent.com/mars167/git-ai-cli/main/install.sh | bash -s -- --with-skill${NC}"
+        echo ""
+    fi
+    
+    echo -e "${BOLD}Documentation:${NC}"
+    echo "  https://github.com/mars167/git-ai-cli"
+    echo ""
+}
+
+# Run main
+main

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@mars167/git-ai",
+  "version": "2.3.0",
+  "main": "dist/index.js",
+  "bin": {
+    "git-ai": "dist/bin/git-ai.js"
+  },
+  "directories": {
+    "doc": "docs"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "ts-node bin/git-ai.ts",
+    "test": "npm run build && node --test test/*.test.mjs test/*.test.ts",
+    "test:parser": "ts-node test/verify_parsing.ts"
+  },
+  "files": [
+    "dist/**",
+    "docs/**",
+    "assets/**",
+    "templates/**",
+    "skills/**",
+    "install.sh",
+    "README.md"
+  ],
+  "keywords": [
+    "git",
+    "ai",
+    "semantic-search",
+    "mcp",
+    "code-search",
+    "code-understanding",
+    "vector-search",
+    "graph-database",
+    "cli",
+    "code-indexing",
+    "knowledge-graph"
+  ],
+  "author": "mars167",
+  "license": "MIT",
+  "description": "A git-compatible CLI with AI indexing/search and an MCP server.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mars167/git-ai-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mars167/git-ai-cli/issues"
+  },
+  "homepage": "https://github.com/mars167/git-ai-cli#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/mars167"
+  },
+  "dependencies": {
+    "@lancedb/lancedb": "0.22.3",
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^25.0.9",
+    "apache-arrow": "18.1.0",
+    "commander": "^14.0.2",
+    "fs-extra": "^11.3.3",
+    "glob": "^13.0.0",
+    "onnxruntime-node": "^1.19.2",
+    "simple-git": "^3.30.0",
+    "tar": "^7.5.3",
+    "tree-sitter": "^0.21.1",
+    "tree-sitter-c": "^0.21.4",
+    "tree-sitter-go": "^0.21.2",
+    "tree-sitter-java": "^0.21.0",
+    "tree-sitter-python": "^0.21.0",
+    "tree-sitter-rust": "^0.21.0",
+    "tree-sitter-typescript": "^0.21.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "zod": "^4.3.5"
+  },
+  "optionalDependencies": {
+    "@lancedb/lancedb-darwin-arm64": "0.22.3",
+    "@lancedb/lancedb-darwin-x64": "0.22.3",
+    "@lancedb/lancedb-linux-arm64-gnu": "0.22.3",
+    "@lancedb/lancedb-linux-arm64-musl": "0.22.3",
+    "@lancedb/lancedb-linux-x64-gnu": "0.22.3",
+    "@lancedb/lancedb-linux-x64-musl": "0.22.3",
+    "@lancedb/lancedb-win32-arm64-msvc": "0.22.3",
+    "@lancedb/lancedb-win32-x64-msvc": "0.22.3",
+    "cozo-lib-wasm": "^0.7.6",
+    "cozo-node": "^0.7.6"
+  }
+}

package/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/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` |