ixt-cli 0.8.0__py3-none-any.whl

ixt/core/cache.py

@@ -0,0 +1,332 @@
+"""Cache storage helpers for ixt.
+
+This module owns operational cache actions. ``doctor`` can report cache
+health, but cache mutation lives here and behind ``ixt cache``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from ixt.config.settings import Settings, get_settings
+
+DOWNLOADS_INDEX_FILENAME = "downloads.json"
+DOWNLOADS_INDEX_SCHEMA = 1
+
+
+@dataclass(slots=True)
+class SizeEntry:
+    """Size and file count for one storage location."""
+
+    name: str
+    path: Path
+    files: int
+    bytes: int
+
+
+@dataclass(slots=True)
+class ClearResult:
+    """Outcome of a cache-clear action."""
+
+    target: str
+    path: Path
+    removed_count: int
+    removed_bytes: int
+
+
+@dataclass(slots=True)
+class PruneResult:
+    """Outcome of pruning indexed download artifacts."""
+
+    kept_count: int
+    removed_count: int
+    removed_bytes: int
+    stale_entries: int
+
+
+def humanize_size(size: int) -> str:
+    """Return a compact human-readable size."""
+    value: float = float(size)
+    for unit in ("B", "KB", "MB", "GB"):
+        if value < 1024 or unit == "GB":
+            return f"{int(value)} B" if unit == "B" else f"{value:.1f} {unit}"
+        value /= 1024
+    return f"{int(value)} B"
+
+
+def count_and_size(path: Path) -> tuple[int, int]:
+    """Return ``(file_count, total_bytes)`` for *path*.
+
+    Missing paths count as empty. A direct file path counts as one file.
+    """
+    if not path.exists():
+        return 0, 0
+    try:
+        if path.is_file() or path.is_symlink():
+            return 1, path.stat().st_size
+    except OSError:
+        return 0, 0
+
+    count = 0
+    total = 0
+    for entry in path.rglob("*"):
+        try:
+            if entry.is_file():
+                count += 1
+                total += entry.stat().st_size
+        except OSError:
+            continue
+    return count, total
+
+
+def storage_sizes(*, settings: Settings | None = None) -> list[SizeEntry]:
+    """Return the main ixt storage locations with sizes."""
+    settings = settings or get_settings()
+    paths = [
+        ("Home", settings.home),
+        ("Config", settings.config_dir),
+        ("Installed", settings.installed_dir),
+        ("Bin", settings.bin_dir),
+        ("Envs", settings.envs_dir),
+        ("Runtimes", settings.runtimes_dir),
+        ("Cache", settings.cache_home),
+        ("Downloads", settings.downloads_dir),
+        ("Metadata", settings.metadata_dir),
+        ("Tmp", settings.tmp_dir),
+    ]
+    return [_size_entry(name, path) for name, path in paths]
+
+
+def cache_sizes(*, settings: Settings | None = None) -> list[SizeEntry]:
+    """Return cache-only locations with sizes."""
+    settings = settings or get_settings()
+    return [
+        _size_entry("Downloads", settings.downloads_dir),
+        _size_entry("Metadata", settings.metadata_dir),
+        _size_entry("Tmp", settings.tmp_dir),
+    ]
+
+
+def _size_entry(name: str, path: Path) -> SizeEntry:
+    files, bytes_ = count_and_size(path)
+    return SizeEntry(name=name, path=path, files=files, bytes=bytes_)
+
+
+def clear_caches(target: str, *, settings: Settings | None = None) -> list[ClearResult]:
+    """Clear the requested cache(s).
+
+    *target* is one of ``"downloads"``, ``"metadata"``, ``"tmp"``, or
+    ``"all"``. This never touches installed tools or user config.
+    """
+    settings = settings or get_settings()
+    targets: dict[str, Path] = {
+        "downloads": settings.downloads_dir,
+        "metadata": settings.metadata_dir,
+        "tmp": settings.tmp_dir,
+    }
+    if target != "all" and target not in targets:
+        raise ValueError(f"Unknown cache target: {target}")
+
+    selected = targets.items() if target == "all" else [(target, targets[target])]
+    results: list[ClearResult] = []
+    for name, path in selected:
+        count, size = count_and_size(path)
+        if path.exists():
+            shutil.rmtree(path)
+        results.append(ClearResult(name, path, count, size))
+    return results
+
+
+def downloads_index_path(*, settings: Settings | None = None) -> Path:
+    """Return the metadata file that indexes downloaded artifacts."""
+    settings = settings or get_settings()
+    return settings.metadata_dir / DOWNLOADS_INDEX_FILENAME
+
+
+def record_download(
+    *,
+    settings: Settings | None = None,
+    kind: str,
+    platform: str,
+    host: str,
+    owner: str,
+    repo: str,
+    tag: str,
+    asset_name: str,
+    asset_url: str,
+    asset_size: int,
+    path: Path,
+) -> None:
+    """Record a downloaded artifact in the programmatic cache index."""
+    settings = settings or get_settings()
+    index = _load_downloads_index(settings=settings)
+    relative_path = _safe_relative(path, settings.cache_home)
+    entry = {
+        "kind": kind,
+        "platform": platform,
+        "host": host,
+        "owner": owner,
+        "repo": repo,
+        "tag": tag,
+        "version": _version_from_tag(tag),
+        "asset": asset_name,
+        "asset_size": int(asset_size),
+        "path": relative_path,
+        "url": asset_url,
+        "downloaded_at": _now_utc(),
+    }
+
+    entries = index["entries"]
+    entries[:] = [
+        existing
+        for existing in entries
+        if not (
+            existing.get("kind") == kind
+            and existing.get("platform") == platform
+            and existing.get("host") == host
+            and existing.get("owner") == owner
+            and existing.get("repo") == repo
+            and existing.get("tag") == tag
+            and existing.get("asset") == asset_name
+        )
+    ]
+    entries.append(entry)
+    _write_downloads_index(index, settings=settings)
+
+
+def prune_downloads(*, settings: Settings | None = None, keep: int = 2) -> PruneResult:
+    """Prune indexed download artifacts, keeping newest *keep* per repo.
+
+    Only files present in ``downloads.json`` are candidates. Unindexed files
+    are left alone, which keeps the operation conservative.
+    """
+    if keep < 1:
+        raise ValueError("keep must be >= 1")
+
+    settings = settings or get_settings()
+    index = _load_downloads_index(settings=settings)
+    groups: dict[tuple[str, str, str, str, str], list[tuple[dict[str, Any], Path]]] = {}
+    stale_entries = 0
+
+    for entry in index["entries"]:
+        path = _entry_path(entry, settings=settings)
+        if path is None or not path.exists():
+            stale_entries += 1
+            continue
+        groups.setdefault(_group_key(entry), []).append((entry, path))
+
+    kept_entries: list[dict[str, Any]] = []
+    removed_count = 0
+    removed_bytes = 0
+
+    for items in groups.values():
+        sortable = [item for item in items if isinstance(item[0].get("downloaded_at"), str)]
+        unsortable = [item for item in items if not isinstance(item[0].get("downloaded_at"), str)]
+        sortable.sort(key=lambda item: item[0]["downloaded_at"], reverse=True)
+
+        kept = sortable[:keep] + unsortable
+        to_remove = sortable[keep:]
+        kept_entries.extend(entry for entry, _path in kept)
+
+        for entry, path in to_remove:
+            count, size = count_and_size(path)
+            try:
+                if path.is_dir() and not path.is_symlink():
+                    shutil.rmtree(path)
+                else:
+                    path.unlink(missing_ok=True)
+            except OSError:
+                kept_entries.append(entry)
+                continue
+            removed_count += count
+            removed_bytes += size
+
+    _write_downloads_index(
+        {"schema": DOWNLOADS_INDEX_SCHEMA, "entries": kept_entries},
+        settings=settings,
+    )
+    return PruneResult(
+        kept_count=len(kept_entries),
+        removed_count=removed_count,
+        removed_bytes=removed_bytes,
+        stale_entries=stale_entries,
+    )
+
+
+def _load_downloads_index(*, settings: Settings) -> dict[str, Any]:
+    path = downloads_index_path(settings=settings)
+    try:
+        with path.open(encoding="utf-8") as f:
+            data = json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return {"schema": DOWNLOADS_INDEX_SCHEMA, "entries": []}
+    if not isinstance(data, dict):
+        return {"schema": DOWNLOADS_INDEX_SCHEMA, "entries": []}
+    entries = data.get("entries", [])
+    if not isinstance(entries, list):
+        entries = []
+    data["schema"] = DOWNLOADS_INDEX_SCHEMA
+    data["entries"] = [entry for entry in entries if isinstance(entry, dict)]
+    return data
+
+
+def _write_downloads_index(data: dict[str, Any], *, settings: Settings) -> None:
+    path = downloads_index_path(settings=settings)
+    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)
+            f.write("\n")
+        os.replace(tmp, path)
+    except Exception:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def _entry_path(entry: dict[str, Any], *, settings: Settings) -> Path | None:
+    raw = entry.get("path")
+    if not isinstance(raw, str) or not raw:
+        return None
+    path = Path(raw)
+    if not path.is_absolute():
+        path = settings.cache_home / path
+    try:
+        path.resolve().relative_to(settings.cache_home.resolve())
+    except ValueError:
+        return None
+    return path
+
+
+def _group_key(entry: dict[str, Any]) -> tuple[str, str, str, str, str]:
+    return (
+        str(entry.get("kind", "")),
+        str(entry.get("platform", "")),
+        str(entry.get("host", "")),
+        str(entry.get("owner", "")),
+        str(entry.get("repo", "")),
+    )
+
+
+def _safe_relative(path: Path, base: Path) -> str:
+    try:
+        return str(path.resolve().relative_to(base.resolve()))
+    except ValueError:
+        return str(path)
+
+
+def _version_from_tag(tag: str) -> str:
+    if tag[:1].lower() == "v":
+        return tag[1:]
+    return tag
+
+
+def _now_utc() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z")

ixt/core/discover.py

@@ -0,0 +1,150 @@
+"""Executable discovery in extracted binary environments.
+
+Scans extracted directories for executable files, filtering out
+non-executable content using heuristics.toml expose rules.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import re
+import stat
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from ixt.config.heuristics import ExposeConfig, load_heuristics
+
+if TYPE_CHECKING:
+    from ixt.libs.logger import Logger
+
+
+_PATH_SEPARATOR_RE = re.compile(r"[\\/]+")
+_TOKEN_SEPARATOR_RE = re.compile(r"[\\/._-]+")
+_MAN_PATH_COMPONENT_RE = re.compile(r"man(?:[0-9][a-z0-9]*|[nl])?$", re.IGNORECASE)
+_DOC_COMPONENT_KEYWORDS = frozenset(
+    {"license", "readme", "changelog", "notice", "copying", "dist-manifest"}
+)
+_TOKEN_KEYWORDS = frozenset({"completion", "completions", "autocomplete"})
+
+
+def _is_executable(path: Path) -> bool:
+    """Return True if *path* is a regular file with an executable bit set."""
+    try:
+        st = path.stat()
+    except OSError:
+        return False
+    if not stat.S_ISREG(st.st_mode):
+        return False
+    return bool(st.st_mode & (stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH))
+
+
+def _should_skip(name: str, expose: ExposeConfig, rel_path: str = "") -> bool:
+    """Return True if *name* (or its relative path) should be filtered out by expose rules."""
+    lower = name.lower()
+    lower_path = rel_path.lower() if rel_path else lower
+
+    # Skip known runtime names
+    if lower in (n.lower() for n in expose.skip_names):
+        return True
+
+    # Skip by glob pattern (*.md, *.txt, etc.) — matched against filename only
+    for pat in expose.skip_patterns:
+        if fnmatch.fnmatch(lower, pat.lower()):
+            return True
+
+    # Skip by keyword, using tighter rules for the built-in archive metadata names.
+    for kw in expose.skip_keywords:
+        if _keyword_matches_path(kw, lower_path):
+            return True
+
+    return False
+
+
+def _keyword_matches_path(keyword: str, lower_path: str) -> bool:
+    """Return True if an expose skip keyword matches *lower_path*."""
+    lower_keyword = keyword.lower()
+    components = _path_components(lower_path)
+
+    # "man" is meant to catch man-page directories such as man/ or man1/,
+    # not binaries whose names merely contain those letters.
+    if lower_keyword == "man":
+        return any(_MAN_PATH_COMPONENT_RE.fullmatch(component) for component in components[:-1])
+
+    if lower_keyword in _DOC_COMPONENT_KEYWORDS:
+        return any(
+            component == lower_keyword or _component_stem(component) == lower_keyword
+            for component in components
+        )
+
+    if lower_keyword in _TOKEN_KEYWORDS:
+        return lower_keyword in _path_tokens(lower_path)
+
+    return lower_keyword in lower_path
+
+
+def _path_components(lower_path: str) -> list[str]:
+    """Split a lowercase relative path into non-empty directory/file components."""
+    return [component for component in _PATH_SEPARATOR_RE.split(lower_path) if component]
+
+
+def _path_tokens(lower_path: str) -> list[str]:
+    """Split a lowercase relative path into non-empty separator-delimited tokens."""
+    return [token for token in _TOKEN_SEPARATOR_RE.split(lower_path) if token]
+
+
+def _component_stem(component: str) -> str:
+    """Return the filename stem using the first dot as metadata extension boundary."""
+    return component.split(".", 1)[0]
+
+
+def find_executables(
+    root: Path,
+    *,
+    expose: ExposeConfig | None = None,
+    max_depth: int = 3,
+    log: Logger | None = None,
+) -> list[Path]:
+    """Find executable files in *root*, filtered by expose rules.
+
+    Walks the directory tree up to *max_depth* levels, looking for
+    executable files that pass the heuristics.toml expose filters.
+
+    Args:
+        root: Directory to scan (typically the extraction root).
+        expose: Expose config to use. Loads defaults if None.
+        max_depth: Maximum directory depth to scan (0 = root only).
+        log: Optional logger; emits debug lines for skipped files.
+
+    Returns:
+        List of absolute paths to discovered executables, sorted by name.
+    """
+    if expose is None:
+        expose = load_heuristics().expose
+
+    executables: list[Path] = []
+    root_depth = len(root.parts)
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        current = Path(dirpath)
+        depth = len(current.parts) - root_depth
+
+        if depth >= max_depth:
+            dirnames.clear()  # stop descending
+
+        for fname in filenames:
+            fpath = current / fname
+
+            if not _is_executable(fpath):
+                continue
+
+            rel = str(fpath.relative_to(root))
+            if _should_skip(fname, expose, rel_path=rel):
+                if log:
+                    log.debug(f"expose skip: {rel}")
+                continue
+
+            executables.append(fpath)
+
+    executables.sort(key=lambda p: p.name)
+    return executables