ixt-cli 0.8.0__py3-none-any.whl

ixt/core/expose.py

@@ -0,0 +1,350 @@
+"""Exposure engine — resolve rules and link binaries to the shared bin dir."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ixt.config.heuristics import get_name_suffix_tokens, get_platform_aliases
+from ixt.core.backend import Backend
+from ixt.core.pathlink import PathLink, create_path_link
+from ixt.libs.constants import EXPOSE_MAIN
+
+# Binaries that should never be exposed (runtime internals).
+_EXCLUDED_RE = re.compile(r"^(python|pythonw|pip)(\d+(\.\d+)?)?(.exe)?$")
+_PLATFORM_SEPARATORS = "._-"
+
+
+def _strip_exe_suffix(name: str) -> str:
+    """Return *name* without the Windows executable suffix, if present."""
+    return name[:-4] if name.lower().endswith(".exe") else name
+
+
+def _executable_name(path: Path) -> str:
+    """Return the executable name used for rule matching."""
+    return _strip_exe_suffix(path.name)
+
+
+def _strip_suffix_tokens(name: str) -> str:
+    """Remove OS/arch/build suffixes when they appear as trailing full tokens."""
+    os_aliases, arch_aliases = get_platform_aliases()
+    aliases = {
+        alias.lower()
+        for alias in [*os_aliases, *arch_aliases]
+        if alias and alias.strip(_PLATFORM_SEPARATORS)
+    }
+    aliases.update(
+        token.lower()
+        for token in get_name_suffix_tokens()
+        if token and token.strip(_PLATFORM_SEPARATORS)
+    )
+    stripped = name.strip(_PLATFORM_SEPARATORS)
+    changed = True
+    while stripped and changed:
+        changed = False
+        for alias in sorted(aliases, key=len, reverse=True):
+            token_re = re.compile(
+                rf"(?:^|[{re.escape(_PLATFORM_SEPARATORS)}])"
+                rf"{re.escape(alias)}$",
+                re.IGNORECASE,
+            )
+            next_stripped = token_re.sub("", stripped).strip(_PLATFORM_SEPARATORS)
+            if next_stripped != stripped:
+                stripped = next_stripped
+                changed = True
+                break
+    return stripped
+
+
+def _eponym_alias(name: str, package_name: str) -> str | None:
+    """Return *package_name* as alias when *name* is a suffixed variant.
+
+    Only aliases when removing the current suffix tokens leaves exactly
+    *package_name*. Returns None when *name* already equals *package_name*.
+    """
+    if name == package_name:
+        return None
+    if _strip_suffix_tokens(name).lower() == package_name.lower():
+        return package_name
+    return None
+
+
+def _is_excluded(name: str) -> bool:
+    """Return True if *name* is a runtime binary that must not be exposed."""
+    return bool(_EXCLUDED_RE.match(name))
+
+
+def _parse_rename(rule: str) -> tuple[str, str | None]:
+    """Parse ``"original:alias"`` → ``("original", "alias")``.
+
+    Plain names return ``("name", None)``.
+    """
+    if ":" in rule:
+        orig, alias = rule.split(":", 1)
+        return orig.strip(), alias.strip()
+    return rule.strip(), None
+
+
+# ------------------------------------------------------------------
+# Expose result
+# ------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class ExposeResult:
+    """Outcome of an expose operation for one tool."""
+
+    linked: dict[str, str] = field(default_factory=dict)
+    """Map of exposed_name → source_path for successfully linked binaries."""
+
+    skipped: dict[str, str] = field(default_factory=dict)
+    """Map of name → reason for binaries that were skipped."""
+
+
+# ------------------------------------------------------------------
+# Rule resolver
+# ------------------------------------------------------------------
+
+
+def _resolve_eponym(
+    package_name: str,
+    all_bins: list[Path],
+) -> list[tuple[Path, str | None]]:
+    """Find the binary matching *package_name* exactly or after platform-token cleanup."""
+    for p in all_bins:
+        if _executable_name(p) == package_name:
+            return [(p, None)]
+    for p in all_bins:
+        alias = _eponym_alias(_executable_name(p), package_name)
+        if alias is not None:
+            return [(p, alias)]
+    return []
+
+
+def _resolve_main(
+    package_name: str,
+    backend: Backend,
+    env_dir: Path,
+    all_bins: list[Path],
+) -> list[tuple[Path, str | None]]:
+    """Resolve ``__main__`` — declared console_scripts / bin entries."""
+    declared = backend.get_package_binaries(env_dir, package_name)
+    if not declared:
+        return []
+    bin_dir_entries = {_executable_name(p): p for p in all_bins}
+    result: list[tuple[Path, str | None]] = []
+    for name in declared:
+        executable_name = _strip_exe_suffix(name)
+        if _is_excluded(executable_name):
+            continue
+        if executable_name in bin_dir_entries:
+            result.append(
+                (
+                    bin_dir_entries[executable_name],
+                    _eponym_alias(executable_name, package_name),
+                )
+            )
+    return result
+
+
+def _resolve_all(
+    all_bins: list[Path],
+) -> list[tuple[Path, str | None]]:
+    """Resolve ``__all__`` — every binary except python/pip."""
+    return [(p, None) for p in all_bins if not _is_excluded(_executable_name(p))]
+
+
+def _resolve_explicit(
+    rules: list[str],
+    all_bins: list[Path],
+) -> list[tuple[Path, str | None]]:
+    """Resolve an explicit list of names, with optional rename syntax."""
+    bin_map = {_executable_name(p): p for p in all_bins}
+    result: list[tuple[Path, str | None]] = []
+    for rule in rules:
+        orig, alias = _parse_rename(rule)
+        executable_name = _strip_exe_suffix(orig)
+        if executable_name in bin_map:
+            result.append((bin_map[executable_name], alias))
+    return result
+
+
+def resolve_rules(
+    rules: list[str],
+    package_name: str,
+    backend: Backend,
+    env_dir: Path,
+) -> list[tuple[Path, str | None]]:
+    """Resolve expose *rules* into a list of ``(source_path, alias_or_None)``.
+
+    Implements the fallback chain when the first rule is a single keyword:
+    ``__eponym__`` → ``__main__`` → ``__eponym__`` retry → ``__all__``
+    """
+    all_bins = backend.find_binaries(env_dir)
+
+    # Special keyword rules (single-element list with a dunder keyword).
+    if len(rules) == 1 and rules[0].startswith("__"):
+        keyword = rules[0]
+
+        if keyword == "__all__":
+            return _resolve_all(all_bins)
+
+        if keyword == EXPOSE_MAIN:
+            result = _resolve_main(package_name, backend, env_dir, all_bins)
+            if result:
+                return result
+            # fallback → __eponym__
+            result = _resolve_eponym(package_name, all_bins)
+            if result:
+                return result
+            # fallback → __all__
+            return _resolve_all(all_bins)
+
+        if keyword == "__eponym__":
+            result = _resolve_eponym(package_name, all_bins)
+            if result:
+                return result
+            # fallback → __main__
+            result = _resolve_main(package_name, backend, env_dir, all_bins)
+            if result:
+                return result
+            # fallback → __all__
+            return _resolve_all(all_bins)
+
+    # Explicit list (possibly with rename syntax).
+    return _resolve_explicit(rules, all_bins)
+
+
+# ------------------------------------------------------------------
+# Public API
+# ------------------------------------------------------------------
+
+
+def expose_tool(
+    package_name: str,
+    backend: Backend,
+    env_dir: Path,
+    bin_dir: Path,
+    rules: list[str] | None = None,
+    *,
+    overwrite: bool = False,
+) -> ExposeResult:
+    """Expose binaries for one tool according to *rules*.
+
+    Returns an `ExposeResult` describing what was linked and what was skipped.
+    Collision reasons include the owning tool name when available.
+    """
+    rules = rules or [EXPOSE_MAIN]
+    resolved = resolve_rules(rules, package_name, backend, env_dir)
+    result = ExposeResult()
+
+    bin_dir.mkdir(parents=True, exist_ok=True)
+
+    for source, alias in resolved:
+        link = create_path_link(source, bin_dir, rename_to=alias)
+        exposed_name = alias or _executable_name(source)
+
+        if link.target_exists() and not overwrite:
+            # Check if it's our own (idempotent re-expose).
+            if link.is_valid():
+                result.linked[exposed_name] = str(source)
+            else:
+                owner = _find_shim_owner(exposed_name, bin_dir, exclude_env_dir=env_dir)
+                reason = (
+                    f"conflict: already exposed by {owner}" if owner else "conflict: already exists"
+                )
+                result.skipped[exposed_name] = reason
+            continue
+
+        link.create(overwrite=overwrite)
+        result.linked[exposed_name] = str(source)
+
+    return result
+
+
+def warn_if_skipped(result: ExposeResult, tool_name: str, logger) -> None:
+    """Log a warning and an actionable hint when expose produced collisions."""
+    if not result.skipped:
+        return
+    if len(result.skipped) == 1:
+        name, reason = next(iter(sorted(result.skipped.items())))
+        logger.warn(f"could not expose: {name} ({reason})")
+    else:
+        logger.warn("could not expose:")
+        for name, reason in sorted(result.skipped.items()):
+            logger.warn(f"  {name}: {reason}")
+    example = next(iter(sorted(result.skipped)))
+    logger.warn(f"  Hint: run ixt tool config {tool_name} expose {example}:<alias>")
+
+
+def _find_shim_owner(exposed_name: str, bin_dir: Path, *, exclude_env_dir: Path) -> str | None:
+    """Return the name of the tool whose record claims *exposed_name*, or None.
+
+    Scans installed tool metadata under ``bin_dir.parent / "envs"``. Skips
+    ``exclude_env_dir`` so a reinstall doesn't report itself as the owner.
+    """
+    envs_dir = bin_dir.parent / "envs"
+    if not envs_dir.is_dir():
+        return None
+    exclude_resolved = exclude_env_dir.resolve() if exclude_env_dir.exists() else exclude_env_dir
+    from ixt.config.models import ToolRecord
+
+    for env_path in envs_dir.iterdir():
+        if not env_path.is_dir():
+            continue
+        if env_path.resolve() == exclude_resolved:
+            continue
+        meta = env_path / "ixt.json"
+        if not meta.is_file():
+            continue
+        try:
+            record = ToolRecord.load_json(meta)
+        except Exception:
+            continue
+        if exposed_name in record.exposed_bins:
+            return record.name
+    return None
+
+
+def unexpose_tool(
+    exposed_bins: dict[str, str],
+    bin_dir: Path,
+) -> list[str]:
+    """Remove previously exposed links for one tool.
+
+    *exposed_bins* maps ``exposed_name → source_path`` (from ``ToolRecord``).
+    Returns the list of names successfully removed.
+    """
+    removed: list[str] = []
+    for exposed_name, source_str in exposed_bins.items():
+        link = PathLink(
+            source_path=Path(source_str),
+            target_path=bin_dir / exposed_name,
+        )
+        if link.remove(force=True):
+            removed.append(exposed_name)
+    return removed
+
+
+def reexpose_tool(record, new_rules: list[str], settings) -> ExposeResult:
+    """Unexpose then re-expose *record* with *new_rules*, and persist it."""
+    from ixt.core.backend import BackendType, get_backend
+
+    env_dir = Path(record.env_dir)
+    bt = BackendType(record.backend)
+    backend = get_backend(bt, settings=settings)
+
+    unexpose_tool(record.exposed_bins, settings.bin_dir)
+    result = expose_tool(
+        record.pkg(),
+        backend,
+        env_dir,
+        settings.bin_dir,
+        new_rules,
+        overwrite=True,
+    )
+    record.expose_rules = list(new_rules)
+    record.exposed_bins = result.linked
+    record.save_json(settings.get_tool_metadata_file(record.name))
+    return result

ixt/core/extract.py

@@ -0,0 +1,261 @@
+"""Archive extraction with anti-traversal protection.
+
+Supports: .tar.gz, .tar.xz, .tar.bz2, .tgz, .txz, .zip, bare binaries.
+All stdlib — no third-party dependencies.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+import tarfile
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+TarReadMode = Literal["r:gz", "r:xz", "r:bz2"]
+
+
+class ExtractionError(Exception):
+    """Raised on extraction failure (bad archive, traversal attempt, etc.)."""
+
+
+@dataclass(slots=True)
+class ExtractionResult:
+    """Outcome of an extraction operation."""
+
+    root: Path
+    """The effective root directory containing the extracted content."""
+
+    files: list[Path]
+    """All extracted file paths (relative to *root*)."""
+
+    is_bare_binary: bool = False
+    """True when the asset was a bare binary (no archive)."""
+
+
+# -- Archive format detection -------------------------------------------------
+
+_TAR_EXTENSIONS: dict[str, TarReadMode] = {
+    ".tar.gz": "r:gz",
+    ".tgz": "r:gz",
+    ".tar.xz": "r:xz",
+    ".txz": "r:xz",
+    ".tar.bz2": "r:bz2",
+}
+
+_ZIP_EXTENSIONS = {".zip"}
+
+
+def _archive_mode(filename: str) -> TarReadMode | None:
+    """Return tarfile open mode if *filename* is a supported tar, else None."""
+    lower = filename.lower()
+    for ext, mode in _TAR_EXTENSIONS.items():
+        if lower.endswith(ext):
+            return mode
+    return None
+
+
+def _is_zip(filename: str) -> bool:
+    return filename.lower().endswith(".zip")
+
+
+# -- Anti-traversal -----------------------------------------------------------
+
+
+def _safe_path(member_name: str, dest: Path) -> Path:
+    """Resolve *member_name* under *dest* and reject path traversal.
+
+    Raises ExtractionError if the resolved path escapes *dest*.
+    """
+    # Normalise: strip leading / and ./ , collapse ..
+    cleaned = os.path.normpath(member_name)
+    if cleaned.startswith(("../", "..\\")):
+        raise ExtractionError(f"Path traversal detected: {member_name!r}")
+
+    resolved = (dest / cleaned).resolve()
+    dest_resolved = dest.resolve()
+
+    if not str(resolved).startswith(str(dest_resolved) + os.sep) and resolved != dest_resolved:
+        raise ExtractionError(f"Path traversal detected: {member_name!r} -> {resolved}")
+
+    return resolved
+
+
+# -- Tar extraction -----------------------------------------------------------
+
+
+def _extract_tar(archive_path: Path, dest: Path, mode: TarReadMode) -> list[Path]:
+    """Extract a tar archive, returning list of extracted files (relative)."""
+    files: list[Path] = []
+
+    with tarfile.open(archive_path, mode) as tf:
+        for member in tf.getmembers():
+            # Skip special file types (devices, etc.)
+            if not (member.isfile() or member.isdir() or member.issym()):
+                continue
+
+            target = _safe_path(member.name, dest)
+
+            if member.isdir():
+                target.mkdir(parents=True, exist_ok=True)
+            elif member.issym():
+                # Validate symlink target stays within dest
+                link_target = os.path.normpath(
+                    os.path.join(os.path.dirname(member.name), member.linkname)
+                )
+                _safe_path(link_target, dest)
+                target.parent.mkdir(parents=True, exist_ok=True)
+                if target.exists() or target.is_symlink():
+                    target.unlink()
+                os.symlink(member.linkname, target)
+            else:
+                # Regular file
+                target.parent.mkdir(parents=True, exist_ok=True)
+                src = tf.extractfile(member)
+                if src is None:
+                    continue
+                with src, target.open("wb") as dst:
+                    shutil.copyfileobj(src, dst)
+
+                # Preserve executable bit
+                if member.mode & 0o111:
+                    target.chmod(target.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+                files.append(Path(member.name))
+
+    return files
+
+
+# -- Zip extraction -----------------------------------------------------------
+
+
+def _extract_zip(archive_path: Path, dest: Path) -> list[Path]:
+    """Extract a zip archive, returning list of extracted files (relative)."""
+    files: list[Path] = []
+
+    with zipfile.ZipFile(archive_path, "r") as zf:
+        for info in zf.infolist():
+            target = _safe_path(info.filename, dest)
+
+            if info.is_dir():
+                target.mkdir(parents=True, exist_ok=True)
+                continue
+
+            target.parent.mkdir(parents=True, exist_ok=True)
+
+            with zf.open(info) as src, target.open("wb") as dst:
+                shutil.copyfileobj(src, dst)
+
+            # Preserve Unix executable bit from external_attr
+            unix_mode = info.external_attr >> 16
+            if unix_mode & 0o111:
+                target.chmod(target.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+            files.append(Path(info.filename))
+
+    return files
+
+
+# -- Bare binary --------------------------------------------------------------
+
+
+def _copy_bare_binary(src: Path, dest: Path, name: str) -> list[Path]:
+    """Copy a bare binary (no archive) into *dest* and make it executable."""
+    target = _safe_path(name, dest)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with src.open("rb") as source, target.open("wb") as out:
+        shutil.copyfileobj(source, out)
+    target.chmod(target.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return [Path(name)]
+
+
+# -- Root normalisation -------------------------------------------------------
+
+
+def _normalise_root(dest: Path, files: list[Path]) -> tuple[Path, list[Path]]:
+    """If all files share a single top-level directory, descend into it.
+
+    Many archives wrap everything in a directory like ``ripgrep-14.1.0/``.
+    This returns the effective root and rebased file paths.
+    """
+    if not files:
+        return dest, files
+
+    # Collect unique top-level components
+    top_dirs: set[str] = set()
+    for f in files:
+        top_dirs.add(f.parts[0])
+
+    if len(top_dirs) != 1:
+        return dest, files
+
+    # Single top-level directory — check it's actually a directory
+    wrapper = top_dirs.pop()
+    wrapper_path = dest / wrapper
+    if not wrapper_path.is_dir():
+        return dest, files
+
+    # Rebase files relative to the wrapper
+    rebased: list[Path] = []
+    for f in files:
+        parts = f.parts[1:]  # strip wrapper prefix
+        if parts:
+            rebased.append(Path(*parts))
+
+    return wrapper_path, rebased
+
+
+# -- Public API ---------------------------------------------------------------
+
+
+def is_archive(filename: str) -> bool:
+    """Return True if *filename* has a recognized archive extension."""
+    return _archive_mode(filename) is not None or _is_zip(filename)
+
+
+def extract(
+    archive_path: Path,
+    dest: Path,
+    *,
+    tool_name: str | None = None,
+) -> ExtractionResult:
+    """Extract an archive or copy a bare binary into *dest*.
+
+    Args:
+        archive_path: Path to the downloaded archive or bare binary.
+        dest: Directory to extract into (created if needed).
+        tool_name: Tool name used as filename for bare binaries.
+
+    Returns:
+        ExtractionResult with the effective root and file listing.
+
+    Raises:
+        ExtractionError: On path traversal, bad archive, or I/O failure.
+    """
+    dest.mkdir(parents=True, exist_ok=True)
+    name = archive_path.name
+
+    tar_mode = _archive_mode(name)
+    if tar_mode is not None:
+        try:
+            files = _extract_tar(archive_path, dest, tar_mode)
+        except (tarfile.TarError, OSError) as exc:
+            raise ExtractionError(f"Failed to extract tar: {exc}") from exc
+        root, files = _normalise_root(dest, files)
+        return ExtractionResult(root=root, files=files)
+
+    if _is_zip(name):
+        try:
+            files = _extract_zip(archive_path, dest)
+        except (zipfile.BadZipFile, OSError) as exc:
+            raise ExtractionError(f"Failed to extract zip: {exc}") from exc
+        root, files = _normalise_root(dest, files)
+        return ExtractionResult(root=root, files=files)
+
+    # Bare binary — not an archive
+    bin_name = tool_name or archive_path.stem
+    files = _copy_bare_binary(archive_path, dest, bin_name)
+    return ExtractionResult(root=dest, files=files, is_bare_binary=True)