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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocoindex-code
-Version: 0.2.6
+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
@@ -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.6 → 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.6 → 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.6'
-__version_tuple__ = version_tuple = (0, 2, 6)
+__version__ = version = '0.2.7'
+__version_tuple__ = version_tuple = (0, 2, 7)
 
 __commit_id__ = commit_id = None

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

@@ -2,10 +2,14 @@
 
 from __future__ import annotations
 
+import functools
+from collections.abc import Callable
 from pathlib import Path
+from typing import TypeVar
 
 import typer as _typer
 
+from .client import DaemonStartError
 from .protocol import DoctorCheckResult, IndexingProgress, ProjectStatusResponse, SearchResponse
 from .settings import (
     default_project_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
@@ -446,6 +485,7 @@ def _print_doctor_result(result: DoctorCheckResult) -> None:
 
 
 @app.command()
+@_catch_daemon_start_error
 def doctor() -> None:
     """Check system health and report issues."""
     from . import client as _client
@@ -553,6 +593,7 @@ def doctor() -> None:
 
 
 @app.command()
+@_catch_daemon_start_error
 def mcp() -> None:
     """Run as MCP server (stdio mode)."""
     import asyncio
@@ -586,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
@@ -603,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
@@ -611,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.6 → cocoindex_code-0.2.7}/src/cocoindex_code/client.py

@@ -18,7 +18,7 @@ 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,
@@ -84,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):
@@ -145,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()
@@ -316,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)
@@ -332,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,
@@ -340,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,
@@ -348,6 +373,7 @@ def start_daemon() -> None:
             stdin=subprocess.DEVNULL,
         )
     log_fd.close()
+    return proc
 
 
 def _find_ccc_executable() -> str | None:
@@ -469,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())
@@ -485,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.6 → 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: