ixt-cli 0.8.0__py3-none-any.whl

ixt/core/save.py

@@ -0,0 +1,237 @@
+"""Save/remove tool entries in the nearest ixt.toml (--save flag support)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ixt.config.toml import (
+    IxtConfig,
+    ToolSpec,
+    find_config_file,
+    load_config,
+    parse_config,
+    serialize_config,
+)
+from ixt.core.backend import BackendType
+from ixt.libs.constants import EXPOSE_MAIN
+
+
+def extract_version_from_spec(spec: str, backend_type: BackendType) -> str | None:
+    """Return the version constraint expressed in a user-provided install spec.
+
+    Preserves the user's intent: an explicit pin stays pinned, a range stays
+    a range, and a bare name returns ``None`` (no version). Normalizes bare
+    versions (e.g. ``1.2.3``) to ``==1.2.3`` so all backends share the
+    ``==<ver>`` convention used elsewhere in ixt.toml.
+    """
+    from ixt.core.backend import strip_protocol
+
+    _, clean = strip_protocol(spec)
+
+    if backend_type == BackendType.BINARY:
+        if "@" in clean and not clean.startswith("@"):
+            tag = clean.rsplit("@", 1)[1]
+            return f"=={tag}" if tag else None
+        return None
+
+    if backend_type == BackendType.NODE:
+        from ixt.backends.node import parse_npm_spec
+
+        _, version = parse_npm_spec(clean)
+        if not version:
+            return None
+        if version[0] in "^~<>=":
+            return version
+        return f"=={version}"
+
+    # Python / PEP 508
+    from ixt.libs.req_spec import parse_requirement
+
+    return parse_requirement(clean).version_constraint
+
+
+def tool_entry_key(_record_name: str, record_spec: str, backend_type: BackendType) -> str:
+    """Return the install-spec key to write in ``ixt.toml``."""
+    return _canonical_install_spec(record_spec, backend_type)
+
+
+def tool_install_spec(record_spec: str, backend_type: BackendType) -> str:
+    """Return the explicit install spec for a slotted ``ixt.toml`` entry."""
+    return _canonical_install_spec(record_spec, backend_type)
+
+
+def _canonical_install_spec(record_spec: str, backend_type: BackendType) -> str:
+    from ixt.core.backend import strip_protocol
+
+    _forced, clean_spec = strip_protocol(record_spec)
+    if backend_type == BackendType.BINARY:
+        from ixt.net.source import parse_spec, strip_version_suffix
+
+        repo_spec = parse_spec(strip_version_suffix(clean_spec))
+        if repo_spec is None:
+            return clean_spec
+        if repo_spec.platform == "github" and repo_spec.host == "github.com":
+            return f"@gh:{repo_spec.owner}/{repo_spec.repo}"
+        if repo_spec.host == "gitlab.com":
+            return f"@gl:{repo_spec.owner}/{repo_spec.repo}"
+        return f"@gl:{repo_spec.host}/{repo_spec.owner}/{repo_spec.repo}"
+
+    if backend_type == BackendType.NODE:
+        from ixt.backends.node import parse_npm_spec
+
+        pkg, _version = parse_npm_spec(clean_spec)
+        return f"@npm:{pkg}"
+
+    from ixt.libs.req_spec import parse_requirement
+
+    pkg = parse_requirement(clean_spec).name
+    return f"@pypi:{pkg}"
+
+
+def save_tool(
+    name: str,
+    *,
+    install: str | None = None,
+    version: str | None = None,
+    expose: list[str] | None = None,
+    inject: list[str] | None = None,
+    node_shim: bool | None = None,
+    runtime: str | None = None,
+    asset_pattern: str | None = None,
+    config_path: Path | None = None,
+) -> Path:
+    """Add or update a tool entry in ixt.toml. Returns the path written.
+
+    Preserves existing fields on update — only non-``None`` arguments override
+    the current entry, so callers can write partial updates without wiping
+    previously-stored inject/expose lists.
+    """
+    path, config = _load_or_create(config_path)
+
+    existing = config.tools.get(name)
+    resolved_expose = expose if expose is not None else (existing.expose if existing else None)
+    resolved_inject = inject if inject is not None else (existing.inject if existing else None)
+    resolved_version = version if version is not None else (existing.version if existing else None)
+    resolved_install = install if install is not None else (existing.install if existing else None)
+    resolved_node_shim = (
+        node_shim if node_shim is not None else (existing.node_shim if existing else None)
+    )
+    resolved_runtime = runtime if runtime is not None else (existing.runtime if existing else None)
+    resolved_asset_pattern = (
+        asset_pattern
+        if asset_pattern is not None
+        else (existing.asset_pattern if existing else None)
+    )
+
+    spec = ToolSpec(
+        name=name,
+        install=resolved_install,
+        version=resolved_version,
+        expose=resolved_expose if resolved_expose is not None else [EXPOSE_MAIN],
+        inject=resolved_inject if resolved_inject is not None else [],
+        node_shim=resolved_node_shim,
+        runtime=resolved_runtime,
+        asset_pattern=resolved_asset_pattern,
+    )
+    config.tools[name] = spec
+
+    path.write_text(serialize_config(config), encoding="utf-8")
+    return path
+
+
+def save_inject(
+    tool_name: str,
+    package: str,
+    *,
+    config_path: Path | None = None,
+) -> Path | None:
+    """Append *package* to ``tools.<tool_name>.inject`` in ixt.toml.
+
+    Returns the path written, or None if no ixt.toml exists. Does nothing if
+    the package is already listed.
+    """
+    path = config_path or find_config_file()
+    if path is None or not path.is_file():
+        return None
+
+    config = load_config(path)
+    spec = config.tools.get(tool_name)
+    if spec is None:
+        return None
+    if package in spec.inject:
+        return path
+
+    spec.inject = [*spec.inject, package]
+    path.write_text(serialize_config(config), encoding="utf-8")
+    return path
+
+
+def remove_inject(
+    tool_name: str,
+    package: str,
+    *,
+    config_path: Path | None = None,
+) -> Path | None:
+    """Remove *package* from ``tools.<tool_name>.inject`` in ixt.toml."""
+    path = config_path or find_config_file()
+    if path is None or not path.is_file():
+        return None
+
+    config = load_config(path)
+    spec = config.tools.get(tool_name)
+    if spec is None or package not in spec.inject:
+        return None
+
+    spec.inject = [p for p in spec.inject if p != package]
+    path.write_text(serialize_config(config), encoding="utf-8")
+    return path
+
+
+def remove_tool(
+    name: str,
+    *,
+    config_path: Path | None = None,
+) -> Path | None:
+    """Remove a tool entry from ixt.toml. Returns the path written, or None if not found."""
+    path = config_path or find_config_file()
+    if path is None:
+        return None
+
+    config = load_config(path)
+    key = _find_tool_key(config, name)
+    if key is None:
+        return None
+
+    del config.tools[key]
+    path.write_text(serialize_config(config), encoding="utf-8")
+    return path
+
+
+def _load_or_create(config_path: Path | None) -> tuple[Path, IxtConfig]:
+    """Load existing config or create a new empty one at cwd/ixt.toml."""
+    path = config_path or find_config_file()
+    if path is not None and path.is_file():
+        return path, load_config(path)
+
+    # Use explicit path or default to cwd/ixt.toml
+    path = path or (Path.cwd() / "ixt.toml")
+    return path, parse_config({}, source_path=path)
+
+
+def _find_tool_key(config: IxtConfig, selector: str) -> str | None:
+    if selector in config.tools:
+        return selector
+    try:
+        from ixt.config.settings import get_settings
+        from ixt.core.apply import _normalize_tool_entry
+    except Exception:
+        return None
+    settings = get_settings()
+    for key, spec in config.tools.items():
+        try:
+            tool_id, _normalized = _normalize_tool_entry(key, spec, settings)
+        except Exception:
+            continue
+        if tool_id == selector:
+            return key
+    return None

ixt/core/setup_completions.py

@@ -0,0 +1,11 @@
+"""Generate shell completion setup snippets for the ixt CLI."""
+
+from __future__ import annotations
+
+from ixt.cli.argparse_completion import render_completion
+from ixt.cli.parser import build_parser
+
+
+def generate_completion(shell: str) -> str:
+    """Return the shell script that enables ixt CLI completions."""
+    return render_completion(build_parser(), shell)

ixt/core/setup_path.py

@@ -0,0 +1,368 @@
+"""Configure PATH for the ixt bin directory across shells."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+from ixt.config.settings import Settings, get_settings
+from ixt.platform import is_windows
+
+_BEGIN = "# Added by ixt"
+_END = "# /Added by ixt"
+
+KNOWN_SHELLS = ("bash", "zsh", "fish", "pwsh")
+
+
+SetupPathStatus = Literal[
+    "ok",  # bin_dir already in current PATH env var
+    "ok_restart",  # already configured in shell file, restart needed
+    "added",  # new block written
+    "migrated",  # legacy block removed, new block written
+    "not_configured",  # check_only, would need to write
+    "blocked",  # symlink target or unknown shell, snippet returned
+]
+
+
+@dataclass
+class SetupPathResult:
+    """Outcome of a setup_path operation."""
+
+    status: SetupPathStatus
+    config_file: Path | None = None
+    message: str = ""
+    warning: str | None = None
+    snippet: str | None = None
+
+
+def _detect_shell() -> str:
+    """Return the user's login shell from ``$SHELL``.
+
+    One of: bash, zsh, fish, pwsh, unknown.
+    """
+    shell_path = os.environ.get("SHELL", "")
+    name = Path(shell_path).name if shell_path else ""
+    if name in KNOWN_SHELLS:
+        return name
+    if name in ("powershell", "powershell.exe"):
+        return "pwsh"
+    return "unknown"
+
+
+def _block(shell: str, bin_dir: Path) -> str:
+    """Build the multi-line PATH block for *shell* targeting *bin_dir*."""
+    if shell in ("bash", "zsh"):
+        return f'{_BEGIN}\nif [ -d "{bin_dir}" ]; then\n    PATH="{bin_dir}:$PATH"\nfi\n{_END}\n'
+    if shell == "fish":
+        return (
+            f'{_BEGIN}\nif test -d "{bin_dir}"\n    set -gx PATH "{bin_dir}" $PATH\nend\n{_END}\n'
+        )
+    if shell == "pwsh":
+        sep = ";" if is_windows() else ":"
+        return (
+            f"{_BEGIN}\n"
+            f'if (Test-Path -Path "{bin_dir}" -PathType Container) {{\n'
+            f'    $env:PATH = "{bin_dir}{sep}" + $env:PATH\n'
+            f"}}\n"
+            f"{_END}\n"
+        )
+    raise ValueError(f"unsupported shell: {shell}")
+
+
+def _target(shell: str) -> Path:
+    """Where the new block is written for *shell*."""
+    home = Path.home()
+    if shell == "zsh":
+        return home / ".zshenv"
+    if shell == "bash":
+        return home / ".bashrc"
+    if shell == "fish":
+        return home / ".config" / "fish" / "conf.d" / "ixt.fish"
+    if shell == "pwsh":
+        if is_windows():
+            return home / "Documents" / "PowerShell" / "profile.ps1"
+        return home / ".config" / "powershell" / "profile.ps1"
+    raise ValueError(f"unsupported shell: {shell}")
+
+
+def _legacy(shell: str) -> Path | None:
+    """Where ixt may have written before the new format. None = no migration."""
+    home = Path.home()
+    if shell == "zsh":
+        return home / ".zshrc"
+    if shell == "fish":
+        return home / ".config" / "fish" / "config.fish"
+    if shell == "bash":
+        # Legacy and target are the same file — migration is in-place.
+        return home / ".bashrc"
+    return None
+
+
+@dataclass
+class _BlockSpan:
+    kind: str  # "new" or "legacy"
+    line_start: int
+    line_end: int  # exclusive
+    lines: list[str] = field(default_factory=list)
+
+
+def _find_blocks(content: str) -> list[_BlockSpan]:
+    """Return ixt blocks (new + legacy) found in *content*."""
+    lines = content.splitlines(keepends=True)
+    blocks: list[_BlockSpan] = []
+    i = 0
+    while i < len(lines):
+        if lines[i].rstrip("\n") != _BEGIN:
+            i += 1
+            continue
+        end_idx = -1
+        for j in range(i + 1, min(i + 21, len(lines))):
+            if lines[j].rstrip("\n") == _END:
+                end_idx = j
+                break
+        if end_idx >= 0:
+            blocks.append(_BlockSpan("new", i, end_idx + 1, lines[i : end_idx + 1]))
+            i = end_idx + 1
+        else:
+            tail = i + 2 if i + 1 < len(lines) else i + 1
+            blocks.append(_BlockSpan("legacy", i, tail, lines[i:tail]))
+            i = tail
+    return blocks
+
+
+def _legacy_export_re(shell: str, bin_dir: Path) -> re.Pattern[str]:
+    """Match the legacy single-line export ixt previously wrote."""
+    bin_re = re.escape(str(bin_dir))
+    if shell == "fish":
+        return re.compile(r'^\s*set -gx PATH \$PATH "' + bin_re + r'"\s*$')
+    return re.compile(r'^\s*export PATH="\$PATH:' + bin_re + r'"\s*$')
+
+
+def _strip_comments(content: str) -> str:
+    return "\n".join(line for line in content.splitlines() if not line.lstrip().startswith("#"))
+
+
+def _heuristic_has_bin(content: str, bin_dir: Path) -> bool:
+    """Detect a non-comment line referencing *bin_dir* as a path component."""
+    bin_re = re.compile(r"(?<![\w./-])" + re.escape(str(bin_dir)) + r"(?![\w./-])")
+    return bool(bin_re.search(_strip_comments(content)))
+
+
+def _remove_block(path: Path, block: _BlockSpan) -> None:
+    """Strip *block* from *path* in-place."""
+    lines = path.read_text(encoding="utf-8").splitlines(keepends=True)
+    new = lines[: block.line_start] + lines[block.line_end :]
+    path.write_text("".join(new), encoding="utf-8")
+
+
+def _append_block(path: Path, body: str) -> None:
+    """Append *body* to *path*, separating from prior content with a blank line."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    existing = path.read_text(encoding="utf-8") if path.exists() else ""
+    with path.open("a", encoding="utf-8") as f:
+        if existing and not existing.endswith("\n"):
+            f.write("\n")
+        if existing:
+            f.write("\n")
+        f.write(body)
+
+
+def setup_path(
+    *,
+    check_only: bool = False,
+    settings: Settings | None = None,
+    shell: str | None = None,
+) -> SetupPathResult:
+    """Ensure the ixt bin directory is on PATH.
+
+    Detects the user's shell from ``$SHELL`` (overridable via *shell*) and
+    writes a multi-line block with start/end markers, a directory guard, and
+    a prepend so ixt shims shadow same-named binaries elsewhere on PATH.
+
+    Migrates legacy single-line ixt blocks when found:
+    strict match → auto-remove + write new block (status "migrated"),
+    divergent or heuristic → leave + warn (status "added", warning set).
+    """
+    settings = settings or get_settings()
+    bin_dir = settings.bin_dir
+    bin_str = str(bin_dir)
+
+    sep = ";" if is_windows() else ":"
+    path_dirs = [p for p in os.environ.get("PATH", "").split(sep) if p]
+    path_already_active = False
+    if is_windows():
+        bin_low = bin_str.lower()
+        path_already_active = any(p.lower() == bin_low for p in path_dirs)
+    elif bin_str in path_dirs:
+        path_already_active = True
+
+    detected = shell or _detect_shell()
+
+    if detected == "unknown":
+        if is_windows():
+            return _setup_path_windows(bin_dir, check_only=check_only)
+        if path_already_active:
+            return SetupPathResult("ok", message="Already in PATH")
+        return _blocked_unknown_shell(bin_dir)
+
+    if detected not in KNOWN_SHELLS:
+        if path_already_active:
+            return SetupPathResult("ok", message="Already in PATH")
+        return _blocked_unknown_shell(bin_dir, shell=detected)
+
+    result = _setup_path_file(detected, bin_dir, check_only=check_only)
+    if path_already_active and result.status == "ok_restart":
+        result.status = "ok"
+        result.message = "Already in PATH"
+    return result
+
+
+def _blocked_unknown_shell(bin_dir: Path, shell: str | None = None) -> SetupPathResult:
+    """Return a blocked result with a POSIX snippet to apply manually."""
+    msg = (
+        f"Unknown shell '{shell}'; PATH not configured automatically"
+        if shell
+        else "Could not detect shell; PATH not configured automatically"
+    )
+    return SetupPathResult("blocked", message=msg, snippet=_block("bash", bin_dir))
+
+
+def _setup_path_file(
+    shell: str,
+    bin_dir: Path,
+    *,
+    check_only: bool = False,
+) -> SetupPathResult:
+    """Write or update the PATH block in the per-shell config file."""
+    target = _target(shell)
+
+    if target.is_symlink():
+        return SetupPathResult(
+            "blocked",
+            config_file=target,
+            message=(
+                f"{target} is a symlink — likely managed externally "
+                f"(Nix, home-manager, chezmoi, ...). Add this snippet manually:"
+            ),
+            snippet=_block(shell, bin_dir),
+        )
+
+    target_content = target.read_text(encoding="utf-8") if target.exists() else ""
+    target_blocks = _find_blocks(target_content)
+
+    for blk in target_blocks:
+        if blk.kind == "new" and str(bin_dir) in "".join(blk.lines):
+            return SetupPathResult(
+                "ok_restart",
+                config_file=target,
+                message=f"Already in {target}, restart shell to activate",
+            )
+
+    target_lines = target_content.splitlines(keepends=True)
+    own_ranges = [(b.line_start, b.line_end) for b in target_blocks]
+    non_own = "".join(
+        line
+        for idx, line in enumerate(target_lines)
+        if not any(s <= idx < e for s, e in own_ranges)
+    )
+    if _heuristic_has_bin(non_own, bin_dir):
+        return SetupPathResult(
+            "ok_restart",
+            config_file=target,
+            message=f"{bin_dir} already exported from {target}",
+        )
+
+    legacy_path = _legacy(shell)
+
+    legacy_action: tuple[str, _BlockSpan] | None = None
+    legacy_warning: str | None = None
+
+    if legacy_path and legacy_path.exists():
+        same_file = legacy_path == target
+        legacy_blocks = (
+            target_blocks if same_file else _find_blocks(legacy_path.read_text(encoding="utf-8"))
+        )
+
+        export_re = _legacy_export_re(shell, bin_dir)
+        for blk in legacy_blocks:
+            if blk.kind != "legacy":
+                continue
+            export_line = blk.lines[1] if len(blk.lines) >= 2 else ""
+            if export_re.match(export_line.rstrip("\n")):
+                legacy_action = ("strict", blk)
+            else:
+                legacy_action = ("divergent", blk)
+                legacy_warning = (
+                    f"Found a previous '{_BEGIN}' block in {legacy_path} "
+                    f"(line {blk.line_start + 1}) that does not match what "
+                    f"ixt wrote. Leaving as-is — review and remove manually."
+                )
+            break
+
+        if legacy_action is None and not same_file:
+            legacy_content = legacy_path.read_text(encoding="utf-8")
+            if _heuristic_has_bin(legacy_content, bin_dir):
+                legacy_warning = (
+                    f"{legacy_path} already references {bin_dir} but ixt did "
+                    f"not write that block. Leaving as-is. ixt's block goes "
+                    f"to {target}."
+                )
+
+    if check_only:
+        return SetupPathResult(
+            "not_configured",
+            config_file=target,
+            message=f"Not configured; would add to {target}",
+            warning=legacy_warning,
+        )
+
+    migrated = False
+    if legacy_action and legacy_action[0] == "strict":
+        _, blk = legacy_action
+        if legacy_path is None:
+            raise RuntimeError("legacy block selected without a legacy path")
+        _remove_block(legacy_path, blk)
+        migrated = True
+
+    _append_block(target, _block(shell, bin_dir))
+
+    if migrated and legacy_path is not None and legacy_path != target:
+        message = f"Migrated from {legacy_path} to {target}, restart shell to activate"
+    elif migrated:
+        message = f"Migrated legacy block in {target} to new format, restart shell"
+    else:
+        message = f"Added to {target}, restart shell to activate"
+
+    return SetupPathResult(
+        "migrated" if migrated else "added",
+        config_file=target,
+        message=message,
+        warning=legacy_warning,
+    )
+
+
+def _setup_path_windows(bin_dir: Path, *, check_only: bool = False) -> SetupPathResult:
+    """Windows registry fallback when no POSIX shell is detected."""
+    from ixt.platform.win import add_to_user_path, get_user_path
+
+    bin_str = str(bin_dir)
+    bin_low = bin_str.lower()
+
+    user_path = get_user_path() or ""
+    if any(p.lower() == bin_low for p in user_path.split(";")):
+        return SetupPathResult(
+            "ok_restart",
+            message="Already in user registry PATH, restart shell to activate",
+        )
+
+    if check_only:
+        return SetupPathResult("not_configured", message="Not in PATH")
+
+    add_to_user_path(bin_str)
+    return SetupPathResult(
+        "added",
+        message="Added to user PATH in registry, restart shell to activate",
+    )