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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocoindex-code
-Version: 0.2.6
+Version: 0.2.8
 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 |
@@ -456,8 +457,30 @@ embedding:
 | xml | | `.xml` |
 | yaml | | `.yaml`, `.yml` |
 
+### Custom Database Location
+
+By default, index databases (`cocoindex.db` and `target_sqlite.db`) live alongside settings in `<project>/.cocoindex_code/`. When running in Docker, you may want the databases on the container's native filesystem for performance (LMDB doesn't work well on mounted volumes) while keeping the source code and settings on a mounted volume.
+
+Set `COCOINDEX_CODE_DB_PATH_MAPPING` to remap database locations by path prefix:
+
+```bash
+COCOINDEX_CODE_DB_PATH_MAPPING=/workspace=/db-files
+```
+
+With this mapping, a project at `/workspace/myrepo` stores its databases in `/db-files/myrepo/` instead of `/workspace/myrepo/.cocoindex_code/`. Settings files remain in the original location.
+
+Multiple mappings are comma-separated and resolved in order (first match wins):
+
+```bash
+COCOINDEX_CODE_DB_PATH_MAPPING=/workspace=/db-files,/workspace2=/db-files2
+```
+
+Both source and target must be absolute paths. If no mapping matches, the default location is used.
+
 ## 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.
@@ -498,6 +521,19 @@ If you previously configured `cocoindex-code` via environment variables, the `co
 
 If you need help with remote setup, please email our maintainer linghua@cocoindex.io, happy to help!
 
+## Contributing
+
+We welcome contributions! Before you start, please install the [pre-commit](https://pre-commit.com/) hooks so that linting, formatting, type checking, and tests run automatically before each commit:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+This catches common issues — trailing whitespace, lint errors (Ruff), type errors (mypy), and test failures — before they reach CI.
+
+For more details, see our [contributing guide](https://cocoindex.io/docs/contributing/guide).
+
 ## License
 
 Apache-2.0

{cocoindex_code-0.2.6 → cocoindex_code-0.2.8}/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 |
@@ -417,8 +418,30 @@ embedding:
 | xml | | `.xml` |
 | yaml | | `.yaml`, `.yml` |
 
+### Custom Database Location
+
+By default, index databases (`cocoindex.db` and `target_sqlite.db`) live alongside settings in `<project>/.cocoindex_code/`. When running in Docker, you may want the databases on the container's native filesystem for performance (LMDB doesn't work well on mounted volumes) while keeping the source code and settings on a mounted volume.
+
+Set `COCOINDEX_CODE_DB_PATH_MAPPING` to remap database locations by path prefix:
+
+```bash
+COCOINDEX_CODE_DB_PATH_MAPPING=/workspace=/db-files
+```
+
+With this mapping, a project at `/workspace/myrepo` stores its databases in `/db-files/myrepo/` instead of `/workspace/myrepo/.cocoindex_code/`. Settings files remain in the original location.
+
+Multiple mappings are comma-separated and resolved in order (first match wins):
+
+```bash
+COCOINDEX_CODE_DB_PATH_MAPPING=/workspace=/db-files,/workspace2=/db-files2
+```
+
+Both source and target must be absolute paths. If no mapping matches, the default location is used.
+
 ## 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.
@@ -459,6 +482,19 @@ If you previously configured `cocoindex-code` via environment variables, the `co
 
 If you need help with remote setup, please email our maintainer linghua@cocoindex.io, happy to help!
 
+## Contributing
+
+We welcome contributions! Before you start, please install the [pre-commit](https://pre-commit.com/) hooks so that linting, formatting, type checking, and tests run automatically before each commit:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+This catches common issues — trailing whitespace, lint errors (Ruff), type errors (mypy), and test failures — before they reach CI.
+
+For more details, see our [contributing guide](https://cocoindex.io/docs/contributing/guide).
+
 ## License
 
 Apache-2.0

{cocoindex_code-0.2.6 → cocoindex_code-0.2.8}/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.8'
+__version_tuple__ = version_tuple = (0, 2, 8)
 
 __commit_id__ = commit_id = None

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

@@ -2,16 +2,21 @@
 
 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,
     default_user_settings,
     find_parent_with_marker,
     find_project_root,
+    resolve_db_dir,
     save_project_settings,
     save_user_settings,
     user_settings_path,
@@ -35,8 +40,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 +62,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 +172,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 +289,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 +311,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 +323,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 +335,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 +372,7 @@ def search(
 
 
 @app.command()
+@_catch_daemon_start_error
 def status() -> None:
     """Show project status."""
     from . import client as _client
@@ -350,10 +390,11 @@ def reset(
     """Reset project databases and optionally remove settings."""
     project_root = require_project_root()
     cocoindex_dir = project_root / ".cocoindex_code"
+    db_dir = resolve_db_dir(project_root)
 
     db_files = [
-        cocoindex_dir / "cocoindex.db",
-        cocoindex_dir / "target_sqlite.db",
+        db_dir / "cocoindex.db",
+        db_dir / "target_sqlite.db",
     ]
     settings_file = cocoindex_dir / "settings.yml"
 
@@ -397,6 +438,12 @@ def reset(
             f.unlink(missing_ok=True)
 
     if all_:
+        # Remove db_dir if empty and different from cocoindex_dir
+        if db_dir != cocoindex_dir:
+            try:
+                db_dir.rmdir()
+            except OSError:
+                pass  # Not empty or doesn't exist
         # Remove .cocoindex_code/ if empty
         try:
             cocoindex_dir.rmdir()
@@ -446,6 +493,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
@@ -499,6 +547,10 @@ def doctor() -> None:
             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))}")
+            if env_resp.db_path_mappings:
+                _typer.echo("  DB path mappings:")
+                for m in env_resp.db_path_mappings:
+                    _typer.echo(f"    {m.source} \u2192 {m.target}")
         except Exception as e:
             _print_error(f"Failed to get daemon env: {e}")
 
@@ -553,6 +605,7 @@ def doctor() -> None:
 
 
 @app.command()
+@_catch_daemon_start_error
 def mcp() -> None:
     """Run as MCP server (stdio mode)."""
     import asyncio
@@ -586,6 +639,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 +657,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 +666,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.8}/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.8}/src/cocoindex_code/config.py

@@ -7,6 +7,8 @@ import os
 from dataclasses import dataclass
 from pathlib import Path
 
+from .settings import resolve_db_dir
+
 _DEFAULT_MODEL = "sbert/sentence-transformers/all-MiniLM-L6-v2"
 
 
@@ -96,8 +98,8 @@ class Config:
             _DEFAULT_MODEL,
         )
 
-        # Index directory is always under the root
-        index_dir = root / ".cocoindex_code"
+        # Index directory: apply DB path mapping if configured
+        index_dir = resolve_db_dir(root)
 
         # Device: auto-detect CUDA or use env override
         device = os.environ.get("COCOINDEX_CODE_DEVICE")

{cocoindex_code-0.2.6 → cocoindex_code-0.2.8}/src/cocoindex_code/daemon.py

@@ -48,6 +48,7 @@ from .protocol import (
 from .settings import (
     global_settings_mtime_us,
     load_user_settings,
+    resolve_db_dir,
     user_settings_dir,
 )
 from .shared import Embedder, create_embedder
@@ -345,7 +346,7 @@ async def _check_index_status(project_root_str: str) -> DoctorCheckResult:
     from cocoindex.connectors import sqlite as coco_sqlite
 
     project_root = Path(project_root_str)
-    db_path = project_root / ".cocoindex_code" / "target_sqlite.db"
+    db_path = resolve_db_dir(project_root) / "target_sqlite.db"
     details = [f"Index: {db_path}"]
 
     if not db_path.exists():
@@ -441,9 +442,16 @@ async def _dispatch(
             return StopResponse(ok=True)
 
         if isinstance(req, DaemonEnvRequest):
+            from .protocol import DbPathMappingEntry
+            from .settings import get_db_path_mappings
+
             return DaemonEnvResponse(
                 env_names=sorted(os.environ.keys()),
                 settings_env_names=settings_env_names,
+                db_path_mappings=[
+                    DbPathMappingEntry(source=str(m.source), target=str(m.target))
+                    for m in get_db_path_mappings()
+                ],
             )
 
         if isinstance(req, DoctorRequest):

{cocoindex_code-0.2.6 → cocoindex_code-0.2.8}/src/cocoindex_code/project.py

@@ -21,6 +21,7 @@ from .protocol import (
     SearchResult,
 )
 from .query import query_codebase
+from .settings import resolve_db_dir
 from .shared import (
     CODEBASE_DIR,
     EMBEDDER,
@@ -170,7 +171,7 @@ class Project:
         offset: int = 0,
     ) -> list[SearchResult]:
         """Search within this project."""
-        target_db = self._project_root / ".cocoindex_code" / "target_sqlite.db"
+        target_db = resolve_db_dir(self._project_root) / "target_sqlite.db"
         results = await query_codebase(
             query=query,
             target_sqlite_db_path=target_db,
@@ -254,11 +255,14 @@ class Project:
         indexer loads them fresh from disk on every run so that user edits
         take effect without restarting the daemon.
         """
-        index_dir = project_root / ".cocoindex_code"
-        index_dir.mkdir(parents=True, exist_ok=True)
+        settings_dir = project_root / ".cocoindex_code"
+        settings_dir.mkdir(parents=True, exist_ok=True)
 
-        cocoindex_db_path = index_dir / "cocoindex.db"
-        target_sqlite_db_path = index_dir / "target_sqlite.db"
+        db_dir = resolve_db_dir(project_root)
+        db_dir.mkdir(parents=True, exist_ok=True)
+
+        cocoindex_db_path = db_dir / "cocoindex.db"
+        target_sqlite_db_path = db_dir / "target_sqlite.db"
 
         settings = coco.Settings.from_env(cocoindex_db_path)
 

{cocoindex_code-0.2.6 → cocoindex_code-0.2.8}/src/cocoindex_code/protocol.py

@@ -158,9 +158,15 @@ class DoctorResponse(_msgspec.Struct, tag="doctor"):
     final: bool = False
 
 
+class DbPathMappingEntry(_msgspec.Struct):
+    source: str
+    target: str
+
+
 class DaemonEnvResponse(_msgspec.Struct, tag="daemon_env"):
     env_names: list[str]
     settings_env_names: list[str]
+    db_path_mappings: list[DbPathMappingEntry] = []
 
 
 class ErrorResponse(_msgspec.Struct, tag="error"):

{cocoindex_code-0.2.6 → cocoindex_code-0.2.8}/src/cocoindex_code/settings.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
@@ -115,14 +116,89 @@ _SETTINGS_DIR_NAME = ".cocoindex_code"
 _SETTINGS_FILE_NAME = "settings.yml"  # project-level
 _USER_SETTINGS_FILE_NAME = "global_settings.yml"  # user-level
 
+_ENV_DB_PATH_MAPPING = "COCOINDEX_CODE_DB_PATH_MAPPING"
+
+
+@dataclass
+class DbPathMapping:
+    source: Path
+    target: Path
+
+
+_db_path_mapping: list[DbPathMapping] | None = None
+
+
+def _parse_db_path_mapping() -> list[DbPathMapping]:
+    """Parse ``COCOINDEX_CODE_DB_PATH_MAPPING`` env var.
+
+    Format: ``/src1=/dst1,/src2=/dst2``
+    Both source and target must be absolute paths.
+    """
+    raw = os.environ.get(_ENV_DB_PATH_MAPPING, "")
+    if not raw.strip():
+        return []
+
+    mappings: list[DbPathMapping] = []
+    for entry in raw.split(","):
+        entry = entry.strip()
+        if not entry:
+            continue
+        parts = entry.split("=", 1)
+        if len(parts) != 2 or not parts[0] or not parts[1]:
+            raise ValueError(
+                f"{_ENV_DB_PATH_MAPPING}: invalid entry {entry!r}, expected format 'source=target'"
+            )
+        source = Path(parts[0])
+        target = Path(parts[1])
+        if not source.is_absolute():
+            raise ValueError(
+                f"{_ENV_DB_PATH_MAPPING}: source path must be absolute, got {source!r}"
+            )
+        if not target.is_absolute():
+            raise ValueError(
+                f"{_ENV_DB_PATH_MAPPING}: target path must be absolute, got {target!r}"
+            )
+        mappings.append(DbPathMapping(source=source.resolve(), target=target.resolve()))
+    return mappings
+
+
+def resolve_db_dir(project_root: Path) -> Path:
+    """Return the directory for database files given a project root.
+
+    Applies ``COCOINDEX_CODE_DB_PATH_MAPPING`` if set, otherwise falls back
+    to ``project_root / ".cocoindex_code"``.
+    """
+    global _db_path_mapping  # noqa: PLW0603
+    if _db_path_mapping is None:
+        _db_path_mapping = _parse_db_path_mapping()
+
+    resolved = project_root.resolve()
+    for mapping in _db_path_mapping:
+        if resolved == mapping.source or resolved.is_relative_to(mapping.source):
+            rel = resolved.relative_to(mapping.source)
+            return mapping.target / rel
+    return project_root / _SETTINGS_DIR_NAME
+
+
+def get_db_path_mappings() -> list[DbPathMapping]:
+    """Return the parsed DB path mappings from ``COCOINDEX_CODE_DB_PATH_MAPPING``."""
+    global _db_path_mapping  # noqa: PLW0603
+    if _db_path_mapping is None:
+        _db_path_mapping = _parse_db_path_mapping()
+    return list(_db_path_mapping)
+
+
+def _reset_db_path_mapping_cache() -> None:
+    """Reset the cached mapping (for tests)."""
+    global _db_path_mapping  # noqa: PLW0603
+    _db_path_mapping = None
+
 
 def user_settings_dir() -> Path:
     """Return ``~/.cocoindex_code/``.
 
     Respects ``COCOINDEX_CODE_DIR`` env var for overriding the base directory.
     """
-    import os
-
     override = os.environ.get("COCOINDEX_CODE_DIR")
     if override:
         return Path(override)
@@ -240,7 +316,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 +364,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 +391,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: