ixt-cli 0.8.0__py3-none-any.whl

ixt/core/install.py

@@ -0,0 +1,509 @@
+"""Backend-agnostic tool installation and removal."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ixt.backends.binary import SetupMetadata
+
+from ixt.config.models import ToolRecord
+from ixt.config.settings import Settings, get_settings
+from ixt.core.backend import BackendType, detect_backend, get_backend, strip_protocol
+from ixt.core.expose import expose_tool, unexpose_tool
+from ixt.core.identity import (
+    display_spec_for_record,
+    id_prefixes,
+    is_id_selector,
+    make_tool_id,
+    parse_id_selector,
+    validate_slot,
+)
+from ixt.libs.constants import EXPOSE_MAIN
+from ixt.libs.req_spec import parse_requirement
+from ixt.net.source import parse_spec, strip_version_suffix
+
+
+@dataclass(slots=True)
+class InstallPlan:
+    """What ``install_tool`` would do for a given spec, without executing."""
+
+    backend: BackendType
+    original_spec: str
+    resolved_spec: str
+    pkg_name: str
+    tool_name: str
+    env_dir: Path
+    expose_rules: list[str]
+    inject: list[str]
+    already_installed: bool
+    setup_path: Path | None
+
+
+def _read_binary_hooks(env_dir: Path) -> SetupMetadata | None:
+    """Read hook config from binary backend metadata, if present."""
+    meta_path = env_dir / "binary_metadata.json"
+    if not meta_path.exists():
+        return None
+    with meta_path.open(encoding="utf-8") as f:
+        meta = json.load(f)
+    return meta.get("setup")
+
+
+def _first_bin_path(exposed_bins: dict[str, str]) -> str | None:
+    """Return the path of the first exposed binary (used as ``{bin}``)."""
+    if not exposed_bins:
+        return None
+    return next(iter(exposed_bins.values()))
+
+
+def _run_hook(env_dir: Path, exposed_bins: dict[str, str], hook_key: str) -> None:
+    """Run a lifecycle hook from binary metadata if defined."""
+    setup = _read_binary_hooks(env_dir)
+    if not setup or hook_key not in setup:
+        return
+
+    from ixt.config.setup_toml import HookConfig
+    from ixt.core import hooks as hook_mod
+    from ixt.libs.logger import get_logger
+
+    log = get_logger("hooks")
+    hook_data = setup[hook_key]
+    hook = HookConfig(run=hook_data.get("run"), check=hook_data.get("check"))
+    bin_path = _first_bin_path(exposed_bins)
+    if not bin_path:
+        return
+
+    runner = getattr(hook_mod, f"run_{hook_key}")
+    try:
+        runner(hook, bin_path=bin_path, env_dir=env_dir)
+    except hook_mod.HookValidationError as e:
+        log.warn(f"{hook_key} hook rejected: {e}")
+
+
+class ToolAlreadyInstalledError(RuntimeError):
+    """Raised when a tool is already installed and ``force`` is False."""
+
+    def __init__(self, tool_name: str, env_dir: Path):
+        self.tool_name = tool_name
+        self.env_dir = env_dir
+        super().__init__(f"Tool '{tool_name}' is already installed in {env_dir}")
+
+
+class ToolNotInstalledError(LookupError):
+    """Raised when an operation targets a tool that isn't installed."""
+
+    def __init__(self, name: str):
+        self.name = name
+        super().__init__(f"Tool '{name}' is not installed")
+
+
+def _reject_binary_inject(bt: BackendType, inject: list[str]) -> None:
+    if bt == BackendType.BINARY and inject:
+        raise ValueError("Binary backend does not support injected packages")
+
+
+def _validate_env_dir(env_dir: Path, envs_root: Path) -> Path:
+    """Ensure *env_dir* is safely under *envs_root* (anti-traversal)."""
+    resolved = env_dir.expanduser().resolve(strict=False)
+    root = envs_root.expanduser().resolve(strict=False)
+    if resolved != root and root not in resolved.parents:
+        raise ValueError(f"Invalid env path outside {root}: {resolved}")
+    return resolved
+
+
+def _remove_env_dir(env_dir: Path, settings: Settings, *, ignore_errors: bool = False) -> None:
+    """Remove a tool env only after revalidating it stays under ``envs_dir``."""
+    safe_env_dir = env_dir.expanduser().resolve(strict=False)
+    envs_root = settings.envs_dir.expanduser().resolve(strict=False)
+    try:
+        safe_env_dir.relative_to(envs_root)
+    except ValueError as exc:
+        raise ValueError(f"Invalid env path outside {envs_root}: {safe_env_dir}") from exc
+    if safe_env_dir == envs_root:
+        raise ValueError(f"Refusing to remove env root: {envs_root}")
+    try:
+        _remove_tree_no_follow(safe_env_dir)
+    except FileNotFoundError:
+        if not ignore_errors:
+            raise
+    except OSError:
+        if not ignore_errors:
+            raise
+
+
+def _remove_tree_no_follow(path: Path) -> None:
+    """Recursively remove *path* without following symlinks."""
+    if path.is_symlink() or path.is_file():
+        path.unlink()
+        return
+    for child in path.iterdir():
+        if child.is_symlink() or child.is_file():
+            child.unlink()
+        elif child.is_dir():
+            _remove_tree_no_follow(child)
+    path.rmdir()
+
+
+def _make_tool_name(bt: BackendType, pkg_name: str, clean_spec: str) -> str:
+    """Compute the namespaced tool identifier from backend + spec."""
+    return make_tool_id(bt, pkg_name, clean_spec)
+
+
+def plan_install(
+    package_spec: str,
+    *,
+    inject: list[str] | None = None,
+    expose_rules: list[str] | None = None,
+    slot: str | None = None,
+    backend_type: BackendType | None = None,
+    setup_path: Path | None = None,
+    settings: Settings | None = None,
+    bare: bool = False,
+) -> InstallPlan:
+    """Resolve what ``install_tool`` would do, without touching disk or network.
+
+    Performs spec parsing, backend detection, registry lookup (local file),
+    and env dir resolution. Does not create directories, fetch packages,
+    or query any remote registry.
+
+    ``bare=True`` plans an install without any exposed shim; it is sugar for
+    ``expose_rules=[]`` and takes precedence when both are given.
+    """
+    settings = settings or get_settings()
+    if bare:
+        expose_rules = []
+
+    # Strip namespace prefix (e.g. @pypi:, @gh:) before further processing.
+    _forced_bt, clean_spec = strip_protocol(package_spec)
+    bt = backend_type or _forced_bt or detect_backend(clean_spec)
+    resolved_inject = list(inject or [])
+
+    # Resolve short names via registry (e.g. "ripgrep" -> "BurntSushi/ripgrep")
+    if "/" not in clean_spec and not clean_spec.startswith("@"):
+        from ixt.config.registry import lookup
+
+        entry = lookup(clean_spec)
+        if entry is not None:
+            _reg_bt, resolved = strip_protocol(entry.spec)
+            clean_spec = resolved
+
+    _reject_binary_inject(bt, resolved_inject)
+
+    # Extract tool name: each backend uses its own spec format.
+    if bt == BackendType.BINARY:
+        repo_spec = parse_spec(clean_spec)
+        pkg_name = repo_spec.repo if repo_spec else clean_spec.split("/")[-1].split("@")[0]
+    elif bt == BackendType.NODE:
+        from ixt.backends.node import parse_npm_spec
+
+        pkg_name, _ver = parse_npm_spec(clean_spec)
+    else:
+        parsed = parse_requirement(clean_spec)
+        pkg_name = parsed.name
+
+    tool_name = make_tool_id(bt, pkg_name, clean_spec, slot=slot)
+    env_dir = settings.get_tool_env_dir(tool_name)
+    env_dir = _validate_env_dir(env_dir, settings.envs_dir)
+
+    resolved_expose = [EXPOSE_MAIN] if expose_rules is None else list(expose_rules)
+
+    return InstallPlan(
+        backend=bt,
+        original_spec=package_spec,
+        resolved_spec=clean_spec,
+        pkg_name=pkg_name,
+        tool_name=tool_name,
+        env_dir=env_dir,
+        expose_rules=resolved_expose,
+        inject=resolved_inject,
+        already_installed=env_dir.exists(),
+        setup_path=setup_path,
+    )
+
+
+def display_tool_name(record: ToolRecord, settings: Settings | None = None) -> str:
+    """User-facing selector for an installed record."""
+    return display_spec_for_record(record)
+
+
+def resolve_tool_arg(
+    spec: str,
+    *,
+    settings: Settings | None = None,
+) -> str:
+    """Resolve *spec* or ``@id:<id>`` to an installed tool id.
+
+    Raises ValueError when the spec cannot be resolved.
+    """
+    return resolve_tool_name(spec, settings=settings)
+
+
+def _binary_spec_aliases(spec: str) -> set[str]:
+    """Return equivalent user-facing forms for a binary install spec."""
+    aliases = {spec}
+    repo_spec = parse_spec(spec)
+    if repo_spec is None:
+        aliases.add(strip_version_suffix(spec))
+        return aliases
+
+    hosted = f"{repo_spec.host}/{repo_spec.owner}/{repo_spec.repo}"
+    aliases.add(hosted)
+    if repo_spec.host == "github.com" and repo_spec.platform == "github":
+        aliases.add(f"{repo_spec.owner}/{repo_spec.repo}")
+    return aliases
+
+
+def _record_lookup_aliases(record: ToolRecord) -> set[str]:
+    """Names a user may type for an installed record, excluding exact ids."""
+    aliases = {record.pkg(), record.spec, display_spec_for_record(record)}
+    aliases.update(id_prefixes(record.name))
+    if record.backend == BackendType.BINARY.value:
+        aliases.update(_binary_spec_aliases(record.spec))
+    return {alias for alias in aliases if alias and alias != record.name}
+
+
+def _input_lookup_aliases(spec: str) -> tuple[BackendType | None, set[str]]:
+    """Normalize a user-supplied tool argument for installed-record lookup."""
+    forced_backend, clean_spec = strip_protocol(spec)
+    aliases = {spec, clean_spec}
+    aliases.update(_binary_spec_aliases(clean_spec))
+    return forced_backend, {alias for alias in aliases if alias}
+
+
+def _resolve_from_installed_metadata(spec: str, settings: Settings) -> str | None:
+    """Resolve *spec* against installed ``ixt.json`` records, if unambiguous."""
+    records = [ToolRecord.load_json(meta) for meta in settings.iter_installed_metadata()]
+    if is_id_selector(spec):
+        tool_id = parse_id_selector(spec)
+        if any(record.name == tool_id for record in records):
+            return tool_id
+        return None
+
+    forced_backend, input_aliases = _input_lookup_aliases(spec)
+    lookup_records = [
+        record
+        for record in records
+        if forced_backend is None or record.backend == forced_backend.value
+    ]
+
+    for record in records:
+        if record.name == spec:
+            return record.name
+
+    candidates: dict[str, ToolRecord] = {}
+    ambiguous: set[str] = set()
+    for record in lookup_records:
+        for alias in _record_lookup_aliases(record):
+            if alias in ambiguous:
+                continue
+            existing = candidates.get(alias)
+            if existing is not None and existing.name != record.name:
+                del candidates[alias]
+                ambiguous.add(alias)
+                continue
+            candidates[alias] = record
+
+    for alias in input_aliases:
+        if alias in ambiguous:
+            matches = sorted(
+                record.name for record in lookup_records if alias in _record_lookup_aliases(record)
+            )
+            joined = ", ".join(matches)
+            raise ValueError(
+                f"Tool selector '{spec}' is ambiguous: {joined}. "
+                f"Use {', '.join('@id:' + name for name in matches)}."
+            )
+        if alias in candidates:
+            return candidates[alias].name
+
+    return None
+
+
+def resolve_tool_name(spec: str, *, settings: Settings | None = None) -> str:
+    """Resolve a package spec or namespaced tool_name to the installed tool_name.
+
+    Lookup order:
+    1. If *spec* matches an existing env dir directly, return it as-is.
+    2. If *spec* matches exactly one installed metadata alias, return that record.
+    3. Fall back to ``plan_install`` spec resolution
+       (e.g. ``mikefarah/yq`` → ``yq.mikefarah.github``).
+    """
+    settings = settings or get_settings()
+    if is_id_selector(spec):
+        tool_id = parse_id_selector(spec)
+        env_dir = settings.get_tool_env_dir(tool_id)
+        if env_dir.exists():
+            return tool_id
+        raise ValueError(f"Tool id '{tool_id}' is not installed")
+
+    env_dir = settings.get_tool_env_dir(spec)
+    if env_dir.exists():
+        return spec
+    installed_name = _resolve_from_installed_metadata(spec, settings)
+    if installed_name is not None:
+        return installed_name
+    return plan_install(spec, settings=settings).tool_name
+
+
+def install_tool(
+    package_spec: str,
+    *,
+    inject: list[str] | None = None,
+    expose_rules: list[str] | None = None,
+    slot: str | None = None,
+    force: bool = False,
+    backend_type: BackendType | None = None,
+    runtime: str | None = None,
+    setup_path: Path | None = None,
+    node_shim: bool | None = None,
+    asset_pattern: str | None = None,
+    settings: Settings | None = None,
+    bare: bool = False,
+) -> ToolRecord:
+    """Install one isolated tool, expose its binaries, and return its record.
+
+    ``bare=True`` creates the env without exposing any shim; the caller can
+    run ``ixt tool config <target> expose ...`` afterwards to wire them up.
+    """
+    settings = settings or get_settings()
+    validate_slot(slot)
+    plan = plan_install(
+        package_spec,
+        inject=inject,
+        expose_rules=expose_rules,
+        slot=slot,
+        backend_type=backend_type,
+        setup_path=setup_path,
+        settings=settings,
+        bare=bare,
+    )
+    bt = plan.backend
+    clean_spec = plan.resolved_spec
+    pkg_name = plan.pkg_name
+    tool_name = plan.tool_name
+    env_dir = plan.env_dir
+    setup_path = plan.setup_path
+
+    backend = get_backend(bt, settings=settings)
+
+    if env_dir.exists():
+        if not force:
+            raise ToolAlreadyInstalledError(tool_name, env_dir)
+        # Remove old exposed bins before wiping the env.
+        meta_file = settings.get_tool_metadata_file(tool_name)
+        if meta_file.exists():
+            old = ToolRecord.load_json(meta_file)
+            unexpose_tool(old.exposed_bins, settings.bin_dir)
+        _remove_env_dir(env_dir, settings)
+
+    rules = plan.expose_rules
+    created = False
+    try:
+        created = backend.create_env(env_dir)
+        all_specs = [clean_spec] if bt == BackendType.BINARY else [clean_spec, *plan.inject]
+        install_kwargs: dict = {}
+        if bt == BackendType.NODE:
+            if runtime:
+                install_kwargs["runtime"] = runtime
+            if node_shim is not None:
+                install_kwargs["node_shim"] = node_shim
+        if setup_path and bt == BackendType.BINARY:
+            install_kwargs["setup_path"] = setup_path
+        if asset_pattern and bt == BackendType.BINARY:
+            install_kwargs["asset_pattern"] = asset_pattern
+        extra = backend.install_packages(env_dir, all_specs, **install_kwargs)
+
+        version = backend.installed_version(env_dir, pkg_name)
+
+        if rules:
+            result = expose_tool(
+                pkg_name,
+                backend,
+                env_dir,
+                settings.bin_dir,
+                rules,
+                overwrite=force,
+            )
+
+            if result.skipped:
+                from ixt.core.expose import warn_if_skipped
+                from ixt.libs.logger import get_logger
+
+                warn_if_skipped(result, tool_name, get_logger("install"))
+            linked_bins = result.linked
+        else:
+            linked_bins = {}
+
+        record = ToolRecord(
+            name=tool_name,
+            pkg_name=pkg_name,
+            backend=bt.value,
+            spec=clean_spec,
+            env_dir=str(env_dir),
+            version=version,
+            injected=list(plan.inject),
+            expose_rules=rules,
+            exposed_bins=linked_bins,
+            node_shim=node_shim,
+            asset_pattern=extra.get("asset_pattern") if extra else None,
+            asset_pattern_forced=bool(extra.get("asset_pattern_forced")) if extra else False,
+        )
+        record.save_json(settings.get_tool_metadata_file(tool_name))
+
+        # Run post-install hook if defined (binary backend only for now).
+        if bt == BackendType.BINARY and linked_bins:
+            _run_hook(env_dir, linked_bins, "post_install")
+
+        return record
+    except Exception:
+        if created:
+            _remove_env_dir(env_dir, settings, ignore_errors=True)
+        raise
+
+
+def uninstall_tool(
+    tool_name: str,
+    *,
+    settings: Settings | None = None,
+) -> Path:
+    """Remove exposed binaries and the tool environment from disk."""
+    settings = settings or get_settings()
+    env_dir = settings.get_tool_env_dir(tool_name)
+    if not env_dir.exists():
+        raise FileNotFoundError(env_dir)
+
+    # Clean up exposed bins first.
+    meta_file = settings.get_tool_metadata_file(tool_name)
+    if meta_file.exists():
+        record = ToolRecord.load_json(meta_file)
+
+        # Run pre-uninstall hook before removing anything.
+        if record.exposed_bins:
+            _run_hook(env_dir, record.exposed_bins, "pre_uninstall")
+
+        unexpose_tool(record.exposed_bins, settings.bin_dir)
+
+    _remove_env_dir(env_dir, settings)
+    return env_dir
+
+
+def uninstall_all(
+    *,
+    settings: Settings | None = None,
+) -> dict[str, Path | Exception]:
+    """Uninstall every installed tool. Returns a map of tool_name -> removed path or error."""
+    settings = settings or get_settings()
+    results: dict[str, Path | Exception] = {}
+
+    for meta_file in settings.iter_installed_metadata():
+        name = meta_file.parent.name
+        try:
+            results[name] = uninstall_tool(name, settings=settings)
+        except Exception as exc:
+            results[name] = exc
+
+    return results