runspec-linux-core 0.3.1__tar.gz → 0.3.3__tar.gz

{runspec_linux_core-0.3.1 → runspec_linux_core-0.3.3}/CHANGELOG.md

@@ -1,5 +1,47 @@
 # runspec-linux-core Changelog
 
+## [0.3.3] — 2026-06-22
+
+Add `commands.py` — the pure logic behind the new `runspec-linux` `which`
+runnable:
+
+- **`which(names, *, all_matches=False, path=None)`** — locate executables on the
+  search PATH, like the `which` command. `names` is a single command or a list
+  (a string is split on whitespace, so `"python3 pip3"` resolves both).
+  `all_matches` returns every match across the PATH (not just the first that
+  would run); `path` overrides the search path (defaults to `$PATH`, falling back
+  to `os.defpath`). A name containing a path separator is checked directly rather
+  than searched. Returns `{path, all_found, results: [{name, found, path,
+  paths}]}` and raises `ValueError` when no name is given.
+
+## [0.3.2] — 2026-06-21
+
+Add `venvs.py` — the pure logic behind three new `runspec-linux` runnables for
+Python virtualenv management:
+
+- **`create_venv(python, dest, *, run_as=None, become_method="sudo", group=None,
+  system_site_packages=False, upgrade_deps=False, clear=False, prompt=None)`** —
+  build a venv at `dest` from a *specific* interpreter (no system default
+  fallback; `python` must be an executable file), always with `--symlinks`. Then
+  creates `<dest>/logs` mode `2775` (setgid, so audit logs inherit the group) and
+  optionally `chgrp -R`s the venv to a shared `group` — the shape a service
+  account needs for a venv shared between several consoles.
+- **`install_into_venv(venv, packages="", *, project=None, editable=False,
+  upgrade=False, no_cache_dir=False, force_reinstall=False, run_as=None,
+  become_method="sudo")`** — `pip install` named packages and/or a local `project`
+  (a `pyproject.toml` directory or a wheel/sdist; `editable` for `-e`) into the
+  venv's bundled python. Package names reuse the shared injection guard.
+- **`configure_pip(index_url, *, extra_index_url=None, trusted_host=None,
+  cert=None, timeout=None, retries=None, proxy=None, require_virtualenv=False,
+  scope="user", venv=None, run_as=None, become_method="sudo")`** — write a
+  validated `pip.conf` (`[global]`) at user (`~/.config/pip/pip.conf`) or venv
+  (`<venv>/pip.conf`) scope for private-PyPI access.
+
+All three take a **runtime** `run_as` user (the service account is chosen
+per-invocation, so escalation is internal — `sudo -n -u <user>` or, via
+`become_method`, `su` — not a declarative `run_as`) and raise `ValueError` on bad
+input / `CommandError` on a failed step.
+
 ## [0.3.1] — 2026-06-20
 
 Fix `enable_passwordless_sudo` failing with "visudo not installed" (and the same

{runspec_linux_core-0.3.1 → runspec_linux_core-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runspec-linux-core
-Version: 0.3.1
+Version: 0.3.3
 Summary: Pure-Python Linux system-admin helpers — the importable core behind runspec-linux (no runspec dependency, no runnables)
 Requires-Python: >=3.10
 Provides-Extra: dev

{runspec_linux_core-0.3.1 → runspec_linux_core-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-linux-core"
-version = "0.3.1"
+version = "0.3.3"
 requires-python = ">=3.10"
 description = "Pure-Python Linux system-admin helpers — the importable core behind runspec-linux (no runspec dependency, no runnables)"
 dependencies = []

{runspec_linux_core-0.3.1 → runspec_linux_core-0.3.3}/runspec_linux_core/__init__.py

@@ -9,6 +9,7 @@ Each function does the work and returns plain data; failures raise (see
 ``runspec_linux_core.errors``).
 """
 
+from runspec_linux_core.commands import which
 from runspec_linux_core.containers import (
     container_logs,
     list_containers,
@@ -32,6 +33,7 @@ from runspec_linux_core.security import last_logins, who
 from runspec_linux_core.services import check_service, list_services, restart_service
 from runspec_linux_core.sudoers import enable_passwordless_sudo
 from runspec_linux_core.system import check_memory, disk_usage, list_processes, system_info
+from runspec_linux_core.venvs import configure_pip, create_venv, install_into_venv
 
 __all__ = [
     # errors
@@ -76,6 +78,12 @@ __all__ = [
     "reboot_host",
     # sudoers
     "enable_passwordless_sudo",
+    # venvs
+    "create_venv",
+    "install_into_venv",
+    "configure_pip",
     # tcp
     "nc_send",
+    # commands
+    "which",
 ]

runspec_linux_core-0.3.3/runspec_linux_core/commands.py

@@ -0,0 +1,76 @@
+"""Command-location helpers — find executables on the search PATH."""
+
+import os
+
+
+def _is_executable(path: str) -> bool:
+    return os.path.isfile(path) and os.access(path, os.X_OK)
+
+
+def _resolve(name: str, dirs: list[str]) -> list[str]:
+    """Return every executable match for ``name`` across ``dirs`` (in order)."""
+    # A name with a path separator is a path, not a bare command: check it
+    # directly rather than searching the PATH (mirrors `which`/`shutil.which`).
+    if os.sep in name or (os.altsep and os.altsep in name):
+        return [os.path.abspath(name)] if _is_executable(name) else []
+    seen: set[str] = set()
+    matches: list[str] = []
+    for d in dirs:
+        full = os.path.join(d, name)
+        if full in seen:
+            continue
+        seen.add(full)
+        if _is_executable(full):
+            matches.append(full)
+    return matches
+
+
+def which(
+    names: str | list[str],
+    *,
+    all_matches: bool = False,
+    path: str | None = None,
+) -> dict:
+    """Locate executables on the search PATH, like the ``which`` command.
+
+    ``names`` is a single command name or a list of them; a string is split on
+    whitespace so ``"python3 pip3"`` resolves both. ``all_matches`` returns every
+    match found across the PATH (not just the first one that would run). ``path``
+    overrides the search path (defaults to ``$PATH``, falling back to
+    ``os.defpath``).
+
+    Returns::
+
+        {"path": "<search path used>",
+         "all_found": bool,                       # every requested name resolved
+         "results": [{"name": str, "found": bool,
+                      "path": str | None,         # first match, else None
+                      "paths": [str, ...]}]}      # all matches if all_matches
+
+    Raises ``ValueError`` when no name is given.
+    """
+    if isinstance(names, str):
+        names = names.split()
+    names = [n for n in names if n]
+    if not names:
+        raise ValueError("no command name given")
+
+    search = os.environ.get("PATH", os.defpath) if path is None else path
+    dirs = [d or os.curdir for d in search.split(os.pathsep)]
+
+    results = []
+    for name in names:
+        matches = _resolve(name, dirs)
+        results.append(
+            {
+                "name": name,
+                "found": bool(matches),
+                "path": matches[0] if matches else None,
+                "paths": matches if all_matches else matches[:1],
+            }
+        )
+    return {
+        "path": search,
+        "all_found": all(r["found"] for r in results),
+        "results": results,
+    }

runspec_linux_core-0.3.3/runspec_linux_core/venvs.py

@@ -0,0 +1,299 @@
+"""Python virtualenv management: create venvs, install into them, write pip.conf.
+
+All three helpers operate in user space (no root): a venv, a pip install into it,
+and a ``pip.conf`` under a home or a venv. The driving use case is a **service
+account that owns a venv shared between several consoles**, so each helper takes an
+optional ``run_as`` user and escalates *internally* — ``sudo -n -u <user>`` (or
+``su``) wrapping every command — rather than the console's declarative ``run_as``
+(the account is chosen per-invocation, not fixed in ``runspec.toml``). ``-n`` makes
+sudo fail fast instead of hanging on the TTY-less SSH channel; passwordless sudo is
+assumed (see ``enable-passwordless-sudo``).
+
+Each function returns plain data and raises on failure (``CommandError`` for a
+non-zero subprocess, ``ValueError`` for bad input). The thin ``runspec-linux``
+wrappers render the JSON/exit.
+"""
+
+import configparser
+import contextlib
+import io
+import os
+import pwd
+import re
+import shlex
+import shutil
+import subprocess
+import tempfile
+
+from runspec_linux_core.errors import CommandError
+
+# Mirrors sudoers._USER_RE: a POSIX-ish user/group name. Validated before it is
+# interpolated into a become command or a chgrp, so a crafted value can't inject
+# extra tokens (everything still goes to argv, never a shell, but this keeps the
+# error early and clear).
+_NAME_RE = re.compile(r"^[a-z_][a-z0-9_.-]*\$?$")
+
+_BECOME_METHODS = ("sudo", "su")
+
+
+def _tail(output: str, limit: int = 40) -> list[str]:
+    """The last ``limit`` non-empty-trimmed lines, so payloads stay bounded."""
+    return output.strip().splitlines()[-limit:]
+
+
+def _validate_name(value: str, what: str) -> str:
+    if not _NAME_RE.match(value):
+        raise ValueError(f"invalid {what}: {value!r}")
+    return value
+
+
+def _become(argv: list[str], run_as: str | None, method: str = "sudo") -> list[str]:
+    """Wrap ``argv`` so it runs as ``run_as`` via ``method`` (no escalation if empty).
+
+    ``sudo`` → ``sudo -n -u <user> <argv...>`` (``-n`` never prompts).
+    ``su``   → ``su <user> -c "<argv joined+quoted>"`` (su has no ``-n``; it only
+    works without a password when the caller is already root).
+    """
+    if not run_as:
+        return argv
+    _validate_name(run_as, "run-as user")
+    if method not in _BECOME_METHODS:
+        raise ValueError(f"invalid become-method: {method!r} (expected sudo or su)")
+    if method == "su":
+        return ["su", run_as, "-c", shlex.join(argv)]
+    return ["sudo", "-n", "-u", run_as, *argv]
+
+
+def _run(argv: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(argv, capture_output=True, text=True)
+
+
+def _check(result: subprocess.CompletedProcess[str], what: str, run_as: str | None) -> None:
+    """Raise CommandError on non-zero, with a passwordless-sudo hint when relevant."""
+    if result.returncode == 0:
+        return
+    err = result.stderr.strip()
+    if run_as and ("password is required" in err.lower() or "a terminal is required" in err.lower()):
+        raise CommandError(f"{what}: passwordless sudo is not configured for run-as {run_as!r} ({err})")
+    raise CommandError(err or f"{what} failed")
+
+
+def create_venv(
+    python: str,
+    dest: str,
+    *,
+    run_as: str | None = None,
+    become_method: str = "sudo",
+    group: str | None = None,
+    system_site_packages: bool = False,
+    upgrade_deps: bool = False,
+    clear: bool = False,
+    prompt: str | None = None,
+) -> dict:
+    """Create a virtualenv at ``dest`` from a specific ``python`` interpreter.
+
+    Always uses ``--symlinks``. Then creates ``<dest>/logs`` mode ``2775`` (setgid,
+    so new audit-log files inherit the directory's group) and, if ``group`` is set,
+    ``chgrp -R`` the venv to it — enabling a shared service-account venv that several
+    consoles read/write. With ``run_as`` set every step runs as that user (so the
+    venv is owned by it). Raises ValueError on a non-executable interpreter / bad
+    name, or CommandError on a failed step.
+    """
+    if not (os.path.isfile(python) and os.access(python, os.X_OK)):
+        raise ValueError(f"not an executable file: {python!r} (pick a real interpreter, not the system default)")
+
+    flags: list[str] = ["--symlinks"]
+    if system_site_packages:
+        flags.append("--system-site-packages")
+    if upgrade_deps:
+        flags.append("--upgrade-deps")
+    if clear:
+        flags.append("--clear")
+    if prompt:
+        flags += ["--prompt", prompt]
+
+    _check(_run(_become([python, "-m", "venv", *flags, dest], run_as, become_method)), "venv creation", run_as)
+
+    logs_dir = os.path.join(dest, "logs")
+    _check(_run(_become(["mkdir", "-p", logs_dir], run_as, become_method)), "logs dir", run_as)
+    if group:
+        _validate_name(group, "group")
+        _check(_run(_become(["chgrp", "-R", group, dest], run_as, become_method)), "chgrp", run_as)
+    _check(_run(_become(["chmod", "2775", logs_dir], run_as, become_method)), "chmod logs", run_as)
+
+    return {
+        "python": python,
+        "dest": dest,
+        "run_as": run_as or "",
+        "group": group or "",
+        "logs_dir": logs_dir,
+        "created": True,
+    }
+
+
+def install_into_venv(
+    venv: str,
+    packages: str = "",
+    *,
+    project: str | None = None,
+    editable: bool = False,
+    upgrade: bool = False,
+    no_cache_dir: bool = False,
+    force_reinstall: bool = False,
+    run_as: str | None = None,
+    become_method: str = "sudo",
+) -> dict:
+    """Install named packages and/or a local project into an existing venv's pip.
+
+    Targets ``<venv>/bin/python -m pip install``. ``packages`` is space-separated
+    named specs (validated against the shared package-token guard); ``project`` is a
+    path to a directory with a ``pyproject.toml`` (or a wheel/sdist), installed
+    editable when ``editable`` is set. At least one of ``packages``/``project`` is
+    required. Raises ValueError on bad input, CommandError on a failed install.
+    """
+    from runspec_linux_core.packages import _validate_packages
+
+    venv_python = os.path.join(venv, "bin", "python")
+    if not (os.path.isfile(venv_python) and os.access(venv_python, os.X_OK)):
+        raise ValueError(f"no python in venv: {venv_python!r}")
+
+    names = _validate_packages(packages) if packages.strip() else []
+    if project is not None and (project.startswith("-") or not os.path.exists(project)):
+        raise ValueError(f"project path not found: {project!r}")
+    if editable and project is None:
+        raise ValueError("--editable requires a project path")
+    if not names and project is None:
+        raise ValueError("nothing to install: give a package and/or a project")
+
+    opts: list[str] = []
+    if upgrade:
+        opts.append("-U")
+    if no_cache_dir:
+        opts.append("--no-cache-dir")
+    if force_reinstall:
+        opts.append("--force-reinstall")
+
+    target: list[str] = list(names)
+    if project is not None:
+        target += ["-e", project] if editable else [project]
+
+    cmd = _become([venv_python, "-m", "pip", "install", *opts, *target], run_as, become_method)
+    result = _run(cmd)
+    _check(result, "pip install", run_as)
+    return {
+        "venv": venv,
+        "packages": names,
+        "project": project or "",
+        "editable": editable,
+        "installed": True,
+        "output": _tail(result.stdout),
+    }
+
+
+def configure_pip(
+    index_url: str,
+    *,
+    extra_index_url: str | None = None,
+    trusted_host: str | None = None,
+    cert: str | None = None,
+    timeout: int | None = None,
+    retries: int | None = None,
+    proxy: str | None = None,
+    require_virtualenv: bool = False,
+    scope: str = "user",
+    venv: str | None = None,
+    run_as: str | None = None,
+    become_method: str = "sudo",
+) -> dict:
+    """Write a ``pip.conf`` at user or venv scope for private-PyPI access.
+
+    Builds a ``[global]`` section from the given settings (``index-url`` is the only
+    required one) and, when ``require_virtualenv`` is set, also pins
+    ``require-virtualenv`` + ``disable-pip-version-check``. The file is validated by
+    re-parsing before it is installed. ``scope="user"`` targets
+    ``<home>/.config/pip/pip.conf`` (the ``run_as`` user's home when escalating, else
+    the caller's); ``scope="venv"`` targets ``<venv>/pip.conf`` and requires ``venv``.
+    With ``run_as`` the file is installed via ``install -D -m 0644`` as that user (so
+    it is owned by it); otherwise it is written atomically with a ``.bak`` of any
+    existing file. Raises ValueError on bad input, CommandError on a failed step.
+    """
+    if scope not in ("user", "venv"):
+        raise ValueError(f"invalid scope: {scope!r} (expected user or venv)")
+    if scope == "venv":
+        if not venv:
+            raise ValueError("scope=venv requires a venv path")
+        path = os.path.join(venv, "pip.conf")
+    else:
+        if run_as:
+            _validate_name(run_as, "run-as user")
+            home = pwd.getpwnam(run_as).pw_dir
+        else:
+            home = os.path.expanduser("~")
+        path = os.path.join(home, ".config", "pip", "pip.conf")
+
+    cfg = configparser.ConfigParser()
+    section: dict[str, str] = {"index-url": index_url}
+    if extra_index_url:
+        section["extra-index-url"] = extra_index_url
+    if trusted_host:
+        section["trusted-host"] = trusted_host
+    if cert:
+        section["cert"] = cert
+    if timeout is not None:
+        section["timeout"] = str(timeout)
+    if retries is not None:
+        section["retries"] = str(retries)
+    if proxy:
+        section["proxy"] = proxy
+    if require_virtualenv:
+        section["require-virtualenv"] = "true"
+        section["disable-pip-version-check"] = "true"
+    cfg["global"] = section
+
+    buf = io.StringIO()
+    cfg.write(buf)
+    content = buf.getvalue()
+
+    # Validate it re-parses before we install it anywhere.
+    check = configparser.ConfigParser()
+    check.read_string(content)
+
+    # Write to a temp file the run-as user can read (0644 — pip.conf is non-secret),
+    # then install it atomically into place as that user (creating parent dirs).
+    fd, tmp = tempfile.mkstemp(prefix="pip.conf.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as fh:
+            fh.write(content)
+        os.chmod(tmp, 0o644)
+        if run_as:
+            if _path_exists_as(path, run_as, become_method):
+                _check(
+                    _run(_become(["cp", path, f"{path}.bak"], run_as, become_method)),
+                    "backup pip.conf",
+                    run_as,
+                )
+            _check(
+                _run(_become(["install", "-D", "-m", "0644", tmp, path], run_as, become_method)),
+                "install pip.conf",
+                run_as,
+            )
+        else:
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            if os.path.exists(path):
+                shutil.copy2(path, f"{path}.bak")
+            shutil.copy2(tmp, path)
+    finally:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+
+    return {
+        "path": path,
+        "scope": scope,
+        "run_as": run_as or "",
+        "configured": True,
+    }
+
+
+def _path_exists_as(path: str, run_as: str | None, become_method: str) -> bool:
+    """True if ``path`` exists from the run-as user's view (``test -e``)."""
+    return _run(_become(["test", "-e", path], run_as, become_method)).returncode == 0

runspec_linux_core-0.3.3/tests/test_commands.py

@@ -0,0 +1,88 @@
+import os
+import stat
+
+import pytest
+
+from runspec_linux_core import which
+
+
+def _make_exec(path):
+    path.write_text("#!/bin/sh\n")
+    path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+
+def test_which_finds_executable(tmp_path):
+    binp = tmp_path / "mytool"
+    _make_exec(binp)
+    res = which("mytool", path=str(tmp_path))
+    assert res["all_found"] is True
+    assert res["path"] == str(tmp_path)
+    (r,) = res["results"]
+    assert r == {
+        "name": "mytool",
+        "found": True,
+        "path": str(binp),
+        "paths": [str(binp)],
+    }
+
+
+def test_which_not_found(tmp_path):
+    res = which("nope", path=str(tmp_path))
+    assert res["all_found"] is False
+    assert res["results"][0] == {
+        "name": "nope",
+        "found": False,
+        "path": None,
+        "paths": [],
+    }
+
+
+def test_which_skips_non_executable(tmp_path):
+    (tmp_path / "plain").write_text("data")
+    res = which("plain", path=str(tmp_path))
+    assert res["results"][0]["found"] is False
+
+
+def test_which_multiple_names_space_separated(tmp_path):
+    _make_exec(tmp_path / "a")
+    res = which("a b", path=str(tmp_path))
+    assert [r["name"] for r in res["results"]] == ["a", "b"]
+    assert res["results"][0]["found"] is True
+    assert res["results"][1]["found"] is False
+    assert res["all_found"] is False
+
+
+def test_which_accepts_list(tmp_path):
+    _make_exec(tmp_path / "a")
+    res = which(["a"], path=str(tmp_path))
+    assert res["all_found"] is True
+
+
+def test_which_first_match_wins_all_matches_lists_every_dir(tmp_path):
+    d1 = tmp_path / "d1"
+    d2 = tmp_path / "d2"
+    d1.mkdir()
+    d2.mkdir()
+    _make_exec(d1 / "dup")
+    _make_exec(d2 / "dup")
+    search = os.pathsep.join([str(d1), str(d2)])
+
+    first = which("dup", path=search)
+    assert first["results"][0]["path"] == str(d1 / "dup")
+    assert first["results"][0]["paths"] == [str(d1 / "dup")]
+
+    allm = which("dup", all_matches=True, path=search)
+    assert allm["results"][0]["paths"] == [str(d1 / "dup"), str(d2 / "dup")]
+
+
+def test_which_name_with_path_separator_checked_directly(tmp_path):
+    binp = tmp_path / "tool"
+    _make_exec(binp)
+    res = which(str(binp))
+    assert res["results"][0]["found"] is True
+    assert res["results"][0]["path"] == str(binp)
+
+
+def test_which_empty_raises():
+    with pytest.raises(ValueError):
+        which("   ")

runspec_linux_core-0.3.3/tests/test_venvs.py

@@ -0,0 +1,249 @@
+"""venv creation, install-into-venv, and pip.conf writing.
+
+The subprocess layer (``_run``) is stubbed so no real venv/pip is touched; the
+tests assert on the argv that *would* run (escalation prefix, flags, ordering)
+and on the input validation that happens before any subprocess.
+"""
+
+import configparser
+import os
+import subprocess
+
+import pytest
+
+from runspec_linux_core import venvs
+from runspec_linux_core.errors import CommandError
+
+
+def _completed(stdout: str = "", returncode: int = 0, stderr: str = "") -> subprocess.CompletedProcess:
+    return subprocess.CompletedProcess(args=[], returncode=returncode, stdout=stdout, stderr=stderr)
+
+
+def _record(monkeypatch: pytest.MonkeyPatch) -> list[list[str]]:
+    """Stub ``venvs._run`` to record every argv and always succeed."""
+    calls: list[list[str]] = []
+
+    def fake_run(argv: list[str]) -> subprocess.CompletedProcess:
+        calls.append(argv)
+        return _completed("Successfully installed foo\n")
+
+    monkeypatch.setattr(venvs, "_run", fake_run)
+    return calls
+
+
+# ── _become ───────────────────────────────────────────────────────────────────
+
+
+def test_become_no_user_is_noop() -> None:
+    assert venvs._become(["echo", "hi"], None) == ["echo", "hi"]
+    assert venvs._become(["echo", "hi"], "") == ["echo", "hi"]
+
+
+def test_become_sudo_prefix() -> None:
+    assert venvs._become(["echo", "hi"], "svc") == ["sudo", "-n", "-u", "svc", "echo", "hi"]
+
+
+def test_become_su_quotes() -> None:
+    assert venvs._become(["pip", "install", "a b"], "svc", "su") == ["su", "svc", "-c", "pip install 'a b'"]
+
+
+def test_become_rejects_bad_user() -> None:
+    with pytest.raises(ValueError):
+        venvs._become(["echo"], "bad;user")
+
+
+def test_become_rejects_bad_method() -> None:
+    with pytest.raises(ValueError):
+        venvs._become(["echo"], "svc", "doas")
+
+
+# ── create_venv ───────────────────────────────────────────────────────────────
+
+
+def test_create_venv_uses_symlinks_and_logs(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _record(monkeypatch)
+    import sys
+
+    result = venvs.create_venv(sys.executable, "/opt/v1")
+
+    venv_cmd = calls[0]
+    assert venv_cmd[:4] == [sys.executable, "-m", "venv", "--symlinks"]
+    assert venv_cmd[-1] == "/opt/v1"
+    # mkdir -p logs, then chmod 2775 logs (no group → no chgrp step).
+    assert calls[1] == ["mkdir", "-p", "/opt/v1/logs"]
+    assert calls[2] == ["chmod", "2775", "/opt/v1/logs"]
+    assert result == {
+        "python": sys.executable,
+        "dest": "/opt/v1",
+        "run_as": "",
+        "group": "",
+        "logs_dir": "/opt/v1/logs",
+        "created": True,
+    }
+
+
+def test_create_venv_only_sets_chosen_flags(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _record(monkeypatch)
+    import sys
+
+    venvs.create_venv(sys.executable, "/opt/v1", system_site_packages=True, clear=True)
+    venv_cmd = calls[0]
+    assert "--system-site-packages" in venv_cmd
+    assert "--clear" in venv_cmd
+    assert "--upgrade-deps" not in venv_cmd
+
+
+def test_create_venv_run_as_escalates_every_step(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _record(monkeypatch)
+    import sys
+
+    venvs.create_venv(sys.executable, "/opt/v1", run_as="svc", group="consoles")
+    for cmd in calls:
+        assert cmd[:4] == ["sudo", "-n", "-u", "svc"]
+    # chgrp -R consoles /opt/v1 runs between mkdir and chmod.
+    assert ["sudo", "-n", "-u", "svc", "chgrp", "-R", "consoles", "/opt/v1"] in calls
+
+
+def test_create_venv_rejects_non_executable(monkeypatch: pytest.MonkeyPatch) -> None:
+    _record(monkeypatch)
+    with pytest.raises(ValueError):
+        venvs.create_venv("/no/such/python", "/opt/v1")
+
+
+def test_create_venv_raises_on_failure(monkeypatch: pytest.MonkeyPatch) -> None:
+    import sys
+
+    monkeypatch.setattr(venvs, "_run", lambda argv: _completed("", returncode=1, stderr="boom"))
+    with pytest.raises(CommandError):
+        venvs.create_venv(sys.executable, "/opt/v1")
+
+
+# ── install_into_venv ─────────────────────────────────────────────────────────
+
+
+def _fake_venv(tmp_path, monkeypatch: pytest.MonkeyPatch) -> str:
+    """A venv dir whose bin/python passes the executable check."""
+    import sys
+
+    venv = tmp_path / "venv"
+    (venv / "bin").mkdir(parents=True)
+    py = venv / "bin" / "python"
+    os.symlink(sys.executable, py)
+    return str(venv)
+
+
+def test_install_into_venv_builds_pip_argv(tmp_path, monkeypatch: pytest.MonkeyPatch) -> None:
+    venv = _fake_venv(tmp_path, monkeypatch)
+    calls = _record(monkeypatch)
+
+    result = venvs.install_into_venv(venv, "httpx rich", upgrade=True)
+    cmd = calls[0]
+    assert cmd[:4] == [f"{venv}/bin/python", "-m", "pip", "install"]
+    assert "-U" in cmd
+    assert cmd[-2:] == ["httpx", "rich"]
+    assert result["installed"] is True
+    assert result["output"] == ["Successfully installed foo"]
+
+
+def test_install_into_venv_editable_project(tmp_path, monkeypatch: pytest.MonkeyPatch) -> None:
+    venv = _fake_venv(tmp_path, monkeypatch)
+    proj = tmp_path / "proj"
+    proj.mkdir()
+    calls = _record(monkeypatch)
+
+    venvs.install_into_venv(venv, project=str(proj), editable=True, run_as="svc")
+    cmd = calls[0]
+    assert cmd[:4] == ["sudo", "-n", "-u", "svc"]
+    assert cmd[-2:] == ["-e", str(proj)]
+
+
+def test_install_into_venv_requires_a_target(tmp_path, monkeypatch: pytest.MonkeyPatch) -> None:
+    venv = _fake_venv(tmp_path, monkeypatch)
+    _record(monkeypatch)
+    with pytest.raises(ValueError):
+        venvs.install_into_venv(venv)
+
+
+def test_install_into_venv_editable_needs_project(tmp_path, monkeypatch: pytest.MonkeyPatch) -> None:
+    venv = _fake_venv(tmp_path, monkeypatch)
+    _record(monkeypatch)
+    with pytest.raises(ValueError):
+        venvs.install_into_venv(venv, "httpx", editable=True)
+
+
+def test_install_into_venv_rejects_missing_venv(tmp_path, monkeypatch: pytest.MonkeyPatch) -> None:
+    _record(monkeypatch)
+    with pytest.raises(ValueError):
+        venvs.install_into_venv(str(tmp_path / "nope"), "httpx")
+
+
+def test_install_into_venv_rejects_injection(tmp_path, monkeypatch: pytest.MonkeyPatch) -> None:
+    venv = _fake_venv(tmp_path, monkeypatch)
+    _record(monkeypatch)
+    with pytest.raises(ValueError):
+        venvs.install_into_venv(venv, "httpx; rm -rf /")
+
+
+# ── configure_pip ─────────────────────────────────────────────────────────────
+
+
+def test_configure_pip_user_scope_writes_ini(tmp_path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(os.path, "expanduser", lambda p: str(tmp_path) if p == "~" else p)
+    result = venvs.configure_pip(
+        "https://nexus/repository/pypi/simple",
+        trusted_host="nexus",
+        timeout=60,
+        retries=5,
+        require_virtualenv=True,
+    )
+    path = result["path"]
+    assert path == str(tmp_path / ".config" / "pip" / "pip.conf")
+
+    cfg = configparser.ConfigParser()
+    cfg.read(path)
+    assert cfg["global"]["index-url"] == "https://nexus/repository/pypi/simple"
+    assert cfg["global"]["trusted-host"] == "nexus"
+    assert cfg["global"]["timeout"] == "60"
+    assert cfg["global"]["retries"] == "5"
+    assert cfg["global"]["require-virtualenv"] == "true"
+    assert cfg["global"]["disable-pip-version-check"] == "true"
+
+
+def test_configure_pip_venv_scope(tmp_path, monkeypatch: pytest.MonkeyPatch) -> None:
+    venv = tmp_path / "venv"
+    venv.mkdir()
+    result = venvs.configure_pip("https://nexus/simple", scope="venv", venv=str(venv))
+    assert result["path"] == str(venv / "pip.conf")
+    cfg = configparser.ConfigParser()
+    cfg.read(result["path"])
+    assert cfg["global"]["index-url"] == "https://nexus/simple"
+
+
+def test_configure_pip_venv_scope_requires_venv() -> None:
+    with pytest.raises(ValueError):
+        venvs.configure_pip("https://nexus/simple", scope="venv")
+
+
+def test_configure_pip_bad_scope() -> None:
+    with pytest.raises(ValueError):
+        venvs.configure_pip("https://nexus/simple", scope="global")
+
+
+def test_configure_pip_run_as_installs_via_become(tmp_path, monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = _record(monkeypatch)
+    # run_as path resolves the user's home via pwd; stub it to tmp_path.
+    monkeypatch.setattr(
+        venvs.pwd,
+        "getpwnam",
+        lambda u: type("PW", (), {"pw_dir": str(tmp_path)})(),
+    )
+    result = venvs.configure_pip("https://nexus/simple", run_as="svc")
+    target = str(tmp_path / ".config" / "pip" / "pip.conf")
+    assert result["path"] == target
+    # An install -D -m 0644 <tmp> <target> ran as svc.
+    install_cmds = [c for c in calls if "install" in c and "-D" in c]
+    assert install_cmds, calls
+    cmd = install_cmds[0]
+    assert cmd[:4] == ["sudo", "-n", "-u", "svc"]
+    assert cmd[4:7] == ["install", "-D", "-m"]
+    assert cmd[-1] == target