cli-skills 0.8.0__py3-none-any.whl

cli_skills/__init__.py

@@ -0,0 +1,13 @@
+## @file __init__.py
+# @brief Expose package-level metadata and public CLI entrypoint symbols.
+# @details Defines stable module exports for downstream imports and runtime version checks.
+
+## @brief Store semantic version string for package metadata.
+# @details Used by CLI usage/version output and by release automation checks.
+__version__ = "0.8.0"
+
+from .core import main  # noqa: F401
+
+## @brief Enumerate public symbols exported by package root.
+# @details Constrains wildcard-import surface to the version constant and CLI main callable.
+__all__ = ["__version__", "main"]

cli_skills/__main__.py

@@ -0,0 +1,11 @@
+## @file __main__.py
+# @brief Execute cli-skills CLI when module is invoked with `python -m`.
+# @details Imports the canonical `main` dispatcher and forwards process exit status.
+from .core import main
+import sys
+
+
+## @brief Trigger CLI dispatcher for module-execution entrypoint.
+# @details Invokes `main()` and propagates returned exit code via `sys.exit(...)`.
+if __name__ == "__main__":
+    sys.exit(main())

cli_skills/catalog.py

@@ -0,0 +1,190 @@
+"""
+@file catalog.py
+@brief Generate the skills and prompts manifest for `src/resources`.
+@details Deterministic generator for `src/resources/manifest.json`. Recursively
+         scans `src/resources/skills` for `SKILL.md` files and
+         `src/resources/prompts` for frontmatter files, extracts frontmatter
+         `name` and `description`, and emits entries sorted by relative path.
+         Validates every skill directory against the canonical support layout
+         before accepting its metadata. Single maintenance path guaranteeing
+         each manifest description equals its source frontmatter `description`
+         string (exact match).
+@satisfies DES-021 DES-022 DES-023 DES-024 DES-067 DES-068 DES-069 DES-070 DES-071 DES-072 DES-073
+"""
+
+from __future__ import annotations
+
+import importlib.resources as ires
+import json
+from pathlib import Path
+
+RESOURCES_ROOT = Path(str(ires.files("resources")))
+MANIFEST_PATH = RESOURCES_ROOT / "manifest.json"
+## @brief Canonical skill support subdirectory names allowed at the skill root.
+## @details Any other root directory or non-`SKILL.md` root file violates DES-067.
+SKILL_SUPPORT_DIRECTORIES = ("scripts", "references", "assets", "images")
+## @brief Canonical nested subdirectory names allowed directly under `references`.
+## @details Any other nested directory under `references` violates DES-069 and DES-070.
+REFERENCE_SUPPORT_DIRECTORIES = ("images",)
+
+
+class SkillLayoutError(ValueError):
+    """
+    @brief Signal a bundled skill layout that violates the canonical support layout.
+    @details Raised by `validate_skill_layout` when a skill root contains an
+             entry outside the canonical support subdirectories or when
+             `references` contains a non-canonical subdirectory.
+    @satisfies DES-073
+    """
+
+
+def validate_skill_layout(skill_dir: Path) -> None:
+    """
+    @brief Validate a bundled skill directory against the canonical support layout.
+    @details Accepts `SKILL.md` plus the canonical support subdirectories at the
+             skill root; accepts only `images` as a nested directory directly
+             under `references`. Non-canonical root files and directories are
+             rejected. Complexity O(E) where E is the number of root entries
+             plus direct `references` entries.
+    @param skill_dir {Path} Packaged skill directory containing `SKILL.md`.
+    @return {None}
+    @throws {SkillLayoutError} When a root entry or a nested `references`
+            directory violates DES-067 through DES-072.
+    @satisfies DES-067 DES-068 DES-069 DES-070 DES-071 DES-072 DES-073
+    @pre `skill_dir` MUST be an existing directory.
+    @post The directory layout is canonical or an exception is raised.
+    """
+    for entry in sorted(skill_dir.iterdir()):
+        if entry.name == "SKILL.md" and entry.is_file():
+            continue
+        if entry.is_dir() and entry.name in SKILL_SUPPORT_DIRECTORIES:
+            continue
+        raise SkillLayoutError(f"Invalid skill entry: {entry}")
+    references = skill_dir / "references"
+    if references.is_dir():
+        for entry in sorted(references.iterdir()):
+            if entry.is_dir() and entry.name not in REFERENCE_SUPPORT_DIRECTORIES:
+                raise SkillLayoutError(f"Invalid references entry: {entry}")
+
+
+def _parse_frontmatter(text: str) -> dict[str, str]:
+    """
+    @brief Parse `name` and `description` from a YAML frontmatter block.
+    @details Reads key/value lines up to the closing `---` delimiter, strips
+             surrounding YAML quotes from scalar values, and returns only the
+             `name` and `description` keys when present.
+    @param text {str} Raw file text (UTF-8).
+    @return {Dict[str, str]} Frontmatter `name`/`description` mapping; empty
+            when the block or keys are absent.
+    @pre `text` must be a non-empty string.
+    """
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}
+    end = 1
+    while end < len(lines) and lines[end].strip() != "---":
+        end += 1
+    if end >= len(lines):
+        return {}
+    fields: dict[str, str] = {}
+    for line in lines[1:end]:
+        if ":" not in line:
+            continue
+        key, _, value = line.partition(":")
+        key = key.strip()
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+            value = value[1:-1]
+        if key in ("name", "description"):
+            fields[key] = value
+    return fields
+
+
+def _discover_skills(root: Path) -> list[Path]:
+    """
+    @brief Discover `SKILL.md` files under `root/skills`.
+    @details Recursively collects every file named `SKILL.md`, sorted by path.
+    @param root {Path} Resources root directory.
+    @return {List[Path]} Sorted `SKILL.md` file paths.
+    """
+    skills_dir = root / "skills"
+    if not skills_dir.is_dir():
+        return []
+    return sorted(p for p in skills_dir.rglob("SKILL.md") if p.is_file())
+
+
+def _discover_prompts(root: Path) -> list[Path]:
+    """
+    @brief Discover candidate prompt files under `root/prompts`.
+    @details Recursively collects every regular file, sorted by path.
+             Frontmatter filtering is applied by `build_catalog`.
+    @param root {Path} Resources root directory.
+    @return {List[Path]} Sorted candidate prompt file paths.
+    """
+    prompts_dir = root / "prompts"
+    if not prompts_dir.is_dir():
+        return []
+    return sorted(p for p in prompts_dir.rglob("*") if p.is_file())
+
+
+def build_catalog(
+    resources_root: Path = RESOURCES_ROOT,
+) -> dict[str, list[dict[str, str]]]:
+    """
+    @brief Build the skills and prompts catalog dictionary.
+    @details Validates each skill directory layout, then scans skills and prompts
+             directories, extracts frontmatter metadata, and emits entries
+             sorted by relative path. Entries missing `name` or `description`
+             are omitted.
+    @param resources_root {Path} Resources root directory to scan.
+    @return {Dict[str, List[Dict[str, str]]]} Catalog with `skills` and
+            `prompts` lists; each entry contains `file`, `name`, `description`.
+    @throws {SkillLayoutError} When a discovered skill directory violates the
+            canonical support layout.
+    @satisfies DES-021 DES-022 DES-023 DES-024 DES-067 DES-068 DES-069 DES-070 DES-071 DES-072 DES-073
+    """
+    catalog: dict[str, list[dict[str, str]]] = {"skills": [], "prompts": []}
+    for path in _discover_skills(resources_root):
+        validate_skill_layout(path.parent)
+        meta = _parse_frontmatter(path.read_text(encoding="utf-8"))
+        if "name" in meta and "description" in meta:
+            catalog["skills"].append(
+                {
+                    "file": path.relative_to(resources_root).as_posix(),
+                    "name": meta["name"],
+                    "description": meta["description"],
+                }
+            )
+    for path in _discover_prompts(resources_root):
+        meta = _parse_frontmatter(path.read_text(encoding="utf-8"))
+        if "name" in meta and "description" in meta:
+            catalog["prompts"].append(
+                {
+                    "file": path.relative_to(resources_root).as_posix(),
+                    "name": meta["name"],
+                    "description": meta["description"],
+                }
+            )
+    return catalog
+
+
+def write_catalog(
+    resources_root: Path = RESOURCES_ROOT,
+    dest: Path = MANIFEST_PATH,
+) -> Path:
+    """
+    @brief Write the catalog to the JSON manifest file.
+    @details Serializes `build_catalog` output deterministically with UTF-8
+             encoding, two-space indent, no ASCII escaping, and trailing newline.
+    @param resources_root {Path} Resources root directory to scan.
+    @param dest {Path} Destination JSON manifest file path.
+    @return {Path} The written manifest file path.
+    @satisfies DES-021
+    """
+    catalog = build_catalog(resources_root)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(
+        json.dumps(catalog, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+    return dest

cli_skills/core.py

@@ -0,0 +1,459 @@
+"""CLI management commands, resource installation and uninstallation dispatch, and release notification orchestration."""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.request import Request, urlopen
+
+from . import __version__
+from .installer import install_enabled, uninstall_enabled
+from .settings import load_config, save_config
+from .show import build_show
+from .targets import TARGETS, resolve_target
+
+## @brief PyPI JSON API endpoint for the newest published version.
+## @satisfies DES-042
+PYPI_ENDPOINT = "https://pypi.org/pypi/cli-skills/json"
+ENDPOINT = "https://api.github.com/repos/Ogekuri/CLI-Skills/releases/latest"
+UPGRADE = ["uv", "tool", "install", "cli-skills", "--force"]
+## @brief Upgrade command argv installing the latest tagged GitHub release via git.
+## @details Executed for `--upgrade --dev`; bypasses PyPI.
+## @satisfies DES-081 REQ-063
+UPGRADE_DEVELOP = ["uv", "tool", "install", "cli-skills", "--force", "--from", "git+https://github.com/Ogekuri/CLI-Skills.git"]
+UNINSTALL = ["uv", "tool", "uninstall", "cli-skills"]
+SKILLS_INSTALL = ["cli-skills", "install"]
+"""
+@brief Child `cli-skills install` command executed after a successful upgrade.
+@details Spawned by `_post_upgrade_install` so the freshly upgraded package
+         installs its bundled skills and prompts into every enabled CLI.
+@satisfies REQ-043
+"""
+HELP = f"""Usage: cli-skills [command] [options] ({__version__})
+
+Management Commands:
+  --upgrade   - Reinstall cli-skills on Linux; print manual command elsewhere.
+  --uninstall - Uninstall cli-skills on Linux; print manual command elsewhere.
+  --ver       - Print the cli-skills version.
+  --version   - Print the cli-skills version.
+  --dev       - With --upgrade, install the latest GitHub release instead of PyPI.
+  --help      - Print the full help screen or the help text of a specific command.
+
+Installation Commands:
+  enable <cli name>  - Enable skill and prompt installation for a supported CLI.
+  disable <cli name> - Disable skill and prompt installation for a supported CLI.
+  install            - Install skills and prompts for every enabled CLI.
+  uninstall          - Remove installed skills and prompts for every enabled CLI.
+
+Reporting Commands:
+  show               - Show packaged resources, CLI configuration, and installation status.
+
+Commands:
+  ..."""
+
+
+def cache_path() -> Path:
+    return Path.home() / ".cache" / "cli-skills" / "check_version_idle-time.json"
+
+
+def _human(timestamp: float | None) -> str | None:
+    return datetime.fromtimestamp(timestamp, timezone.utc).isoformat() if timestamp is not None else None
+
+
+def _version(value: str) -> tuple[int, int, int]:
+    match = re.fullmatch(r"v?(\d+)\.(\d+)\.(\d+)", value)
+    if not match:
+        raise ValueError(f"Invalid release version: {value}")
+    return int(match.group(1)), int(match.group(2)), int(match.group(3))
+
+
+def _http_json(url: str, accept: str) -> dict:
+    """
+    @brief Perform one HTTP GET and parse the JSON response body.
+    @details Sends a `cli-skills` User-Agent with the caller-supplied Accept
+             header and enforces the hardcoded 2-second timeout. Network and
+             protocol errors propagate to the caller.
+    @param url {str} Absolute HTTP/HTTPS endpoint URL.
+    @param accept {str} HTTP Accept header value.
+    @return {Dict} Decoded top-level JSON object.
+    @throws {OSError} On transport or HTTP errors, including 429 and 503.
+    @throws {ValueError} When the response body is not valid JSON.
+    @satisfies CTN-006 DES-042 DES-083
+    """
+    request = Request(url, headers={"Accept": accept, "User-Agent": "cli-skills"})
+    with urlopen(request, timeout=2) as response:
+        return json.load(response)
+
+
+def fetch_pypi_latest() -> str:
+    """
+    @brief Fetch the newest published version from the PyPI JSON API.
+    @details Requests `PYPI_ENDPOINT`, reads `info.version`, and returns it
+             trimmed. Any transport, HTTP, or payload-shape failure raises.
+    @return {str} Newest PyPI version string.
+    @throws {OSError} On transport or HTTP errors, including 429 and 503.
+    @throws {ValueError} When the payload is not valid JSON or omits a
+            non-empty string `info.version`.
+    @throws {KeyError} When the payload omits `info.version`.
+    @satisfies DES-042 REQ-002 REQ-003 REQ-059
+    """
+    version = _http_json(PYPI_ENDPOINT, "application/json")["info"]["version"]
+    if not isinstance(version, str) or not version.strip():
+        raise ValueError("missing PyPI latest version")
+    return version.strip()
+
+
+def fetch_github_latest() -> str:
+    """
+    @brief Fetch the newest GitHub release version in `x.y.z` form.
+    @details Requests `ENDPOINT`, reads `tag_name`, and strips an optional `v`
+             prefix. The returned release is the newest tagged GitHub release
+             regardless of its source branch, matching the `--upgrade --dev`
+             download source.
+    @return {str} Newest GitHub release version as `x.y.z`.
+    @throws {OSError} On transport or HTTP errors, including 429 and 503.
+    @throws {ValueError} When the payload omits or holds an invalid
+            `tag_name`.
+    @throws {KeyError} When the payload omits `tag_name`.
+    @satisfies DES-083 REQ-061 REQ-062 REQ-063
+    """
+    tag = _http_json(ENDPOINT, "application/vnd.github+json")["tag_name"]
+    if not isinstance(tag, str):
+        raise ValueError("missing GitHub latest release tag")
+    match = re.fullmatch(r"v?(\d+\.\d+\.\d+)", tag.strip())
+    if not match:
+        raise ValueError(f"invalid GitHub release tag: {tag}")
+    return match.group(1)
+
+
+def check_version(force: bool = False) -> None:
+    """
+    @brief Run the cached automatic release check against PyPI.
+    @details Skips while the cached idle-time is valid unless `force` is set;
+             otherwise fetches the newest PyPI version via `fetch_pypi_latest`,
+             compares it with `__version__`, prints a bright-green
+             available-versus-installed message when a newer version exists or
+             a bright-red message for a failed or negative check, records
+             last-success timestamps on success only, and writes the cache
+             with a 3600-second (positive) or 86400-second (negative or
+             failed) expiration.
+    @param force {bool} Bypass the cached idle-time and perform the request.
+    @return {None}
+    @note Cache read/write and network failures are reported to stderr and do
+          not raise.
+    @satisfies REQ-001 REQ-002 REQ-003 REQ-004 REQ-005 REQ-016 REQ-017 REQ-018
+               REQ-019 REQ-020 REQ-021 REQ-022 REQ-023 REQ-059 CTN-006 CTN-007
+               CTN-008 DES-042 DES-043 DES-044 DES-045 DES-046
+    """
+    path = cache_path()
+    cache = {}
+    try:
+        with path.open(encoding="utf-8") as file:
+            cache = json.load(file)
+        if not isinstance(cache, dict):
+            cache = {}
+    except (OSError, ValueError):
+        pass
+    now = time.time()
+    idle = cache.get("idle_time_epoch")
+    if not force and isinstance(idle, (int, float)) and idle > now:
+        return
+
+    last_success = cache.get("last_success_epoch")
+    if not isinstance(last_success, (int, float)):
+        last_success = None
+    delay = 86400
+    try:
+        available = fetch_pypi_latest()
+        newer = _version(available) > _version(__version__)
+        now = time.time()
+        last_success = now
+        if newer:
+            delay = 3600
+            print(f"\033[92mAvailable Version: {available} | Installed Version: {__version__}\033[0m", file=sys.stderr)
+        else:
+            print("\033[91mVersion check: no newer version available.\033[0m", file=sys.stderr)
+    except (OSError, ValueError, KeyError, TypeError) as exc:
+        now = time.time()
+        print(f"\033[91mVersion check error: {exc}\033[0m", file=sys.stderr)
+    data = {
+        "last_success_epoch": last_success,
+        "last_success_human": _human(last_success),
+        "idle_time_epoch": now + delay,
+        "idle_time_human": _human(now + delay),
+    }
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    except OSError as exc:
+        print(f"\033[91mVersion cache error: {exc}\033[0m", file=sys.stderr)
+
+
+def _manage(command: list[str]) -> int:
+    if not sys.platform.startswith("linux"):
+        print(f"Warning: run this command manually: {' '.join(command)}")
+        return 0
+    try:
+        return subprocess.run(command, check=False).returncode
+    except OSError as exc:
+        print(f"Error executing {command[0]}: {exc}", file=sys.stderr)
+        return 1
+
+
+def _post_upgrade_install(home: Path | None = None) -> int:
+    """
+    @brief Install bundled resources through `cli-skills install` after a
+           successful upgrade.
+    @details Loads the user configuration and, when at least one CLI is
+             enabled, spawns `cli-skills install` as a child process so the
+             freshly upgraded package synchronizes its bundled skills and
+             prompts into every enabled CLI. Skips the child process when
+             the enabled configuration is empty. The child reads the
+             upgraded package resources, not the running process ones. The
+             child inherits stdout, so its per-CLI count and installed-name
+             report surfaces as visible `--upgrade` output.
+    @param home {Path | None} Optional home-directory override used only for
+            the configuration read; the child process inherits the real
+            environment.
+    @return {int} 0 when no CLI is enabled; otherwise the `cli-skills install`
+            exit code (1 on spawn or installation failure).
+    @throws {OSError} When reading the configuration file fails.
+    @satisfies REQ-043 REQ-044 REQ-046 REQ-058
+    """
+    if not load_config(home)["enabled"]:
+        return 0
+    return _manage(SKILLS_INSTALL)
+
+
+def _run_upgrade(command: list[str]) -> int:
+    """
+    @brief Execute one upgrade command and chain the post-upgrade install.
+    @details Delegates to `_manage` and, on a zero exit code under Linux,
+             chains `_post_upgrade_install` so the freshly upgraded package
+             installs bundled resources into every enabled CLI. Used by both
+             the PyPI `--upgrade` form and the GitHub `--upgrade --dev` form.
+    @param command {list[str]} Upgrade command argv executed on Linux and
+            printed as the manual command on other operating systems.
+    @return {int} Upgrade exit code, or the chained `cli-skills install` exit
+            code when the chained install executes.
+    @satisfies REQ-010 REQ-011 REQ-012 REQ-043 REQ-044 REQ-045 REQ-046 REQ-063
+    """
+    upgraded = _manage(command)
+    if upgraded == 0 and sys.platform.startswith("linux"):
+        return _post_upgrade_install()
+    return upgraded
+
+
+def _unsupported(name: str) -> str:
+    """
+    @brief Build an unsupported-CLI diagnostic message.
+    @details Lists the canonical CLI names accepted by the adapter registry.
+    @param name {str} Unsupported CLI name from the command line.
+    @return {str} Human-readable diagnostic message.
+    @satisfies REQ-026
+    """
+    return f"Unsupported CLI: {name}. Supported: {', '.join(TARGETS)}."
+
+
+def _enable(name: str, home: Path | None = None) -> int:
+    """
+    @brief Enable resource installation for one supported CLI.
+    @details Resolves the CLI adapter, loads the user configuration, appends
+             the canonical CLI name when absent, and persists the configuration.
+             Re-enabling an enabled CLI leaves configuration unchanged.
+    @param name {str} CLI name from the command line.
+    @param home {Path | None} Optional home-directory override.
+    @return {int} Exit code: 0 on success; 2 for an unsupported CLI.
+    @throws {OSError} When saving the configuration file fails.
+    @satisfies REQ-024 REQ-026 REQ-027 REQ-028
+    """
+    target = resolve_target(name)
+    if target is None:
+        print(_unsupported(name), file=sys.stderr)
+        return 2
+    config = load_config(home)
+    if target.name in config["enabled"]:
+        print(f"{target.name} is already enabled.")
+        return 0
+    config["enabled"].append(target.name)
+    save_config(config, home)
+    print(f"Enabled {target.name}.")
+    return 0
+
+
+def _disable(name: str, home: Path | None = None) -> int:
+    """
+    @brief Disable resource installation for one supported CLI.
+    @details Resolves the CLI adapter, loads the user configuration, removes
+             the canonical CLI name when present, and persists the
+             configuration. Disabling an already disabled CLI is a successful
+             no-op.
+    @param name {str} CLI name from the command line.
+    @param home {Path | None} Optional home-directory override.
+    @return {int} Exit code: 0 on success; 2 for an unsupported CLI.
+    @throws {OSError} When saving the configuration file fails.
+    @satisfies REQ-025 REQ-026 REQ-027 REQ-028
+    """
+    target = resolve_target(name)
+    if target is None:
+        print(_unsupported(name), file=sys.stderr)
+        return 2
+    config = load_config(home)
+    if target.name not in config["enabled"]:
+        print(f"{target.name} is already disabled.")
+        return 0
+    config["enabled"] = [item for item in config["enabled"] if item != target.name]
+    save_config(config, home)
+    print(f"Disabled {target.name}.")
+    return 0
+
+
+def _install(home: Path | None = None) -> int:
+    """
+    @brief Install bundled resources for all enabled CLIs.
+    @details Delegates installation to `install_enabled`, prints per-CLI skill
+             and prompt counts plus the installed skill names and prompt
+             filenames, prints an informational message when no CLI is
+             enabled, and reports collected failures.
+    @param home {Path | None} Optional home-directory override.
+    @return {int} Exit code: 0 when no failure occurs; 1 when any failure
+            occurs.
+    @satisfies REQ-029 REQ-030 REQ-031 REQ-032 REQ-057
+    """
+    summaries, errors = install_enabled(home)
+    if not summaries and not errors:
+        print("No CLI enabled. Use 'cli-skills enable <cli name>' first.")
+        return 0
+    for summary in summaries:
+        print(
+            f"Installed {summary.skills} skills and "
+            f"{summary.prompts} prompts for {summary.cli}."
+        )
+        skill_names = ", ".join(summary.skill_names) or "none"
+        prompt_names = ", ".join(summary.prompt_files) or "none"
+        print(f"  Skills: {skill_names}")
+        print(f"  Prompts: {prompt_names}")
+    for error in errors:
+        print(f"Error: {error}", file=sys.stderr)
+    return 1 if errors else 0
+
+
+def _uninstall(home: Path | None = None) -> int:
+    """
+    @brief Remove installed bundled resources for all enabled CLIs.
+    @details Delegates uninstallation to `uninstall_enabled`, prints per-CLI
+             removed skill and prompt counts, prints an informational message
+             when no CLI is enabled, and reports collected failures.
+    @param home {Path | None} Optional home-directory override.
+    @return {int} Exit code: 0 when no failure occurs; 1 when any failure
+            occurs.
+    @satisfies REQ-047 REQ-054 REQ-055 REQ-056
+    """
+    summaries, errors = uninstall_enabled(home)
+    if not summaries and not errors:
+        print("No CLI enabled. Use 'cli-skills enable <cli name>' first.")
+        return 0
+    for summary in summaries:
+        print(
+            f"Removed {summary.skills} skills and "
+            f"{summary.prompts} prompts for {summary.cli}."
+        )
+    for error in errors:
+        print(f"Error: {error}", file=sys.stderr)
+    return 1 if errors else 0
+
+
+def _show(home: Path | None = None) -> int:
+    """
+    @brief Print packaged resources, CLI configuration, and installation status.
+    @details Delegates report rendering to `build_show` and prints the result.
+    @param home {Path | None} Optional home-directory override.
+    @return {int} Exit code 0 after printing the report.
+    @throws {OSError} When bundled resources or the configuration cannot be read.
+    @satisfies REQ-037 REQ-038 REQ-039 REQ-042
+    """
+    print(build_show(home))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """
+    @brief Run the automatic release check and dispatch one CLI command.
+    @details Executes `check_version` before argument parsing (forced by
+             `--ver` or `--version`), then routes to help, version,
+             management, enable/disable, install, uninstall, or show
+             handlers. The `--upgrade` branch with or without `--dev` chains
+             `cli-skills install` after a successful Linux upgrade when the
+             enabled configuration is non-empty and returns the chained exit
+             code. The `--ver` and `--version` branch prints the installed
+             version plus the PyPI and GitHub latest-version lines.
+    @param argv {list[str] | None} Command-line arguments; defaults to
+            `sys.argv[1:]`.
+    @return {int} Process exit code: 0 on success; 1 on upgrade or install
+            failure; 2 on usage errors.
+    @satisfies REQ-006 REQ-007 REQ-008 REQ-009 REQ-010 REQ-011 REQ-012
+               REQ-013 REQ-014 REQ-015 REQ-024 REQ-025 REQ-026 REQ-029
+               REQ-030 REQ-031 REQ-032 REQ-037 REQ-042 REQ-043 REQ-044
+               REQ-045 REQ-046 REQ-047 REQ-054 REQ-055 REQ-056 REQ-057
+               REQ-058 REQ-059 REQ-060 REQ-061 REQ-062 REQ-063 REQ-064
+               REQ-065 DES-089
+    """
+    args = list(sys.argv[1:] if argv is None else argv)
+    check_version(force="--ver" in args or "--version" in args)
+    if not args or args == ["--help"]:
+        print(HELP)
+        return 0
+    if len(args) == 2 and args[1] == "--help":
+        command = args[0]
+        descriptions = {
+            "--upgrade": "Reinstall cli-skills on Linux; print manual command elsewhere.",
+            "--uninstall": "Uninstall cli-skills on Linux; print manual command elsewhere.",
+            "--ver": "Print the cli-skills version.",
+            "--version": "Print the cli-skills version.",
+            "--dev": "With --upgrade, install the latest GitHub release instead of PyPI.",
+            "enable": "Enable skill and prompt installation for a supported CLI.",
+            "disable": "Disable skill and prompt installation for a supported CLI.",
+            "install": "Install skills and prompts for every enabled CLI.",
+            "uninstall": "Remove installed skills and prompts for every enabled CLI.",
+            "show": "Show packaged resources, CLI configuration, and installation status.",
+        }
+        if command in descriptions:
+            print(f"{command} - {descriptions[command]}")
+            return 0
+    if args in (["--ver"], ["--version"]):
+        print(__version__)
+        try:
+            print(f"PyPI latest: {fetch_pypi_latest()}")
+        except (OSError, ValueError, KeyError, TypeError) as exc:
+            print(f"PyPI latest: unavailable ({exc})")
+        try:
+            print(f"GitHub latest: {fetch_github_latest()}")
+        except (OSError, ValueError, KeyError, TypeError) as exc:
+            print(f"GitHub latest: unavailable ({exc})")
+        return 0
+    if args == ["--upgrade"]:
+        return _run_upgrade(UPGRADE)
+    if args in (["--upgrade", "--dev"], ["--upgrade", "--develop"]):
+        return _run_upgrade(UPGRADE_DEVELOP)
+    if args == ["--uninstall"]:
+        return _manage(UNINSTALL)
+    if len(args) == 1 and args[0] in ("enable", "disable"):
+        print(f"Usage: cli-skills {args[0]} <cli name>", file=sys.stderr)
+        return 2
+    if len(args) == 2 and args[0] == "enable":
+        return _enable(args[1])
+    if len(args) == 2 and args[0] == "disable":
+        return _disable(args[1])
+    if args == ["install"]:
+        return _install()
+    if args == ["uninstall"]:
+        return _uninstall()
+    if args == ["show"]:
+        return _show()
+    print(f"Unknown command or options: {' '.join(args)}", file=sys.stderr)
+    return 2