ixt-cli 0.9.1__tar.gz → 0.10.1__tar.gz

{ixt_cli-0.9.1 → ixt_cli-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: ixt-cli
-Version: 0.9.1
+Version: 0.10.1
 Summary: Universal CLI tool isolator - manage Python, Node, and binary tools with per-tool isolation
 Project-URL: Homepage, https://gitlab.com/pytgaen-group/ixt
 Project-URL: Repository, https://gitlab.com/pytgaen-group/ixt.git
@@ -223,7 +223,7 @@ resolve upstream again and refresh the lock.
 | `ixt tool apply --locked --strict`             | Sync using exact versions and assets from ixt.lock                    |
 | `ixt tool export`                              | Export installed tools as ixt.toml (stdout), preserves install intent |
 | `ixt lock write`                               | Resolve ixt.toml and write ixt.lock                                   |
-| `ixt lock check`                               | Validate ixt.lock against ixt.toml locally                             |
+| `ixt lock check`                               | Validate ixt.lock against ixt.toml locally                            |
 | `ixt lock diff`                                | Show semantic differences between ixt.toml and ixt.lock               |
 | `ixt asset-index export`                       | Export portable binary-resolution metadata as JSON                    |
 | `ixt tool config <pkg> expose <rules...>`      | Change exposed binaries                                               |
@@ -232,6 +232,7 @@ resolve upstream again and refresh the lock.
 | `ixt tool config __all__ expose <rules...>`    | Re-expose every installed tool                                        |
 | `ixt tool shell <pkg>`                         | Open a subshell in tool's env                                         |
 | `ixt tool where <pkg>`                         | Print the tool env path                                               |
+| `ixt exec [--sudo] <tool> -- <args...>`        | Run an exposed tool by name, without relying on PATH                  |
 | `ixt environment [--sizes]`                    | Show ixt configuration, paths, and optional storage sizes             |
 | `ixt doctor`                                   | Check ixt health (runtimes, PATH, caches)                             |
 | `ixt cache info`                               | Show cache paths and sizes                                            |

{ixt_cli-0.9.1 → ixt_cli-0.10.1}/README.md

@@ -194,7 +194,7 @@ resolve upstream again and refresh the lock.
 | `ixt tool apply --locked --strict`             | Sync using exact versions and assets from ixt.lock                    |
 | `ixt tool export`                              | Export installed tools as ixt.toml (stdout), preserves install intent |
 | `ixt lock write`                               | Resolve ixt.toml and write ixt.lock                                   |
-| `ixt lock check`                               | Validate ixt.lock against ixt.toml locally                             |
+| `ixt lock check`                               | Validate ixt.lock against ixt.toml locally                            |
 | `ixt lock diff`                                | Show semantic differences between ixt.toml and ixt.lock               |
 | `ixt asset-index export`                       | Export portable binary-resolution metadata as JSON                    |
 | `ixt tool config <pkg> expose <rules...>`      | Change exposed binaries                                               |
@@ -203,6 +203,7 @@ resolve upstream again and refresh the lock.
 | `ixt tool config __all__ expose <rules...>`    | Re-expose every installed tool                                        |
 | `ixt tool shell <pkg>`                         | Open a subshell in tool's env                                         |
 | `ixt tool where <pkg>`                         | Print the tool env path                                               |
+| `ixt exec [--sudo] <tool> -- <args...>`        | Run an exposed tool by name, without relying on PATH                  |
 | `ixt environment [--sizes]`                    | Show ixt configuration, paths, and optional storage sizes             |
 | `ixt doctor`                                   | Check ixt health (runtimes, PATH, caches)                             |
 | `ixt cache info`                               | Show cache paths and sizes                                            |

{ixt_cli-0.9.1 → ixt_cli-0.10.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ixt-cli"
-version = "0.9.1" # to bump
+version = "0.10.1"  # to bump
 description = "Universal CLI tool isolator - manage Python, Node, and binary tools with per-tool isolation"
 readme = "README.md"
 requires-python = ">=3.10"

{ixt_cli-0.9.1 → ixt_cli-0.10.1}/src/ixt/__init__.py

@@ -1,8 +1,6 @@
 """ixt — Universal CLI Tool Isolator"""
 
-from importlib.metadata import version
-
-__version__ = version("ixt-cli")
+__version__ = "0.10.1"  # to bump
 __author__ = "Gaetan"
 
 __all__ = ["__author__", "__version__"]

{ixt_cli-0.9.1 → ixt_cli-0.10.1}/src/ixt/backends/binary.py

@@ -4,7 +4,9 @@ from __future__ import annotations
 
 import hashlib
 import json
+import os
 import re
+import shutil
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import TYPE_CHECKING, TypedDict
@@ -19,7 +21,9 @@ from ixt.config.flags import is_setup_toml_enabled
 from ixt.config.heuristics import (
     get_name_suffix_tokens,
     get_platform_aliases,
+    has_any_token,
     is_asset_arch_compatible,
+    libc_tokens,
     load_heuristics,
     select_asset,
 )
@@ -31,14 +35,17 @@ 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.elf import PREFIX_SIZE as ELF_PREFIX_SIZE
+from ixt.libs.elf import parse_elf, read_elf
 from ixt.libs.logger import get_logger, get_verbosity
-from ixt.net.http import MAX_DOWNLOAD_SIZE, DownloadTooLargeError
+from ixt.net.http import MAX_DOWNLOAD_SIZE, DownloadTooLargeError, get_range
 from ixt.net.source import Asset, Release, ReleaseSource, RepoSpec, parse_spec
 from ixt.platform import get_arch, get_os
 
 __all__ = [
     "AssetSelectionError",
     "BinaryBackend",
+    "BinaryNoExecutableError",
     "BinaryPlatformError",
     "BinarySpecError",
     "HookEntry",
@@ -88,14 +95,27 @@ class SetupMetadata(_SetupMetadataRequired, total=False):
 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]):
+    def __init__(
+        self,
+        spec: str,
+        release_tag: str,
+        asset_names: list[str],
+        unusable: list[tuple[str, str]] | None = None,
+    ):
         self.spec = spec
         self.release_tag = release_tag
         self.asset_names = asset_names
+        self.unusable = unusable or []
         names = ", ".join(asset_names[:10]) or "<none>"
-        super().__init__(
+        message = (
             f"No suitable asset found for '{spec}' (release {release_tag}). Available: {names}"
         )
+        if self.unusable:
+            skipped = ", ".join(
+                f"{name} (needs missing loader {loader})" for name, loader in self.unusable
+            )
+            message += f". Skipped as unrunnable here: {skipped}"
+        super().__init__(message)
 
 
 class BinaryPlatformError(RuntimeError):
@@ -123,6 +143,78 @@ class BinaryPlatformError(RuntimeError):
         )
 
 
+def _empty_dir(path: Path) -> None:
+    """Remove everything inside *path*, keeping the directory itself."""
+    if not path.is_dir():
+        return
+    for entry in path.iterdir():
+        if entry.is_dir() and not entry.is_symlink():
+            shutil.rmtree(entry, ignore_errors=True)
+        else:
+            entry.unlink(missing_ok=True)
+
+
+def _doomed_by_libc(release: Release, rejected: list[tuple[Path, str]], log) -> set[str]:
+    """Return the sibling assets built against a libc this host cannot load.
+
+    A candidate turned down for a missing loader condemns every asset built
+    against the same libc: downloading them to reach the very same verdict is
+    pure waste. Must be called while the rejected files are still on disk.
+    """
+    loaders = set()
+    for path, _label in rejected:
+        info = read_elf(path)
+        if info is not None and info.interpreter and info.loader_missing():
+            loaders.add(info.interpreter)
+    if not loaders:
+        return set()
+
+    cfg = load_heuristics()
+    tokens = sorted({token for loader in loaders for token in libc_tokens(loader, cfg)})
+    if not tokens:
+        return set()
+
+    doomed = {asset.name for asset in release.assets if has_any_token(asset.name, tokens)}
+    if doomed:
+        log.debug(f"skip (needs {'/'.join(tokens)} loader): {sorted(doomed)}")
+    return doomed
+
+
+def _rejection_reason(rejected: list[tuple[Path, str]]) -> str:
+    """Describe why an unpacked asset yielded nothing runnable."""
+    if not rejected:
+        return "no executable inside"
+    return ", ".join(
+        f"{path.name} ({label})" for path, label in sorted(rejected, key=lambda item: str(item[0]))
+    )
+
+
+class BinaryNoExecutableError(RuntimeError):
+    """Raised when the selected asset extracts without a single runnable file."""
+
+    def __init__(
+        self,
+        spec: str,
+        release_tag: str,
+        asset_name: str,
+        alternatives: list[str],
+    ):
+        self.spec = spec
+        self.release_tag = release_tag
+        self.asset_name = asset_name
+        self.alternatives = alternatives
+        message = (
+            f"No executable found in '{asset_name}' for '{spec}' (release {release_tag}). "
+            "The asset carries no runnable file — a shared library, headers or a "
+            "source archive rather than the tool itself."
+        )
+        if alternatives:
+            others = ", ".join(alternatives[:10])
+            message += f" Other assets in this release: {others}."
+        message += " Point --asset-pattern at another asset."
+        super().__init__(message)
+
+
 class BinarySpecError(ValueError):
     """Raised when a spec cannot be parsed as a binary backend spec."""
 
@@ -578,10 +670,7 @@ class BinaryBackend:
         )
         if asset_pattern:
             log.debug(f"user-forced asset_pattern: {asset_pattern!r}")
-        selection_pattern = _selection_pattern(effective_pattern, release.tag)
-        if locked_binary is None:
-            asset = self._select_asset(release, selection_pattern, tool_name, spec)
-        else:
+        if locked_binary is not None:
             asset = release.assets[0]
             if not is_asset_arch_compatible(
                 asset.name,
@@ -589,36 +678,33 @@ class BinaryBackend:
                 declared_platform=locked_binary.platform,
             ):
                 raise AssetSelectionError(spec, release.tag, [asset.name])
-        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()
-        rejected_executables: list[tuple[Path, str]] = []
-        executables = find_executables(
-            result.root,
-            expose=heuristics.expose,
-            log=log,
-            rejected=rejected_executables,
-        )
-        log.debug(f"executables: {[e.name for e in executables]}")
-        if not executables and rejected_executables:
-            raise BinaryPlatformError(spec, release.tag, asset.name, rejected_executables)
+            executables = self._unpack(
+                source,
+                repo_spec,
+                release,
+                asset,
+                env_dir,
+                cache_dir,
+                spec=spec,
+                tool_name=tool_name,
+                setup=setup,
+                upgrade=upgrade,
+                log=log,
+            )
+        else:
+            asset, release, executables = self._unpack_first_runnable(
+                source,
+                repo_spec,
+                release,
+                env_dir,
+                cache_dir,
+                spec=spec,
+                tool_name=tool_name,
+                setup=setup,
+                effective_pattern=effective_pattern,
+                upgrade=upgrade,
+                log=log,
+            )
 
         binaries = {exe.name: str(exe) for exe in executables}
 
@@ -727,29 +813,299 @@ class BinaryBackend:
             )
         return setup
 
+    def _unpack_candidate(
+        self,
+        source: ReleaseSource,
+        repo_spec: RepoSpec,
+        release: Release,
+        asset: Asset,
+        env_dir: Path,
+        cache_dir: Path,
+        *,
+        tool_name: str,
+        setup: SetupConfig | None,
+        upgrade: bool,
+        log,
+    ) -> tuple[list[Path], list[tuple[Path, str]]]:
+        """Download *asset* into *env_dir* and report what can run on this host.
+
+        Returns the runnable executables and, when there are none, the files
+        that were found but rejected as incompatible.
+        """
+        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}")
+
+        rejected: list[tuple[Path, str]] = []
+        executables = find_executables(
+            result.root,
+            expose=load_heuristics().expose,
+            log=log,
+            rejected=rejected,
+        )
+        log.debug(f"executables: {[e.name for e in executables]}")
+        return executables, rejected
+
+    def _unpack(
+        self,
+        source: ReleaseSource,
+        repo_spec: RepoSpec,
+        release: Release,
+        asset: Asset,
+        env_dir: Path,
+        cache_dir: Path,
+        *,
+        spec: str,
+        tool_name: str,
+        setup: SetupConfig | None,
+        upgrade: bool,
+        log,
+    ) -> list[Path]:
+        """Unpack the one asset a lockfile names, which has no fallback."""
+        executables, rejected = self._unpack_candidate(
+            source,
+            repo_spec,
+            release,
+            asset,
+            env_dir,
+            cache_dir,
+            tool_name=tool_name,
+            setup=setup,
+            upgrade=upgrade,
+            log=log,
+        )
+        if executables:
+            return executables
+        if rejected:
+            raise BinaryPlatformError(spec, release.tag, asset.name, rejected)
+        raise BinaryNoExecutableError(spec, release.tag, asset.name, [])
+
+    def _unpack_first_runnable(
+        self,
+        source: ReleaseSource,
+        repo_spec: RepoSpec,
+        release: Release,
+        env_dir: Path,
+        cache_dir: Path,
+        *,
+        spec: str,
+        tool_name: str,
+        setup: SetupConfig | None,
+        effective_pattern: str | None,
+        upgrade: bool,
+        log,
+    ) -> tuple[Asset, Release, list[Path]]:
+        """Try candidates in scoring order until one unpacks to something runnable.
+
+        An archive only says what it holds once unpacked: the tool, a shared
+        library shipped under the same os/arch tokens, or a build this host has
+        no loader for. Rather than fail on an unlucky first pick, a candidate
+        that unpacks to nothing usable is dropped and its siblings get their
+        turn — releases that ship a library beside the binary, or a musl build
+        beside the glibc one, resolve on the second pass.
+        """
+        excluded: set[str] = set()
+        tried: list[str] = []
+        first_rejection: tuple[str, list[tuple[Path, str]]] | None = None
+        relearned = False
+
+        while True:
+            selection_pattern = _selection_pattern(effective_pattern, release.tag)
+            try:
+                asset = self._select_asset(
+                    release,
+                    selection_pattern,
+                    tool_name,
+                    spec,
+                    repo_spec=repo_spec,
+                    exclude=excluded,
+                )
+            except AssetSelectionError:
+                # A synthesized release carries only the asset its pattern named.
+                # If that asset cannot run here, the pattern is wrong for this
+                # host, not merely stale — relearn it against the full release.
+                wider = None if relearned else self._relearn_release(source, repo_spec, release)
+                if wider is not None:
+                    relearned = True
+                    release = wider
+                    continue
+                if first_rejection is not None:
+                    name, rejected = first_rejection
+                    raise BinaryPlatformError(spec, release.tag, name, rejected) from None
+                if tried:
+                    # Nothing in the release unpacked to a runnable file. Name the
+                    # best candidate and let the user point at another asset: an
+                    # install that exposes nothing must never look successful.
+                    raise BinaryNoExecutableError(
+                        spec,
+                        release.tag,
+                        tried[0],
+                        [a.name for a in release.assets if a.name not in tried],
+                    ) from None
+                raise
+
+            executables, rejected = self._unpack_candidate(
+                source,
+                repo_spec,
+                release,
+                asset,
+                env_dir,
+                cache_dir,
+                tool_name=tool_name,
+                setup=setup,
+                upgrade=upgrade,
+                log=log,
+            )
+            if executables:
+                return asset, release, executables
+
+            log.debug(f"asset skip: {asset.name} — {_rejection_reason(rejected)}")
+            doomed = _doomed_by_libc(release, rejected, log)
+            _empty_dir(env_dir)
+            if effective_pattern is not None:
+                # The asset was named, by the user or by the tool's setup file.
+                # Quietly installing a different one would answer a question
+                # nobody asked: report what the named asset turned out to be.
+                if rejected:
+                    raise BinaryPlatformError(spec, release.tag, asset.name, rejected)
+                raise BinaryNoExecutableError(
+                    spec,
+                    release.tag,
+                    asset.name,
+                    [a.name for a in release.assets if a.name != asset.name],
+                )
+            tried.append(asset.name)
+            if rejected and first_rejection is None:
+                first_rejection = (asset.name, rejected)
+            excluded.add(asset.name)
+            excluded |= doomed
+
     def _select_asset(
         self,
         release: Release,
         asset_pattern: str | None,
         tool_name: str,
         main_spec: str,
+        *,
+        repo_spec: RepoSpec | None = None,
+        exclude: set[str] | None = None,
     ) -> Asset:
+        log = get_logger("binary")
         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],
+        excluded = exclude or set()
+        candidates = [a for a in release.assets if a.name not in excluded]
+        unusable: list[tuple[str, str]] = []
+
+        while candidates:
+            asset = select_asset(
+                candidates,
+                tool_name,
+                _strip_v_prefix(release.tag),
+                heuristics=heuristics,
+                asset_pattern=asset_pattern,
+                verbose=get_verbosity(),
             )
-        return asset
+            if asset is None:
+                break
+
+            loader = self._unrunnable_loader(asset, repo_spec=repo_spec, tag=release.tag)
+            if loader is None:
+                return asset
+
+            log.debug(f"asset skip: {asset.name} needs missing loader {loader}")
+            unusable.append((asset.name, loader))
+            candidates = [a for a in candidates if a.name != asset.name]
+
+        raise AssetSelectionError(
+            main_spec,
+            release.tag,
+            [a.name for a in release.assets],
+            unusable,
+        )
+
+    def _relearn_release(
+        self,
+        source: ReleaseSource,
+        repo_spec: RepoSpec,
+        release: Release,
+    ) -> Release | None:
+        """Re-fetch *release* from the API after its learned pattern proved wrong.
+
+        The fast path synthesizes a release holding only the asset its pattern
+        names, so a pattern pointing at an unrunnable build leaves selection
+        with nothing to fall back on. The pattern is dropped and the real asset
+        list fetched, which lets scoring reach the runnable siblings.
+
+        Returns None when the release already came from the API: there is then
+        no wider list to fall back to, and the caller should surface the
+        original selection error instead.
+        """
+        if (release.resolution_source or "").endswith("-api"):
+            return None
+
+        log = get_logger("binary")
+        log.debug(
+            f"asset pattern for {repo_spec.owner}/{repo_spec.repo} names an unrunnable "
+            "asset — invalidating and refetching from the release API"
+        )
+        from ixt.config import asset_pattern_cache
+
+        asset_pattern_cache.invalidate(repo_spec.owner, repo_spec.repo)
+        self._require_github_api(repo_spec)
+        refetched = source.get_release_by_tag(repo_spec.owner, repo_spec.repo, release.tag)
+        refetched.resolution_source = f"{repo_spec.platform}-api"
+        log.debug(f"release (relearn): {refetched.tag} ({len(refetched.assets)} assets)")
+        return refetched
+
+    def _unrunnable_loader(
+        self,
+        asset: Asset,
+        *,
+        repo_spec: RepoSpec | None,
+        tag: str,
+    ) -> str | None:
+        """Return the loader *asset* needs but this host lacks, else None.
+
+        A cached asset is read from disk; otherwise only the head of the asset
+        is fetched over HTTP Range, which keeps a doomed candidate from costing
+        a full download. Only bare binaries can be checked this way — an
+        archive reveals nothing at offset zero, so those are validated after
+        extraction by ``find_executables`` instead.
+
+        Any doubt resolves to None: a server without Range support, a network
+        hiccup, or a truncated prefix all fall through to the normal path.
+        """
+        if os.name == "nt" or is_archive(asset.name):
+            return None
+        if repo_spec is not None:
+            cache_path = _asset_cache_path(self.settings.downloads_dir, repo_spec, asset, tag=tag)
+            cached = _cached_asset(cache_path, asset.size)
+            if cached is not None:
+                # Already on disk: judge the real file, no request needed.
+                info = read_elf(cached)
+                return info.interpreter if info is not None and info.loader_missing() else None
+
+        head = get_range(asset.url, ELF_PREFIX_SIZE)
+        if head is None:
+            return None
+        info = parse_elf(head)
+        if info is None or not info.loader_missing():
+            return None
+        return info.interpreter
 
     def uninstall_package(self, env_dir: Path, package: str) -> None:
         """No-op — binary tools are atomic (uninstall removes the whole env)."""