ixt-cli 0.8.0__py3-none-any.whl

ixt/backends/binary.py

@@ -0,0 +1,935 @@
+"""Binary backend — GitHub/GitLab Releases via heuristic asset selection."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, TypedDict
+
+from ixt.backends.binary_resolver import _fast_path_release, derive_asset_pattern
+from ixt.config.asset_index import (
+    GitHubApiDisabledError,
+    disabled_api_message,
+    is_github_api_allowed,
+)
+from ixt.config.flags import is_setup_toml_enabled
+from ixt.config.heuristics import (
+    get_name_suffix_tokens,
+    get_platform_aliases,
+    load_heuristics,
+    select_asset,
+)
+
+if TYPE_CHECKING:
+    from ixt.config.setup_toml import SetupConfig
+from ixt.config.settings import Settings, get_settings
+from ixt.core.backend import BackendType
+from ixt.core.discover import find_executables
+from ixt.core.extract import extract, is_archive
+from ixt.libs.logger import get_logger, get_verbosity
+from ixt.net.source import Asset, Release, ReleaseSource, RepoSpec, parse_spec
+
+__all__ = [
+    "AssetSelectionError",
+    "BinaryBackend",
+    "BinarySpecError",
+    "HookEntry",
+    "SetupMetadata",
+    "_fast_path_release",
+    "derive_asset_pattern",
+    "make_source",
+]
+
+
+# 3.10 lacks typing.NotRequired (added in 3.11) and the project bans
+# third-party deps (typing_extensions). The required-base + total=False
+# subclass pattern is the canonical 3.10 stdlib alternative.
+
+
+class _HookEntryRequired(TypedDict):
+    run: list[str] | str
+
+
+class HookEntry(_HookEntryRequired, total=False):
+    """Persisted lifecycle hook entry inside ``binary_metadata.json``."""
+
+    check: list[str] | str
+
+
+class _SetupMetadataRequired(TypedDict):
+    name: str | None
+    expose: list[str]
+    description: str | None
+    asset_pattern: str | None
+
+
+class SetupMetadata(_SetupMetadataRequired, total=False):
+    """``setup`` sub-document stored in ``binary_metadata.json``.
+
+    Mirrors the relevant subset of ``SetupConfig`` — the bits the tool
+    runtime needs after install (expose filter, hook commands).
+    """
+
+    post_install: HookEntry
+    pre_uninstall: HookEntry
+
+
+class AssetSelectionError(RuntimeError):
+    """Raised when no suitable asset could be selected for the current platform."""
+
+    def __init__(self, spec: str, release_tag: str, asset_names: list[str]):
+        self.spec = spec
+        self.release_tag = release_tag
+        self.asset_names = asset_names
+        names = ", ".join(asset_names[:10]) or "<none>"
+        super().__init__(
+            f"No suitable asset found for '{spec}' (release {release_tag}). Available: {names}"
+        )
+
+
+class BinarySpecError(ValueError):
+    """Raised when a spec cannot be parsed as a binary backend spec."""
+
+    def __init__(self, spec: str):
+        self.spec = spec
+        super().__init__(f"Invalid binary spec: {spec!r} (expected owner/repo[@version])")
+
+
+# ---------------------------------------------------------------------------
+# Metadata stored alongside the extracted environment
+# ---------------------------------------------------------------------------
+
+_META_FILE = "binary_metadata.json"
+
+
+def _encode_path_under_env(path: str, env_dir: Path) -> str:
+    candidate = Path(path)
+    if not candidate.is_absolute():
+        return path
+    try:
+        return str(candidate.absolute().relative_to(env_dir.absolute()))
+    except ValueError:
+        return path
+
+
+def _decode_path_from_env(path: str, env_dir: Path) -> str:
+    candidate = Path(path)
+    if candidate.is_absolute():
+        return path
+    return str(env_dir / candidate)
+
+
+def _existing_metadata_binaries(meta: dict, env_dir: Path) -> dict[str, str]:
+    binaries = meta.get("binaries", {})
+    if not isinstance(binaries, dict):
+        return {}
+    existing: dict[str, str] = {}
+    for name, bin_path in binaries.items():
+        path = Path(bin_path)
+        if path.exists():
+            existing[str(name)] = str(path)
+    return existing
+
+
+def _write_metadata(
+    env_dir: Path,
+    *,
+    spec: str,
+    tag: str,
+    asset_name: str,
+    binaries: dict[str, str],
+    setup: SetupMetadata | None = None,
+    resolution_source: str | None = None,
+) -> Path:
+    """Write binary backend metadata to env_dir."""
+    path = env_dir / _META_FILE
+    data: dict = {
+        "spec": spec,
+        "tag": tag,
+        "asset_name": asset_name,
+        "binaries": {
+            name: _encode_path_under_env(path, env_dir) for name, path in binaries.items()
+        },
+    }
+    if setup is not None:
+        data["setup"] = setup
+    if resolution_source:
+        data["resolution_source"] = resolution_source
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+    return path
+
+
+def _read_metadata(env_dir: Path) -> dict | None:
+    """Read binary backend metadata, or None if absent."""
+    path = env_dir / _META_FILE
+    if not path.exists():
+        return None
+    with path.open(encoding="utf-8") as f:
+        data = json.load(f)
+    binaries = data.get("binaries")
+    if isinstance(binaries, dict):
+        data["binaries"] = {
+            name: _decode_path_from_env(path, env_dir) for name, path in binaries.items()
+        }
+    return data
+
+
+def _build_setup_metadata(setup: SetupConfig | None) -> SetupMetadata | None:
+    """Serialize a SetupConfig into the JSON-ready metadata dict."""
+    if setup is None:
+        return None
+    data: SetupMetadata = {
+        "name": setup.name,
+        "expose": setup.expose,
+        "description": setup.description,
+        "asset_pattern": setup.asset_pattern,
+    }
+    if setup.post_install.run:
+        post: HookEntry = {"run": setup.post_install.run}
+        if setup.post_install.check:
+            post["check"] = setup.post_install.check
+        data["post_install"] = post
+    if setup.pre_uninstall.run:
+        pre: HookEntry = {"run": setup.pre_uninstall.run}
+        if setup.pre_uninstall.check:
+            pre["check"] = setup.pre_uninstall.check
+        data["pre_uninstall"] = pre
+    return data
+
+
+# ---------------------------------------------------------------------------
+# Release source factory
+# ---------------------------------------------------------------------------
+
+
+def make_source(repo_spec: RepoSpec) -> ReleaseSource:
+    """Create the appropriate ReleaseSource for a parsed spec.
+
+    For GitLab, ``base_url`` is derived from ``repo_spec.host`` so
+    self-hosted instances (e.g. ``gitlab.company.com``) are reached
+    instead of ``gitlab.com``.
+    """
+    if repo_spec.platform == "github":
+        from ixt.net.github_api import GitHubSource
+
+        return GitHubSource()
+
+    from ixt.net.gitlab_api import GitLabSource
+
+    base_url = f"https://{repo_spec.host}"
+    return GitLabSource(base_url=base_url)
+
+
+# ---------------------------------------------------------------------------
+# Cache helpers
+# ---------------------------------------------------------------------------
+
+
+def _cache_dir_for(settings: Settings, repo_spec: RepoSpec) -> Path:
+    """Return the cache directory for a given repo spec.
+
+    Layout: ``$IXT_CACHE_HOME/downloads/{host}/{owner}-{repo}/``
+    """
+    host = repo_spec.host.replace(":", "_")
+    return settings.cache_dir / host / f"{repo_spec.owner}-{repo_spec.repo}"
+
+
+def _cached_asset(cache_dir: Path, asset_name: str) -> Path | None:
+    """Return the cached asset path if it exists."""
+    path = cache_dir / asset_name
+    if path.exists() and path.stat().st_size > 0:
+        return path
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Version extraction
+# ---------------------------------------------------------------------------
+
+_BARE_NAME_SEPARATORS = "._-"
+_VERSION_SUFFIX_RE = re.compile(
+    rf"(^|[{re.escape(_BARE_NAME_SEPARATORS)}])"
+    rf"v?\d+(?:\.\d+){{1,}}(?:[-+][0-9A-Za-z.]+)?$",
+    re.IGNORECASE,
+)
+
+
+def _strip_v_prefix(tag: str) -> str:
+    """Strip leading 'v' from a version tag: 'v14.1.0' -> '14.1.0'."""
+    if tag.startswith("v") and len(tag) > 1 and tag[1:2].isdigit():
+        return tag[1:]
+    return tag
+
+
+def _tag_candidates(tag: str) -> list[str]:
+    """Return direct-download tag candidates, preserving exact-tag priority."""
+    if tag.startswith("v"):
+        return [tag]
+    return [tag, f"v{tag}"]
+
+
+def _selection_pattern(pattern: str | None, tag: str) -> str | None:
+    """Return a pattern suitable for the existing selector.
+
+    The selection layer knows ``{version}``, ``{os}``, ``{arch}``, and
+    ``{name}``. Direct-download patterns may also use ``{tag}``, so replace
+    that placeholder before matching the synthesized one-asset release.
+    """
+    if pattern is None:
+        return None
+    return pattern.replace("{tag}", tag)
+
+
+def _strip_exe_suffix(name: str) -> str:
+    """Return *name* without a Windows executable suffix, if present."""
+    return name[:-4] if name.lower().endswith(".exe") else name
+
+
+def _strip_trailing_token(name: str, token: str) -> str:
+    """Strip *token* when it is the final separator-delimited name token."""
+    cleaned = token.strip(_BARE_NAME_SEPARATORS)
+    if not cleaned:
+        return name
+
+    lower = name.lower()
+    token_lower = cleaned.lower()
+    if lower == token_lower:
+        return ""
+
+    for sep in _BARE_NAME_SEPARATORS:
+        suffix = f"{sep}{token_lower}"
+        if lower.endswith(suffix):
+            return name[: -len(suffix)].rstrip(_BARE_NAME_SEPARATORS)
+    return name
+
+
+def _strip_trailing_tokens(name: str, tokens: list[str]) -> str:
+    """Repeatedly strip known final tokens, longest aliases first."""
+    current = name
+    aliases = sorted({token for token in tokens if token}, key=len, reverse=True)
+    changed = True
+    while current and changed:
+        changed = False
+        for token in aliases:
+            stripped = _strip_trailing_token(current, token)
+            if stripped != current:
+                current = stripped
+                changed = True
+                break
+    return current
+
+
+def _strip_trailing_version(name: str, tag: str) -> str:
+    """Strip a final release-version token from *name*."""
+    version = _strip_v_prefix(tag)
+    candidates = [tag, version]
+    if version:
+        candidates.append(f"v{version}")
+
+    stripped = _strip_trailing_tokens(name, candidates)
+    if stripped != name:
+        return stripped
+
+    return _VERSION_SUFFIX_RE.sub("", name).strip(_BARE_NAME_SEPARATORS)
+
+
+def _derive_bare_binary_name(asset_name: str, fallback_name: str, tag: str) -> str:
+    """Infer the executable name for a bare binary asset.
+
+    Bare release assets are the executable itself. Keep that source of truth,
+    but remove common version/platform suffixes such as
+    ``shfmt_v3.13.1_linux_amd64`` -> ``shfmt``.
+    """
+    current = _strip_exe_suffix(asset_name).strip(_BARE_NAME_SEPARATORS)
+    os_aliases, arch_aliases = get_platform_aliases()
+    suffix_tokens = [*os_aliases, *arch_aliases, *get_name_suffix_tokens()]
+
+    changed = True
+    while current and changed:
+        changed = False
+        stripped = _strip_trailing_tokens(current, suffix_tokens)
+        stripped = _strip_trailing_version(stripped, tag)
+        if stripped != current:
+            current = stripped
+            changed = True
+
+    return current or _strip_exe_suffix(fallback_name)
+
+
+# ---------------------------------------------------------------------------
+# BinaryBackend
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class BinaryBackend:
+    """Install binary tools from GitHub/GitLab Releases."""
+
+    settings: Settings = field(default_factory=get_settings)
+    backend_type: BackendType = field(default=BackendType.BINARY, init=False)
+
+    # -- Backend protocol ---------------------------------------------------
+
+    def env_exists(self, env_dir: Path) -> bool:
+        """Check whether extracted binary content exists."""
+        meta = env_dir / _META_FILE
+        return meta.exists()
+
+    def create_env(self, env_dir: Path) -> bool:
+        """Create the environment directory. Return True if newly created."""
+        if env_dir.exists() and self.env_exists(env_dir):
+            return False
+        env_dir.mkdir(parents=True, exist_ok=True)
+        return True
+
+    def install_packages(
+        self,
+        env_dir: Path,
+        specs: list[str],
+        *,
+        upgrade: bool = False,
+        setup_path: Path | None = None,
+        asset_pattern: str | None = None,
+        known_tag: str | None = None,
+        use_cache: bool = True,
+    ) -> dict | None:
+        """Compatibility adapter for the shared backend protocol."""
+        if not specs:
+            return None
+        if len(specs) > 1:
+            raise ValueError("Binary backend does not support injected packages")
+        return self.install_package(
+            env_dir,
+            specs[0],
+            upgrade=upgrade,
+            setup_path=setup_path,
+            asset_pattern=asset_pattern,
+            known_tag=known_tag,
+            use_cache=use_cache,
+        )
+
+    def install_package(
+        self,
+        env_dir: Path,
+        spec: str,
+        *,
+        upgrade: bool = False,
+        setup_path: Path | None = None,
+        asset_pattern: str | None = None,
+        known_tag: str | None = None,
+        use_cache: bool = True,
+    ) -> dict | None:
+        """Resolve, download, extract, and discover one atomic binary tool.
+
+        *asset_pattern* (when provided) forces the asset selection pattern
+        and takes precedence over any value declared in ixt.setup.toml.
+
+        *known_tag* (when provided) is the latest tag a caller already
+        resolved, reused by the fast-path to skip a redundant network HEAD.
+
+        *use_cache=False* disables reuse of the resolve TTL cache entry. It
+        does not disable asset-pattern reuse because that cache stores URL
+        shape, not a latest-version decision.
+        """
+
+        log = get_logger("binary")
+        repo_spec = parse_spec(spec)
+        if repo_spec is None:
+            raise BinarySpecError(spec)
+
+        source = make_source(repo_spec)
+        log.debug(f"spec: {repo_spec.owner}/{repo_spec.repo} platform={repo_spec.platform}")
+
+        cache_dir = _cache_dir_for(self.settings, repo_spec)
+
+        setup, setup_resolved = self._resolve_setup_before_release(
+            source,
+            repo_spec,
+            cache_dir,
+            setup_path,
+            upgrade=upgrade,
+            asset_pattern=asset_pattern,
+        )
+        release_pattern = asset_pattern or (
+            setup.asset_pattern if setup and setup.asset_pattern else None
+        )
+        release_pattern_name = setup.name if setup and setup.name else None
+
+        # Reuse the release already fetched during version resolution (e.g. an
+        # upgrade or a dry-run within the TTL window). This skips a second API
+        # call — the only option for GitLab, whose asset URLs can't be rebuilt
+        # from a pattern like GitHub's.
+        release = self._cached_release(spec) if use_cache and not repo_spec.version else None
+        if release is not None:
+            log.debug(f"release (resolve cache): {release.tag} ({len(release.assets)} assets)")
+        else:
+            release = self._fetch_release(
+                source,
+                repo_spec,
+                env_dir=env_dir,
+                upgrade=upgrade,
+                known_tag=known_tag,
+                asset_pattern=release_pattern,
+                pattern_name=release_pattern_name,
+            )
+            log.debug(f"release: {release.tag} ({len(release.assets)} assets)")
+
+        if setup is None and not setup_resolved:
+            setup = self._resolve_setup(
+                source, repo_spec, cache_dir, setup_path, upgrade=upgrade, ref=release.tag
+            )
+
+        tool_name = setup.name if setup and setup.name else repo_spec.repo
+        effective_pattern = asset_pattern or (
+            setup.asset_pattern if setup and setup.asset_pattern else None
+        )
+        if asset_pattern:
+            log.debug(f"user-forced asset_pattern: {asset_pattern!r}")
+        selection_pattern = _selection_pattern(effective_pattern, release.tag)
+        asset = self._select_asset(release, selection_pattern, tool_name, spec)
+        log.debug(f"selected asset: {asset.name}")
+
+        archive_path = self._download_asset(
+            source,
+            repo_spec,
+            asset,
+            cache_dir,
+            tag=release.tag,
+            upgrade=upgrade,
+        )
+        log.debug(f"archive: {archive_path}")
+
+        extract_tool_name = tool_name
+        if not is_archive(asset.name) and not (setup and setup.name):
+            extract_tool_name = _derive_bare_binary_name(asset.name, tool_name, release.tag)
+
+        result = extract(archive_path, env_dir, tool_name=extract_tool_name)
+        log.debug(f"extracted to: {result.root}")
+
+        heuristics = load_heuristics()
+        executables = find_executables(result.root, expose=heuristics.expose, log=log)
+        log.debug(f"executables: {[e.name for e in executables]}")
+
+        binaries = {exe.name: str(exe) for exe in executables}
+
+        # Learn the asset URL pattern so future upgrades can skip the API.
+        # Priority: user CLI override > ixt.setup.toml (author) > derived
+        # from the resolved asset name. Only the first two are "forced" —
+        # the derived one bakes in OS/arch and is unsafe for cross-machine
+        # replay via ixt tool export.
+        pattern_forced = effective_pattern is not None
+        learned_pattern = effective_pattern or derive_asset_pattern(asset.name, release.tag)
+
+        _write_metadata(
+            env_dir,
+            spec=spec,
+            tag=release.tag,
+            asset_name=asset.name,
+            binaries=binaries,
+            setup=_build_setup_metadata(setup),
+            resolution_source=release.resolution_source,
+        )
+
+        # Persist the pattern globally (IXT_CACHE_HOME metadata) so reinstalls of the
+        # same tool — including after an uninstall — skip the API too.
+        if learned_pattern and repo_spec.platform == "github":
+            from ixt.config import asset_pattern_cache
+
+            asset_pattern_cache.set_(repo_spec.owner, repo_spec.repo, learned_pattern)
+
+        return {
+            "asset_pattern": learned_pattern,
+            "asset_pattern_forced": pattern_forced,
+        }
+
+    def _resolve_setup_before_release(
+        self,
+        source: ReleaseSource,
+        repo_spec: RepoSpec,
+        cache_dir: Path,
+        setup_path: Path | None,
+        *,
+        upgrade: bool,
+        asset_pattern: str | None,
+    ) -> tuple[SetupConfig | None, bool]:
+        """Resolve setup early when it can feed a direct release URL.
+
+        Remote setup files are only fetched early for exact pinned binary tags:
+        the raw-file fetch can be pinned to the same tag without consulting the
+        release API. Unpinned and partial-version installs keep the normal
+        release-first order so setup stays tied to the resolved release tag.
+
+        Returns ``(setup, resolved)`` where ``resolved`` means the normal
+        post-release setup lookup can be skipped, even when no file exists.
+        """
+        if asset_pattern:
+            return None, False
+        if setup_path is not None:
+            setup = self._resolve_setup(
+                source, repo_spec, cache_dir, setup_path, upgrade=upgrade, ref=repo_spec.version
+            )
+            return setup, True
+        if not is_setup_toml_enabled() or not repo_spec.version:
+            return None, False
+
+        from ixt.libs.semver import is_partial_version
+
+        if is_partial_version(repo_spec.version):
+            return None, False
+
+        for ref in _tag_candidates(repo_spec.version):
+            setup = self._resolve_setup(
+                source, repo_spec, cache_dir, None, upgrade=upgrade, ref=ref
+            )
+            if setup is not None:
+                return setup, True
+        return None, True
+
+    def _resolve_setup(
+        self,
+        source: ReleaseSource,
+        repo_spec: RepoSpec,
+        cache_dir: Path,
+        setup_path: Path | None,
+        *,
+        upgrade: bool,
+        ref: str | None = None,
+    ) -> SetupConfig | None:
+        """Resolve ixt.setup.toml: local override > remote (gated by flag).
+
+        *ref* pins the remote fetch to a specific revision (tag) so the
+        config matches the release being installed.
+        """
+        log = get_logger("binary")
+        if setup_path is not None:
+            from ixt.config.setup_toml import load_local_setup_toml
+
+            setup = load_local_setup_toml(setup_path)
+            log.debug(f"using local setup.toml: {setup_path}")
+        elif is_setup_toml_enabled():
+            setup = self._fetch_setup_toml(source, repo_spec, cache_dir, upgrade=upgrade, ref=ref)
+        else:
+            setup = None
+        if setup:
+            log.debug(
+                f"ixt.setup.toml: name={setup.name} expose={setup.expose}"
+                f" pattern={setup.asset_pattern}"
+            )
+        return setup
+
+    def _select_asset(
+        self,
+        release: Release,
+        asset_pattern: str | None,
+        tool_name: str,
+        main_spec: str,
+    ) -> Asset:
+        heuristics = load_heuristics()
+        asset = select_asset(
+            release.assets,
+            tool_name,
+            _strip_v_prefix(release.tag),
+            heuristics=heuristics,
+            asset_pattern=asset_pattern,
+            verbose=get_verbosity(),
+        )
+        if asset is None:
+            raise AssetSelectionError(
+                main_spec,
+                release.tag,
+                [a.name for a in release.assets],
+            )
+        return asset
+
+    def uninstall_package(self, env_dir: Path, package: str) -> None:
+        """No-op — binary tools are atomic (uninstall removes the whole env)."""
+
+    def find_binaries(self, env_dir: Path) -> list[Path]:
+        """Discover executables in the extracted environment."""
+        meta = _read_metadata(env_dir)
+        if meta and meta.get("binaries"):
+            # Fast path: use cached binary list from metadata
+            existing = _existing_metadata_binaries(meta, env_dir)
+            if existing:
+                return sorted((Path(p) for p in existing.values()), key=lambda p: p.name)
+
+        # Slow path: re-scan the environment
+        heuristics = load_heuristics()
+        return find_executables(env_dir, expose=heuristics.expose, log=get_logger("binary"))
+
+    def get_package_binaries(self, env_dir: Path, package_name: str) -> dict[str, str]:
+        """Return discovered binaries as {name: path}.
+
+        Priority: setup.toml expose > all discovered executables.
+        When setup.toml defines an expose list, only those names are returned.
+        """
+        meta = _read_metadata(env_dir)
+        if not meta or not meta.get("binaries"):
+            # Fallback: live scan
+            bins = self.find_binaries(env_dir)
+            all_bins = {p.name: str(p) for p in bins}
+        else:
+            all_bins = _existing_metadata_binaries(meta, env_dir)
+            if not all_bins:
+                bins = self.find_binaries(env_dir)
+                all_bins = {p.name: str(p) for p in bins}
+
+        # Apply setup.toml expose filter if present
+        setup = meta.get("setup") if meta else None
+        if setup and setup.get("expose"):
+            expose_names = set(setup["expose"])
+            filtered = {k: v for k, v in all_bins.items() if k in expose_names}
+            if filtered:
+                return filtered
+            from ixt.libs.logger import get_logger
+
+            get_logger("binary").warn(
+                f"setup.toml expose {setup['expose']} matched no binaries "
+                f"(available: {list(all_bins)}), falling back to all"
+            )
+
+        return all_bins
+
+    def installed_version(self, env_dir: Path, package_name: str) -> str | None:
+        """Return the installed version from the release tag."""
+        meta = _read_metadata(env_dir)
+        if meta is None:
+            return None
+        tag = meta.get("tag", "")
+        return _strip_v_prefix(tag) if tag else None
+
+    def export(self, env_dir: Path) -> list[str]:
+        """Return installed spec with pinned version."""
+        meta = _read_metadata(env_dir)
+        if meta is None:
+            return []
+        spec = meta.get("spec", "")
+        tag = meta.get("tag", "")
+        if spec and tag:
+            repo_spec = parse_spec(spec)
+            if repo_spec:
+                return [f"{repo_spec.owner}/{repo_spec.repo}@{tag}"]
+        return []
+
+    # -- Internal helpers ---------------------------------------------------
+
+    def _cached_release(self, main_spec: str) -> Release | None:
+        """Rebuild a Release from a fresh resolve-cache entry that carries assets.
+
+        Returns None when there is no fresh entry or it has no assets (e.g. the
+        GitHub HEAD-redirect path, which caches only the tag). Keyed identically
+        to ``resolve.resolve_latest`` so the resolution and the install agree.
+        """
+        from ixt.core import resolve_cache
+
+        entry = resolve_cache.get_entry(
+            resolve_cache.make_key("binary", main_spec), settings=self.settings
+        )
+        if not entry:
+            return None
+        assets = entry.get("assets")
+        if not assets:
+            return None
+        rebuilt = [
+            Asset(name=a["name"], url=a["url"], size=a.get("size", 0))
+            for a in assets
+            if isinstance(a, dict) and a.get("name") and a.get("url")
+        ]
+        if not rebuilt:
+            # Entry present but every asset is malformed/schema-drifted: fall
+            # back to the API rather than fail asset selection on an empty list.
+            return None
+        return Release(tag=entry["version"], assets=rebuilt, resolution_source="resolve-cache")
+
+    def _fetch_release(
+        self,
+        source: ReleaseSource,
+        repo_spec: RepoSpec,
+        *,
+        env_dir: Path | None = None,
+        upgrade: bool = False,
+        known_tag: str | None = None,
+        asset_pattern: str | None = None,
+        pattern_name: str | None = None,
+    ) -> Release:
+        """Fetch the target release (by tag, partial semver, or latest).
+
+        Fast-path: a GitHub repo that has an explicit or cached
+        ``asset_pattern`` can synthesize the Release without touching the
+        API. Unpinned installs resolve the tag via a plain 302 on
+        ``github.com/.../releases/latest``; pinned installs reuse their tag
+        directly. Falls back silently on any failure. *known_tag* lets an
+        upgrade reuse the tag it already resolved, skipping even that 302.
+        """
+        if not repo_spec.version:
+            # Pattern-based fast-path: consults the global metadata cache and
+            # falls back to per-tool metadata. Works on fresh install and
+            # upgrade alike — upgrade kept in the signature for callers
+            # that still want to force-refresh the cached setup.toml.
+            fast = _fast_path_release(
+                repo_spec,
+                env_dir,
+                known_tag=known_tag,
+                asset_pattern=asset_pattern,
+                pattern_name=pattern_name,
+                settings=self.settings,
+            )
+            if fast is not None:
+                return fast
+
+        if repo_spec.version:
+            from ixt.libs.semver import is_partial_version
+
+            if is_partial_version(repo_spec.version):
+                fast = _fast_path_release(
+                    repo_spec,
+                    env_dir,
+                    known_tag=None,
+                    asset_pattern=asset_pattern,
+                    pattern_name=pattern_name,
+                    allow_partial_version=True,
+                    settings=self.settings,
+                )
+                if fast is not None:
+                    return fast
+                self._require_github_api(repo_spec)
+                return self._fetch_release_partial(source, repo_spec)
+
+            tag = repo_spec.version
+            for direct_tag in _tag_candidates(tag):
+                fast = _fast_path_release(
+                    repo_spec,
+                    env_dir,
+                    known_tag=direct_tag,
+                    asset_pattern=asset_pattern,
+                    pattern_name=pattern_name,
+                    invalidate_cache_on_error=False,
+                    settings=self.settings,
+                )
+                if fast is not None:
+                    return fast
+
+            self._require_github_api(repo_spec)
+            # Try exact tag first, then with 'v' prefix.
+            try:
+                release = source.get_release_by_tag(repo_spec.owner, repo_spec.repo, tag)
+            except Exception:
+                if not tag.startswith("v"):
+                    release = source.get_release_by_tag(repo_spec.owner, repo_spec.repo, f"v{tag}")
+                    release.resolution_source = f"{repo_spec.platform}-api"
+                    return release
+                raise
+            release.resolution_source = f"{repo_spec.platform}-api"
+            return release
+
+        self._require_github_api(repo_spec)
+        release = source.get_latest_release(repo_spec.owner, repo_spec.repo)
+        release.resolution_source = f"{repo_spec.platform}-api"
+        return release
+
+    def _require_github_api(self, repo_spec: RepoSpec) -> None:
+        """Fail before touching ``api.github.com`` in strict mode."""
+        if repo_spec.platform == "github" and not is_github_api_allowed():
+            raise GitHubApiDisabledError(disabled_api_message(repo_spec))
+
+    def _fetch_release_partial(
+        self,
+        source: ReleaseSource,
+        repo_spec: RepoSpec,
+    ) -> Release:
+        """Fetch the latest release matching a partial semver (e.g. '14' or '14.1')."""
+        from ixt.libs.semver import matches_partial, parse_version
+
+        releases = source.list_releases(repo_spec.owner, repo_spec.repo)
+        partial = repo_spec.version or ""
+        candidates = [
+            r
+            for r in releases
+            if not r.prerelease and not r.draft and matches_partial(r.tag, partial)
+        ]
+        if not candidates:
+            raise RuntimeError(
+                f"No release matching '{partial}' for {repo_spec.owner}/{repo_spec.repo}"
+            )
+        # Sort by parsed version descending, pick newest
+        candidates.sort(key=lambda r: parse_version(r.tag) or (), reverse=True)
+        release = candidates[0]
+        release.resolution_source = f"{repo_spec.platform}-api"
+        return release
+
+    def _fetch_setup_toml(
+        self,
+        source: ReleaseSource,
+        repo_spec: RepoSpec,
+        cache_dir: Path,
+        *,
+        upgrade: bool = False,
+        ref: str | None = None,
+    ) -> SetupConfig | None:
+        """Fetch ixt.setup.toml from the repo (cached, silent on 404)."""
+        from ixt.config.setup_toml import fetch_setup_toml
+
+        # On upgrade, invalidate cached setup.toml so we fetch fresh
+        if upgrade:
+            cached = cache_dir / "setup.toml"
+            cached.unlink(missing_ok=True)
+
+        return fetch_setup_toml(
+            source,
+            repo_spec.owner,
+            repo_spec.repo,
+            cache_dir=cache_dir,
+            ref=ref,
+        )
+
+    def _download_asset(
+        self,
+        source: ReleaseSource,
+        repo_spec: RepoSpec,
+        asset: Asset,
+        cache_dir: Path,
+        *,
+        tag: str,
+        upgrade: bool = False,
+    ) -> Path:
+        """Download an asset, using cache when available."""
+        cached = _cached_asset(cache_dir, asset.name)
+        if cached is not None and not upgrade:
+            self._record_download(repo_spec, asset, cached, tag=tag)
+            return cached
+
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        dest = cache_dir / asset.name
+        source.download_asset(asset.url, dest)
+        self._record_download(repo_spec, asset, dest, tag=tag)
+        return dest
+
+    def _record_download(
+        self,
+        repo_spec: RepoSpec,
+        asset: Asset,
+        path: Path,
+        *,
+        tag: str,
+    ) -> None:
+        """Index the downloaded binary asset for later cache pruning."""
+        from ixt.core.cache import record_download
+
+        record_download(
+            settings=self.settings,
+            kind="binary-asset",
+            platform=repo_spec.platform,
+            host=repo_spec.host,
+            owner=repo_spec.owner,
+            repo=repo_spec.repo,
+            tag=tag,
+            asset_name=asset.name,
+            asset_url=asset.url,
+            asset_size=asset.size,
+            path=path,
+        )