offbox 0.1.0__py3-none-any.whl

offbox/sync.py

@@ -0,0 +1,380 @@
+import csv
+import io
+import logging
+import subprocess
+from collections.abc import Callable
+from datetime import datetime
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, ValidationError
+
+from offbox import console
+from offbox.config import Model, SyncConfig
+from offbox.errors import CommandFailed, PreconditionError
+from offbox.naming import Worktree, validate_env_name
+from offbox.paths import Paths
+from offbox.providers import validate_name
+from offbox.runner import Result, Runner
+from offbox.state import HostState
+from offbox.timings import measured
+from offbox.tools import MUTAGEN_FIX, MutagenMissing, cached_mutagen, download_prompt, install_mutagen
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_IGNORES = (
+    "node_modules",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "*.pyc",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    "dist",
+    "build",
+    ".next",
+    ".nuxt",
+    "target",
+    ".terraform",
+    ".DS_Store",
+    ".git",
+)
+SyncState = Literal[
+    "disconnected",
+    "halted-on-root-emptied",
+    "halted-on-root-deletion",
+    "halted-on-root-type-change",
+    "connecting-alpha",
+    "connecting-beta",
+    "watching",
+    "scanning",
+    "waiting-for-rescan",
+    "reconciling",
+    "staging-alpha",
+    "staging-beta",
+    "transitioning",
+    "saving",
+    "unknown",
+]
+
+
+class MutagenModel(BaseModel):
+    model_config = ConfigDict(extra="ignore", populate_by_name=True, hide_input_in_errors=True)
+
+
+class IgnoreConfig(MutagenModel):
+    paths: list[str] = Field(default_factory=list[str])
+    vcs: bool | None = None
+
+
+class Permissions(MutagenModel):
+    file_mode: str | None = Field(default=None, alias="defaultFileMode")
+    directory_mode: str | None = Field(default=None, alias="defaultDirectoryMode")
+
+
+class SyncProblem(MutagenModel):
+    path: str
+    error: str
+
+
+class Conflict(MutagenModel):
+    root: str
+
+
+class Endpoint(MutagenModel):
+    protocol: Literal["local", "ssh", "docker"]
+    path: str
+    host: str | None = None
+    user: str | None = None
+    port: int | None = None
+    environment: dict[str, str] = Field(default_factory=dict[str, str])
+    parameters: dict[str, str] = Field(default_factory=dict[str, str])
+    connected: bool
+    permissions: Permissions = Field(default_factory=Permissions)
+    scan_problems: list[SyncProblem] = Field(default_factory=list[SyncProblem], alias="scanProblems")
+    transition_problems: list[SyncProblem] = Field(default_factory=list[SyncProblem], alias="transitionProblems")
+    excluded_scan_problems: int = Field(default=0, ge=0, alias="excludedScanProblems")
+    excluded_transition_problems: int = Field(default=0, ge=0, alias="excludedTransitionProblems")
+
+    @property
+    def problem_count(self) -> int:
+        return len(self.scan_problems) + len(self.transition_problems) + self.excluded_scan_problems + self.excluded_transition_problems
+
+
+class SyncSession(MutagenModel):
+    identifier: str = Field(pattern=r"^[A-Za-z0-9_-]+$")
+    version: Literal[1]
+    creation_time: datetime = Field(alias="creationTime")
+    creating_version: str = Field(alias="creatingVersion")
+    name: str = ""
+    labels: dict[str, str] = Field(default_factory=dict[str, str])
+    alpha: Endpoint
+    beta: Endpoint
+    paused: bool
+    status: SyncState
+    mode: str | None = None
+    ignore: IgnoreConfig = Field(default_factory=IgnoreConfig)
+    conflicts: list[Conflict] = Field(default_factory=list[Conflict])
+    excluded_conflicts: int = Field(default=0, ge=0, alias="excludedConflicts")
+    last_error: str | None = Field(default=None, alias="lastError")
+
+
+class SyncHealth(Model):
+    state: SyncState
+    paused: bool
+    conflicts: int
+    problems: int
+    last_error: str | None = None
+    ok: bool
+    fix: str | None = None
+
+
+def health(session: SyncSession) -> SyncHealth:
+    conflicts = len(session.conflicts) + session.excluded_conflicts
+    problems = session.alpha.problem_count + session.beta.problem_count
+    fix: str | None = None
+    if session.paused:
+        fix = "Run offbox up to resume source sync."
+    elif conflicts:
+        paths = ", ".join(conflict.root or "<root>" for conflict in session.conflicts) or "excluded paths"
+        fix = f"Resolve sync conflicts locally ({paths}), then run mutagen sync reset {session.identifier} and offbox up."
+    elif session.status.startswith("halted-on-root-"):
+        fix = f"Restore the worktree root, then run mutagen sync reset {session.identifier} and offbox up."
+    elif session.status == "unknown":
+        fix = "Check the Mutagen daemon and install a supported Mutagen 0.18.x version, then run offbox up."
+    elif problems:
+        details = [
+            problem for endpoint in (session.alpha, session.beta) for problem in (*endpoint.scan_problems, *endpoint.transition_problems)
+        ]
+        paths = ", ".join(problem.path or "<root>" for problem in details) or "excluded paths"
+        fix = f"Correct sync access problems ({paths}) and run offbox up."
+    elif session.last_error or not session.alpha.connected or not session.beta.connected:
+        fix = "Check host connectivity with offbox host ssh, then run offbox up."
+    return SyncHealth(
+        state=session.status,
+        paused=session.paused,
+        conflicts=conflicts,
+        problems=problems,
+        last_error=session.last_error,
+        ok=fix is None,
+        fix=fix,
+    )
+
+
+def ignores(config: SyncConfig) -> list[str]:
+    if any(not pattern or any(character in pattern for character in "\x00\r\n") for pattern in config.ignore):
+        raise PreconditionError("Invalid sync ignore pattern", "Set sync.ignore to nonempty, single-line patterns without NUL characters.")
+    return [*(pattern for pattern in (*DEFAULT_IGNORES, *config.ignore) if pattern != ".git"), ".git"]
+
+
+def _csv_pattern(pattern: str) -> str:
+    output = io.StringIO()
+    csv.writer(output, lineterminator="\n").writerow([pattern])
+    return output.getvalue()[:-1]
+
+
+def create_command(work: Worktree, host: HostState, config: SyncConfig) -> list[str]:
+    argv = [
+        "mutagen",
+        "sync",
+        "create",
+        "--no-global-configuration",
+        "--name",
+        f"offbox-{work.name}",
+        "--label",
+        f"offbox-env={work.name}",
+        "--mode",
+        "two-way-safe",
+        "--ignore-vcs",
+        "--default-file-mode-beta=0644",
+        "--default-directory-mode-beta=0755",
+    ]
+    for pattern in ignores(config):
+        argv.extend(["--ignore", _csv_pattern(pattern)])
+    return [*argv, str(work.root), f"offbox-{host.name}:{work.work}"]
+
+
+class SyncManager:
+    def __init__(self, runner: Runner, *, cache: Path | None = None, offer: Callable[[str], bool] | None = None) -> None:
+        self.runner = runner
+        self.cache = cache
+        self.offer = offer
+        self.executable = "mutagen"
+
+    def _locate(self, install: bool) -> str:
+        cache = self.cache or Paths.discover().cache
+        cached = cached_mutagen(cache)
+        if cached is not None:
+            return str(cached)
+        offer = self.offer or (console.confirm if console.interactive() else None)
+        if install and offer is not None and offer(download_prompt(cache)):
+            return str(install_mutagen(cache))
+        raise MutagenMissing("Mutagen is not installed", MUTAGEN_FIX)
+
+    def _run(self, argv: list[str], *, timeout: float = 30, install: bool = True) -> Result:
+        command = [self.executable, *argv[1:]]
+        try:
+            result = self.runner.run(command, check=False, timeout=timeout)
+        except PreconditionError as exc:
+            if isinstance(exc.__cause__, FileNotFoundError) and self.executable == "mutagen":
+                self.executable = self._locate(install)
+                return self._run(argv, timeout=timeout, install=install)
+            if isinstance(exc.__cause__, subprocess.TimeoutExpired):
+                raise PreconditionError("Source sync timed out", "Check sync conflicts and host connectivity, then run offbox up.") from exc
+            raise
+        if result.returncode:
+            failure = CommandFailed(command, result.returncode, result.stderr)
+            failure.fix = "Check the Mutagen daemon and SSH connectivity, then run offbox up."
+            raise failure
+        return result
+
+    def status(self, work: Worktree, host: HostState | None = None, *, install: bool = True) -> SyncSession | None:
+        result = self._run(
+            ["mutagen", "sync", "list", "--label-selector", f"offbox-env={work.name}", "--template", "{{ json . }}"], install=install
+        )
+        try:
+            sessions = TypeAdapter(list[SyncSession]).validate_json(result.stdout)
+        except ValidationError as exc:
+            raise PreconditionError("Invalid Mutagen session response", "Install Mutagen 0.18.x and inspect the sync daemon.") from exc
+        if not sessions:
+            return None
+        if len(sessions) != 1:
+            raise PreconditionError(
+                f"Several sync sessions claim {work.name}", "Inspect mutagen sync list and remove duplicate managed sessions."
+            )
+        session = sessions[0]
+        if (
+            session.name != f"offbox-{work.name}"
+            or session.labels.get("offbox-env") != work.name
+            or session.alpha.user
+            or session.alpha.host
+            or session.alpha.port
+            or session.alpha.environment
+            or session.alpha.parameters
+            or session.beta.user
+            or session.beta.port
+            or session.beta.environment
+            or session.beta.parameters
+            or session.alpha.protocol != "local"
+            or Path(session.alpha.path) != work.root
+            or session.beta.protocol != "ssh"
+            or session.beta.path != work.work
+            or (host is not None and session.beta.host != f"offbox-{host.name}")
+        ):
+            raise PreconditionError(
+                "Sync session has conflicting ownership or endpoints", "Inspect mutagen sync list before changing this environment."
+            )
+        return session
+
+    @measured("Sync setup")
+    def ensure(self, work: Worktree, host: HostState, config: SyncConfig) -> None:
+        session = self.status(work, host)
+        if session is None:
+            self._run(create_command(work, host, config))
+            return
+        if (
+            session.mode != "two-way-safe"
+            or session.ignore.vcs is not True
+            or session.ignore.paths != ignores(config)
+            or session.beta.permissions.file_mode != "0644"
+            or session.beta.permissions.directory_mode != "0755"
+        ):
+            raise PreconditionError(
+                "Sync configuration changed",
+                f"Run mutagen sync terminate {session.identifier}, then offbox up to apply the new configuration.",
+            )
+        if session.paused:
+            self._run(["mutagen", "sync", "resume", session.identifier])
+
+    @measured("Sync flush")
+    def flush(self, work: Worktree, host: HostState | None = None) -> None:
+        try:
+            self._run(["mutagen", "sync", "flush", "--label-selector", f"offbox-env={work.name}"], timeout=120)
+        except CommandFailed:
+            logger.info("label flush failed for %s; inspecting the session", work.name, exc_info=True)
+            self._recover_and_flush(work, host)
+        current = self.status(work, host)
+        if current is None:
+            raise PreconditionError("No source sync session", "Run offbox up in this worktree.")
+        self._raise_health(current)
+
+    def _recover_and_flush(self, work: Worktree, host: HostState | None) -> None:
+        session = self.status(work, host)
+        if session is None:
+            raise PreconditionError("No source sync session", "Run offbox up in this worktree.")
+        if session.paused:
+            self._run(["mutagen", "sync", "resume", session.identifier])
+        elif (
+            session.conflicts
+            or session.excluded_conflicts
+            or session.status.startswith("halted-on-root-")
+            or session.alpha.problem_count
+            or session.beta.problem_count
+        ):
+            self._raise_health(session)
+        self._run(["mutagen", "sync", "flush", session.identifier], timeout=120)
+
+    def _raise_health(self, session: SyncSession) -> None:
+        report = health(session)
+        if not report.ok:
+            detail = session.last_error or f"{report.conflicts} conflicts, {report.problems} problems"
+            raise PreconditionError(f"Source sync is {session.status}: {detail}", report.fix)
+
+    def _cleanup(self, action: Literal["pause", "terminate"], work: Worktree, host: HostState | None) -> None:
+        try:
+            session = self.status(work, host, install=False)
+            if session is not None and (action == "terminate" or not session.paused):
+                self._run(["mutagen", "sync", action, session.identifier], install=False)
+        except MutagenMissing:
+            console.warn(f"Mutagen is not installed; continuing cleanup without sync {action}.")
+
+    @measured("Sync pause")
+    def pause(self, work: Worktree, host: HostState | None = None) -> None:
+        self._cleanup("pause", work, host)
+
+    @measured("Sync cleanup")
+    def terminate(self, work: Worktree, host: HostState | None = None) -> None:
+        self._cleanup("terminate", work, host)
+
+    def terminate_all(self) -> None:
+        try:
+            result = self._run(["mutagen", "sync", "list", "--label-selector", "offbox-env", "--template", "{{ json . }}"], install=False)
+        except MutagenMissing:
+            console.warn("Mutagen is not installed; continuing local cleanup without terminating sync sessions.")
+            return
+        try:
+            sessions = TypeAdapter(list[SyncSession]).validate_json(result.stdout)
+        except ValidationError as exc:
+            raise PreconditionError("Invalid Mutagen session response", "Check mutagen sync list and retry uninstall.") from exc
+        owned: list[SyncSession] = []
+        for session in sessions:
+            name = session.labels.get("offbox-env")
+            if name is None or session.name != f"offbox-{name}":
+                continue
+            validate_env_name(name)
+            if session.beta.host is not None and session.beta.host.startswith("offbox-"):
+                validate_name(session.beta.host[len("offbox-") :])
+            if (
+                session.alpha.protocol != "local"
+                or not Path(session.alpha.path).is_absolute()
+                or session.beta.protocol != "ssh"
+                or not (session.beta.host or "").startswith("offbox-")
+                or session.beta.path != f"/srv/offbox/envs/{name}/work"
+                or session.alpha.user
+                or session.alpha.host
+                or session.alpha.port
+                or session.alpha.environment
+                or session.alpha.parameters
+                or session.beta.user
+                or session.beta.port
+                or session.beta.environment
+                or session.beta.parameters
+            ):
+                raise PreconditionError(
+                    f"Cannot verify ownership of sync session {session.identifier}",
+                    f"Inspect mutagen sync list; terminate {session.identifier} explicitly only if it belongs to offbox.",
+                )
+            owned.append(session)
+        for session in owned:
+            self._run(["mutagen", "sync", "terminate", session.identifier])

offbox/timings.py

@@ -0,0 +1,69 @@
+from collections.abc import Callable, Generator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from functools import wraps
+from time import perf_counter
+
+from offbox import console
+
+
+@dataclass
+class _Timing:
+    seconds: float = 0
+    calls: int = 0
+
+
+@dataclass
+class _Session:
+    started: float
+    stages: dict[str, _Timing] = field(default_factory=dict[str, _Timing])
+
+
+_active: ContextVar[_Session | None] = ContextVar("offbox_timings", default=None)
+
+
+@contextmanager
+def collect(enabled: bool) -> Generator[None]:
+    if not enabled:
+        yield
+        return
+    session = _Session(started=perf_counter())
+    token = _active.set(session)
+    try:
+        yield
+    finally:
+        elapsed = perf_counter() - session.started
+        _active.reset(token)
+        console.info("Timings (CLI startup excluded):")
+        for label, value in session.stages.items():
+            calls = f" ({value.calls} calls)" if value.calls > 1 else ""
+            console.info(f"  {label}: {value.seconds:.3f}s{calls}")
+        console.info(f"  Total: {elapsed:.3f}s")
+
+
+@contextmanager
+def stage(label: str) -> Generator[None]:
+    session = _active.get()
+    if session is None:
+        yield
+        return
+    started = perf_counter()
+    try:
+        yield
+    finally:
+        value = session.stages.setdefault(label, _Timing())
+        value.seconds += perf_counter() - started
+        value.calls += 1
+
+
+def measured[**P, R](label: str) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    def decorate(function: Callable[P, R]) -> Callable[P, R]:
+        @wraps(function)
+        def call(*args: P.args, **kwargs: P.kwargs) -> R:
+            with stage(label):
+                return function(*args, **kwargs)
+
+        return call
+
+    return decorate

offbox/tools.py

@@ -0,0 +1,227 @@
+import hashlib
+import io
+import os
+import platform
+import re
+import shutil
+import tarfile
+import tempfile
+import zipfile
+from collections.abc import Callable, Mapping
+from pathlib import Path
+
+from offbox import console
+from offbox.config import Model
+from offbox.errors import PreconditionError
+from offbox.runner import Runner
+from offbox.timings import measured
+
+TOFU_VERSION = "1.10.6"
+MUTAGEN_MIN = (0, 18)
+MUTAGEN_VERSION = "0.18.1"
+MUTAGEN_FIX = "Run offbox setup to download Mutagen, or install Mutagen 0.18.x."
+TOFU_SHA256 = {
+    ("darwin", "amd64"): "85115c8ec23b48b425259060347ff932355dad48056fa83ade05f7d890dc43ed",
+    ("darwin", "arm64"): "6da8ee57f20113c302baeddc1f0c6340589fa1f7af04d41282e406cfa53c0b59",
+    ("linux", "amd64"): "15b7bed76420b50da3e121769c43341df8cd57d751ca14e6dbe9c850124c6dac",
+    ("linux", "arm64"): "a32f653d686a8cad9b9be82101eb5b5e834fbfa8d095842fa1820c5d27fad967",
+}
+MUTAGEN_SHA256 = {
+    ("darwin", "amd64"): "7d06f7d8fcfe90bc7e55cc834a2f2f20c2e0af9ea9bc35911fc4341ad56a9bbf",
+    ("darwin", "arm64"): "6f810416d9e5fc4fd5e18431146f8b3c5a2056ba5a24f76c1e66da86eb3257e2",
+    ("linux", "amd64"): "7735286c778cc438418209f24d03a64f3a0151c8065ef0fe079cfaf093af6f8f",
+    ("linux", "arm64"): "bcba735aebf8cbc11da9b3742118a665599ac697fa06bc5751cac8dcd540db8a",
+}
+_MUTAGEN_MEMBERS = ("mutagen", "mutagen-agents.tar.gz")
+_VERSION = re.compile(r"(?:OpenSSH_|(?:OpenTofu|Terraform)\s+v?|(?:git|mutagen)\s+version\s+v?)(\d+)\.(\d+)(?:\.(\d+))?", re.IGNORECASE)
+
+
+class Tool(Model):
+    name: str
+    path: Path
+    version: str
+
+
+class MutagenMissing(PreconditionError):
+    pass
+
+
+def download(url: str, timeout: float) -> bytes:
+    import urllib.request
+
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as response:
+            content: object = response.read()
+            if not isinstance(content, bytes):
+                raise PreconditionError(f"Invalid download response from {url}", "Retry, or install the tool on PATH.")
+            return content
+    except OSError as exc:
+        raise PreconditionError(f"Cannot download {url}", "Check your network and retry, or install the tool on PATH.") from exc
+
+
+def _atomic_write(path: Path, content: bytes, mode: int) -> None:
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(dir=path.parent, delete=False) as output:
+            temporary = Path(output.name)
+            output.write(content)
+            output.flush()
+            os.fsync(output.fileno())
+        temporary.chmod(mode)
+        os.replace(temporary, path)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+
+
+def _platform(system: str | None, machine: str | None) -> tuple[str, str]:
+    arch_name = (machine or platform.machine()).lower()
+    return (system or platform.system()).lower(), {"x86_64": "amd64", "aarch64": "arm64"}.get(arch_name, arch_name)
+
+
+def install_tofu(
+    cache: Path,
+    *,
+    system: str | None = None,
+    machine: str | None = None,
+    fetch: Callable[[str, float], bytes] = download,
+) -> Path:
+    os_name, arch_name = _platform(system, machine)
+    checksum = TOFU_SHA256.get((os_name, arch_name))
+    if checksum is None:
+        raise PreconditionError(f"Unsupported OpenTofu platform: {os_name}/{arch_name}", "Install OpenTofu >=1.8 on PATH.")
+    directory = cache / "tools" / "tofu" / TOFU_VERSION
+    archive = directory / f"tofu_{TOFU_VERSION}_{os_name}_{arch_name}.zip"
+    try:
+        directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        content = (
+            archive.read_bytes()
+            if archive.exists()
+            else fetch(
+                f"https://github.com/opentofu/opentofu/releases/download/v{TOFU_VERSION}/{archive.name}",
+                60.0,
+            )
+        )
+        if hashlib.sha256(content).hexdigest() != checksum:
+            raise PreconditionError("OpenTofu checksum mismatch", f"Remove {archive} and retry, or install OpenTofu on PATH.")
+        with zipfile.ZipFile(io.BytesIO(content)) as package:
+            binary = package.read("tofu")
+        executable = directory / "tofu"
+        _atomic_write(archive, content, 0o600)
+        _atomic_write(executable, binary, 0o700)
+        return executable
+    except (OSError, zipfile.BadZipFile, KeyError) as exc:
+        raise PreconditionError("Cannot install verified OpenTofu", f"Clear {directory} and retry, or install OpenTofu on PATH.") from exc
+
+
+def mutagen_directory(cache: Path) -> Path:
+    return cache / "tools" / "mutagen" / MUTAGEN_VERSION
+
+
+def cached_mutagen(cache: Path) -> Path | None:
+    directory = mutagen_directory(cache)
+    executable = directory / "mutagen"
+    return executable if executable.is_file() and (directory / "mutagen-agents.tar.gz").is_file() else None
+
+
+def download_prompt(cache: Path) -> str:
+    return f"Mutagen {MUTAGEN_VERSION} not found. Download it (verified) into {mutagen_directory(cache)}?"
+
+
+def install_mutagen(
+    cache: Path,
+    *,
+    system: str | None = None,
+    machine: str | None = None,
+    fetch: Callable[[str, float], bytes] = download,
+) -> Path:
+    """Download, verify and unpack the pinned Mutagen release; its agent bundle must sit beside the binary."""
+    os_name, arch_name = _platform(system, machine)
+    checksum = MUTAGEN_SHA256.get((os_name, arch_name))
+    if checksum is None:
+        raise PreconditionError(f"Unsupported Mutagen platform: {os_name}/{arch_name}", "Install Mutagen 0.18.x on PATH.")
+    directory = mutagen_directory(cache)
+    name = f"mutagen_{os_name}_{arch_name}_v{MUTAGEN_VERSION}.tar.gz"
+    console.step(f"Downloading Mutagen {MUTAGEN_VERSION} (about 100 MB)")
+    content = fetch(f"https://github.com/mutagen-io/mutagen/releases/download/v{MUTAGEN_VERSION}/{name}", 300.0)
+    if hashlib.sha256(content).hexdigest() != checksum:
+        raise PreconditionError("Mutagen checksum mismatch", "Retry offbox setup, or install Mutagen 0.18.x on PATH.")
+    executable = directory / "mutagen"
+    try:
+        members: dict[str, bytes] = {}
+        with tarfile.open(fileobj=io.BytesIO(content), mode="r:gz") as package:
+            for member_name in _MUTAGEN_MEMBERS:
+                member = package.getmember(member_name)
+                extracted = package.extractfile(member) if member.isfile() else None
+                if extracted is None:
+                    raise PreconditionError(f"Invalid Mutagen archive member: {member_name}", "Install Mutagen 0.18.x on PATH.")
+                members[member_name] = extracted.read()
+        directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        _atomic_write(directory / "mutagen-agents.tar.gz", members["mutagen-agents.tar.gz"], 0o644)
+        _atomic_write(executable, members["mutagen"], 0o755)
+    except (OSError, tarfile.TarError, KeyError) as exc:
+        raise PreconditionError(
+            "Cannot install verified Mutagen", f"Clear {directory} and retry, or install Mutagen 0.18.x on PATH."
+        ) from exc
+    console.success(f"Installed Mutagen {MUTAGEN_VERSION} at {executable}")
+    return executable
+
+
+def install_hint(name: str, system: str | None = None, release: Mapping[str, str] | None = None) -> str:
+    os_name = (system or platform.system()).lower()
+    if os_name == "darwin":
+        return "Run xcode-select --install or brew install git." if name == "git" else "Run brew install openssh."
+    if release is None:
+        try:
+            release = platform.freedesktop_os_release()
+        except OSError:
+            release = {}
+    family = {release.get("ID", ""), *release.get("ID_LIKE", "").split()}
+    if family & {"debian", "ubuntu"}:
+        return "Run sudo apt install git openssh-client."
+    if family & {"fedora", "rhel", "centos"}:
+        return "Run sudo dnf install git openssh-clients."
+    return "Install git >=2.30 and OpenSSH >=8.0 with your package manager."
+
+
+class ToolDiscovery:
+    def __init__(self, runner: Runner, cache: Path, lookup: Callable[[str], str | None] = shutil.which) -> None:
+        self.runner = runner
+        self.cache = cache
+        self.lookup = lookup
+
+    @measured("Local tool checks")
+    def check(self, name: str) -> Tool:
+        executable = self.lookup(name)
+        if name in ("ssh", "git"):
+            fix = f"{'OpenSSH >=8.0' if name == 'ssh' else 'git >=2.30'} is required. {install_hint(name)}"
+        elif name == "mutagen":
+            fix = MUTAGEN_FIX
+        elif name == "tofu":
+            fix = "Install OpenTofu >=1.8 or Terraform >=1.6."
+        else:
+            fix = f"Install {name}."
+        if name == "mutagen" and executable is None:
+            cached = cached_mutagen(self.cache)
+            if cached is None:
+                raise MutagenMissing("Missing tool: mutagen", fix)
+            executable = str(cached)
+        if name == "tofu" and executable is None:
+            executable = self.lookup("terraform")
+            if executable is not None:
+                name = "terraform"
+            else:
+                executable = str(install_tofu(self.cache))
+        if executable is None:
+            raise PreconditionError(f"Missing tool: {name}", fix)
+        result = self.runner.run([executable, "-V" if name == "ssh" else "--version"], check=False, timeout=10)
+        match = _VERSION.search(result.stdout + "\n" + result.stderr)
+        if result.returncode != 0 or match is None:
+            raise PreconditionError(f"Cannot determine {name} version", fix)
+        found = (int(match[1]), int(match[2]))
+        minimum = {"ssh": (8, 0), "git": (2, 30), "mutagen": MUTAGEN_MIN, "tofu": (1, 8), "terraform": (1, 6)}[name]
+        if found < minimum or (name == "mutagen" and found != MUTAGEN_MIN):
+            if name == "mutagen":
+                fix = f"Install Mutagen 0.18.x, or run mutagen daemon stop, remove {executable} from PATH and run offbox setup."
+            raise PreconditionError(f"Unsupported {name} version: {match.group(0)}", fix)
+        return Tool(name=name, path=Path(executable), version=".".join(part for part in match.groups() if part is not None))