ixt-cli 0.8.0__py3-none-any.whl

ixt/core/resolve.py

@@ -0,0 +1,150 @@
+"""Version resolver — dispatches to backend-specific registry clients.
+
+Consults the TTL cache first; on miss, performs the HTTP call and writes
+back to the cache. Never raises on network errors: returns None so callers
+(e.g. ``upgrade --dry-run``) can fail tool-by-tool.
+"""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import TYPE_CHECKING, Final
+
+from ixt.config.settings import Settings, get_settings
+from ixt.core import resolve_cache
+from ixt.core.backend import BackendType
+from ixt.core.resolution_stats import (
+    record_github_latest_redirect,
+    resolution_phase,
+)
+from ixt.libs.logger import get_logger
+
+if TYPE_CHECKING:
+    from ixt.net.source import Release
+
+# Cap concurrent registry calls so `upgrade --all [--dry-run]` parallelizes
+# without hammering PyPI / npm / GitHub.
+_RESOLVE_MAX_WORKERS: Final = 3
+
+
+def _resolve_python(name: str) -> tuple[str, str, list[dict] | None]:
+    from ixt.net import pypi
+
+    version = pypi.get_latest_version(name)
+    return version, pypi.latest_version_url(name), None
+
+
+def _resolve_node(name: str) -> tuple[str, str, list[dict] | None]:
+    from ixt.net import npm
+
+    version = npm.get_latest_version(name)
+    return version, npm.latest_version_url(name), None
+
+
+def _resolve_binary(spec: str) -> tuple[str, str, list[dict] | None]:
+    from ixt.backends.binary import make_source
+    from ixt.config.asset_index import is_github_api_allowed
+    from ixt.net.source import parse_spec
+
+    repo_spec = parse_spec(spec)
+    if repo_spec is None:
+        raise ValueError(f"Not a binary spec: {spec!r}")
+
+    if repo_spec.platform == "github":
+        from ixt.net.github_api import fetch_latest_tag
+
+        tag = fetch_latest_tag(repo_spec.owner, repo_spec.repo)
+        record_github_latest_redirect(repo_spec.owner, repo_spec.repo, hit=bool(tag))
+        if tag:
+            # Cheap HEAD-redirect path: tag only, no assets fetched. The
+            # install reconstructs the asset URL from the cached pattern.
+            src_url = f"{repo_spec.host}/{repo_spec.owner}/{repo_spec.repo}@{tag}"
+            return tag, src_url, None
+
+        if not is_github_api_allowed():
+            raise RuntimeError("IXT_GITHUB_API=never is set and latest redirect failed")
+
+    source = make_source(repo_spec)
+    release = source.get_latest_release(repo_spec.owner, repo_spec.repo)
+    src_url = f"{repo_spec.host}/{repo_spec.owner}/{repo_spec.repo}@{release.tag}"
+    return release.tag, src_url, _assets_to_dicts(release)
+
+
+def _assets_to_dicts(release: Release) -> list[dict]:
+    """Serialize a release's assets for the resolve cache."""
+    return [{"name": a.name, "url": a.url, "size": a.size} for a in release.assets]
+
+
+def resolve_latest(
+    backend: BackendType,
+    spec: str,
+    *,
+    use_cache: bool = True,
+    settings: Settings | None = None,
+) -> str | None:
+    """Return the latest upstream version for (backend, spec), or None on failure.
+
+    On success, writes the result to the TTL cache. On HTTP/parse failure,
+    returns None without raising.
+    """
+    settings = settings or get_settings()
+    key = resolve_cache.make_key(backend.value, spec)
+
+    if use_cache:
+        cached = resolve_cache.get(key, settings=settings)
+        if cached is not None:
+            return cached
+
+    with resolution_phase("version"):
+        try:
+            if backend == BackendType.PYTHON:
+                version, source, assets = _resolve_python(spec)
+            elif backend == BackendType.NODE:
+                version, source, assets = _resolve_node(spec)
+            elif backend == BackendType.BINARY:
+                version, source, assets = _resolve_binary(spec)
+            else:
+                return None
+        except Exception as exc:
+            # Intentionally broad: per-tool isolation (see module docstring).
+            get_logger("resolve").debug(
+                f"resolve_latest({backend.value}, {spec!r}) failed: {type(exc).__name__}: {exc}"
+            )
+            return None
+
+    resolve_cache.set_(key, version, source=source, assets=assets, settings=settings)
+    return version
+
+
+def resolve_latest_many(
+    requests: list[tuple[str, BackendType, str]],
+    *,
+    use_cache: bool = True,
+    settings: Settings | None = None,
+) -> dict[str, str | None]:
+    """Resolve the latest version for many ``(key, backend, spec)`` in parallel.
+
+    Returns ``{key: version-or-None}``. Each resolution is independent and
+    never raises (``resolve_latest`` swallows network errors), so one slow or
+    failing tool does not block the rest. Honors the TTL cache per entry unless
+    *use_cache* is False (then every entry is re-resolved upstream).
+    """
+    settings = settings or get_settings()
+    if not requests:
+        return {}
+    results: dict[str, str | None] = {}
+    workers = min(_RESOLVE_MAX_WORKERS, len(requests))
+    with ThreadPoolExecutor(max_workers=workers) as executor:
+        futures = {
+            executor.submit(
+                resolve_latest, backend, spec, use_cache=use_cache, settings=settings
+            ): key
+            for key, backend, spec in requests
+        }
+        for future in as_completed(futures):
+            key = futures[future]
+            try:
+                results[key] = future.result()
+            except Exception:
+                results[key] = None
+    return results

ixt/core/resolve_cache.py

@@ -0,0 +1,185 @@
+"""TTL cache for resolved tool versions (PyPI / npm / GH latest).
+
+Populated by ``ixt tool upgrade --dry-run`` and consumed by the real ``upgrade``
+so that a user who runs dry-run followed by the actual command within the
+TTL window does not pay for two network resolutions.
+
+Schema is forward-compatible with a future ``ixt.lock`` (phase 6): entries
+already carry ``source``, leaving room for ``integrity`` / ``asset_url``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ixt.config.settings import Settings, get_settings
+
+DEFAULT_TTL_SECONDS = 420  # 7 minutes
+CACHE_FILENAME = "resolve.json"
+_CACHE_LOCK = threading.Lock()
+
+
+def _ttl_seconds() -> int:
+    override = os.environ.get("IXT_RESOLVE_TTL")
+    if override:
+        try:
+            return max(0, int(override))
+        except ValueError:
+            pass
+    return DEFAULT_TTL_SECONDS
+
+
+def ttl_seconds() -> int:
+    """Public accessor for the active cache TTL (honors ``IXT_RESOLVE_TTL``)."""
+    return _ttl_seconds()
+
+
+def min_remaining_ttl(settings: Settings | None = None) -> int | None:
+    """Seconds until the soonest-expiring fresh entry, or None.
+
+    Returns None when caching is disabled (TTL ≤ 0) or no fresh entry exists.
+    Lets the CLI tell the user *when* an instant (cached) run stops being
+    instant, rather than just the static TTL.
+    """
+    ttl = _ttl_seconds()
+    if ttl <= 0:
+        return None
+    settings = settings or get_settings()
+    now = datetime.now(timezone.utc)
+    remaining: list[int] = []
+    for entry in _load(settings)["entries"].values():
+        if not isinstance(entry, dict):
+            continue
+        resolved_at = _parse_iso(entry.get("resolved_at", ""))
+        if resolved_at is None:
+            continue
+        age = (now - resolved_at).total_seconds()
+        if age <= ttl:
+            remaining.append(int(ttl - age))
+    return min(remaining) if remaining else None
+
+
+def _cache_path(settings: Settings) -> Path:
+    return settings.metadata_dir / CACHE_FILENAME
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _parse_iso(value: str) -> datetime | None:
+    try:
+        return datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+    except (ValueError, TypeError):
+        return None
+
+
+def _load(settings: Settings) -> dict:
+    path = _cache_path(settings)
+    if not path.exists():
+        return {"entries": {}}
+    try:
+        with path.open(encoding="utf-8") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return {"entries": {}}
+    if not isinstance(data, dict) or "entries" not in data:
+        return {"entries": {}}
+    return data
+
+
+def _atomic_write(path: Path, data: dict) -> None:
+    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)
+        os.replace(tmp, path)
+    except Exception:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def _is_fresh(entry: object) -> bool:
+    """True if *entry* is a dict with a ``resolved_at`` still within TTL."""
+    if not isinstance(entry, dict) or "version" not in entry:
+        return False
+    resolved_at = _parse_iso(entry.get("resolved_at", ""))
+    if resolved_at is None:
+        return False
+    age = (datetime.now(timezone.utc) - resolved_at).total_seconds()
+    return age <= _ttl_seconds()
+
+
+def get_entry(key: str, *, settings: Settings | None = None) -> dict | None:
+    """Return the full cache entry for *key* if within TTL, else None."""
+    settings = settings or get_settings()
+    entry = _load(settings)["entries"].get(key)
+    return entry if _is_fresh(entry) else None
+
+
+def get(key: str, *, settings: Settings | None = None) -> str | None:
+    """Return the cached version for *key* if within TTL, else None."""
+    entry = get_entry(key, settings=settings)
+    return entry["version"] if entry else None
+
+
+def set_(
+    key: str,
+    version: str,
+    *,
+    source: str | None = None,
+    assets: list[dict] | None = None,
+    settings: Settings | None = None,
+) -> None:
+    """Write *version* for *key* with current timestamp.
+
+    *assets* (when given) records the resolved release's downloadable assets
+    (``[{"name", "url", "size"}, …]``) so a later install can rebuild the
+    release without a second API call — used by binary backends whose asset
+    URLs can't be reconstructed from a pattern (GitLab).
+
+    Skips the disk write only when the existing entry is identical *and still
+    fresh* — a no-op refresh inside the TTL window isn't worth a rewrite. When
+    the entry is stale, we always rewrite so ``resolved_at`` is bumped and the
+    TTL window restarts; otherwise a stable-version tool would expire once and
+    never re-warm (every later resolve would re-hit the network).
+    """
+    settings = settings or get_settings()
+    with _CACHE_LOCK:
+        data = _load(settings)
+        existing = data["entries"].get(key)
+        if (
+            isinstance(existing, dict)
+            and existing.get("version") == version
+            and existing.get("source") == source
+            and existing.get("assets") == assets
+            and _is_fresh(existing)
+        ):
+            return
+        entry: dict = {"version": version, "resolved_at": _now_iso()}
+        if source:
+            entry["source"] = source
+        if assets:
+            entry["assets"] = assets
+        data["entries"][key] = entry
+        _atomic_write(_cache_path(settings), data)
+
+
+def invalidate(key: str, *, settings: Settings | None = None) -> None:
+    """Remove *key* from the cache if present."""
+    settings = settings or get_settings()
+    with _CACHE_LOCK:
+        data = _load(settings)
+        if data["entries"].pop(key, None) is not None:
+            _atomic_write(_cache_path(settings), data)
+
+
+def make_key(backend: str, spec: str) -> str:
+    """Compose a stable cache key."""
+    return f"{backend}:{spec}"

ixt/core/runtimes.py

@@ -0,0 +1,192 @@
+"""Inspect and prune ixt-managed runtime binaries."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from ixt.config.models import ToolRecord
+from ixt.config.settings import Settings, get_settings
+from ixt.core.cache import count_and_size
+from ixt.libs.shell import ShellError, shell_run_output
+
+RuntimeName = Literal["uv", "bun"]
+
+
+@dataclass(slots=True, frozen=True)
+class RuntimeStatus:
+    """Status of one ixt-managed runtime."""
+
+    name: RuntimeName
+    path: Path
+    present: bool
+    files: int
+    bytes: int
+    version: str | None
+    used_by: tuple[str, ...]
+    prune_reason: str
+
+    @property
+    def used(self) -> bool:
+        return bool(self.used_by)
+
+    @property
+    def prunable(self) -> bool:
+        return self.present and not self.used
+
+
+@dataclass(slots=True, frozen=True)
+class RuntimePruneResult:
+    """Outcome of a runtime prune action."""
+
+    name: RuntimeName
+    path: Path
+    removed: bool
+    files: int
+    bytes: int
+    reason: str
+
+
+def runtime_statuses(*, settings: Settings | None = None) -> list[RuntimeStatus]:
+    """Return status for known ixt-managed runtimes.
+
+    Only runtimes under ``$IXT_HOME/installed/runtimes`` are considered
+    ixt-managed. System runtimes on ``PATH`` are intentionally out of scope.
+    """
+    settings = settings or get_settings()
+    bun_users = _bun_runtime_users(settings)
+    specs: list[tuple[RuntimeName, Path, tuple[str, ...], str]] = [
+        ("uv", settings.uv_runtime, (), "Python tools do not need managed uv at runtime"),
+        (
+            "bun",
+            settings.bun_runtime,
+            tuple(sorted(bun_users)),
+            "kept for node tools that may run through managed bun"
+            if bun_users
+            else "no installed node tool depends on managed bun",
+        ),
+    ]
+
+    statuses: list[RuntimeStatus] = []
+    for name, path, used_by, reason in specs:
+        files, bytes_ = count_and_size(path)
+        present = path.exists()
+        statuses.append(
+            RuntimeStatus(
+                name=name,
+                path=path,
+                present=present,
+                files=files,
+                bytes=bytes_,
+                version=_runtime_version(path) if present else None,
+                used_by=used_by,
+                prune_reason=reason,
+            )
+        )
+    return statuses
+
+
+def prune_runtimes(
+    *,
+    settings: Settings | None = None,
+    all_: bool = False,
+) -> list[RuntimePruneResult]:
+    """Remove ixt-managed runtimes.
+
+    By default, removes only unused runtimes. With *all_* true, removes every
+    known ixt-managed runtime present under ``$IXT_HOME/installed/runtimes``.
+    Installed environments, shims, config, and downloaded archives are never
+    touched.
+    """
+    settings = settings or get_settings()
+    results: list[RuntimePruneResult] = []
+    for status in runtime_statuses(settings=settings):
+        should_remove = status.present and (all_ or status.prunable)
+        if not should_remove:
+            reason = "not installed" if not status.present else status.prune_reason
+            results.append(
+                RuntimePruneResult(
+                    name=status.name,
+                    path=status.path,
+                    removed=False,
+                    files=0,
+                    bytes=0,
+                    reason=reason,
+                )
+            )
+            continue
+
+        files, bytes_ = count_and_size(status.path)
+        _remove_runtime_path(status.path)
+        results.append(
+            RuntimePruneResult(
+                name=status.name,
+                path=status.path,
+                removed=True,
+                files=files,
+                bytes=bytes_,
+                reason="removed by --all" if all_ else status.prune_reason,
+            )
+        )
+    return results
+
+
+def _remove_runtime_path(path: Path) -> None:
+    if path.is_dir() and not path.is_symlink():
+        shutil.rmtree(path)
+    else:
+        path.unlink(missing_ok=True)
+
+
+def _runtime_version(path: Path) -> str | None:
+    if not path.is_file():
+        return None
+    try:
+        output = shell_run_output([str(path), "--version"])
+    except (OSError, ShellError):
+        return None
+    first = output.strip().splitlines()[0] if output.strip() else ""
+    return first or None
+
+
+def _bun_runtime_users(settings: Settings) -> set[str]:
+    users: set[str] = set()
+    for meta_path in settings.iter_installed_metadata():
+        try:
+            record = ToolRecord.load_json(meta_path)
+        except (OSError, ValueError, KeyError, json.JSONDecodeError):
+            continue
+        if record.backend != "node":
+            continue
+        if _node_record_uses_managed_bun(record):
+            users.add(record.name)
+    return users
+
+
+def _node_record_uses_managed_bun(record: ToolRecord) -> bool:
+    if record.node_shim is False:
+        return False
+
+    node_meta = _read_node_metadata(Path(record.env_dir))
+    if node_meta is None:
+        return True
+    if node_meta.get("runtime") == "node":
+        return False
+    if node_meta.get("used_npm_fallback") is True:
+        return False
+    return True
+
+
+def _read_node_metadata(env_dir: Path) -> dict | None:
+    path = env_dir / "node_metadata.json"
+    if not path.exists():
+        return None
+    try:
+        with path.open(encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None