refactor: extract daemon path helpers to avoid CLI importing cocoindex (#130)

* refactor: extract daemon path helpers to avoid CLI importing cocoindex

Move daemon_dir, daemon_socket_path, daemon_pid_path, daemon_log_path,
and connection_family from daemon.py into a new lightweight _daemon_paths.py
module. This prevents the CLI client from transitively importing cocoindex
and its heavy dependencies (numpy, torch, etc.) when it only needs path
utilities.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* ci: mark free-threaded Python CI jobs as continue-on-error

tokenizers lacks pre-built wheels for cp314t (free-threaded ABI),
so uv falls back to compiling from Rust source. This source build
is fragile across macOS runner image updates and broke after the
20260406 image bump. Mark 3.14t jobs as continue-on-error since
free-threaded wheel coverage across the ecosystem is still limited.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: georgeh0

.github/workflows/pre-commit.yml

@@ -9,6 +9,9 @@ on:
 jobs:
   pre-commit:
     runs-on: ${{ matrix.os }}
+    # Free-threaded Python (3.14t) lacks pre-built wheels for tokenizers;
+    # the fallback source build is fragile across macOS toolchain updates.
+    continue-on-error: ${{ matrix.python-version == '3.14t' }}
     strategy:
       fail-fast: false
       matrix:

src/cocoindex_code/_daemon_paths.py

@@ -0,0 +1,44 @@
+"""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"

src/cocoindex_code/cli.py

@@ -599,7 +599,7 @@ def doctor() -> None:
 
     # --- 8. Log files ---
     _print_section("Log Files")
-    from .daemon import daemon_log_path as _daemon_log_path
+    from ._daemon_paths import daemon_log_path as _daemon_log_path
 
     _typer.echo(f"  Daemon logs: {_daemon_log_path()}")
     _typer.echo("  Check logs above for further troubleshooting.")
@@ -675,8 +675,8 @@ def daemon_restart() -> None:
 @daemon_app.command("stop")
 def daemon_stop() -> None:
     """Stop the daemon."""
+    from ._daemon_paths import daemon_pid_path
     from .client import is_daemon_running, stop_daemon
-    from .daemon import daemon_pid_path
 
     pid_path = daemon_pid_path()
     if not pid_path.exists() and not is_daemon_running():

src/cocoindex_code/client.py

@@ -17,8 +17,14 @@
 from multiprocessing.connection import Client, Connection
 from pathlib import Path
 
+from ._daemon_paths import (
+    connection_family,
+    daemon_dir,
+    daemon_log_path,
+    daemon_pid_path,
+    daemon_socket_path,
+)
 from ._version import __version__
-from .daemon import _connection_family, daemon_log_path, daemon_pid_path, daemon_socket_path
 from .protocol import (
     DaemonEnvRequest,
     DaemonEnvResponse,
@@ -105,7 +111,7 @@ def _raw_connect_and_handshake() -> Connection:
     if sys.platform != "win32" and not os.path.exists(sock):
         raise ConnectionRefusedError(f"Daemon socket not found: {sock}")
     try:
-        conn = Client(sock, family=_connection_family())
+        conn = Client(sock, family=connection_family())
     except (ConnectionRefusedError, FileNotFoundError, OSError) as e:
         raise ConnectionRefusedError(f"Cannot connect to daemon: {e}") from e
 
@@ -329,7 +335,7 @@ def is_daemon_running() -> bool:
     """Check if the daemon is running."""
     if sys.platform == "win32":
         try:
-            conn = Client(daemon_socket_path(), family=_connection_family())
+            conn = Client(daemon_socket_path(), family=connection_family())
             conn.close()
             return True
         except (ConnectionRefusedError, OSError):
@@ -343,8 +349,6 @@ 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.
     """
-    from .daemon import daemon_dir, daemon_log_path
-
     daemon_dir().mkdir(parents=True, exist_ok=True)
     log_path = daemon_log_path()
 
@@ -518,7 +522,7 @@ def _wait_for_daemon(
 
         if sys.platform == "win32":
             try:
-                conn = Client(sock_path, family=_connection_family())
+                conn = Client(sock_path, family=connection_family())
                 conn.close()
                 return
             except (ConnectionRefusedError, OSError):

src/cocoindex_code/daemon.py

@@ -15,6 +15,13 @@
 from pathlib import Path
 from typing import Any
 
+from ._daemon_paths import (
+    connection_family,
+    daemon_dir,
+    daemon_log_path,
+    daemon_pid_path,
+    daemon_socket_path,
+)
 from ._version import __version__
 from .chunking import ChunkerFn as _ChunkerFn
 from .project import Project
@@ -53,7 +60,6 @@
     load_project_settings,
     load_user_settings,
     target_sqlite_db_path,
-    user_settings_dir,
 )
 from .shared import Embedder, create_embedder
 
@@ -79,43 +85,6 @@ def _resolve_chunker_registry(mappings: list[ChunkerMapping]) -> dict[str, _Chun
     return registry
 
 
-# ---------------------------------------------------------------------------
-# Daemon paths
-# ---------------------------------------------------------------------------
-
-
-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"
-
-
 # ---------------------------------------------------------------------------
 # Project Registry
 # ---------------------------------------------------------------------------
@@ -540,7 +509,7 @@ def run_daemon() -> None:
         except Exception:
             pass
 
-    listener = Listener(sock_path, family=_connection_family())
+    listener = Listener(sock_path, family=connection_family())
     logger.info("Listening on %s", sock_path)
 
     loop = asyncio.new_event_loop()

tests/test_daemon.py

@@ -16,8 +16,8 @@
 
 import pytest
 
+from cocoindex_code._daemon_paths import connection_family
 from cocoindex_code._version import __version__
-from cocoindex_code.daemon import _connection_family
 from cocoindex_code.protocol import (
     DaemonStatusRequest,
     HandshakeRequest,
@@ -96,7 +96,7 @@ def daemon_sock() -> Iterator[str]:
 
     # Gracefully shut down the daemon thread so named pipes are released on Windows
     try:
-        conn = Client(sock_path, family=_connection_family())
+        conn = Client(sock_path, family=connection_family())
         conn.send_bytes(encode_request(HandshakeRequest(version=__version__)))
         conn.recv_bytes()
         conn.send_bytes(encode_request(StopRequest()))
@@ -136,7 +136,7 @@ def daemon_project(daemon_sock: str) -> str:
     save_project_settings(project, default_project_settings())
     (project / "main.py").write_text(SAMPLE_MAIN_PY)
 
-    conn = Client(daemon_sock, family=_connection_family())
+    conn = Client(daemon_sock, family=connection_family())
     conn.send_bytes(encode_request(HandshakeRequest(version=__version__)))
     decode_response(conn.recv_bytes())
     conn.send_bytes(encode_request(IndexRequest(project_root=str(project))))
@@ -148,7 +148,7 @@ def daemon_project(daemon_sock: str) -> str:
 
 
 def _connect_and_handshake(sock_path: str) -> tuple[Connection, Response]:
-    conn = Client(sock_path, family=_connection_family())
+    conn = Client(sock_path, family=connection_family())
     conn.send_bytes(encode_request(HandshakeRequest(version=__version__)))
     resp = decode_response(conn.recv_bytes())
     return conn, resp
@@ -162,7 +162,7 @@ def test_daemon_starts_and_accepts_handshake(daemon_sock: str) -> None:
 
 
 def test_daemon_rejects_version_mismatch(daemon_sock: str) -> None:
-    conn = Client(daemon_sock, family=_connection_family())
+    conn = Client(daemon_sock, family=connection_family())
     conn.send_bytes(encode_request(HandshakeRequest(version="0.0.0-fake")))
     resp = decode_response(conn.recv_bytes())
     assert resp.ok is False