cocoindex-code 0.2.23__tar.gz → 0.2.24__tar.gz

{cocoindex_code-0.2.23 → cocoindex_code-0.2.24}/.gitignore

@@ -46,3 +46,7 @@ src/cocoindex_code/_version.py
 
 # CocoIndex Code (ccc)
 /.cocoindex_code/
+
+# Docker E2E fixtures contain a `lib/` dir that the generic Python rule above
+# would ignore — keep it tracked.
+!tests/e2e_docker_fixtures/**

{cocoindex_code-0.2.23 → cocoindex_code-0.2.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocoindex-code
-Version: 0.2.23
+Version: 0.2.24
 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
@@ -242,33 +242,79 @@ The recommended approach is a **persistent container**: start it once, and use
 `docker exec` to run CLI commands or connect MCP sessions to it. The daemon
 inside stays warm across sessions, so the embedding model is loaded only once.
 
-### Step 1 — Start the container
+### Quick start — `docker compose up -d`
+
+Grab [`docker/docker-compose.yml`](./docker/docker-compose.yml) from this repo and run:
+
+```bash
+# macOS / Windows
+docker compose up -d
+
+# Linux (aligns file ownership on bind-mounted paths with your host user)
+PUID=$(id -u) PGID=$(id -g) docker compose up -d
+```
+
+By default your home directory is mounted into the container (set
+`COCOINDEX_HOST_WORKSPACE` to narrow this to a specific code folder). Index
+data and the embedding model cache persist in a Docker volume across
+restarts. Your global settings file at `$HOME/.cocoindex_code/global_settings.yml`
+is visible and editable on the host; edits take effect on your next `ccc` command.
+
+> **GHCR:** to pull from GitHub Container Registry instead of Docker Hub,
+> change the `image:` line in your copy of `docker-compose.yml` to
+> `ghcr.io/cocoindex-io/cocoindex-code:latest`.
+
+### Or: `docker run`
+
+<details>
+<summary>Docker Desktop (macOS / Windows)</summary>
 
 ```bash
 docker run -d --name cocoindex-code \
-  --volume "$(pwd):/workspace" \
-  --volume cocoindex-db:/db \
-  --volume cocoindex-model-cache:/root/.cache \
-  ghcr.io/cocoindex-io/cocoindex-code:latest
+  --volume "$HOME:/workspace" \
+  --volume cocoindex-data:/var/cocoindex \
+  -e COCOINDEX_CODE_HOST_PATH_MAPPING="/workspace=$HOME" \
+  cocoindex/cocoindex-code:latest
 ```
+</details>
 
-- `/workspace` — mount your project root here
-- `cocoindex-db` — index databases live inside the container (fast native I/O, no cross-OS volume issues)
-- `cocoindex-model-cache` — persists the embedding model across image upgrades
+<details>
+<summary>Linux (with <code>PUID</code>/<code>PGID</code>)</summary>
 
-### Step 2 — Index your codebase
+```bash
+docker run -d --name cocoindex-code \
+  -e PUID=$(id -u) -e PGID=$(id -g) \
+  --volume "$HOME:/workspace" \
+  --volume cocoindex-data:/var/cocoindex \
+  -e COCOINDEX_CODE_HOST_PATH_MAPPING="/workspace=$HOME" \
+  cocoindex/cocoindex-code:latest
+```
+</details>
+
+### Shell wrapper for `ccc` commands
+
+Paste this into `~/.bashrc` / `~/.zshrc` so `ccc` feels native on the host
+and picks up the right project based on your current directory:
 
 ```bash
-docker exec -it cocoindex-code ccc index
+ccc() {
+  docker exec -it -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc "$@"
+}
 ```
 
-### Step 3 — Connect your coding agent
+Now `cd` into any project under your workspace and run `ccc init`, `ccc index`,
+`ccc search ...`, `ccc status`, etc. — it just works.
+
+### Connect your coding agent
 
 <details>
 <summary>Claude Code</summary>
 
+Register MCP from inside the target project so `$PWD` points there:
+
 ```bash
-claude mcp add cocoindex-code -- docker exec -i cocoindex-code ccc mcp
+claude mcp add cocoindex-code -- docker exec -i \
+  -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc mcp
 ```
 
 Or via `.mcp.json`:
@@ -279,40 +325,50 @@ Or via `.mcp.json`:
     "cocoindex-code": {
       "type": "stdio",
       "command": "docker",
-      "args": ["exec", "-i", "cocoindex-code", "ccc", "mcp"]
+      "args": [
+        "exec",
+        "-i",
+        "-e",
+        "COCOINDEX_CODE_HOST_CWD=${PWD}",
+        "cocoindex-code",
+        "ccc",
+        "mcp"
+      ]
     }
   }
 }
 ```
+
+> Note: use `-i` (not `-it`). The `-t` flag allocates a terminal, which
+> interferes with MCP's JSON messaging over stdin/stdout — only add it for
+> interactive `ccc` commands like `ccc init`.
 </details>
 
 <details>
 <summary>Codex</summary>
 
 ```bash
-codex mcp add cocoindex-code -- docker exec -i cocoindex-code ccc mcp
+codex mcp add cocoindex-code -- docker exec -i \
+  -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc mcp
 ```
 </details>
 
-### CLI usage inside the container
+### Upgrading from an older image
 
-All `ccc` commands work via `docker exec`:
+Earlier images used separate `cocoindex-db` and `cocoindex-model-cache`
+volumes; the current image consolidates them into a single `cocoindex-data`
+volume. Before pulling the new image, drop the old container and volumes —
+indexes rebuild on your next `ccc index`, and the embedding model is
+re-populated automatically on first start:
 
 ```bash
-docker exec -it cocoindex-code ccc index
-docker exec -it cocoindex-code ccc search "authentication logic"
-docker exec -it cocoindex-code ccc status
-```
-
-Or set an alias on your host so it feels native:
-
-```bash
-alias ccc='docker exec -it cocoindex-code ccc'
+docker rm -f cocoindex-code
+docker volume rm cocoindex-db cocoindex-model-cache
 ```
 
 ### Configuration via environment variables
 
-Pass configuration to `docker run` with `-e`:
+Pass configuration to `docker run` / compose with `-e`:
 
 ```bash
 # Extra extensions (e.g. Typesafe Config, SBT build files)
@@ -325,6 +381,10 @@ Pass configuration to `docker run` with `-e`:
 -e VOYAGE_API_KEY=your-key
 ```
 
+> **Security note:** mounting `$HOME` gives the container read/write access
+> to everything under it. If that's too broad, bind-mount a narrower
+> directory instead (`COCOINDEX_HOST_WORKSPACE=/path/to/code`).
+
 ### Build the image locally
 
 ```bash
@@ -359,6 +419,8 @@ envs:                                                # extra environment variabl
 
 > **Note:** The daemon inherits your shell environment. If an API key (e.g. `OPENAI_API_KEY`) is already set as an environment variable, you don't need to duplicate it in `envs`. The `envs` field is only for values that aren't in your environment.
 
+> **Custom location:** set `COCOINDEX_CODE_DIR` to place `global_settings.yml` somewhere other than `~/.cocoindex_code/` — useful if you want the file to live alongside your projects (e.g. on a synced folder).
+
 ### Project Settings (`<project>/.cocoindex_code/settings.yml`)
 
 Per-project. Controls which files to index.

{cocoindex_code-0.2.23 → cocoindex_code-0.2.24}/README.md

@@ -198,33 +198,79 @@ The recommended approach is a **persistent container**: start it once, and use
 `docker exec` to run CLI commands or connect MCP sessions to it. The daemon
 inside stays warm across sessions, so the embedding model is loaded only once.
 
-### Step 1 — Start the container
+### Quick start — `docker compose up -d`
+
+Grab [`docker/docker-compose.yml`](./docker/docker-compose.yml) from this repo and run:
+
+```bash
+# macOS / Windows
+docker compose up -d
+
+# Linux (aligns file ownership on bind-mounted paths with your host user)
+PUID=$(id -u) PGID=$(id -g) docker compose up -d
+```
+
+By default your home directory is mounted into the container (set
+`COCOINDEX_HOST_WORKSPACE` to narrow this to a specific code folder). Index
+data and the embedding model cache persist in a Docker volume across
+restarts. Your global settings file at `$HOME/.cocoindex_code/global_settings.yml`
+is visible and editable on the host; edits take effect on your next `ccc` command.
+
+> **GHCR:** to pull from GitHub Container Registry instead of Docker Hub,
+> change the `image:` line in your copy of `docker-compose.yml` to
+> `ghcr.io/cocoindex-io/cocoindex-code:latest`.
+
+### Or: `docker run`
+
+<details>
+<summary>Docker Desktop (macOS / Windows)</summary>
 
 ```bash
 docker run -d --name cocoindex-code \
-  --volume "$(pwd):/workspace" \
-  --volume cocoindex-db:/db \
-  --volume cocoindex-model-cache:/root/.cache \
-  ghcr.io/cocoindex-io/cocoindex-code:latest
+  --volume "$HOME:/workspace" \
+  --volume cocoindex-data:/var/cocoindex \
+  -e COCOINDEX_CODE_HOST_PATH_MAPPING="/workspace=$HOME" \
+  cocoindex/cocoindex-code:latest
 ```
+</details>
 
-- `/workspace` — mount your project root here
-- `cocoindex-db` — index databases live inside the container (fast native I/O, no cross-OS volume issues)
-- `cocoindex-model-cache` — persists the embedding model across image upgrades
+<details>
+<summary>Linux (with <code>PUID</code>/<code>PGID</code>)</summary>
 
-### Step 2 — Index your codebase
+```bash
+docker run -d --name cocoindex-code \
+  -e PUID=$(id -u) -e PGID=$(id -g) \
+  --volume "$HOME:/workspace" \
+  --volume cocoindex-data:/var/cocoindex \
+  -e COCOINDEX_CODE_HOST_PATH_MAPPING="/workspace=$HOME" \
+  cocoindex/cocoindex-code:latest
+```
+</details>
+
+### Shell wrapper for `ccc` commands
+
+Paste this into `~/.bashrc` / `~/.zshrc` so `ccc` feels native on the host
+and picks up the right project based on your current directory:
 
 ```bash
-docker exec -it cocoindex-code ccc index
+ccc() {
+  docker exec -it -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc "$@"
+}
 ```
 
-### Step 3 — Connect your coding agent
+Now `cd` into any project under your workspace and run `ccc init`, `ccc index`,
+`ccc search ...`, `ccc status`, etc. — it just works.
+
+### Connect your coding agent
 
 <details>
 <summary>Claude Code</summary>
 
+Register MCP from inside the target project so `$PWD` points there:
+
 ```bash
-claude mcp add cocoindex-code -- docker exec -i cocoindex-code ccc mcp
+claude mcp add cocoindex-code -- docker exec -i \
+  -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc mcp
 ```
 
 Or via `.mcp.json`:
@@ -235,40 +281,50 @@ Or via `.mcp.json`:
     "cocoindex-code": {
       "type": "stdio",
       "command": "docker",
-      "args": ["exec", "-i", "cocoindex-code", "ccc", "mcp"]
+      "args": [
+        "exec",
+        "-i",
+        "-e",
+        "COCOINDEX_CODE_HOST_CWD=${PWD}",
+        "cocoindex-code",
+        "ccc",
+        "mcp"
+      ]
     }
   }
 }
 ```
+
+> Note: use `-i` (not `-it`). The `-t` flag allocates a terminal, which
+> interferes with MCP's JSON messaging over stdin/stdout — only add it for
+> interactive `ccc` commands like `ccc init`.
 </details>
 
 <details>
 <summary>Codex</summary>
 
 ```bash
-codex mcp add cocoindex-code -- docker exec -i cocoindex-code ccc mcp
+codex mcp add cocoindex-code -- docker exec -i \
+  -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc mcp
 ```
 </details>
 
-### CLI usage inside the container
+### Upgrading from an older image
 
-All `ccc` commands work via `docker exec`:
+Earlier images used separate `cocoindex-db` and `cocoindex-model-cache`
+volumes; the current image consolidates them into a single `cocoindex-data`
+volume. Before pulling the new image, drop the old container and volumes —
+indexes rebuild on your next `ccc index`, and the embedding model is
+re-populated automatically on first start:
 
 ```bash
-docker exec -it cocoindex-code ccc index
-docker exec -it cocoindex-code ccc search "authentication logic"
-docker exec -it cocoindex-code ccc status
-```
-
-Or set an alias on your host so it feels native:
-
-```bash
-alias ccc='docker exec -it cocoindex-code ccc'
+docker rm -f cocoindex-code
+docker volume rm cocoindex-db cocoindex-model-cache
 ```
 
 ### Configuration via environment variables
 
-Pass configuration to `docker run` with `-e`:
+Pass configuration to `docker run` / compose with `-e`:
 
 ```bash
 # Extra extensions (e.g. Typesafe Config, SBT build files)
@@ -281,6 +337,10 @@ Pass configuration to `docker run` with `-e`:
 -e VOYAGE_API_KEY=your-key
 ```
 
+> **Security note:** mounting `$HOME` gives the container read/write access
+> to everything under it. If that's too broad, bind-mount a narrower
+> directory instead (`COCOINDEX_HOST_WORKSPACE=/path/to/code`).
+
 ### Build the image locally
 
 ```bash
@@ -315,6 +375,8 @@ envs:                                                # extra environment variabl
 
 > **Note:** The daemon inherits your shell environment. If an API key (e.g. `OPENAI_API_KEY`) is already set as an environment variable, you don't need to duplicate it in `envs`. The `envs` field is only for values that aren't in your environment.
 
+> **Custom location:** set `COCOINDEX_CODE_DIR` to place `global_settings.yml` somewhere other than `~/.cocoindex_code/` — useful if you want the file to live alongside your projects (e.g. on a synced folder).
+
 ### Project Settings (`<project>/.cocoindex_code/settings.yml`)
 
 Per-project. Controls which files to index.

{cocoindex_code-0.2.23 → cocoindex_code-0.2.24}/pyproject.toml

@@ -105,5 +105,8 @@ explicit_package_bases = true
 testpaths = ["tests"]
 python_files = ["test_*.py"]
 python_functions = ["test_*"]
-addopts = "-v --tb=short"
+addopts = "-v --tb=short -m 'not docker_e2e'"
 asyncio_mode = "auto"
+markers = [
+    "docker_e2e: requires Docker; builds the image and runs containerized E2E tests. Run with: pytest -m docker_e2e",
+]

cocoindex_code-0.2.24/src/cocoindex_code/_daemon_paths.py

@@ -0,0 +1,60 @@
+"""Daemon filesystem paths and connection helpers.
+
+Lightweight module with no cocoindex dependency so that the CLI client
+can import these without pulling in the full daemon stack.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from .settings import user_settings_dir
+
+
+def daemon_runtime_dir() -> Path:
+    """Return the directory that holds daemon runtime artifacts.
+
+    Holds ``daemon.sock``, ``daemon.pid``, ``daemon.log``. Kept separate from
+    the user-settings dir so that (e.g. in Docker) the socket can live on the
+    container's native filesystem while ``global_settings.yml`` lives on a
+    bind mount.
+
+    Override with ``COCOINDEX_CODE_RUNTIME_DIR``. Defaults to
+    :func:`user_settings_dir` for backward compatibility — non-Docker users
+    see identical behavior to before the split.
+    """
+    override = os.environ.get("COCOINDEX_CODE_RUNTIME_DIR")
+    if override:
+        return Path(override)
+    return user_settings_dir()
+
+
+def connection_family() -> str:
+    """Return the multiprocessing connection family for this platform."""
+    return "AF_PIPE" if sys.platform == "win32" else "AF_UNIX"
+
+
+def daemon_socket_path() -> str:
+    """Return the daemon socket/pipe address."""
+    if sys.platform == "win32":
+        import hashlib
+
+        # Hash the runtime dir so COCOINDEX_CODE_RUNTIME_DIR (or the
+        # COCOINDEX_CODE_DIR fallback) overrides produce unique pipe names,
+        # preventing conflicts between different daemon instances (tests,
+        # users, etc.)
+        dir_hash = hashlib.md5(str(daemon_runtime_dir()).encode()).hexdigest()[:12]
+        return rf"\\.\pipe\cocoindex_code_{dir_hash}"
+    return str(daemon_runtime_dir() / "daemon.sock")
+
+
+def daemon_pid_path() -> Path:
+    """Return the path for the daemon's PID file."""
+    return daemon_runtime_dir() / "daemon.pid"
+
+
+def daemon_log_path() -> Path:
+    """Return the path for the daemon's log file."""
+    return daemon_runtime_dir() / "daemon.log"

{cocoindex_code-0.2.23 → cocoindex_code-0.2.24}/src/cocoindex_code/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.23'
-__version_tuple__ = version_tuple = (0, 2, 23)
+__version__ = version = '0.2.24'
+__version_tuple__ = version_tuple = (0, 2, 24)
 
 __commit_id__ = commit_id = None

{cocoindex_code-0.2.23 → cocoindex_code-0.2.24}/src/cocoindex_code/cli.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import functools
+import os
 import sys
 from collections.abc import Callable
 from pathlib import Path
@@ -19,6 +20,8 @@ from .settings import (
     default_project_settings,
     find_parent_with_marker,
     find_project_root,
+    format_path_for_display,
+    normalize_input_path,
     project_settings_path,
     resolve_db_dir,
     save_initial_user_settings,
@@ -37,6 +40,29 @@ daemon_app = _typer.Typer(name="daemon", help="Manage the daemon process.")
 app.add_typer(daemon_app, name="daemon")
 
 
+@app.callback()
+def _apply_host_cwd() -> None:
+    """Honor ``COCOINDEX_CODE_HOST_CWD`` when forwarded from a ``docker exec`` wrapper.
+
+    The env var carries the host shell's pwd verbatim. We normalize it through
+    the host path mapping to container form and ``chdir`` there so
+    cwd-driven discovery (``find_project_root`` etc.) sees the user's real
+    project subtree. Unset → no-op.
+    """
+    host_cwd = os.environ.get("COCOINDEX_CODE_HOST_CWD")
+    if not host_cwd:
+        return
+    target = normalize_input_path(host_cwd)
+    try:
+        os.chdir(target)
+    except OSError as e:
+        _typer.echo(
+            f"Warning: COCOINDEX_CODE_HOST_CWD={host_cwd!r} → {target!r} "
+            f"is not accessible: {e}. Continuing with cwd={os.getcwd()!r}.",
+            err=True,
+        )
+
+
 # ---------------------------------------------------------------------------
 # Shared CLI helpers
 # ---------------------------------------------------------------------------
@@ -51,7 +77,7 @@ def require_project_root() -> Path:
     gs_path = user_settings_path()
     if not gs_path.is_file():
         _typer.echo(
-            f"Error: Global settings not found: {gs_path}\n"
+            f"Error: Global settings not found: {format_path_for_display(gs_path)}\n"
             "Run `ccc init` to create it with default settings.",
             err=True,
         )
@@ -112,7 +138,7 @@ def _format_progress(progress: IndexingProgress) -> str:
 
 def print_project_header(project_root: str) -> None:
     """Print the project root directory."""
-    _typer.echo(f"Project: {project_root}")
+    _typer.echo(f"Project: {format_path_for_display(project_root)}")
 
 
 def print_index_stats(status: ProjectStatusResponse) -> None:
@@ -400,8 +426,9 @@ def _run_init_model_check(settings_path: Path) -> None:
             failed = True
 
     if failed:
+        display_path = format_path_for_display(settings_path)
         _typer.echo(
-            f"You can edit {settings_path} to change the model or add API keys\n"
+            f"You can edit {display_path} to change the model or add API keys\n"
             "under `envs:`. Then run `ccc doctor` to verify.",
             err=True,
         )
@@ -419,7 +446,7 @@ def _setup_user_settings_interactive(litellm_model_flag: str | None) -> None:
 
     path = save_initial_user_settings(embedding)
     _typer.echo()
-    _typer.echo(f"Created user settings: {path}")
+    _typer.echo(f"Created user settings: {format_path_for_display(path)}")
 
     _typer.echo()
     _typer.echo(f"Testing embedding model: {embedding.provider} / {embedding.model}")
@@ -443,8 +470,9 @@ def init(
     user_path = user_settings_path()
     if user_path.is_file():
         if litellm_model is not None:
+            display_path = format_path_for_display(user_path)
             _typer.echo(
-                f"Error: global settings already exist at {user_path}.\n"
+                f"Error: global settings already exist at {display_path}.\n"
                 "Edit that file or remove it before passing `--litellm-model`.",
                 err=True,
             )
@@ -461,8 +489,9 @@ def init(
     if not force:
         parent = find_parent_with_marker(cwd)
         if parent is not None and parent != cwd:
+            display_parent = format_path_for_display(parent)
             _typer.echo(
-                f"Warning: A parent directory has a project marker: {parent}\n"
+                f"Warning: A parent directory has a project marker: {display_parent}\n"
                 "You might want to run `ccc init` there instead.\n"
                 "Use `ccc init -f` to initialize here anyway."
             )
@@ -470,7 +499,7 @@ def init(
 
     # Create project settings
     save_project_settings(cwd, default_project_settings())
-    _typer.echo(f"Created project settings: {settings_file}")
+    _typer.echo(f"Created project settings: {format_path_for_display(settings_file)}")
 
     # Add to .gitignore
     add_to_gitignore(cwd)
@@ -538,10 +567,10 @@ def status() -> None:
     project_root = str(project_root_path)
     print_project_header(project_root)
 
-    _typer.echo(f"Settings: {project_settings_path(project_root_path)}")
+    _typer.echo(f"Settings: {format_path_for_display(project_settings_path(project_root_path))}")
     db_path = target_sqlite_db_path(project_root_path)
     if db_path.exists():
-        _typer.echo(f"Index DB: {db_path}")
+        _typer.echo(f"Index DB: {format_path_for_display(db_path)}")
 
     print_index_stats(_client.project_status(project_root))
 
@@ -576,7 +605,7 @@ def reset(
     if to_delete:
         _typer.echo("The following files will be deleted:")
         for f in to_delete:
-            _typer.echo(f"  {f}")
+            _typer.echo(f"  {format_path_for_display(f)}")
 
     # Confirm
     if not force:
@@ -668,7 +697,7 @@ def doctor() -> None:
     # --- 1. Global settings (local, no daemon needed) ---
     _print_section("Global Settings")
     settings_path = user_settings_path()
-    _typer.echo(f"  Settings: {settings_path}")
+    _typer.echo(f"  Settings: {format_path_for_display(settings_path)}")
     try:
         user_settings = _load_user_settings()
         emb = user_settings.embedding
@@ -706,6 +735,10 @@ def doctor() -> None:
                 _typer.echo("  DB path mappings:")
                 for m in env_resp.db_path_mappings:
                     _typer.echo(f"    {m.source} \u2192 {m.target}")
+            if env_resp.host_path_mappings:
+                _typer.echo("  Host path mappings:")
+                for m in env_resp.host_path_mappings:
+                    _typer.echo(f"    {m.source} \u2192 {m.target}")
         except Exception as e:
             _print_error(f"Failed to get daemon env: {e}")
 
@@ -726,7 +759,7 @@ def doctor() -> None:
     if project_root is not None:
         _print_section("Project Settings")
         ps_path = project_settings_path(project_root)
-        _typer.echo(f"  Settings: {ps_path}")
+        _typer.echo(f"  Settings: {format_path_for_display(ps_path)}")
         try:
             ps = _load_project_settings(project_root)
             _typer.echo(f"  Include patterns ({len(ps.include_patterns)}):")
@@ -754,7 +787,7 @@ def doctor() -> None:
     _print_section("Log Files")
     from ._daemon_paths import daemon_log_path as _daemon_log_path
 
-    _typer.echo(f"  Daemon logs: {_daemon_log_path()}")
+    _typer.echo(f"  Daemon logs: {format_path_for_display(_daemon_log_path())}")
     _typer.echo("  Check logs above for further troubleshooting.")
 
 
@@ -805,7 +838,7 @@ def daemon_status() -> None:
         _typer.echo("Projects:")
         for p in resp.projects:
             state = "indexing" if p.indexing else "idle"
-            _typer.echo(f"  {p.project_root} [{state}]")
+            _typer.echo(f"  {format_path_for_display(p.project_root)} [{state}]")
     else:
         _typer.echo("No projects loaded.")
 

{cocoindex_code-0.2.23 → cocoindex_code-0.2.24}/src/cocoindex_code/client.py

@@ -19,9 +19,9 @@ from pathlib import Path
 
 from ._daemon_paths import (
     connection_family,
-    daemon_dir,
     daemon_log_path,
     daemon_pid_path,
+    daemon_runtime_dir,
     daemon_socket_path,
 )
 from ._version import __version__
@@ -53,6 +53,7 @@ from .protocol import (
     decode_response,
     encode_request,
 )
+from .settings import normalize_input_path
 
 logger = logging.getLogger(__name__)
 
@@ -65,6 +66,14 @@ logger = logging.getLogger(__name__)
 _daemon_ensured = False
 
 
+def _is_daemon_supervised() -> bool:
+    """True when an external supervisor (Docker entrypoint loop, systemd, …) owns
+    daemon respawn. The client in that mode calls ``stop_daemon`` but never
+    ``start_daemon`` — it just waits for the socket to reappear.
+    """
+    return os.environ.get("COCOINDEX_CODE_DAEMON_SUPERVISED") == "1"
+
+
 def _connect_and_handshake() -> Connection:
     """Connect to the daemon and perform the version handshake.
 
@@ -90,8 +99,13 @@ def _connect_and_handshake() -> Connection:
     except (ConnectionRefusedError, OSError):
         pass
 
-    proc = start_daemon()
-    _wait_for_daemon(proc=proc)
+    if _is_daemon_supervised():
+        # Supervisor is responsible for (re)starting the daemon — just wait
+        # for the socket to reappear.
+        _wait_for_daemon()
+    else:
+        proc = start_daemon()
+        _wait_for_daemon(proc=proc)
 
     # Verify the fresh daemon is reachable
     for _attempt in range(10):
@@ -199,6 +213,7 @@ def index(
     on_waiting: Callable[[], None] | None = None,
 ) -> IndexResponse:
     """Request indexing with streaming progress. Blocks until complete."""
+    project_root = normalize_input_path(project_root)
     conn = _connect_and_handshake()
     try:
         conn.send_bytes(encode_request(IndexRequest(project_root=project_root)))
@@ -240,6 +255,7 @@ def search(
     progress), calls *on_waiting* (if provided) then continues reading
     until the final ``SearchResponse``.
     """
+    project_root = normalize_input_path(project_root)
     conn = _connect_and_handshake()
     try:
         conn.send_bytes(
@@ -274,7 +290,7 @@ def search(
 
 
 def project_status(project_root: str) -> ProjectStatusResponse:
-    return _send(ProjectStatusRequest(project_root=project_root))  # type: ignore[return-value]
+    return _send(ProjectStatusRequest(project_root=normalize_input_path(project_root)))  # type: ignore[return-value]
 
 
 def daemon_status() -> DaemonStatusResponse:
@@ -284,7 +300,7 @@ def daemon_status() -> DaemonStatusResponse:
 
 
 def remove_project(project_root: str) -> RemoveProjectResponse:
-    return _send(RemoveProjectRequest(project_root=project_root))  # type: ignore[return-value]
+    return _send(RemoveProjectRequest(project_root=normalize_input_path(project_root)))  # type: ignore[return-value]
 
 
 def stop() -> StopResponse:
@@ -301,6 +317,8 @@ def doctor(
     on_result: Callable[[DoctorCheckResult], None] | None = None,
 ) -> list[DoctorCheckResult]:
     """Run doctor checks via daemon, streaming results to on_result callback."""
+    if project_root is not None:
+        project_root = normalize_input_path(project_root)
     conn = _connect_and_handshake()
     try:
         conn.send_bytes(encode_request(DoctorRequest(project_root=project_root)))
@@ -349,7 +367,7 @@ def start_daemon() -> subprocess.Popen[bytes]:
     Returns the ``Popen`` object so callers can detect early process death
     (via ``proc.poll()``) instead of waiting for a full timeout.
     """
-    daemon_dir().mkdir(parents=True, exist_ok=True)
+    daemon_runtime_dir().mkdir(parents=True, exist_ok=True)
     log_path = daemon_log_path()
 
     ccc_path = _find_ccc_executable()
@@ -508,18 +526,16 @@ def _wait_for_daemon(
     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.
+
+    Socket existence is checked *before* ``proc.poll()`` so that races with a
+    supervisor (e.g. the Docker entrypoint restart loop) don't spuriously raise
+    ``DaemonStartError``: if the supervisor wins the bind and our subprocess
+    exits because the socket is already in use, the socket is still ready — we
+    should return success, not flag a failure.
     """
     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())
@@ -530,6 +546,16 @@ def _wait_for_daemon(
         else:
             if os.path.exists(sock_path):
                 return
+
+        # Daemon socket not yet up — if we spawned a subprocess that already
+        # exited, bail out with its log.
+        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)
+
         time.sleep(0.2)
 
     # Timeout — also include log for diagnostics.

{cocoindex_code-0.2.23 → cocoindex_code-0.2.24}/src/cocoindex_code/daemon.py

@@ -17,9 +17,9 @@ from typing import Any
 
 from ._daemon_paths import (
     connection_family,
-    daemon_dir,
     daemon_log_path,
     daemon_pid_path,
+    daemon_runtime_dir,
     daemon_socket_path,
 )
 from ._version import __version__
@@ -56,10 +56,13 @@ from .protocol import (
 )
 from .settings import (
     ChunkerMapping,
+    format_path_for_display,
+    get_host_path_mappings,
     global_settings_mtime_us,
     load_project_settings,
     load_user_settings,
     target_sqlite_db_path,
+    user_settings_path,
 )
 from .shared import Embedder, check_embedding, create_embedder
 
@@ -91,17 +94,28 @@ def _resolve_chunker_registry(mappings: list[ChunkerMapping]) -> dict[str, _Chun
 
 
 class ProjectRegistry:
-    """Cache of loaded projects, keyed by project root path."""
+    """Cache of loaded projects, keyed by project root path.
+
+    ``_embedder`` is ``None`` when the daemon is running in "no-settings mode"
+    (started before ``global_settings.yml`` existed). In that state
+    ``get_project`` raises an error pointing the user at ``ccc init``; the
+    daemon still serves handshakes so the client can detect the mtime
+    mismatch once the file is created and trigger a supervisor respawn.
+    """
 
     _projects: dict[str, Project]
-    _embedder: Embedder
+    _embedder: Embedder | None
 
-    def __init__(self, embedder: Embedder) -> None:
+    def __init__(self, embedder: Embedder | None) -> None:
         self._projects = {}
         self._embedder = embedder
 
     async def get_project(self, project_root: str) -> Project:
         """Get or create a Project for the given root. Lazy initialization."""
+        if self._embedder is None:
+            raise RuntimeError(
+                "Daemon has no global settings loaded. Run `ccc init` to set up cocoindex-code."
+            )
         if project_root not in self._projects:
             root = Path(project_root)
             project_settings = load_project_settings(root)
@@ -260,8 +274,19 @@ async def _handle_doctor(
     )
 
 
-async def _check_model(embedder: Embedder) -> DoctorCheckResult:
-    """Test the embedding model by embedding a short string."""
+async def _check_model(embedder: Embedder | None) -> DoctorCheckResult:
+    """Test the embedding model by embedding a short string.
+
+    Returns a failed result when the embedder is ``None`` (daemon running in
+    no-settings mode).
+    """
+    if embedder is None:
+        return DoctorCheckResult(
+            name="Model Check",
+            ok=False,
+            details=[],
+            errors=["Daemon has no global settings loaded. Run `ccc init` to set up."],
+        )
     result = await check_embedding(embedder)
     if result.error is None:
         return DoctorCheckResult(
@@ -340,7 +365,7 @@ async def _check_index_status(project_root_str: str) -> DoctorCheckResult:
 
     project_root = Path(project_root_str)
     db_path = target_sqlite_db_path(project_root)
-    details = [f"Index: {db_path}"]
+    details = [f"Index: {format_path_for_display(db_path)}"]
 
     if not db_path.exists():
         details.append("Index not created yet.")
@@ -445,6 +470,10 @@ async def _dispatch(
                     DbPathMappingEntry(source=str(m.source), target=str(m.target))
                     for m in get_db_path_mappings()
                 ],
+                host_path_mappings=[
+                    DbPathMappingEntry(source=str(m.source), target=str(m.target))
+                    for m in get_host_path_mappings()
+                ],
             )
 
         if isinstance(req, DoctorRequest):
@@ -468,19 +497,24 @@ def run_daemon() -> None:
     to serve connections, and performs cleanup when shutdown is requested via
     ``StopRequest`` or a signal (SIGTERM / SIGINT).
     """
-    daemon_dir().mkdir(parents=True, exist_ok=True)
-
-    # Load user settings and record mtime for staleness detection
-    user_settings = load_user_settings()
-    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
-
-    # Create embedder
-    embedder = create_embedder(user_settings.embedding)
+    daemon_runtime_dir().mkdir(parents=True, exist_ok=True)
+
+    # No-settings mode: start even when global_settings.yml is missing so the
+    # client can complete its handshake, detect the mtime mismatch once
+    # `ccc init` writes the file, and trigger a supervisor respawn. The
+    # alternative (auto-creating defaults) would skip the interactive
+    # provider/model picker in `ccc init`.
+    settings_mtime_us = global_settings_mtime_us()  # None when file is missing
+    embedder: Embedder | None
+    if user_settings_path().is_file():
+        user_settings = load_user_settings()
+        settings_env_keys = list(user_settings.envs.keys())
+        for key, value in user_settings.envs.items():
+            os.environ[key] = value
+        embedder = create_embedder(user_settings.embedding)
+    else:
+        settings_env_keys = []
+        embedder = None
 
     # Write PID file
     pid_path = daemon_pid_path()

{cocoindex_code-0.2.23 → cocoindex_code-0.2.24}/src/cocoindex_code/protocol.py

@@ -167,6 +167,7 @@ class DaemonEnvResponse(_msgspec.Struct, tag="daemon_env"):
     env_names: list[str]
     settings_env_names: list[str]
     db_path_mappings: list[DbPathMappingEntry] = []
+    host_path_mappings: list[DbPathMappingEntry] = []
 
 
 class ErrorResponse(_msgspec.Struct, tag="error"):

{cocoindex_code-0.2.23 → cocoindex_code-0.2.24}/src/cocoindex_code/settings.py

@@ -151,51 +151,68 @@ _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"
+_ENV_HOST_PATH_MAPPING = "COCOINDEX_CODE_HOST_PATH_MAPPING"
 
 
 @dataclass
-class DbPathMapping:
+class PathMapping:
     source: Path
     target: Path
 
 
-_db_path_mapping: list[DbPathMapping] | None = None
+def _parse_path_mapping(env_var: str) -> list[PathMapping]:
+    """Parse a ``source=target[,source=target...]`` env var.
 
-
-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.
+    Both source and target must be absolute paths. Returns an empty list when
+    the env var is unset or blank. Raises ``ValueError`` on malformed entries.
     """
-    raw = os.environ.get(_ENV_DB_PATH_MAPPING, "")
+    raw = os.environ.get(env_var, "")
     if not raw.strip():
         return []
 
-    mappings: list[DbPathMapping] = []
+    mappings: list[PathMapping] = []
     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'"
-            )
+            raise ValueError(f"{env_var}: 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}"
-            )
+            raise ValueError(f"{env_var}: 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()))
+            raise ValueError(f"{env_var}: target path must be absolute, got {target!r}")
+        mappings.append(PathMapping(source=source.resolve(), target=target.resolve()))
     return mappings
 
 
+def _apply_mapping(mappings: list[PathMapping], path: str | Path, reverse: bool = False) -> str:
+    """Rewrite ``path`` through ``mappings``. First prefix match wins.
+
+    ``reverse=False``: rewrites source-prefix → target-prefix (forward).
+    ``reverse=True``: rewrites target-prefix → source-prefix (reverse).
+
+    Relative paths and absolute paths with no matching prefix are returned
+    unchanged (as ``str``).
+    """
+    p = Path(path)
+    if not p.is_absolute():
+        return str(path)
+    resolved = p.resolve()
+    for m in mappings:
+        src, dst = (m.target, m.source) if reverse else (m.source, m.target)
+        if resolved == src or resolved.is_relative_to(src):
+            rel = resolved.relative_to(src)
+            return str(dst / rel) if str(rel) != "." else str(dst)
+    return str(path)
+
+
+_db_path_mapping: list[PathMapping] | None = None
+_host_path_mapping: list[PathMapping] | None = None
+
+
 def resolve_db_dir(project_root: Path) -> Path:
     """Return the directory for database files given a project root.
 
@@ -204,7 +221,7 @@ def resolve_db_dir(project_root: Path) -> Path:
     """
     global _db_path_mapping  # noqa: PLW0603
     if _db_path_mapping is None:
-        _db_path_mapping = _parse_db_path_mapping()
+        _db_path_mapping = _parse_path_mapping(_ENV_DB_PATH_MAPPING)
 
     resolved = project_root.resolve()
     for mapping in _db_path_mapping:
@@ -214,20 +231,52 @@ def resolve_db_dir(project_root: Path) -> Path:
     return project_root / _SETTINGS_DIR_NAME
 
 
-def get_db_path_mappings() -> list[DbPathMapping]:
+def get_db_path_mappings() -> list[PathMapping]:
     """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()
+        _db_path_mapping = _parse_path_mapping(_ENV_DB_PATH_MAPPING)
     return list(_db_path_mapping)
 
 
+def get_host_path_mappings() -> list[PathMapping]:
+    """Return the parsed host path mappings from ``COCOINDEX_CODE_HOST_PATH_MAPPING``."""
+    global _host_path_mapping  # noqa: PLW0603
+    if _host_path_mapping is None:
+        _host_path_mapping = _parse_path_mapping(_ENV_HOST_PATH_MAPPING)
+    return list(_host_path_mapping)
+
+
+def format_path_for_display(p: str | Path) -> str:
+    """Translate a container path to its host equivalent for user-facing output.
+
+    No-op when ``COCOINDEX_CODE_HOST_PATH_MAPPING`` is unset or when ``p`` is a
+    relative path / unmatched absolute path.
+    """
+    return _apply_mapping(get_host_path_mappings(), p, reverse=False)
+
+
+def normalize_input_path(p: str | Path) -> str:
+    """Translate a host path back to its container form before using it internally.
+
+    Inverse of :func:`format_path_for_display`. No-op when the env var is unset
+    or when ``p`` is relative / unmatched.
+    """
+    return _apply_mapping(get_host_path_mappings(), p, reverse=True)
+
+
 def _reset_db_path_mapping_cache() -> None:
     """Reset the cached mapping (for tests)."""
     global _db_path_mapping  # noqa: PLW0603
     _db_path_mapping = None
 
 
+def _reset_host_path_mapping_cache() -> None:
+    """Reset the cached mapping (for tests)."""
+    global _host_path_mapping  # noqa: PLW0603
+    _host_path_mapping = None
+
+
 _TARGET_SQLITE_DB_NAME = "target_sqlite.db"
 _COCOINDEX_DB_NAME = "cocoindex.db"
 
@@ -295,22 +344,27 @@ def find_legacy_project_root(start: Path) -> Path | None:
 
 
 def find_parent_with_marker(start: Path) -> Path | None:
-    """Walk up from *start* looking for ``.cocoindex_code/`` or ``.git/``.
+    """Walk up from *start* looking for an initialized project or a git repo.
+
+    Match criteria: ``.cocoindex_code/settings.yml`` (a real project marker —
+    distinct from a workspace-root ``.cocoindex_code/global_settings.yml``
+    which should not trigger this check) or ``.git/``.
 
-    Returns the first directory found, or ``None``.
-    Does not consider the home directory or above, to avoid false positives
-    on CI runners where ~/.git may exist.
+    Returns the first directory found, or ``None``. Does not consider the home
+    directory or above, to avoid false positives on CI runners where ~/.git
+    may exist.
     """
     home = Path.home().resolve()
     current = start.resolve()
     while True:
-        # Stop before reaching the home directory (home itself is not a project root)
         if current == home:
             return None
         parent = current.parent
         if parent == current:
             return None
-        if (current / _SETTINGS_DIR_NAME).is_dir() or (current / ".git").is_dir():
+        if (current / _SETTINGS_DIR_NAME / _SETTINGS_FILE_NAME).is_file() or (
+            current / ".git"
+        ).is_dir():
             return current
         current = parent
 

cocoindex_code-0.2.23/src/cocoindex_code/_daemon_paths.py

@@ -1,44 +0,0 @@
-"""Daemon filesystem paths and connection helpers.
-
-Lightweight module with no cocoindex dependency so that the CLI client
-can import these without pulling in the full daemon stack.
-"""
-
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-from .settings import user_settings_dir
-
-
-def daemon_dir() -> Path:
-    """Return the daemon directory (``~/.cocoindex_code/``)."""
-    return user_settings_dir()
-
-
-def connection_family() -> str:
-    """Return the multiprocessing connection family for this platform."""
-    return "AF_PIPE" if sys.platform == "win32" else "AF_UNIX"
-
-
-def daemon_socket_path() -> str:
-    """Return the daemon socket/pipe address."""
-    if sys.platform == "win32":
-        import hashlib
-
-        # Hash the daemon dir so COCOINDEX_CODE_DIR overrides create unique pipe names,
-        # preventing conflicts between different daemon instances (tests, users, etc.)
-        dir_hash = hashlib.md5(str(daemon_dir()).encode()).hexdigest()[:12]
-        return rf"\\.\pipe\cocoindex_code_{dir_hash}"
-    return str(daemon_dir() / "daemon.sock")
-
-
-def daemon_pid_path() -> Path:
-    """Return the path for the daemon's PID file."""
-    return daemon_dir() / "daemon.pid"
-
-
-def daemon_log_path() -> Path:
-    """Return the path for the daemon's log file."""
-    return daemon_dir() / "daemon.log"