libcontext 0.7.1__tar.gz → 0.7.4__tar.gz

{libcontext-0.7.1 → libcontext-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: libcontext
-Version: 0.7.1
+Version: 0.7.4
 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.7.1 → libcontext-0.7.4}/pyproject.toml

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

{libcontext-0.7.1 → libcontext-0.7.4}/src/libcontext/_envsetup.py

@@ -1,11 +1,12 @@
-"""Environment setup — resolve and activate a target Python environment.
+"""Environment setup — resolve 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.
+directory, or accepts an explicit ``--python`` override, and resolves the
+target interpreter.  Package discovery is then delegated to the target
+interpreter via subprocess (see :func:`query_target_package`), keeping the
+tool process free from cross-version import contamination.
 
 Detection priority:
 1. Explicit ``--python`` argument → use that environment.
@@ -15,19 +16,15 @@ Detection priority:
 5. ``.venv/`` or ``venv/`` in CWD → use the detected venv.
 6. ``uv`` fallback: if CWD has ``pyproject.toml``, query ``uv`` for the
    project interpreter.
-7. Neither → use the current process's environment (no injection).
+7. Neither → use the current process's environment (no delegation).
 """
 
 from __future__ import annotations
 
-import importlib
 import json
 import logging
 import os
 import subprocess
-import sys
-from collections.abc import Generator
-from contextlib import contextmanager
 from pathlib import Path
 
 from .exceptions import EnvironmentSetupError
@@ -47,6 +44,54 @@ _INTERPRETER_CANDIDATES = (
 )
 
 
+# Script executed in the *target* interpreter to discover a package.
+# Accepts the package name as sys.argv[1].  Returns a JSON object with
+# path, version, summary, and installed package names for suggestions.
+_PACKAGE_DISCOVERY_SCRIPT = """\
+import importlib.metadata, importlib.util, json, sys
+from pathlib import Path
+
+name = sys.argv[1]
+result = {"path": None, "version": None, "summary": None, "installed": []}
+
+# Locate the package source via find_spec
+try:
+    spec = importlib.util.find_spec(name)
+except (ModuleNotFoundError, ValueError, AttributeError):
+    spec = None
+
+if spec is not None:
+    if spec.origin and spec.origin != "frozen":
+        origin = Path(spec.origin)
+        result["path"] = str(origin.parent if origin.name == "__init__.py" else origin)
+    elif spec.submodule_search_locations:
+        locs = list(spec.submodule_search_locations)
+        if locs:
+            result["path"] = locs[0]
+
+# Retrieve metadata (version + summary)
+try:
+    meta = importlib.metadata.metadata(name)
+    result["version"] = meta.get("Version")
+    result["summary"] = meta.get("Summary")
+except importlib.metadata.PackageNotFoundError:
+    pass
+
+# Collect installed package names for typo suggestions
+installed = set()
+for dist in importlib.metadata.distributions():
+    dn = dist.metadata.get("Name")
+    if dn:
+        installed.add(dn)
+        norm = dn.replace("-", "_").lower()
+        if norm != dn:
+            installed.add(norm)
+result["installed"] = sorted(installed)
+
+print(json.dumps(result))
+"""
+
+
 def _has_python_interpreter(venv_dir: Path) -> bool:
     """Check whether a directory contains a recognisable Python interpreter."""
     return any((venv_dir / rel).is_file() for rel in _INTERPRETER_CANDIDATES)
@@ -160,21 +205,27 @@ def setup_environment(
     python_arg: str | None = None,
     *,
     cwd: Path | None = None,
-) -> str | None:
-    """Set up the target environment for package discovery.
+) -> tuple[str | None, Path | None]:
+    """Resolve 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).
+    1. Explicit *python_arg* → use that environment.
+    2. Auto-detected venv in *cwd* → use it.
+    3. Neither → use the current process environment.
+
+    Returns the resolved interpreter path so that callers can delegate
+    package discovery to the target interpreter via subprocess, avoiding
+    cross-version ``importlib`` contamination when the tool and target
+    run different Python versions.
 
     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.
+        A ``(env_tag, target_python)`` tuple.  Both are *None* when no
+        external environment was detected (i.e. the current process
+        environment is used).
 
     Raises:
         EnvironmentSetupError: If an explicit *python_arg* is invalid.
@@ -187,122 +238,44 @@ def setup_environment(
             target = str(detected)
 
     if target is None:
-        return None
+        return None, 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",
+        "Resolved target environment '%s' → '%s'",
         target,
-        len(new_paths),
+        python_exe,
     )
 
-    return _env_tag_from_resolved(python_exe)
+    return _env_tag_from_resolved(python_exe), python_exe
 
 
-def resolve_python_executable(python_arg: str) -> Path:
-    """Resolve a user-supplied path to a Python executable.
+def query_target_package(
+    python_exe: Path,
+    package_name: str,
+) -> dict[str, object]:
+    """Discover a package by running the target interpreter.
 
-    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():
-        for candidate in (path / rel for rel in _INTERPRETER_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 non-stdlib ``sys.path`` entries.
-
-    Runs the interpreter in a subprocess with a short timeout to
-    extract site-packages and user-added paths.  Stdlib paths are
-    excluded to prevent cross-version import contamination when the
-    tool interpreter differs from the target (e.g. tool on 3.13,
-    target venv on 3.11).
+    Delegates ``importlib.util.find_spec`` and
+    ``importlib.metadata.metadata`` to *python_exe* via subprocess,
+    keeping the tool process free from cross-version import
+    contamination.
 
     Args:
         python_exe: Absolute path to the target Python executable.
+        package_name: Package import name (e.g. ``openai``).
 
     Returns:
-        List of non-stdlib path strings from the target interpreter.
+        Dict with keys ``path`` (str | None), ``version`` (str | None),
+        ``summary`` (str | None), ``installed`` (list[str]).
 
     Raises:
         EnvironmentSetupError: If the subprocess fails or times out.
     """
-    # Filter out stdlib paths from the target interpreter's sys.path.
-    # When the target runs a different Python version from the tool,
-    # injecting stdlib paths causes C-extension mismatches (e.g.
-    # Python 3.13 loading csv.py from 3.11 stdlib → _csv ImportError).
-    script = (
-        "import json, os, sys\n"
-        "base = os.path.realpath(sys.base_prefix)\n"
-        "prefix = os.path.realpath(sys.prefix)\n"
-        "in_venv = prefix != base\n"
-        "def _under(p, root):\n"
-        "    return p == root or p.startswith(root + os.sep)\n"
-        "paths = [\n"
-        "    p for p in sys.path\n"
-        "    if p and not (\n"
-        "        in_venv\n"
-        "        and _under(os.path.realpath(p), base)\n"
-        "        and not _under(os.path.realpath(p), prefix)\n"
-        "    )\n"
-        "]\n"
-        "print(json.dumps(paths))\n"
-    )
     try:
         result = subprocess.run(
-            [str(python_exe), "-c", script],
+            [str(python_exe), "-c", _PACKAGE_DISCOVERY_SCRIPT, package_name],
             capture_output=True,
             text=True,
             timeout=_SUBPROCESS_TIMEOUT_SECONDS,
@@ -322,100 +295,70 @@ def get_target_sys_path(python_exe: Path) -> list[str]:
         stderr = result.stderr.strip()[:200]
         raise EnvironmentSetupError(
             str(python_exe),
-            f"interpreter exited with code {result.returncode}: {stderr}",
+            f"package discovery failed (exit {result.returncode}): {stderr}",
         )
 
     try:
-        paths = json.loads(result.stdout)
+        data = json.loads(result.stdout)
     except json.JSONDecodeError as exc:
         raise EnvironmentSetupError(
             str(python_exe),
-            f"cannot parse sys.path output: {exc}",
+            f"cannot parse discovery output: {exc}",
         ) from exc
 
-    if not isinstance(paths, list):
-        raise EnvironmentSetupError(
-            str(python_exe),
-            "sys.path output is not a list",
-        )
+    return data  # type: ignore[no-any-return]
 
-    return [str(p) for p in paths]
 
+def resolve_python_executable(python_arg: str) -> Path:
+    """Resolve a user-supplied path to a Python executable.
 
-@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.
+    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.
 
-    Yields:
-        The resolved Python executable path.
+    Returns:
+        Resolved absolute path to the Python executable.
 
     Raises:
-        EnvironmentSetupError: If the environment cannot be resolved
-            or queried.
+        EnvironmentSetupError: If the path does not exist or no
+            interpreter can be found.
     """
-    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()
+    path = Path(python_arg)
 
-        logger.debug(
-            "Activated environment '%s': injected %d paths",
+    if not path.exists():
+        raise EnvironmentSetupError(
             python_arg,
-            len(new_paths),
+            f"path does not exist: {python_arg}",
         )
-        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)
+    # Direct path to an executable
+    if path.is_file():
+        return path.resolve()
 
-    current_set = set(sys.path)
-    new_paths = [p for p in target_paths if p and p not in current_set]
+    # Directory — probe for interpreter
+    if path.is_dir():
+        for candidate in (path / rel for rel in _INTERPRETER_CANDIDATES):
+            if candidate.is_file():
+                logger.debug(
+                    "Resolved venv directory '%s' to interpreter '%s'",
+                    python_arg,
+                    candidate,
+                )
+                return candidate.resolve()
 
-    sys.path[:0] = new_paths
-    importlib.invalidate_caches()
+        raise EnvironmentSetupError(
+            python_arg,
+            f"no Python interpreter found in directory: {python_arg}. "
+            f"Expected Scripts/python.exe (Windows) or bin/python (Unix).",
+        )
 
-    logger.debug(
-        "Injected environment '%s': added %d paths",
+    raise EnvironmentSetupError(
         python_arg,
-        len(new_paths),
+        f"path is neither a file nor a directory: {python_arg}",
     )
 
 

{libcontext-0.7.1 → libcontext-0.7.4}/src/libcontext/cli.py

@@ -259,7 +259,7 @@ def inspect(
     from ._envsetup import setup_environment
 
     try:
-        _env_tag = setup_environment(python_env)
+        _env_tag, _target_python = setup_environment(python_env)
     except EnvironmentSetupError as exc:
         click.echo(f"Error: {exc}", err=True)
         sys.exit(1)
@@ -278,6 +278,7 @@ def inspect(
                 config_override=config,
                 no_cache=no_cache,
                 env_tag=_env_tag,
+                target_python=_target_python,
             )
         except PackageNotFoundError as exc:
             click.echo(f"Error: {exc}", err=True)

{libcontext-0.7.1 → libcontext-0.7.4}/src/libcontext/collector.py

@@ -636,6 +636,104 @@ def _walk_package(
     return modules
 
 
+# ---------------------------------------------------------------------------
+# Subprocess-based package discovery
+# ---------------------------------------------------------------------------
+
+
+def _find_stub_package_fs(package_name: str, pkg_path: Path) -> Path | None:
+    """Find a stub package via the filesystem, without importlib.metadata.
+
+    Derives the site-packages directory from *pkg_path* (its parent) and
+    checks for ``<name>-stubs/`` or ``<norm_name>-stubs/`` directories.
+    This works correctly in cross-venv scenarios where the tool process
+    cannot see the target's installed distributions.
+
+    Args:
+        package_name: The importable package name (e.g. ``openai``).
+        pkg_path: Resolved path to the package source directory.
+
+    Returns:
+        Path to the stub package directory, or ``None`` if not found.
+    """
+    norm_name = package_name.replace("-", "_").lower()
+    site_packages = pkg_path.parent
+
+    # Check in priority order: <name>-stubs, <norm_name>-stubs
+    for suffix in (f"{package_name}-stubs", f"{norm_name}-stubs"):
+        candidate = site_packages / suffix
+        if candidate.is_dir():
+            logger.debug("Found stub package at '%s'", candidate)
+            return candidate
+
+    return None
+
+
+def _resolve_via_target(
+    package_name: str,
+    python_exe: Path,
+) -> tuple[Path, dict[str, str | None], Path | None]:
+    """Discover a package by querying the target interpreter.
+
+    Delegates ``importlib.util.find_spec`` and metadata retrieval to
+    *python_exe* via subprocess, avoiding cross-version contamination.
+
+    Args:
+        package_name: The importable package name.
+        python_exe: Path to the target Python interpreter.
+
+    Returns:
+        A ``(pkg_path, metadata, stub_path)`` tuple.
+
+    Raises:
+        PackageNotFoundError: If the package is not found in the target.
+    """
+    from ._envsetup import query_target_package
+
+    data = query_target_package(python_exe, package_name)
+
+    pkg_path_str: str | None = data.get("path")  # type: ignore[assignment]
+    installed: list[str] = data.get("installed", [])  # type: ignore[assignment]
+
+    if pkg_path_str is None:
+        suggestions = difflib.get_close_matches(
+            package_name,
+            installed,
+            n=_SUGGESTION_MAX,
+            cutoff=_SUGGESTION_CUTOFF,
+        )
+        raise PackageNotFoundError(package_name, suggestions=suggestions)
+
+    pkg_path = Path(pkg_path_str)
+    metadata: dict[str, str | None] = {
+        "version": data.get("version"),  # type: ignore[dict-item]
+        "summary": data.get("summary"),  # type: ignore[dict-item]
+    }
+
+    # Check for compiled extension and stubs.
+    # Use filesystem-based detection: the target's site-packages is the
+    # parent of pkg_path, so we look for <name>-stubs/ there directly.
+    # This avoids using the tool's importlib.metadata which cannot see
+    # packages installed only in the target venv.
+    stub_path = _find_stub_package_fs(package_name, pkg_path)
+    if _is_compiled_extension(pkg_path):
+        if stub_path:
+            pkg_path = stub_path
+            stub_path = None
+            logger.info(
+                "Package '%s' has no Python source; using stubs as primary",
+                package_name,
+            )
+    elif stub_path:
+        logger.info(
+            "Stub package discovered for '%s' at %s",
+            package_name,
+            stub_path,
+        )
+
+    return pkg_path, metadata, stub_path
+
+
 # ---------------------------------------------------------------------------
 # Public API
 # ---------------------------------------------------------------------------
@@ -649,6 +747,7 @@ def collect_package(
     config_override: LibcontextConfig | None = None,
     no_cache: bool = False,
     env_tag: str | None = None,
+    target_python: Path | None = None,
 ) -> PackageInfo:
     """Collect complete API information for a Python package.
 
@@ -663,6 +762,11 @@ def collect_package(
         no_cache: Skip the disk cache (force fresh AST collection).
         env_tag: Environment identifier for cache namespacing (from
             ``--python``).
+        target_python: Resolved path to the target Python interpreter.
+            When provided, package discovery is delegated to this
+            interpreter via subprocess instead of using in-process
+            ``importlib``.  This prevents cross-version contamination
+            when the tool runs a different Python than the target.
 
     Returns:
         :class:`~libcontext.models.PackageInfo` with all collected data.
@@ -680,6 +784,15 @@ def collect_package(
         pkg_name = path.name if path.is_dir() else path.stem
         metadata: dict[str, str | None] = {}
         logger.debug("Resolved '%s' as local path: %s", package_name, pkg_path)
+    elif target_python is not None:
+        # Delegate discovery to the target interpreter to avoid
+        # cross-version importlib contamination.
+        pkg_path, metadata, stub_path = _resolve_via_target(
+            package_name,
+            target_python,
+        )
+        pkg_name = package_name
+        logger.debug("Resolved '%s' via target interpreter: %s", package_name, pkg_path)
     else:
         pkg_path_resolved = find_package_path(package_name)
 

{libcontext-0.7.1 → libcontext-0.7.4}/src/libcontext/mcp_server.py

@@ -24,6 +24,7 @@ import dataclasses
 import json
 import logging
 from functools import lru_cache
+from pathlib import Path
 
 from mcp.server.fastmcp import FastMCP
 
@@ -64,8 +65,9 @@ mcp = FastMCP(
 
 _CACHE_SIZE = 32
 
-# Set by main() at startup; used by _collect_cached for cache namespacing.
+# Set by main() at startup; used by _collect_cached for cache/discovery.
 _active_env_tag: str | None = None
+_active_target_python: Path | None = None
 
 
 @lru_cache(maxsize=_CACHE_SIZE)
@@ -76,6 +78,7 @@ def _collect_cached(package_name: str, include_private: bool = False) -> Package
         include_private=include_private,
         include_readme=False,
         env_tag=_active_env_tag,
+        target_python=_active_target_python,
     )
 
 
@@ -317,11 +320,11 @@ def main() -> None:
     elif os.environ.get("LIBCONTEXT_PYTHON"):
         python_env = os.environ["LIBCONTEXT_PYTHON"]
 
-    global _active_env_tag
+    global _active_env_tag, _active_target_python
 
     from ._envsetup import setup_environment
 
-    _active_env_tag = setup_environment(python_env)
+    _active_env_tag, _active_target_python = setup_environment(python_env)
 
     mcp.run()
 

{libcontext-0.7.1 → libcontext-0.7.4}/tests/test_envsetup.py

@@ -2,18 +2,15 @@
 
 from __future__ import annotations
 
-import os
 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,
+    query_target_package,
     resolve_python_executable,
     setup_environment,
 )
@@ -59,19 +56,32 @@ def test_resolve_empty_directory_raises(tmp_path):
 
 
 # ---------------------------------------------------------------------------
-# get_target_sys_path
+# query_target_package
 # ---------------------------------------------------------------------------
 
 
-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_query_target_package_finds_installed():
+    """Discovers a package known to be installed in the current interpreter."""
+    data = query_target_package(Path(sys.executable), "pytest")
+    assert data["path"] is not None
+    assert data["version"] is not None
+    assert isinstance(data["installed"], list)
+    assert len(data["installed"]) > 0
 
 
-def test_get_target_sys_path_bad_executable(tmp_path):
+def test_query_target_package_missing_returns_null_path():
+    """Returns null path for a package that does not exist."""
+    data = query_target_package(Path(sys.executable), "nonexistent_pkg_xyz")
+    assert data["path"] is None
+
+
+def test_query_target_package_returns_installed_names():
+    """The installed list contains distribution names for suggestions."""
+    data = query_target_package(Path(sys.executable), "pytest")
+    assert "pytest" in data["installed"]
+
+
+def test_query_target_package_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")
@@ -79,68 +89,7 @@ def test_get_target_sys_path_bad_executable(tmp_path):
         fake.chmod(0o755)
 
     with pytest.raises(EnvironmentSetupError):
-        get_target_sys_path(fake)
-
-
-def test_get_target_sys_path_excludes_base_stdlib_in_venv():
-    """Stdlib paths from the base interpreter are excluded when in a venv."""
-    paths = get_target_sys_path(Path(sys.executable))
-
-    base = os.path.realpath(sys.base_prefix)
-    prefix = os.path.realpath(sys.prefix)
-    if prefix == base:
-        pytest.skip("not running inside a venv")
-
-    # Paths under the base Python installation (stdlib, lib-dynload, etc.)
-    # must be excluded to prevent cross-version contamination.
-    # Paths under the venv prefix itself (e.g. site-packages) are kept.
-    for p in paths:
-        rp = os.path.realpath(p)
-        is_under_base = rp.startswith(base + os.sep) or rp == base
-        is_under_venv = rp.startswith(prefix + os.sep) or rp == prefix
-        if is_under_base and not is_under_venv:
-            pytest.fail(f"base-interpreter stdlib path leaked: {p}")
-
-
-# ---------------------------------------------------------------------------
-# 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
+        query_target_package(fake, "anything")
 
 
 # ---------------------------------------------------------------------------
@@ -291,22 +240,25 @@ def test_auto_detect_venv_ignores_dir_without_interpreter(tmp_path):
 
 
 def test_setup_environment_explicit_python():
-    """Explicit --python takes effect and returns an env_tag."""
-    tag = setup_environment(sys.executable)
+    """Explicit --python returns (env_tag, target_python)."""
+    tag, target = setup_environment(sys.executable)
     assert tag is not None
     assert len(tag) == 8
+    assert target is not None
+    assert target.is_file()
 
 
 @pytest.mark.usefixtures("_clean_venv_env")
 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)
+    """No venv, no --python → returns (None, None)."""
+    tag, target = setup_environment(None, cwd=tmp_path)
     assert tag is None
+    assert target is None
 
 
 @pytest.mark.usefixtures("_clean_venv_env")
 def test_setup_environment_auto_detects(tmp_path, monkeypatch):
-    """Auto-detects .venv/ and returns an env_tag when using real interpreter."""
+    """Auto-detects .venv/ and returns (env_tag, target_python)."""
     # Point the fake venv at the real interpreter so subprocess works
     venv = tmp_path / ".venv"
     venv.mkdir()
@@ -314,19 +266,21 @@ def test_setup_environment_auto_detects(tmp_path, monkeypatch):
     if sys.platform == "win32":
         scripts = venv / "Scripts"
         scripts.mkdir()
-        target = scripts / "python.exe"
+        link = scripts / "python.exe"
     else:
         bin_dir = venv / "bin"
         bin_dir.mkdir()
-        target = bin_dir / "python"
+        link = bin_dir / "python"
 
     # Create a symlink (or copy) so the interpreter actually works
     try:
-        target.symlink_to(real_exe)
+        link.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)
+    tag, target = setup_environment(None, cwd=tmp_path)
     assert tag is not None
     assert len(tag) == 8
+    assert target is not None
+    assert target.is_file()