open-codebase-index 0.21.0-bootstrap.0

package/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "printf '\nFor repository questions, use index_status when readiness is unknown, then call codebase_context before shell search, grep, or broad file reads. Pass symbol for definitions or from+to for dependency paths; use specialized lookup and graph tools afterward.\\n'",
+            "commandWindows": "Write-Output 'For repository questions, use index_status when readiness is unknown, then call codebase_context before shell search, grep, or broad file reads. Pass symbol for definitions or from+to for dependency paths; use specialized lookup and graph tools afterward.'",
+            "statusMessage": "Codebase Index ready"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,147 @@
+{
+  "name": "open-codebase-index",
+  "version": "0.21.0-bootstrap.0",
+  "description": "Host-neutral semantic codebase search with embeddings, symbol discovery, and call-graph tooling",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "bin": {
+    "open-codebase-index-mcp": "dist/cli.js",
+    "opencode-codebase-index-mcp": "dist/cli.js"
+  },
+  "license": "MIT",
+  "author": "Kenneth",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Helweg/opencode-codebase-index"
+  },
+  "keywords": [
+    "semantic-search",
+    "codebase-indexing",
+    "vector-search",
+    "embeddings",
+    "tree-sitter",
+    "ai-coding",
+    "agent-extensions",
+    "pi-package",
+    "pi"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "npm run build:ts && npm run build:native",
+    "build:ts": "tsup && node scripts/smoke-test-built-cli.mjs",
+    "build:native": "cd native && cargo build --release && napi build --release --platform",
+    "build:native:all": "cd native && napi build --release --platform --target x86_64-apple-darwin --target aarch64-apple-darwin --target x86_64-unknown-linux-gnu --target aarch64-unknown-linux-gnu --target x86_64-pc-windows-msvc",
+    "visualize": "node dist/cli.js visualize",
+    "dev": "tsup --watch",
+    "eval": "npx tsx src/cli.ts eval run",
+    "eval:agent": "npx tsx src/cli.ts eval run --dataset benchmarks/golden/agent-context.json",
+    "eval:representative": "npx tsx src/cli.ts eval run --dataset benchmarks/golden/representative.json",
+    "eval:agent:ci": "npx tsx src/cli.ts eval run --dataset benchmarks/golden/agent-context.json --reindex --ci --budget benchmarks/budgets/agent-context.json",
+    "eval:smoke": "npx tsx src/cli.ts eval run --config .github/eval-config.json --reindex --dataset benchmarks/golden/small.json",
+    "eval:ci": "npx tsx src/cli.ts eval run --reindex --ci --budget benchmarks/budgets/default.json --against benchmarks/baselines/eval-baseline-summary.json",
+    "eval:ci:ollama": "npx tsx src/cli.ts eval run --config .github/eval-ollama-config.json --reindex --ci --budget benchmarks/budgets/default.json --against benchmarks/baselines/eval-baseline-summary.json",
+    "eval:compare": "npx tsx src/cli.ts eval compare",
+    "eval:effectiveness": "npx tsx scripts/effectiveness-report.ts",
+    "dev:link-mcp": "node scripts/link-local-mcp-bin.mjs",
+    "test": "vitest",
+    "pretest:run": "node scripts/run-build-native-with-rustflags.mjs",
+    "test:run": "vitest run",
+    "pretest:coverage": "node scripts/run-build-native-with-rustflags.mjs",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "THIRD_PARTY_LICENSES.md",
+    "native/*.node",
+    "skill",
+    "commands",
+    "scripts/link-local-mcp-bin.mjs",
+    ".codex-plugin",
+    ".claude-plugin",
+    ".mcp.json",
+    "skills",
+    "hooks"
+  ],
+  "napi": {
+    "binaryName": "codebase-index-native",
+    "targets": [
+      "x86_64-apple-darwin",
+      "aarch64-apple-darwin",
+      "x86_64-unknown-linux-gnu",
+      "aarch64-unknown-linux-gnu",
+      "x86_64-pc-windows-msvc"
+    ]
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opencode-ai/plugin": "~1.3.13",
+    "chokidar": "^5.0.0",
+    "ignore": "^7.0.5",
+    "p-queue": "^9.1.1",
+    "p-retry": "^7.1.1",
+    "tiktoken": "^1.0.15",
+    "typebox": "^1.3.2",
+    "unicode-case-folding": "1.1.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.82.0",
+    "@eslint/js": "^9.39.4",
+    "@napi-rs/cli": "^3.6.0",
+    "@types/node": "^25.5.2",
+    "@vitest/coverage-v8": "^4.1.2",
+    "eslint": "^9.39.4",
+    "tsup": "^8.1.0",
+    "tsx": "^4.23.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.58.0",
+    "vitest": "^4.1.2"
+  },
+  "overrides": {
+    "@hono/node-server": "2.0.10",
+    "brace-expansion": "5.0.8",
+    "express-rate-limit": "8.5.2",
+    "fast-uri": "3.1.4",
+    "hono": "4.12.27",
+    "ip-address": "10.2.0",
+    "postcss": "8.5.18",
+    "qs": "6.15.2",
+    "vite": "8.0.16",
+    "esbuild": "0.28.1",
+    "body-parser": "2.3.0",
+    "js-yaml": "4.3.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@opencode-ai/plugin": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opencode-ai/plugin": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "pi": {
+    "extensions": [
+      "./dist/pi-extension.js"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/scripts/link-local-mcp-bin.mjs

@@ -0,0 +1,25 @@
+import { existsSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "fs";
+import { dirname, relative, resolve } from "path";
+import { fileURLToPath } from "url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const cliPath = resolve(root, "dist/cli.js");
+const binDir = resolve(root, "node_modules/.bin");
+const binPath = resolve(binDir, "opencode-codebase-index-mcp");
+
+if (!existsSync(cliPath)) {
+  console.error("dist/cli.js is missing. Run `npm run build:ts` first.");
+  process.exit(1);
+}
+
+mkdirSync(binDir, { recursive: true });
+rmSync(binPath, { force: true });
+rmSync(`${binPath}.cmd`, { force: true });
+
+if (process.platform === "win32") {
+  writeFileSync(`${binPath}.cmd`, `@echo off\r\nnode "%~dp0\\..\\..\\dist\\cli.js" %*\r\n`, "utf-8");
+} else {
+  symlinkSync(relative(dirname(binPath), cliPath), binPath);
+}
+
+console.log(`Linked ${binPath} -> ${cliPath}`);

package/skill/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: codebase-search
+description: Semantic code and documentation search by meaning. Use codebase_peek to find WHERE code is (saves tokens), codebase_search to see actual code. For exact identifiers, use grep instead. Search local codebase before using websearch for code/library/API/example questions.
+---
+
+# Codebase Search Skill
+
+## Important: Indexed Content
+
+The indexed codebase contains **two types of content**:
+
+1. **Project Source Code** — all code files in the current workspace
+2. **Knowledge Base Documentation** — external documentation, usage guides, API references, and example programs added via `add_knowledge_base`
+
+## When to Use What
+
+| Scenario | Tool | Why |
+|----------|------|-----|
+| Code/library/API question | `codebase_search` | Search local knowledge first |
+| Just need file locations | `codebase_peek` | Metadata only, saves ~90% tokens |
+| Need to see actual code | `codebase_search` | Returns full code content |
+| Find duplicates/patterns | `find_similar` | Given code snippet → similar code |
+| Understand code flow | `call_graph` | Find callers/callees of any function |
+| Trace dependency paths | `call_graph_path` | Find a shortest known path between two symbols |
+| Analyze PR blast radius | `pr_impact` | Find affected symbols, communities, hub nodes, and risk |
+| Don't know function/class names | `codebase_peek` or `codebase_search` | Natural language → code |
+| Know exact identifier names | `grep` | Faster, more precise |
+| Need ALL occurrences | `grep` | Semantic returns top N only |
+| Access specific URL | `webfetch` | Direct URL access, no codebase search needed |
+| Local search fails | `websearch` | Fallback when codebase has no results |
+| Local and web search fails | suggest adding knowledge base | Notify user to add related folder |
+
+## Search Rule
+
+**Search local codebase first, then web search if needed.**
+
+```
+Question received
+    ↓
+Is this about code/library/API/framework?
+    ↓ YES
+codebase_search(query)
+    ↓
+Found relevant results? → YES → Return answer
+    ↓ NO
+websearch(query)
+    ↓
+Found relevant results? → YES → Return answer
+    ↓ NO
+Suggest: "知识库中未找到相关信息，是否添加相关文档文件夹？"
+```
+
+1. Use `codebase_search` for code/library/API questions
+2. If no relevant results → use `websearch`
+3. If web search also fails → suggest adding a knowledge base folder
+
+## Recommended Workflow
+
+1. **Locate by meaning first**: `codebase_peek("authentication flow")` → get likely locations before grep or graph tools
+2. **Search with content**: `codebase_search("ADC channels ESP32")` → inspect implementation or knowledge-base matches
+3. **Read what matters**: `Read` the specific files you need
+4. **Trace structure after discovery**: `call_graph`, `call_graph_path`, `pr_impact`, or OMO CodeGraph once you know the relevant symbol
+5. **Drill down with grep**: `grep "validateToken"` for exact matches
+
+## Tools
+
+### `codebase_peek`
+Find WHERE code is. Returns metadata only (file, line, name, type).
+
+```
+codebase_peek(query="validation logic", chunkType="function", directory="src/utils")
+codebase_peek(query="authentication flow", blameAuthor="jane@example.com")
+```
+
+### `codebase_search`
+Find code with full content. Use when you need to see implementation.
+
+```
+codebase_search(query="error handling middleware", fileType="ts", contextLines=2)
+codebase_search(query="rate limiter", blameSince="2025-01-01")
+```
+
+### `find_similar`
+Find code similar to a given snippet. Use for duplicate detection, pattern discovery, refactoring.
+
+```
+find_similar(code="function validate(input) { return input.length > 0; }", excludeFile="src/current.ts")
+```
+
+### `call_graph`
+Query callers or callees of a function/method.
+
+```
+call_graph(name="validateToken", direction="callers")
+```
+
+### `index_codebase`
+Manually trigger indexing. Required before first search.
+
+### `index_status`
+Check if indexed and ready.
+
+### `add_knowledge_base`
+Add a folder as a knowledge base. The folder will be indexed alongside project code.
+
+```
+add_knowledge_base(path="/path/to/docs")
+```
+
+### `list_knowledge_bases`
+List all configured knowledge base folders.
+
+### `remove_knowledge_base`
+Remove a knowledge base folder from the index.
+
+```
+remove_knowledge_base(path="/path/to/docs")
+```
+
+## Query Tips
+
+**Describe behavior, not syntax:**
+- Good: `"function that hashes passwords securely"`
+- Bad: `"hashPassword"` (use grep for exact names)
+
+**Search across documentation:**
+- Good: `"how to configure WiFi in ESP-IDF"`
+- Good: `"GPIO initialization example"`
+
+## Filters
+
+| Filter | Example |
+|--------|---------|
+| `chunkType` | `function`, `class`, `interface`, `type`, `method` |
+| `directory` | `"src/api"`, `"tests"` |
+| `fileType` | `"ts"`, `"py"`, `"rs"` |
+| `blameAuthor` | `"jane@example.com"` or `"Jane Doe"` |
+| `blameSha` | `"abc1234"` |
+| `blameSince` | `"2025-01-01"` |

package/skills/codebase-search/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: codebase-search
+description: Preferred local codebase-understanding workflow for Pi and Codex. Start with codebase_context before shell search or broad reads, then use specialized semantic and graph tools.
+---
+
+# Codebase Search Skill
+
+Use this skill when you need local repository knowledge before web lookup.
+
+## Core workflow
+
+1. Run `index_status` when index readiness or freshness is unknown.
+2. Use `codebase_context(query, ...)` before shell search, grep, or broad file reads. Pass `symbol` for an authoritative definition or `from` + `to` for a dependency path.
+3. Use `codebase_peek(query, ...)` for specialized metadata-only conceptual lookup.
+4. Use `codebase_search(query, ...)` when you need full code context.
+5. Use `implementation_lookup(query)` for known-symbol definitions and `call_graph` / `call_graph_path` for execution flow.
+6. Use `find_similar(code)` for duplicate patterns and refactor planning.
+
+If results are weak, run `index_status` (check readiness) and `index_codebase`.
+
+## Tool Priority
+
+- `codebase_context` as the preferred first repository tool and unified router.
+- `codebase_peek` for specialized discovery (fastest, cheap tokens).
+- `codebase_search` for exact implementation review.
+- `find_similar` for pattern matching and duplication.
+- `call_graph` and `call_graph_path` for execution flow.
+- `index_codebase` (force/estimate/verbose) for first-time or stale indexes.
+- `index_status`, `index_health_check`, `index_metrics`, `index_logs` for operational checks.
+
+## Suggested Commands
+
+1. `codebase_peek("payment processing flow")`
+2. `codebase_search("payment processing flow")`
+3. `call_graph("chargeCard", "callees")`
+4. `find_similar("function validate(data)")`
+5. `implementation_lookup("validate")`
+
+## Additional Notes
+
+- Use `grep` for exact identifiers and tiny, deterministic lookups.
+- Use `websearch` only when local tools return no results and docs are likely missing.
+- Prefer `codebase_peek` before `codebase_search` to avoid high token usage.