cli-tools-kit 0.8.2__tar.gz → 0.8.3__tar.gz

{cli_tools_kit-0.8.2 → cli_tools_kit-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-tools-kit
-Version: 0.8.2
+Version: 0.8.3
 Summary: Installer protocol + helpers for self-installing Python CLI/GUI tools (desktop shortcuts, bash aliases, cron entries), plus reusable tkinter and curses installer screens
 Author: Steffen Probst
 License: MIT License

{cli_tools_kit-0.8.2 → cli_tools_kit-0.8.3}/cli_tools_kit/__init__.py

@@ -56,4 +56,4 @@ __all__ = [
     "read_installed_skill",
 ]
 
-__version__ = "0.8.2"
+__version__ = "0.8.3"

{cli_tools_kit-0.8.2 → cli_tools_kit-0.8.3}/cli_tools_kit/gui_installer.py

@@ -60,6 +60,7 @@ except ImportError:  # pragma: no cover - exercised only where python3-tk is mis
 from typing import Callable, Dict, List, NamedTuple, Optional, Sequence
 
 from . import host
+from . import venvs
 from .identity import InstallerIdentity, LEGACY_IDENTITY
 from .autostart_gate import (
     KNOWN_CONDITIONS,
@@ -1149,9 +1150,20 @@ def install_tool(tool: ToolEntry, skip_deps: bool = False) -> tuple[bool, str]:
     When skip_deps is True, sets TOOLS_INSTALLER_SKIP_DEPS=1 in the child
     environment so the shared ToolInstaller writes the .desktop/alias without
     running 'pip install'. This keeps a shortcut refresh local and network-free.
+
+    The tool runs in the venv :mod:`cli_tools_kit.venvs` resolves for its
+    checkout — shared with every other checkout of the same upstream repo, so
+    a tool offered by two installers is built once. That venv is provisioned
+    here, before --install runs, because the tool imports this package to
+    handle the flag and cannot install what it is already missing.
     """
     try:
-        cmd = [sys.executable, tool.script_path, "--install"] + tool.args
+        tool_dir = os.path.dirname(tool.script_path)
+        try:
+            python = venvs.ensure_venv(tool_dir, provision=not skip_deps)
+        except RuntimeError as exc:
+            return False, str(exc)
+        cmd = [python, tool.script_path, "--install"] + tool.args
         env = os.environ.copy()
         # The tool writes its own .desktop and alias via ToolInstaller, so it
         # needs to know which installer asked — otherwise a third-party org's
@@ -1171,9 +1183,17 @@ def install_tool(tool: ToolEntry, skip_deps: bool = False) -> tuple[bool, str]:
         return False, str(e)
 
 def remove_tool(tool: ToolEntry) -> tuple[bool, str]:
-    """Invokes the tool's own --remove argument. Returns (success, output)."""
+    """Invokes the tool's own --remove argument. Returns (success, output).
+
+    Runs in the tool's venv, provisioning nothing: removal must work even when
+    the environment is half-built, and it must not rebuild what it is about to
+    stop using. The shared venv stays behind — another installer's checkout of
+    the same upstream may still need it.
+    """
     try:
-        cmd = [sys.executable, tool.script_path, "--remove"] + tool.args
+        python = venvs.ensure_venv(os.path.dirname(tool.script_path),
+                                   provision=False)
+        cmd = [python, tool.script_path, "--remove"] + tool.args
         env = os.environ.copy()
         env.update(IDENTITY.env())   # remove the alias from OUR alias file
         result = subprocess.run(cmd, cwd=os.path.dirname(tool.script_path),
@@ -1194,7 +1214,12 @@ def install_skill_for_tool(tool: ToolEntry) -> tuple[bool, str]:
     detect an up-to-date SKILL.md and no-op.
     """
     try:
-        cmd = [sys.executable, tool.script_path, "--install-skill"] + tool.args
+        # provision=False: ticking a skill box must not build a venv. An
+        # uninstalled tool still registers its skill, under whichever
+        # interpreter is to hand.
+        python = venvs.ensure_venv(os.path.dirname(tool.script_path),
+                                   provision=False)
+        cmd = [python, tool.script_path, "--install-skill"] + tool.args
         result = subprocess.run(cmd, cwd=os.path.dirname(tool.script_path),
                                 capture_output=True, text=True)
         output = (result.stdout + result.stderr).strip()
@@ -1208,7 +1233,9 @@ def install_skill_for_tool(tool: ToolEntry) -> tuple[bool, str]:
 def uninstall_skill_for_tool(tool: ToolEntry) -> tuple[bool, str]:
     """Invokes the tool's --uninstall-skill argument. Returns (success, output)."""
     try:
-        cmd = [sys.executable, tool.script_path, "--uninstall-skill"] + tool.args
+        python = venvs.ensure_venv(os.path.dirname(tool.script_path),
+                                   provision=False)
+        cmd = [python, tool.script_path, "--uninstall-skill"] + tool.args
         result = subprocess.run(cmd, cwd=os.path.dirname(tool.script_path),
                                 capture_output=True, text=True)
         output = (result.stdout + result.stderr).strip()
@@ -1419,8 +1446,15 @@ def get_autostart_path(tool: ToolEntry) -> str:
 
 
 def _cron_line_for_tool(tool: ToolEntry) -> str:
-    """Build the crontab line for a cron-based tool."""
-    parts = [tool.cron_schedule, sys.executable, tool.script_path] + list(tool.cron_args)
+    """Build the crontab line for a cron-based tool.
+
+    The interpreter is the tool's own venv, not the installer's: cron runs the
+    line long after the installer has exited, and the installer's Python has
+    none of the tool's dependencies.
+    """
+    python = venvs.ensure_venv(os.path.dirname(tool.script_path),
+                               provision=False)
+    parts = [tool.cron_schedule, python, tool.script_path] + list(tool.cron_args)
     return " ".join(parts)
 
 
@@ -3783,8 +3817,10 @@ class InstallerApp:
                             dialog.after(0, mark_failed)
 
                     except Exception as e:
+                        error_msg = str(e)[:20]
+
                         def mark_error():
-                            update_grid_cell(idx, None, f"Error: {str(e)[:20]}")
+                            update_grid_cell(idx, None, f"Error: {error_msg}")
                             current_index[0] += 1
                             dialog.after(100, generate_next_varied)
                         dialog.after(0, mark_error)
@@ -4663,7 +4699,7 @@ class InstallerApp:
             autostart_var.trace_add("write", self._on_checkbox_changed)
             # A tool with conditions gets the checkbox and a ⚙ side by side;
             # without them the checkbox stays centred as before.
-            if tool.autostart_conditions:
+            if parent.autostart_conditions:
                 holder = ttk.Frame(autostart_frame, style="Card.TFrame")
                 holder.pack(expand=True)
                 autostart_cb = ttk.Checkbutton(holder, variable=autostart_var, style="Card.TCheckbutton")

{cli_tools_kit-0.8.2 → cli_tools_kit-0.8.3}/cli_tools_kit/tui_installer.py

@@ -12,8 +12,9 @@ step, drawn with the stdlib ``curses`` module.
 
 Everything that touches the host goes through :mod:`gui_installer`'s
 primitives, looked up on that module at call time, so a wrapper that replaced
-them (FAU-WW3-Tools routes each tool through its own venv) is honoured here
-as well.
+them is honoured here as well. Routing each tool through its own venv is no
+longer something a wrapper has to do: :mod:`cli_tools_kit.venvs` is the default
+for both screens.
 
 Skill targets
 -------------

cli_tools_kit-0.8.3/cli_tools_kit/venvs.py

@@ -0,0 +1,319 @@
+"""One venv per tool, shared by every installer that offers that tool.
+
+A host often carries the same tool twice. Two installers each clone
+``manim-kit`` from the same GitHub repo into their own tree, and each
+provisions its own ``.venv`` next to the checkout — two copies of manim, two
+copies of Kokoro, 666M apiece, from one upstream.
+
+This module puts the venv somewhere neither checkout owns:
+
+    <IDENTITY.cache_path>/venvs/<key>/
+
+``key`` comes from the checkout's ``origin`` remote, normalised so that
+``git@github.com:Org/tool`` and ``https://github.com/Org/tool.git`` agree
+(:func:`upstream_key`). Both checkouts resolve to the same directory, so the
+second install finds the environment already built. A checkout with no origin
+remote is nobody's duplicate: it keeps a private ``.venv`` in the tool
+directory, exactly as before this module existed.
+
+Requirements drift between checkouts
+------------------------------------
+Two checkouts of one tool sit at different commits, so their
+``requirements.txt`` differ. The shared venv records what it last installed in
+``.cli-tools-kit.json`` (:func:`read_manifest`) together with the checkout and
+commit that wrote it. :func:`ensure_venv` compares the incoming requirement
+lines against that record and reinstalls when they differ, so whichever
+checkout ran most recently has its dependencies present.
+
+Where one checkout's requirements are a superset of the other's — the usual
+case, a tool that grew a dependency — pip converges and both checkouts work.
+Where two pins genuinely contradict each other pip fails, and the error names
+the checkout that last wrote the venv, because that is the one holding the
+environment the current install is fighting.
+
+Adopting what is already on disk
+--------------------------------
+A per-checkout ``.venv`` from before the move is not deleted. The first
+install after the upgrade adopts one (:func:`adopt_existing`) as the shared
+venv when no shared venv exists yet; any further ones are left alone on disk
+for the user to remove. Deleting a few hundred megabytes is the user's call,
+so the installer only reports them.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+from typing import Optional
+
+MANIFEST_NAME = ".cli-tools-kit.json"
+
+# git@host:org/repo.git and ssh://git@host/org/repo both mean the same upstream
+# as https://host/org/repo — strip the transport so the key does not.
+_SCP_LIKE = re.compile(r"^(?:[\w.-]+@)?([\w.-]+):(.+)$")
+_URL_LIKE = re.compile(r"^[a-z][a-z0-9+.-]*://(?:[^@/]+@)?([\w.-]+)/(.+)$", re.I)
+
+
+def normalise_remote(url: str) -> Optional[str]:
+    """``host/path`` for a git remote, or None when it does not look like one.
+
+    Lowercased and stripped of the transport, any credentials, a trailing
+    ``.git`` and trailing slashes, so every spelling of one repo gives one
+    string::
+
+        git@github.com:Org/tool.git   -> github.com/org/tool
+        https://github.com/Org/tool   -> github.com/org/tool
+
+    A remote that is a local path — a bare repo on this machine, or a mirror on
+    a mounted share — is resolved to its absolute path under a ``local`` host.
+    Two clones of one such repo are as much the same upstream as two clones of
+    one GitHub repo, and share a venv on the same terms. Case is preserved
+    here: unlike a hostname, a POSIX path distinguishes it.
+    """
+    url = (url or "").strip()
+    if not url:
+        return None
+    if url.startswith("file://"):
+        url = url[len("file://"):]
+    # A local path first: on Windows `C:\repos\tool` also matches the scp-like
+    # pattern, and reading it as host `c` would be wrong.
+    if url.startswith(("/", "./", "../", "~")) or os.path.isabs(url) \
+            or os.path.isdir(url):
+        path = os.path.normpath(os.path.abspath(os.path.expanduser(url)))
+        if path.endswith(".git"):
+            path = path[: -len(".git")]
+        return f"local{path}" if path.startswith("/") else f"local/{path}"
+    m = _URL_LIKE.match(url) or _SCP_LIKE.match(url)
+    if not m:
+        return None
+    host, path = m.group(1), m.group(2)
+    path = path.strip("/")
+    if path.lower().endswith(".git"):
+        path = path[: -len(".git")]
+    if not path:
+        return None
+    return f"{host.lower()}/{path.lower()}"
+
+
+def origin_url(tool_dir: str) -> Optional[str]:
+    """The ``origin`` remote of the checkout at ``tool_dir``, if it has one."""
+    try:
+        result = subprocess.run(
+            ["git", "-C", tool_dir, "remote", "get-url", "origin"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def head_commit(tool_dir: str) -> Optional[str]:
+    """Short HEAD of the checkout, for the manifest's record of who wrote it."""
+    try:
+        result = subprocess.run(
+            ["git", "-C", tool_dir, "rev-parse", "--short", "HEAD"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def upstream_key(tool_dir: str) -> Optional[str]:
+    """Stable directory name for the venv shared by one upstream repo.
+
+    None when the checkout has no usable ``origin``, which means it cannot be
+    matched with any other checkout and so keeps a private venv.
+    """
+    normalised = normalise_remote(origin_url(tool_dir) or "")
+    if not normalised:
+        return None
+    digest = hashlib.sha256(normalised.encode("utf-8")).hexdigest()[:12]
+    # The leaf name is readable on purpose: a user looking through the cache
+    # should see which tool a directory belongs to without resolving a hash.
+    leaf = re.sub(r"[^a-z0-9]+", "-", normalised.rsplit("/", 1)[-1]).strip("-")
+    return f"{leaf}-{digest}" if leaf else digest
+
+
+def venvs_root() -> str:
+    """Directory holding every shared venv for this installer's organisation.
+
+    ``gui_installer.IDENTITY`` is rebound when a wrapper calls ``run()``, so it
+    is read here at call time rather than imported once — two organisations on
+    one host must not share a cache directory.
+    """
+    from . import gui_installer
+    return os.path.join(gui_installer.IDENTITY.cache_path, "venvs")
+
+
+def venv_python(venv_dir: str) -> str:
+    """Interpreter path inside ``venv_dir`` on this platform."""
+    if os.name == "nt":
+        return os.path.join(venv_dir, "Scripts", "python.exe")
+    return os.path.join(venv_dir, "bin", "python3")
+
+
+def private_venv(tool_dir: str) -> str:
+    """The pre-0.9 location: a ``.venv`` beside the tool's own script."""
+    return os.path.join(tool_dir, ".venv")
+
+
+def venv_for(tool_dir: str) -> str:
+    """Where this checkout's venv belongs — shared when it has an upstream."""
+    key = upstream_key(tool_dir)
+    if not key:
+        return private_venv(tool_dir)
+    return os.path.join(venvs_root(), key)
+
+
+def requirement_lines(requirements: str) -> list:
+    """Requirement lines of a requirements file, without comments or blanks."""
+    try:
+        with open(requirements, encoding="utf-8") as fh:
+            lines = fh.readlines()
+    except OSError:
+        return []
+    out = []
+    for line in lines:
+        line = line.strip()
+        if line and not line.startswith("#"):
+            out.append(line)
+    return out
+
+
+def manifest_path(venv_dir: str) -> str:
+    return os.path.join(venv_dir, MANIFEST_NAME)
+
+
+def read_manifest(venv_dir: str) -> dict:
+    """What this venv last installed, or ``{}`` when it has no record."""
+    try:
+        with open(manifest_path(venv_dir), encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def write_manifest(venv_dir: str, requirements: list, tool_dir: str) -> None:
+    """Record the requirements just installed and the checkout that asked."""
+    data = {
+        "requirements": list(requirements),
+        "written_by": os.path.abspath(tool_dir),
+        "commit": head_commit(tool_dir),
+    }
+    try:
+        os.makedirs(venv_dir, exist_ok=True)
+        with open(manifest_path(venv_dir), "w", encoding="utf-8") as fh:
+            json.dump(data, fh, indent=2, sort_keys=True)
+    except OSError:
+        pass  # a venv that works but cannot be annotated still works
+
+
+def adopt_existing(tool_dir: str, venv_dir: str) -> bool:
+    """Move a pre-existing private ``.venv`` into the shared location.
+
+    Only when the shared venv does not exist yet, so the first install after
+    the upgrade reuses what is already built instead of downloading it again.
+    Returns True when a venv was adopted. Other checkouts' private venvs are
+    left where they are; :func:`stale_private_venvs` reports them.
+    """
+    private = private_venv(tool_dir)
+    if os.path.abspath(private) == os.path.abspath(venv_dir):
+        return False
+    if os.path.exists(venv_dir) or not os.path.isdir(private):
+        return False
+    if not os.path.exists(venv_python(private)):
+        return False
+    try:
+        os.makedirs(os.path.dirname(venv_dir), exist_ok=True)
+        os.rename(private, venv_dir)
+    except OSError:
+        return False  # across filesystems, or in use: build a fresh one instead
+    # A venv records its own location in pyvenv.cfg and in the shebangs of its
+    # scripts, so a moved one is only safe through its interpreter, never
+    # through `<venv>/bin/<entry-point>`. The kit always calls the interpreter.
+    return True
+
+
+def stale_private_venvs(tool_dirs) -> list:
+    """Private ``.venv`` directories made redundant by a shared venv.
+
+    Reported to the user, never deleted: these run to hundreds of megabytes
+    and removing them is a decision the installer does not get to make.
+    """
+    out = []
+    for tool_dir in tool_dirs:
+        private = private_venv(tool_dir)
+        shared = venv_for(tool_dir)
+        if os.path.abspath(private) == os.path.abspath(shared):
+            continue
+        if os.path.isdir(private) and os.path.isdir(shared):
+            out.append(private)
+    return out
+
+
+def ensure_venv(tool_dir: str, requirements: Optional[str] = None,
+                provision: bool = True) -> str:
+    """Interpreter to run this tool with, building the venv when asked.
+
+    Creates the shared venv if it is missing, adopting an existing private one
+    first. Installs the checkout's requirements whenever they differ from what
+    the manifest records, so a second checkout at a different commit gets its
+    own dependencies rather than inheriting a stale set.
+
+    With ``provision=False`` nothing is created or installed: the existing
+    interpreter is returned when there is one, else the current one. That is
+    the path taken by the login check and by a shortcuts-only refresh.
+    """
+    venv_dir = venv_for(tool_dir)
+    py = venv_python(venv_dir)
+
+    if not provision:
+        return py if os.path.exists(py) else sys.executable
+
+    if requirements is None:
+        requirements = os.path.join(tool_dir, "requirements.txt")
+    wanted = requirement_lines(requirements)
+    if not wanted:
+        # Nothing to install: a venv would add nothing over the interpreter
+        # already running, and building one costs a directory for no gain.
+        return py if os.path.exists(py) else sys.executable
+
+    if not os.path.exists(py):
+        adopt_existing(tool_dir, venv_dir)
+    if not os.path.exists(py):
+        try:
+            os.makedirs(os.path.dirname(venv_dir), exist_ok=True)
+            subprocess.run([sys.executable, "-m", "venv", venv_dir], check=True)
+        except (OSError, subprocess.CalledProcessError):
+            return sys.executable  # no venv to be had; the caller still runs
+
+    manifest = read_manifest(venv_dir)
+    if manifest.get("requirements") == wanted:
+        return py if os.path.exists(py) else sys.executable
+
+    try:
+        subprocess.run([py, "-m", "pip", "install", "-r", requirements],
+                       check=True)
+    except (OSError, subprocess.CalledProcessError) as exc:
+        owner = manifest.get("written_by")
+        if owner and os.path.abspath(owner) != os.path.abspath(tool_dir):
+            commit = manifest.get("commit") or "unknown commit"
+            raise RuntimeError(
+                f"{requirements} could not be installed into the venv shared "
+                f"with {owner} (last written from {commit}). The two checkouts "
+                f"pin dependencies that cannot both hold. Pip said: {exc}"
+            ) from exc
+        raise
+
+    write_manifest(venv_dir, wanted, tool_dir)
+    return py if os.path.exists(py) else sys.executable

{cli_tools_kit-0.8.2 → cli_tools_kit-0.8.3}/cli_tools_kit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-tools-kit
-Version: 0.8.2
+Version: 0.8.3
 Summary: Installer protocol + helpers for self-installing Python CLI/GUI tools (desktop shortcuts, bash aliases, cron entries), plus reusable tkinter and curses installer screens
 Author: Steffen Probst
 License: MIT License

{cli_tools_kit-0.8.2 → cli_tools_kit-0.8.3}/cli_tools_kit.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ cli_tools_kit/skills.py
 cli_tools_kit/sources.py
 cli_tools_kit/tool_installer.py
 cli_tools_kit/tui_installer.py
+cli_tools_kit/venvs.py
 cli_tools_kit.egg-info/PKG-INFO
 cli_tools_kit.egg-info/SOURCES.txt
 cli_tools_kit.egg-info/dependency_links.txt
@@ -38,4 +39,5 @@ tests/test_skills.py
 tests/test_sources.py
 tests/test_taxonomy_cluster.py
 tests/test_tool_installer.py
-tests/test_tui_installer.py
+tests/test_tui_installer.py
+tests/test_venvs.py

{cli_tools_kit-0.8.2 → cli_tools_kit-0.8.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cli-tools-kit"
-version = "0.8.2"
+version = "0.8.3"
 description = "Installer protocol + helpers for self-installing Python CLI/GUI tools (desktop shortcuts, bash aliases, cron entries), plus reusable tkinter and curses installer screens"
 readme = "README.md"
 requires-python = ">=3.10"

cli_tools_kit-0.8.3/tests/test_venvs.py

@@ -0,0 +1,242 @@
+"""Tests for venvs — one venv per upstream, shared across installers."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from cli_tools_kit import venvs
+
+
+def _pip_calls(monkeypatch: pytest.MonkeyPatch, tool: Path) -> list:
+    """Run ensure_venv with pip stubbed out, returning the pip commands it ran.
+
+    Only pip is intercepted: the git calls that resolve the upstream key have
+    to keep working, or the venv would not resolve to the shared location the
+    test just prepared.
+    """
+    real_run = subprocess.run
+    calls = []
+
+    def fake_run(cmd, *a, **k):
+        if "pip" in cmd:
+            calls.append(cmd)
+            return subprocess.CompletedProcess(cmd, 0, "", "")
+        return real_run(cmd, *a, **k)
+
+    monkeypatch.setattr(venvs.subprocess, "run", fake_run)
+    venvs.ensure_venv(str(tool))
+    return calls
+
+
+def _checkout(home: Path, name: str, origin: str | None,
+              requirements: str = "somedep==1.0\n") -> Path:
+    """A tool directory, optionally a git checkout with an origin remote."""
+    tool_dir = home / name
+    tool_dir.mkdir(parents=True)
+    (tool_dir / "requirements.txt").write_text(requirements)
+    if origin is not None:
+        subprocess.run(["git", "init", "-q", str(tool_dir)], check=True)
+        subprocess.run(["git", "-C", str(tool_dir), "remote", "add",
+                        "origin", origin], check=True)
+    return tool_dir
+
+
+# --- key derivation ----------------------------------------------------------------
+
+@pytest.mark.parametrize("url, expected", [
+    ("git@github.com:Org/tool.git", "github.com/org/tool"),
+    ("git@github.com:Org/tool", "github.com/org/tool"),
+    ("https://github.com/Org/tool.git", "github.com/org/tool"),
+    ("https://github.com/Org/tool", "github.com/org/tool"),
+    ("https://user@github.com/Org/tool/", "github.com/org/tool"),
+    ("ssh://git@github.com/Org/tool.git", "github.com/org/tool"),
+])
+def test_normalise_remote_agrees_across_spellings(url: str, expected: str) -> None:
+    assert venvs.normalise_remote(url) == expected
+
+
+@pytest.mark.parametrize("url", ["", "   ", "not a url"])
+def test_normalise_remote_rejects_non_remotes(url: str) -> None:
+    assert venvs.normalise_remote(url) is None
+
+
+def test_local_path_remotes_agree(tmp_path: Path) -> None:
+    """A bare repo on disk is an upstream too — two clones of it should share."""
+    bare = tmp_path / "upstream.git"
+    bare.mkdir()
+    direct = venvs.normalise_remote(str(bare))
+    assert direct is not None
+    assert venvs.normalise_remote(f"file://{bare}") == direct
+    assert venvs.normalise_remote(str(tmp_path / "." / "upstream.git")) == direct
+
+
+def test_different_repos_get_different_keys(sandbox_home: Path) -> None:
+    a = _checkout(sandbox_home, "a", "git@github.com:Org/one.git")
+    b = _checkout(sandbox_home, "b", "git@github.com:Org/two.git")
+    assert venvs.upstream_key(str(a)) != venvs.upstream_key(str(b))
+
+
+def test_key_is_none_without_origin(sandbox_home: Path) -> None:
+    plain = _checkout(sandbox_home, "plain", None)
+    assert venvs.upstream_key(str(plain)) is None
+
+
+# --- the point of the module -------------------------------------------------------
+
+def test_two_checkouts_of_one_upstream_share_a_venv(sandbox_home: Path) -> None:
+    """The whole reason this module exists: install once, reuse everywhere."""
+    first = _checkout(sandbox_home, "installer-a/manim-kit",
+                      "git@github.com:Org/manim-kit.git")
+    second = _checkout(sandbox_home, "installer-b/manim-kit",
+                       "https://github.com/Org/manim-kit")
+    assert venvs.venv_for(str(first)) == venvs.venv_for(str(second))
+
+
+def test_checkout_without_origin_keeps_a_private_venv(sandbox_home: Path) -> None:
+    plain = _checkout(sandbox_home, "plain", None)
+    assert venvs.venv_for(str(plain)) == str(plain / ".venv")
+
+
+def test_shared_venv_lives_outside_both_checkouts(sandbox_home: Path) -> None:
+    tool = _checkout(sandbox_home, "installer-a/tool", "git@github.com:Org/tool.git")
+    assert not venvs.venv_for(str(tool)).startswith(str(tool))
+
+
+# --- requirements --------------------------------------------------------------
+
+def test_requirement_lines_skip_comments_and_blanks(tmp_path: Path) -> None:
+    req = tmp_path / "requirements.txt"
+    req.write_text("# a comment\n\nfoo==1.0\n  bar>=2  \n\n# trailing\n")
+    assert venvs.requirement_lines(str(req)) == ["foo==1.0", "bar>=2"]
+
+
+def test_requirement_lines_of_missing_file_is_empty(tmp_path: Path) -> None:
+    assert venvs.requirement_lines(str(tmp_path / "nope.txt")) == []
+
+
+def test_manifest_round_trip(sandbox_home: Path) -> None:
+    tool = _checkout(sandbox_home, "tool", "git@github.com:Org/tool.git")
+    venv_dir = sandbox_home / "venv"
+    venv_dir.mkdir()
+    venvs.write_manifest(str(venv_dir), ["foo==1.0"], str(tool))
+    stored = venvs.read_manifest(str(venv_dir))
+    assert stored["requirements"] == ["foo==1.0"]
+    assert stored["written_by"] == str(tool)
+
+
+def test_read_manifest_of_unwritten_venv_is_empty(tmp_path: Path) -> None:
+    assert venvs.read_manifest(str(tmp_path)) == {}
+
+
+def test_read_manifest_survives_corruption(tmp_path: Path) -> None:
+    (tmp_path / venvs.MANIFEST_NAME).write_text("{not json")
+    assert venvs.read_manifest(str(tmp_path)) == {}
+
+
+# --- provisioning ------------------------------------------------------------------
+
+def test_no_requirements_means_no_venv_is_built(sandbox_home: Path) -> None:
+    """A tool with nothing to install gains nothing from a venv."""
+    tool = _checkout(sandbox_home, "tool", "git@github.com:Org/tool.git",
+                     requirements="# only a comment\n")
+    import sys
+    assert venvs.ensure_venv(str(tool)) == sys.executable
+    assert not Path(venvs.venv_for(str(tool))).exists()
+
+
+def test_provision_false_never_creates_anything(sandbox_home: Path) -> None:
+    tool = _checkout(sandbox_home, "tool", "git@github.com:Org/tool.git")
+    venvs.ensure_venv(str(tool), provision=False)
+    assert not Path(venvs.venv_for(str(tool))).exists()
+
+
+def test_matching_requirements_skip_reinstall(sandbox_home: Path,
+                                              monkeypatch: pytest.MonkeyPatch) -> None:
+    """The second installer must not re-run pip for an already-built venv."""
+    tool = _checkout(sandbox_home, "tool", "git@github.com:Org/tool.git")
+    venv_dir = Path(venvs.venv_for(str(tool)))
+    (venv_dir / "bin").mkdir(parents=True)
+    (venv_dir / "bin" / "python3").write_text("")
+    venvs.write_manifest(str(venv_dir), ["somedep==1.0"], str(tool))
+
+    assert _pip_calls(monkeypatch, tool) == []
+
+
+def test_drifted_requirements_trigger_reinstall(sandbox_home: Path,
+                                                monkeypatch: pytest.MonkeyPatch) -> None:
+    """A checkout at a different commit gets its own dependencies installed."""
+    tool = _checkout(sandbox_home, "tool", "git@github.com:Org/tool.git",
+                     requirements="somedep==2.0\n")
+    venv_dir = Path(venvs.venv_for(str(tool)))
+    (venv_dir / "bin").mkdir(parents=True)
+    (venv_dir / "bin" / "python3").write_text("")
+    venvs.write_manifest(str(venv_dir), ["somedep==1.0"], str(tool))
+
+    assert _pip_calls(monkeypatch, tool) != []
+    assert venvs.read_manifest(str(venv_dir))["requirements"] == ["somedep==2.0"]
+
+
+def test_conflicting_pins_name_the_other_checkout(sandbox_home: Path,
+                                                  monkeypatch: pytest.MonkeyPatch) -> None:
+    """When pip cannot satisfy both checkouts, say which one holds the venv."""
+    other = _checkout(sandbox_home, "installer-a/tool", "git@github.com:Org/tool.git")
+    tool = _checkout(sandbox_home, "installer-b/tool", "git@github.com:Org/tool.git",
+                     requirements="somedep==2.0\n")
+    venv_dir = Path(venvs.venv_for(str(tool)))
+    (venv_dir / "bin").mkdir(parents=True)
+    (venv_dir / "bin" / "python3").write_text("")
+    venvs.write_manifest(str(venv_dir), ["somedep==1.0"], str(other))
+
+    real_run = subprocess.run
+
+    def fail_pip(cmd, *a, **k):
+        if "pip" in cmd:
+            raise subprocess.CalledProcessError(1, cmd)
+        return real_run(cmd, *a, **k)
+
+    monkeypatch.setattr(venvs.subprocess, "run", fail_pip)
+    with pytest.raises(RuntimeError, match=str(other)):
+        venvs.ensure_venv(str(tool))
+
+
+# --- migration ---------------------------------------------------------------------
+
+def test_existing_private_venv_is_adopted(sandbox_home: Path) -> None:
+    """The 666M already on disk is reused, not downloaded again."""
+    tool = _checkout(sandbox_home, "tool", "git@github.com:Org/tool.git")
+    private = tool / ".venv"
+    (private / "bin").mkdir(parents=True)
+    (private / "bin" / "python3").write_text("")
+    (private / "marker").write_text("original")
+
+    shared = venvs.venv_for(str(tool))
+    assert venvs.adopt_existing(str(tool), shared) is True
+    assert (Path(shared) / "marker").read_text() == "original"
+    assert not private.exists()
+
+
+def test_adoption_does_not_clobber_an_existing_shared_venv(sandbox_home: Path) -> None:
+    tool = _checkout(sandbox_home, "tool", "git@github.com:Org/tool.git")
+    private = tool / ".venv"
+    (private / "bin").mkdir(parents=True)
+    (private / "bin" / "python3").write_text("")
+
+    shared = Path(venvs.venv_for(str(tool)))
+    shared.mkdir(parents=True)
+    assert venvs.adopt_existing(str(tool), str(shared)) is False
+    assert private.exists()
+
+
+def test_stale_private_venvs_are_reported_not_removed(sandbox_home: Path) -> None:
+    first = _checkout(sandbox_home, "installer-a/tool", "git@github.com:Org/tool.git")
+    second = _checkout(sandbox_home, "installer-b/tool", "git@github.com:Org/tool.git")
+    leftover = second / ".venv"
+    leftover.mkdir()
+    Path(venvs.venv_for(str(first))).mkdir(parents=True)
+
+    stale = venvs.stale_private_venvs([str(first), str(second)])
+    assert stale == [str(leftover)]
+    assert leftover.exists()