shellscripts 0.23.1__py3-none-any.whl

shell_scripts/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.23.1"
+
+from .core import main  # noqa: F401
+
+__all__ = ["__version__", "main"]

shell_scripts/__main__.py

@@ -0,0 +1,5 @@
+from .core import main
+import sys
+
+if __name__ == "__main__":
+    sys.exit(main())

shell_scripts/commands/__init__.py

@@ -0,0 +1,81 @@
+"""@brief Command registry and lazy command module resolver.
+
+@details Defines a static command-to-module map consumed by the CLI dispatcher.
+Dictionary lookup enforces deterministic command availability; missing keys
+resolve to `None` to drive unknown-command error handling in the caller.
+@satisfies PRJ-001, PRJ-002, PRJ-003, DES-001, DES-008, REQ-057, REQ-058
+"""
+
+import importlib
+from types import ModuleType
+
+## @var _COMMAND_MODULES
+#  @brief Static map from CLI command names to importable module paths.
+#  @details Enables lazy command loading and deterministic command exposure.
+#  Removing an entry removes command discoverability and dispatch reachability.
+#  @satisfies PRJ-003, DES-001
+_COMMAND_MODULES = {
+    "ai-install": "shell_scripts.commands.ai_install",
+    "clean": "shell_scripts.commands.clean",
+    "claude": "shell_scripts.commands.claude",
+    "codex": "shell_scripts.commands.codex",
+    "copilot": "shell_scripts.commands.copilot",
+    "gemini": "shell_scripts.commands.gemini",
+    "kiro": "shell_scripts.commands.kiro",
+    "opencode": "shell_scripts.commands.opencode",
+    "pi": "shell_scripts.commands.pi",
+    "dicom2jpg": "shell_scripts.commands.dicom2jpg",
+    "dicomviewer": "shell_scripts.commands.dicomviewer",
+    "diff": "shell_scripts.commands.diff_cmd",
+    "edit": "shell_scripts.commands.edit_cmd",
+    "view": "shell_scripts.commands.view_cmd",
+    "doxygen": "shell_scripts.commands.doxygen_cmd",
+    "pdf-crop": "shell_scripts.commands.pdf_crop",
+    "pdf-merge": "shell_scripts.commands.pdf_merge",
+    "pdf-split-by-format": "shell_scripts.commands.pdf_split_by_format",
+    "pdf-split-by-toc": "shell_scripts.commands.pdf_split_by_toc",
+    "pdf-tiler-090": "shell_scripts.commands.pdf_tiler_090",
+    "pdf-tiler-100": "shell_scripts.commands.pdf_tiler_100",
+    "pdf-toc-clean": "shell_scripts.commands.pdf_toc_clean",
+    "req": "shell_scripts.commands.req_cmd",
+    "tests": "shell_scripts.commands.tests_cmd",
+    "ubuntu-dark-theme": "shell_scripts.commands.ubuntu_dark_theme",
+    "venv": "shell_scripts.commands.venv_cmd",
+    "video2h264": "shell_scripts.commands.video2h264",
+    "video2h265": "shell_scripts.commands.video2h265",
+    "vscode": "shell_scripts.commands.vscode_cmd",
+    "vsinsider": "shell_scripts.commands.vsinsider_cmd",
+}
+
+
+def get_command(name: str) -> ModuleType | None:
+    """@brief Resolve one CLI command token to its command module.
+
+    @details Performs O(1) dictionary lookup on `_COMMAND_MODULES`; returns
+    `None` for unknown tokens; imports target module lazily only on hit.
+    @param name {str} CLI command token.
+    @return {ModuleType|None} Imported command module for known token; `None` otherwise.
+    @throws {ImportError} If module path exists in map but import fails.
+    @satisfies PRJ-001, DES-001, DES-008, REQ-057, REQ-058
+    """
+    module_path = _COMMAND_MODULES.get(name)
+    if module_path is None:
+        return None
+    return importlib.import_module(module_path)
+
+
+def get_all_commands() -> dict[str, str]:
+    """@brief Build command-description index for help rendering.
+
+    @details Iterates sorted command keys for stable output ordering; imports
+    each module via `get_command`; extracts `DESCRIPTION` or empty string.
+    Time complexity O(N log N) for N commands due to key sorting.
+    @return {dict[str, str]} Mapping `command_name -> description`.
+    @throws {ImportError} If any mapped command module import fails.
+    @satisfies PRJ-002, DES-001, DES-008, REQ-057, REQ-058
+    """
+    result: dict[str, str] = {}
+    for name in sorted(_COMMAND_MODULES):
+        mod = get_command(name)
+        result[name] = getattr(mod, "DESCRIPTION", "")
+    return result

shell_scripts/commands/_dc_common.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""@brief Shared MIME-based dispatcher primitives for diff/edit/view commands.
+
+@details Provides extension and MIME classification plus external executable
+resolution and blocking subprocess invocation for generic file tool wrappers.
+@satisfies DES-007, REQ-024, REQ-055, REQ-056, REQ-064
+"""
+
+import os
+import subprocess
+
+from shell_scripts.utils import is_executable_command, print_error
+
+CODE_EXTENSIONS = {
+    "c", "h", "cc", "cpp", "cxx", "hpp", "hh", "hxx", "rs", "go",
+    "java", "kt", "kts", "cs", "swift", "php", "rb", "py", "js",
+    "mjs", "cjs", "ts", "tsx", "jsx", "vue", "svelte", "sh", "bash",
+    "zsh", "lua", "pl", "pm", "sql", "yaml", "yml", "toml", "ini",
+    "cfg", "conf", "json", "xml", "gradle", "mk", "cmake", "dockerfile",
+}
+
+MARKDOWN_EXTENSIONS = {"md", "markdown", "mdown", "mkd"}
+HTML_EXTENSIONS = {"html", "htm", "xhtml"}
+IMAGE_EXTENSIONS = {"png", "jpg", "jpeg", "gif", "webp", "bmp", "tif", "tiff", "svg"}
+
+
+def get_extension(filepath):
+    name = os.path.basename(filepath)
+    if "." not in name:
+        return ""
+    return name.rsplit(".", 1)[1].lower()
+
+
+def detect_mime(filepath):
+    """@brief Detect file MIME type with external tools.
+
+    @details Probes MIME by trying `mimetype` then `file --mime-type`, using
+    executable availability checks before subprocess invocation.
+    @param filepath {str} Target file path.
+    @return {str} MIME type string or empty string on detection failure.
+    @satisfies REQ-024, REQ-056
+    """
+
+    if not os.path.exists(filepath):
+        return ""
+    for cmd in ["mimetype", "file"]:
+        if is_executable_command(cmd):
+            try:
+                result = subprocess.run(
+                    [cmd if cmd == "mimetype" else "file", "-b", "--mime-type", filepath]
+                    if cmd == "file" else ["mimetype", "-b", filepath],
+                    capture_output=True, text=True, timeout=5
+                )
+                if result.returncode == 0:
+                    return result.stdout.strip()
+            except (subprocess.TimeoutExpired, FileNotFoundError):
+                pass
+    return ""
+
+
+def categorize(filepath):
+    ext = get_extension(filepath)
+    mime = detect_mime(filepath)
+
+    if mime.startswith("image/"):
+        return "image"
+    if mime == "application/pdf":
+        return "pdf"
+    if mime == "text/html":
+        return "html"
+
+    if (mime.startswith("text/") or mime in (
+        "application/json", "application/xml", "application/x-shellscript", ""
+    )):
+        if ext in MARKDOWN_EXTENSIONS:
+            return "markdown"
+        if ext in HTML_EXTENSIONS:
+            return "html"
+        if ext in CODE_EXTENSIONS:
+            return "code"
+        return "text"
+
+    if not os.path.exists(filepath):
+        if ext in MARKDOWN_EXTENSIONS:
+            return "markdown"
+        if ext in HTML_EXTENSIONS:
+            return "html"
+        if ext == "pdf":
+            return "pdf"
+        if ext in IMAGE_EXTENSIONS:
+            return "image"
+        if ext in CODE_EXTENSIONS:
+            return "code"
+        return "text"
+
+    return "other"
+
+
+def pick_cmd(primary, fallback):
+    """@brief Select primary command when executable, else fallback.
+
+    @details Uses shared executable-check helper on first token of primary
+    command vector.
+    @param primary {list[str]} Preferred command vector.
+    @param fallback {list[str]} Fallback command vector.
+    @return {list[str]} Selected executable command vector.
+    @satisfies REQ-024, REQ-055
+    """
+
+    if primary and is_executable_command(primary[0]):
+        return primary
+    return fallback
+
+
+def dispatch(category_cmds, fallback_cmd, filepath, extra_args):
+    """@brief Dispatch diff/edit/view command by detected file category.
+
+    @details Resolves category-specific command vector, validates executable
+    availability, and executes selected command via blocking subprocess run.
+    @param category_cmds {dict[str, list[str]]} Category-to-command mapping.
+    @param fallback_cmd {list[str]} Fallback command vector.
+    @param filepath {str} Target file path.
+    @param extra_args {list[str]} Additional arguments forwarded to executable.
+    @return {int} `1` when executable is unavailable; child return code otherwise.
+    @satisfies REQ-024, REQ-055, REQ-056, REQ-064
+    """
+
+    category = categorize(filepath)
+    cmd_list = category_cmds.get(category, fallback_cmd)
+    cmd = pick_cmd(cmd_list, fallback_cmd)
+
+    if not is_executable_command(cmd[0]):
+        print_error(f"Command not executable: {cmd[0]}")
+        return 1
+
+    full_cmd = cmd + [filepath] + extra_args
+    result = subprocess.run(full_cmd)
+    return result.returncode

shell_scripts/commands/ai_install.py

@@ -0,0 +1,453 @@
+#!/usr/bin/env python3
+"""@brief AI CLI installers dispatcher with OS-aware package resolution.
+
+@details Provides selector-based installation flows for npm-distributed tools
+and direct-download installers. Npm command prefix and installer payload
+sources are resolved from detected runtime OS. Kiro package resolution is
+manifest-driven on Linux and explicitly unsupported on Windows/macOS. pi.dev
+installation always runs npm global installation first and then installs the
+configured pi package list without any `--extra` selector gate.
+@satisfies PRJ-003, DES-013, REQ-006, REQ-007, REQ-008, REQ-009, REQ-010, REQ-047, REQ-056, REQ-067, REQ-072, REQ-073, REQ-074
+"""
+
+import json
+import os
+import platform
+import subprocess
+import shutil
+import zipfile
+import tempfile
+from pathlib import Path
+
+from shell_scripts.utils import (
+    get_runtime_os,
+    print_info,
+    print_error,
+    print_success,
+    require_commands,
+)
+
+## @var PROGRAM
+#  @brief Base CLI program name used in help output.
+#  @details Constant identifier for usage-line rendering in command help.
+PROGRAM = "shellscripts"
+
+## @var DESCRIPTION
+#  @brief One-line command description for dispatcher help surfaces.
+#  @details Exposed by command registry introspection (`get_all_commands`).
+DESCRIPTION = "Install AI CLI tools (Codex, Copilot, Gemini, OpenCode, pi.dev, Claude, Kiro)."
+
+## @var TOOLS
+#  @brief Static npm-installer registry for supported AI CLIs.
+#  @details Maps selector tokens to user-facing installer names and exact npm
+#  command vectors consumed by `_install_npm_tool(...)`.
+TOOLS = {
+    "codex": {
+        "name": "OpenAI Codex CLI",
+        "install": ["npm", "install", "-g", "@openai/codex"],
+    },
+    "copilot": {
+        "name": "GitHub Copilot CLI",
+        "install": ["npm", "install", "-g", "@github/copilot"],
+    },
+    "gemini": {
+        "name": "Google Gemini CLI",
+        "install": ["npm", "install", "-g", "@google/gemini-cli"],
+    },
+    "opencode": {
+        "name": "OpenCode CLI",
+        "install": ["npm", "install", "-g", "opencode-ai"],
+    },
+    "pi": {
+        "name": "pi.dev CLI",
+        "install": ["npm", "install", "-g", "@mariozechner/pi-coding-agent"],
+    },
+}
+
+## @var PI_PACKAGES
+#  @brief Post-install pi package registry executed after pi.dev CLI install.
+#  @details Ordered tuple of package specifiers passed to `pi install` after
+#  successful npm-based pi.dev CLI installation.
+PI_PACKAGES = ("git:github.com/ferologics/pi-notify",)
+
+CLAUDE_BUCKET = (
+    "https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819"
+    "/claude-code-releases"
+)
+CLAUDE_ARTIFACT_CANDIDATES = {
+    "linux": ("linux-x64/claude",),
+    "windows": ("windows-x64/claude.exe", "win32-x64/claude.exe"),
+    "darwin": ("darwin-arm64/claude", "darwin-x64/claude"),
+}
+KIRO_CHANNEL_BASE_URL = "https://prod.download.cli.kiro.dev/stable"
+KIRO_MANIFEST_URL = f"{KIRO_CHANNEL_BASE_URL}/latest/manifest.json"
+KIRO_LINUX_VARIANT = "headless"
+
+
+def print_help(version: str) -> None:
+    """@brief Render command help for `ai-install`.
+
+    @details Prints supported selectors and execution contract for installer
+    dispatch. The selector surface excludes any `--extra` compatibility flag.
+    @param version {str} CLI version string appended in usage output.
+    @return {None} Writes help text to stdout.
+    @satisfies DES-008
+    """
+
+    print(f"Usage: {PROGRAM} ai-install [options] ({version})")
+    print()
+    print("ai-install options:")
+    print("  --all        - Install all AI CLI tools (default).")
+    print("  --codex      - Install OpenAI Codex CLI only.")
+    print("  --copilot    - Install GitHub Copilot CLI only.")
+    print("  --gemini     - Install Google Gemini CLI only.")
+    print("  --opencode   - Install OpenCode CLI only.")
+    print("  --pi         - Install pi.dev CLI only.")
+    print("  --claude     - Install Claude CLI only.")
+    print("  --kiro       - Install Kiro CLI only.")
+    print("  --help       - Show this help message.")
+
+
+def _install_npm_tool(tool_key):
+    """@brief Execute npm-based installer command for selected tool.
+
+    @details Resolves base npm command from static tool mapping, omits `sudo`
+    on Linux and Windows, prepends `sudo` on other runtimes, and uses resolved
+    `npm.cmd` path on Windows when available to avoid process-launch failures.
+    For Windows Copilot installs, retries once after a non-zero first attempt
+    to mitigate transient file-lock failures during binary replacement.
+    @param tool_key {str} Tool identifier key from `TOOLS`.
+    @return {bool} `True` when installation succeeds; `False` otherwise.
+    @satisfies DES-013, REQ-008, REQ-047, REQ-056, REQ-072
+    """
+
+    info = TOOLS[tool_key]
+    command = list(info["install"])
+    runtime_os = get_runtime_os()
+    windows_runtime = runtime_os == "windows"
+    if windows_runtime:
+        npm_cmd_path = shutil.which("npm.cmd")
+        if npm_cmd_path:
+            command[0] = npm_cmd_path
+    elif runtime_os != "linux":
+        require_commands("sudo")
+        command = ["sudo"] + command
+    require_commands(command[0])
+    print_info(f"Installing {info['name']}...")
+    max_attempts = 2 if windows_runtime and tool_key == "copilot" else 1
+    result = None
+    for attempt_idx in range(max_attempts):
+        result = subprocess.run(command)
+        if result.returncode == 0:
+            break
+        if attempt_idx + 1 < max_attempts:
+            print_info(
+                "Retrying GitHub Copilot CLI installation after transient Windows file lock..."
+            )
+    assert result is not None
+    if result.returncode != 0:
+        print_error(f"Failed to install {info['name']}.")
+        print()
+        return False
+
+    print_success(f"{info['name']} installed.")
+    print()
+    return True
+
+
+def _normalize_kiro_linux_arch(machine_token):
+    """@brief Normalize machine architecture token for Kiro Linux packages.
+
+    @details Maps runtime machine names into manifest architecture keys accepted
+    by Kiro headless Linux ZIP entries. Raises explicit error for unknown
+    architecture to avoid ambiguous package selection.
+    @param machine_token {str} Raw `platform.machine()` token.
+    @return {str} Normalized architecture token (`x86_64` or `aarch64`).
+    @throws {RuntimeError} When architecture is not supported by Kiro installer.
+    @satisfies REQ-010, REQ-067
+    """
+
+    normalized = machine_token.strip().lower()
+    if normalized in ("x86_64", "amd64"):
+        return "x86_64"
+    if normalized in ("aarch64", "arm64"):
+        return "aarch64"
+    raise RuntimeError(
+        f"Unsupported Linux architecture for Kiro installer: {machine_token}"
+    )
+
+
+def _detect_kiro_linux_libc():
+    """@brief Detect Linux libc class token for Kiro package selection.
+
+    @details Uses `platform.libc_ver()` to classify runtime libc as `musl` or
+    `gnu`. Unknown or empty values default to `gnu` to keep deterministic
+    package selection for glibc environments.
+    @return {str} libc class token (`musl` or `gnu`).
+    @satisfies REQ-010
+    """
+
+    libc_name, _ = platform.libc_ver()
+    if "musl" in libc_name.lower():
+        return "musl"
+    return "gnu"
+
+
+def _resolve_kiro_linux_download_path(manifest, arch_token, libc_token):
+    """@brief Resolve Kiro Linux ZIP download path from manifest metadata.
+
+    @details Filters manifest packages by Linux OS, headless ZIP variant,
+    runtime architecture, and runtime libc class reflected in target triple.
+    Returns first matching `download` path and fails explicitly when no match
+    exists.
+    @param manifest {dict[str, object]} Parsed Kiro manifest JSON payload.
+    @param arch_token {str} Normalized architecture token (`x86_64|aarch64`).
+    @param libc_token {str} Normalized libc token (`gnu|musl`).
+    @return {str} Relative download path from manifest `packages[].download`.
+    @throws {RuntimeError} When no manifest package matches runtime filters.
+    @satisfies DES-013, REQ-010
+    """
+
+    if libc_token not in ("gnu", "musl"):
+        raise RuntimeError(f"Unsupported Linux libc class for Kiro installer: {libc_token}")
+
+    target_suffix = "linux-musl" if libc_token == "musl" else "linux-gnu"
+    packages = manifest.get("packages")
+    if not isinstance(packages, list):
+        raise RuntimeError("Invalid Kiro manifest format: missing packages list")
+
+    for package in packages:
+        if not isinstance(package, dict):
+            continue
+        if package.get("os") != "linux":
+            continue
+        if package.get("fileType") != "zip":
+            continue
+        if package.get("variant") != KIRO_LINUX_VARIANT:
+            continue
+        if package.get("architecture") != arch_token:
+            continue
+        target_triple = str(package.get("targetTriple", ""))
+        if target_suffix not in target_triple:
+            continue
+        download_path = package.get("download")
+        if isinstance(download_path, str) and download_path:
+            return download_path
+
+    raise RuntimeError(
+        "No Kiro Linux package matched runtime architecture/libc in manifest"
+    )
+
+
+def _install_claude():
+    """@brief Install Claude CLI by direct binary download.
+
+    @details Downloads latest version metadata from configured bucket, resolves
+    OS-specific Claude artifact candidates from runtime OS token, downloads the
+    first available artifact, writes executable into `~/.claude/bin/claude`,
+    and sets execute permissions on non-Windows runtimes.
+    @return {None} Executes side effects and prints result messages.
+    @throws {RuntimeError} When runtime OS has no configured package candidates.
+    @throws {urllib.error.URLError} When metadata or artifact download fails.
+    @throws {OSError} When destination write or permission update fails.
+    @satisfies DES-013, REQ-009
+    """
+
+    import urllib.error
+    import urllib.request
+
+    print_info("Installing Claude CLI...")
+    install_dir = Path.home() / ".claude" / "bin"
+    install_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        runtime_os = get_runtime_os()
+        artifact_candidates = CLAUDE_ARTIFACT_CANDIDATES.get(runtime_os)
+        if not artifact_candidates:
+            raise RuntimeError(f"Unsupported runtime OS for Claude installer: {runtime_os}")
+
+        version_url = f"{CLAUDE_BUCKET}/latest"
+        with urllib.request.urlopen(version_url, timeout=15) as resp:
+            version = resp.read().decode().strip()
+
+        print_info(f"Downloading Claude CLI version {version}...")
+        download_error = None
+        dest = install_dir / "claude"
+        for artifact_path in artifact_candidates:
+            binary_url = f"{CLAUDE_BUCKET}/{version}/{artifact_path}"
+            try:
+                urllib.request.urlretrieve(binary_url, str(dest))
+                break
+            except (urllib.error.HTTPError, urllib.error.URLError) as error:
+                download_error = error
+        else:
+            raise RuntimeError(
+                f"No Claude artifact candidate was downloadable for OS {runtime_os}"
+            ) from download_error
+
+        if runtime_os != "windows":
+            dest.chmod(0o755)
+        print_success(f"Claude CLI installed to {dest}")
+    except (OSError, RuntimeError, urllib.error.HTTPError, urllib.error.URLError) as e:
+        print_error(f"Failed to install Claude CLI: {e}")
+    print()
+
+
+def _install_pi() -> None:
+    """@brief Install pi.dev CLI and required post-install pi packages.
+
+    @details Executes npm-based pi.dev CLI installation first. When npm
+    installation succeeds, the function resolves the `pi` executable and
+    installs each package from `PI_PACKAGES` using `pi install <package>` in
+    tuple order. Package installation is skipped only when CLI installation
+    fails.
+    @return {None} Executes side effects and prints result messages.
+    @satisfies DES-013, REQ-072, REQ-073, REQ-074
+    """
+
+    if not _install_npm_tool("pi"):
+        return
+
+    pi_executable = require_commands("pi")
+    print_info("Installing pi.dev packages...")
+    for package in PI_PACKAGES:
+        result = subprocess.run([pi_executable, "install", package])
+        if result.returncode != 0:
+            print_error(f"Failed to install pi.dev package: {package}.")
+            print()
+            return
+
+    print_success("pi.dev packages installed.")
+    print()
+
+
+def _install_kiro():
+    """@brief Install Kiro CLI binaries by ZIP extraction flow.
+
+    @details Rejects unsupported runtime OS values (`windows`, `darwin`) with
+    explicit errors. On Linux, resolves runtime architecture/libc package from
+    official stable manifest, downloads selected ZIP archive, extracts
+    `kiro-cli*` binaries, and installs them into `~/.local/bin`.
+    @return {None} Executes side effects and prints result messages.
+    @throws {RuntimeError} When runtime OS is unsupported or manifest has no
+      matching package.
+    @throws {urllib.error.URLError} When archive download fails.
+    @throws {json.JSONDecodeError} When manifest payload is malformed.
+    @throws {zipfile.BadZipFile} When downloaded archive is invalid.
+    @throws {OSError} When extraction/copy/permission updates fail.
+    @satisfies DES-013, REQ-010, REQ-067
+    """
+
+    import urllib.error
+    import urllib.request
+
+    print_info("Installing Kiro CLI...")
+    runtime_os = get_runtime_os()
+    if runtime_os == "windows":
+        print_error("Failed to install Kiro CLI: unsupported runtime OS windows.")
+        print()
+        return
+    if runtime_os == "darwin":
+        print_error("Failed to install Kiro CLI: unsupported runtime OS darwin.")
+        print()
+        return
+    if runtime_os != "linux":
+        print_error(f"Failed to install Kiro CLI: unsupported runtime OS {runtime_os}.")
+        print()
+        return
+
+    install_dir = Path.home() / ".local" / "bin"
+    install_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        machine_arch = _normalize_kiro_linux_arch(platform.machine())
+        libc_token = _detect_kiro_linux_libc()
+        with urllib.request.urlopen(KIRO_MANIFEST_URL, timeout=15) as response:
+            manifest_payload = json.loads(response.read().decode())
+        download_path = _resolve_kiro_linux_download_path(
+            manifest_payload,
+            machine_arch,
+            libc_token,
+        )
+        archive_url = f"{KIRO_CHANNEL_BASE_URL}/{download_path}"
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            zip_path = os.path.join(tmpdir, "kiro.zip")
+            print_info("Downloading Kiro CLI...")
+            urllib.request.urlretrieve(archive_url, zip_path)
+
+            with zipfile.ZipFile(zip_path, "r") as zf:
+                zf.extractall(tmpdir)
+
+            copied_binaries = []
+            for src in Path(tmpdir).rglob("kiro-cli*"):
+                if src.is_file():
+                    dest = install_dir / src.name
+                    shutil.copy2(src, str(dest))
+                    dest.chmod(0o755)
+                    copied_binaries.append(dest.name)
+
+            if not copied_binaries:
+                raise RuntimeError("No kiro-cli* binaries found in extracted archive")
+
+            print_success(f"Kiro CLI installed to {install_dir}")
+    except (
+        OSError,
+        RuntimeError,
+        urllib.error.HTTPError,
+        urllib.error.URLError,
+        zipfile.BadZipFile,
+    ) as e:
+        print_error(f"Failed to install Kiro CLI: {e}")
+    print()
+
+
+ALL_INSTALLERS = {
+    "codex": lambda: _install_npm_tool("codex"),
+    "copilot": lambda: _install_npm_tool("copilot"),
+    "gemini": lambda: _install_npm_tool("gemini"),
+    "opencode": lambda: _install_npm_tool("opencode"),
+    "pi": _install_pi,
+    "claude": _install_claude,
+    "kiro": _install_kiro,
+}
+
+
+def run(args: list[str]) -> int:
+    """@brief Parse selectors and execute selected AI installer routines.
+
+    @details Accepts explicit selectors or defaults to the full installer set
+    when omitted. Unknown selectors are rejected with return code `1`; no
+    compatibility parsing exists for removed `--extra` behavior.
+    @param args {list[str]} CLI selector tokens for installer filtering.
+    @return {int} `0` on successful dispatch; `1` on unknown selector.
+    @satisfies REQ-006, REQ-007, REQ-073, REQ-074
+    """
+
+    selected = []
+    include_all = False
+    for arg in args:
+        key = arg.lstrip("-")
+        if key == "all":
+            include_all = True
+            continue
+        if key in ALL_INSTALLERS:
+            selected.append(key)
+            continue
+        print_error(f"Unknown option: {arg}")
+        return 1
+
+    if include_all or not selected:
+        selected = list(ALL_INSTALLERS.keys())
+    else:
+        selected = list(dict.fromkeys(selected))
+
+    print_info(f"Starting AI CLI tools installation ({len(selected)} tools)...")
+    print()
+
+    for key in selected:
+        installer = ALL_INSTALLERS[key]
+        installer()
+
+    print_success("AI CLI tools installation complete.")
+    return 0