ixt-cli 0.8.0__py3-none-any.whl

ixt/core/backend.py

@@ -0,0 +1,187 @@
+"""Backend protocol and auto-detection for tool installation."""
+
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from ixt.config.registry import lookup_spec
+
+
+class BackendType(Enum):
+    """Supported tool ecosystems."""
+
+    PYTHON = "python"
+    NODE = "node"
+    BINARY = "binary"
+
+
+@runtime_checkable
+class Backend(Protocol):
+    """Interface every backend must implement."""
+
+    backend_type: BackendType
+
+    def env_exists(self, env_dir: Path) -> bool:
+        """Check whether the isolated environment already exists."""
+        ...
+
+    def create_env(self, env_dir: Path) -> bool:
+        """Create the isolated environment. Return True if newly created."""
+        ...
+
+    def install_packages(
+        self, env_dir: Path, specs: list[str], *, upgrade: bool = False
+    ) -> dict | None:
+        """Install packages into the environment.
+
+        May return a dict of backend-specific metadata to merge into the
+        ToolRecord (e.g. ``asset_pattern`` for the binary backend).
+        """
+        ...
+
+    def uninstall_package(self, env_dir: Path, package: str) -> None:
+        """Remove a package from the environment."""
+        ...
+
+    def find_binaries(self, env_dir: Path) -> list[Path]:
+        """Discover all executables exposed by the environment."""
+        ...
+
+    def get_package_binaries(self, env_dir: Path, package_name: str) -> dict[str, str]:
+        """Return binaries declared by *package_name*.
+
+        Returns ``{binary_name: entry_point_or_path}``.
+        For Python this reads ``console_scripts``; for Node it reads
+        the ``bin`` field in ``package.json``.
+        """
+        ...
+
+    def installed_version(self, env_dir: Path, package_name: str) -> str | None:
+        """Return the installed version of *package_name*, or ``None``."""
+        ...
+
+    def export(self, env_dir: Path) -> list[str]:
+        """List every installed package with pinned version."""
+        ...
+
+
+# Namespace prefixes that force a specific backend: @prefix:spec
+_NAMESPACE_PREFIXES: dict[str, BackendType] = {
+    "pypi": BackendType.PYTHON,
+    "npm": BackendType.NODE,
+    "gh": BackendType.BINARY,
+    "gl": BackendType.BINARY,
+}
+
+# Forge prefixes that normalize to a default host when the spec is owner/repo.
+_FORGE_DEFAULT_HOST: dict[str, str] = {
+    "gh": "github.com",
+    "gl": "gitlab.com",
+}
+
+
+def _ensure_forge_host(spec: str, default_host: str) -> str:
+    """Prefix *default_host* to ``owner/repo`` specs lacking a host.
+
+    Leaves ``host/owner/repo`` (first segment contains a dot) and short names
+    without ``/`` (short names go through registry lookup) unchanged.
+    """
+    if "/" not in spec:
+        return spec
+    first = spec.split("/", 1)[0]
+    if "." in first:
+        return spec
+    return f"{default_host}/{spec}"
+
+
+def strip_protocol(spec: str) -> tuple[BackendType | None, str]:
+    """Strip a namespace prefix from *spec* and return ``(forced_backend, clean_spec)``.
+
+    Recognized prefixes: ``@pypi:``, ``@npm:``, ``@gh:``, ``@gl:``.
+    For forge prefixes (``@gh:``/``@gl:``), an ``owner/repo`` spec is normalized
+    to ``host/owner/repo`` so the binary backend routes to the right platform.
+    If no prefix matches, returns ``(None, spec)`` unchanged.
+
+    Raises:
+        ValueError: If spec has ``@prefix:`` form but prefix is unknown,
+            or if spec looks like a namespace prefix but is missing the
+            leading ``@`` (e.g. ``gl:owner/repo`` should be ``@gl:owner/repo``).
+    """
+    s = spec.strip()
+    if s.startswith("@") and ":" in s:
+        prefix, _, rest = s[1:].partition(":")
+        if prefix in _NAMESPACE_PREFIXES:
+            default_host = _FORGE_DEFAULT_HOST.get(prefix)
+            if default_host is not None:
+                rest = _ensure_forge_host(rest, default_host)
+            return _NAMESPACE_PREFIXES[prefix], rest
+        known = ", ".join(f"@{p}:" for p in _NAMESPACE_PREFIXES)
+        raise ValueError(f"Unknown namespace '@{prefix}:'. Valid: {known}")
+    # Catch the missing-@ typo: ``gl:owner/repo`` should be ``@gl:owner/repo``.
+    # Only short alphanumeric prefixes (≤6 chars) qualify, so we don't trip on
+    # legitimate ``foo:bar``-style URLs or specs.
+    if ":" in s and not s.startswith("@"):
+        head, _, rest = s.partition(":")
+        if head and head.isalnum() and len(head) <= 6 and head in _NAMESPACE_PREFIXES:
+            raise ValueError(
+                f"Spec '{spec}' looks like a namespace shortcut. "
+                f"Did you mean '@{head}:{rest}'? Prefixes need a leading '@'."
+            )
+    return None, s
+
+
+def detect_backend(spec: str) -> BackendType:
+    """Auto-detect backend type from a package specification.
+
+    Supports explicit namespace prefixes:
+
+    * ``@pypi:ruff``              -> Python
+    * ``@npm:typescript``         -> Node
+    * ``@gh:BurntSushi/ripgrep``  -> Binary (GitHub)
+    * ``@gl:gitlab-org/cli``      -> Binary (GitLab)
+
+    Without prefix, auto-detection applies:
+
+    * ``@scope/pkg``   -> Node
+    * ``owner/repo``   -> Binary (GitHub Releases)
+    * simple name      -> registry lookup, then fallback Python (PyPI)
+    """
+    forced, clean = strip_protocol(spec)
+    if forced is not None:
+        return forced
+
+    name = clean
+    for sep in ("[", ">", "<", "=", "!", "~"):
+        name = name.split(sep, 1)[0]
+    name = name.strip()
+
+    if name.startswith("@") and "/" in name:
+        return BackendType.NODE
+    if "/" in name:
+        return BackendType.BINARY
+
+    # Registry lookup for simple names (e.g. "ripgrep" -> "@gh:BurntSushi/ripgrep")
+    registry_spec = lookup_spec(name)
+    if registry_spec is not None:
+        return detect_backend(registry_spec)
+
+    return BackendType.PYTHON
+
+
+def get_backend(backend_type: BackendType, **kwargs) -> Backend:
+    """Instantiate the backend for *backend_type*."""
+    if backend_type == BackendType.PYTHON:
+        from ixt.backends.python import PythonBackend
+
+        return PythonBackend(**kwargs)
+    if backend_type == BackendType.NODE:
+        from ixt.backends.node import NodeBackend
+
+        return NodeBackend(**kwargs)
+    if backend_type == BackendType.BINARY:
+        from ixt.backends.binary import BinaryBackend
+
+        return BinaryBackend(**kwargs)
+    raise NotImplementedError(f"Backend '{backend_type.value}' is not yet implemented")

ixt/core/bootstrap.py

@@ -0,0 +1,410 @@
+"""Runtime bootstrap — ensure required runtimes are available.
+
+Finds, verifies, and downloads ``uv`` and ``bun`` so that ixt can manage
+Python and Node tools without requiring the user to pre-install anything
+beyond Python itself.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+import tarfile
+import tempfile
+import zipfile
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+from urllib.parse import unquote, urlparse
+
+from ixt.config.settings import Settings, get_settings
+from ixt.libs.semver import parse_version
+from ixt.libs.shell import ShellError, command_exists, shell_run_output
+from ixt.net.http import HttpError, download_file
+from ixt.platform import OS, Arch, get_arch, get_os, is_windows
+
+
+class BootstrapError(RuntimeError):
+    """Raised when runtime bootstrap fails."""
+
+
+RuntimeName = Literal["uv", "bun"]
+
+
+# ===========================================================================
+# Generic runtime bootstrap primitives
+# ===========================================================================
+
+
+@dataclass(frozen=True)
+class _RuntimeSpec:
+    """Parameters describing how to find, verify, and download a runtime."""
+
+    name: str
+    min_version: tuple[int, ...]
+    parse_version: Callable[[str], tuple[int, ...]]
+    get_download: Callable[[], tuple[str, str]]  # returns (url, archive-ext)
+    extract: Callable[[Path, Path, str], None]  # (archive, dest, ext)
+    runtime_path: Callable[[Settings], Path]
+
+
+def _check_version(spec: _RuntimeSpec, path: str) -> bool:
+    """Return *True* if the runtime at *path* meets ``spec.min_version``."""
+    try:
+        output = shell_run_output([path, "--version"])
+        return spec.parse_version(output) >= spec.min_version
+    except (ShellError, BootstrapError):
+        return False
+
+
+def _archive_cache_path(settings: Settings, spec: _RuntimeSpec, url: str, ext: str) -> Path:
+    name = Path(unquote(urlparse(url).path)).name or f"{spec.name}.{ext}"
+    return settings.downloads_dir / "runtimes" / spec.name / name
+
+
+def _download_archive(url: str, archive: Path, settings: Settings) -> None:
+    archive.parent.mkdir(parents=True, exist_ok=True)
+    settings.tmp_dir.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=f"{archive.name}.",
+        suffix=".tmp",
+        dir=settings.tmp_dir,
+    )
+    os.close(fd)
+    tmp = Path(tmp_name)
+    try:
+        download_file(url, tmp, headers={"User-Agent": "ixt-bootstrap/1"})
+        tmp.replace(archive)
+    except (HttpError, OSError) as exc:
+        tmp.unlink(missing_ok=True)
+        raise BootstrapError(f"Failed to download {url}: {exc}") from exc
+
+
+def _download_runtime(
+    spec: _RuntimeSpec,
+    target_path: Path,
+    *,
+    settings: Settings | None = None,
+    force: bool = False,
+) -> None:
+    """Download, extract, and verify the runtime described by *spec*."""
+    s = settings or get_settings()
+    url, ext = spec.get_download()
+    archive = _archive_cache_path(s, spec, url, ext)
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if force or not archive.exists() or archive.stat().st_size == 0:
+        _download_archive(url, archive, s)
+
+    try:
+        spec.extract(archive, target_path, ext)
+    except (BootstrapError, OSError, tarfile.TarError, zipfile.BadZipFile):
+        if force:
+            raise
+        archive.unlink(missing_ok=True)
+        _download_archive(url, archive, s)
+        spec.extract(archive, target_path, ext)
+
+    if not _check_version(spec, str(target_path)):
+        target_path.unlink(missing_ok=True)
+        if force:
+            raise BootstrapError(f"Downloaded {spec.name} binary failed version check")
+        archive.unlink(missing_ok=True)
+        _download_archive(url, archive, s)
+        spec.extract(archive, target_path, ext)
+        if not _check_version(spec, str(target_path)):
+            target_path.unlink(missing_ok=True)
+            raise BootstrapError(f"Downloaded {spec.name} binary failed version check")
+
+
+def _find_runtime(
+    spec: _RuntimeSpec,
+    settings: Settings | None,
+    check_fn: Callable[[str], bool],
+) -> str | None:
+    """Find a usable runtime matching *spec* without downloading anything.
+
+    Search order:
+        1. Bootstrapped binary at ``spec.runtime_path(settings)``
+        2. System binary on ``PATH``
+
+    *check_fn* is passed by the caller so tests can ``patch()`` the
+    per-runtime wrapper (``_check_uv_version`` / ``_check_bun_version``).
+    """
+    s = settings or get_settings()
+
+    rt = spec.runtime_path(s)
+    if rt.exists() and check_fn(str(rt)):
+        return str(rt)
+
+    if command_exists(spec.name) and check_fn(spec.name):
+        return spec.name
+
+    return None
+
+
+def _ensure_runtime(
+    spec: _RuntimeSpec,
+    settings: Settings | None,
+    find_fn: Callable[[Settings | None], str | None],
+    download_fn: Callable[..., None],
+) -> str:
+    """Return a working runtime path, downloading via *download_fn* if needed.
+
+    *find_fn* and *download_fn* are looked up at call time (passed by name,
+    not by value), so tests can ``patch()`` the module-level symbols.
+    """
+    s = settings or get_settings()
+    found = find_fn(s)
+    if found is not None:
+        return found
+
+    from ixt.libs.logger import get_logger
+
+    get_logger("bootstrap").info(f"Bootstrapping {spec.name} runtime...")
+    target = spec.runtime_path(s)
+    download_fn(target, settings=s)
+    return str(target)
+
+
+# ===========================================================================
+# uv bootstrap
+# ===========================================================================
+
+# Minimum uv version required (0.4.0 stabilised uv pip / uv venv).
+MIN_UV_VERSION: tuple[int, ...] = (0, 4, 0)
+
+# GitHub release archive URL pattern.
+_UV_RELEASE_URL = "https://github.com/astral-sh/uv/releases/latest/download/uv-{target}.{ext}"
+
+# Platform → uv release target name.
+_UV_TARGETS: dict[tuple[OS, Arch], str] = {
+    (OS.LINUX, Arch.X86_64): "x86_64-unknown-linux-musl",
+    (OS.LINUX, Arch.ARM64): "aarch64-unknown-linux-musl",
+    (OS.LINUX, Arch.ARMV7): "armv7-unknown-linux-musleabihf",
+    (OS.MACOS, Arch.X86_64): "x86_64-apple-darwin",
+    (OS.MACOS, Arch.ARM64): "aarch64-apple-darwin",
+    (OS.WINDOWS, Arch.X86_64): "x86_64-pc-windows-msvc",
+    (OS.WINDOWS, Arch.ARM64): "aarch64-pc-windows-msvc",
+}
+
+
+def _parse_uv_version(version_str: str) -> tuple[int, ...]:
+    """Parse ``'uv 0.5.1 (abc123)'`` or ``'0.5.1'`` into ``(0, 5, 1)``."""
+    text = version_str.strip().removeprefix("uv ")
+    result = parse_version(text)
+    if result is None:
+        raise BootstrapError(f"Cannot parse uv version: {version_str!r}")
+    return result
+
+
+def _get_uv_download_url() -> tuple[str, str]:
+    """Return ``(url, archive_extension)`` for the current platform."""
+    key = (get_os(), get_arch())
+    target = _UV_TARGETS.get(key)
+    if target is None:
+        raise BootstrapError(f"No uv binary available for {get_os().value}/{get_arch().value}")
+    ext = "zip" if is_windows() else "tar.gz"
+    url = _UV_RELEASE_URL.format(target=target, ext=ext)
+    return url, ext
+
+
+def _extract_uv(archive_path: Path, dest: Path, ext: str) -> None:
+    """Extract the ``uv`` binary from *archive_path* into *dest*."""
+    binary_name = "uv.exe" if is_windows() else "uv"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    if ext == "tar.gz":
+        with tarfile.open(archive_path, "r:gz") as tar:
+            for member in tar.getmembers():
+                if member.name.endswith(f"/{binary_name}") or member.name == binary_name:
+                    reader = tar.extractfile(member)
+                    if reader is None:
+                        continue
+                    with dest.open("wb") as f:
+                        shutil.copyfileobj(reader, f)
+                    dest.chmod(dest.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+                    return
+    elif ext == "zip":
+        with zipfile.ZipFile(archive_path) as zf:
+            for name in zf.namelist():
+                if name.endswith(f"/{binary_name}") or name == binary_name:
+                    with zf.open(name) as src, dest.open("wb") as f:
+                        shutil.copyfileobj(src, f)
+                    return
+
+    raise BootstrapError(f"Could not find {binary_name} in archive {archive_path}")
+
+
+_UV_SPEC = _RuntimeSpec(
+    name="uv",
+    min_version=MIN_UV_VERSION,
+    parse_version=_parse_uv_version,
+    get_download=_get_uv_download_url,
+    extract=_extract_uv,
+    runtime_path=lambda s: s.uv_runtime,
+)
+
+
+def _check_uv_version(uv_path: str) -> bool:
+    """Return *True* if the ``uv`` at *uv_path* meets the minimum version."""
+    return _check_version(_UV_SPEC, uv_path)
+
+
+def _download_uv(
+    target_path: Path,
+    *,
+    settings: Settings | None = None,
+    force: bool = False,
+) -> None:
+    """Download and install the ``uv`` binary to *target_path*."""
+    _download_runtime(_UV_SPEC, target_path, settings=settings, force=force)
+
+
+def find_uv(settings: Settings | None = None) -> str | None:
+    """Find a usable ``uv`` binary without downloading anything.
+
+    Search order:
+        1. Bootstrapped ``uv`` at ``$IXT_HOME/installed/runtimes/uv``
+        2. System ``uv`` in ``PATH``
+
+    Returns:
+        Path string to a working ``uv``, or *None*.
+    """
+    return _find_runtime(_UV_SPEC, settings, _check_uv_version)
+
+
+def ensure_uv(settings: Settings | None = None) -> str:
+    """Ensure ``uv`` is available, downloading it if necessary.
+
+    This is the main entry point — idempotent and lazy.
+
+    Returns:
+        Path string to a working ``uv``.
+
+    Raises:
+        BootstrapError: If ``uv`` cannot be found or downloaded.
+    """
+    return _ensure_runtime(_UV_SPEC, settings, find_uv, _download_uv)
+
+
+# ===========================================================================
+# Bun bootstrap
+# ===========================================================================
+
+# Minimum bun version required (1.0.0 stabilised bun add / bun run).
+MIN_BUN_VERSION: tuple[int, ...] = (1, 0, 0)
+
+# GitHub release archive URL pattern — bun ships as zip on all platforms.
+_BUN_RELEASE_URL = "https://github.com/oven-sh/bun/releases/latest/download/{target}.zip"
+
+# Platform → bun release target name.
+_BUN_TARGETS: dict[tuple[OS, Arch], str] = {
+    (OS.LINUX, Arch.X86_64): "bun-linux-x64",
+    (OS.LINUX, Arch.ARM64): "bun-linux-aarch64",
+    (OS.MACOS, Arch.X86_64): "bun-darwin-x64",
+    (OS.MACOS, Arch.ARM64): "bun-darwin-aarch64",
+    (OS.WINDOWS, Arch.X86_64): "bun-windows-x64",
+}
+
+
+def _parse_bun_version(version_str: str) -> tuple[int, ...]:
+    """Parse ``'1.1.34'`` or ``'bun 1.1.34'`` into ``(1, 1, 34)``."""
+    text = version_str.strip()
+    if text.lower().startswith("bun "):
+        text = text[4:]
+    result = parse_version(text)
+    if result is None:
+        raise BootstrapError(f"Cannot parse bun version: {version_str!r}")
+    return result
+
+
+def _get_bun_download_url() -> str:
+    """Return the download URL for the current platform."""
+    key = (get_os(), get_arch())
+    target = _BUN_TARGETS.get(key)
+    if target is None:
+        raise BootstrapError(f"No bun binary available for {get_os().value}/{get_arch().value}")
+    return _BUN_RELEASE_URL.format(target=target)
+
+
+def _extract_bun(archive_path: Path, dest: Path) -> None:
+    """Extract the ``bun`` binary from a zip archive into *dest*."""
+    binary_name = "bun.exe" if is_windows() else "bun"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    with zipfile.ZipFile(archive_path) as zf:
+        for name in zf.namelist():
+            if name.endswith(f"/{binary_name}") or name == binary_name:
+                with zf.open(name) as src, dest.open("wb") as f:
+                    shutil.copyfileobj(src, f)
+                if not is_windows():
+                    dest.chmod(dest.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+                return
+
+    raise BootstrapError(f"Could not find {binary_name} in archive {archive_path}")
+
+
+_BUN_SPEC = _RuntimeSpec(
+    name="bun",
+    min_version=MIN_BUN_VERSION,
+    parse_version=_parse_bun_version,
+    get_download=lambda: (_get_bun_download_url(), "zip"),
+    extract=lambda archive, dest, _ext: _extract_bun(archive, dest),
+    runtime_path=lambda s: s.bun_runtime,
+)
+
+
+def _check_bun_version(bun_path: str) -> bool:
+    """Return *True* if ``bun`` at *bun_path* meets the minimum version."""
+    return _check_version(_BUN_SPEC, bun_path)
+
+
+def _download_bun(
+    target_path: Path,
+    *,
+    settings: Settings | None = None,
+    force: bool = False,
+) -> None:
+    """Download and install the ``bun`` binary to *target_path*."""
+    _download_runtime(_BUN_SPEC, target_path, settings=settings, force=force)
+
+
+def find_bun(settings: Settings | None = None) -> str | None:
+    """Find a usable ``bun`` binary without downloading anything.
+
+    Search order:
+        1. Bootstrapped ``bun`` at ``$IXT_HOME/installed/runtimes/bun``
+        2. System ``bun`` in ``PATH``
+    """
+    return _find_runtime(_BUN_SPEC, settings, _check_bun_version)
+
+
+def ensure_bun(settings: Settings | None = None) -> str:
+    """Ensure ``bun`` is available, downloading it if necessary.
+
+    Returns:
+        Path string to a working ``bun``.
+
+    Raises:
+        BootstrapError: If ``bun`` cannot be found or downloaded.
+    """
+    return _ensure_runtime(_BUN_SPEC, settings, find_bun, _download_bun)
+
+
+def upgrade_runtime(name: RuntimeName, *, settings: Settings | None = None) -> str:
+    """Download or replace an ixt-managed runtime.
+
+    This intentionally writes to ``$IXT_HOME/installed/runtimes`` even when a
+    usable system runtime exists, so users can move back to the managed path.
+    """
+    s = settings or get_settings()
+    if name == "uv":
+        _download_uv(s.uv_runtime, settings=s, force=True)
+        return str(s.uv_runtime)
+    if name == "bun":
+        _download_bun(s.bun_runtime, settings=s, force=True)
+        return str(s.bun_runtime)
+    raise BootstrapError(f"Unsupported runtime: {name}")