ixt-cli 0.8.0__py3-none-any.whl

ixt/core/apply.py

@@ -0,0 +1,564 @@
+"""Apply ixt.toml configuration — sync installed tools with declared config."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import TypeVar
+
+from ixt.config.models import ToolRecord
+from ixt.config.settings import Settings, get_settings
+from ixt.config.toml import IxtConfig, ToolSpec, find_config_file, load_config
+from ixt.core.apply_actions import (
+    ApplyPlan,
+    ApplyResult,
+    InjectAction,
+    InstallAction,
+    ReexposeAction,
+    ReinstallAction,
+    RepolicyAction,
+    UninjectAction,
+)
+from ixt.core.backend import BackendType
+
+__all__ = [
+    "ApplyPlan",
+    "ApplyResult",
+    "InjectAction",
+    "InstallAction",
+    "ReexposeAction",
+    "ReinstallAction",
+    "RemovalsRefused",
+    "RepolicyAction",
+    "UninjectAction",
+    "apply_config",
+    "plan_apply",
+]
+
+ApplyAction = (
+    InstallAction
+    | ReinstallAction
+    | InjectAction
+    | UninjectAction
+    | ReexposeAction
+    | RepolicyAction
+    | str
+)
+ApplyProgress = Callable[[str, str, ApplyAction, int, int, ApplyResult, Exception | None], None]
+_T = TypeVar("_T")
+
+
+class RemovalsRefused(Exception):
+    """Raised when a ``confirm_removals`` callback declines the removals."""
+
+
+def _spec_to_install_spec(spec: ToolSpec) -> str:
+    """Build the package spec string from a ToolSpec (name + optional version).
+
+    The ``[tools]`` key is the install spec unless ``install`` is set. Version
+    constraints stay as a separate field so exported TOML remains easy to scan.
+    """
+    install = spec.install or spec.name
+    if not spec.version:
+        return install
+
+    from ixt.core.backend import detect_backend
+
+    backend = detect_backend(install)
+    version = spec.version.strip()
+    if backend == BackendType.BINARY:
+        return f"{install}@{version.lstrip('=')}"
+    if backend == BackendType.NODE:
+        npm_version = version[2:] if version.startswith("==") else version
+        return f"{install}@{npm_version}"
+    return f"{install}{version}"
+
+
+def _pinned_version(spec_version: str | None) -> str | None:
+    """Return the concrete pinned version if the spec pins exactly (``==X.Y.Z``).
+
+    Ranges (``>=``, ``~=``, ``<``, etc.) never return a pinned version — they
+    describe a set of acceptable versions, not one.
+    """
+    if not spec_version:
+        return None
+    if spec_version.startswith("=="):
+        return spec_version[2:].strip() or None
+    return None
+
+
+def _policy_drifted(spec: ToolSpec, record: ToolRecord) -> bool:
+    return (
+        spec.env_base != record.env_base
+        or spec.env_allow != record.env_allow
+        or spec.env_deny != record.env_deny
+        or spec.fs_base != record.fs_base
+        or spec.fs_ro != record.fs_ro
+        or spec.fs_rw != record.fs_rw
+        or spec.fs_scratch != record.fs_scratch
+    )
+
+
+def _version_drifted(spec: ToolSpec, record: ToolRecord) -> bool:
+    """True if the declared constraint is not satisfied by the installed version.
+
+    - No version constraint → never drifts.
+    - Exact pin (``==X.Y.Z``) → drift if installed differs.
+    - Range (``>=``, ``<``, ``~=``, ``!=``, …) → drift if installed is outside.
+    """
+    from ixt.libs.semver import version_satisfies
+
+    if not spec.version:
+        return False
+    installed = record.version or ""
+    if not installed:
+        return True
+    return not version_satisfies(installed, spec.version)
+
+
+def _inject_drifted(spec: ToolSpec, record: ToolRecord) -> bool:
+    """True if the declared inject set differs from what's installed."""
+    return sorted(spec.inject) != sorted(record.injected)
+
+
+def _expose_drifted(spec: ToolSpec, record: ToolRecord) -> bool:
+    """True if expose rules differ."""
+    return sorted(spec.expose) != sorted(record.expose_rules)
+
+
+def _get_installed_tools(settings: Settings) -> dict[str, ToolRecord]:
+    """Return a dict of tool_name → ToolRecord for all installed tools."""
+    result: dict[str, ToolRecord] = {}
+    for meta_file in settings.iter_installed_metadata():
+        record = ToolRecord.load_json(meta_file)
+        result[record.name] = record
+    return result
+
+
+def _append_install(plan: ApplyPlan, name: str, spec: ToolSpec) -> None:
+    plan.to_install.append(
+        InstallAction(
+            name=name,
+            install_spec=_spec_to_install_spec(spec),
+            backend=None,
+        )
+    )
+
+
+def _append_reinstall(
+    plan: ApplyPlan,
+    name: str,
+    spec: ToolSpec,
+    record: ToolRecord,
+    *,
+    inject_drift: bool,
+) -> None:
+    reasons = ["version"]
+    if inject_drift:
+        reasons.append("inject")
+    plan.to_reinstall.append(
+        ReinstallAction(
+            name=name,
+            install_spec=_spec_to_install_spec(spec),
+            backend=None,
+            old_version=record.version,
+            pinned_version=_pinned_version(spec.version),
+            old_inject=list(record.injected),
+            new_inject=list(spec.inject),
+            expose_rules=list(spec.expose),
+            reasons=reasons,
+        )
+    )
+
+
+def _append_inject_diff(plan: ApplyPlan, name: str, spec: ToolSpec, record: ToolRecord) -> None:
+    old_set = set(record.injected)
+    new_set = set(spec.inject)
+    to_add = sorted(new_set - old_set)
+    to_remove = sorted(old_set - new_set)
+    if to_add:
+        plan.to_inject.append(InjectAction(name=name, packages=to_add))
+    if to_remove:
+        plan.to_uninject.append(UninjectAction(name=name, packages=to_remove))
+
+
+def _plan_one_tool(
+    plan: ApplyPlan,
+    name: str,
+    spec: ToolSpec,
+    installed: dict[str, ToolRecord],
+) -> None:
+    """Classify one tool into the appropriate plan bucket."""
+    if name not in installed:
+        _append_install(plan, name, spec)
+        return
+
+    record = installed[name]
+    version_drift = _version_drifted(spec, record)
+    inject_drift = _inject_drifted(spec, record)
+    expose_drift = _expose_drifted(spec, record)
+
+    if version_drift:
+        # A full reinstall atomically covers any concurrent inject/expose
+        # drift — simpler than coordinating multiple sub-operations.
+        _append_reinstall(plan, name, spec, record, inject_drift=inject_drift)
+        return
+
+    if inject_drift:
+        _append_inject_diff(plan, name, spec, record)
+
+    if expose_drift:
+        plan.to_reexpose.append(
+            ReexposeAction(
+                name=name,
+                old_rules=list(record.expose_rules),
+                new_rules=list(spec.expose),
+            )
+        )
+
+    if _policy_drifted(spec, record):
+        plan.to_repolicy.append(RepolicyAction(name=name))
+
+
+def plan_apply(
+    config: IxtConfig,
+    installed: dict[str, ToolRecord],
+    *,
+    remove_unlisted: bool = False,
+) -> ApplyPlan:
+    """Compute the diff between config and installed state.
+
+    Pure function: reads no filesystem, performs no network, no mutation.
+    The caller provides already-loaded *config* and *installed* records.
+    """
+    plan = ApplyPlan()
+
+    for name, spec in config.tools.items():
+        _plan_one_tool(plan, name, spec, installed)
+
+    if remove_unlisted:
+        for name in installed:
+            if name not in config.tools:
+                plan.to_remove.append(name)
+
+    return plan
+
+
+def _normalize_config_for_apply(config: IxtConfig, settings: Settings) -> IxtConfig:
+    """Resolve user-facing TOML keys to installed ids before planning."""
+    tools: dict[str, ToolSpec] = {}
+    source_keys: dict[str, str] = {}
+    for name, spec in config.tools.items():
+        tool_id, normalized = _normalize_tool_entry(name, spec, settings)
+        existing_key = source_keys.get(tool_id)
+        if existing_key is not None:
+            raise ValueError(
+                f"Config entries '{existing_key}' and '{name}' resolve to the same id '{tool_id}'"
+            )
+        tools[tool_id] = normalized
+        source_keys[tool_id] = name
+    return IxtConfig(tools=tools, settings=dict(config.settings), source_path=config.source_path)
+
+
+def _normalize_tool_entry(
+    name: str,
+    spec: ToolSpec,
+    settings: Settings,
+) -> tuple[str, ToolSpec]:
+    """Return the target installed id and an executable ToolSpec.
+
+    Human-written entries use the package spec as key (``ruff = {}``,
+    ``"@gh:owner/repo" = {}``). Entries with ``install`` use the key as
+    a slot, e.g. ``ruff-old = { install = "@pypi:ruff" }``.
+    """
+    from ixt.core.identity import apply_slot, validate_slot
+    from ixt.core.install import plan_install
+
+    install_spec = _spec_to_install_spec(spec)
+    base_id = plan_install(install_spec, settings=settings).tool_name
+    if spec.install:
+        tool_id = apply_slot(base_id, validate_slot(name))
+        return tool_id, spec
+    return base_id, spec
+
+
+def apply_config(
+    config: IxtConfig | None = None,
+    config_path: Path | None = None,
+    *,
+    remove_unlisted: bool = False,
+    settings: Settings | None = None,
+    confirm_removals: Callable[[list[str]], bool] | None = None,
+    progress: ApplyProgress | None = None,
+) -> ApplyResult:
+    """Sync installed tools to match ixt.toml.
+
+    Parameters
+    ----------
+    config:
+        Parsed config. If None, loaded from *config_path* or auto-discovered.
+    config_path:
+        Explicit path to ixt.toml. Ignored if *config* is given.
+    remove_unlisted:
+        If True, uninstall tools not listed in config.
+    settings:
+        Custom settings (for testing).
+    confirm_removals:
+        Optional callback invoked with the list of tools about to be
+        uninstalled. If it returns ``False``, ``RemovalsRefused`` is raised
+        and no mutation occurs.
+    progress:
+        Optional callback invoked before and after every planned action.
+        The first argument is ``"start"`` or ``"done"``.
+    """
+    settings = settings or get_settings()
+    result = ApplyResult()
+
+    if config is None:
+        path = config_path or find_config_file()
+        if path is None:
+            raise FileNotFoundError("No ixt.toml found")
+        config = load_config(path)
+
+    installed = _get_installed_tools(settings)
+    config = _normalize_config_for_apply(config, settings)
+    plan = plan_apply(config, installed, remove_unlisted=remove_unlisted)
+
+    if (
+        plan.to_remove
+        and confirm_removals is not None
+        and not confirm_removals(list(plan.to_remove))
+    ):
+        raise RemovalsRefused()
+
+    actions = _iter_plan_actions(plan)
+    total = len(actions)
+    for index, (kind, action) in enumerate(actions, 1):
+        if progress is not None:
+            progress("start", kind, action, index, total, result, None)
+        error = _execute_action(kind, action, config, installed, settings, result)
+        if progress is not None:
+            progress("done", kind, action, index, total, result, error)
+
+    return result
+
+
+def _iter_plan_actions(plan: ApplyPlan) -> list[tuple[str, ApplyAction]]:
+    actions: list[tuple[str, ApplyAction]] = []
+    actions.extend(("install", action) for action in plan.to_install)
+    actions.extend(("reinstall", action) for action in plan.to_reinstall)
+    actions.extend(("inject", action) for action in plan.to_inject)
+    actions.extend(("uninject", action) for action in plan.to_uninject)
+    actions.extend(("re-expose", action) for action in plan.to_reexpose)
+    actions.extend(("policy", action) for action in plan.to_repolicy)
+    actions.extend(("remove", name) for name in plan.to_remove)
+    return actions
+
+
+def _expect_action(kind: str, action: ApplyAction, expected: type[_T]) -> _T:
+    if not isinstance(action, expected):
+        raise TypeError(
+            f"apply action {kind!r} expected {expected.__name__}, got {type(action).__name__}"
+        )
+    return action
+
+
+def _execute_action(
+    kind: str,
+    action: ApplyAction,
+    config: IxtConfig,
+    installed: dict[str, ToolRecord],
+    settings: Settings,
+    result: ApplyResult,
+) -> Exception | None:
+    if kind == "install":
+        action = _expect_action(kind, action, InstallAction)
+        return _execute_install(action, config.tools[action.name], settings, result)
+    if kind == "reinstall":
+        action = _expect_action(kind, action, ReinstallAction)
+        return _execute_reinstall(action, config.tools[action.name], settings, result)
+    if kind == "inject":
+        action = _expect_action(kind, action, InjectAction)
+        return _execute_inject(action, settings, result)
+    if kind == "uninject":
+        action = _expect_action(kind, action, UninjectAction)
+        return _execute_uninject(action, settings, result)
+    if kind == "re-expose":
+        action = _expect_action(kind, action, ReexposeAction)
+        return _execute_reexpose(action, installed[action.name], settings, result)
+    if kind == "policy":
+        action = _expect_action(kind, action, RepolicyAction)
+        return _execute_repolicy(
+            action, config.tools[action.name], installed[action.name], settings, result
+        )
+    if kind == "remove":
+        action = _expect_action(kind, action, str)
+        return _execute_remove(action, settings, result)
+    raise ValueError(f"unknown apply action kind: {kind!r}")
+
+
+def _apply_spec_policy(name: str, spec: ToolSpec, settings: Settings) -> None:
+    """Write policy fields from spec into the installed record and regenerate shim."""
+    from ixt.config.env_policy import apply_policy
+
+    meta_file = settings.get_tool_metadata_file(name)
+    if not meta_file.exists():
+        return
+    record = ToolRecord.load_json(meta_file)
+    record.env_base = spec.env_base
+    record.env_allow = list(spec.env_allow)
+    record.env_deny = dict(spec.env_deny)
+    record.fs_base = spec.fs_base
+    record.fs_ro = list(spec.fs_ro)
+    record.fs_rw = list(spec.fs_rw)
+    record.fs_scratch = list(spec.fs_scratch)
+    record.save_json(meta_file)
+    if record.exposed_bins:
+        apply_policy(record, settings.bin_dir)
+
+
+def _execute_install(
+    action: InstallAction, spec: ToolSpec, settings: Settings, result: ApplyResult
+) -> Exception | None:
+    from ixt.core.install import install_tool
+
+    try:
+        install_tool(
+            action.install_spec,
+            inject=spec.inject or None,
+            expose_rules=spec.expose,
+            slot=_slot_for_config_key(action.name, action.install_spec, spec, settings),
+            runtime=spec.runtime,
+            node_shim=spec.node_shim,
+            asset_pattern=spec.asset_pattern,
+            settings=settings,
+        )
+        _apply_spec_policy(action.name, spec, settings)
+        result.installed.append(action.name)
+        return None
+    except Exception as exc:
+        result.errors[action.name] = exc
+        return exc
+
+
+def _execute_reinstall(
+    action: ReinstallAction, spec: ToolSpec, settings: Settings, result: ApplyResult
+) -> Exception | None:
+    from ixt.core.install import install_tool
+
+    try:
+        install_tool(
+            action.install_spec,
+            inject=spec.inject or None,
+            expose_rules=spec.expose,
+            slot=_slot_for_config_key(action.name, action.install_spec, spec, settings),
+            force=True,
+            runtime=spec.runtime,
+            node_shim=spec.node_shim,
+            asset_pattern=spec.asset_pattern,
+            settings=settings,
+        )
+        _apply_spec_policy(action.name, spec, settings)
+        result.updated.append(action.name)
+        return None
+    except Exception as exc:
+        result.errors[action.name] = exc
+        return exc
+
+
+def _slot_for_config_key(
+    name: str,
+    install_spec: str,
+    spec: ToolSpec,
+    settings: Settings,
+) -> str | None:
+    """Return the slot needed to materialize a configured slotted entry."""
+    if not spec.install:
+        return None
+
+    from ixt.core.identity import slot_from_id
+    from ixt.core.install import plan_install
+
+    base_id = plan_install(install_spec, settings=settings).tool_name
+    if name == base_id:
+        return None
+    slot = slot_from_id(name, base_id)
+    if slot is None:
+        configured_spec = spec.install or spec.name
+        raise ValueError(
+            f"Config id '{name}' does not match install spec '{configured_spec}' "
+            f"(expected '{base_id}' or a slotted id ending with '.{base_id}')"
+        )
+    return slot
+
+
+def _execute_repolicy(
+    action: RepolicyAction,
+    spec: ToolSpec,
+    record: ToolRecord,
+    settings: Settings,
+    result: ApplyResult,
+) -> Exception | None:
+    try:
+        _apply_spec_policy(action.name, spec, settings)
+        result.updated.append(action.name)
+        return None
+    except Exception as exc:
+        result.errors[action.name] = exc
+        return exc
+
+
+def _execute_inject(
+    action: InjectAction, settings: Settings, result: ApplyResult
+) -> Exception | None:
+    from ixt.core.inject import inject_packages
+
+    try:
+        inject_packages(action.name, action.packages, settings=settings)
+        result.updated.append(action.name)
+        return None
+    except Exception as exc:
+        result.errors[action.name] = exc
+        return exc
+
+
+def _execute_uninject(
+    action: UninjectAction, settings: Settings, result: ApplyResult
+) -> Exception | None:
+    from ixt.core.inject import uninject_packages
+
+    try:
+        uninject_packages(action.name, action.packages, settings=settings)
+        if action.name not in result.updated:
+            result.updated.append(action.name)
+        return None
+    except Exception as exc:
+        result.errors[action.name] = exc
+        return exc
+
+
+def _execute_reexpose(
+    action: ReexposeAction, record: ToolRecord, settings: Settings, result: ApplyResult
+) -> Exception | None:
+    from ixt.core.expose import reexpose_tool
+
+    try:
+        reexpose_tool(record, action.new_rules, settings)
+        if action.name not in result.updated:
+            result.updated.append(action.name)
+        return None
+    except Exception as exc:
+        result.errors[action.name] = exc
+        return exc
+
+
+def _execute_remove(name: str, settings: Settings, result: ApplyResult) -> Exception | None:
+    from ixt.core.install import uninstall_tool
+
+    try:
+        uninstall_tool(name, settings=settings)
+        result.removed.append(name)
+        return None
+    except Exception as exc:
+        result.errors[name] = exc
+        return exc

ixt/core/apply_actions.py

@@ -0,0 +1,106 @@
+"""Action dataclasses produced by ``plan_apply`` and consumed by ``apply_config``.
+
+Pure data — no behavior, no I/O. Kept apart from ``apply.py`` so the planner
+and executor stay below the file-size threshold and the dataclasses can be
+imported without dragging in the apply pipeline.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(slots=True)
+class InstallAction:
+    """A tool in ixt.toml that is not yet installed."""
+
+    name: str
+    install_spec: str
+    backend: str | None
+
+
+@dataclass(slots=True)
+class ReinstallAction:
+    """A tool whose version and/or inject set drifted from ixt.toml.
+
+    A full reinstall is triggered because it covers version, inject add,
+    inject remove, and expose changes in one go — simpler than coordinating
+    upgrade/inject/uninject separately.
+    """
+
+    name: str
+    install_spec: str
+    backend: str | None
+    old_version: str | None
+    pinned_version: str | None
+    old_inject: list[str]
+    new_inject: list[str]
+    expose_rules: list[str]
+    reasons: list[str]  # subset of {"version", "inject"}
+
+
+@dataclass(slots=True)
+class ReexposeAction:
+    """A tool whose only drift is its expose rules (cheaper than reinstall)."""
+
+    name: str
+    old_rules: list[str]
+    new_rules: list[str]
+
+
+@dataclass(slots=True)
+class InjectAction:
+    """Add packages to an installed tool's inject set (no version drift)."""
+
+    name: str
+    packages: list[str]
+
+
+@dataclass(slots=True)
+class UninjectAction:
+    """Remove packages from an installed tool's inject set (no version drift)."""
+
+    name: str
+    packages: list[str]
+
+
+@dataclass(slots=True)
+class RepolicyAction:
+    """A tool whose policy drifted from ixt.toml (no reinstall needed)."""
+
+    name: str
+
+
+@dataclass(slots=True)
+class ApplyPlan:
+    """Diff between ixt.toml and installed tools — zero side effects."""
+
+    to_install: list[InstallAction] = field(default_factory=list)
+    to_reinstall: list[ReinstallAction] = field(default_factory=list)
+    to_inject: list[InjectAction] = field(default_factory=list)
+    to_uninject: list[UninjectAction] = field(default_factory=list)
+    to_reexpose: list[ReexposeAction] = field(default_factory=list)
+    to_repolicy: list[RepolicyAction] = field(default_factory=list)
+    to_remove: list[str] = field(default_factory=list)
+
+    @property
+    def is_empty(self) -> bool:
+        return not (
+            self.to_install
+            or self.to_reinstall
+            or self.to_inject
+            or self.to_uninject
+            or self.to_reexpose
+            or self.to_repolicy
+            or self.to_remove
+        )
+
+
+@dataclass(slots=True)
+class ApplyResult:
+    """Summary of an executed apply operation."""
+
+    installed: list[str] = field(default_factory=list)
+    removed: list[str] = field(default_factory=list)
+    updated: list[str] = field(default_factory=list)
+    errors: dict[str, Exception] = field(default_factory=dict)