codecortex 0.9.0__tar.gz → 0.10.0__tar.gz

{codecortex-0.9.0/src/codecortex.egg-info → codecortex-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.9.0
+Version: 0.10.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
@@ -60,10 +60,13 @@ It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the defa
 | 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 |
+| Trace a call chain up/downstream | `chain` | graph | ordered, risk-labeled 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 |
+| **Impact of your uncommitted edits** | `changed` | graph | changed files → impacted symbols |
+| Refactor-risk hotspots | `hotspots` | graph | highest complexity / fan-in symbols |
+| Unreferenced (dead) code | `deadcode` | graph | non-test symbols with no callers |
 
 Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
 
@@ -99,11 +102,21 @@ The agent hands `result` straight to the model. If the graph backend isn't insta
 pip install codecortex
 ```
 
-This installs the `codeintel` CLI; the **semantic** engine works out of the box. The **graph**
-and **LSP** engines use external backends (`codebase-memory-mcp`, and serena via `uvx`) —
-run `codeintel doctor` to see what's available and how to enable the rest. (On PyPI the
+This installs the `codeintel` CLI; the **semantic** engine works out of the box. (On PyPI the
 distribution is `codecortex` because `codeintel` was taken; the CLI and import stay `codeintel`.)
 
+**One command prepares the rest and indexes your repo:**
+
+```bash
+codeintel setup --all /path/to/your/project
+```
+
+This installs `uv` (for the LSP engine), warms serena, downloads the embedding model, indexes the
+repo, and prints a health report ending in a **Next:** list — exactly what's ready and the one
+remaining step. It's idempotent, so re-running is safe. The **graph** engine (`codebase-memory-mcp`)
+is an *optional* external binary that adds who-calls / impact / hotspots / `changed`; codeintel is
+fully usable without it.
+
 Or from source:
 
 ```bash
@@ -112,17 +125,10 @@ cd codeintel
 pip install -e .
 ```
 
-Register with your AI agent(s):
+Register with your AI agent(s), then query:
 
 ```bash
 codeintel install            # registers with Claude, Codex, Gemini, Zed
-```
-
-Index a project, check what's ready, and run your first query:
-
-```bash
-codeintel index /path/to/your/project
-codeintel doctor /path/to/your/project    # which engines are ready + how to fix the rest
 codeintel query --op search --target "authentication middleware"
 ```
 
@@ -174,6 +180,7 @@ 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).
 - **[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.
 - Engine references: **[graph](docs/graph.md)** · **[lsp](docs/lsp.md)** · **[semantic](docs/semantic.md)**.
 
 ## CLI reference
@@ -181,7 +188,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | Command | Purpose |
 |---|---|
 | `codeintel install [--agent claude\|codex\|gemini\|zed\|all]` | Register codeintel with AI agent(s) |
-| `codeintel setup [project_root] [--index] [--warm] [--install-uv]` | Check backends + optionally index this repo; ends with a health report |
+| `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 |
 | `codeintel serve` | Start the MCP server (stdio transport) |
 | `codeintel serve-http [--host HOST] [--port 8766] [--allow-remote] [--token TOKEN]` | Start the HTTP transport (loopback-only unless `--allow-remote`; `--token` requires a bearer token on every request) |

{codecortex-0.9.0 → codecortex-0.10.0}/README.md

@@ -26,10 +26,13 @@ It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the defa
 | 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 |
+| Trace a call chain up/downstream | `chain` | graph | ordered, risk-labeled 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 |
+| **Impact of your uncommitted edits** | `changed` | graph | changed files → impacted symbols |
+| Refactor-risk hotspots | `hotspots` | graph | highest complexity / fan-in symbols |
+| Unreferenced (dead) code | `deadcode` | graph | non-test symbols with no callers |
 
 Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
 
@@ -65,11 +68,21 @@ The agent hands `result` straight to the model. If the graph backend isn't insta
 pip install codecortex
 ```
 
-This installs the `codeintel` CLI; the **semantic** engine works out of the box. The **graph**
-and **LSP** engines use external backends (`codebase-memory-mcp`, and serena via `uvx`) —
-run `codeintel doctor` to see what's available and how to enable the rest. (On PyPI the
+This installs the `codeintel` CLI; the **semantic** engine works out of the box. (On PyPI the
 distribution is `codecortex` because `codeintel` was taken; the CLI and import stay `codeintel`.)
 
+**One command prepares the rest and indexes your repo:**
+
+```bash
+codeintel setup --all /path/to/your/project
+```
+
+This installs `uv` (for the LSP engine), warms serena, downloads the embedding model, indexes the
+repo, and prints a health report ending in a **Next:** list — exactly what's ready and the one
+remaining step. It's idempotent, so re-running is safe. The **graph** engine (`codebase-memory-mcp`)
+is an *optional* external binary that adds who-calls / impact / hotspots / `changed`; codeintel is
+fully usable without it.
+
 Or from source:
 
 ```bash
@@ -78,17 +91,10 @@ cd codeintel
 pip install -e .
 ```
 
-Register with your AI agent(s):
+Register with your AI agent(s), then query:
 
 ```bash
 codeintel install            # registers with Claude, Codex, Gemini, Zed
-```
-
-Index a project, check what's ready, and run your first query:
-
-```bash
-codeintel index /path/to/your/project
-codeintel doctor /path/to/your/project    # which engines are ready + how to fix the rest
 codeintel query --op search --target "authentication middleware"
 ```
 
@@ -140,6 +146,7 @@ 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).
 - **[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.
 - Engine references: **[graph](docs/graph.md)** · **[lsp](docs/lsp.md)** · **[semantic](docs/semantic.md)**.
 
 ## CLI reference
@@ -147,7 +154,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | Command | Purpose |
 |---|---|
 | `codeintel install [--agent claude\|codex\|gemini\|zed\|all]` | Register codeintel with AI agent(s) |
-| `codeintel setup [project_root] [--index] [--warm] [--install-uv]` | Check backends + optionally index this repo; ends with a health report |
+| `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 |
 | `codeintel serve` | Start the MCP server (stdio transport) |
 | `codeintel serve-http [--host HOST] [--port 8766] [--allow-remote] [--token TOKEN]` | Start the HTTP transport (loopback-only unless `--allow-remote`; `--token` requires a bearer token on every request) |

{codecortex-0.9.0 → codecortex-0.10.0/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.9.0
+Version: 0.10.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
@@ -60,10 +60,13 @@ It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the defa
 | 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 |
+| Trace a call chain up/downstream | `chain` | graph | ordered, risk-labeled 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 |
+| **Impact of your uncommitted edits** | `changed` | graph | changed files → impacted symbols |
+| Refactor-risk hotspots | `hotspots` | graph | highest complexity / fan-in symbols |
+| Unreferenced (dead) code | `deadcode` | graph | non-test symbols with no callers |
 
 Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
 
@@ -99,11 +102,21 @@ The agent hands `result` straight to the model. If the graph backend isn't insta
 pip install codecortex
 ```
 
-This installs the `codeintel` CLI; the **semantic** engine works out of the box. The **graph**
-and **LSP** engines use external backends (`codebase-memory-mcp`, and serena via `uvx`) —
-run `codeintel doctor` to see what's available and how to enable the rest. (On PyPI the
+This installs the `codeintel` CLI; the **semantic** engine works out of the box. (On PyPI the
 distribution is `codecortex` because `codeintel` was taken; the CLI and import stay `codeintel`.)
 
+**One command prepares the rest and indexes your repo:**
+
+```bash
+codeintel setup --all /path/to/your/project
+```
+
+This installs `uv` (for the LSP engine), warms serena, downloads the embedding model, indexes the
+repo, and prints a health report ending in a **Next:** list — exactly what's ready and the one
+remaining step. It's idempotent, so re-running is safe. The **graph** engine (`codebase-memory-mcp`)
+is an *optional* external binary that adds who-calls / impact / hotspots / `changed`; codeintel is
+fully usable without it.
+
 Or from source:
 
 ```bash
@@ -112,17 +125,10 @@ cd codeintel
 pip install -e .
 ```
 
-Register with your AI agent(s):
+Register with your AI agent(s), then query:
 
 ```bash
 codeintel install            # registers with Claude, Codex, Gemini, Zed
-```
-
-Index a project, check what's ready, and run your first query:
-
-```bash
-codeintel index /path/to/your/project
-codeintel doctor /path/to/your/project    # which engines are ready + how to fix the rest
 codeintel query --op search --target "authentication middleware"
 ```
 
@@ -174,6 +180,7 @@ 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).
 - **[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.
 - Engine references: **[graph](docs/graph.md)** · **[lsp](docs/lsp.md)** · **[semantic](docs/semantic.md)**.
 
 ## CLI reference
@@ -181,7 +188,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | Command | Purpose |
 |---|---|
 | `codeintel install [--agent claude\|codex\|gemini\|zed\|all]` | Register codeintel with AI agent(s) |
-| `codeintel setup [project_root] [--index] [--warm] [--install-uv]` | Check backends + optionally index this repo; ends with a health report |
+| `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 |
 | `codeintel serve` | Start the MCP server (stdio transport) |
 | `codeintel serve-http [--host HOST] [--port 8766] [--allow-remote] [--token TOKEN]` | Start the HTTP transport (loopback-only unless `--allow-remote`; `--token` requires a bearer token on every request) |

codecortex-0.10.0/src/codeintel/__init__.py

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

{codecortex-0.9.0 → codecortex-0.10.0}/src/codeintel/__main__.py

@@ -77,6 +77,9 @@ def main() -> None:
     # 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)")
@@ -284,12 +287,13 @@ def main() -> None:
             from codeintel import onboarding
 
             project_root = args.project_root or os.getcwd()
+            all_steps = getattr(args, "all_steps", False)  # --all implies every automatable step
             report = onboarding.run_setup(
                 project_root,
-                install_uv=args.install_uv,
-                install_deps=args.install_deps,
-                do_index=args.index,
-                warm_lsp=args.warm,
+                install_uv=args.install_uv or all_steps,
+                install_deps=args.install_deps or all_steps,
+                do_index=args.index or all_steps,
+                warm_lsp=args.warm or all_steps,
             )
             if args.json:
                 import json as _json

{codecortex-0.9.0 → codecortex-0.10.0}/src/codeintel/doctor.py

@@ -11,6 +11,9 @@ import os
 from typing import Any, Callable, Optional
 
 _ENGINES = ("graph", "lsp", "semantic")
+# Graph needs an external native binary (codebase-memory-mcp) codeintel can't auto-install, so a
+# missing graph engine does NOT make a repo "unhealthy" — the tool is fully usable on semantic + lsp.
+_OPTIONAL_ENGINES = frozenset({"graph"})
 
 
 def _status_for(report: dict) -> str:
@@ -112,13 +115,17 @@ def run_doctor(
         treesitter = False
 
     ready = sum(1 for e in engines.values() if e.get("status") != "fail")
+    # "healthy" ignores OPTIONAL engines (graph): a repo with semantic + lsp ready is healthy even
+    # without the external graph binary. `ready`/`total` stay literal (all three) for transparency.
+    healthy = all(
+        e.get("status") != "fail" for n, e in engines.items() if n not in _OPTIONAL_ENGINES
+    )
     return {
         "ok": True,
         "project_root": root,
         "deep": bool(deep),
         "treesitter": treesitter,
-        "summary": {"ready": ready, "total": len(engines),
-                    "healthy": all(e.get("status") != "fail" for e in engines.values())},
+        "summary": {"ready": ready, "total": len(engines), "healthy": healthy},
         "engines": engines,
     }
 
@@ -168,10 +175,16 @@ def render_doctor_text(report: dict) -> str:
     tail = "" if report.get("deep") else c.dim("  (run with --deep to boot-check serena)")
     out.append("")
     out.append(f"  {count} engines ready for this repo.{tail}")
+    opt_down = [n for n in _ENGINES
+                if n in _OPTIONAL_ENGINES and (engines.get(n) or {}).get("status") == "fail"]
+    if opt_down:
+        out.append("  " + c.dim(
+            f"({', '.join(opt_down)} optional — an external backend; codeintel works without it)"
+        ))
     if healthy is False:
         out.append("  " + c.dim(
-            "tip: `codeintel setup --install-uv --install-deps --index` bootstraps the "
-            "pip-installable backends; each fix: line above has the per-engine command."
+            "tip: `codeintel setup --all` installs + indexes everything automatable in one command; "
+            "each fix: line above has the per-engine command."
         ))
     if report.get("treesitter") is False:
         out.append("  " + c.dim(

{codecortex-0.9.0 → codecortex-0.10.0}/src/codeintel/onboarding.py

@@ -17,12 +17,25 @@ from codeintel import doctor
 _ENGINES = ("graph", "lsp", "semantic")
 
 
+def _platform_tag() -> str:
+    """Best-effort ``System/arch`` (e.g. ``Darwin/arm64``) for platform-specific guidance."""
+    try:
+        import platform
+        return f"{platform.system() or 'your-OS'}/{platform.machine() or 'your-arch'}"
+    except Exception:
+        return "your platform"
+
+
 def _guidance_for(engine: str, probe: dict) -> str:
     """One-line install instructions for an engine that is not installed."""
     try:
         if engine == "graph":
-            return ("install codebase-memory-mcp (a platform-specific binary) and ensure "
-                    "it's on PATH — see its project; then `codeintel index`")
+            # codebase-memory-mcp is a standalone native binary distributed by its own project —
+            # codeintel can't (and shouldn't) auto-download a third-party binary. Frame it as the
+            # OPTIONAL add-on it is: the tool is fully usable on semantic + LSP without it.
+            return (f"OPTIONAL (adds who-calls / impact / hotspots / changed): install the "
+                    f"codebase-memory-mcp binary for {_platform_tag()} on PATH, then re-run setup — "
+                    f"codeintel works without it")
         if engine == "lsp":
             return "install uv (provides uvx): pip install uv — serena is fetched on first use"
         if engine == "semantic":
@@ -123,10 +136,10 @@ def run_setup(
         root = str(project_root or "")
 
     try:
-        if warm_lsp:
-            print("  first serena launch fetches it via uvx; this can be slow the first time…", file=out)
         try:
-            report0 = doctor.run_doctor(root, deep=warm_lsp, lsp_deep_timeout_s=lsp_warm_timeout_s)
+            # Shallow diagnose only — the warm/deep serena boot happens AFTER the install loop (below)
+            # so a freshly-installed uv is visible to it (see the warm_lsp block).
+            report0 = doctor.run_doctor(root, deep=False)
             engines0 = report0.get("engines", {}) if isinstance(report0, dict) else {}
         except Exception as exc:
             engines0 = {}
@@ -136,11 +149,18 @@ def run_setup(
             if probe.get("installed") is False:
                 _step(f"{name}: preflight", probe.get("status", "fail"), _guidance_for(name, probe))
 
-        for flag, pkg_args, step_name in (
-            (install_uv, ["uv"], "install uv"),
-            (install_deps, ["-e", "."], "install deps (-e .)"),
+        # Idempotent installs: skip when the engine already reports installed, so `--all` and re-runs
+        # don't reinstall (lsp installed ⇒ uv/uvx present; semantic installed ⇒ deps present).
+        lsp_installed = (engines0.get("lsp") or {}).get("installed") is True
+        semantic_installed = (engines0.get("semantic") or {}).get("installed") is True
+        for flag, pkg_args, step_name, already in (
+            (install_uv, ["uv"], "install uv", lsp_installed),
+            (install_deps, ["-e", "."], "install deps (-e .)", semantic_installed),
         ):
             if flag:
+                if already:
+                    _step(step_name, "ok", "already satisfied — skipped")
+                    continue
                 r = _pip_install(pkg_args, out=out)
                 _step(step_name, "ok" if r["ok"] else "fail", r["detail"])
 
@@ -157,8 +177,17 @@ def run_setup(
                 _step("index: graph", "warn", f"graph reindex skipped ({type(exc).__name__})")
 
         if warm_lsp:
-            lsp = engines0.get("lsp") or {}
-            _step("warm lsp", lsp.get("status", "warn"), lsp.get("detail", ""))
+            # Warm with a FRESH deep probe AFTER the install loop: on a fresh machine uv was just
+            # installed above, so the pre-install preflight would report lsp missing — emitting a
+            # stale, self-contradictory "warm lsp: fail" under "install uv: ok". Re-probe so the boot
+            # actually runs against the now-present uvx.
+            print("  first serena launch fetches it via uvx; this can be slow the first time…", file=out)
+            try:
+                from codeintel.providers.lsp import LspProvider
+                wl = LspProvider().probe(root, deep=True, timeout_s=lsp_warm_timeout_s)
+                _step("warm lsp", doctor._status_for({**wl, "engine": "lsp"}), wl.get("detail", ""))
+            except Exception as exc:
+                _step("warm lsp", "warn", f"warm attempt failed ({type(exc).__name__})")
 
         try:
             final_doctor = doctor.run_doctor(root)
@@ -170,6 +199,31 @@ def run_setup(
                 "detail": f"setup failed ({type(exc).__name__})"}
 
 
+def _next_steps(doctor_report: dict, root: str) -> list[str]:
+    """The crisp 'what's left' list after a setup pass, computed from the final doctor state —
+    so a user knows the ONE remaining action instead of parsing the engine table."""
+    try:
+        out: list[str] = []
+        engines = doctor_report.get("engines") if isinstance(doctor_report, dict) else None
+        engines = engines if isinstance(engines, dict) else {}
+        _get = lambda name: engines.get(name) if isinstance(engines.get(name), dict) else {}
+        sem, lsp, graph = _get("semantic"), _get("lsp"), _get("graph")
+        if sem.get("installed") is not True:
+            out.append("Semantic engine deps missing — pip install fastembed sqlite-vec")
+        elif sem.get("repo_indexed") is False:
+            out.append(f"Index this repo — codeintel index {root}")
+        if lsp.get("installed") is not True:
+            out.append("LSP engine — pip install uv  (serena auto-fetched on first use)")
+        if graph.get("installed") is not True:
+            out.append(f"Graph engine (OPTIONAL — who-calls/impact/hotspots/changed) — put the "
+                       f"codebase-memory-mcp binary for {_platform_tag()} on PATH")
+        # Always the last mile: an installed+indexed tool does nothing until the agent knows about it.
+        out.append("Make your AI agent use it — codeintel install")
+        return out
+    except Exception:
+        return []
+
+
 def render_setup_text(report: dict) -> str:
     """Human CLI view: a ``[n/N]`` step list, the doctor table, then the overall summary."""
     from codeintel.term import c  # imported at call time so the CLI's term.configure() is honored
@@ -184,14 +238,24 @@ def render_setup_text(report: dict) -> str:
             tail = f"  {c.dim(str(detail))}" if detail else ""
             name = c.bold(str(step.get("name", "")))
             lines.append(f"  [{i}/{n}] {c.glyph(step.get('status', 'na'))} {name}{tail}")
-        if not steps:
-            lines.append(c.dim("  (nothing to do — no opt-in flags set)"))
+        _ACTION_STEPS = {"install uv", "install deps (-e .)", "index: semantic", "index: graph", "warm lsp"}
+        if not any(s.get("name") in _ACTION_STEPS for s in steps):
+            lines.append(c.dim("  (diagnose only — run `codeintel setup --all` to install + index "
+                               "everything automatically)"))
         lines.append("")
         try:
             from codeintel.doctor import render_doctor_text
             lines.append(render_doctor_text(report.get("doctor") or {}))
         except Exception:
             lines.append(c.dim("(doctor report unavailable)"))
+
+        nexts = _next_steps(report.get("doctor") or {}, root)
+        if nexts:
+            lines.append("")
+            lines.append(c.bold("Next:"))
+            for step in nexts:
+                lines.append("  " + c.cyan("→") + " " + step)
+
         lines.append("")
         lines.append(c.green("setup finished") if report.get("ok") else c.red("setup did not complete cleanly"))
         return "\n".join(lines)

{codecortex-0.9.0 → codecortex-0.10.0}/tests/test_doctor.py

@@ -83,6 +83,24 @@ def test_run_doctor_reports_treesitter_availability():
     assert isinstance(r.get("treesitter"), bool)   # always reported (bool), never raises
 
 
+def test_healthy_ignores_optional_graph_engine():
+    # graph is optional (external binary) — its absence must NOT mark a repo unhealthy or exit 1.
+    class _Stub:
+        available = True
+        def __init__(self, installed, runnable=True, indexed=True):
+            self._d = {"installed": installed, "runnable": runnable, "repo_indexed": indexed,
+                       "detail": "", "remediation": None}
+        def probe(self, *a, **k):
+            return dict(self._d)
+
+    r = doctor.run_doctor("/repo", graph=_Stub(False, False, False),
+                          lsp=_Stub(True), semantic=_Stub(True))
+    assert r["engines"]["graph"]["status"] == "fail"
+    assert r["summary"]["healthy"] is True          # semantic + lsp ready ⇒ healthy despite graph
+    text = doctor.render_doctor_text(r)
+    assert "optional" in text                        # render frames graph as optional, not a failure
+
+
 # --------------------------------------------------------------------------- #
 # never-raise + no-hang orchestration
 # --------------------------------------------------------------------------- #

codecortex-0.10.0/tests/test_onboarding.py

@@ -0,0 +1,160 @@
+"""Onboarding / setup tests — real-boundary, never-raise, bounded.
+
+Mirrors tests/test_doctor.py's philosophy: pip install and semantic indexing are exercised
+against a real subprocess / a real SemanticDb rather than fabricated mocks, so a genuine
+contract drift (e.g. pip's actual CLI shape) cannot hide behind a mock that agrees with itself.
+"""
+from __future__ import annotations
+
+import io
+import os
+import time
+
+import pytest
+
+from codeintel import onboarding
+
+
+def test_pip_install_nonexistent_never_raises():
+    result = onboarding._pip_install(["codeintel-nonexistent-pkg-xyz-999"], timeout_s=30)
+    assert isinstance(result, dict)
+    assert result["ok"] is False
+    assert "detail" in result
+
+
+def test_run_setup_never_raises_and_bounded(tmp_path, monkeypatch):
+    monkeypatch.setattr("codeintel.providers.graph.shutil.which", lambda x: None)
+    start = time.monotonic()
+    report = onboarding.run_setup(tmp_path, do_index=False, warm_lsp=False)
+    elapsed = time.monotonic() - start
+    assert isinstance(report, dict)
+    assert "doctor" in report
+    assert elapsed < 12
+
+
+def test_setup_index_timeout_bounded(tmp_path, monkeypatch):
+    def _slow_index(self, project_root):
+        time.sleep(5)
+        return 0
+
+    monkeypatch.setattr("codeintel.indexer.Indexer.index", _slow_index)
+    start = time.monotonic()
+    result = onboarding._bounded_index(str(tmp_path), timeout_s=1, out=io.StringIO())
+    elapsed = time.monotonic() - start
+    assert result["status"] == "timeout"
+    assert elapsed < 2.5
+
+
+def test_guidance_for_missing_graph():
+    probe = {"installed": False}
+    guidance = onboarding._guidance_for("graph", probe)
+    assert "codebase-memory-mcp" in guidance
+
+
+def test_setup_index_real_db(tmp_path, monkeypatch):
+    pytest.importorskip("fastembed")
+
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    (repo / "sample.py").write_text("def greet():\n    return 'hello'\n")
+
+    db_path = tmp_path / "semantic.db"
+    monkeypatch.setattr("codeintel.semantic_db.default_db_path", lambda *a, **k: str(db_path))
+
+    report = onboarding.run_setup(str(repo), do_index=True, out=io.StringIO())
+    assert report["ok"] is True
+
+    from codeintel.semantic_db import SemanticDb
+
+    db = SemanticDb(str(db_path))
+    try:
+        real_repo = os.path.realpath(str(repo))
+        row = db.conn().execute(
+            "SELECT COUNT(*) FROM chunk_hashes WHERE project_root = ?", (real_repo,)
+        ).fetchone()
+        count = row[0] if row else 0
+    finally:
+        db.close()
+    assert count > 0
+
+
+# --------------------------------------------------------------------------- #
+# one-command setup (--all): idempotency, optional-graph framing, next steps
+# --------------------------------------------------------------------------- #
+
+def test_guidance_for_graph_is_optional_and_platform_aware():
+    g = onboarding._guidance_for("graph", {"installed": False})
+    assert "codebase-memory-mcp" in g   # (kept from the original guidance test)
+    assert "OPTIONAL" in g              # framed as the optional add-on it is
+    assert "/" in g                     # carries a platform tag like Darwin/arm64
+
+
+def test_run_setup_skips_install_when_engine_already_installed(tmp_path, monkeypatch):
+    # Idempotency: `--all`/re-runs must NOT reinstall uv when the LSP engine already reports installed.
+    monkeypatch.setattr("codeintel.providers.graph.shutil.which", lambda x: None)
+    monkeypatch.setattr("codeintel.providers.lsp.shutil.which", lambda x: "/fake/uvx")  # lsp installed
+
+    def _boom(*a, **k):
+        raise AssertionError("_pip_install must not run when the engine is already satisfied")
+    monkeypatch.setattr(onboarding, "_pip_install", _boom)
+
+    report = onboarding.run_setup(tmp_path, install_uv=True, do_index=False, warm_lsp=False)
+    step = next(s for s in report["steps"] if s["name"] == "install uv")
+    assert step["status"] == "ok"
+    assert "already satisfied" in step["detail"]
+
+
+def test_next_steps_lists_remaining_actions():
+    doctor_report = {"engines": {
+        "semantic": {"installed": True, "repo_indexed": False},
+        "lsp": {"installed": False},
+        "graph": {"installed": False},
+    }}
+    joined = " | ".join(onboarding._next_steps(doctor_report, "/repo"))
+    assert "codeintel index /repo" in joined                    # indexed=False → index step
+    assert "pip install uv" in joined                           # lsp missing
+    assert "codebase-memory-mcp" in joined and "OPTIONAL" in joined  # graph = optional
+    assert "codeintel install" in joined                        # always the last mile
+
+
+def test_next_steps_all_ready_is_just_agent_registration():
+    doctor_report = {"engines": {
+        "semantic": {"installed": True, "repo_indexed": True},
+        "lsp": {"installed": True},
+        "graph": {"installed": True},
+    }}
+    assert onboarding._next_steps(doctor_report, "/repo") == ["Make your AI agent use it — codeintel install"]
+
+
+def test_render_diagnose_only_points_to_all(monkeypatch):
+    # Bare setup (no action flags) must point the user at the one-command form + show Next steps.
+    monkeypatch.setattr("codeintel.providers.graph.shutil.which", lambda x: None)
+    report = onboarding.run_setup("/tmp/x", do_index=False, warm_lsp=False)
+    text = onboarding.render_setup_text(report)
+    assert "setup --all" in text
+    assert "Next:" in text
+
+
+def test_warm_lsp_reprobes_after_install_not_stale_preflight(tmp_path, monkeypatch):
+    # The warm step must re-probe (deep) AFTER installs, not reuse the pre-install shallow preflight —
+    # else a fresh machine prints "warm lsp: fail" directly under "install uv: ok".
+    monkeypatch.setattr("codeintel.providers.graph.shutil.which", lambda x: None)
+
+    def _probe(self, root, deep=False, timeout_s=0):
+        if deep:  # the dedicated warm boot, run AFTER the install loop
+            return {"installed": True, "runnable": True, "repo_indexed": None,
+                    "detail": "READY (warmed)", "remediation": None}
+        return {"installed": False, "runnable": False, "repo_indexed": None,
+                "detail": "no uvx (preflight)", "remediation": None}
+    monkeypatch.setattr("codeintel.providers.lsp.LspProvider.probe", _probe)
+
+    report = onboarding.run_setup(tmp_path, warm_lsp=True, do_index=False, lsp_warm_timeout_s=5)
+    warm = next(s for s in report["steps"] if s["name"] == "warm lsp")
+    assert "READY (warmed)" in warm["detail"]   # reflects the fresh deep probe, not the stale preflight
+
+
+def test_next_steps_never_raises_on_malformed_doctor():
+    # Hardened like every sibling helper — malformed doctor input degrades to a list, never raises.
+    for bad in ({"engines": None}, {"engines": {"semantic": "x"}}, {}, None,
+                {"engines": 5}, {"engines": {"lsp": 7}}):
+        assert isinstance(onboarding._next_steps(bad, "/repo"), list)

codecortex-0.9.0/src/codeintel/__init__.py

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

codecortex-0.9.0/tests/test_onboarding.py

@@ -1,78 +0,0 @@
-"""Onboarding / setup tests — real-boundary, never-raise, bounded.
-
-Mirrors tests/test_doctor.py's philosophy: pip install and semantic indexing are exercised
-against a real subprocess / a real SemanticDb rather than fabricated mocks, so a genuine
-contract drift (e.g. pip's actual CLI shape) cannot hide behind a mock that agrees with itself.
-"""
-from __future__ import annotations
-
-import io
-import os
-import time
-
-import pytest
-
-from codeintel import onboarding
-
-
-def test_pip_install_nonexistent_never_raises():
-    result = onboarding._pip_install(["codeintel-nonexistent-pkg-xyz-999"], timeout_s=30)
-    assert isinstance(result, dict)
-    assert result["ok"] is False
-    assert "detail" in result
-
-
-def test_run_setup_never_raises_and_bounded(tmp_path, monkeypatch):
-    monkeypatch.setattr("codeintel.providers.graph.shutil.which", lambda x: None)
-    start = time.monotonic()
-    report = onboarding.run_setup(tmp_path, do_index=False, warm_lsp=False)
-    elapsed = time.monotonic() - start
-    assert isinstance(report, dict)
-    assert "doctor" in report
-    assert elapsed < 12
-
-
-def test_setup_index_timeout_bounded(tmp_path, monkeypatch):
-    def _slow_index(self, project_root):
-        time.sleep(5)
-        return 0
-
-    monkeypatch.setattr("codeintel.indexer.Indexer.index", _slow_index)
-    start = time.monotonic()
-    result = onboarding._bounded_index(str(tmp_path), timeout_s=1, out=io.StringIO())
-    elapsed = time.monotonic() - start
-    assert result["status"] == "timeout"
-    assert elapsed < 2.5
-
-
-def test_guidance_for_missing_graph():
-    probe = {"installed": False}
-    guidance = onboarding._guidance_for("graph", probe)
-    assert "codebase-memory-mcp" in guidance
-
-
-def test_setup_index_real_db(tmp_path, monkeypatch):
-    pytest.importorskip("fastembed")
-
-    repo = tmp_path / "repo"
-    repo.mkdir()
-    (repo / "sample.py").write_text("def greet():\n    return 'hello'\n")
-
-    db_path = tmp_path / "semantic.db"
-    monkeypatch.setattr("codeintel.semantic_db.default_db_path", lambda *a, **k: str(db_path))
-
-    report = onboarding.run_setup(str(repo), do_index=True, out=io.StringIO())
-    assert report["ok"] is True
-
-    from codeintel.semantic_db import SemanticDb
-
-    db = SemanticDb(str(db_path))
-    try:
-        real_repo = os.path.realpath(str(repo))
-        row = db.conn().execute(
-            "SELECT COUNT(*) FROM chunk_hashes WHERE project_root = ?", (real_repo,)
-        ).fetchone()
-        count = row[0] if row else 0
-    finally:
-        db.close()
-    assert count > 0