codecortex 0.2.0__tar.gz → 0.2.1__tar.gz

{codecortex-0.2.0/src/codecortex.egg-info → codecortex-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.2.0
+Version: 0.2.1
 Summary: Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents.
 Author: Shammai Hamilton
 License-Expression: MIT
@@ -33,10 +33,55 @@ Dynamic: license-file
 
 # codeintel
 
-A unified code-intelligence gateway — graph + LSP + semantic — that gives any coding agent a single safe API to search, trace, and understand any codebase.
+**One MCP tool that lets a coding agent search, trace, and *understand* a codebase — structurally, not by grepping.** codeintel unifies three engines — a call/import **graph**, an **LSP** for exact symbols, and **semantic** embedding search — behind a single `code.query` call that routes to the right engine, caches the answer, and **never throws**. The agent always gets back a clean, well-formed result to reason over.
 
 [![CI](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml/badge.svg)](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml)
 
+## Why an agent needs it
+
+Without structural tools, an agent dropped into unfamiliar code falls back on `grep` and reads whole files to reconstruct relationships by hand — burning tokens, missing call sites, and guessing at blast radius before it edits anything. codeintel answers those questions directly instead:
+
+- **"What calls this? What breaks if I change it?"** → the real call graph, which catches cross-file and module-level callers a text search silently misses.
+- **"Where is this symbol defined, and everywhere it's used?"** → the language server, with exact locations.
+- **"Where's the code that does X?"** (when you don't know the name) → semantic search over the repo.
+- **Always a clean answer.** Every call returns the same JSON envelope. A missing or broken backend degrades to a safe `null` *with a reason* — so the agent falls back to grep instead of crashing on an exception it can't reason its way out of.
+
+Net effect: fewer, sharper tool calls, less re-reading, and an agent that can see *structure* — callers, impact, call chains — that plain search can't.
+
+## What your agent can ask
+
+It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the default) codeintel picks the engine per operation:
+
+| Ask | `op` | Engine (auto) | Comes back as |
+|---|---|---|---|
+| Find code by meaning ("auth middleware") | `search` | semantic | ranked `path:line │ snippet` hits |
+| A symbol's definition **and** all references | `symbol` | lsp | definition body + reference list |
+| Who calls this? | `callers` | graph | caller symbols + files |
+| What does this call? | `callees` | graph | callee symbols + files |
+| Blast radius of a change | `impact` | graph | callers **and** callees together |
+| Trace a call chain up/downstream | `chain` | graph | ordered hops |
+| Find symbols by pattern | `pattern` | graph | matching nodes + locations |
+| Project shape at a glance | `overview` | graph → lsp | modules, node/edge counts, languages |
+| Everything about one symbol | `context` | graph + lsp | both views merged |
+
+Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
+
+**Example — "who uses `safe_null_result`?"**
+
+```jsonc
+// request
+{ "op": "callers", "target": "safe_null_result", "engine": "auto" }
+
+// response — always this exact envelope; `result` is ready-to-read markdown
+{
+  "ok": true, "op": "callers", "target": "safe_null_result",
+  "engine": "graph", "cached": false,
+  "result": "## Callers of safe_null_result (7)\n- …gateway [USAGE] (src/codeintel/gateway.py)\n- …providers.graph [USAGE] (src/codeintel/providers/graph.py)\n- …server [USAGE] (src/codeintel/server.py)\n- … (4 more)"
+}
+```
+
+The agent hands `result` straight to the model. If the graph backend isn't installed, the identical call returns `"result": null, "reason": "engine-unavailable"` — no exception, and the agent just falls back to its own search.
+
 ## Quickstart
 
 ```bash
@@ -146,7 +191,7 @@ backend      = "auto"                   # auto | graph | lsp | semantic
 semantic     = "on"                     # on | off
 reindex      = "on-demand"              # on-demand | never
 cosine_floor = 0.25                     # minimum similarity score for semantic hits
-max_chunks   = 500                      # max chunks to embed per project
+max_chunks   = 500                      # max chunks to embed per file
 model        = "BAAI/bge-small-en-v1.5" # fastembed embedding model
 ```
 
@@ -170,7 +215,16 @@ Not sure what's installed? `codeintel doctor` reports exactly which backends are
 
 ## For agents
 
-Start the HTTP server, then POST queries to `/code/query`:
+Register codeintel as an MCP server (`codeintel install`) and the agent gets four tools:
+
+| MCP tool | HTTP equivalent | Purpose |
+|---|---|---|
+| `code.query` | `POST /code/query` | The main call — search, trace, understand (the `op` table above) |
+| `code.status` | `GET /code/status` | Which engines are live + whether an index exists |
+| `code.doctor` | `POST /code/doctor` | Per-engine health + repo index status, with a fix for each gap |
+| `code.map` | — | Generate/refresh `CODE_INTEL.md`, a static orientation file for hosts without MCP |
+
+Over MCP the agent calls `code.query` directly. Over HTTP, start the server and POST to `/code/query`:
 
 ```bash
 codeintel serve-http &   # listens on 127.0.0.1:8766 by default
@@ -202,5 +256,5 @@ The response is always JSON-safe. Check `result["result"] is not None` before us
 git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
-pytest tests/ -q            # full suite, ~1s
+pytest tests/ -q            # full suite (~15s — includes live graph/LSP backend tests)
 ```

{codecortex-0.2.0 → codecortex-0.2.1}/README.md

@@ -1,9 +1,54 @@
 # codeintel
 
-A unified code-intelligence gateway — graph + LSP + semantic — that gives any coding agent a single safe API to search, trace, and understand any codebase.
+**One MCP tool that lets a coding agent search, trace, and *understand* a codebase — structurally, not by grepping.** codeintel unifies three engines — a call/import **graph**, an **LSP** for exact symbols, and **semantic** embedding search — behind a single `code.query` call that routes to the right engine, caches the answer, and **never throws**. The agent always gets back a clean, well-formed result to reason over.
 
 [![CI](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml/badge.svg)](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml)
 
+## Why an agent needs it
+
+Without structural tools, an agent dropped into unfamiliar code falls back on `grep` and reads whole files to reconstruct relationships by hand — burning tokens, missing call sites, and guessing at blast radius before it edits anything. codeintel answers those questions directly instead:
+
+- **"What calls this? What breaks if I change it?"** → the real call graph, which catches cross-file and module-level callers a text search silently misses.
+- **"Where is this symbol defined, and everywhere it's used?"** → the language server, with exact locations.
+- **"Where's the code that does X?"** (when you don't know the name) → semantic search over the repo.
+- **Always a clean answer.** Every call returns the same JSON envelope. A missing or broken backend degrades to a safe `null` *with a reason* — so the agent falls back to grep instead of crashing on an exception it can't reason its way out of.
+
+Net effect: fewer, sharper tool calls, less re-reading, and an agent that can see *structure* — callers, impact, call chains — that plain search can't.
+
+## What your agent can ask
+
+It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the default) codeintel picks the engine per operation:
+
+| Ask | `op` | Engine (auto) | Comes back as |
+|---|---|---|---|
+| Find code by meaning ("auth middleware") | `search` | semantic | ranked `path:line │ snippet` hits |
+| A symbol's definition **and** all references | `symbol` | lsp | definition body + reference list |
+| Who calls this? | `callers` | graph | caller symbols + files |
+| What does this call? | `callees` | graph | callee symbols + files |
+| Blast radius of a change | `impact` | graph | callers **and** callees together |
+| Trace a call chain up/downstream | `chain` | graph | ordered hops |
+| Find symbols by pattern | `pattern` | graph | matching nodes + locations |
+| Project shape at a glance | `overview` | graph → lsp | modules, node/edge counts, languages |
+| Everything about one symbol | `context` | graph + lsp | both views merged |
+
+Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
+
+**Example — "who uses `safe_null_result`?"**
+
+```jsonc
+// request
+{ "op": "callers", "target": "safe_null_result", "engine": "auto" }
+
+// response — always this exact envelope; `result` is ready-to-read markdown
+{
+  "ok": true, "op": "callers", "target": "safe_null_result",
+  "engine": "graph", "cached": false,
+  "result": "## Callers of safe_null_result (7)\n- …gateway [USAGE] (src/codeintel/gateway.py)\n- …providers.graph [USAGE] (src/codeintel/providers/graph.py)\n- …server [USAGE] (src/codeintel/server.py)\n- … (4 more)"
+}
+```
+
+The agent hands `result` straight to the model. If the graph backend isn't installed, the identical call returns `"result": null, "reason": "engine-unavailable"` — no exception, and the agent just falls back to its own search.
+
 ## Quickstart
 
 ```bash
@@ -113,7 +158,7 @@ backend      = "auto"                   # auto | graph | lsp | semantic
 semantic     = "on"                     # on | off
 reindex      = "on-demand"              # on-demand | never
 cosine_floor = 0.25                     # minimum similarity score for semantic hits
-max_chunks   = 500                      # max chunks to embed per project
+max_chunks   = 500                      # max chunks to embed per file
 model        = "BAAI/bge-small-en-v1.5" # fastembed embedding model
 ```
 
@@ -137,7 +182,16 @@ Not sure what's installed? `codeintel doctor` reports exactly which backends are
 
 ## For agents
 
-Start the HTTP server, then POST queries to `/code/query`:
+Register codeintel as an MCP server (`codeintel install`) and the agent gets four tools:
+
+| MCP tool | HTTP equivalent | Purpose |
+|---|---|---|
+| `code.query` | `POST /code/query` | The main call — search, trace, understand (the `op` table above) |
+| `code.status` | `GET /code/status` | Which engines are live + whether an index exists |
+| `code.doctor` | `POST /code/doctor` | Per-engine health + repo index status, with a fix for each gap |
+| `code.map` | — | Generate/refresh `CODE_INTEL.md`, a static orientation file for hosts without MCP |
+
+Over MCP the agent calls `code.query` directly. Over HTTP, start the server and POST to `/code/query`:
 
 ```bash
 codeintel serve-http &   # listens on 127.0.0.1:8766 by default
@@ -169,5 +223,5 @@ The response is always JSON-safe. Check `result["result"] is not None` before us
 git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
-pytest tests/ -q            # full suite, ~1s
+pytest tests/ -q            # full suite (~15s — includes live graph/LSP backend tests)
 ```

{codecortex-0.2.0 → codecortex-0.2.1/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.2.0
+Version: 0.2.1
 Summary: Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents.
 Author: Shammai Hamilton
 License-Expression: MIT
@@ -33,10 +33,55 @@ Dynamic: license-file
 
 # codeintel
 
-A unified code-intelligence gateway — graph + LSP + semantic — that gives any coding agent a single safe API to search, trace, and understand any codebase.
+**One MCP tool that lets a coding agent search, trace, and *understand* a codebase — structurally, not by grepping.** codeintel unifies three engines — a call/import **graph**, an **LSP** for exact symbols, and **semantic** embedding search — behind a single `code.query` call that routes to the right engine, caches the answer, and **never throws**. The agent always gets back a clean, well-formed result to reason over.
 
 [![CI](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml/badge.svg)](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml)
 
+## Why an agent needs it
+
+Without structural tools, an agent dropped into unfamiliar code falls back on `grep` and reads whole files to reconstruct relationships by hand — burning tokens, missing call sites, and guessing at blast radius before it edits anything. codeintel answers those questions directly instead:
+
+- **"What calls this? What breaks if I change it?"** → the real call graph, which catches cross-file and module-level callers a text search silently misses.
+- **"Where is this symbol defined, and everywhere it's used?"** → the language server, with exact locations.
+- **"Where's the code that does X?"** (when you don't know the name) → semantic search over the repo.
+- **Always a clean answer.** Every call returns the same JSON envelope. A missing or broken backend degrades to a safe `null` *with a reason* — so the agent falls back to grep instead of crashing on an exception it can't reason its way out of.
+
+Net effect: fewer, sharper tool calls, less re-reading, and an agent that can see *structure* — callers, impact, call chains — that plain search can't.
+
+## What your agent can ask
+
+It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the default) codeintel picks the engine per operation:
+
+| Ask | `op` | Engine (auto) | Comes back as |
+|---|---|---|---|
+| Find code by meaning ("auth middleware") | `search` | semantic | ranked `path:line │ snippet` hits |
+| A symbol's definition **and** all references | `symbol` | lsp | definition body + reference list |
+| Who calls this? | `callers` | graph | caller symbols + files |
+| What does this call? | `callees` | graph | callee symbols + files |
+| Blast radius of a change | `impact` | graph | callers **and** callees together |
+| Trace a call chain up/downstream | `chain` | graph | ordered hops |
+| Find symbols by pattern | `pattern` | graph | matching nodes + locations |
+| Project shape at a glance | `overview` | graph → lsp | modules, node/edge counts, languages |
+| Everything about one symbol | `context` | graph + lsp | both views merged |
+
+Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
+
+**Example — "who uses `safe_null_result`?"**
+
+```jsonc
+// request
+{ "op": "callers", "target": "safe_null_result", "engine": "auto" }
+
+// response — always this exact envelope; `result` is ready-to-read markdown
+{
+  "ok": true, "op": "callers", "target": "safe_null_result",
+  "engine": "graph", "cached": false,
+  "result": "## Callers of safe_null_result (7)\n- …gateway [USAGE] (src/codeintel/gateway.py)\n- …providers.graph [USAGE] (src/codeintel/providers/graph.py)\n- …server [USAGE] (src/codeintel/server.py)\n- … (4 more)"
+}
+```
+
+The agent hands `result` straight to the model. If the graph backend isn't installed, the identical call returns `"result": null, "reason": "engine-unavailable"` — no exception, and the agent just falls back to its own search.
+
 ## Quickstart
 
 ```bash
@@ -146,7 +191,7 @@ backend      = "auto"                   # auto | graph | lsp | semantic
 semantic     = "on"                     # on | off
 reindex      = "on-demand"              # on-demand | never
 cosine_floor = 0.25                     # minimum similarity score for semantic hits
-max_chunks   = 500                      # max chunks to embed per project
+max_chunks   = 500                      # max chunks to embed per file
 model        = "BAAI/bge-small-en-v1.5" # fastembed embedding model
 ```
 
@@ -170,7 +215,16 @@ Not sure what's installed? `codeintel doctor` reports exactly which backends are
 
 ## For agents
 
-Start the HTTP server, then POST queries to `/code/query`:
+Register codeintel as an MCP server (`codeintel install`) and the agent gets four tools:
+
+| MCP tool | HTTP equivalent | Purpose |
+|---|---|---|
+| `code.query` | `POST /code/query` | The main call — search, trace, understand (the `op` table above) |
+| `code.status` | `GET /code/status` | Which engines are live + whether an index exists |
+| `code.doctor` | `POST /code/doctor` | Per-engine health + repo index status, with a fix for each gap |
+| `code.map` | — | Generate/refresh `CODE_INTEL.md`, a static orientation file for hosts without MCP |
+
+Over MCP the agent calls `code.query` directly. Over HTTP, start the server and POST to `/code/query`:
 
 ```bash
 codeintel serve-http &   # listens on 127.0.0.1:8766 by default
@@ -202,5 +256,5 @@ The response is always JSON-safe. Check `result["result"] is not None` before us
 git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
-pytest tests/ -q            # full suite, ~1s
+pytest tests/ -q            # full suite (~15s — includes live graph/LSP backend tests)
 ```

codecortex-0.2.1/src/codeintel/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.1"

{codecortex-0.2.0 → codecortex-0.2.1}/src/codeintel/injector.py

@@ -57,8 +57,12 @@ def _read_file(path: str) -> str | None:
 
 
 def _write_file(path: str, content: str) -> None:
-    with open(path, "w", encoding="utf-8") as f:
+    # Atomic: write a sibling temp file then os.replace it into place, so an interrupted
+    # write can never leave the user's CLAUDE.md/AGENTS.md truncated or half-written.
+    tmp = path + ".codeintel.tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
         f.write(content)
+    os.replace(tmp, path)
 
 
 def _update_block(content: str) -> tuple[str, str]:

{codecortex-0.2.0 → codecortex-0.2.1}/src/codeintel/installer.py

@@ -1,10 +1,20 @@
 from __future__ import annotations
 
 import json
+import os
 import pathlib
 
 _AGENTS = ["claude", "codex", "gemini", "zed"]
 
+
+def _atomic_write_text(path: pathlib.Path, text: str) -> None:
+    """Write via a sibling temp file + os.replace so an interrupted write can never truncate
+    the user's existing agent config (which holds unrelated settings) to a partial/empty file.
+    The temp lives in the same directory as ``path`` so the replace stays on one filesystem."""
+    tmp = path.with_name(path.name + ".codeintel.tmp")
+    tmp.write_text(text, encoding="utf-8")
+    os.replace(tmp, path)
+
 _CONFIG: dict[str, dict] = {
     "claude": {
         "path": "~/.claude/settings.json",
@@ -80,7 +90,7 @@ class Installer:
 
             config_path.parent.mkdir(parents=True, exist_ok=True)
             _set_nested(data, spec["key"], spec["value"])
-            config_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+            _atomic_write_text(config_path, json.dumps(data, indent=2))
 
             return {
                 "agent": agent,

{codecortex-0.2.0 → codecortex-0.2.1}/src/codeintel/semantic_db.py

@@ -31,6 +31,18 @@ class SemanticDb:
             self._conn = sqlite3.connect(self.db_path)
             self._conn.enable_load_extension(True)
             self._conn.row_factory = sqlite3.Row
+            # Concurrency: the background Reindexer writes on a daemon thread while a foreground
+            # query indexes inline — two separate connections to this one file. With the SQLite
+            # default (busy_timeout=0) the loser of that write race gets an immediate
+            # "database is locked" and silently drops its work; a busy timeout makes it wait
+            # instead, and WAL lets a search read while a reindex writes. (reset.py already
+            # cleans up the -wal/-shm siblings WAL creates.) Never-raise: if the pragmas can't
+            # be applied, fall back to default locking rather than fail to open the db.
+            try:
+                self._conn.execute("PRAGMA busy_timeout=5000")
+                self._conn.execute("PRAGMA journal_mode=WAL")
+            except Exception:
+                pass
         return self._conn
 
     def init(self) -> None:

codecortex-0.2.0/src/codeintel/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.2.0"