ixt-cli 0.8.0__py3-none-any.whl

ixt/core/upgrade.py

@@ -0,0 +1,596 @@
+"""Upgrade an installed tool to the latest version."""
+
+from __future__ import annotations
+
+import shutil
+import tempfile
+from collections.abc import Iterable, Iterator
+from concurrent.futures import Future, ThreadPoolExecutor, as_completed
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+from ixt.config.models import ToolRecord
+from ixt.config.settings import Settings, get_settings
+from ixt.config.toml import IxtConfig, ToolSpec
+from ixt.core import resolve
+from ixt.core.backend import BackendType, get_backend
+from ixt.core.expose import expose_tool, unexpose_tool
+from ixt.core.install import ToolNotInstalledError, _remove_env_dir
+from ixt.core.locks import tool_lock
+from ixt.libs.logger import get_logger
+from ixt.libs.semver import compare_versions, parse_version
+
+_UPGRADE_ALL_LATEST_WORKERS: Final = 3
+
+__all__ = [
+    "ToolLocalInstallError",
+    "ToolNotInstalledError",
+    "ToolPinnedError",
+    "load_config_pins",
+    "upgrade_all",
+    "upgrade_tool",
+]
+
+
+class ToolLocalInstallError(Exception):
+    """Raised when trying to upgrade a tool installed via ``ixt tool install --from``."""
+
+    def __init__(self, tool_name: str, source_path: str):
+        self.tool_name = tool_name
+        self.source_path = source_path
+        super().__init__(
+            f"'{tool_name}' is a local install — cannot upgrade.\n"
+            f"  Re-run: ixt tool install --from {source_path} --reinstall"
+        )
+
+
+class ToolPinnedError(Exception):
+    """Raised when ``upgrade`` is called on a tool pinned with ``==`` in ixt.toml.
+
+    Carries the pinned version and (if resolvable) the latest available version
+    so the CLI can show an informational skip rather than treating it as a
+    failure.
+    """
+
+    def __init__(
+        self,
+        tool_name: str,
+        pinned_version: str,
+        *,
+        latest_available: str | None = None,
+    ):
+        self.tool_name = tool_name
+        self.pinned_version = pinned_version
+        self.latest_available = latest_available
+        super().__init__(f"Tool '{tool_name}' is pinned to {pinned_version} in ixt.toml")
+
+
+@dataclass(frozen=True, slots=True)
+class _PrefetchJob:
+    name: str
+    record: ToolRecord
+    bt: BackendType
+    main_spec: str
+    config_spec: ToolSpec | None
+
+
+@dataclass(frozen=True, slots=True)
+class _PendingUpgrade:
+    """A tool queued for the real upgrade, carrying any pre-resolved data.
+
+    ``config_checked`` mirrors the ``latest_checked`` convention: when True,
+    ``upgrade_tool`` trusts ``config_spec`` instead of reloading ixt.toml.
+    """
+
+    name: str
+    latest_checked: bool = False
+    latest_version: str | None = None
+    config_checked: bool = False
+    config_spec: ToolSpec | None = None
+
+
+def _load_discovered_config() -> IxtConfig | None:
+    """Load the nearest ixt.toml (cwd upward, then global), or None.
+
+    Separated from the per-tool lookup so a batch caller can parse the file
+    once and reuse the result across every installed tool.
+    """
+    from ixt.config.toml import find_config_file, load_config
+
+    path = find_config_file()
+    if path is None:
+        return None
+    try:
+        return load_config(path)
+    except (OSError, ValueError) as exc:
+        get_logger("upgrade").debug(f"Could not load config at {path}: {exc}")
+        return None
+
+
+def _spec_in_config(config: IxtConfig | None, tool_name: str) -> ToolSpec | None:
+    """Return the ToolSpec for *tool_name* within an already-loaded *config*."""
+    if config is None:
+        return None
+
+    spec = config.tools.get(tool_name)
+    if spec is not None:
+        return spec
+    try:
+        from ixt.core.apply import _normalize_config_for_apply
+
+        normalized = _normalize_config_for_apply(config, get_settings())
+    except ValueError as exc:
+        get_logger("upgrade").debug(f"Could not normalize config: {exc}")
+    else:
+        spec = normalized.tools.get(tool_name)
+        if spec is not None:
+            return spec
+    for key, candidate in config.tools.items():
+        if "/" in key and key.rsplit("/", 1)[1] == tool_name:
+            return candidate
+    return None
+
+
+def _lookup_spec_in_config(tool_name: str) -> ToolSpec | None:
+    """Return the ToolSpec for *tool_name* from the discovered ixt.toml, or None."""
+    return _spec_in_config(_load_discovered_config(), tool_name)
+
+
+def load_config_pins(tool_names: Iterable[str]) -> dict[str, str | None]:
+    """Return ``{name: exact-pin-or-None}`` resolved from a single config load.
+
+    A batch command (``upgrade --all --dry-run``) parses ``ixt.toml`` once
+    instead of once per tool.
+    """
+    config = _load_discovered_config()
+    return {name: _pin_from_spec(_spec_in_config(config, name)) for name in tool_names}
+
+
+def _pin_from_spec(spec: ToolSpec | None) -> str | None:
+    """Return the exact pin (``==X.Y.Z``) declared by *spec*, or None."""
+    if spec is None or not spec.version:
+        return None
+    version = spec.version.strip()
+    return version if version.startswith("==") else None
+
+
+def _constraint_from_spec(spec: ToolSpec | None) -> str | None:
+    """Return the raw version constraint declared by *spec*, or None."""
+    if spec is None or not spec.version:
+        return None
+    return spec.version.strip() or None
+
+
+def _cached_resolution(
+    bt: BackendType, resolve_spec: str, tool_name: str, *, settings: Settings
+) -> str | None:
+    """Return a cached resolved version for this tool, or None if stale/missing.
+
+    For Python/Node, the resolver indexes by package name; for Binary, by
+    ``owner/repo`` (no tag).
+    """
+    from ixt.core import resolve_cache
+
+    key_spec = tool_name if bt != BackendType.BINARY else resolve_spec
+    return resolve_cache.get(resolve_cache.make_key(bt.value, key_spec), settings=settings)
+
+
+def _pin_spec(bt: BackendType, main_spec: str, tool_name: str, version: str) -> str:
+    """Build a backend-specific install spec pinned to *version*."""
+    if bt == BackendType.PYTHON:
+        return f"{tool_name}=={version}"
+    if bt == BackendType.NODE:
+        return f"{tool_name}@{version}"
+    # Binary: owner/repo@tag (keep the 'v' prefix if upstream uses it).
+    return f"{main_spec}@{version}"
+
+
+def _strip_binary_pin(bt: BackendType, spec: str) -> str:
+    """For binary backend, drop the ``@tag`` suffix so we resolve latest."""
+    if bt == BackendType.BINARY:
+        from ixt.net.source import strip_version_suffix
+
+        return strip_version_suffix(spec)
+    return spec
+
+
+def _raise_if_pinned(
+    record: ToolRecord,
+    bt: BackendType,
+    main_spec: str,
+    settings: Settings,
+    *,
+    config_spec: ToolSpec | None,
+    latest_checked: bool = False,
+    latest_version: str | None = None,
+    use_cache: bool = True,
+) -> None:
+    """Raise ToolPinnedError if the tool is pinned with ``==`` in ixt.toml.
+
+    The error surfaces ``record.name`` (user-facing identifier) but the
+    resolve cache is keyed by the underlying package name.
+    """
+    pinned = _pin_from_spec(config_spec)
+    if pinned is None:
+        return
+
+    latest = (
+        latest_version
+        if latest_checked
+        else _resolve_latest_for_upgrade(
+            record, bt, main_spec, settings=settings, use_cache=use_cache
+        )
+    )
+    raise ToolPinnedError(record.name, pinned, latest_available=latest)
+
+
+def _resolve_install_spec(
+    record: ToolRecord,
+    bt: BackendType,
+    main_spec: str,
+    settings: Settings,
+    *,
+    config_spec: ToolSpec | None,
+    use_cache: bool = True,
+) -> str:
+    """Apply cached resolution or a declared range from ixt.toml to *main_spec*."""
+    # Honor a declared range from ixt.toml (e.g. ``>=1.0,<2.0``) so the
+    # backend resolves within bounds. Binary backend only understands
+    # exact tags, so skip it there.
+    constraint = _constraint_from_spec(config_spec)
+    if constraint and not constraint.startswith("==") and bt != BackendType.BINARY:
+        return f"{record.pkg()}{constraint}"
+
+    if use_cache:
+        cached_version = _cached_resolution(bt, main_spec, record.pkg(), settings=settings)
+        if cached_version is not None and bt != BackendType.BINARY:
+            return _pin_spec(bt, main_spec, record.pkg(), cached_version)
+    return main_spec
+
+
+def _has_range_constraint(bt: BackendType, config_spec: ToolSpec | None) -> bool:
+    constraint = _constraint_from_spec(config_spec)
+    return bool(constraint and not constraint.startswith("==") and bt != BackendType.BINARY)
+
+
+def _versions_match_current(bt: BackendType, installed: str | None, latest: str | None) -> bool:
+    """Return True when *latest* is the already-installed version.
+
+    Python and Node versions are compared as exact registry strings. Binary
+    release tags may differ only by a leading ``v`` or semver padding.
+    """
+    if not installed or not latest:
+        return False
+    installed_norm = installed.removeprefix("v")
+    latest_norm = latest.removeprefix("v")
+    if installed_norm == latest_norm:
+        return True
+    if bt != BackendType.BINARY:
+        return False
+    return (
+        parse_version(installed) is not None
+        and parse_version(latest) is not None
+        and compare_versions(installed, latest) == 0
+    )
+
+
+def _resolve_latest_for_upgrade(
+    record: ToolRecord,
+    bt: BackendType,
+    main_spec: str,
+    *,
+    settings: Settings,
+    use_cache: bool = True,
+) -> str | None:
+    if use_cache:
+        latest = _cached_resolution(bt, main_spec, record.pkg(), settings=settings)
+        if latest is not None:
+            return latest
+    return resolve.resolve_latest(bt, main_spec, use_cache=use_cache, settings=settings)
+
+
+def _can_prefetch_latest(record: ToolRecord, bt: BackendType, config_spec: ToolSpec | None) -> bool:
+    if record.source == "local":
+        return False
+    if record.injected:
+        return False
+    return not _has_range_constraint(bt, config_spec)
+
+
+def _node_runtime_kwargs(bt: BackendType, env_dir: Path) -> dict[str, str]:
+    """Return ``{'runtime': ...}`` for node envs that stored a runtime hint."""
+    if bt != BackendType.NODE:
+        return {}
+    from ixt.backends.node import read_metadata as read_node_meta
+
+    node_meta = read_node_meta(env_dir)
+    if node_meta and node_meta.get("runtime"):
+        return {"runtime": node_meta["runtime"]}
+    return {}
+
+
+def _backup_env_dir(env_dir: Path, settings: Settings) -> Path:
+    """Copy *env_dir* to a per-transaction backup directory."""
+    backup_root = settings.envs_dir / ".ixt-backups"
+    backup_root.mkdir(parents=True, exist_ok=True)
+    txn_dir = Path(tempfile.mkdtemp(prefix=f"{env_dir.name}-", dir=backup_root))
+    backup_env = txn_dir / "env"
+    shutil.copytree(env_dir, backup_env, symlinks=True)
+    return backup_env
+
+
+def _cleanup_backup(backup_env: Path, settings: Settings) -> None:
+    _remove_env_dir(backup_env.parent, settings, ignore_errors=True)
+
+
+def _restore_upgrade_backup(
+    record: ToolRecord,
+    backup_env: Path,
+    settings: Settings,
+    *,
+    failed_stage: str,
+    old_version: str | None,
+    new_version: str | None,
+    original_error: Exception,
+) -> Exception | None:
+    """Restore the previous env and shims. Return rollback error, if any."""
+    log = get_logger("upgrade")
+    env_dir = Path(record.env_dir)
+    log.warn(
+        "upgrade failed during "
+        f"{failed_stage}; restoring {record.name} "
+        f"(old={old_version or '?'}, new={new_version or '?'}, backup={backup_env})"
+    )
+    try:
+        _remove_env_dir(env_dir, settings, ignore_errors=True)
+        shutil.copytree(backup_env, env_dir, symlinks=True)
+        restored = ToolRecord.load_json(env_dir / "ixt.json")
+        restored.exposed_bins = dict(record.exposed_bins)
+        unexpose_tool(record.exposed_bins, settings.bin_dir)
+        result = expose_tool(
+            restored.pkg(),
+            get_backend(BackendType(restored.backend), settings=settings),
+            env_dir,
+            settings.bin_dir,
+            restored.expose_rules,
+            overwrite=True,
+        )
+        restored.exposed_bins = result.linked or dict(record.exposed_bins)
+        restored.save_json(settings.get_tool_metadata_file(record.name))
+        log.warn(f"rollback restored {record.name} after {type(original_error).__name__}")
+        return None
+    except Exception as rollback_error:
+        log.error(
+            f"rollback failed for {record.name}: {rollback_error}; "
+            f"manual backup remains at {backup_env}"
+        )
+        return rollback_error
+
+
+def upgrade_tool(
+    tool_name: str,
+    *,
+    settings: Settings | None = None,
+    ignore_pin: bool = False,
+    use_cache: bool = True,
+    _latest_checked: bool = False,
+    _latest_version: str | None = None,
+    _config_checked: bool = False,
+    _config_spec: ToolSpec | None = None,
+) -> tuple[ToolRecord, str | None]:
+    """Upgrade an installed tool and re-expose its binaries.
+
+    Returns ``(updated_record, old_version)``.
+
+    Raises ``ToolPinnedError`` when the tool is pinned with ``==`` in ixt.toml
+    and *ignore_pin* is False. The error carries the pinned version and, if
+    it could be resolved, the latest upstream version.
+    """
+    settings = settings or get_settings()
+    with tool_lock(tool_name, settings=settings):
+        meta_file = settings.get_tool_metadata_file(tool_name)
+
+        if not meta_file.exists():
+            raise ToolNotInstalledError(tool_name)
+
+        record = ToolRecord.load_json(meta_file)
+
+        if record.source == "local":
+            raise ToolLocalInstallError(record.name, record.spec)
+
+        old_version = record.version
+        env_dir = Path(record.env_dir)
+        bt = BackendType(record.backend)
+        if bt == BackendType.BINARY and record.injected:
+            raise ValueError("Binary backend does not support injected packages")
+        backend = get_backend(bt, settings=settings)
+
+        main_spec = _strip_binary_pin(bt, record.spec)
+        config_spec = _config_spec if _config_checked else _lookup_spec_in_config(record.name)
+
+        if not ignore_pin:
+            _raise_if_pinned(
+                record,
+                bt,
+                main_spec,
+                settings,
+                config_spec=config_spec,
+                latest_checked=_latest_checked,
+                latest_version=_latest_version,
+                use_cache=use_cache,
+            )
+
+        latest: str | None = None
+        if not record.injected and not _has_range_constraint(bt, config_spec):
+            latest = (
+                _latest_version
+                if _latest_checked
+                else _resolve_latest_for_upgrade(
+                    record, bt, main_spec, settings=settings, use_cache=use_cache
+                )
+            )
+            if _versions_match_current(bt, old_version, latest):
+                return record, old_version
+
+        main_spec = _resolve_install_spec(
+            record, bt, main_spec, settings, config_spec=config_spec, use_cache=use_cache
+        )
+
+        rollback_record = ToolRecord.load_json(meta_file)
+        backup_env = _backup_env_dir(env_dir, settings)
+        stage = "install"
+        new_version: str | None = None
+        try:
+            # Reinstall main + injected with --upgrade.
+            all_specs = [main_spec] if bt == BackendType.BINARY else [main_spec, *record.injected]
+            upgrade_kwargs: dict = {"upgrade": True, **_node_runtime_kwargs(bt, env_dir)}
+            # The latest tag was just resolved above; hand it to the binary fast-path
+            # so it doesn't re-issue the ``releases/latest`` HEAD it already paid for.
+            if bt == BackendType.BINARY and latest:
+                upgrade_kwargs["known_tag"] = latest
+            if bt == BackendType.BINARY:
+                upgrade_kwargs["use_cache"] = use_cache
+            backend.install_packages(env_dir, all_specs, **upgrade_kwargs)
+
+            stage = "version-read"
+            new_version = backend.installed_version(env_dir, record.pkg())
+
+            stage = "unexpose"
+            unexpose_tool(record.exposed_bins, settings.bin_dir)
+            stage = "expose"
+            result = expose_tool(
+                record.pkg(),
+                backend,
+                env_dir,
+                settings.bin_dir,
+                record.expose_rules,
+                overwrite=True,
+            )
+
+            stage = "metadata"
+            record.version = new_version
+            record.exposed_bins = result.linked
+            record.save_json(meta_file)
+        except Exception as exc:
+            rollback_error = _restore_upgrade_backup(
+                rollback_record,
+                backup_env,
+                settings,
+                failed_stage=stage,
+                old_version=old_version,
+                new_version=new_version,
+                original_error=exc,
+            )
+            if rollback_error is not None:
+                raise RuntimeError(
+                    f"upgrade failed during {stage}; rollback failed: {rollback_error}"
+                ) from exc
+            raise
+        _cleanup_backup(backup_env, settings)
+        return record, old_version
+
+
+def upgrade_all(
+    *,
+    settings: Settings | None = None,
+    use_cache: bool = True,
+) -> Iterator[tuple[str, tuple[ToolRecord, str | None] | Exception]]:
+    """Upgrade every installed tool. Yields ``(name, result)`` as each completes.
+
+    *result* is either ``(updated_record, old_version)`` on success, or an
+    Exception (``ToolPinnedError``, ``ToolLocalInstallError``, or any other
+    failure surfaced by ``upgrade_tool``).
+
+    The generator drives one upgrade per ``next()`` call so callers can stream
+    progress lines as they happen. Materialise via ``dict(upgrade_all())`` if
+    you want the legacy map shape.
+    """
+    settings = settings or get_settings()
+    meta_files = settings.iter_installed_metadata()
+    config = _load_discovered_config()
+    prefetches: dict[Future[str | None], _PrefetchJob] = {}
+    queued: list[_PendingUpgrade] = []
+    with ThreadPoolExecutor(max_workers=_UPGRADE_ALL_LATEST_WORKERS) as executor:
+        for meta_file in meta_files:
+            name = meta_file.parent.name
+            try:
+                record = ToolRecord.load_json(meta_file)
+                bt = BackendType(record.backend)
+                main_spec = _strip_binary_pin(bt, record.spec)
+                config_spec = _spec_in_config(config, record.name)
+            except Exception:
+                queued.append(_PendingUpgrade(name))
+                continue
+            if record.source == "local":
+                yield name, ToolLocalInstallError(record.name, record.spec)
+                continue
+            if _can_prefetch_latest(record, bt, config_spec):
+                prefetches[
+                    executor.submit(
+                        _resolve_latest_for_upgrade,
+                        record,
+                        bt,
+                        main_spec,
+                        settings=settings,
+                        use_cache=use_cache,
+                    )
+                ] = _PrefetchJob(
+                    name=name,
+                    record=record,
+                    bt=bt,
+                    main_spec=main_spec,
+                    config_spec=config_spec,
+                )
+            else:
+                queued.append(_PendingUpgrade(name, config_checked=True, config_spec=config_spec))
+
+        for future in as_completed(prefetches):
+            job = prefetches[future]
+            latest_checked = True
+            latest_version = None
+            try:
+                latest_version = future.result()
+            except Exception:
+                latest_checked = False
+
+            pinned = _pin_from_spec(job.config_spec)
+            if pinned is not None:
+                yield (
+                    job.name,
+                    ToolPinnedError(
+                        job.record.name,
+                        pinned,
+                        latest_available=latest_version,
+                    ),
+                )
+                continue
+            if _versions_match_current(job.bt, job.record.version, latest_version):
+                yield job.name, (job.record, job.record.version)
+                continue
+            queued.append(
+                _PendingUpgrade(
+                    job.name,
+                    latest_checked=latest_checked,
+                    latest_version=latest_version,
+                    config_checked=True,
+                    config_spec=job.config_spec,
+                )
+            )
+
+        for item in queued:
+            try:
+                yield (
+                    item.name,
+                    upgrade_tool(
+                        item.name,
+                        settings=settings,
+                        use_cache=use_cache,
+                        _latest_checked=item.latest_checked,
+                        _latest_version=item.latest_version,
+                        _config_checked=item.config_checked,
+                        _config_spec=item.config_spec,
+                    ),
+                )
+            except Exception as exc:
+                yield item.name, exc

ixt/data/__init__.py

@@ -0,0 +1,10 @@
+"""Embedded data files (heuristics.toml, registry.toml)."""
+
+from pathlib import Path
+
+DATA_DIR = Path(__file__).parent
+
+
+def get_data_path(filename: str) -> Path:
+    """Return the absolute path to an embedded data file."""
+    return DATA_DIR / filename