@fodx/codelens 1.0.0

package/docs/routing.md

@@ -0,0 +1,59 @@
+# Agent Routing Instructions — CodeLens
+
+> Inject this block into your agent's system prompt / rules so it routes code
+> discovery through the codelens tools instead of raw grep/find/read.
+
+## When to use codelens tools
+
+**For codebase discovery, do NOT start with `grep`/`find`/`read`.** Use the
+codelens tools first:
+
+1. Call `cl_current` to confirm the index is ready for the current branch.
+   - If `status` is `missing`, call `cl_refresh` to build the index.
+2. Use `cl_search` to find relevant files/symbols by intent (2–4 specific terms).
+3. Use `cl_related` to expand graph neighbors (tests, callers, imports).
+4. Use `cl_expand` to read the exact current file content for a chosen target
+   (it reads from disk — never stale).
+5. Save working context with `cl_save` and reload it with `cl_load` across
+   compaction / long sessions.
+
+## When raw reads are still allowed
+
+- Before **editing** a file: read the exact target file with your normal read
+  tool (or `cl_expand`) so you have the current bytes.
+- When **verifying** exact code, logs, or user-supplied paths.
+- When `cl_search` explicitly cannot answer (e.g. the index is empty and the
+  repo is not a git repo).
+- When the user explicitly asks for raw command output.
+
+Do **not** ban raw reads outright — they are correct for editing and
+verification. The routing is about **discovery**: prefer indexed context over
+bulk file dumps to keep your context window lean.
+
+## Branch safety
+
+Results are scoped to the **current branch/worktree index only** by default.
+After `git checkout`, results will not leak from the old branch. If you switch
+branches mid-task, call `cl_current` again; the tool activates/creates the new
+branch's index automatically.
+
+## Freshness
+
+`cl_search` auto-refreshes changed files before returning (budget-bounded). If
+the response carries `freshness: "partial"` and `pendingFiles > 0`, some very
+recent edits may not yet be reflected — call `cl_refresh` or re-query.
+
+## Tool quick reference
+
+| Tool | Purpose |
+|------|---------|
+| `cl_current` | repo/branch/index status + freshness |
+| `cl_refresh` | build/update the current branch index |
+| `cl_search` | hybrid ranked search → compact handles |
+| `cl_related` | graph neighbors (imports/tests/callers) |
+| `cl_expand` | exact current file content by path/range |
+| `cl_save` / `cl_load` | persist + reload working context |
+| `cl_stats` | index counts |
+| `cl_doctor` | runtime/DB/integrity health check |
+| `cl_prune` | manual TTL sweep |
+| `cl_drop` | delete a branch/index explicitly |

package/docs/tools.md

@@ -0,0 +1,53 @@
+# Tool Reference — CodeLens
+
+All tools are exposed via MCP. Inputs are validated with zod; outputs are
+JSON-serialized text content.
+
+## cl_current
+- **Input**: none
+- **Returns**: `{ repo, branch, headSha, indexId, status, dirtyFiles, lastIndexedAt, inGitRepo }`
+- **Use**: first call to check index readiness.
+
+## cl_refresh
+- **Input**: none
+- **Returns**: `{ indexId, branch, indexedFiles, totalChunks, skipped, status }`
+- **Use**: build/update the current branch index.
+
+## cl_search
+- **Input**: `{ query: string, limit?: number=5, cursor?: string }`
+- **Returns**: `{ indexId, results:[{handle,path,startLine,endLine,score,snippet,why}], nextCursor, freshness, pendingFiles }`
+- **Use**: intent-level code discovery.
+
+## cl_related
+- **Input**: `{ path: string, types?: string[], depth?: number=2, direction?: "out"|"in"|"both" }`
+- **Returns**: `{ indexId, results:[{handle,path,edgeType,hops,confidence}] }`
+- **Edge types**: `imports|imported_by|tests|calls|references|defines|exports|belongs_to`
+
+## cl_expand
+- **Input**: `{ path?: string, handle?: string, startLine?: number, endLine?: number, budget?: number=4000 }`
+- **Returns**: `{ path, startLine, endLine, content, truncated, chars }`
+- **Use**: read exact current file content (disk-backed, never stale). Rejects path traversal.
+
+## cl_save
+- **Input**: `{ name: string, items: [{handle?,path?,symbol_id?,chunk_id?}], notes?: string, pinned?: boolean }`
+- **Returns**: `{ id, name, pinned, itemCount }`
+
+## cl_load
+- **Input**: `{ name: string }`
+- **Returns**: `{ context, items }`
+
+## cl_stats
+- **Input**: none
+- **Returns**: `{ active, indexId, branch, counts, backlog, lastIndexedAt, totalIndexes }`
+
+## cl_doctor
+- **Input**: none
+- **Returns**: `{ nodeVersion, betterSqlite3, gitPresent, schemaVersion, integrityOk, walMode, inGitRepo, codeVersion }`
+
+## cl_prune
+- **Input**: none
+- **Returns**: `{ deletedIndexes, skipped, bytesFreed }`
+
+## cl_drop
+- **Input**: `{ indexId?: string, branch?: string }`
+- **Returns**: `{ deleted, indexId, reason? }` (refuses active/pinned)

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@fodx/codelens",
+  "version": "1.0.0",
+  "description": "Local, branch-aware code search & relation graph. SQLite FTS5 + tree-sitter symbols + source-graph edges, exposed as an MCP server and CLI. No chat LLM required.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/ex-git/codeLens#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ex-git/codeLens.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ex-git/codeLens/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "mcp",
+    "mcp-server",
+    "modelcontextprotocol",
+    "code-search",
+    "code-graph",
+    "code-index",
+    "tree-sitter",
+    "claude-code",
+    "cursor",
+    "gemini-cli",
+    "opencode",
+    "codex"
+  ],
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "main": "build/src/server.js",
+  "bin": {
+    "codelens": "build/src/server.js"
+  },
+  "files": [
+    "build/src",
+    "adapters/pi",
+    "README.md",
+    "docs/agent-guide.md",
+    "docs/routing.md",
+    "docs/tools.md",
+    "docs/codelens-preview.png"
+  ],
+  "pi": {
+    "extensions": [
+      "adapters/pi/codelens.extension.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/ex-git/codeLens/main/docs/codelens-preview.png"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --ext .ts",
+    "test": "vitest run",
+    "build": "tsc && node scripts/build.mjs",
+    "prepublishOnly": "npm run build",
+    "mcp:smoke": "node build/src/server.js --smoke",
+    "start": "node build/src/server.js",
+    "benchmark": "npx tsx bench/run.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^12.6.2",
+    "ignore": "^7.0.5",
+    "tree-sitter": "^0.25.0",
+    "tree-sitter-c": "^0.24.1",
+    "tree-sitter-cpp": "^0.23.4",
+    "tree-sitter-go": "^0.25.0",
+    "tree-sitter-java": "^0.23.5",
+    "tree-sitter-javascript": "^0.25.0",
+    "tree-sitter-php": "^0.24.2",
+    "tree-sitter-python": "^0.25.0",
+    "tree-sitter-ruby": "^0.23.1",
+    "tree-sitter-rust": "^0.24.0",
+    "tree-sitter-typescript": "^0.23.2",
+    "zod": "^3.25.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.19.11",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "tsx": "^4.22.4",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^4.0.18"
+  }
+}