codecortex 0.12.1__tar.gz → 0.13.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.12.1
+Version: 0.13.0
 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
@@ -9,7 +9,7 @@ Project-URL: Repository, https://github.com/hamilton-sky/codeintel
 Project-URL: Issues, https://github.com/hamilton-sky/codeintel/issues
 Project-URL: Changelog, https://github.com/hamilton-sky/codeintel/blob/main/CHANGELOG.md
 Keywords: mcp,model-context-protocol,code-intelligence,code-search,llm,agents,lsp,semantic-search,knowledge-graph,static-analysis,developer-tools
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Environment :: Console
 Classifier: Operating System :: OS Independent
@@ -29,7 +29,10 @@ Requires-Dist: fastembed>=0.3
 Requires-Dist: tree-sitter-language-pack>=1.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
 Requires-Dist: numpy>=1.24; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
 Dynamic: license-file
 
 # codeintel
@@ -414,7 +417,19 @@ 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            # ~410 tests, ~35s (live graph/LSP backend tests skip when absent)
+
+pytest tests/ -q            # ~494 tests, ~35s; fails under 83% coverage
+ruff check src tests        # lint
+mypy                        # types (src/ only)
+```
+
+**Your local run is not CI's run.** A dev machine usually has `codebase-memory-mcp` and `uvx`
+installed; CI has neither, so the live graph/LSP tests skip there *and* the never-raise envelopes
+take different `reason`/`hint` paths. A bug reachable only on the no-backend path passes at your
+desk and fails in CI. To see CI's shape before you push:
+
+```bash
+env PATH="$(dirname "$(which python)"):/usr/bin:/bin" pytest -q
 ```
 
 **Release gate.** The unit suite runs against the source tree, so it cannot see a packaging break, a

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

@@ -380,7 +380,19 @@ 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            # ~410 tests, ~35s (live graph/LSP backend tests skip when absent)
+
+pytest tests/ -q            # ~494 tests, ~35s; fails under 83% coverage
+ruff check src tests        # lint
+mypy                        # types (src/ only)
+```
+
+**Your local run is not CI's run.** A dev machine usually has `codebase-memory-mcp` and `uvx`
+installed; CI has neither, so the live graph/LSP tests skip there *and* the never-raise envelopes
+take different `reason`/`hint` paths. A bug reachable only on the no-backend path passes at your
+desk and fails in CI. To see CI's shape before you push:
+
+```bash
+env PATH="$(dirname "$(which python)"):/usr/bin:/bin" pytest -q
 ```
 
 **Release gate.** The unit suite runs against the source tree, so it cannot see a packaging break, a

codecortex-0.13.0/pyproject.toml

@@ -0,0 +1,139 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# Distribution name is `codecortex` because `codeintel` is taken on PyPI and `codeintel-*` names
+# are rejected as "too similar" to it. The import package and the CLI are still `codeintel`
+# (i.e. `pip install codecortex` installs the `codeintel` command).
+name = "codecortex"
+dynamic = ["version"]
+description = "Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Shammai Hamilton" }]
+keywords = [
+    "mcp", "model-context-protocol", "code-intelligence", "code-search", "llm", "agents",
+    "lsp", "semantic-search", "knowledge-graph", "static-analysis", "developer-tools",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+dependencies = [
+    "mcp>=1.0",
+    "sqlite-vec>=0.1",
+    "fastembed>=0.3",
+    "tree-sitter-language-pack>=1.0",  # def-aligned chunking for non-Python languages (P3)
+]
+
+[project.urls]
+Homepage = "https://github.com/hamilton-sky/codeintel"
+Repository = "https://github.com/hamilton-sky/codeintel"
+Issues = "https://github.com/hamilton-sky/codeintel/issues"
+Changelog = "https://github.com/hamilton-sky/codeintel/blob/main/CHANGELOG.md"
+
+[project.scripts]
+codeintel = "codeintel.__main__:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov>=5", "numpy>=1.24", "ruff>=0.16", "mypy>=1.11"]
+
+# Single source of truth for the version: read from codeintel.__version__ (AST-parsed, no import).
+[tool.setuptools.dynamic]
+version = { attr = "codeintel.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Ship the self-contained interactive graph viewer template with the wheel, and the PEP 561 marker
+# without which the `Typing :: Typed` classifier is a promise the installed package cannot keep —
+# type checkers ignore an installed package's annotations entirely unless py.typed is present.
+[tool.setuptools.package-data]
+"codeintel.viewer" = ["*.html"]
+"codeintel" = ["py.typed"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E", "W",   # pycodestyle
+    "F",        # pyflakes
+    "I",        # import sorting
+    "UP",       # pyupgrade — this is a >=3.11 package, so modern syntax is always available
+    "B",        # bugbear
+    "C4",       # comprehensions
+    "SIM",      # simplify
+    "PIE", "PERF", "RUF",
+    "S",        # bandit — the HTTP transport is a real network surface
+]
+ignore = [
+    # The never-raise contract IS the architecture: providers and handlers degrade to a `reason`
+    # string rather than propagate, and the best-effort refresh paths (graph reindex, map rewrite)
+    # are deliberately allowed to fail silently. These three rules flag that design at ~190 sites,
+    # so enforcing them would mean 190 `noqa`s asserting the same thing the module docstrings say.
+    "S110",     # try-except-pass
+    "S112",     # try-except-continue
+    "SIM105",   # "use contextlib.suppress" — see below
+    "S603",     # subprocess call — every one is an explicit argv list, never a shell string
+]
+# On SIM105 specifically: the suppressed blocks carry their reason on the `pass` line itself
+# (`pass  # code_embeddings is created lazily at first embed — may not exist yet`), and
+# contextlib.suppress has nowhere to put that. Losing 13 such explanations to gain a context
+# manager is a bad trade in code whose whole contract is degrading quietly.
+
+[tool.ruff.lint.per-file-ignores]
+# Tests stand up fake servers on loopback, assert on hardcoded fixture tokens, and shell out to
+# the CLI under test. Flagging that as a security finding is noise.
+"tests/*" = [
+    "S101", "S104", "S105", "S106", "S108", "S404", "S607",
+    "S310",     # urlopen against the loopback test server this same test just started
+    "E402",     # a few modules import after a skip guard, so a missing backend skips, not errors
+    "E501",     # fixture payloads (graph JSON, serena responses) are copied verbatim; rewrapping
+                # them would make them stop matching what the real backend returns
+    "E702",     # `a = 1; b = 2` setup one-liners
+    "SIM115",   # ad-hoc open() in assertions, inside tmp_path — nothing to leak
+    "UP031",    # %-format is the readable choice for templating source into a fake server
+]
+
+[tool.mypy]
+python_version = "3.11"
+files = ["src/codeintel"]
+# Deliberately not --strict: the provider seams cross into untyped third-party backends (mcp,
+# fastembed, sqlite-vec, tree-sitter), where demanding annotations buys noise rather than safety.
+# These flags catch the errors that actually bite — unreachable branches, bad returns, silent Any
+# propagation out of our own typed code.
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_unreachable = true
+warn_no_return = true
+no_implicit_optional = true
+check_untyped_defs = true
+
+[[tool.mypy.overrides]]
+# Don't type-check the backends themselves, and don't follow into them: `python_version = "3.11"`
+# makes mypy parse their stubs under 3.11 syntax rules, and numpy's (reached transitively through
+# fastembed) use 3.12 `type` statements — an error in a dependency's own stubs, not in our code.
+module = ["mcp.*", "fastembed.*", "sqlite_vec.*", "tree_sitter_language_pack.*", "numpy.*"]
+ignore_missing_imports = true
+follow_imports = "skip"
+
+[tool.pytest.ini_options]
+# The floor sits below the current number (85.3% with every backend present) on purpose: the live
+# graph/LSP tests skip when codebase-memory-mcp and uvx/serena are absent, which is exactly the
+# case in CI, and that costs ~0.4 points. A floor pinned to today's measurement would go red on a
+# runner's toolchain rather than on a real coverage regression. Ratchet it up deliberately.
+addopts = "--cov=codeintel --cov-report=term-missing:skip-covered --cov-fail-under=83"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.12.1
+Version: 0.13.0
 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
@@ -9,7 +9,7 @@ Project-URL: Repository, https://github.com/hamilton-sky/codeintel
 Project-URL: Issues, https://github.com/hamilton-sky/codeintel/issues
 Project-URL: Changelog, https://github.com/hamilton-sky/codeintel/blob/main/CHANGELOG.md
 Keywords: mcp,model-context-protocol,code-intelligence,code-search,llm,agents,lsp,semantic-search,knowledge-graph,static-analysis,developer-tools
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Environment :: Console
 Classifier: Operating System :: OS Independent
@@ -29,7 +29,10 @@ Requires-Dist: fastembed>=0.3
 Requires-Dist: tree-sitter-language-pack>=1.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
 Requires-Dist: numpy>=1.24; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
 Dynamic: license-file
 
 # codeintel
@@ -414,7 +417,19 @@ 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            # ~410 tests, ~35s (live graph/LSP backend tests skip when absent)
+
+pytest tests/ -q            # ~494 tests, ~35s; fails under 83% coverage
+ruff check src tests        # lint
+mypy                        # types (src/ only)
+```
+
+**Your local run is not CI's run.** A dev machine usually has `codebase-memory-mcp` and `uvx`
+installed; CI has neither, so the live graph/LSP tests skip there *and* the never-raise envelopes
+take different `reason`/`hint` paths. A bug reachable only on the no-backend path passes at your
+desk and fails in CI. To see CI's shape before you push:
+
+```bash
+env PATH="$(dirname "$(which python)"):/usr/bin:/bin" pytest -q
 ```
 
 **Release gate.** The unit suite runs against the source tree, so it cannot see a packaging break, a

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

@@ -25,6 +25,7 @@ src/codeintel/metrics.py
 src/codeintel/onboarding.py
 src/codeintel/policy.py
 src/codeintel/provider.py
+src/codeintel/py.typed
 src/codeintel/reindexer.py
 src/codeintel/reset.py
 src/codeintel/searcher.py
@@ -32,6 +33,20 @@ src/codeintel/semantic_db.py
 src/codeintel/server.py
 src/codeintel/term.py
 src/codeintel/verify.py
+src/codeintel/commands/__init__.py
+src/codeintel/commands/_common.py
+src/codeintel/commands/doctor.py
+src/codeintel/commands/gen_token.py
+src/codeintel/commands/graph.py
+src/codeintel/commands/index.py
+src/codeintel/commands/install.py
+src/codeintel/commands/map.py
+src/codeintel/commands/query.py
+src/codeintel/commands/reset.py
+src/codeintel/commands/serve.py
+src/codeintel/commands/serve_http.py
+src/codeintel/commands/setup.py
+src/codeintel/commands/status.py
 src/codeintel/providers/__init__.py
 src/codeintel/providers/graph.py
 src/codeintel/providers/lsp.py
@@ -41,6 +56,7 @@ src/codeintel/viewer/__init__.py
 src/codeintel/viewer/graph_template.html
 tests/test_cache.py
 tests/test_chunking.py
+tests/test_cli_commands.py
 tests/test_cli_help.py
 tests/test_config.py
 tests/test_doctor.py

{codecortex-0.12.1 → codecortex-0.13.0}/src/codecortex.egg-info/requires.txt

@@ -5,4 +5,7 @@ tree-sitter-language-pack>=1.0
 
 [dev]
 pytest>=8
+pytest-cov>=5
 numpy>=1.24
+ruff>=0.16
+mypy>=1.11

codecortex-0.13.0/src/codeintel/__init__.py

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

codecortex-0.13.0/src/codeintel/__main__.py

@@ -0,0 +1,273 @@
+import argparse
+import difflib
+import sys
+from importlib import import_module
+
+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]
+
+# Each command's body lives in codeintel.commands.<module> as `run(args) -> int`. The mapping is
+# spelled out rather than derived from the command name so the target of any command is greppable,
+# and the import happens at dispatch time so `codeintel serve` never pays for the semantic
+# engine's imports (nor serve-http for the graph's).
+_MODULES = {
+    "query": "query",
+    "map": "map",
+    "graph": "graph",
+    "setup": "setup",
+    "index": "index",
+    "install": "install",
+    "doctor": "doctor",
+    "status": "status",
+    "reset": "reset",
+    "serve": "serve",
+    "serve-http": "serve_http",
+    "gen-token": "gen_token",
+}
+
+_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")
+    parser.add_argument("--version", action="version", version=f"codeintel {__version__}")
+    subparsers = parser.add_subparsers(dest="command")
+
+    # Shared flags for the human-facing (styled) commands.
+    color_parent = argparse.ArgumentParser(add_help=False)
+    color_parent.add_argument("--no-color", action="store_true", help="Disable ANSI color output")
+    color_parent.add_argument("--ascii", action="store_true", help="Use ASCII-only glyphs")
+
+    subparsers.add_parser("serve", help="Start the MCP server")
+
+    # index subcommand
+    index_parser = subparsers.add_parser("index", help="Index a project for semantic search")
+    index_parser.add_argument(
+        "project_root",
+        nargs="?",
+        default=None,
+        help="Project root directory (default: cwd)",
+    )
+
+    # query subcommand
+    query_parser = subparsers.add_parser("query", help="Query the code intelligence engine")
+    query_parser.add_argument("--op", required=True, help="Query operation (e.g. search, symbol)")
+    query_parser.add_argument("--target", required=True, help="Query target")
+    query_parser.add_argument("--engine", default="auto", help="Engine to use (default: auto)")
+    query_parser.add_argument(
+        "--project-root",
+        default=None,
+        help="Project root directory (default: cwd)",
+    )
+
+    # status subcommand
+    status_parser = subparsers.add_parser("status", help="Show code intelligence engine status")
+    status_parser.add_argument(
+        "project_root",
+        nargs="?",
+        default=None,
+        help="Project root directory (default: cwd)",
+    )
+
+    # serve-http subcommand
+    http_parser = subparsers.add_parser("serve-http", help="Start the HTTP transport server")
+    http_parser.add_argument("--port", type=int, default=8766, help="Port to listen on (default: 8766)")
+    http_parser.add_argument("--host", default="127.0.0.1", help="Host to bind to (default: 127.0.0.1)")
+    http_parser.add_argument("--allow-remote", action="store_true",
+                             help="Permit binding a non-loopback host (use with --token, or the "
+                                  "endpoint is UNAUTHENTICATED)")
+    http_parser.add_argument("--token", default=None,
+                             help="Require this bearer token on every request (or set "
+                                  "CODEINTEL_HTTP_TOKEN). Strongly recommended with --allow-remote.")
+
+    # install subcommand
+    install_parser = subparsers.add_parser("install", help="Register codeintel with AI agents")
+    install_parser.add_argument(
+        "--agent",
+        choices=["auto", "claude", "codex", "gemini", "zed", "all"],
+        default="auto",
+        help="Agent to register with (default: auto — only agents installed on this machine; "
+             "`all` forces every supported agent)",
+    )
+    install_parser.add_argument(
+        "--no-verify",
+        action="store_true",
+        help="Skip the post-registration MCP handshake (verification is on by default)",
+    )
+    install_parser.add_argument(
+        "--relative-command",
+        action="store_true",
+        help="Register the bare `codeintel` name instead of its absolute path (the absolute path "
+             "is the default because a GUI-launched agent does not inherit your shell's PATH)",
+    )
+
+    # map subcommand
+    map_parser = subparsers.add_parser("map", help="Generate CODE_INTEL.md orientation file")
+    map_parser.add_argument("project_root", nargs="?", default=None)
+    map_parser.add_argument("--inject", action="store_true", help="Inject reference block into CLAUDE.md/AGENTS.md")
+    map_parser.add_argument("--budget", type=int, default=32768, help="Byte budget for CODE_INTEL.md (default: 32768)")
+
+    # graph subcommand — interactive call-graph view (HTML) or the raw {nodes,edges} JSON
+    graph_parser = subparsers.add_parser(
+        "graph", help="Build an interactive call-graph view (--html) or emit the graph as JSON — "
+                      "works on any indexed repo")
+    graph_parser.add_argument("project_root", nargs="?", default=None, help="Project root (default: cwd)")
+    graph_parser.add_argument("--html", action="store_true",
+                              help="Write a self-contained interactive HTML viewer (default: print JSON)")
+    graph_parser.add_argument("--out", default=None, help="Output path for --html (default: codeintel-graph.html)")
+    graph_parser.add_argument("--limit", type=int, default=220, help="Max call edges to include (default: 220)")
+
+    # doctor subcommand
+    doctor_parser = subparsers.add_parser("doctor", parents=[color_parent],
+                                          help="Diagnose engine health + index status for a repo")
+    doctor_parser.add_argument("project_root", nargs="?", default=None, help="Project root (default: cwd)")
+    doctor_parser.add_argument("--deep", action="store_true",
+                               help="Also boot-check serena (slower; first boot pulls it via uvx)")
+    doctor_parser.add_argument("--json", action="store_true",
+                               help="Emit the structured JSON report instead of the table")
+
+    # setup subcommand
+    setup_parser = subparsers.add_parser("setup", parents=[color_parent],
+                                         help="Prepare backends and optionally index this repo")
+    setup_parser.add_argument("project_root", nargs="?", default=None, help="Project root (default: cwd)")
+    setup_parser.add_argument("--all", action="store_true", dest="all_steps",
+                              help="One-command setup: do everything automatable (uv + deps + index + "
+                                   "warm serena). Idempotent — skips what's already installed.")
+    setup_parser.add_argument("--install-uv", action="store_true",
+                              help="Run `pip install uv` (provides uvx for the LSP engine)")
+    setup_parser.add_argument("--install-deps", action="store_true",
+                              help="Run `pip install -e .` (semantic engine deps)")
+    setup_parser.add_argument("--index", action="store_true",
+                              help="Index this repo now (first run downloads the ~50MB model)")
+    setup_parser.add_argument("--warm", action="store_true", help="Boot serena now (first run pulls it via uvx; slow)")
+    setup_parser.add_argument("--json", action="store_true", help="Emit the structured JSON report")
+
+    # reset subcommand
+    reset_parser = subparsers.add_parser("reset", parents=[color_parent],
+                                         help="Clear the semantic index (recover from a corrupt/stale DB)")
+    reset_parser.add_argument("project_root", nargs="?", default=None, help="Project root (default: cwd)")
+    reset_parser.add_argument("--all", action="store_true",
+                              help="Clear the ENTIRE index (all projects), not just this repo")
+    reset_parser.add_argument("--yes", "-y", action="store_true", help="Skip the confirmation prompt")
+    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()
+
+    from codeintel import term
+    term.configure(
+        no_color=getattr(args, "no_color", False),
+        ascii_mode=(True if getattr(args, "ascii", False) else None),
+    )
+
+    module = _MODULES.get(args.command)
+    if module is None:          # unreachable via argparse; a bare `codeintel` is handled above
+        print(render_help())
+        sys.exit(0)
+    sys.exit(import_module(f"codeintel.commands.{module}").run(args))
+
+
+if __name__ == "__main__":
+    main()

{codecortex-0.12.1 → codecortex-0.13.0}/src/codeintel/auth.py

@@ -25,7 +25,6 @@ import logging
 import os
 import pathlib
 import tomllib  # stdlib on Python 3.11+ (the project's minimum)
-from typing import Dict, List, Optional
 
 from codeintel.policy import TieringPolicy
 
@@ -39,7 +38,7 @@ class TokenAuth:
     """Resolves a bearer token to a role and builds the matching op policy. Tokens are held as
     sha256 hashes; a presented token is hashed and looked up in O(1). Immutable; thread-safe."""
 
-    def __init__(self, token_hash_to_role: Dict[str, str], role_ops: Dict[str, List[str]]) -> None:
+    def __init__(self, token_hash_to_role: dict[str, str], role_ops: dict[str, list[str]]) -> None:
         self._tokens = token_hash_to_role
         self._role_ops = role_ops
 
@@ -47,7 +46,7 @@ class TokenAuth:
     def enabled(self) -> bool:
         return bool(self._tokens)
 
-    def role_for(self, presented_token: str) -> Optional[str]:
+    def role_for(self, presented_token: str) -> str | None:
         """The role for a presented token, or None if it isn't a known token."""
         if not presented_token:
             return None
@@ -58,7 +57,7 @@ class TokenAuth:
         """A role with ops ``["*"]`` (or none) is unrestricted → omit it from the rules, since
         TieringPolicy treats a role absent from its rules as full-access. Every other role maps to
         its explicit op allowlist (an empty list = deny all ops, a fail-safe default)."""
-        rules: Dict[str, List[str]] = {}
+        rules: dict[str, list[str]] = {}
         for role, ops in self._role_ops.items():
             if _ALL in ops:
                 continue  # unrestricted
@@ -66,7 +65,7 @@ class TokenAuth:
         return TieringPolicy(enabled=bool(rules), rules=rules)
 
 
-def _auth_config_path() -> Optional[pathlib.Path]:
+def _auth_config_path() -> pathlib.Path | None:
     env = os.environ.get("CODEINTEL_AUTH_CONFIG", "").strip()
     if env:
         p = pathlib.Path(env)
@@ -88,8 +87,9 @@ def load_auth() -> TokenAuth:
         logger.warning("auth: %s could not be parsed (%s) — RBAC is OFF", path, type(exc).__name__)
         return TokenAuth({}, {})
 
-    raw_roles = data.get("roles") if isinstance(data.get("roles"), dict) else {}
-    role_ops: Dict[str, List[str]] = {}
+    roles_section = data.get("roles")
+    raw_roles: dict = roles_section if isinstance(roles_section, dict) else {}
+    role_ops: dict[str, list[str]] = {}
     for role, ops in raw_roles.items():
         if isinstance(ops, list):
             role_ops[str(role)] = [str(o) for o in ops]
@@ -99,8 +99,9 @@ def load_auth() -> TokenAuth:
             logger.warning("auth: role %r ops must be a list (got %r) — denying all ops for it", role, ops)
             role_ops[str(role)] = []
 
-    raw_tokens = data.get("tokens") if isinstance(data.get("tokens"), dict) else {}
-    token_hash_to_role: Dict[str, str] = {}
+    tokens_section = data.get("tokens")
+    raw_tokens: dict = tokens_section if isinstance(tokens_section, dict) else {}
+    token_hash_to_role: dict[str, str] = {}
     for tok, role in raw_tokens.items():
         role = str(role)
         # A token mapped to an undefined role fails safe: define it as deny-all (empty op list).