fix(doctor): resolve F-01 build venv preflight

Closes #4

Author: ayhammouda

README.md

@@ -196,6 +196,10 @@ Check the local environment:
 uvx mcp-server-python-docs doctor
 ```
 
+This checks the runtime Python version, SQLite FTS5, cache/index paths, disk
+space, and whether the current interpreter has the `venv`/`ensurepip` support
+needed by `build-index`.
+
 Validate an existing index:
 
 ```bash
@@ -222,6 +226,19 @@ Install Python from [python.org](https://www.python.org/) or use:
 uv python install
 ```
 
+### Missing `pythonX.Y-venv` on Debian/Ubuntu
+
+If `doctor` reports that build venv support is unavailable, install the venv
+package for the same Python minor version that runs the server:
+
+```bash
+sudo apt install python3.12-venv
+```
+
+Adjust `3.12` to match the version shown by `doctor`. Without this package,
+`build-index` cannot create the disposable Sphinx environment it uses to build
+JSON documentation content.
+
 ### `uvx` cache stale
 
 If `uvx mcp-server-python-docs` runs an old version:

src/mcp_server_python_docs/__main__.py

@@ -434,6 +434,7 @@ def doctor() -> None:
     import sqlite3
     from pathlib import Path
 
+    from mcp_server_python_docs.diagnostics import check_build_venv_support
     from mcp_server_python_docs.storage.db import get_cache_dir, get_index_path
 
     results: list[tuple[str, bool, str]] = []  # (probe_name, passed, detail)
@@ -470,7 +471,15 @@ def doctor() -> None:
             )
     results.append(("SQLite FTS5", fts5_ok, fts5_detail))
 
-    # 3. Cache directory
+    # 3. Build-index Sphinx venv support
+    build_venv_result = check_build_venv_support()
+    results.append((
+        "Build venv support",
+        build_venv_result.passed,
+        build_venv_result.detail,
+    ))
+
+    # 4. Cache directory
     cache_dir = get_cache_dir()
     cache_exists = cache_dir.exists()
     cache_writable = False
@@ -491,7 +500,7 @@ def doctor() -> None:
         cache_ok = False
     results.append(("Cache directory", cache_ok, cache_detail))
 
-    # 4. Index database presence
+    # 5. Index database presence
     index_path = get_index_path()
     index_exists = index_path.exists()
     index_detail = str(index_path)
@@ -504,7 +513,7 @@ def doctor() -> None:
         index_detail += f" ({size_mb:.1f} MB)"
     results.append(("Index database", index_exists, index_detail))
 
-    # 5. Free disk space
+    # 6. Free disk space
     check_path = cache_dir if cache_exists else cache_dir.parent
     # Ensure path exists for disk_usage
     if not check_path.exists():

src/mcp_server_python_docs/diagnostics.py

@@ -0,0 +1,74 @@
+"""Environment diagnostics shared by CLI health checks."""
+from __future__ import annotations
+
+import subprocess
+import sys
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class DiagnosticResult:
+    """Result for a single environment diagnostic probe."""
+
+    passed: bool
+    detail: str
+
+
+def _combined_output_excerpt(stdout: str, stderr: str, limit: int = 500) -> str:
+    combined = "\n".join(part.strip() for part in (stderr, stdout) if part.strip())
+    if len(combined) <= limit:
+        return combined
+    return combined[-limit:]
+
+
+def check_build_venv_support(
+    python_executable: str | None = None,
+    timeout: float = 10.0,
+) -> DiagnosticResult:
+    """Check that build-index can create pip-enabled Sphinx environments.
+
+    ``build-index`` creates a disposable Sphinx virtual environment with pip.
+    Debian/Ubuntu hosts without the matching ``pythonX.Y-venv`` package can run
+    the server but fail when that environment needs ``ensurepip``.
+    """
+    executable = python_executable or sys.executable
+    package_name = f"python{sys.version_info.major}.{sys.version_info.minor}-venv"
+    command = [executable, "-c", "import ensurepip; import venv"]
+
+    try:
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except FileNotFoundError:
+        return DiagnosticResult(
+            passed=False,
+            detail=f"{executable} not found; build-index cannot create Sphinx venvs",
+        )
+    except subprocess.TimeoutExpired:
+        return DiagnosticResult(
+            passed=False,
+            detail=(
+                f"{executable} timed out while checking venv/ensurepip support "
+                "for build-index"
+            ),
+        )
+
+    if result.returncode == 0:
+        return DiagnosticResult(
+            passed=True,
+            detail=f"{executable} has venv and ensurepip available for build-index",
+        )
+
+    detail = (
+        f"{executable} cannot import venv/ensurepip; build-index needs them to "
+        "create Sphinx venvs. On Debian/Ubuntu, install "
+        f"{package_name} for this interpreter."
+    )
+    output = _combined_output_excerpt(result.stdout, result.stderr)
+    if output:
+        detail = f"{detail} Output: {output}"
+
+    return DiagnosticResult(passed=False, detail=detail)

tests/test_doctor.py

@@ -80,6 +80,16 @@ def test_doctor_checks_disk_space(self):
         )
         assert "PASS: Disk space" in result.stderr
 
+    def test_doctor_checks_build_venv_support(self):
+        """Doctor reports whether build-index can create Sphinx venvs."""
+        result = subprocess.run(
+            [sys.executable, "-m", "mcp_server_python_docs", "doctor"],
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+        assert "Build venv support" in result.stderr
+
     def test_doctor_reports_missing_index(self):
         """Doctor reports FAIL for Index database when pointed at empty dir."""
         with tempfile.TemporaryDirectory() as tmpdir:
@@ -115,3 +125,54 @@ def test_doctor_in_help(self):
         )
         combined = result.stdout + result.stderr
         assert "doctor" in combined
+
+
+class TestBuildVenvSupportProbe:
+    """Verify the build-index venv prerequisite probe."""
+
+    def test_probe_reports_missing_ensurepip_with_platform_package_hint(self, monkeypatch):
+        """Missing ensurepip points users to the versioned Debian/Ubuntu venv package."""
+
+        def fake_run(*args, **kwargs):
+            return subprocess.CompletedProcess(
+                args=args[0],
+                returncode=1,
+                stdout="",
+                stderr="ModuleNotFoundError: No module named 'ensurepip'",
+            )
+
+        monkeypatch.setattr(subprocess, "run", fake_run)
+
+        from mcp_server_python_docs.diagnostics import check_build_venv_support
+
+        result = check_build_venv_support()
+
+        assert result.passed is False
+        assert "ensurepip" in result.detail
+        assert (
+            f"python{sys.version_info.major}.{sys.version_info.minor}-venv"
+            in result.detail
+        )
+
+    def test_probe_passes_when_venv_and_ensurepip_are_importable(self, monkeypatch):
+        """Available venv and ensurepip support passes the build prerequisite probe."""
+
+        def fake_run(*args, **kwargs):
+            command = args[0]
+            assert "ensurepip" in command[-1]
+            assert "venv" in command[-1]
+            return subprocess.CompletedProcess(
+                args=command,
+                returncode=0,
+                stdout="",
+                stderr="",
+            )
+
+        monkeypatch.setattr(subprocess, "run", fake_run)
+
+        from mcp_server_python_docs.diagnostics import check_build_venv_support
+
+        result = check_build_venv_support()
+
+        assert result.passed is True
+        assert "build-index" in result.detail