ixt-cli 0.8.0__py3-none-any.whl

ixt/cli/parser.py

@@ -0,0 +1,555 @@
+"""Argument parser for the ixt CLI — built on stdlib argparse."""
+
+from __future__ import annotations
+
+import argparse
+from importlib.metadata import version
+
+from ixt.cli.argparse_completion import SUPPORTED_COMPLETION_SHELLS, complete_with
+
+
+def _get_version() -> str:
+    try:
+        return version("ixt-cli")
+    except Exception:
+        return "unknown"
+
+
+def effective_verbosity(args: argparse.Namespace) -> int:
+    """Return global verbosity, including aliases accepted after a subcommand."""
+    return (getattr(args, "verbose", 0) or 0) + (getattr(args, "_verbose_after", 0) or 0)
+
+
+def normalize_verbosity(args: argparse.Namespace) -> int:
+    """Fold internal verbosity aliases into ``args.verbose`` and return it."""
+    verbosity = effective_verbosity(args)
+    args.verbose = verbosity
+    if hasattr(args, "_verbose_after"):
+        delattr(args, "_verbose_after")
+    return verbosity
+
+
+def _add_global_verbose_alias(parser: argparse.ArgumentParser) -> None:
+    """Accept global verbosity after selected subcommands.
+
+    argparse only accepts top-level options before the subcommand. Adding the
+    same destination on selected subparsers preserves the global ``args.verbose``
+    contract while allowing forms like ``ixt tool upgrade --all -v``. ``list -v`` is
+    intentionally excluded because it already means "show exact installed ids".
+    """
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="count",
+        default=0,
+        dest="_verbose_after",
+        help=argparse.SUPPRESS,
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build and return the top-level argument parser with all subcommands."""
+    parser = argparse.ArgumentParser(
+        prog="ixt",
+        description="Universal CLI tool isolator",
+    )
+    parser.add_argument(
+        "--version",
+        "-V",
+        action="version",
+        version=f"%(prog)s {_get_version()}",
+    )
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="count",
+        default=0,
+        help="Increase output verbosity (can be repeated)",
+    )
+
+    sub = parser.add_subparsers(dest="resource", metavar="COMMAND")
+
+    # -- tool ------------------------------------------------------------------
+    p_tool = sub.add_parser("tool", help="Manage installed tools")
+    tool_sub = p_tool.add_subparsers(dest="tool_action", metavar="ACTION", required=True)
+
+    # -- tool add --------------------------------------------------------------
+    p_add = tool_sub.add_parser(
+        "add",
+        help="Add a tool to ixt.toml without installing it",
+    )
+    p_add.set_defaults(command="add")
+    p_add.add_argument(
+        "package",
+        help="Package spec to persist in ixt.toml (e.g. ruff, @scope/pkg, owner/repo)",
+    )
+    p_add.add_argument(
+        "--bare",
+        action="store_true",
+        help="Persist the tool without exposing any binary",
+    )
+    p_add.add_argument(
+        "--slot",
+        default=None,
+        metavar="SLOT",
+        help="Persist as a side-by-side slot (entry key)",
+    )
+    p_add.add_argument(
+        "--runtime",
+        choices=["bun", "bun-strict", "node"],
+        default=None,
+        help=(
+            "Runtime for npm packages. 'bun-strict' persists node_shim=false; "
+            "'node' persists runtime='node'. Ignored for python/binary backends."
+        ),
+    )
+    p_add.add_argument(
+        "--asset-pattern",
+        dest="asset_pattern",
+        default=None,
+        metavar="PATTERN",
+        help=(
+            "Persist a forced asset selection pattern (binary backend only). "
+            "Supports {version}, {tag}, {os}, {arch} placeholders."
+        ),
+    )
+
+    # -- tool install ----------------------------------------------------------
+    p_install = tool_sub.add_parser(
+        "install",
+        help="Install a tool in an isolated environment",
+        epilog=(
+            "Post-install configuration goes through 'ixt tool config <target> <action>' "
+            "(expose / inject / uninject)."
+        ),
+    )
+    p_install.set_defaults(command="install")
+    p_install.add_argument(
+        "package",
+        nargs="?",
+        help="Package spec (e.g. ruff, ruff>=0.5). Omit when using --from.",
+    )
+    complete_with(
+        p_install.add_argument(
+            "--from",
+            dest="from_path",
+            default=None,
+            metavar="PATH",
+            help=(
+                "Install from a local directory (auto-detected backend). "
+                "Mutually exclusive with the positional package spec."
+            ),
+        ),
+        "dir",
+    )
+    p_install.add_argument(
+        "--bare",
+        action="store_true",
+        help="Install without exposing any binary (configure later with ixt tool config)",
+    )
+    p_install.add_argument(
+        "--reinstall",
+        action="store_true",
+        help="Reinstall if already installed",
+    )
+    p_install.add_argument(
+        "--slot",
+        default=None,
+        metavar="SLOT",
+        help="Install into a side-by-side slot (id prefix)",
+    )
+    p_install.add_argument(
+        "--runtime",
+        choices=["bun", "bun-strict", "node"],
+        default="bun",
+        help=(
+            "Runtime for npm packages (default: bun). "
+            "'bun' rewrites '#!/usr/bin/env node' shebangs to bun. "
+            "'bun-strict' runs bun without shebang rewrite (host must have node). "
+            "'node' uses node natively. Ignored for python/binary backends."
+        ),
+    )
+    complete_with(
+        p_install.add_argument(
+            "--setup-file",
+            "-s",
+            dest="setup",
+            default=None,
+            metavar="PATH",
+            help="Use a local ixt.setup.toml (overrides remote fetch)",
+        ),
+        "file",
+    )
+    p_install.add_argument(
+        "--asset-pattern",
+        dest="asset_pattern",
+        default=None,
+        metavar="PATTERN",
+        help=(
+            "Force the asset selection pattern (binary backend only). "
+            "Supports {version}, {tag}, {os}, {arch} placeholders. "
+            "Persisted in the tool's ixt.json; survives upgrades, "
+            "lost on uninstall."
+        ),
+    )
+    p_install.add_argument(
+        "--save",
+        action="store_true",
+        help="Add the tool to ixt.toml",
+    )
+    p_install.add_argument(
+        "--dry-run",
+        action="store_true",
+        dest="dry_run",
+        help="Show what would be installed without touching disk or network",
+    )
+
+    # -- tool uninstall --------------------------------------------------------
+    p_uninstall = tool_sub.add_parser("uninstall", help="Remove an installed tool")
+    p_uninstall.set_defaults(command="uninstall")
+    p_uninstall.add_argument(
+        "target",
+        nargs="?",
+        help="Tool spec or @id:<installed-id> to remove",
+    )
+    p_uninstall.add_argument(
+        "--all",
+        action="store_true",
+        dest="uninstall_all",
+        help="Remove all installed tools",
+    )
+    p_uninstall.add_argument(
+        "--save",
+        action="store_true",
+        help="Remove the tool from ixt.toml",
+    )
+    p_uninstall.add_argument(
+        "--yes",
+        "-y",
+        dest="yes",
+        action="store_true",
+        help="Skip confirmation prompt for --all",
+    )
+    p_uninstall.add_argument(
+        "--dry-run",
+        action="store_true",
+        dest="dry_run",
+        help="Show what would be removed without touching disk",
+    )
+
+    # -- tool upgrade ----------------------------------------------------------
+    p_upgrade = tool_sub.add_parser("upgrade", help="Upgrade a tool to the latest version")
+    p_upgrade.set_defaults(command="upgrade")
+    _add_global_verbose_alias(p_upgrade)
+    p_upgrade.add_argument(
+        "tool",
+        nargs="?",
+        help="Tool spec or @id:<installed-id> (omit for --all)",
+    )
+    p_upgrade.add_argument(
+        "--all",
+        action="store_true",
+        dest="upgrade_all",
+        help="Upgrade all installed tools",
+    )
+    p_upgrade.add_argument(
+        "--dry-run",
+        action="store_true",
+        dest="dry_run",
+        help="Resolve new versions and show old -> new without installing",
+    )
+    p_upgrade.add_argument(
+        "--no-cache",
+        action="store_true",
+        dest="no_cache",
+        help="Ignore the resolve cache; always check upstream for the latest version",
+    )
+
+    # -- tool list -------------------------------------------------------------
+    p_list = tool_sub.add_parser("list", help="List all installed tools")
+    p_list.set_defaults(command="list")
+    p_list.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        dest="verbose_list",
+        help="Show exact installed ids",
+    )
+
+    # -- tool info -------------------------------------------------------------
+    p_info = tool_sub.add_parser("info", help="Show details about an installed tool")
+    p_info.set_defaults(command="info")
+    p_info.add_argument("tool", help="Tool spec or @id:<installed-id>")
+
+    # -- tool config -----------------------------------------------------------
+    p_config = tool_sub.add_parser(
+        "config",
+        help="Change an installed tool's settings (expose / inject / env / fs / …)",
+    )
+    p_config.set_defaults(command="config")
+    p_config.add_argument(
+        "tool",
+        help=(
+            "Tool spec, @id:<installed-id>, or '__all__' to apply the action "
+            "to every installed tool (expose only)"
+        ),
+    )
+    config_action = p_config.add_subparsers(dest="config_action", metavar="ACTION", required=True)
+
+    p_conf_expose = config_action.add_parser(
+        "expose", help="Change which binaries are exposed to PATH"
+    )
+    p_conf_expose.add_argument(
+        "rules", nargs="+", metavar="RULE", help="Exposure rules (e.g. __all__, name:alias)"
+    )
+
+    p_conf_inject = config_action.add_parser(
+        "inject", help="Add a package to the tool's environment"
+    )
+    p_conf_inject.add_argument("package", help="Package spec to inject")
+
+    p_conf_uninject = config_action.add_parser(
+        "uninject", help="Remove an injected package from the tool's environment"
+    )
+    p_conf_uninject.add_argument("package", help="Package name to remove")
+
+    p_conf_env = config_action.add_parser(
+        "env", help="Manage the environment variable policy for a tool"
+    )
+    env_sub = p_conf_env.add_subparsers(dest="env_action", metavar="ACTION")
+
+    p_env_base = env_sub.add_parser("base", help="Set the base policy (all / none / os-common)")
+    p_env_base.add_argument("value", choices=["all", "none", "os-common"])
+
+    p_env_allow = env_sub.add_parser("allow", help="Add glob patterns to the allow list")
+    p_env_allow.add_argument("patterns", nargs="+", metavar="PATTERN")
+
+    p_env_deny = env_sub.add_parser("deny", help="Add glob patterns to the deny list (always wins)")
+    p_env_deny.add_argument("patterns", nargs="+", metavar="PATTERN")
+    p_env_deny.add_argument(
+        "--except",
+        dest="exceptions",
+        nargs="+",
+        metavar="PATTERN",
+        default=[],
+        help="Variables excluded from this deny rule",
+    )
+
+    env_sub.add_parser("list", help="Show the current env policy (default when no action given)")
+    env_sub.add_parser("reset", help="Clear all env policy rules (restores symlink)")
+
+    p_conf_fs = config_action.add_parser(
+        "fs", help="Manage the filesystem policy for a tool (requires bwrap)"
+    )
+    fs_sub = p_conf_fs.add_subparsers(dest="fs_action", metavar="ACTION")
+
+    p_fs_base = fs_sub.add_parser(
+        "base", help="Set the fs base policy (all / app-common / app-minimal / none)"
+    )
+    p_fs_base.add_argument("value", choices=["all", "app-common", "app-minimal", "none"])
+
+    p_fs_ro = fs_sub.add_parser("ro", help="Add read-only bind paths")
+    complete_with(p_fs_ro.add_argument("paths", nargs="+", metavar="PATH"), "file")
+
+    p_fs_rw = fs_sub.add_parser("rw", help="Add read-write bind paths")
+    complete_with(p_fs_rw.add_argument("paths", nargs="+", metavar="PATH"), "file")
+
+    p_fs_scratch = fs_sub.add_parser(
+        "scratch", help="Add scratch paths (empty rw tmpfs, discarded on exit)"
+    )
+    complete_with(p_fs_scratch.add_argument("paths", nargs="+", metavar="PATH"), "file")
+
+    fs_sub.add_parser("list", help="Show the current fs policy (default when no action given)")
+    fs_sub.add_parser("reset", help="Clear all fs policy rules (restores direct exec)")
+
+    # -- tool apply ------------------------------------------------------------
+    p_apply = tool_sub.add_parser("apply", help="Install/sync tools from ixt.toml")
+    p_apply.set_defaults(command="apply")
+    complete_with(
+        p_apply.add_argument(
+            "config_file",
+            nargs="?",
+            default=None,
+            help="Path to ixt.toml (default: auto-discover)",
+        ),
+        "file",
+    )
+    p_apply.add_argument(
+        "--remove",
+        action="store_true",
+        help="Remove tools not listed in ixt.toml",
+    )
+    p_apply.add_argument(
+        "--yes",
+        "-y",
+        dest="yes",
+        action="store_true",
+        help="Skip confirmation prompts (e.g. --remove)",
+    )
+    p_apply.add_argument(
+        "--dry-run",
+        action="store_true",
+        dest="dry_run",
+        help="Show what would change without installing, reinstalling, or removing",
+    )
+
+    # -- tool export -----------------------------------------------------------
+    p_export_tools = tool_sub.add_parser(
+        "export",
+        help="Export installed tools as ixt.toml (stdout), preserving install intent",
+    )
+    p_export_tools.set_defaults(command="export", export_action="tools")
+    p_export_tools.add_argument(
+        "names",
+        nargs="*",
+        help="Tool spec or @id:<installed-id> selectors to export (default: all installed tools)",
+    )
+
+    # -- asset-index export ----------------------------------------------------
+    p_asset_index = sub.add_parser("asset-index", help="Manage asset_index.json metadata")
+    asset_index_sub = p_asset_index.add_subparsers(
+        dest="asset_index_action",
+        metavar="ACTION",
+        required=True,
+    )
+    p_export_asset_index = asset_index_sub.add_parser(
+        "export",
+        help="Export portable binary-resolution metadata as asset_index.json",
+    )
+    p_export_asset_index.set_defaults(command="export", export_action="asset-index")
+    complete_with(
+        p_export_asset_index.add_argument(
+            "--from-registry",
+            dest="from_registry",
+            default=None,
+            metavar="PATH",
+            help="Generate asset-index patterns from a registry.toml file",
+        ),
+        "file",
+    )
+    p_export_asset_index.add_argument(
+        "--all-platforms",
+        action="store_true",
+        help="Generate the initial linux/macos x86_64/aarch64 platform matrix",
+    )
+
+    # -- cache -----------------------------------------------------------------
+    p_cache = sub.add_parser("cache", help="Inspect and prune ixt caches")
+    p_cache.set_defaults(command="cache")
+    cache_sub = p_cache.add_subparsers(dest="cache_action", metavar="ACTION")
+
+    cache_sub.add_parser("info", help="Show cache paths and sizes")
+
+    p_cache_prune = cache_sub.add_parser(
+        "prune",
+        help="Prune old indexed download artifacts",
+    )
+    p_cache_prune.add_argument(
+        "--keep",
+        type=int,
+        default=2,
+        metavar="N",
+        help="Keep the newest N indexed download artifacts per repository (default: 2)",
+    )
+
+    p_cache_clear = cache_sub.add_parser("clear", help="Clear a cache subtree")
+    p_cache_clear.add_argument(
+        "target",
+        choices=["downloads", "metadata", "tmp", "all"],
+        help="'downloads' (network artifacts), 'metadata' (resolutions + indexes), 'tmp', or 'all'",
+    )
+
+    # -- registry --------------------------------------------------------------
+    p_registry = sub.add_parser("registry", help="Inspect registry entries")
+    p_registry.set_defaults(command="registry")
+    registry_sub = p_registry.add_subparsers(dest="registry_action", metavar="ACTION")
+
+    registry_sub.add_parser("list", help="List registry short names and specs")
+
+    # -- runtime ---------------------------------------------------------------
+    p_runtimes = sub.add_parser("runtime", help="Inspect, prune, and upgrade ixt-managed runtimes")
+    p_runtimes.set_defaults(command="runtime")
+    runtimes_sub = p_runtimes.add_subparsers(dest="runtimes_action", metavar="ACTION")
+
+    runtimes_sub.add_parser("info", help="Show ixt-managed runtime state")
+
+    p_runtimes_prune = runtimes_sub.add_parser(
+        "prune",
+        help="Remove unused ixt-managed runtimes",
+    )
+    p_runtimes_prune.add_argument(
+        "--all",
+        action="store_true",
+        help="Remove all ixt-managed runtimes, even when currently used",
+    )
+
+    p_runtimes_upgrade = runtimes_sub.add_parser(
+        "upgrade",
+        help="Install or replace an ixt-managed runtime",
+    )
+    p_runtimes_upgrade.add_argument(
+        "name",
+        choices=["uv", "bun", "all"],
+        help="Runtime to upgrade",
+    )
+
+    # -- doctor ----------------------------------------------------------------
+    p_doctor = sub.add_parser("doctor", help="Check ixt health and environment")
+    p_doctor.set_defaults(command="doctor")
+    p_doctor.add_argument(
+        "--no-network",
+        action="store_true",
+        help="Skip GitHub, PyPI, npm, and latest-version network probes",
+    )
+
+    # -- environment -----------------------------------------------------------
+    p_environment = sub.add_parser("environment", help="Show ixt configuration and paths")
+    p_environment.set_defaults(command="environment")
+    p_environment.add_argument(
+        "--sizes",
+        action="store_true",
+        help="Also show sizes for config, installed tools, runtimes, and caches",
+    )
+
+    # -- tool shell ------------------------------------------------------------
+    p_shell = tool_sub.add_parser("shell", help="Open a subshell in a tool's environment directory")
+    p_shell.set_defaults(command="shell")
+    p_shell.add_argument("tool", help="Tool spec or @id:<installed-id>")
+
+    # -- tool where ------------------------------------------------------------
+    p_where = tool_sub.add_parser("where", help="Print a tool's environment directory")
+    p_where.set_defaults(command="where")
+    p_where.add_argument("tool", help="Tool spec or @id:<installed-id>")
+
+    # -- setup -----------------------------------------------------------------
+    p_setup = sub.add_parser("setup", help="Configure shell integration (PATH, ...)")
+    p_setup.set_defaults(command="setup")
+    setup_sub = p_setup.add_subparsers(dest="setup_command", metavar="SUBCOMMAND")
+
+    p_setup_path = setup_sub.add_parser("path", help="Add ixt bin directory to PATH")
+    p_setup_path.add_argument(
+        "--check",
+        action="store_true",
+        help="Only check, don't modify anything",
+    )
+    from ixt.core.setup_path import KNOWN_SHELLS
+
+    p_setup_path.add_argument(
+        "--shell",
+        choices=list(KNOWN_SHELLS),
+        default=None,
+        help="Override shell detection (default: $SHELL)",
+    )
+
+    p_setup_completions = setup_sub.add_parser(
+        "completions",
+        help="Print shell completion script",
+    )
+    p_setup_completions.add_argument(
+        "--shell",
+        choices=list(SUPPORTED_COMPLETION_SHELLS),
+        required=True,
+        help="Shell to generate completions for",
+    )
+
+    return parser

ixt/cli/render.py

@@ -0,0 +1,85 @@
+"""Small CLI rendering helpers shared across command modules."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ixt.config.models import ToolRecord
+from ixt.libs.style import cyan, dim
+from ixt.net.source import parse_spec
+
+
+def id_suffix(tool_id: str) -> str:
+    """Render the compact installed-id suffix used in command summaries."""
+    return dim(f"(id: {tool_id})")
+
+
+def format_source_tag(label: str | None) -> str:
+    """Render a compact backend/source tag, or an empty suffix."""
+    return dim(f"[{label}]") if label else ""
+
+
+def source_label_for_record(record: ToolRecord) -> str:
+    """Return the user-facing package source for an installed record."""
+    if record.source == "local":
+        return "local"
+    if record.backend == "python":
+        return "pypi"
+    if record.backend == "node":
+        return "npm"
+    if record.backend == "binary":
+        repo_spec = parse_spec(record.spec)
+        return repo_spec.platform if repo_spec is not None else "binary"
+    return record.backend
+
+
+def source_label_for_spec(
+    spec: str,
+    *,
+    backend_hint: str | None = None,
+    tool_id: str | None = None,
+) -> str | None:
+    """Best-effort source label for an action that has not produced metadata yet."""
+    if backend_hint in {"pypi", "python"}:
+        return "pypi"
+    if backend_hint in {"npm", "node"}:
+        return "npm"
+
+    repo_spec = parse_spec(spec)
+    if repo_spec is not None:
+        return repo_spec.platform
+
+    if backend_hint in {"github", "binary"}:
+        return "github"
+
+    if tool_id:
+        if tool_id.endswith(".pypi"):
+            return "pypi"
+        if tool_id.endswith(".npm"):
+            return "npm"
+        if tool_id.endswith(".github"):
+            return "github"
+        if tool_id.endswith(".gitlab"):
+            return "gitlab"
+
+    return None
+
+
+def format_exposed_bin(exposed_name: str, source_path: str) -> str:
+    """Render one exposed shim, showing aliases as ``alias -> source``."""
+    source_basename = Path(source_path).name
+    if source_basename == exposed_name:
+        return cyan(exposed_name)
+    return f"{cyan(exposed_name)} {dim('->')} {cyan(source_basename)}"
+
+
+def format_exposed_bins(exposed_bins: dict[str, str]) -> str:
+    """Render exposed PATH shim names, or ``none``.
+
+    The source binary path is intentionally hidden here. ``exposed:`` answers
+    "what command names did ixt add to PATH?", not "which file do they point to?"
+    Detailed source paths are available through ``ixt tool info``.
+    """
+    if not exposed_bins:
+        return dim("none")
+    return ", ".join(cyan(name) for name in sorted(exposed_bins))

ixt/config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration helpers and data models."""
+
+from ixt.config.models import ToolRecord
+
+__all__ = ["ToolRecord"]