code-aide 1.16.2__tar.gz → 1.18.0__tar.gz

{code_aide-1.16.2 → code_aide-1.18.0}/.github/workflows/ci.yml

@@ -20,5 +20,7 @@ jobs:
         run: uv run ruff check .
       - name: Format check
         run: uv run black --check .
+      - name: Type check
+        run: uv run mypy
       - name: Run tests
         run: uv run pytest tests/ -v

{code_aide-1.16.2 → code_aide-1.18.0}/.gitlab-ci.yml

@@ -12,6 +12,7 @@ variables:
   script:
     - uv run ruff check .
     - uv run black --check .
+    - uv run mypy
     - uv run pytest tests/ -v
 
 check:python3.11:

{code_aide-1.16.2 → code_aide-1.18.0}/.pre-commit-config.yaml

@@ -36,3 +36,11 @@ repos:
     rev: 0.10.6
     hooks:
       - id: uv-lock
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run mypy
+        language: system
+        pass_filenames: false
+        files: ^src/code_aide/.*\.py$

code_aide-1.18.0/Makefile

@@ -0,0 +1,29 @@
+# code-aide quality checks (uv-based)
+
+.PHONY: build install test lint format format-check typecheck hooks check
+
+build:
+	uv build
+
+install:
+	uv sync
+
+test:
+	uv run pytest -n4 -q
+
+lint:
+	uv run ruff check .
+
+format:
+	uv run black .
+
+format-check:
+	uv run black --check .
+
+typecheck:
+	uv run mypy
+
+hooks:
+	pre-commit install
+
+check: lint format-check typecheck

{code_aide-1.16.2 → code_aide-1.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-aide
-Version: 1.16.2
+Version: 1.18.0
 Summary: Manage AI coding CLI tools (Claude, Antigravity, Copilot, Cursor, Gemini, Amp, Codex)
 Project-URL: Homepage, https://github.com/dajobe/code-aide
 Project-URL: Repository, https://github.com/dajobe/code-aide
@@ -49,6 +49,9 @@ pipx install code-aide
 ## Usage
 
 ```bash
+# Show compact one-line-per-tool status (default when no command is given)
+code-aide
+
 # List available tools and their status
 code-aide list
 
@@ -67,12 +70,24 @@ code-aide install
 # Install with automatic prerequisite installation (Node.js, npm)
 code-aide install -p
 
+# Verify checksums and show what would be installed, without installing
+code-aide install -n
+
 # Upgrade installed tools (no args = only out-of-date tools)
 code-aide upgrade [NAMES]
 
-# Remove tools
+# Remove tools (prompts before removing all managed tools)
 code-aide remove [NAMES]
 
+# Preview a removal without changing anything
+code-aide remove -n
+
+# Remove all managed tools without prompting
+code-aide remove -y
+
+# Remove stale version directories of direct-download tools
+code-aide clean [NAMES]
+
 # Check upstream for latest versions (dry-run)
 code-aide update-versions -n
 
@@ -106,8 +121,8 @@ code-aide uses a two-layer version data model:
    versions of code-aide.
 
 2. **User's local version cache** (`~/.config/code-aide/versions.json`): Written
-   by `code-aide update-versions`. Provides latest versions, dates, and updated
-   SHA256 checksums.
+   by `code-aide update-versions`. Provides latest versions, dates, updated
+   SHA256 checksums, and recorded tarball checksums for direct_download tools.
 
 Run `code-aide update-versions` to get the latest version data without waiting
 for a new code-aide release.
@@ -118,32 +133,34 @@ Each entry in `tools.json` describes one managed tool. Required fields are
 `name`, `command`, and `install_type`; the others are optional and only
 consulted when the relevant install method or platform applies.
 
-| Field                           | Required | Notes                                                                                        |
-|:--------------------------------|:---------|:---------------------------------------------------------------------------------------------|
-| `name`                          | Yes      | Display name for status output                                                               |
-| `command`                       | Yes      | Binary name (looked up in `PATH`)                                                            |
-| `aliases`                       | No       | Alternate names accepted by commands and resolved to the canonical tool key                  |
-| `install_type`                  | Yes      | One of `npm`, `script`, `direct_download`, `pkg`                                             |
-| `version_args`                  | No       | List of arguments passed to the binary to print its version (default: `["--version"]`)       |
-| `version_url`                   | No       | URL queried by `update-versions` to discover the latest upstream version                     |
-| `version_manifest_url_template` | No       | JSON manifest URL template with `{platform}`; reads its `version` field                      |
-| `latest_version`                | Cache    | Last known upstream version (filled by `update-versions`)                                    |
-| `latest_date`                   | Cache    | Release date for `latest_version`                                                            |
-| `prerequisites`                 | No       | List of required external commands (e.g. `["npm"]`)                                          |
-| `min_node_version`              | No       | Minimum major Node.js version required                                                       |
-| `npm_package`                   | npm      | npm package name (e.g. `@anthropic-ai/claude-code`)                                          |
-| `install_url`                   | script   | URL of the install script that will be downloaded and piped to `bash`                        |
-| `install_sha256`                | script   | SHA-256 of the install script body — required for verified installs                          |
-| `install_script_path_prepend`   | script   | Extra directories prepended to `PATH` when the install script runs (e.g. `["~/.local/bin"]`) |
-| `download_url_template`         | direct   | URL template with `{version}`, `{os}`, `{arch}` placeholders                                 |
-| `install_dir`                   | direct   | Directory to extract into; supports `{version}`                                              |
-| `bin_dir`                       | direct   | Directory where symlinks for `command` are created (e.g. `~/.local/bin`)                     |
-| `symlinks`                      | direct   | Map of `link_name` → relative path inside `install_dir` to symlink into `bin_dir`            |
-| `freebsd_port`                  | FreeBSD  | FreeBSD ports/pkg name (used when running on FreeBSD)                                        |
-| `freebsd_pkg_repo`              | FreeBSD  | Optional non-default pkg repository name (passed via `pkg install -r <repo>`)                |
-| `next_steps`                    | No       | Free-form text printed after a successful install                                            |
-| `docs_url`                      | No       | Documentation URL printed after install                                                      |
-| `self_updates`                  | No       | Tool updates itself when run; excludes it from managed upgrade actions                       |
+| Field                           | Required | Notes                                                                                                           |
+|:--------------------------------|:---------|:----------------------------------------------------------------------------------------------------------------|
+| `name`                          | Yes      | Display name for status output                                                                                  |
+| `command`                       | Yes      | Binary name (looked up in `PATH`)                                                                               |
+| `aliases`                       | No       | Alternate names accepted by commands and resolved to the canonical tool key                                     |
+| `install_type`                  | Yes      | One of `npm`, `script`, `direct_download`, `pkg`                                                                |
+| `version_args`                  | No       | List of arguments passed to the binary to print its version (default: `["--version"]`)                          |
+| `version_url`                   | No       | URL queried by `update-versions` to discover the latest upstream version                                        |
+| `version_manifest_url_template` | No       | JSON manifest URL template with `{platform}`; reads its `version` field                                         |
+| `version_extract_pattern`       | No       | Regex applied to the install script to extract the version before generic heuristics                            |
+| `latest_version`                | Cache    | Last known upstream version (filled by `update-versions`)                                                       |
+| `latest_date`                   | Cache    | Release date for `latest_version`                                                                               |
+| `prerequisites`                 | No       | List of required external commands (e.g. `["npm"]`)                                                             |
+| `min_node_version`              | No       | Minimum major Node.js version required                                                                          |
+| `npm_package`                   | npm      | npm package name (e.g. `@anthropic-ai/claude-code`)                                                             |
+| `install_url`                   | script   | URL of the install script that will be downloaded and piped to `bash`                                           |
+| `install_sha256`                | script   | SHA-256 of the install script body — required for verified installs                                             |
+| `download_sha256`               | Cache    | SHA-256 of the downloaded tarball for direct_download tools; recorded by `update-versions`, verified on install |
+| `install_script_path_prepend`   | script   | Extra directories prepended to `PATH` when the install script runs (e.g. `["~/.local/bin"]`)                    |
+| `download_url_template`         | direct   | URL template with `{version}`, `{os}`, `{arch}` placeholders                                                    |
+| `install_dir`                   | direct   | Directory to extract into; supports `{version}`                                                                 |
+| `bin_dir`                       | direct   | Directory where symlinks for `command` are created (e.g. `~/.local/bin`)                                        |
+| `symlinks`                      | direct   | Map of `link_name` → relative path inside `install_dir` to symlink into `bin_dir`                               |
+| `freebsd_port`                  | FreeBSD  | FreeBSD ports/pkg name (used when running on FreeBSD)                                                           |
+| `freebsd_pkg_repo`              | FreeBSD  | Optional non-default pkg repository name (passed via `pkg install -r <repo>`)                                   |
+| `next_steps`                    | No       | Free-form text printed after a successful install                                                               |
+| `docs_url`                      | No       | Documentation URL printed after install                                                                         |
+| `self_updates`                  | No       | Tool updates itself when run; excludes it from managed upgrade actions                                          |
 
 ## Features
 
@@ -155,6 +172,15 @@ consulted when the relevant install method or platform applies.
 - PATH configuration validation and warnings
 - Supports Linux and macOS
 
+## Configuration
+
+- Tool definitions are bundled at `src/code_aide/data/tools.json`.
+- The version cache lives at `~/.config/code-aide/versions.json` by default; set
+  `XDG_CONFIG_HOME` to relocate the `code-aide` config directory.
+- Color output honors `NO_COLOR`, `FORCE_COLOR`, `CLICOLOR_FORCE`, `CLICOLOR=0`,
+  and `TERM=dumb`, in that priority order; color is disabled when stdout is not
+  a terminal.
+
 ## Requirements
 
 - Python 3.11+

{code_aide-1.16.2 → code_aide-1.18.0}/README.md

@@ -22,6 +22,9 @@ pipx install code-aide
 ## Usage
 
 ```bash
+# Show compact one-line-per-tool status (default when no command is given)
+code-aide
+
 # List available tools and their status
 code-aide list
 
@@ -40,12 +43,24 @@ code-aide install
 # Install with automatic prerequisite installation (Node.js, npm)
 code-aide install -p
 
+# Verify checksums and show what would be installed, without installing
+code-aide install -n
+
 # Upgrade installed tools (no args = only out-of-date tools)
 code-aide upgrade [NAMES]
 
-# Remove tools
+# Remove tools (prompts before removing all managed tools)
 code-aide remove [NAMES]
 
+# Preview a removal without changing anything
+code-aide remove -n
+
+# Remove all managed tools without prompting
+code-aide remove -y
+
+# Remove stale version directories of direct-download tools
+code-aide clean [NAMES]
+
 # Check upstream for latest versions (dry-run)
 code-aide update-versions -n
 
@@ -79,8 +94,8 @@ code-aide uses a two-layer version data model:
    versions of code-aide.
 
 2. **User's local version cache** (`~/.config/code-aide/versions.json`): Written
-   by `code-aide update-versions`. Provides latest versions, dates, and updated
-   SHA256 checksums.
+   by `code-aide update-versions`. Provides latest versions, dates, updated
+   SHA256 checksums, and recorded tarball checksums for direct_download tools.
 
 Run `code-aide update-versions` to get the latest version data without waiting
 for a new code-aide release.
@@ -91,32 +106,34 @@ Each entry in `tools.json` describes one managed tool. Required fields are
 `name`, `command`, and `install_type`; the others are optional and only
 consulted when the relevant install method or platform applies.
 
-| Field                           | Required | Notes                                                                                        |
-|:--------------------------------|:---------|:---------------------------------------------------------------------------------------------|
-| `name`                          | Yes      | Display name for status output                                                               |
-| `command`                       | Yes      | Binary name (looked up in `PATH`)                                                            |
-| `aliases`                       | No       | Alternate names accepted by commands and resolved to the canonical tool key                  |
-| `install_type`                  | Yes      | One of `npm`, `script`, `direct_download`, `pkg`                                             |
-| `version_args`                  | No       | List of arguments passed to the binary to print its version (default: `["--version"]`)       |
-| `version_url`                   | No       | URL queried by `update-versions` to discover the latest upstream version                     |
-| `version_manifest_url_template` | No       | JSON manifest URL template with `{platform}`; reads its `version` field                      |
-| `latest_version`                | Cache    | Last known upstream version (filled by `update-versions`)                                    |
-| `latest_date`                   | Cache    | Release date for `latest_version`                                                            |
-| `prerequisites`                 | No       | List of required external commands (e.g. `["npm"]`)                                          |
-| `min_node_version`              | No       | Minimum major Node.js version required                                                       |
-| `npm_package`                   | npm      | npm package name (e.g. `@anthropic-ai/claude-code`)                                          |
-| `install_url`                   | script   | URL of the install script that will be downloaded and piped to `bash`                        |
-| `install_sha256`                | script   | SHA-256 of the install script body — required for verified installs                          |
-| `install_script_path_prepend`   | script   | Extra directories prepended to `PATH` when the install script runs (e.g. `["~/.local/bin"]`) |
-| `download_url_template`         | direct   | URL template with `{version}`, `{os}`, `{arch}` placeholders                                 |
-| `install_dir`                   | direct   | Directory to extract into; supports `{version}`                                              |
-| `bin_dir`                       | direct   | Directory where symlinks for `command` are created (e.g. `~/.local/bin`)                     |
-| `symlinks`                      | direct   | Map of `link_name` → relative path inside `install_dir` to symlink into `bin_dir`            |
-| `freebsd_port`                  | FreeBSD  | FreeBSD ports/pkg name (used when running on FreeBSD)                                        |
-| `freebsd_pkg_repo`              | FreeBSD  | Optional non-default pkg repository name (passed via `pkg install -r <repo>`)                |
-| `next_steps`                    | No       | Free-form text printed after a successful install                                            |
-| `docs_url`                      | No       | Documentation URL printed after install                                                      |
-| `self_updates`                  | No       | Tool updates itself when run; excludes it from managed upgrade actions                       |
+| Field                           | Required | Notes                                                                                                           |
+|:--------------------------------|:---------|:----------------------------------------------------------------------------------------------------------------|
+| `name`                          | Yes      | Display name for status output                                                                                  |
+| `command`                       | Yes      | Binary name (looked up in `PATH`)                                                                               |
+| `aliases`                       | No       | Alternate names accepted by commands and resolved to the canonical tool key                                     |
+| `install_type`                  | Yes      | One of `npm`, `script`, `direct_download`, `pkg`                                                                |
+| `version_args`                  | No       | List of arguments passed to the binary to print its version (default: `["--version"]`)                          |
+| `version_url`                   | No       | URL queried by `update-versions` to discover the latest upstream version                                        |
+| `version_manifest_url_template` | No       | JSON manifest URL template with `{platform}`; reads its `version` field                                         |
+| `version_extract_pattern`       | No       | Regex applied to the install script to extract the version before generic heuristics                            |
+| `latest_version`                | Cache    | Last known upstream version (filled by `update-versions`)                                                       |
+| `latest_date`                   | Cache    | Release date for `latest_version`                                                                               |
+| `prerequisites`                 | No       | List of required external commands (e.g. `["npm"]`)                                                             |
+| `min_node_version`              | No       | Minimum major Node.js version required                                                                          |
+| `npm_package`                   | npm      | npm package name (e.g. `@anthropic-ai/claude-code`)                                                             |
+| `install_url`                   | script   | URL of the install script that will be downloaded and piped to `bash`                                           |
+| `install_sha256`                | script   | SHA-256 of the install script body — required for verified installs                                             |
+| `download_sha256`               | Cache    | SHA-256 of the downloaded tarball for direct_download tools; recorded by `update-versions`, verified on install |
+| `install_script_path_prepend`   | script   | Extra directories prepended to `PATH` when the install script runs (e.g. `["~/.local/bin"]`)                    |
+| `download_url_template`         | direct   | URL template with `{version}`, `{os}`, `{arch}` placeholders                                                    |
+| `install_dir`                   | direct   | Directory to extract into; supports `{version}`                                                                 |
+| `bin_dir`                       | direct   | Directory where symlinks for `command` are created (e.g. `~/.local/bin`)                                        |
+| `symlinks`                      | direct   | Map of `link_name` → relative path inside `install_dir` to symlink into `bin_dir`                               |
+| `freebsd_port`                  | FreeBSD  | FreeBSD ports/pkg name (used when running on FreeBSD)                                                           |
+| `freebsd_pkg_repo`              | FreeBSD  | Optional non-default pkg repository name (passed via `pkg install -r <repo>`)                                   |
+| `next_steps`                    | No       | Free-form text printed after a successful install                                                               |
+| `docs_url`                      | No       | Documentation URL printed after install                                                                         |
+| `self_updates`                  | No       | Tool updates itself when run; excludes it from managed upgrade actions                                          |
 
 ## Features
 
@@ -128,6 +145,15 @@ consulted when the relevant install method or platform applies.
 - PATH configuration validation and warnings
 - Supports Linux and macOS
 
+## Configuration
+
+- Tool definitions are bundled at `src/code_aide/data/tools.json`.
+- The version cache lives at `~/.config/code-aide/versions.json` by default; set
+  `XDG_CONFIG_HOME` to relocate the `code-aide` config directory.
+- Color output honors `NO_COLOR`, `FORCE_COLOR`, `CLICOLOR_FORCE`, `CLICOLOR=0`,
+  and `TERM=dumb`, in that priority order; color is disabled when stdout is not
+  a terminal.
+
 ## Requirements
 
 - Python 3.11+

code_aide-1.18.0/TODO.md

@@ -0,0 +1,30 @@
+# TODO
+
+Keep the project focused on managing AI coding CLI tools (install, upgrade,
+remove, status, and version metadata).
+
+All items below are deferred; none are scheduled.
+
+| # | Item                           | Risk | Effort | Notes                                                  |
+|:---|:-------------------------------|:-----|:-------|:-------------------------------------------------------|
+| 1 | `doctor` command               | Low  | Med    | Health checks exist but are scattered                  |
+| 2 | Cross-distro package detection | Med  | High   | Only Gentoo supported; other Linux distros get nothing |
+| 3 | Split large modules            | Low  | High   | Refactoring only; no behavior change                   |
+| 4 | Tests for edge cases           | Med  | Med    | PATH oddities, more version parsing corners            |
+
+## CLI and Automation UX
+
+- [ ] Add a focused `doctor` command for environment checks (PATH,
+  prerequisites, command health).
+
+## Platform and Package Detection
+
+- [ ] Broaden system package metadata detection beyond Gentoo-specific tooling
+  where practical; note that non-Gentoo system installs currently report "up to
+  date" because no available version is detectable.
+
+## Maintainability and Tests
+
+- [ ] Split larger modules into smaller focused files where practical
+  (`install.py`, `commands_actions.py`, `versions.py`).
+- [ ] Add tests for more prerequisite edge cases and PATH oddities.

{code_aide-1.16.2 → code_aide-1.18.0}/pyproject.toml

@@ -47,9 +47,6 @@ filterwarnings = [
     "error",
     "ignore::DeprecationWarning:_pytest.*",
 ]
-markers = [
-    "network: tests that make real network calls (deselect with '-m \"not network\"')",
-]
 
 [tool.mypy]
 python_version = "3.11"

{code_aide-1.16.2 → code_aide-1.18.0}/src/code_aide/__init__.py

@@ -1,3 +1,3 @@
 """code-aide - Manage AI coding CLI tools."""
 
-__version__ = "1.16.2"
+__version__ = "1.18.0"

{code_aide-1.16.2 → code_aide-1.18.0}/src/code_aide/commands_actions.py

@@ -6,7 +6,7 @@ from typing import Any, Dict, List
 
 from code_aide.constants import TOOLS
 from code_aide.detection import detect_install_method, get_brew_package_info
-from code_aide.install import install_tool
+from code_aide.install import fetch_download_checksum, install_tool
 from code_aide.install_types import (
     InstallMethod,
     InstallType,
@@ -16,6 +16,7 @@ from code_aide.install_types import (
 from code_aide.console import error, info, success, warning
 from code_aide.operations import (
     UpgradeResult,
+    clean_tool_versions,
     remove_tool,
     upgrade_tool,
     validate_tools,
@@ -34,6 +35,7 @@ from code_aide.versions import (
     print_check_results_table,
 )
 from code_aide.config import (
+    ensure_versions_cache,
     load_bundled_tools,
     load_versions_cache,
     merge_cached_versions,
@@ -45,6 +47,7 @@ from code_aide.config import (
 def cmd_install(args: argparse.Namespace) -> None:
     """Handle install command."""
     dryrun = getattr(args, "dryrun", False)
+    force = getattr(args, "force", False)
 
     if args.tools:
         tools_to_install = args.tools
@@ -75,7 +78,7 @@ def cmd_install(args: argparse.Namespace) -> None:
         )
 
     installed = []
-    installed_bin_dirs = []
+    installed_bin_dirs: List[str] = []
     failed = []
 
     for tool in tools_to_install:
@@ -85,7 +88,7 @@ def cmd_install(args: argparse.Namespace) -> None:
         else:
             info(f"=== Installing {tool} ===")
 
-        outcome = install_tool(tool, dryrun=dryrun)
+        outcome = install_tool(tool, dryrun=dryrun, force=force)
         if outcome:
             installed.append(tool)
             installed_bin_dirs.extend(outcome.bin_dirs)
@@ -136,6 +139,9 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
         info(f"Upgrading specified tools: {', '.join(tools_to_upgrade)}")
     else:
         tools_to_upgrade = []
+        # Default selection is driven by latest_version, so refresh stale
+        # cache data first; named upgrades below skip this.
+        ensure_versions_cache(TOOLS)
         for name, config in TOOLS.items():
             assessment = ToolUpgradeEvaluator(name, config).evaluate()
             if assessment.actionable_by_upgrade and name not in tools_to_upgrade:
@@ -198,14 +204,37 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
         )
 
 
+def _confirm_remove_all(tools: List[str]) -> bool:
+    """Prompt before removing every managed tool."""
+    print(f"This will remove {len(tools)} managed tools: {', '.join(tools)}")
+    try:
+        answer = input("Remove all of them? [y/N] ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return False
+    return answer in ("y", "yes")
+
+
 def cmd_remove(args: argparse.Namespace) -> None:
     """Handle remove command."""
+    dryrun = getattr(args, "dryrun", False)
+    assume_yes = getattr(args, "yes", False)
+
     if args.tools:
         tools_to_remove = args.tools
         info(f"Removing specified tools: {', '.join(tools_to_remove)}")
     else:
         tools_to_remove = list(TOOLS.keys())
-        info(f"No tools specified, removing all: {', '.join(tools_to_remove)}")
+        if dryrun:
+            info(
+                "[DRYRUN] Would remove all managed tools: "
+                f"{', '.join(tools_to_remove)}"
+            )
+        else:
+            info(f"No tools specified, removing all: {', '.join(tools_to_remove)}")
+            if not assume_yes and not _confirm_remove_all(tools_to_remove):
+                print("Aborted.")
+                return
 
     tools_to_remove = resolve_tool_names(tools_to_remove, TOOLS)
     validate_tools(tools_to_remove)
@@ -216,6 +245,14 @@ def cmd_remove(args: argparse.Namespace) -> None:
 
     for tool in tools_to_remove:
         print()
+        if dryrun:
+            info(f"=== Checking {tool} ===")
+            if is_tool_installed(tool):
+                removed.append(tool)
+            else:
+                skipped.append(tool)
+            continue
+
         info(f"=== Removing {tool} ===")
 
         if not is_tool_installed(tool):
@@ -229,8 +266,19 @@ def cmd_remove(args: argparse.Namespace) -> None:
 
     print()
     print("=" * 42)
-    info("Removal Summary")
+    if dryrun:
+        info("Removal Summary (dry run)")
+    else:
+        info("Removal Summary")
     print("=" * 42)
+    if dryrun:
+        if removed:
+            success(f"Would remove: {', '.join(removed)}")
+        if skipped:
+            warning(f"Not installed (skipped): {', '.join(skipped)}")
+        print()
+        success("Dry run completed without removing anything!")
+        return
 
     if removed:
         success(f"Successfully removed: {', '.join(removed)}")
@@ -248,6 +296,56 @@ def cmd_remove(args: argparse.Namespace) -> None:
         info("No tools were removed (all were not installed)")
 
 
+def cmd_clean(args: argparse.Namespace) -> None:
+    """Handle clean command: remove stale direct-download version dirs."""
+    dryrun = getattr(args, "dryrun", False)
+
+    if args.tools:
+        tools_to_clean = resolve_tool_names(args.tools, TOOLS)
+    else:
+        tools_to_clean = [
+            name
+            for name, config in TOOLS.items()
+            if parse_install_type(config.get("install_type"))
+            == InstallType.DIRECT_DOWNLOAD
+        ]
+        if not tools_to_clean:
+            info("No direct-download tools with cleanable versions")
+            return
+        info(
+            "No tools specified, cleaning direct-download tools: "
+            f"{', '.join(tools_to_clean)}"
+        )
+
+    validate_tools(tools_to_clean)
+
+    cleaned: Dict[str, List[str]] = {}
+    skipped = []
+    for tool in tools_to_clean:
+        print()
+        info(f"=== {'Checking' if dryrun else 'Cleaning'} {tool} ===")
+        removed = clean_tool_versions(tool, dryrun=dryrun)
+        if removed is None:
+            skipped.append(tool)
+        elif removed:
+            cleaned[tool] = removed
+
+    print()
+    print("=" * 42)
+    info("Cleanup Summary" + (" (dry run)" if dryrun else ""))
+    print("=" * 42)
+
+    if cleaned:
+        total = sum(len(paths) for paths in cleaned.values())
+        details = ", ".join(f"{tool} ({len(paths)})" for tool, paths in cleaned.items())
+        noun = "Would remove" if dryrun else "Removed"
+        success(f"{noun} {total} stale version directories: {details}")
+    if skipped:
+        info(f"Not cleanable (no versioned install layout): {', '.join(skipped)}")
+    if not cleaned:
+        success("Nothing to clean!")
+
+
 def cmd_update_versions(args: argparse.Namespace) -> None:
     """Handle update-versions command: check upstream for latest tool versions."""
     bundled = load_bundled_tools()
@@ -326,6 +424,30 @@ def cmd_update_versions(args: argparse.Namespace) -> None:
             tool_entry["latest_version"] = normalized
             version_info_changed = True
 
+    # Record the tarball checksum for direct-download tools so later
+    # installs can verify integrity against it.
+    if not args.dryrun:
+        for tool_name in tool_names:
+            tool_entry = config["tools"][tool_name]
+            if (
+                parse_install_type(tool_entry.get("install_type"))
+                != InstallType.DIRECT_DOWNLOAD
+            ):
+                continue
+            if "download_url_template" not in tool_entry:
+                continue
+            if not tool_entry.get("latest_version"):
+                continue
+            checksum = fetch_download_checksum(tool_entry)
+            if not checksum:
+                continue
+            if tool_entry.get("download_sha256") != checksum:
+                tool_entry["download_sha256"] = checksum
+                version_info_changed = True
+                print(f"Recorded download SHA256 for {tool_name}.")
+            else:
+                print(f"Download SHA256 for {tool_name} is unchanged.")
+
     def _save(tools: dict) -> str:
         """Save versions to user cache. Returns description."""
         save_updated_versions(tools)