ixt-cli 0.8.0__py3-none-any.whl

ixt/libs/shell.py

@@ -0,0 +1,126 @@
+"""Safe shell execution utilities.
+
+Ported from uvpipx's misc.py — only the secure (shell=False) path is kept.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess  # nosemgrep: gitlab.bandit.B404
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class ShellError(Exception):
+    """Raised when a shell command fails."""
+
+    def __init__(self, cmd: list[str], returncode: int, stderr: str):
+        self.cmd = cmd
+        self.returncode = returncode
+        self.stderr = stderr
+        super().__init__(f"Command failed with code {returncode}: {' '.join(cmd)}\n{stderr}")
+
+
+def shell_run(
+    cmd: list[str],
+    cwd: Path | None = None,
+    capture_output: bool = False,
+    check: bool = True,
+    env: dict[str, str] | None = None,
+    timeout: float | None = None,
+) -> subprocess.CompletedProcess:
+    """Run a command safely (shell=False to prevent injection).
+
+    Args:
+        cmd: Command as a list of strings.
+        cwd: Working directory.
+        capture_output: Capture stdout/stderr.
+        check: Raise ShellError on non-zero exit.
+        env: Environment variables (defaults to clean env without VIRTUAL_ENV).
+        timeout: Wall-clock timeout in seconds; raises ``subprocess.TimeoutExpired``.
+
+    Returns:
+        subprocess.CompletedProcess
+
+    Raises:
+        ShellError: If check=True and command fails.
+        subprocess.TimeoutExpired: If timeout elapses before completion.
+    """
+    resolved_env = env if env is not None else _clean_env()
+
+    result = subprocess.run(
+        cmd,
+        cwd=cwd,
+        capture_output=capture_output,
+        text=capture_output,
+        shell=False,
+        env=resolved_env,
+        timeout=timeout,
+    )
+
+    if check and result.returncode != 0:
+        stderr = result.stderr or ""
+        raise ShellError(cmd, result.returncode, stderr)
+
+    return result
+
+
+def shell_run_output(
+    cmd: list[str],
+    cwd: Path | None = None,
+) -> str:
+    """Run a command and return stdout (stripped).
+
+    Raises:
+        ShellError: If command fails.
+    """
+    result = shell_run(cmd, cwd=cwd, capture_output=True, check=True)
+    return result.stdout.strip() if result.stdout else ""
+
+
+def command_exists(cmd: str) -> bool:
+    """Check if a command exists in PATH using shutil.which."""
+    return shutil.which(cmd) is not None
+
+
+def _clean_env() -> dict[str, str]:
+    """Return a copy of os.environ without VIRTUAL_ENV variables."""
+    env = os.environ.copy()
+    for key in ("VIRTUAL_ENV", "VIRTUAL_ENV_PROMPT"):
+        env.pop(key, None)
+    return env
+
+
+# -- Elapser -----------------------------------------------------------------
+
+
+@dataclass
+class Elapser:
+    """Context manager for measuring elapsed time.
+
+    Usage::
+
+        with Elapser() as ela:
+            do_work()
+        print(ela.elapsed)  # "1.234 seconds"
+    """
+
+    start: float = 0.0
+    end: float = 0.0
+    seconds: float = 0.0
+    elapsed: str = ""
+
+    def __enter__(self) -> Elapser:
+        self.start = time.perf_counter()
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.end = time.perf_counter()
+        self.seconds = self.end - self.start
+        self.elapsed = f"{self.seconds:.3f} seconds"
+
+    def format(self, message: str) -> str:
+        """Return ``message`` followed by the elapsed time."""
+        return f"{message}  ({self.elapsed})"

ixt/libs/style.py

@@ -0,0 +1,238 @@
+"""ANSI color and style utilities.
+
+Ported and cleaned up from uvpipx's stylist.py.
+Supports NO_COLOR (https://no-color.org/) and NO_EMOJI environment variables.
+"""
+
+from __future__ import annotations
+
+import functools
+import os
+import re
+import sys
+import unicodedata
+from enum import Enum
+
+
+class Color(Enum):
+    """ANSI color and style codes."""
+
+    # Foreground
+    RED = "\033[31m"
+    GREEN = "\033[32m"
+    YELLOW = "\033[33m"
+    BLUE = "\033[34m"
+    MAGENTA = "\033[35m"
+    CYAN = "\033[36m"
+    WHITE = "\033[37m"
+
+    BRIGHT_RED = "\033[91m"
+    BRIGHT_GREEN = "\033[92m"
+    BRIGHT_YELLOW = "\033[93m"
+    BRIGHT_BLUE = "\033[94m"
+    BRIGHT_MAGENTA = "\033[95m"
+    BRIGHT_CYAN = "\033[96m"
+    BRIGHT_WHITE = "\033[97m"
+
+    # Background
+    BG_RED = "\033[41m"
+    BG_GREEN = "\033[42m"
+    BG_YELLOW = "\033[43m"
+    BG_BLUE = "\033[44m"
+    BG_MAGENTA = "\033[45m"
+    BG_CYAN = "\033[46m"
+    BG_WHITE = "\033[47m"
+
+    BG_BRIGHT_RED = "\033[101m"
+    BG_BRIGHT_GREEN = "\033[102m"
+    BG_BRIGHT_YELLOW = "\033[103m"
+    BG_BRIGHT_BLUE = "\033[104m"
+    BG_BRIGHT_MAGENTA = "\033[105m"
+    BG_BRIGHT_CYAN = "\033[106m"
+    BG_BRIGHT_WHITE = "\033[107m"
+
+    # Styles
+    ST_RESET = "\033[0m"
+    ST_BOLD = "\033[1m"
+    ST_DIM = "\033[2m"
+    ST_ITALIC = "\033[3m"
+    ST_UNDERLINE = "\033[4m"
+    ST_REVERSE = "\033[7m"
+
+    @staticmethod
+    def rgb(r: int, g: int, b: int, *, background: bool = False) -> str:
+        """Generate an ANSI escape sequence for a 24-bit RGB color."""
+        layer = 48 if background else 38
+        return f"\033[{layer};2;{r};{g};{b}m"
+
+
+# -- ANSI escape stripping ---------------------------------------------------
+
+_ANSI_RE = re.compile(r"\033\[[0-9;]*m")
+
+
+def strip_ansi(text: str) -> str:
+    """Remove all ANSI escape sequences from *text*."""
+    return _ANSI_RE.sub("", text)
+
+
+def visible_len(text: str) -> int:
+    """Return the visible (printable) length of *text*, ignoring ANSI codes."""
+    return len(strip_ansi(text))
+
+
+# -- NO_COLOR / NO_EMOJI detection -------------------------------------------
+
+
+def _no_color_env() -> bool:
+    """Return True when the ``NO_COLOR`` env var opts out globally."""
+    return os.getenv("NO_COLOR", "") != ""
+
+
+def _no_color_for(stream) -> bool:
+    return _no_color_env() or not stream.isatty()
+
+
+@functools.lru_cache(maxsize=1)
+def no_color_stderr() -> bool:
+    """Return True when color output should be suppressed on stderr.
+
+    Consulted by the logger before writing. Cached for the process lifetime.
+    """
+    return _no_color_for(sys.stderr)
+
+
+@functools.lru_cache(maxsize=1)
+def no_color_stdout() -> bool:
+    """Return True when color output should be suppressed on stdout.
+
+    Consulted by ``libs/output.data()`` before writing. Cached for the process lifetime.
+    """
+    return _no_color_for(sys.stdout)
+
+
+@functools.lru_cache(maxsize=1)
+def _use_emoji() -> bool:
+    """Return True when the terminal is likely to render emoji."""
+    if os.getenv("NO_EMOJI", "") != "":
+        return False
+    encoding = getattr(sys.stdout, "encoding", "") or ""
+    return encoding.lower() == "utf-8"
+
+
+# -- Painter -----------------------------------------------------------------
+
+
+class Painter:
+    """Static helpers for applying ANSI styles to text.
+
+    The helpers are flux-neutral: they always emit ANSI unless ``NO_COLOR`` is
+    set. Writers (logger → stderr, ``data()`` → stdout) are responsible for
+    stripping the codes when their target stream is not a TTY.
+    """
+
+    @staticmethod
+    def color_str(message: str, *styles: Color) -> str:
+        """Apply one or more Color styles to *message*."""
+        if _no_color_env():
+            return message
+        codes = "".join(s.value for s in styles)
+        return f"{codes}{message}{Color.ST_RESET.value}"
+
+    @staticmethod
+    def hex_color(hexcode: str, *, background: bool = False) -> str:
+        """Return an ANSI escape from a hex color code like ``#ff8800``."""
+        if _no_color_env():
+            return ""
+        hexcode = hexcode.lstrip("#")
+        r, g, b = int(hexcode[:2], 16), int(hexcode[2:4], 16), int(hexcode[4:6], 16)
+        return Color.rgb(r, g, b, background=background)
+
+    @staticmethod
+    def reset() -> str:
+        if _no_color_env():
+            return ""
+        return Color.ST_RESET.value
+
+    @staticmethod
+    def parse_color_tags(message: str) -> str:
+        """Process ``<COLOR>text</COLOR>`` markup into ANSI escapes.
+
+        Supports nesting: ``<RED><ST_BOLD>text</ST_BOLD></RED>``.
+        """
+        if _no_color_env():
+            return re.sub(r"</?[A-Z_]+>", "", message)
+
+        tag_re = re.compile(r"</?([A-Z_]+)>")
+        active: list[str] = []
+        result = message
+
+        match = tag_re.search(result)
+        while match:
+            tag = match.group(0)
+            inner = tag.strip("<>/")
+            if not tag.startswith("</"):
+                active.append(inner)
+                try:
+                    replacement = Color[inner].value
+                except KeyError:
+                    replacement = tag
+            else:
+                if inner in active:
+                    active.remove(inner)
+                replacement = Color.ST_RESET.value
+                replacement += "".join(Color[s].value for s in active if s in Color.__members__)
+            result = result.replace(tag, replacement, 1)
+            match = tag_re.search(result)
+
+        return result
+
+
+# -- Emoji helpers -----------------------------------------------------------
+
+
+def strip_emoji(text: str) -> str:
+    """Remove all emoji characters from *text*."""
+    return "".join(c for c in text if unicodedata.category(c) not in ("So", "Sk", "Sm"))
+
+
+def emoji(char: str) -> str:
+    """Return *char* if emoji rendering is available, else empty string."""
+    return char if _use_emoji() else ""
+
+
+# -- Convenience shortcuts ---------------------------------------------------
+
+
+def _colored(text: str, color: Color, bold: bool = False) -> str:
+    """Apply *color* (and optionally bold) to *text*."""
+    styles: tuple[Color, ...] = (Color.ST_BOLD, color) if bold else (color,)
+    return Painter.color_str(text, *styles)
+
+
+def red(text: str, bold: bool = False) -> str:
+    return _colored(text, Color.RED, bold)
+
+
+def green(text: str, bold: bool = False) -> str:
+    return _colored(text, Color.GREEN, bold)
+
+
+def yellow(text: str, bold: bool = False) -> str:
+    return _colored(text, Color.YELLOW, bold)
+
+
+def blue(text: str, bold: bool = False) -> str:
+    return _colored(text, Color.BLUE, bold)
+
+
+def cyan(text: str, bold: bool = False) -> str:
+    return _colored(text, Color.CYAN, bold)
+
+
+def bold(text: str) -> str:
+    return Painter.color_str(text, Color.ST_BOLD)
+
+
+def dim(text: str) -> str:
+    return Painter.color_str(text, Color.ST_DIM)

ixt/net/__init__.py

@@ -0,0 +1 @@
+"""Networking layer for ixt — HTTP client and release source APIs."""

ixt/net/github_api.py

@@ -0,0 +1,158 @@
+"""GitHub Releases API client — implements ReleaseSource."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from ixt.net.http import HttpError, NotFoundError, download_file, get_final_url, get_json, get_text
+from ixt.net.source import Asset, Release
+
+_API_BASE = "https://api.github.com"
+_RAW_BASE = "https://raw.githubusercontent.com"
+_WEB_BASE = "https://github.com"
+
+
+class GitHubSource:
+    """Fetch releases and files from the GitHub API.
+
+    Token resolution order:
+        1. Explicit ``token`` argument
+        2. ``GITHUB_TOKEN`` environment variable
+        3. ``GH_TOKEN`` environment variable
+        4. No token (unauthenticated, 60 req/h)
+    """
+
+    def __init__(self, token: str | None = None):
+        self._token = token or os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+
+    def _headers(self) -> dict[str, str]:
+        h: dict[str, str] = {"Accept": "application/vnd.github+json"}
+        if self._token:
+            h["Authorization"] = f"Bearer {self._token}"
+        return h
+
+    # -- ReleaseSource interface ------------------------------------------------
+
+    def get_latest_release(self, owner: str, repo: str) -> Release:
+        """GET /repos/{owner}/{repo}/releases/latest
+
+        Falls back to listing releases if no 'latest' is set.
+        """
+        from ixt.core.resolution_stats import record_github_api
+
+        url = f"{_API_BASE}/repos/{owner}/{repo}/releases/latest"
+        try:
+            record_github_api(owner, repo, "releases/latest")
+            data = get_json(url, headers=self._headers())
+            return _parse_release(data)
+        except NotFoundError:
+            # Some repos have releases but none marked 'latest'
+            releases = self.list_releases(owner, repo)
+            for r in releases:
+                if not r.prerelease and not r.draft:
+                    return r
+            if releases:
+                return releases[0]
+            raise
+
+    def get_release_by_tag(self, owner: str, repo: str, tag: str) -> Release:
+        """GET /repos/{owner}/{repo}/releases/tags/{tag}"""
+        from ixt.core.resolution_stats import record_github_api
+
+        url = f"{_API_BASE}/repos/{owner}/{repo}/releases/tags/{tag}"
+        record_github_api(owner, repo, f"releases/tags/{tag}")
+        data = get_json(url, headers=self._headers())
+        return _parse_release(data)
+
+    def list_releases(self, owner: str, repo: str) -> list[Release]:
+        """GET /repos/{owner}/{repo}/releases (first page, up to 30)."""
+        from ixt.core.resolution_stats import record_github_api
+
+        url = f"{_API_BASE}/repos/{owner}/{repo}/releases?per_page=30"
+        record_github_api(owner, repo, "releases")
+        data = get_json(url, headers=self._headers())
+        return [_parse_release(r) for r in data]
+
+    def download_asset(self, url: str, dest: Path) -> None:
+        """Download a release asset to *dest*.
+
+        *url* is expected to be a ``browser_download_url`` pointing at the CDN
+        (``github.com/{owner}/{repo}/releases/download/...``). No API quota
+        consumed, no auth header required.
+        """
+        download_file(url, dest)
+
+    def get_file_content(
+        self, owner: str, repo: str, path: str, *, ref: str | None = None
+    ) -> str | None:
+        """Fetch a file from ``raw.githubusercontent.com`` — no API quota.
+
+        When *ref* is None, uses ``HEAD`` (default branch). Callers that know
+        the target tag should pass it so the fetched content stays coherent
+        with the installed release.
+        """
+        url = f"{_RAW_BASE}/{owner}/{repo}/{ref or 'HEAD'}/{path}"
+        try:
+            return get_text(url)
+        except NotFoundError:
+            return None
+
+
+_RELEASE_TAG_MARKER = "/releases/tag/"
+
+
+def parse_tag_from_release_url(final_url: str) -> str | None:
+    """Extract the tag from a resolved ``.../releases/tag/{tag}`` URL.
+
+    Returns None when the marker is absent (unexpected redirect) or the tag
+    segment is empty.
+    """
+    idx = final_url.find(_RELEASE_TAG_MARKER)
+    if idx < 0:
+        return None
+    return final_url[idx + len(_RELEASE_TAG_MARKER) :].rstrip("/").split("/")[0] or None
+
+
+def fetch_latest_tag(owner: str, repo: str, *, timeout: int | None = None) -> str | None:
+    """Resolve the latest release tag without calling the GitHub API.
+
+    Issues a HEAD on ``github.com/{owner}/{repo}/releases/latest`` and parses
+    the tag from the redirect's final URL (``.../releases/tag/{tag}``).
+    Returns None if the repo has no releases or the format is unexpected.
+    """
+    url = f"{_WEB_BASE}/{owner}/{repo}/releases/latest"
+    try:
+        if timeout is None:
+            final = get_final_url(url)
+        else:
+            final = get_final_url(url, timeout=timeout)
+    except HttpError:
+        return None
+    return parse_tag_from_release_url(final)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_release(data: dict) -> Release:
+    """Parse a GitHub release JSON into a Release."""
+    tag = data.get("tag_name", "")
+    assets = [
+        Asset(
+            name=a["name"],
+            # Prefer CDN URL (no API quota). The API asset URL is only used
+            # as fallback for legacy responses that omit browser_download_url.
+            url=a.get("browser_download_url") or a.get("url", ""),
+            size=a.get("size", 0),
+        )
+        for a in data.get("assets", [])
+    ]
+    return Release(
+        tag=tag,
+        assets=assets,
+        prerelease=data.get("prerelease", False),
+        draft=data.get("draft", False),
+    )

ixt/net/gitlab_api.py

@@ -0,0 +1,149 @@
+"""GitLab Releases API client — implements ReleaseSource.
+
+Supports gitlab.com and self-hosted instances via dynamic base_url.
+"""
+
+from __future__ import annotations
+
+import os
+import urllib.parse
+from pathlib import Path
+
+from ixt.net.http import NotFoundError, download_file, get_json, get_text
+from ixt.net.source import Asset, Release
+
+
+class GitLabSource:
+    """Fetch releases and files from the GitLab API v4.
+
+    Token resolution order:
+        1. Explicit ``token`` argument
+        2. ``GITLAB_TOKEN`` environment variable
+        3. No token (public repos only)
+
+    Args:
+        base_url: GitLab instance URL (e.g. "https://gitlab.com",
+                  "https://gitlab.company.com"). No trailing slash.
+        token: Private access token.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "https://gitlab.com",
+        token: str | None = None,
+    ):
+        self._base = base_url.rstrip("/")
+        self._api = f"{self._base}/api/v4"
+        self._token = token or os.environ.get("GITLAB_TOKEN")
+
+    def _headers(self) -> dict[str, str]:
+        h: dict[str, str] = {}
+        if self._token:
+            h["PRIVATE-TOKEN"] = self._token
+        return h
+
+    def _project_id(self, owner: str, repo: str) -> str:
+        """URL-encode the project path for API calls."""
+        return urllib.parse.quote(f"{owner}/{repo}", safe="")
+
+    # -- ReleaseSource interface ------------------------------------------------
+
+    def get_latest_release(self, owner: str, repo: str) -> Release:
+        """GET /projects/{id}/releases/permalink/latest
+
+        Falls back to listing releases if permalink not available.
+        """
+        from ixt.core.resolution_stats import record_gitlab_api
+
+        pid = self._project_id(owner, repo)
+        url = f"{self._api}/projects/{pid}/releases/permalink/latest"
+        try:
+            record_gitlab_api(owner, repo, "releases/permalink/latest")
+            data = get_json(url, headers=self._headers())
+            return _parse_release(data, self._base)
+        except NotFoundError:
+            releases = self.list_releases(owner, repo)
+            if releases:
+                return releases[0]
+            raise
+
+    def get_release_by_tag(self, owner: str, repo: str, tag: str) -> Release:
+        """GET /projects/{id}/releases/{tag}"""
+        from ixt.core.resolution_stats import record_gitlab_api
+
+        pid = self._project_id(owner, repo)
+        encoded_tag = urllib.parse.quote(tag, safe="")
+        url = f"{self._api}/projects/{pid}/releases/{encoded_tag}"
+        record_gitlab_api(owner, repo, f"releases/{tag}")
+        data = get_json(url, headers=self._headers())
+        return _parse_release(data, self._base)
+
+    def list_releases(self, owner: str, repo: str) -> list[Release]:
+        """GET /projects/{id}/releases (first page, up to 20)."""
+        from ixt.core.resolution_stats import record_gitlab_api
+
+        pid = self._project_id(owner, repo)
+        url = f"{self._api}/projects/{pid}/releases?per_page=20"
+        record_gitlab_api(owner, repo, "releases")
+        data = get_json(url, headers=self._headers())
+        return [_parse_release(r, self._base) for r in data]
+
+    def download_asset(self, url: str, dest: Path) -> None:
+        """Download a release asset to *dest*."""
+        download_file(url, dest, headers=self._headers())
+
+    def get_file_content(
+        self, owner: str, repo: str, path: str, *, ref: str | None = None
+    ) -> str | None:
+        """Fetch a file from GitLab's raw endpoint — no API quota.
+
+        Uses ``{base}/{owner}/{repo}/-/raw/{ref}/{path}`` which is served
+        outside the API. When *ref* is None, uses ``HEAD``.
+        """
+        encoded_ref = urllib.parse.quote(ref or "HEAD", safe="")
+        url = f"{self._base}/{owner}/{repo}/-/raw/{encoded_ref}/{path}"
+        try:
+            return get_text(url, headers=self._headers())
+        except NotFoundError:
+            return None
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_release(data: dict, base_url: str) -> Release:
+    """Parse a GitLab release JSON into a Release."""
+    tag = data.get("tag_name", "")
+    assets_data = data.get("assets", {})
+
+    assets: list[Asset] = []
+
+    # Release links (uploaded assets)
+    for link in assets_data.get("links", []):
+        assets.append(
+            Asset(
+                name=link.get("name", ""),
+                url=link.get("direct_asset_url", link.get("url", "")),
+                size=0,  # GitLab links don't report size
+            )
+        )
+
+    # Source archives (auto-generated by GitLab)
+    for src in assets_data.get("sources", []):
+        fmt = src.get("format", "")
+        assets.append(
+            Asset(
+                name=f"source.{fmt}",
+                url=src.get("url", ""),
+                size=0,
+            )
+        )
+
+    return Release(
+        tag=tag,
+        assets=assets,
+        prerelease=data.get("upcoming_release", False),
+        draft=False,  # GitLab doesn't have draft releases
+    )