libcontext 0.3.0__tar.gz → 0.4.0__tar.gz

{libcontext-0.3.0 → libcontext-0.4.0}/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-03-23
+
+### Added
+
+- **Auto-detect project venv**: libcontext now automatically detects `.venv/` or `venv/` in the current directory and uses it for package discovery. This fixes the core issue where `uv tool install libcontext` could not see packages from project environments.
+- **`--python` CLI option**: explicit override for targeting a specific Python interpreter or venv directory (e.g. `--python /path/to/other/venv`).
+- **`LIBCONTEXT_PYTHON` env var**: configure the MCP server's target environment via environment variable or `--python` argument.
+- **`EnvironmentSetupError` exception**: raised when a target environment cannot be resolved or queried.
+- **Cache namespacing by environment**: packages from different environments get separate cache entries, preventing cross-environment cache collisions.
+
 ## [0.3.0] - 2026-03-23
 
 ### Added
@@ -83,7 +93,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Free-form `extra_context` field for library authors.
 - Python API for programmatic usage (`collect_package`, `render_package`).
 
-[Unreleased]: https://github.com/Syclaw/libcontext/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/Syclaw/libcontext/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/Syclaw/libcontext/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/Syclaw/libcontext/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Syclaw/libcontext/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/Syclaw/libcontext/releases/tag/v0.1.0

{libcontext-0.3.0 → libcontext-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: libcontext
-Version: 0.3.0
+Version: 0.4.0
 Summary: Generate optimized LLM context from Python library APIs — CLI, skill, and MCP server
 Project-URL: Homepage, https://github.com/Syclaw/libcontext
 Project-URL: Repository, https://github.com/Syclaw/libcontext

{libcontext-0.3.0 → libcontext-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "libcontext"
-version = "0.3.0"
+version = "0.4.0"
 description = "Generate optimized LLM context from Python library APIs — CLI, skill, and MCP server"
 readme = "README.md"
 license = "MIT"

{libcontext-0.3.0 → libcontext-0.4.0}/src/libcontext/__init__.py

@@ -27,6 +27,7 @@ from .config import LibcontextConfig
 from .diff import diff_packages
 from .exceptions import (
     ConfigError,
+    EnvironmentSetupError,
     InspectionError,
     LibcontextError,
     PackageNotFoundError,
@@ -69,6 +70,7 @@ __all__ = [
     "ClassInfo",
     "ConfigError",
     "DiffResult",
+    "EnvironmentSetupError",
     "FunctionDiff",
     "FunctionInfo",
     "InspectionError",

libcontext-0.4.0/src/libcontext/_envsetup.py

@@ -0,0 +1,334 @@
+"""Environment setup — resolve and activate a target Python environment.
+
+When libcontext is installed globally (e.g. via ``uv tool install``), it
+runs inside its own isolated venv and cannot see packages from a project's
+``.venv``.  This module auto-detects a project venv in the current working
+directory, or accepts an explicit ``--python`` override, and injects the
+target environment's paths into ``sys.path`` so that :mod:`importlib`
+discovery works against the target environment.
+
+Detection priority:
+1. Explicit ``--python`` argument → use that environment.
+2. ``.venv/`` or ``venv/`` in CWD → use the detected venv.
+3. Neither → use the current process's environment (no injection).
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+import logging
+import subprocess
+import sys
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+
+from .exceptions import EnvironmentSetupError
+
+logger = logging.getLogger(__name__)
+
+_SUBPROCESS_TIMEOUT_SECONDS = 10
+
+
+_VENV_DIR_NAMES = (".venv", "venv")
+
+
+def auto_detect_venv(cwd: Path | None = None) -> Path | None:
+    """Detect a project venv in the current working directory.
+
+    Checks for ``.venv/`` then ``venv/`` in *cwd* (defaults to
+    ``Path.cwd()``).  Only considers directories that contain a
+    recognisable Python interpreter.
+
+    Args:
+        cwd: Directory to search in.  Defaults to the process CWD.
+
+    Returns:
+        Path to the venv directory, or *None* if no venv is found.
+    """
+    if cwd is None:
+        cwd = Path.cwd()
+
+    for name in _VENV_DIR_NAMES:
+        candidate = cwd / name
+        if not candidate.is_dir():
+            continue
+        # Verify it actually contains an interpreter
+        interpreters = [
+            candidate / "Scripts" / "python.exe",
+            candidate / "bin" / "python",
+            candidate / "bin" / "python3",
+        ]
+        if any(exe.is_file() for exe in interpreters):
+            logger.debug("Auto-detected venv at '%s'", candidate)
+            return candidate
+
+    return None
+
+
+def setup_environment(
+    python_arg: str | None = None,
+    *,
+    cwd: Path | None = None,
+) -> str | None:
+    """Set up the target environment for package discovery.
+
+    Implements the detection priority:
+    1. Explicit *python_arg* → inject that environment.
+    2. Auto-detected venv in *cwd* → inject it.
+    3. Neither → no injection (current process environment).
+
+    Args:
+        python_arg: Explicit ``--python`` value, or *None*.
+        cwd: Working directory for auto-detection (defaults to CWD).
+
+    Returns:
+        The env_tag for cache namespacing, or *None* if no injection
+        was performed.
+
+    Raises:
+        EnvironmentSetupError: If an explicit *python_arg* is invalid.
+    """
+    target: str | None = python_arg
+
+    if target is None:
+        detected = auto_detect_venv(cwd)
+        if detected is not None:
+            target = str(detected)
+
+    if target is None:
+        return None
+
+    # Resolve once, reuse for both injection and tag computation
+    python_exe = resolve_python_executable(target)
+    target_paths = get_target_sys_path(python_exe)
+
+    current_set = set(sys.path)
+    new_paths = [p for p in target_paths if p and p not in current_set]
+
+    sys.path[:0] = new_paths
+    importlib.invalidate_caches()
+
+    logger.debug(
+        "Activated environment '%s': injected %d paths",
+        target,
+        len(new_paths),
+    )
+
+    return _env_tag_from_resolved(python_exe)
+
+
+def resolve_python_executable(python_arg: str) -> Path:
+    """Resolve a user-supplied path to a Python executable.
+
+    Accepts either a direct path to a Python interpreter or a venv
+    directory.  When given a directory, probes for the interpreter
+    in the standard locations (``Scripts/python.exe`` on Windows,
+    ``bin/python`` on Unix).
+
+    Args:
+        python_arg: Path to a Python interpreter or venv directory.
+
+    Returns:
+        Resolved absolute path to the Python executable.
+
+    Raises:
+        EnvironmentSetupError: If the path does not exist or no
+            interpreter can be found.
+    """
+    path = Path(python_arg)
+
+    if not path.exists():
+        raise EnvironmentSetupError(
+            python_arg,
+            f"path does not exist: {python_arg}",
+        )
+
+    # Direct path to an executable
+    if path.is_file():
+        return path.resolve()
+
+    # Directory — probe for interpreter
+    if path.is_dir():
+        candidates = [
+            path / "Scripts" / "python.exe",  # Windows venv
+            path / "bin" / "python",  # Unix venv
+            path / "bin" / "python3",  # Unix alternative
+        ]
+        for candidate in candidates:
+            if candidate.is_file():
+                logger.debug(
+                    "Resolved venv directory '%s' to interpreter '%s'",
+                    python_arg,
+                    candidate,
+                )
+                return candidate.resolve()
+
+        raise EnvironmentSetupError(
+            python_arg,
+            f"no Python interpreter found in directory: {python_arg}. "
+            f"Expected Scripts/python.exe (Windows) or bin/python (Unix).",
+        )
+
+    raise EnvironmentSetupError(
+        python_arg,
+        f"path is neither a file nor a directory: {python_arg}",
+    )
+
+
+def get_target_sys_path(python_exe: Path) -> list[str]:
+    """Query a Python interpreter for its ``sys.path``.
+
+    Runs the interpreter in a subprocess with a short timeout to
+    extract the full search path, including ``.pth`` expansions and
+    site-packages.
+
+    Args:
+        python_exe: Absolute path to the target Python executable.
+
+    Returns:
+        List of path strings from the target interpreter's ``sys.path``.
+
+    Raises:
+        EnvironmentSetupError: If the subprocess fails or times out.
+    """
+    script = "import sys, json; print(json.dumps(sys.path))"
+    try:
+        result = subprocess.run(
+            [str(python_exe), "-c", script],
+            capture_output=True,
+            text=True,
+            timeout=_SUBPROCESS_TIMEOUT_SECONDS,
+        )
+    except (FileNotFoundError, OSError) as exc:
+        raise EnvironmentSetupError(
+            str(python_exe),
+            f"cannot execute interpreter: {exc}",
+        ) from exc
+    except subprocess.TimeoutExpired as exc:
+        raise EnvironmentSetupError(
+            str(python_exe),
+            f"interpreter timed out after {_SUBPROCESS_TIMEOUT_SECONDS}s",
+        ) from exc
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip()[:200]
+        raise EnvironmentSetupError(
+            str(python_exe),
+            f"interpreter exited with code {result.returncode}: {stderr}",
+        )
+
+    try:
+        paths = json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        raise EnvironmentSetupError(
+            str(python_exe),
+            f"cannot parse sys.path output: {exc}",
+        ) from exc
+
+    if not isinstance(paths, list):
+        raise EnvironmentSetupError(
+            str(python_exe),
+            "sys.path output is not a list",
+        )
+
+    return [str(p) for p in paths]
+
+
+@contextmanager
+def activate_environment(python_arg: str) -> Generator[Path, None, None]:
+    """Temporarily inject a target environment's paths into the process.
+
+    Resolves the Python executable, queries its ``sys.path``, prepends
+    the target paths to the current ``sys.path``, and invalidates
+    :mod:`importlib` caches so that :func:`importlib.util.find_spec`
+    and :func:`importlib.metadata.distributions` pick up the target
+    environment's packages.
+
+    The original ``sys.path`` is restored on exit.
+
+    Args:
+        python_arg: Path to a Python interpreter or venv directory.
+
+    Yields:
+        The resolved Python executable path.
+
+    Raises:
+        EnvironmentSetupError: If the environment cannot be resolved
+            or queried.
+    """
+    python_exe = resolve_python_executable(python_arg)
+    target_paths = get_target_sys_path(python_exe)
+
+    # Filter to paths that actually exist and aren't already present
+    current_set = set(sys.path)
+    new_paths = [p for p in target_paths if p and p not in current_set]
+
+    saved_path = sys.path.copy()
+    try:
+        # Prepend target paths so they take priority
+        sys.path[:0] = new_paths
+        importlib.invalidate_caches()
+
+        logger.debug(
+            "Activated environment '%s': injected %d paths",
+            python_arg,
+            len(new_paths),
+        )
+        yield python_exe
+    finally:
+        sys.path[:] = saved_path
+        importlib.invalidate_caches()
+        logger.debug("Restored original sys.path")
+
+
+def inject_target_environment(python_arg: str) -> None:
+    """Inject a target environment's paths into the current process.
+
+    Unlike :func:`activate_environment`, this does **not** restore
+    ``sys.path`` afterward.  Suitable for CLI entry points where the
+    process exits after the command completes.
+
+    Args:
+        python_arg: Path to a Python interpreter or venv directory.
+
+    Raises:
+        EnvironmentSetupError: If the environment cannot be resolved
+            or queried.
+    """
+    python_exe = resolve_python_executable(python_arg)
+    target_paths = get_target_sys_path(python_exe)
+
+    current_set = set(sys.path)
+    new_paths = [p for p in target_paths if p and p not in current_set]
+
+    sys.path[:0] = new_paths
+    importlib.invalidate_caches()
+
+    logger.debug(
+        "Injected environment '%s': added %d paths",
+        python_arg,
+        len(new_paths),
+    )
+
+
+def _env_tag_from_resolved(python_exe: Path) -> str:
+    """Compute a short tag from an already-resolved interpreter path."""
+    import hashlib
+
+    digest = hashlib.sha256(str(python_exe).encode()).hexdigest()
+    return digest[:8]
+
+
+def env_tag_for_path(python_arg: str) -> str:
+    """Compute a short tag identifying a target environment for cache keys.
+
+    Args:
+        python_arg: The original ``--python`` argument (before resolution).
+
+    Returns:
+        An 8-character hex string derived from the resolved path.
+    """
+    resolved = resolve_python_executable(python_arg)
+    return _env_tag_from_resolved(resolved)

{libcontext-0.3.0 → libcontext-0.4.0}/src/libcontext/cache.py

@@ -113,6 +113,7 @@ def load(
     package_name: str,
     version: str | None,
     package_path: Path,
+    env_tag: str | None = None,
 ) -> PackageInfo | None:
     """Load a cached PackageInfo if still valid.
 
@@ -120,11 +121,12 @@ def load(
         package_name: Package name.
         version: Current installed version (from metadata).
         package_path: Path to the package source (for mtime check).
+        env_tag: Environment identifier (from ``--python``).
 
     Returns:
         Cached PackageInfo if valid, None on miss or invalidation.
     """
-    cache_file = _get_cache_dir() / _cache_filename(package_name, version)
+    cache_file = _get_cache_dir() / _cache_filename(package_name, version, env_tag)
 
     if not cache_file.is_file():
         logger.debug("Cache miss for %r: file not found", package_name)
@@ -178,6 +180,7 @@ def save(
     package_info: PackageInfo,
     package_path: Path,
     source_stats: _SourceStats | None = None,
+    env_tag: str | None = None,
 ) -> None:
     """Save a PackageInfo to the disk cache.
 
@@ -185,6 +188,7 @@ def save(
         package_info: The collected package data.
         package_path: Path to the package source (for mtime computation).
         source_stats: Pre-computed stats. If None, stats are computed fresh.
+        env_tag: Environment identifier (from ``--python``).
     """
     if source_stats is None:
         source_stats = _compute_source_stats(package_path)
@@ -198,7 +202,9 @@ def save(
     envelope = _serialize_envelope(data)
 
     cache_dir = _get_cache_dir()
-    cache_file = cache_dir / _cache_filename(package_info.name, package_info.version)
+    cache_file = cache_dir / _cache_filename(
+        package_info.name, package_info.version, env_tag
+    )
 
     try:
         cache_file.write_text(
@@ -252,14 +258,25 @@ def clear_all() -> int:
     return count
 
 
-def _cache_filename(package_name: str, version: str | None) -> str:
+def _cache_filename(
+    package_name: str,
+    version: str | None,
+    env_tag: str | None = None,
+) -> str:
     """Build the cache filename for a package.
 
     Sanitises both components to prevent path traversal via crafted
     package names (e.g. ``../../etc/cron.d/evil``).
+
+    When *env_tag* is provided (from ``--python``), it is appended to
+    the filename so that packages from different environments get
+    separate cache entries.
     """
     from ._security import sanitize_filename
 
     safe_name = sanitize_filename(package_name)
     safe_version = sanitize_filename(version) if version else "unknown"
+    if env_tag:
+        safe_tag = sanitize_filename(env_tag)
+        return f"{safe_name}-{safe_version}-{safe_tag}.json"
     return f"{safe_name}-{safe_version}.json"

{libcontext-0.3.0 → libcontext-0.4.0}/src/libcontext/cli.py

@@ -35,7 +35,12 @@ from . import cache as _cache
 from .collector import collect_package
 from .config import LibcontextConfig, read_config_from_pyproject
 from .diff import diff_packages
-from .exceptions import ConfigError, InspectionError, PackageNotFoundError
+from .exceptions import (
+    ConfigError,
+    EnvironmentSetupError,
+    InspectionError,
+    PackageNotFoundError,
+)
 from .models import PackageInfo, _deserialize_envelope, _serialize_envelope
 from .renderer import (
     inject_into_file,
@@ -165,6 +170,17 @@ def _write_stdout(text: str) -> None:
     default=False,
     help="Force fresh collection, bypass disk cache.",
 )
+@click.option(
+    "--python",
+    "python_env",
+    type=str,
+    default=None,
+    help=(
+        "Override environment for package discovery.  Accepts a venv "
+        "directory or Python interpreter path.  By default, libcontext "
+        "auto-detects .venv/ or venv/ in the current directory."
+    ),
+)
 @click.option(
     "-v",
     "--verbose",
@@ -185,6 +201,7 @@ def inspect(
     max_readme_lines: int | None,
     config_path: Path | None,
     no_cache: bool,
+    python_env: str | None,
     quiet: bool,
     verbose: bool,
 ) -> None:
@@ -225,6 +242,15 @@ def inspect(
     # --overview and --search don't need README
     skip_readme = no_readme or overview or search_query is not None
 
+    # Resolve target environment (--python override, auto-detected venv, or current)
+    from ._envsetup import setup_environment
+
+    try:
+        _env_tag = setup_environment(python_env)
+    except EnvironmentSetupError as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
     all_blocks: list[tuple[str, str]] = []
 
     for pkg_name in packages:
@@ -238,6 +264,7 @@ def inspect(
                 include_readme=not skip_readme,
                 config_override=config,
                 no_cache=no_cache,
+                env_tag=_env_tag,
             )
         except PackageNotFoundError as exc:
             click.echo(f"Error: {exc}", err=True)

{libcontext-0.3.0 → libcontext-0.4.0}/src/libcontext/collector.py

@@ -620,6 +620,7 @@ def collect_package(
     include_readme: bool = True,
     config_override: LibcontextConfig | None = None,
     no_cache: bool = False,
+    env_tag: str | None = None,
 ) -> PackageInfo:
     """Collect complete API information for a Python package.
 
@@ -632,6 +633,8 @@ def collect_package(
         include_readme: Attach the package README to the result.
         config_override: Explicit config; skips automatic discovery.
         no_cache: Skip the disk cache (force fresh AST collection).
+        env_tag: Environment identifier for cache namespacing (from
+            ``--python``).
 
     Returns:
         :class:`~libcontext.models.PackageInfo` with all collected data.
@@ -695,7 +698,7 @@ def collect_package(
     source_stats: _cache._SourceStats | None = None
 
     if use_cache:
-        cached = _cache.load(pkg_name, metadata.get("version"), pkg_path)
+        cached = _cache.load(pkg_name, metadata.get("version"), pkg_path, env_tag)
         if cached is not None:
             if include_readme:
                 cached.readme = _find_readme(pkg_name, pkg_path)
@@ -722,6 +725,6 @@ def collect_package(
 
     # --- Cache save ----------------------------------------------------
     if use_cache:
-        _cache.save(pkg_info, pkg_path, source_stats=source_stats)
+        _cache.save(pkg_info, pkg_path, source_stats=source_stats, env_tag=env_tag)
 
     return pkg_info

{libcontext-0.3.0 → libcontext-0.4.0}/src/libcontext/exceptions.py

@@ -52,6 +52,18 @@ class ConfigError(LibcontextError):
         super().__init__(detail)
 
 
+class EnvironmentSetupError(LibcontextError):
+    """Raised when a target Python environment cannot be resolved or queried.
+
+    Attributes:
+        python_path: The path that was supplied by the user.
+    """
+
+    def __init__(self, python_path: str, reason: str) -> None:
+        self.python_path = python_path
+        super().__init__(f"Cannot use environment '{python_path}': {reason}")
+
+
 class InspectionError(LibcontextError):
     """Raised when a source file cannot be parsed or read.
 

{libcontext-0.3.0 → libcontext-0.4.0}/src/libcontext/mcp_server.py

@@ -59,6 +59,9 @@ mcp = FastMCP(
 
 _CACHE_SIZE = 32
 
+# Set by main() at startup; used by _collect_cached for cache namespacing.
+_active_env_tag: str | None = None
+
 
 @lru_cache(maxsize=_CACHE_SIZE)
 def _collect_cached(package_name: str, include_private: bool = False) -> PackageInfo:
@@ -67,6 +70,7 @@ def _collect_cached(package_name: str, include_private: bool = False) -> Package
         package_name,
         include_private=include_private,
         include_readme=False,
+        env_tag=_active_env_tag,
     )
 
 
@@ -262,7 +266,31 @@ def refresh_cache() -> str:
 
 
 def main() -> None:
-    """Run the libcontext MCP server (stdio transport)."""
+    """Run the libcontext MCP server (stdio transport).
+
+    Environment resolution (in priority order):
+
+    1. ``--python <path>`` CLI argument → use that environment.
+    2. ``LIBCONTEXT_PYTHON`` env var → use that environment.
+    3. Auto-detect ``.venv/`` or ``venv/`` in CWD → use the detected venv.
+    4. None of the above → use the current process's environment.
+    """
+    import os
+    import sys as _sys
+
+    python_env = None
+    args = _sys.argv[1:]
+    if args and args[0] == "--python" and len(args) >= 2:
+        python_env = args[1]
+    elif os.environ.get("LIBCONTEXT_PYTHON"):
+        python_env = os.environ["LIBCONTEXT_PYTHON"]
+
+    global _active_env_tag
+
+    from ._envsetup import setup_environment
+
+    _active_env_tag = setup_environment(python_env)
+
     mcp.run()
 
 

libcontext-0.4.0/tests/test_envsetup.py

@@ -0,0 +1,276 @@
+"""Tests for the _envsetup module."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+from libcontext._envsetup import (
+    activate_environment,
+    auto_detect_venv,
+    env_tag_for_path,
+    get_target_sys_path,
+    inject_target_environment,
+    resolve_python_executable,
+    setup_environment,
+)
+from libcontext.exceptions import EnvironmentSetupError
+
+# ---------------------------------------------------------------------------
+# resolve_python_executable
+# ---------------------------------------------------------------------------
+
+
+def test_resolve_direct_interpreter():
+    """Passing the current interpreter returns its resolved path."""
+    result = resolve_python_executable(sys.executable)
+    assert result == Path(sys.executable).resolve()
+
+
+def test_resolve_venv_directory(tmp_path):
+    """Passing a venv-like directory finds the interpreter."""
+    if sys.platform == "win32":
+        scripts = tmp_path / "Scripts"
+        scripts.mkdir()
+        exe = scripts / "python.exe"
+    else:
+        bin_dir = tmp_path / "bin"
+        bin_dir.mkdir()
+        exe = bin_dir / "python"
+
+    exe.write_text("fake", encoding="utf-8")
+    result = resolve_python_executable(str(tmp_path))
+    assert result == exe.resolve()
+
+
+def test_resolve_nonexistent_raises():
+    """A nonexistent path raises EnvironmentSetupError."""
+    with pytest.raises(EnvironmentSetupError, match="does not exist"):
+        resolve_python_executable("/no/such/path/python")
+
+
+def test_resolve_empty_directory_raises(tmp_path):
+    """A directory without a Python interpreter raises."""
+    with pytest.raises(EnvironmentSetupError, match="no Python interpreter"):
+        resolve_python_executable(str(tmp_path))
+
+
+# ---------------------------------------------------------------------------
+# get_target_sys_path
+# ---------------------------------------------------------------------------
+
+
+def test_get_target_sys_path_current_interpreter():
+    """Querying the current interpreter returns a non-empty path list."""
+    paths = get_target_sys_path(Path(sys.executable))
+    assert isinstance(paths, list)
+    assert len(paths) > 0
+    assert all(isinstance(p, str) for p in paths)
+
+
+def test_get_target_sys_path_bad_executable(tmp_path):
+    """A non-Python executable raises EnvironmentSetupError."""
+    fake = tmp_path / "not_python"
+    fake.write_text("not a python interpreter", encoding="utf-8")
+    if sys.platform != "win32":
+        fake.chmod(0o755)
+
+    with pytest.raises(EnvironmentSetupError):
+        get_target_sys_path(fake)
+
+
+# ---------------------------------------------------------------------------
+# inject_target_environment
+# ---------------------------------------------------------------------------
+
+
+def test_inject_target_environment_adds_paths():
+    """Injecting the current interpreter adds its paths to sys.path."""
+    original_len = len(sys.path)
+    # Inject the current interpreter (should be mostly a no-op since
+    # paths already overlap, but validates the mechanics)
+    inject_target_environment(sys.executable)
+    assert len(sys.path) >= original_len
+
+
+# ---------------------------------------------------------------------------
+# activate_environment (context manager)
+# ---------------------------------------------------------------------------
+
+
+def test_activate_environment_restores_path():
+    """sys.path is restored after the context manager exits."""
+    saved = sys.path.copy()
+    with activate_environment(sys.executable):
+        pass
+    assert sys.path == saved
+
+
+def test_activate_environment_restores_on_exception():
+    """sys.path is restored even if an exception occurs."""
+    saved = sys.path.copy()
+    with pytest.raises(RuntimeError), activate_environment(sys.executable):
+        raise RuntimeError("boom")
+    assert sys.path == saved
+
+
+def test_activate_environment_bad_path():
+    """EnvironmentSetupError propagates from the context manager."""
+    with pytest.raises(EnvironmentSetupError), activate_environment("/no/such/env"):
+        pass
+
+
+# ---------------------------------------------------------------------------
+# env_tag_for_path
+# ---------------------------------------------------------------------------
+
+
+def test_env_tag_for_path_returns_hex_string():
+    """env_tag returns an 8-char hex string."""
+    tag = env_tag_for_path(sys.executable)
+    assert len(tag) == 8
+    int(tag, 16)  # validates hex
+
+
+def test_env_tag_deterministic():
+    """Same input produces the same tag."""
+    tag1 = env_tag_for_path(sys.executable)
+    tag2 = env_tag_for_path(sys.executable)
+    assert tag1 == tag2
+
+
+# ---------------------------------------------------------------------------
+# Cache filename with env_tag
+# ---------------------------------------------------------------------------
+
+
+def test_cache_filename_with_env_tag():
+    """Cache filename includes env_tag when provided."""
+    from libcontext.cache import _cache_filename
+
+    without = _cache_filename("requests", "2.31.0")
+    with_tag = _cache_filename("requests", "2.31.0", env_tag="abcd1234")
+    assert "abcd1234" in with_tag
+    assert "abcd1234" not in without
+    assert with_tag != without
+
+
+# ---------------------------------------------------------------------------
+# auto_detect_venv
+# ---------------------------------------------------------------------------
+
+
+def _make_fake_venv(parent: Path) -> Path:
+    """Create a fake venv directory with a recognisable interpreter."""
+    venv = parent / ".venv"
+    venv.mkdir()
+    if sys.platform == "win32":
+        scripts = venv / "Scripts"
+        scripts.mkdir()
+        (scripts / "python.exe").write_text("fake", encoding="utf-8")
+    else:
+        bin_dir = venv / "bin"
+        bin_dir.mkdir()
+        (bin_dir / "python").write_text("fake", encoding="utf-8")
+    return venv
+
+
+def test_auto_detect_venv_finds_dotvenv(tmp_path):
+    """Detects .venv/ in the given directory."""
+    _make_fake_venv(tmp_path)
+    result = auto_detect_venv(tmp_path)
+    assert result is not None
+    assert result.name == ".venv"
+
+
+def test_auto_detect_venv_finds_venv(tmp_path):
+    """Detects venv/ when .venv/ is absent."""
+    venv = tmp_path / "venv"
+    venv.mkdir()
+    if sys.platform == "win32":
+        scripts = venv / "Scripts"
+        scripts.mkdir()
+        (scripts / "python.exe").write_text("fake", encoding="utf-8")
+    else:
+        bin_dir = venv / "bin"
+        bin_dir.mkdir()
+        (bin_dir / "python").write_text("fake", encoding="utf-8")
+
+    result = auto_detect_venv(tmp_path)
+    assert result is not None
+    assert result.name == "venv"
+
+
+def test_auto_detect_venv_prefers_dotvenv(tmp_path):
+    """.venv/ takes priority over venv/."""
+    _make_fake_venv(tmp_path)
+    venv = tmp_path / "venv"
+    venv.mkdir()
+    if sys.platform == "win32":
+        (venv / "Scripts").mkdir()
+        (venv / "Scripts" / "python.exe").write_text("fake", encoding="utf-8")
+    else:
+        (venv / "bin").mkdir()
+        (venv / "bin" / "python").write_text("fake", encoding="utf-8")
+
+    result = auto_detect_venv(tmp_path)
+    assert result is not None
+    assert result.name == ".venv"
+
+
+def test_auto_detect_venv_returns_none_when_absent(tmp_path):
+    """Returns None when no venv directory exists."""
+    assert auto_detect_venv(tmp_path) is None
+
+
+def test_auto_detect_venv_ignores_dir_without_interpreter(tmp_path):
+    """A .venv/ directory without an interpreter is ignored."""
+    (tmp_path / ".venv").mkdir()
+    assert auto_detect_venv(tmp_path) is None
+
+
+# ---------------------------------------------------------------------------
+# setup_environment
+# ---------------------------------------------------------------------------
+
+
+def test_setup_environment_explicit_python():
+    """Explicit --python takes effect and returns an env_tag."""
+    tag = setup_environment(sys.executable)
+    assert tag is not None
+    assert len(tag) == 8
+
+
+def test_setup_environment_no_venv_returns_none(tmp_path):
+    """No venv, no --python → returns None (no injection)."""
+    tag = setup_environment(None, cwd=tmp_path)
+    assert tag is None
+
+
+def test_setup_environment_auto_detects(tmp_path, monkeypatch):
+    """Auto-detects .venv/ and returns an env_tag when using real interpreter."""
+    # Point the fake venv at the real interpreter so subprocess works
+    venv = tmp_path / ".venv"
+    venv.mkdir()
+    real_exe = Path(sys.executable)
+    if sys.platform == "win32":
+        scripts = venv / "Scripts"
+        scripts.mkdir()
+        target = scripts / "python.exe"
+    else:
+        bin_dir = venv / "bin"
+        bin_dir.mkdir()
+        target = bin_dir / "python"
+
+    # Create a symlink (or copy) so the interpreter actually works
+    try:
+        target.symlink_to(real_exe)
+    except OSError:
+        # Symlinks may require privileges on Windows; skip test
+        pytest.skip("Cannot create symlink to Python interpreter")
+
+    tag = setup_environment(None, cwd=tmp_path)
+    assert tag is not None
+    assert len(tag) == 8