cocoindex-code 0.2.5__tar.gz → 0.2.7__tar.gz

{cocoindex_code-0.2.5 → cocoindex_code-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocoindex-code
-Version: 0.2.5
+Version: 0.2.7
 Summary: MCP server for indexing and querying codebases using CocoIndex
 Project-URL: Homepage, https://github.com/cocoindex-io/cocoindex-code
 Project-URL: Repository, https://github.com/cocoindex-io/cocoindex-code
@@ -17,7 +17,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
-Requires-Dist: cocoindex[litellm]==1.0.0a35
+Requires-Dist: cocoindex[litellm]==1.0.0a37
 Requires-Dist: einops>=0.8.2
 Requires-Dist: mcp>=1.0.0
 Requires-Dist: msgspec>=0.19.0
@@ -208,6 +208,7 @@ The background daemon starts automatically on first use.
 | `ccc search <query>` | Semantic search across the codebase |
 | `ccc status` | Show index stats (chunk count, file count, language breakdown) |
 | `ccc mcp` | Run as MCP server in stdio mode |
+| `ccc doctor` | Run diagnostics — checks settings, daemon, model, file matching, and index health |
 | `ccc reset` | Delete index databases. `--all` also removes settings. `-f` skips confirmation. |
 | `ccc daemon status` | Show daemon version, uptime, and loaded projects |
 | `ccc daemon restart` | Restart the background daemon |
@@ -458,6 +459,8 @@ embedding:
 
 ## Troubleshooting
 
+Run `ccc doctor` to diagnose common issues. It checks your settings, daemon health, embedding model, file matching, and index status — all in one command.
+
 ### `sqlite3.Connection object has no attribute enable_load_extension`
 
 Some Python installations (e.g. the one pre-installed on macOS) ship with a SQLite library that doesn't enable extensions.

{cocoindex_code-0.2.5 → cocoindex_code-0.2.7}/README.md

@@ -169,6 +169,7 @@ The background daemon starts automatically on first use.
 | `ccc search <query>` | Semantic search across the codebase |
 | `ccc status` | Show index stats (chunk count, file count, language breakdown) |
 | `ccc mcp` | Run as MCP server in stdio mode |
+| `ccc doctor` | Run diagnostics — checks settings, daemon, model, file matching, and index health |
 | `ccc reset` | Delete index databases. `--all` also removes settings. `-f` skips confirmation. |
 | `ccc daemon status` | Show daemon version, uptime, and loaded projects |
 | `ccc daemon restart` | Restart the background daemon |
@@ -419,6 +420,8 @@ embedding:
 
 ## Troubleshooting
 
+Run `ccc doctor` to diagnose common issues. It checks your settings, daemon health, embedding model, file matching, and index status — all in one command.
+
 ### `sqlite3.Connection object has no attribute enable_load_extension`
 
 Some Python installations (e.g. the one pre-installed on macOS) ship with a SQLite library that doesn't enable extensions.

{cocoindex_code-0.2.5 → cocoindex_code-0.2.7}/pyproject.toml

@@ -23,7 +23,7 @@ classifiers = [
 
 dependencies = [
     "mcp>=1.0.0",
-    "cocoindex[litellm]==1.0.0a35",
+    "cocoindex[litellm]==1.0.0a37",
     "sentence-transformers>=2.2.0",
     "sqlite-vec>=0.1.0",
     "pydantic>=2.0.0",

{cocoindex_code-0.2.5 → cocoindex_code-0.2.7}/src/cocoindex_code/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.5'
-__version_tuple__ = version_tuple = (0, 2, 5)
+__version__ = version = '0.2.7'
+__version_tuple__ = version_tuple = (0, 2, 7)
 
 __commit_id__ = commit_id = None

{cocoindex_code-0.2.5 → cocoindex_code-0.2.7}/src/cocoindex_code/cli.py

@@ -2,11 +2,15 @@
 
 from __future__ import annotations
 
+import functools
+from collections.abc import Callable
 from pathlib import Path
+from typing import TypeVar
 
 import typer as _typer
 
-from .protocol import IndexingProgress, ProjectStatusResponse, SearchResponse
+from .client import DaemonStartError
+from .protocol import DoctorCheckResult, IndexingProgress, ProjectStatusResponse, SearchResponse
 from .settings import (
     default_project_settings,
     default_user_settings,
@@ -35,8 +39,17 @@ app.add_typer(daemon_app, name="daemon")
 def require_project_root() -> Path:
     """Find the project root by walking up from CWD.
 
-    Exits with code 1 if not found.
+    Checks global settings first (more fundamental), then project settings.
+    Exits with code 1 if either check fails.
     """
+    gs_path = user_settings_path()
+    if not gs_path.is_file():
+        _typer.echo(
+            f"Error: Global settings not found: {gs_path}\n"
+            "Run `ccc init` to create it with default settings.",
+            err=True,
+        )
+        raise _typer.Exit(code=1)
     root = find_project_root(Path.cwd())
     if root is None:
         _typer.echo(
@@ -48,6 +61,26 @@ def require_project_root() -> Path:
     return root
 
 
+_F = TypeVar("_F", bound=Callable[..., object])
+
+
+def _catch_daemon_start_error(func: _F) -> _F:
+    """Decorator that catches ``DaemonStartError`` and exits with a clean message.
+
+    Apply to any CLI command that may trigger daemon auto-start.
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args: object, **kwargs: object) -> object:
+        try:
+            return func(*args, **kwargs)
+        except DaemonStartError as e:
+            _typer.echo(f"Error: {e}", err=True)
+            raise _typer.Exit(code=1)
+
+    return wrapper  # type: ignore[return-value]
+
+
 def resolve_default_path(project_root: Path) -> str | None:
     """Compute default ``--path`` filter from CWD relative to project root."""
     cwd = Path.cwd().resolve()
@@ -138,6 +171,9 @@ def _run_index_with_progress(project_root: str) -> None:
             resp = _client.index(project_root, on_progress=_on_progress, on_waiting=_on_waiting)
         except RuntimeError as e:
             live.stop()
+            # Let DaemonStartError propagate to the decorator for consistent handling.
+            if isinstance(e, DaemonStartError):
+                raise
             _typer.echo(f"Indexing failed: {e}", err=True)
             raise _typer.Exit(code=1)
 
@@ -252,6 +288,12 @@ def init(
     cwd = Path.cwd().resolve()
     settings_file = _project_settings_path(cwd)
 
+    # Always ensure user settings exist
+    user_path = user_settings_path()
+    if not user_path.is_file():
+        save_user_settings(default_user_settings())
+        _typer.echo(f"Created user settings: {user_path}")
+
     # Check if already initialized
     if settings_file.is_file():
         _typer.echo("Project already initialized.")
@@ -268,12 +310,6 @@ def init(
             )
             raise _typer.Exit(code=1)
 
-    # Create user settings if missing
-    user_path = user_settings_path()
-    if not user_path.is_file():
-        save_user_settings(default_user_settings())
-        _typer.echo(f"Created user settings: {user_path}")
-
     # Create project settings
     save_project_settings(cwd, default_project_settings())
     _typer.echo(f"Created project settings: {settings_file}")
@@ -286,6 +322,7 @@ def init(
 
 
 @app.command()
+@_catch_daemon_start_error
 def index() -> None:
     """Create/update index for the codebase."""
     from . import client as _client
@@ -297,6 +334,7 @@ def index() -> None:
 
 
 @app.command()
+@_catch_daemon_start_error
 def search(
     query: list[str] = _typer.Argument(..., help="Search query"),
     lang: list[str] = _typer.Option([], "--lang", help="Filter by language"),
@@ -333,6 +371,7 @@ def search(
 
 
 @app.command()
+@_catch_daemon_start_error
 def status() -> None:
     """Show project status."""
     from . import client as _client
@@ -415,7 +454,146 @@ def reset(
             )
 
 
+def _print_section(name: str) -> None:
+    import click as _click
+
+    _typer.echo()
+    _typer.echo(_click.style(f"  {name}", bold=True))
+    _typer.echo(_click.style(f"  {'─' * 38}", fg="bright_black"))
+
+
+def _print_error(msg: str) -> None:
+    import click as _click
+
+    _typer.echo(_click.style(f"  ERROR: {msg}", fg="red"), err=True)
+
+
+def _print_doctor_result(result: DoctorCheckResult) -> None:
+    import click as _click
+
+    if result.name == "done":
+        return
+    if result.ok:
+        tag = _click.style("[OK]", fg="green", bold=True)
+    else:
+        tag = _click.style("[FAIL]", fg="red", bold=True)
+    _typer.echo(f"\n  {tag} {result.name}")
+    for line in result.details:
+        _typer.echo(f"    {line}")
+    for err in result.errors:
+        _typer.echo(_click.style(f"    ERROR: {err}", fg="red"), err=True)
+
+
+@app.command()
+@_catch_daemon_start_error
+def doctor() -> None:
+    """Check system health and report issues."""
+    from . import client as _client
+    from .settings import (
+        load_project_settings as _load_project_settings,
+    )
+    from .settings import (
+        load_user_settings as _load_user_settings,
+    )
+    from .settings import (
+        project_settings_path as _project_settings_path,
+    )
+    from .settings import (
+        user_settings_path as _user_settings_path,
+    )
+
+    # --- 1. Global settings (local, no daemon needed) ---
+    _print_section("Global Settings")
+    settings_path = _user_settings_path()
+    _typer.echo(f"  Settings: {settings_path}")
+    try:
+        user_settings = _load_user_settings()
+        emb = user_settings.embedding
+        device_str = f", device={emb.device}" if emb.device else ""
+        _typer.echo(f"  Embedding: provider={emb.provider}, model={emb.model}{device_str}")
+        if user_settings.envs:
+            _typer.echo(
+                f"  Env vars (from settings): {', '.join(sorted(user_settings.envs.keys()))}"
+            )
+    except (FileNotFoundError, ValueError) as e:
+        _print_error(str(e))
+
+    # --- 2. Connect to daemon (handshake with auto-start/restart) ---
+    _print_section("Daemon")
+    daemon_ok = False
+    try:
+        status = _client.daemon_status()
+        _typer.echo(f"  Version: {status.version}")
+        _typer.echo(f"  Uptime: {status.uptime_seconds:.1f}s")
+        _typer.echo(f"  Loaded projects: {len(status.projects)}")
+        daemon_ok = True
+    except Exception as e:
+        _print_error(f"Cannot connect to daemon: {e}")
+        _typer.echo("  Remaining daemon-side checks will be skipped.")
+
+    # --- 3. Daemon environment (requires daemon) ---
+    if daemon_ok:
+        try:
+            env_resp = _client.daemon_env()
+            settings_keys = set(env_resp.settings_env_names)
+            other_keys = [k for k in env_resp.env_names if k not in settings_keys]
+            if other_keys:
+                _typer.echo(f"  Other env vars in daemon: {', '.join(sorted(other_keys))}")
+        except Exception as e:
+            _print_error(f"Failed to get daemon env: {e}")
+
+    # --- 4. Model check (daemon-side, global — before project checks) ---
+    if daemon_ok:
+        try:
+            _client.doctor(
+                project_root=None,
+                on_result=_print_doctor_result,
+            )
+        except Exception as e:
+            _print_error(f"Model check failed: {e}")
+
+    # --- 5. Detect project ---
+    project_root = find_project_root(Path.cwd())
+
+    # --- 6. Project settings (local, no daemon needed) ---
+    if project_root is not None:
+        _print_section("Project Settings")
+        ps_path = _project_settings_path(project_root)
+        _typer.echo(f"  Settings: {ps_path}")
+        try:
+            ps = _load_project_settings(project_root)
+            _typer.echo(f"  Include patterns ({len(ps.include_patterns)}):")
+            _typer.echo(f"    {', '.join(ps.include_patterns)}")
+            _typer.echo(f"  Exclude patterns ({len(ps.exclude_patterns)}):")
+            _typer.echo(f"    {', '.join(ps.exclude_patterns)}")
+            if ps.language_overrides:
+                _typer.echo("  Language overrides:")
+                for lo in ps.language_overrides:
+                    _typer.echo(f"    .{lo.ext} -> {lo.lang}")
+        except (FileNotFoundError, ValueError) as e:
+            _print_error(str(e))
+
+    # --- 7. Project daemon-side checks (file walk + index status) ---
+    if daemon_ok and project_root is not None:
+        try:
+            _client.doctor(
+                project_root=str(project_root),
+                on_result=_print_doctor_result,
+            )
+        except Exception as e:
+            _print_error(f"Project checks failed: {e}")
+
+    # --- 8. Log files ---
+    _print_section("Log Files")
+    from .daemon import daemon_dir as _daemon_dir
+
+    log_dir = _daemon_dir()
+    _typer.echo(f"  Daemon logs: {log_dir / 'daemon.log'}")
+    _typer.echo("  Check logs above for further troubleshooting.")
+
+
 @app.command()
+@_catch_daemon_start_error
 def mcp() -> None:
     """Run as MCP server (stdio mode)."""
     import asyncio
@@ -449,6 +627,7 @@ async def _bg_index(project_root: str) -> None:
 
 
 @daemon_app.command("status")
+@_catch_daemon_start_error
 def daemon_status() -> None:
     """Show daemon status."""
     from . import client as _client
@@ -466,6 +645,7 @@ def daemon_status() -> None:
 
 
 @daemon_app.command("restart")
+@_catch_daemon_start_error
 def daemon_restart() -> None:
     """Restart the daemon."""
     from .client import _wait_for_daemon, start_daemon, stop_daemon
@@ -474,13 +654,9 @@ def daemon_restart() -> None:
     stop_daemon()
 
     _typer.echo("Starting daemon...")
-    start_daemon()
-    try:
-        _wait_for_daemon()
-        _typer.echo("Daemon restarted.")
-    except TimeoutError:
-        _typer.echo("Error: Daemon did not start in time.", err=True)
-        raise _typer.Exit(code=1)
+    proc = start_daemon()
+    _wait_for_daemon(proc=proc)
+    _typer.echo("Daemon restarted.")
 
 
 @daemon_app.command("stop")

{cocoindex_code-0.2.5 → cocoindex_code-0.2.7}/src/cocoindex_code/client.py

@@ -18,9 +18,14 @@ from multiprocessing.connection import Client, Connection
 from pathlib import Path
 
 from ._version import __version__
-from .daemon import _connection_family, daemon_pid_path, daemon_socket_path
+from .daemon import _connection_family, daemon_log_path, daemon_pid_path, daemon_socket_path
 from .protocol import (
+    DaemonEnvRequest,
+    DaemonEnvResponse,
     DaemonStatusResponse,
+    DoctorCheckResult,
+    DoctorRequest,
+    DoctorResponse,
     ErrorResponse,
     HandshakeRequest,
     HandshakeResponse,
@@ -79,8 +84,8 @@ def _connect_and_handshake() -> Connection:
     except (ConnectionRefusedError, OSError):
         pass
 
-    start_daemon()
-    _wait_for_daemon()
+    proc = start_daemon()
+    _wait_for_daemon(proc=proc)
 
     # Verify the fresh daemon is reachable
     for _attempt in range(10):
@@ -140,6 +145,27 @@ class DaemonVersionError(RuntimeError):
         )
 
 
+class DaemonStartError(RuntimeError):
+    """Raised when the daemon process fails to start.
+
+    Carries the daemon log content so callers can display it to the user.
+    """
+
+    def __init__(self, message: str, log: str | None = None) -> None:
+        self.log = log
+        super().__init__(message)
+
+
+def _read_daemon_log() -> str | None:
+    """Read the daemon log file, returning its content or None."""
+    log_path = daemon_log_path()
+    try:
+        content = log_path.read_text().strip()
+        return content if content else None
+    except (FileNotFoundError, OSError):
+        return None
+
+
 def _send(req: Request) -> Response:
     """Open connection, handshake, send one request, read one response, close."""
     conn = _connect_and_handshake()
@@ -259,6 +285,41 @@ def stop() -> StopResponse:
     return _send(StopRequest())  # type: ignore[return-value]
 
 
+def daemon_env() -> DaemonEnvResponse:
+    """Get environment variable names from the daemon."""
+    return _send(DaemonEnvRequest())  # type: ignore[return-value]
+
+
+def doctor(
+    project_root: str | None = None,
+    on_result: Callable[[DoctorCheckResult], None] | None = None,
+) -> list[DoctorCheckResult]:
+    """Run doctor checks via daemon, streaming results to on_result callback."""
+    conn = _connect_and_handshake()
+    try:
+        conn.send_bytes(encode_request(DoctorRequest(project_root=project_root)))
+        results: list[DoctorCheckResult] = []
+        while True:
+            try:
+                data = conn.recv_bytes()
+            except EOFError:
+                raise RuntimeError("Connection to daemon lost during doctor checks")
+            resp = decode_response(data)
+            if isinstance(resp, ErrorResponse):
+                raise RuntimeError(f"Daemon error: {resp.message}")
+            if isinstance(resp, DoctorResponse):
+                results.append(resp.result)
+                if on_result is not None:
+                    on_result(resp.result)
+                if resp.final:
+                    break
+            else:
+                raise RuntimeError(f"Unexpected response: {type(resp).__name__}")
+        return results
+    finally:
+        conn.close()
+
+
 # ---------------------------------------------------------------------------
 # Daemon lifecycle helpers
 # ---------------------------------------------------------------------------
@@ -276,8 +337,12 @@ def is_daemon_running() -> bool:
     return os.path.exists(daemon_socket_path())
 
 
-def start_daemon() -> None:
-    """Start the daemon as a background process."""
+def start_daemon() -> subprocess.Popen[bytes]:
+    """Start the daemon as a background process.
+
+    Returns the ``Popen`` object so callers can detect early process death
+    (via ``proc.poll()``) instead of waiting for a full timeout.
+    """
     from .daemon import daemon_dir
 
     daemon_dir().mkdir(parents=True, exist_ok=True)
@@ -292,7 +357,7 @@ def start_daemon() -> None:
     log_fd = open(log_path, "w")
     if sys.platform == "win32":
         _create_no_window = 0x08000000
-        subprocess.Popen(
+        proc = subprocess.Popen(
             cmd,
             stdout=log_fd,
             stderr=log_fd,
@@ -300,7 +365,7 @@ def start_daemon() -> None:
             creationflags=_create_no_window,
         )
     else:
-        subprocess.Popen(
+        proc = subprocess.Popen(
             cmd,
             start_new_session=True,
             stdout=log_fd,
@@ -308,6 +373,7 @@ def start_daemon() -> None:
             stdin=subprocess.DEVNULL,
         )
     log_fd.close()
+    return proc
 
 
 def _find_ccc_executable() -> str | None:
@@ -429,11 +495,27 @@ def _cleanup_stale_files(pid_path: Path, pid: int | None) -> None:
             pass
 
 
-def _wait_for_daemon(timeout: float = 30.0) -> None:
-    """Wait for the daemon socket/pipe to become available."""
+def _wait_for_daemon(
+    timeout: float = 30.0,
+    proc: subprocess.Popen[bytes] | None = None,
+) -> None:
+    """Wait for the daemon socket/pipe to become available.
+
+    If *proc* is given, polls the process each iteration.  When the process
+    exits before the socket appears, raises ``DaemonStartError`` immediately
+    with the daemon log content — no need to wait for the full timeout.
+    """
     deadline = time.monotonic() + timeout
     sock_path = daemon_socket_path()
     while time.monotonic() < deadline:
+        # Check if the daemon process died before the socket appeared.
+        if proc is not None and proc.poll() is not None:
+            log = _read_daemon_log()
+            msg = "Daemon process exited before it became ready."
+            if log:
+                msg += f"\n\nDaemon log:\n{log}"
+            raise DaemonStartError(msg, log=log)
+
         if sys.platform == "win32":
             try:
                 conn = Client(sock_path, family=_connection_family())
@@ -445,7 +527,13 @@ def _wait_for_daemon(timeout: float = 30.0) -> None:
             if os.path.exists(sock_path):
                 return
         time.sleep(0.2)
-    raise TimeoutError("Daemon did not start in time")
+
+    # Timeout — also include log for diagnostics.
+    log = _read_daemon_log()
+    msg = "Daemon did not start in time."
+    if log:
+        msg += f"\n\nDaemon log:\n{log}"
+    raise DaemonStartError(msg, log=log)
 
 
 def _needs_restart(resp: HandshakeResponse) -> bool:

{cocoindex_code-0.2.5 → cocoindex_code-0.2.7}/src/cocoindex_code/daemon.py

@@ -17,9 +17,15 @@ from typing import Any
 from ._version import __version__
 from .project import Project
 from .protocol import (
+    DaemonEnvRequest,
+    DaemonEnvResponse,
     DaemonProjectInfo,
     DaemonStatusRequest,
     DaemonStatusResponse,
+    DoctorCheckResult,
+    DoctorRequest,
+    DoctorResponse,
+    DoctorStreamResponse,
     ErrorResponse,
     HandshakeRequest,
     HandshakeResponse,
@@ -151,6 +157,7 @@ async def handle_connection(
     start_time: float,
     on_shutdown: Callable[[], None],
     settings_mtime_us: int | None,
+    settings_env_names: list[str],
 ) -> None:
     """Handle a single client connection (per-request model).
 
@@ -186,7 +193,7 @@ async def handle_connection(
         data = await loop.run_in_executor(None, conn.recv_bytes)
         req = decode_request(data)
 
-        result = await _dispatch(req, registry, start_time, on_shutdown)
+        result = await _dispatch(req, registry, start_time, on_shutdown, settings_env_names)
         if isinstance(result, AsyncIterator):
             try:
                 async for resp in result:
@@ -231,17 +238,161 @@ async def _search_with_wait(
         yield ErrorResponse(message=str(e))
 
 
+async def _handle_doctor(
+    req: DoctorRequest,
+    registry: ProjectRegistry,
+) -> AsyncIterator[DoctorStreamResponse]:
+    """Run doctor checks sequentially, yielding results as they complete.
+
+    When ``project_root`` is None, only the model check runs (global scope).
+    When ``project_root`` is set, only project-specific checks run (file walk + index status).
+    The CLI calls this twice — once without project, once with — so that global checks
+    appear before project settings in the output.
+    """
+    if req.project_root is None:
+        # Global-scope checks
+        yield DoctorResponse(result=await _check_model(registry._embedder))
+    else:
+        # Project-scope checks
+        yield DoctorResponse(result=await _check_file_walk(req.project_root))
+        yield DoctorResponse(result=await _check_index_status(req.project_root))
+
+    # Final marker
+    yield DoctorResponse(
+        result=DoctorCheckResult(name="done", ok=True, details=[], errors=[]),
+        final=True,
+    )
+
+
+async def _check_model(embedder: Embedder) -> DoctorCheckResult:
+    """Test the embedding model by embedding a short string."""
+    try:
+        vec = await embedder.embed("hello world")
+        dim = len(vec)
+        return DoctorCheckResult(
+            name="Model Check",
+            ok=True,
+            details=[f"Embedding dimension: {dim}"],
+            errors=[],
+        )
+    except Exception as e:
+        return DoctorCheckResult(
+            name="Model Check",
+            ok=False,
+            details=[],
+            errors=[str(e)],
+        )
+
+
+async def _check_file_walk(project_root_str: str) -> DoctorCheckResult:
+    """Walk project files and report counts + gitignore paths."""
+    from pathlib import PurePath
+
+    from cocoindex.resources.file import PatternFilePathMatcher
+
+    from .indexer import GitignoreAwareMatcher
+    from .settings import load_gitignore_spec, load_project_settings
+
+    project_root = Path(project_root_str)
+    try:
+        ps = load_project_settings(project_root)
+    except FileNotFoundError as e:
+        return DoctorCheckResult(name="File Walk", ok=False, details=[], errors=[str(e)])
+
+    gitignore_spec = load_gitignore_spec(project_root)
+    base_matcher = PatternFilePathMatcher(
+        included_patterns=ps.include_patterns,
+        excluded_patterns=ps.exclude_patterns,
+    )
+    matcher = GitignoreAwareMatcher(base_matcher, gitignore_spec, project_root)
+
+    counts_by_ext: dict[str, int] = {}
+    gitignore_dirs: list[str] = []
+    total = 0
+
+    def _walk() -> None:
+        nonlocal total
+        for dirpath_str, dirnames, filenames in os.walk(project_root):
+            dirpath = Path(dirpath_str)
+            rel_dir = PurePath(dirpath.relative_to(project_root))
+            if rel_dir != PurePath(".") and not matcher.is_dir_included(rel_dir):
+                dirnames.clear()
+                continue
+
+            if (dirpath / ".gitignore").is_file():
+                gitignore_dirs.append(str(rel_dir))
+
+            for fname in filenames:
+                rel_path = rel_dir / fname if rel_dir != PurePath(".") else PurePath(fname)
+                if matcher.is_file_included(rel_path):
+                    total += 1
+                    ext = PurePath(fname).suffix or "(no ext)"
+                    counts_by_ext[ext] = counts_by_ext.get(ext, 0) + 1
+
+    await asyncio.get_event_loop().run_in_executor(None, _walk)
+
+    details = [f"Total matched files: {total}"]
+    for ext, count in sorted(counts_by_ext.items(), key=lambda x: -x[1]):
+        details.append(f"  {ext}: {count}")
+    if gitignore_dirs:
+        details.append(f"Loaded .gitignore from: {', '.join(gitignore_dirs)}")
+
+    return DoctorCheckResult(name="File Walk", ok=True, details=details, errors=[])
+
+
+async def _check_index_status(project_root_str: str) -> DoctorCheckResult:
+    """Check index status by querying target_sqlite.db directly."""
+    from cocoindex.connectors import sqlite as coco_sqlite
+
+    project_root = Path(project_root_str)
+    db_path = project_root / ".cocoindex_code" / "target_sqlite.db"
+    details = [f"Index: {db_path}"]
+
+    if not db_path.exists():
+        details.append("Index not created yet.")
+        return DoctorCheckResult(name="Index Status", ok=True, details=details, errors=[])
+
+    try:
+        conn = coco_sqlite.connect(str(db_path), load_vec=True)
+        try:
+            with conn.readonly() as db:
+                total_chunks = db.execute("SELECT COUNT(*) FROM code_chunks_vec").fetchone()[0]
+                file_rows = db.execute("SELECT DISTINCT file_path FROM code_chunks_vec").fetchall()
+                total_files = len(file_rows)
+                lang_rows = db.execute(
+                    "SELECT language, COUNT(*) FROM code_chunks_vec GROUP BY language"
+                ).fetchall()
+                languages = {row[0]: row[1] for row in lang_rows}
+        finally:
+            conn.close()
+
+        details.append(f"Chunks: {total_chunks}")
+        details.append(f"Files: {total_files}")
+        if languages:
+            details.append("Languages:")
+            for lang, count in sorted(languages.items(), key=lambda x: -x[1]):
+                details.append(f"  {lang}: {count} chunks")
+        return DoctorCheckResult(name="Index Status", ok=True, details=details, errors=[])
+    except Exception as e:
+        return DoctorCheckResult(name="Index Status", ok=False, details=details, errors=[str(e)])
+
+
 async def _dispatch(
     req: Request,
     registry: ProjectRegistry,
     start_time: float,
     on_shutdown: Callable[[], None],
-) -> Response | AsyncIterator[IndexStreamResponse] | AsyncIterator[SearchStreamResponse]:
+    settings_env_names: list[str],
+) -> (
+    Response
+    | AsyncIterator[IndexStreamResponse]
+    | AsyncIterator[SearchStreamResponse]
+    | AsyncIterator[DoctorStreamResponse]
+):
     """Dispatch a request to the appropriate handler.
 
     Returns a single Response for most requests, or an AsyncIterator for
-    streaming requests (IndexRequest, or SearchRequest when waiting for
-    load-time indexing).
+    streaming requests (IndexRequest, SearchRequest when waiting, DoctorRequest).
     """
     try:
         if isinstance(req, IndexRequest):
@@ -289,6 +440,15 @@ async def _dispatch(
             on_shutdown()
             return StopResponse(ok=True)
 
+        if isinstance(req, DaemonEnvRequest):
+            return DaemonEnvResponse(
+                env_names=sorted(os.environ.keys()),
+                settings_env_names=settings_env_names,
+            )
+
+        if isinstance(req, DoctorRequest):
+            return _handle_doctor(req, registry)
+
         return ErrorResponse(message=f"Unknown request type: {type(req).__name__}")
     except Exception as e:
         logger.exception("Error dispatching request")
@@ -314,6 +474,7 @@ def run_daemon() -> None:
     settings_mtime_us = global_settings_mtime_us()
 
     # Set environment variables from settings
+    settings_env_keys = list(user_settings.envs.keys())
     for key, value in user_settings.envs.items():
         os.environ[key] = value
 
@@ -363,6 +524,7 @@ def run_daemon() -> None:
                 start_time,
                 _request_shutdown,
                 settings_mtime_us,
+                settings_env_keys,
             )
         )
         tasks.add(task)

{cocoindex_code-0.2.5 → cocoindex_code-0.2.7}/src/cocoindex_code/protocol.py

@@ -42,6 +42,14 @@ class StopRequest(_msgspec.Struct, tag="stop"):
     pass
 
 
+class DoctorRequest(_msgspec.Struct, tag="doctor"):
+    project_root: str | None = None
+
+
+class DaemonEnvRequest(_msgspec.Struct, tag="daemon_env"):
+    pass
+
+
 Request = (
     HandshakeRequest
     | IndexRequest
@@ -50,6 +58,8 @@ Request = (
     | DaemonStatusRequest
     | RemoveProjectRequest
     | StopRequest
+    | DoctorRequest
+    | DaemonEnvRequest
 )
 
 # ---------------------------------------------------------------------------
@@ -136,6 +146,23 @@ class StopResponse(_msgspec.Struct, tag="stop"):
     ok: bool
 
 
+class DoctorCheckResult(_msgspec.Struct):
+    name: str
+    ok: bool
+    details: list[str]
+    errors: list[str]
+
+
+class DoctorResponse(_msgspec.Struct, tag="doctor"):
+    result: DoctorCheckResult
+    final: bool = False
+
+
+class DaemonEnvResponse(_msgspec.Struct, tag="daemon_env"):
+    env_names: list[str]
+    settings_env_names: list[str]
+
+
 class ErrorResponse(_msgspec.Struct, tag="error"):
     message: str
 
@@ -150,11 +177,14 @@ Response = (
     | DaemonStatusResponse
     | RemoveProjectResponse
     | StopResponse
+    | DoctorResponse
+    | DaemonEnvResponse
     | ErrorResponse
 )
 
 IndexStreamResponse = IndexProgressUpdate | IndexWaitingNotice | IndexResponse | ErrorResponse
 SearchStreamResponse = IndexWaitingNotice | SearchResponse | ErrorResponse
+DoctorStreamResponse = DoctorResponse | ErrorResponse
 
 # ---------------------------------------------------------------------------
 # Encode / decode helpers (msgpack binary)

{cocoindex_code-0.2.5 → cocoindex_code-0.2.7}/src/cocoindex_code/settings.py

@@ -240,7 +240,7 @@ def _user_settings_to_dict(settings: UserSettings) -> dict[str, Any]:
 def _user_settings_from_dict(d: dict[str, Any]) -> UserSettings:
     emb_dict = d.get("embedding")
     if not emb_dict or "model" not in emb_dict:
-        raise ValueError("global_settings.yml must contain 'embedding' with at least 'model' field")
+        raise ValueError("Must contain 'embedding' with at least 'model' field")
     # Only pass keys that are present; provider uses dataclass default ("litellm") if omitted
     emb_kwargs: dict[str, Any] = {"model": emb_dict["model"]}
     if "provider" in emb_dict:
@@ -288,11 +288,14 @@ def load_user_settings() -> UserSettings:
     path = user_settings_path()
     if not path.is_file():
         raise FileNotFoundError(f"User settings not found: {path}")
-    with open(path) as f:
-        data = _yaml.safe_load(f)
-    if not data:
-        raise ValueError(f"User settings file is empty: {path}")
-    return _user_settings_from_dict(data)
+    try:
+        with open(path) as f:
+            data = _yaml.safe_load(f)
+        if not data:
+            raise ValueError("File is empty")
+        return _user_settings_from_dict(data)
+    except Exception as e:
+        raise type(e)(f"Error loading {path}: {e}") from e
 
 
 def save_user_settings(settings: UserSettings) -> Path:
@@ -312,11 +315,14 @@ def load_project_settings(project_root: Path) -> ProjectSettings:
     path = project_settings_path(project_root)
     if not path.is_file():
         raise FileNotFoundError(f"Project settings not found: {path}")
-    with open(path) as f:
-        data = _yaml.safe_load(f)
-    if not data:
-        return default_project_settings()
-    return _project_settings_from_dict(data)
+    try:
+        with open(path) as f:
+            data = _yaml.safe_load(f)
+        if not data:
+            return default_project_settings()
+        return _project_settings_from_dict(data)
+    except Exception as e:
+        raise type(e)(f"Error loading {path}: {e}") from e
 
 
 def save_project_settings(project_root: Path, settings: ProjectSettings) -> Path: