codecortex 0.12.0__tar.gz → 0.12.1__tar.gz

{codecortex-0.12.0/src/codecortex.egg-info → codecortex-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.12.0
+Version: 0.12.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
@@ -229,6 +229,9 @@ against the built wheel in a clean environment: it registers Codex and Claude Co
 `code.query` over a fixture repo. A release that writes a config no host reads, or that returns
 `ok: true` with nothing in it, fails there instead of on your machine.
 
+> Full reference — what each host reads, the absolute-path rationale, and troubleshooting:
+> **[docs/install.md](docs/install.md)**.
+
 ## How it works
 
 A `Gateway` receives every query and dispatches it to one of three providers — graph (structural relationships), LSP (precise symbol resolution), or semantic (embedding-based search) — based on the operation type. Each provider is fully isolated: if it is unavailable or raises an exception, the gateway catches it and returns a safe-null envelope. The caller always gets a well-formed response with no exception to catch.
@@ -275,6 +278,7 @@ Pass `--engine auto` (the default) and codeintel chooses the best engine per ope
 Full system docs live in [`docs/`](docs/) — start with the index:
 
 - **[Architecture](docs/architecture.md)** — layers, the `CodeProvider` protocol, the safe-null contract, caching, freshness (ASCII + Mermaid).
+- **[Install & registration](docs/install.md)** — what each agent host actually reads, why the registered command is an absolute path, and the three levels of proof that registration worked.
 - **[Query flow](docs/query-flow.md)** — request lifecycle, engine selection, fan-out & merge, and why it never throws.
 - **[Map file](docs/map-file.md)** — the static `CODE_INTEL.md` orientation layer for hosts with no MCP support.
 - **[Benchmarks](docs/benchmarks.md)** — real numbers at scale: 25 k chunks indexed in ~8 min, ~235 ms warm queries, 60 MB index.
@@ -284,6 +288,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 
 | Command | Purpose |
 |---|---|
+| `codeintel help` | Every command grouped by task, with descriptions and examples (also the bare `codeintel`). A mistyped command suggests what you meant. |
 | `codeintel install [--agent auto\|claude\|codex\|gemini\|zed\|all] [--no-verify] [--relative-command]` | Register codeintel with the agents installed on this machine (`auto`, the default), then prove it by completing a real MCP handshake against the registered command |
 | `codeintel setup [project_root] [--all] [--index] [--warm] [--install-uv] [--install-deps] [--json]` | Prepare backends + index this repo (`--all` = one command: do everything automatable, idempotent); ends with a health report + **Next:** steps |
 | `codeintel index [project_root]` | Index a project for semantic search |
@@ -409,7 +414,7 @@ docker build -t codeintel . && docker run -p 127.0.0.1:8766:8766 \
 git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
-pytest tests/ -q            # ~390 tests, ~35s (live graph/LSP backend tests skip when absent)
+pytest tests/ -q            # ~410 tests, ~35s (live graph/LSP backend tests skip when absent)
 ```
 
 **Release gate.** The unit suite runs against the source tree, so it cannot see a packaging break, a

{codecortex-0.12.0 → codecortex-0.12.1}/README.md

@@ -195,6 +195,9 @@ against the built wheel in a clean environment: it registers Codex and Claude Co
 `code.query` over a fixture repo. A release that writes a config no host reads, or that returns
 `ok: true` with nothing in it, fails there instead of on your machine.
 
+> Full reference — what each host reads, the absolute-path rationale, and troubleshooting:
+> **[docs/install.md](docs/install.md)**.
+
 ## How it works
 
 A `Gateway` receives every query and dispatches it to one of three providers — graph (structural relationships), LSP (precise symbol resolution), or semantic (embedding-based search) — based on the operation type. Each provider is fully isolated: if it is unavailable or raises an exception, the gateway catches it and returns a safe-null envelope. The caller always gets a well-formed response with no exception to catch.
@@ -241,6 +244,7 @@ Pass `--engine auto` (the default) and codeintel chooses the best engine per ope
 Full system docs live in [`docs/`](docs/) — start with the index:
 
 - **[Architecture](docs/architecture.md)** — layers, the `CodeProvider` protocol, the safe-null contract, caching, freshness (ASCII + Mermaid).
+- **[Install & registration](docs/install.md)** — what each agent host actually reads, why the registered command is an absolute path, and the three levels of proof that registration worked.
 - **[Query flow](docs/query-flow.md)** — request lifecycle, engine selection, fan-out & merge, and why it never throws.
 - **[Map file](docs/map-file.md)** — the static `CODE_INTEL.md` orientation layer for hosts with no MCP support.
 - **[Benchmarks](docs/benchmarks.md)** — real numbers at scale: 25 k chunks indexed in ~8 min, ~235 ms warm queries, 60 MB index.
@@ -250,6 +254,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 
 | Command | Purpose |
 |---|---|
+| `codeintel help` | Every command grouped by task, with descriptions and examples (also the bare `codeintel`). A mistyped command suggests what you meant. |
 | `codeintel install [--agent auto\|claude\|codex\|gemini\|zed\|all] [--no-verify] [--relative-command]` | Register codeintel with the agents installed on this machine (`auto`, the default), then prove it by completing a real MCP handshake against the registered command |
 | `codeintel setup [project_root] [--all] [--index] [--warm] [--install-uv] [--install-deps] [--json]` | Prepare backends + index this repo (`--all` = one command: do everything automatable, idempotent); ends with a health report + **Next:** steps |
 | `codeintel index [project_root]` | Index a project for semantic search |
@@ -375,7 +380,7 @@ docker build -t codeintel . && docker run -p 127.0.0.1:8766:8766 \
 git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
-pytest tests/ -q            # ~390 tests, ~35s (live graph/LSP backend tests skip when absent)
+pytest tests/ -q            # ~410 tests, ~35s (live graph/LSP backend tests skip when absent)
 ```
 
 **Release gate.** The unit suite runs against the source tree, so it cannot see a packaging break, a

{codecortex-0.12.0 → codecortex-0.12.1/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.12.0
+Version: 0.12.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
@@ -229,6 +229,9 @@ against the built wheel in a clean environment: it registers Codex and Claude Co
 `code.query` over a fixture repo. A release that writes a config no host reads, or that returns
 `ok: true` with nothing in it, fails there instead of on your machine.
 
+> Full reference — what each host reads, the absolute-path rationale, and troubleshooting:
+> **[docs/install.md](docs/install.md)**.
+
 ## How it works
 
 A `Gateway` receives every query and dispatches it to one of three providers — graph (structural relationships), LSP (precise symbol resolution), or semantic (embedding-based search) — based on the operation type. Each provider is fully isolated: if it is unavailable or raises an exception, the gateway catches it and returns a safe-null envelope. The caller always gets a well-formed response with no exception to catch.
@@ -275,6 +278,7 @@ Pass `--engine auto` (the default) and codeintel chooses the best engine per ope
 Full system docs live in [`docs/`](docs/) — start with the index:
 
 - **[Architecture](docs/architecture.md)** — layers, the `CodeProvider` protocol, the safe-null contract, caching, freshness (ASCII + Mermaid).
+- **[Install & registration](docs/install.md)** — what each agent host actually reads, why the registered command is an absolute path, and the three levels of proof that registration worked.
 - **[Query flow](docs/query-flow.md)** — request lifecycle, engine selection, fan-out & merge, and why it never throws.
 - **[Map file](docs/map-file.md)** — the static `CODE_INTEL.md` orientation layer for hosts with no MCP support.
 - **[Benchmarks](docs/benchmarks.md)** — real numbers at scale: 25 k chunks indexed in ~8 min, ~235 ms warm queries, 60 MB index.
@@ -284,6 +288,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 
 | Command | Purpose |
 |---|---|
+| `codeintel help` | Every command grouped by task, with descriptions and examples (also the bare `codeintel`). A mistyped command suggests what you meant. |
 | `codeintel install [--agent auto\|claude\|codex\|gemini\|zed\|all] [--no-verify] [--relative-command]` | Register codeintel with the agents installed on this machine (`auto`, the default), then prove it by completing a real MCP handshake against the registered command |
 | `codeintel setup [project_root] [--all] [--index] [--warm] [--install-uv] [--install-deps] [--json]` | Prepare backends + index this repo (`--all` = one command: do everything automatable, idempotent); ends with a health report + **Next:** steps |
 | `codeintel index [project_root]` | Index a project for semantic search |
@@ -409,7 +414,7 @@ docker build -t codeintel . && docker run -p 127.0.0.1:8766:8766 \
 git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
-pytest tests/ -q            # ~390 tests, ~35s (live graph/LSP backend tests skip when absent)
+pytest tests/ -q            # ~410 tests, ~35s (live graph/LSP backend tests skip when absent)
 ```
 
 **Release gate.** The unit suite runs against the source tree, so it cannot see a packaging break, a

{codecortex-0.12.0 → codecortex-0.12.1}/src/codecortex.egg-info/SOURCES.txt

@@ -41,6 +41,7 @@ src/codeintel/viewer/__init__.py
 src/codeintel/viewer/graph_template.html
 tests/test_cache.py
 tests/test_chunking.py
+tests/test_cli_help.py
 tests/test_config.py
 tests/test_doctor.py
 tests/test_e2e.py

codecortex-0.12.1/src/codeintel/__init__.py

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

{codecortex-0.12.0 → codecortex-0.12.1}/src/codeintel/__main__.py

@@ -1,9 +1,101 @@
 import argparse
+import difflib
 import os
 import sys
 
 from codeintel import __version__
 
+# Commands grouped by what you are trying to DO. argparse lists them in declaration order with no
+# grouping, which turns "what can this thing do?" into reading twelve lines to find the one verb you
+# wanted. Each entry is (command, one-line description).
+_COMMAND_GROUPS: list[tuple[str, list[tuple[str, str]]]] = [
+    ("Understand your code", [
+        ("query", "Ask one question — search, callers, callees, impact, chain, symbol, hotspots"),
+        ("map", "Write CODE_INTEL.md — a committable architecture overview"),
+        ("graph", "Interactive call-graph viewer (--html), or the graph as JSON"),
+    ]),
+    ("Set up", [
+        ("setup", "Prepare backends + index this repo (--all does everything automatable)"),
+        ("index", "Index a project for semantic search"),
+        ("install", "Register codeintel with the AI agents installed on this machine"),
+    ]),
+    ("Check health", [
+        ("doctor", "Per-engine health + index status, with the fix for each gap"),
+        ("status", "Engine readiness and index age at a glance"),
+        ("reset", "Clear the semantic index (recover from a corrupt or stale DB)"),
+    ]),
+    ("Run as a server", [
+        ("serve", "Start the MCP server over stdio — what an agent host launches"),
+        ("serve-http", "Start the HTTP transport (loopback only unless --allow-remote)"),
+        ("gen-token", "Print a secure random bearer token for serve-http / RBAC"),
+    ]),
+]
+
+_COMMANDS = [name for _group, items in _COMMAND_GROUPS for name, _desc in items]
+
+_EXAMPLES = [
+    ("codeintel setup --all .", "prepare backends and index this repo"),
+    ("codeintel install", "register with the agents you have"),
+    ("codeintel query --op callers --target my_function", "who calls it?"),
+    ("codeintel doctor", "why is a query coming back empty?"),
+]
+
+
+def render_help() -> str:
+    """The `codeintel` / `codeintel help` screen: grouped, colored, with real examples.
+
+    Color comes from codeintel.term, so it auto-degrades on a pipe, under NO_COLOR, and on a dumb
+    terminal — same as every other human-facing command."""
+    from codeintel.term import c
+
+    width = max(len(name) for name in _COMMANDS)
+    out = [
+        c.bold("codeintel") + c.dim(f" {__version__}")
+        + c.dim("  —  code intelligence for AI agents: graph + LSP + semantic search"),
+        "",
+        c.dim("usage: ") + "codeintel <command> [options]",
+    ]
+    for group, items in _COMMAND_GROUPS:
+        out.append("")
+        out.append("  " + c.bold(group))
+        for name, desc in items:
+            out.append("    " + c.cyan(name.ljust(width)) + "  " + desc)
+
+    out.append("")
+    out.append("  " + c.bold("Examples"))
+    # Width from the content, not a guess — a hardcoded column silently loses its gutter the moment
+    # one example grows past it, and ljust() will not pad below the string's own length.
+    cmd_width = max(len(cmd) for cmd, _why in _EXAMPLES) + 2
+    for cmd, why in _EXAMPLES:
+        out.append("    " + cmd.ljust(cmd_width) + c.dim("# " + why))
+
+    out.append("")
+    out.append("  " + c.dim("codeintel <command> --help") + "   full options for one command")
+    out.append("  " + c.dim("docs: https://github.com/hamilton-sky/codeintel"))
+    return "\n".join(out)
+
+
+def _suggest(unknown: str) -> list[str]:
+    """Commands a typo probably meant. Close matches first, then prefix matches — `gragh` should
+    land on `graph`, and a bare `serv` on both `serve` and `serve-http`."""
+    close = difflib.get_close_matches(unknown, _COMMANDS, n=3, cutoff=0.5)
+    prefix = [cmd for cmd in _COMMANDS if cmd.startswith(unknown) and cmd not in close]
+    return (close + prefix)[:3]
+
+
+def _unknown_command(name: str) -> int:
+    """Report an unrecognized command with a way forward. argparse's own error dumps the full list
+    of choices and stops there, which is a dead end for a one-character typo."""
+    from codeintel.term import c_err as e
+
+    print(e.red(f"unknown command: {name!r}"), file=sys.stderr)
+    matches = _suggest(name)
+    if matches:
+        joined = " or ".join(e.cyan(m) for m in matches)
+        print(f"\n  did you mean {joined}?", file=sys.stderr)
+    print("\n  " + e.dim("run `codeintel help` to see every command"), file=sys.stderr)
+    return 2
+
 
 def main() -> None:
     parser = argparse.ArgumentParser(prog="codeintel")
@@ -113,6 +205,19 @@ def main() -> None:
     reset_parser.add_argument("--json", action="store_true", help="Emit the structured JSON report")
 
     subparsers.add_parser("gen-token", help="Print a secure random bearer token (for serve-http / RBAC auth.toml)")
+    subparsers.add_parser("help", help="Show every command, grouped, with examples")
+
+    # Intercept an unrecognized command BEFORE argparse, whose error prints the full choice list and
+    # stops — a dead end for a one-character typo. Only a bare word is claimed here; anything
+    # starting with `-` (--version, --help) still goes to argparse.
+    argv = sys.argv[1:]
+    if argv and not argv[0].startswith("-") and argv[0] not in _COMMANDS + ["help"]:
+        sys.exit(_unknown_command(argv[0]))
+    if not argv or argv[0] == "help":
+        from codeintel import term
+        term.configure(no_color=False, ascii_mode=None)
+        print(render_help())
+        sys.exit(0)
 
     args = parser.parse_args()
 
@@ -464,7 +569,7 @@ def main() -> None:
         sys.exit(0)
 
     else:
-        parser.print_help()
+        print(render_help())
         sys.exit(0)
 
 

{codecortex-0.12.0 → codecortex-0.12.1}/src/codeintel/http_server.py

@@ -131,6 +131,13 @@ class _Handler(BaseHTTPRequestHandler):
         parsed["role"] = role  # server-authoritative — overrides any client-supplied role (no escalation)
         if self.path == "/code/doctor":
             result = code_doctor_handler(parsed)
+            # `registrations` (which agent hosts this machine registered codeintel with, and where)
+            # is a LOCAL diagnostic: on a shared deployment the server is not an agent host, so the
+            # field says nothing useful and only hands a client the server user's home layout and
+            # which agent tools are installed there. Dropped on the network transport; the CLI and
+            # the stdio MCP tool — both running as the user, on their own machine — still get it.
+            if isinstance(result, dict):
+                result.pop("registrations", None)
         else:
             result = code_query_handler(parsed)
         # An RBAC denial (query OR doctor) comes back as a safe-null with this reason — 403 it.

codecortex-0.12.1/tests/test_cli_help.py

@@ -0,0 +1,136 @@
+"""The CLI's front door: `codeintel help` and what happens when you mistype a command.
+
+argparse's default behavior on an unknown subcommand is to print the full list of choices and stop
+— a dead end for a one-character typo (`gragh`, `dector`), which is exactly how it gets hit. And its
+help lists twelve commands in declaration order with no grouping, so "what can this thing do?" means
+reading every line to find the one verb you wanted.
+
+The load-bearing invariant here is that the help screen stays HONEST: every command it advertises
+must actually be a registered subcommand, and every registered subcommand must be advertised.
+"""
+from __future__ import annotations
+
+import subprocess
+import sys
+
+import pytest
+
+from codeintel.__main__ import _COMMAND_GROUPS, _COMMANDS, _suggest, render_help
+
+
+def _run(*args, env_extra=None):
+    import os
+    env = {**os.environ, "NO_COLOR": "1", **(env_extra or {})}
+    return subprocess.run([sys.executable, "-m", "codeintel", *args],
+                          capture_output=True, text=True, timeout=120, env=env)
+
+
+# --------------------------------------------------------------------------- honesty
+
+def test_help_advertises_exactly_the_registered_subcommands():
+    """The drift that makes help worse than useless: a command renamed in argparse but not in the
+    help table, or advertised here and never wired up."""
+    listed = _run("--help").stdout
+    # argparse's own listing is the source of truth for what is actually registered.
+    registered = {line.split()[0] for line in listed.splitlines()
+                  if line.startswith("    ") and line.strip() and not line.startswith("     ")}
+    registered = {r for r in registered if not r.startswith("-")}
+    assert set(_COMMANDS) | {"help"} == registered
+
+
+def test_every_advertised_command_has_a_description():
+    for _group, items in _COMMAND_GROUPS:
+        for name, desc in items:
+            assert desc.strip(), name
+            assert len(desc) > 20, f"{name}: description is too thin to help anyone"
+
+
+def test_no_command_is_listed_in_two_groups():
+    assert len(_COMMANDS) == len(set(_COMMANDS))
+
+
+# --------------------------------------------------------------------------- help screen
+
+def test_bare_invocation_shows_the_grouped_help_and_exits_zero():
+    res = _run()
+    assert res.returncode == 0
+    for group, _items in _COMMAND_GROUPS:
+        assert group in res.stdout
+    assert "Examples" in res.stdout
+
+
+def test_help_subcommand_matches_the_bare_invocation():
+    assert _run("help").stdout == _run().stdout
+
+
+def test_help_lists_every_command_with_its_description():
+    out = _run("help").stdout
+    for name, desc in [(n, d) for _g, items in _COMMAND_GROUPS for n, d in items]:
+        assert name in out and desc in out
+
+
+def test_examples_stay_aligned_as_they_grow():
+    """A hardcoded comment column silently loses its gutter the moment an example outgrows it —
+    ljust() will not pad below the string's own length."""
+    lines = [ln for ln in _run("help").stdout.splitlines() if "  # " in ln]
+    assert len(lines) >= 3
+    assert len({ln.index("#") for ln in lines}) == 1      # one shared comment column
+
+
+def test_examples_only_reference_real_commands():
+    from codeintel.__main__ import _EXAMPLES
+    for cmd, _why in _EXAMPLES:
+        assert cmd.split()[0] == "codeintel"
+        assert cmd.split()[1] in _COMMANDS
+
+
+# --------------------------------------------------------------------------- typos
+
+@pytest.mark.parametrize("typo,expected", [
+    ("gragh", "graph"),        # observed in real use
+    ("dector", "doctor"),      # observed in real use
+    ("doctro", "doctor"),
+    ("instal", "install"),
+    ("quer", "query"),
+    ("statuss", "status"),
+])
+def test_a_typo_suggests_the_command_that_was_meant(typo, expected):
+    assert expected in _suggest(typo)
+
+
+def test_a_prefix_suggests_every_command_it_could_be():
+    assert set(_suggest("serve")) >= {"serve", "serve-http"}
+
+
+def test_unknown_command_exits_two_with_a_suggestion():
+    res = _run("gragh", ".", "--html")
+    assert res.returncode == 2
+    assert "unknown command: 'gragh'" in res.stderr
+    assert "did you mean" in res.stderr and "graph" in res.stderr
+    assert "codeintel help" in res.stderr
+
+
+def test_unrecognizable_input_still_points_at_help():
+    res = _run("zzzzzzzz")
+    assert res.returncode == 2
+    assert "codeintel help" in res.stderr      # no guess to offer, but never a dead end
+
+
+def test_flags_are_left_to_argparse():
+    """Only a bare word is claimed as a command — `--version` and `--help` must still work."""
+    assert _run("--version").returncode == 0
+    assert _run("--help").returncode == 0
+
+
+# --------------------------------------------------------------------------- color
+
+def test_color_is_stripped_when_not_a_tty():
+    assert "\x1b[" not in _run("help").stdout
+
+
+def test_no_color_beats_force_color():
+    assert "\x1b[" not in _run("help", env_extra={"FORCE_COLOR": "1"}).stdout
+
+
+def test_render_help_never_raises_without_a_terminal():
+    assert isinstance(render_help(), str) and render_help()

{codecortex-0.12.0 → codecortex-0.12.1}/tests/test_rbac.py

@@ -141,6 +141,16 @@ def test_rbac_reader_denied_doctor_is_403(rbac_server):
     assert status == 403 and body["reason"] == "op-not-allowed-for-role"
 
 
+def test_doctor_over_http_omits_local_registrations(rbac_server):
+    """`registrations` names the agent config files on THIS machine. A shared HTTP deployment is
+    not an agent host, so the field says nothing useful there and only leaks the server user's home
+    layout and which agent tools are installed. It stays on the local CLI / stdio MCP surfaces."""
+    status, body = _doctor(rbac_server, "admintok")
+    assert status == 200
+    assert "registrations" not in body
+    assert "engines" in body                       # the rest of the report is untouched
+
+
 def test_rbac_admin_allowed_doctor(rbac_server):
     status, body = _doctor(rbac_server, "admintok")     # admin is ["*"]
     assert status == 200 and body.get("reason") != "op-not-allowed-for-role"

codecortex-0.12.0/src/codeintel/__init__.py

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