ixt-cli 0.8.0__py3-none-any.whl

ixt/core/hooks.py

@@ -0,0 +1,182 @@
+"""Lifecycle hook execution engine with security validation.
+
+Hooks are defined in ``ixt.setup.toml`` and run at two lifecycle points:
+
+* ``post_install`` — after binaries are exposed
+* ``pre_uninstall`` — before environment removal
+
+Three security locks are enforced:
+
+1. **bin-only**: command must start with ``{bin}``
+2. **action whitelist**: last positional arg must be in the allowed set
+3. **precheck** (post_install only): skip ``run`` if ``check`` succeeds with output
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ixt.config.setup_toml import HookConfig
+from ixt.libs.logger import get_logger
+from ixt.libs.shell import ShellError, shell_run_output
+
+log = get_logger(__name__)
+
+# ---------------------------------------------------------------------------
+# Whitelists
+# ---------------------------------------------------------------------------
+
+POST_INSTALL_ACTIONS = frozenset({"init", "setup", "install"})
+PRE_UNINSTALL_ACTIONS = frozenset({"cleanup", "uninstall", "teardown"})
+
+# ---------------------------------------------------------------------------
+# Template expansion
+# ---------------------------------------------------------------------------
+
+
+def _expand_template(cmd: str, bin_path: str, env_dir: str) -> str:
+    """Replace ``{bin}`` and ``{env_dir}`` placeholders."""
+    return cmd.replace("{bin}", bin_path).replace("{env_dir}", env_dir)
+
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+
+class HookValidationError(ValueError):
+    """Raised when a hook command fails security validation."""
+
+
+def _split_args(cmd: str) -> list[str]:
+    """Split a command string into arguments (simple whitespace split).
+
+    Respects quoted strings for paths with spaces.
+    """
+    import shlex
+
+    return shlex.split(cmd)
+
+
+def _last_positional_arg(args: list[str]) -> str | None:
+    """Return the last non-flag argument (not starting with ``-``)."""
+    for arg in reversed(args):
+        if not arg.startswith("-"):
+            return arg
+    return None
+
+
+def validate_hook(
+    cmd: str,
+    *,
+    bin_path: str,
+    allowed_actions: frozenset[str],
+) -> list[str]:
+    """Validate a hook command against the three security locks.
+
+    Returns the parsed argument list ready for execution.
+
+    Raises:
+        HookValidationError: if any lock fails.
+    """
+    args = _split_args(cmd)
+
+    if not args:
+        raise HookValidationError("Hook command is empty")
+
+    # Lock 1: must start with {bin} (already expanded)
+    if args[0] != bin_path:
+        raise HookValidationError(
+            f"Hook command must start with {{bin}} ({bin_path}), got: {args[0]}"
+        )
+
+    # Lock 2: last positional arg must be in the whitelist
+    if len(args) < 2:
+        raise HookValidationError("Hook command must include an action argument")
+
+    action = _last_positional_arg(args[1:])
+    if action is None:
+        raise HookValidationError("Hook command has no positional action argument")
+
+    if action not in allowed_actions:
+        raise HookValidationError(
+            f"Action '{action}' not in allowed set: {sorted(allowed_actions)}"
+        )
+
+    return args
+
+
+# ---------------------------------------------------------------------------
+# Execution
+# ---------------------------------------------------------------------------
+
+
+def run_hook(
+    hook: HookConfig,
+    *,
+    bin_path: str,
+    env_dir: Path,
+    allowed_actions: frozenset[str],
+) -> bool:
+    """Execute a lifecycle hook if defined.
+
+    Returns True if the hook ran, False if skipped.
+
+    Raises:
+        HookValidationError: if the command fails validation.
+    """
+    if not hook.run:
+        return False
+
+    env_dir_str = str(env_dir)
+
+    # Precheck: if check is defined and succeeds with output, skip run.
+    if hook.check:
+        check_cmd = _expand_template(hook.check, bin_path, env_dir_str)
+        check_args = validate_hook(check_cmd, bin_path=bin_path, allowed_actions=allowed_actions)
+        try:
+            output = shell_run_output(check_args)
+            if output.strip():
+                log.debug("Hook precheck passed (non-empty output), skipping run")
+                return False
+        except ShellError:
+            # Check failed (non-zero exit) → proceed with run
+            log.debug("Hook precheck failed (non-zero exit), proceeding with run")
+
+    # Execute run
+    run_cmd = _expand_template(hook.run, bin_path, env_dir_str)
+    run_args = validate_hook(run_cmd, bin_path=bin_path, allowed_actions=allowed_actions)
+
+    log.info(f"Running hook: {' '.join(run_args)}")
+    shell_run_output(run_args)
+    return True
+
+
+def run_post_install(
+    hook: HookConfig,
+    *,
+    bin_path: str,
+    env_dir: Path,
+) -> bool:
+    """Run a post-install hook with post_install action whitelist."""
+    return run_hook(
+        hook,
+        bin_path=bin_path,
+        env_dir=env_dir,
+        allowed_actions=POST_INSTALL_ACTIONS,
+    )
+
+
+def run_pre_uninstall(
+    hook: HookConfig,
+    *,
+    bin_path: str,
+    env_dir: Path,
+) -> bool:
+    """Run a pre-uninstall hook with pre_uninstall action whitelist."""
+    return run_hook(
+        hook,
+        bin_path=bin_path,
+        env_dir=env_dir,
+        allowed_actions=PRE_UNINSTALL_ACTIONS,
+    )

ixt/core/identity.py

@@ -0,0 +1,148 @@
+"""Tool identity helpers.
+
+User-facing commands normally accept package specs (``ruff``, ``alajmo/mani``).
+The installed environment id is the unique technical reference
+(``mani.alajmo.github``) and can be selected explicitly with ``@id:<id>``.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from ixt.config.models import ToolRecord
+from ixt.core.backend import BackendType, strip_protocol
+from ixt.libs.req_spec import parse_requirement
+from ixt.net.source import parse_spec, strip_version_suffix
+
+ID_SELECTOR_PREFIX = "@id:"
+_SLOT_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+@dataclass(frozen=True, slots=True)
+class ToolIdentity:
+    """The stable identity surfaces for one installed tool."""
+
+    id: str
+    spec: str
+    display: str
+    backend: str
+    pkg: str
+
+
+def is_id_selector(value: str) -> bool:
+    return value.startswith(ID_SELECTOR_PREFIX)
+
+
+def parse_id_selector(value: str) -> str:
+    """Return the exact id from ``@id:<id>``, or raise ValueError."""
+    if not is_id_selector(value):
+        raise ValueError(f"Not an id selector: {value!r}")
+    tool_id = value[len(ID_SELECTOR_PREFIX) :].strip()
+    if not tool_id:
+        raise ValueError("Empty @id: selector")
+    return tool_id
+
+
+def validate_slot(slot: str | None) -> str | None:
+    """Validate a side-by-side install slot.
+
+    A slot is a single id segment that gets prepended to the generated base id.
+    It deliberately excludes dots, slashes, colons, and spaces so id-prefix
+    matching remains predictable.
+    """
+    if slot is None:
+        return None
+    if not _SLOT_RE.match(slot):
+        raise ValueError("Invalid slot: use only letters, digits, '-' or '_'")
+    return slot
+
+
+def apply_slot(base_id: str, slot: str | None) -> str:
+    slot = validate_slot(slot)
+    return f"{slot}.{base_id}" if slot else base_id
+
+
+def make_tool_id(bt: BackendType, pkg_name: str, spec: str, *, slot: str | None = None) -> str:
+    """Compute the canonical installed tool id from backend, package and spec."""
+    _, clean_spec = strip_protocol(spec)
+    if bt == BackendType.BINARY:
+        repo_spec = parse_spec(clean_spec)
+        base_id = (
+            f"{repo_spec.repo}.{repo_spec.owner}.{repo_spec.platform}" if repo_spec else pkg_name
+        )
+    elif bt == BackendType.NODE:
+        if clean_spec.startswith("@"):
+            scope = clean_spec.lstrip("@").split("/")[0]
+            short_pkg = pkg_name.split("/")[-1] if "/" in pkg_name else pkg_name.lstrip("@")
+            base_id = f"{short_pkg}.{scope}.npm"
+        else:
+            base_id = f"{pkg_name}.npm"
+    else:
+        base_id = f"{pkg_name}.pypi"
+    return apply_slot(base_id, slot)
+
+
+def slot_from_id(tool_id: str, base_id: str) -> str | None:
+    """Return the slot prefix if *tool_id* is a slotted variant of *base_id*."""
+    if tool_id == base_id:
+        return None
+    suffix = f".{base_id}"
+    if not tool_id.endswith(suffix):
+        return None
+    slot = tool_id[: -len(suffix)]
+    return validate_slot(slot)
+
+
+def id_prefixes(tool_id: str) -> set[str]:
+    """Return segment prefixes for a dotted id, excluding the full id."""
+    parts = [part for part in tool_id.split(".") if part]
+    return {".".join(parts[:i]) for i in range(1, len(parts))}
+
+
+def _binary_display_spec(spec: str) -> str:
+    _, clean = strip_protocol(spec)
+    repo_spec = parse_spec(clean)
+    if repo_spec is None:
+        return strip_version_suffix(clean)
+    if repo_spec.platform == "github" and repo_spec.host == "github.com":
+        return f"{repo_spec.owner}/{repo_spec.repo}"
+    return f"{repo_spec.host}/{repo_spec.owner}/{repo_spec.repo}"
+
+
+def _node_display_spec(spec: str) -> str:
+    from ixt.backends.node import parse_npm_spec
+
+    name, _version = parse_npm_spec(spec)
+    return name
+
+
+def _python_display_spec(spec: str, fallback: str) -> str:
+    try:
+        return parse_requirement(spec).name
+    except ValueError:
+        return fallback
+
+
+def display_spec_for_record(record: ToolRecord) -> str:
+    """Return the normal user-facing selector for an installed record."""
+    if record.source == "local":
+        return record.spec
+    if record.backend == "binary":
+        return _binary_display_spec(record.spec)
+    if record.backend == "node":
+        return _node_display_spec(record.spec)
+    if record.backend == "python":
+        return _python_display_spec(record.spec, record.pkg())
+    return record.pkg()
+
+
+def identity_for_record(record: ToolRecord) -> ToolIdentity:
+    spec = display_spec_for_record(record)
+    return ToolIdentity(
+        id=record.name,
+        spec=spec,
+        display=spec,
+        backend=record.backend,
+        pkg=record.pkg(),
+    )

ixt/core/inject.py

@@ -0,0 +1,143 @@
+"""Inject and uninject packages into/from an installed tool's environment."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ixt.config.models import ToolRecord
+from ixt.config.settings import Settings, get_settings
+from ixt.core.backend import BackendType, get_backend
+from ixt.core.expose import expose_tool, unexpose_tool
+from ixt.libs.req_spec import parse_requirement
+
+
+class PackageAlreadyInjectedError(ValueError):
+    """Raised when trying to inject a package that's already injected."""
+
+    def __init__(self, package: str, tool_name: str):
+        self.package = package
+        self.tool_name = tool_name
+        super().__init__(f"Package '{package}' is already injected in '{tool_name}'")
+
+
+class PackageNotInjectedError(ValueError):
+    """Raised when trying to uninject a package that isn't injected."""
+
+    def __init__(self, package: str, tool_name: str):
+        self.package = package
+        self.tool_name = tool_name
+        super().__init__(f"Package '{package}' is not injected in '{tool_name}'")
+
+
+def inject_packages(
+    tool_name: str,
+    packages: list[str],
+    *,
+    settings: Settings | None = None,
+) -> ToolRecord:
+    """Inject additional packages into an installed tool's environment.
+
+    Validates that none of the packages are already injected, installs them
+    into the existing environment, re-exposes binaries, and updates the record.
+
+    Returns the updated ToolRecord.
+    """
+    settings = settings or get_settings()
+    meta_file = settings.get_tool_metadata_file(tool_name)
+
+    if not meta_file.exists():
+        raise FileNotFoundError(f"Tool '{tool_name}' is not installed")
+
+    record = ToolRecord.load_json(meta_file)
+    bt = BackendType(record.backend)
+    if bt == BackendType.BINARY:
+        raise ValueError("Binary backend does not support injected packages")
+
+    # Check for duplicates against existing injected packages.
+    existing_names = {parse_requirement(s).name for s in record.injected}
+    for spec in packages:
+        name = parse_requirement(spec).name
+        if name in existing_names:
+            raise PackageAlreadyInjectedError(name, tool_name)
+
+    env_dir = Path(record.env_dir)
+    backend = get_backend(bt, settings=settings)
+
+    backend.install_packages(env_dir, packages)
+
+    # Update injected list (sorted for deterministic output).
+    record.injected = sorted([*record.injected, *packages])
+
+    # Re-expose to pick up any new binaries from injected packages.
+    unexpose_tool(record.exposed_bins, settings.bin_dir)
+    result = expose_tool(
+        record.pkg(),
+        backend,
+        env_dir,
+        settings.bin_dir,
+        record.expose_rules,
+        overwrite=True,
+    )
+    record.exposed_bins = result.linked
+
+    record.save_json(meta_file)
+    return record
+
+
+def uninject_packages(
+    tool_name: str,
+    packages: list[str],
+    *,
+    settings: Settings | None = None,
+) -> ToolRecord:
+    """Remove injected packages from an installed tool's environment.
+
+    Validates that the packages are currently injected, uninstalls them,
+    re-exposes binaries (some may disappear), and updates the record.
+
+    Returns the updated ToolRecord.
+    """
+    settings = settings or get_settings()
+    meta_file = settings.get_tool_metadata_file(tool_name)
+
+    if not meta_file.exists():
+        raise FileNotFoundError(f"Tool '{tool_name}' is not installed")
+
+    record = ToolRecord.load_json(meta_file)
+
+    # Build a map of injected name → spec for validation.
+    injected_names: dict[str, str] = {
+        parse_requirement(spec).name: spec for spec in record.injected
+    }
+
+    removing_names: set[str] = set()
+    for spec in packages:
+        name = parse_requirement(spec).name
+        if name not in injected_names:
+            raise PackageNotInjectedError(name, tool_name)
+        removing_names.add(name)
+
+    env_dir = Path(record.env_dir)
+    bt = BackendType(record.backend)
+    backend = get_backend(bt, settings=settings)
+
+    for name in removing_names:
+        backend.uninstall_package(env_dir, name)
+
+    # Remove from injected list (reuse already-parsed names).
+    record.injected = [spec for name, spec in injected_names.items() if name not in removing_names]
+
+    # Re-expose (removed packages may have contributed binaries).
+    unexpose_tool(record.exposed_bins, settings.bin_dir)
+    result = expose_tool(
+        record.pkg(),
+        backend,
+        env_dir,
+        settings.bin_dir,
+        record.expose_rules,
+        overwrite=True,
+    )
+    record.exposed_bins = result.linked
+
+    record.save_json(meta_file)
+    return record