ixt-cli 0.8.0__py3-none-any.whl

ixt/config/asset_index.py

@@ -0,0 +1,305 @@
+"""Asset-index loading for GitHub binary resolution.
+
+``asset_index.json`` is public resolution metadata. It maps canonical GitHub
+specs (``@gh:owner/repo``) to platform-specific asset patterns or exact assets.
+It is intentionally separate from ``registry.toml``: registry resolves names,
+asset-index resolves release assets.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ixt.config.settings import Settings, get_settings
+from ixt.data import get_data_path
+from ixt.net.source import RepoSpec, parse_spec
+from ixt.platform import OS, Arch, get_arch, get_os
+
+ASSET_INDEX_FILENAME = "asset_index.json"
+GITHUB_API_ENV = "IXT_GITHUB_API"
+
+_OS_KEY = {
+    OS.LINUX: "linux",
+    OS.MACOS: "macos",
+    OS.WINDOWS: "windows",
+}
+_ARCH_KEY = {
+    Arch.X86_64: "x86_64",
+    Arch.ARM64: "aarch64",
+    Arch.ARMV7: "armv7",
+}
+
+
+class GitHubApiDisabledError(RuntimeError):
+    """Raised when strict no-GitHub-API mode lacks local resolution metadata."""
+
+
+@dataclass(slots=True)
+class AssetIndexAsset:
+    """An exact platform asset already known by an asset-index source."""
+
+    tag: str
+    asset: str
+    url: str | None = None
+
+
+@dataclass(slots=True)
+class AssetIndexEntry:
+    """Resolution metadata for one canonical GitHub spec."""
+
+    canonical_spec: str
+    names: list[str] = field(default_factory=list)
+    patterns: dict[str, str] = field(default_factory=dict)
+    assets: dict[str, AssetIndexAsset] = field(default_factory=dict)
+    source: str = ""
+
+
+def github_api_mode() -> str:
+    """Return the configured GitHub API mode (``auto`` or ``never``)."""
+    value = os.environ.get(GITHUB_API_ENV, "auto").strip().lower()
+    return value or "auto"
+
+
+def is_github_api_allowed() -> bool:
+    """Whether calls to ``api.github.com`` are allowed."""
+    return github_api_mode() != "never"
+
+
+def disabled_api_message(repo_spec: RepoSpec) -> str:
+    """Clear error text for strict mode when local metadata is insufficient."""
+    return (
+        f"Cannot resolve GitHub release for {repo_spec.owner}/{repo_spec.repo}: "
+        f"{GITHUB_API_ENV}=never is set and no matching asset_index.json entry, "
+        "learned asset pattern, exact cached asset, or downloaded cache metadata "
+        "could resolve the asset. Preload an asset_index.json with IXT_ASSET_INDEX "
+        "or unset IXT_GITHUB_API to allow the GitHub Releases API fallback."
+    )
+
+
+def platform_key(
+    *,
+    os_override: OS | None = None,
+    arch_override: Arch | None = None,
+) -> str:
+    """Return the public ``os/arch`` key for the current or supplied platform."""
+    os_key = _OS_KEY[os_override or get_os()]
+    arch_key = _ARCH_KEY[arch_override or get_arch()]
+    return f"{os_key}/{arch_key}"
+
+
+def canonical_github_spec(repo_spec: RepoSpec) -> str | None:
+    """Return ``@gh:owner/repo`` for GitHub specs; otherwise None."""
+    if repo_spec.platform != "github":
+        return None
+    return f"@gh:{repo_spec.owner}/{repo_spec.repo}"
+
+
+def load_configured_asset_index(*, settings: Settings | None = None) -> dict[str, AssetIndexEntry]:
+    """Load built-in, user-config and env-supplied asset indexes.
+
+    Lower-priority sources are loaded first. Later sources replace an entire
+    canonical entry when the same top-level key is present.
+    """
+    settings = settings or get_settings()
+    merged: dict[str, AssetIndexEntry] = {}
+    for path, source in _configured_sources(settings):
+        merged.update(load_asset_index_file(path, source=source))
+    return merged
+
+
+def load_learned_asset_index(*, settings: Settings | None = None) -> dict[str, AssetIndexEntry]:
+    """Expose learned cache metadata as low-priority asset-index entries."""
+    settings = settings or get_settings()
+    entries: dict[str, AssetIndexEntry] = {}
+    key = platform_key()
+
+    for owner_repo, pattern in _load_asset_patterns(settings).items():
+        owner, sep, repo = owner_repo.partition("/")
+        if not sep or not owner or not repo:
+            continue
+        canonical = f"@gh:{owner}/{repo}"
+        entry = entries.setdefault(
+            canonical,
+            AssetIndexEntry(canonical_spec=canonical, source="cache"),
+        )
+        entry.patterns[key] = pattern
+
+    for item in _load_download_assets(settings):
+        canonical = f"@gh:{item['owner']}/{item['repo']}"
+        entry = entries.setdefault(
+            canonical,
+            AssetIndexEntry(canonical_spec=canonical, source="cache"),
+        )
+        entry.assets[key] = AssetIndexAsset(
+            tag=item["tag"],
+            asset=item["asset"],
+            url=item["url"] or None,
+        )
+
+    return entries
+
+
+def load_asset_index_file(path: Path, *, source: str | None = None) -> dict[str, AssetIndexEntry]:
+    """Parse one asset-index file. Missing or malformed files are ignored."""
+    if _is_remote_placeholder(path):
+        return {}
+    try:
+        with path.open(encoding="utf-8") as f:
+            data = json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+
+    source_label = source or str(path)
+    entries: dict[str, AssetIndexEntry] = {}
+    for raw_spec, raw_entry in data.items():
+        if not isinstance(raw_spec, str) or not isinstance(raw_entry, dict):
+            continue
+        canonical = _canonical_key(raw_spec)
+        if canonical is None:
+            continue
+        entry = _parse_entry(canonical, raw_entry, source=source_label)
+        if entry is not None:
+            entries[canonical] = entry
+    return entries
+
+
+def _configured_sources(settings: Settings) -> list[tuple[Path, str]]:
+    sources = [
+        (get_data_path(ASSET_INDEX_FILENAME), "built-in"),
+        (settings.config_dir / ASSET_INDEX_FILENAME, "config"),
+    ]
+    for raw in _split_env_paths(os.environ.get("IXT_ASSET_INDEX", "")):
+        if raw.startswith(("http://", "https://")):
+            continue
+        sources.append((Path(raw).expanduser(), f"env:{raw}"))
+    return sources
+
+
+def _split_env_paths(value: str) -> list[str]:
+    return [part for part in (item.strip() for item in value.split(";")) if part]
+
+
+def _is_remote_placeholder(path: Path) -> bool:
+    raw = str(path)
+    return raw.startswith(("http://", "https://"))
+
+
+def _canonical_key(raw_spec: str) -> str | None:
+    raw = raw_spec.strip()
+    if raw.startswith("@gh:"):
+        raw = raw[4:]
+    repo_spec = parse_spec(raw)
+    if repo_spec is None or repo_spec.platform != "github":
+        return None
+    return f"@gh:{repo_spec.owner}/{repo_spec.repo}"
+
+
+def _parse_entry(
+    canonical: str,
+    data: dict[str, Any],
+    *,
+    source: str,
+) -> AssetIndexEntry | None:
+    names = _string_list(data.get("names"))
+    patterns = _string_map(data.get("patterns"))
+    assets = _asset_map(data.get("assets"))
+    if not patterns and not assets:
+        return None
+    return AssetIndexEntry(
+        canonical_spec=canonical,
+        names=names,
+        patterns=patterns,
+        assets=assets,
+        source=source,
+    )
+
+
+def _string_list(value: object) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [item for item in value if isinstance(item, str)]
+
+
+def _string_map(value: object) -> dict[str, str]:
+    if not isinstance(value, dict):
+        return {}
+    return {str(k): v for k, v in value.items() if isinstance(k, str) and isinstance(v, str)}
+
+
+def _asset_map(value: object) -> dict[str, AssetIndexAsset]:
+    if not isinstance(value, dict):
+        return {}
+    result: dict[str, AssetIndexAsset] = {}
+    for platform, raw_asset in value.items():
+        if not isinstance(platform, str) or not isinstance(raw_asset, dict):
+            continue
+        tag = raw_asset.get("tag")
+        asset = raw_asset.get("asset")
+        url = raw_asset.get("url")
+        if not isinstance(tag, str) or not isinstance(asset, str):
+            continue
+        result[platform] = AssetIndexAsset(
+            tag=tag,
+            asset=asset,
+            url=url if isinstance(url, str) else None,
+        )
+    return result
+
+
+def _load_asset_patterns(settings: Settings) -> dict[str, str]:
+    path = settings.metadata_dir / "asset_patterns.json"
+    try:
+        with path.open(encoding="utf-8") as f:
+            data = json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return {k: v for k, v in data.items() if isinstance(k, str) and isinstance(v, str)}
+
+
+def _load_download_assets(settings: Settings) -> list[dict[str, str]]:
+    from ixt.core.cache import downloads_index_path
+
+    try:
+        with downloads_index_path(settings=settings).open(encoding="utf-8") as f:
+            data = json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return []
+    if not isinstance(data, dict) or not isinstance(data.get("entries"), list):
+        return []
+
+    items: list[dict[str, str]] = []
+    for entry in data["entries"]:
+        if not isinstance(entry, dict) or entry.get("kind") != "binary-asset":
+            continue
+        if entry.get("platform") != "github" or entry.get("host") != "github.com":
+            continue
+        owner = entry.get("owner")
+        repo = entry.get("repo")
+        tag = entry.get("tag")
+        asset = entry.get("asset")
+        url = entry.get("url")
+        if (
+            not isinstance(owner, str)
+            or not isinstance(repo, str)
+            or not isinstance(tag, str)
+            or not isinstance(asset, str)
+        ):
+            continue
+        items.append(
+            {
+                "owner": owner,
+                "repo": repo,
+                "tag": tag,
+                "asset": asset,
+                "url": url if isinstance(url, str) else "",
+            }
+        )
+    return items

ixt/config/asset_pattern_cache.py

@@ -0,0 +1,87 @@
+"""Cache of learned asset patterns for GitHub Releases.
+
+Stored in ``$IXT_CACHE_HOME/metadata/asset_patterns.json``. When
+``IXT_CACHE_HOME`` is unset, ixt falls back to ``$XDG_CACHE_HOME/ixt`` or
+``~/.cache/ixt``.
+
+Schema::
+
+    {
+      "sharkdp/bat": "bat-v{version}-x86_64-unknown-linux-gnu.tar.gz",
+      "BurntSushi/ripgrep": "ripgrep-{version}-x86_64-unknown-linux-musl.tar.gz"
+    }
+
+No TTL. Patterns are stable across years — when one breaks (rare rename
+by a maintainer), the caller invalidates the entry and relearns from a
+fresh release API call.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from ixt.config.settings import get_ixt_metadata_dir
+
+CACHE_FILENAME = "asset_patterns.json"
+
+
+def _cache_path() -> Path:
+    return get_ixt_metadata_dir() / CACHE_FILENAME
+
+
+def _make_key(owner: str, repo: str) -> str:
+    return f"{owner}/{repo}"
+
+
+def _load() -> dict[str, str]:
+    path = _cache_path()
+    if not path.exists():
+        return {}
+    try:
+        with path.open(encoding="utf-8") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return {k: v for k, v in data.items() if isinstance(k, str) and isinstance(v, str)}
+
+
+def _atomic_write(data: dict[str, str]) -> None:
+    path = _cache_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix=path.name + ".", suffix=".tmp", dir=str(path.parent))
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, sort_keys=True)
+            f.write("\n")
+        os.replace(tmp, path)
+    except Exception:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def get(owner: str, repo: str) -> str | None:
+    """Return the cached pattern for ``owner/repo``, or None if absent."""
+    return _load().get(_make_key(owner, repo))
+
+
+def set_(owner: str, repo: str, pattern: str) -> None:
+    """Upsert a pattern for ``owner/repo``. Skips the write on no-op."""
+    data = _load()
+    key = _make_key(owner, repo)
+    if data.get(key) == pattern:
+        return
+    data[key] = pattern
+    _atomic_write(data)
+
+
+def invalidate(owner: str, repo: str) -> None:
+    """Drop ``owner/repo`` from the cache if present."""
+    data = _load()
+    key = _make_key(owner, repo)
+    if data.pop(key, None) is not None:
+        _atomic_write(data)