Add a CLI Tool to a Multi-Platform Downloader and Check Each Binary

## Check That the Tool Ships Static Binaries and List the Target Platforms Use this workflow for adding a command-line tool that is distributed as a directly executable static binary. Route system packages, container-image extraction, cluster add-ons, and runtime-managed applications to their own installation paths. Confirm the proposed tool has precompiled release assets before changing code. Reject packages that require an interpreter, package manager, installer script, or undeclared runtime dependency. Check that the contribution changes one tool only unless the project explicitly permits a broader batch. Require any project-specific design or issue approval before implementation when that gate exists. Create a focused branch using the repository's naming convention. Identify the installer command, the tool's public name, and its upstream owner and repository. List every platform combination the installer is expected to support. Use these baseline targets unless the project defines another matrix: - Linux on x86-64. - Linux on ARM64. - macOS on x86-64. - macOS on ARM64. - Windows on x86-64. Do not claim support for 32-bit x86 or ARMv6 unless the installer explicitly includes them. Record unavailable combinations rather than silently substituting another platform's artifact. ## Find the Exact Release Filenames for Each OS and Architecture Before Coding Inspect the latest stable upstream release before writing a download template. Prefer a redirect-only request to the upstream latest-release endpoint so the location header reveals the version tag. Do not follow the redirect when the tag itself is the required result. Inspect the expanded asset listing or another authoritative release page for that exact tag. Avoid consuming rate-limited APIs when equivalent public release metadata is available. Enumerate every published filename, archive format, operating system, and architecture. Preserve the upstream vocabulary exactly, including distinctions such as amd64 versus x86_64 and arm64 versus aarch64. For each expected target, record: - Whether an asset exists. - The exact asset filename. - The archive type, if any. - The binary name inside the archive, if different. - Any libc or toolchain variant that changes compatibility. Prefer a portable static variant such as musl when the project supports it and the choice is appropriate. Treat Rust filenames containing terms such as unknown as valid when they match the upstream release. Use the gathered matrix as the source of truth for templates, tests, and pull-request evidence. ## Map Each Platform to Its Real Download URL Without Fallbacks Add the tool through the installer's established definition structure and follow a nearby working example. Provide the required identity fields: tool name, upstream owner, repository, and concise description. Use a binary filename template for plain binaries whose release asset is the executable itself. Use a full URL template when the asset location needs custom path logic. Map every supported operating system and architecture to its actual upstream filename. Keep installer architecture constants separate from upstream filename vocabulary. Use explicit Windows detection that matches the runtime's operating-system representation. Supported archive forms must match the installer's decompression capabilities. Typical accepted forms include tar.gz, tgz, zip, bz2, and tar.xz. When a platform combination is unavailable, its generated URL must fail clearly, such as with a not-found response. It must never fall back to a Linux artifact, another architecture, or another tool. Keep version tag transformations explicit, especially when both a prefixed tag and a numeric version are used. Use existing template variables for operating system, architecture, name, version, owner, and repository. Do not hard-code a current version into the production definition when the installer supports version substitution. Review the final URL for every matrix row before relying on tests. ## Separate the Archive Name From the Binary Name Inside It Treat the release asset name and the executable name inside an archive as separate facts. If an archive contains a platform-suffixed executable, define both: - A URL template that names the downloadable archive including its extension. - A binary template that names the extracted executable without the archive extension. Do not place an archive filename with its extension into the binary template alone. Many decompressors use the binary template to locate the extracted file. An archive extension in that field can trigger fallback to the generic tool name. That fallback fails when the archive contains a platform-specific binary name. For a plain, uncompressed executable, a binary template alone is normally sufficient. Confirm the distinction by inspecting the archive rather than guessing from its filename. Check whether the archive adds a directory prefix around the executable. Check whether Windows executables require an exe suffix in both mapping and extraction. Keep checksum, signature, and executable-permission handling consistent with the existing installer. If extraction reports a missing file, compare these three names: - The downloaded asset. - The extracted archive member. - The name requested by the installer. Correct the mapping at the definition boundary instead of adding a broad fallback. ## Test Every Platform's Download URL With a Pinned Version Add a focused unit test beside existing downloader tests. Use a pinned upstream version; never test URL generation against latest. Create one case for every published and supported operating-system and architecture combination. Assert the full expected URL, including owner, repository, tag, filename, separators, and archive extension. Include platform-specific architecture aliases exactly as upstream publishes them. Test special version transformations and Windows suffixes when present. For unavailable combinations, test the installer's intended failure behavior when the framework supports such cases. Keep the test independent of mutable release metadata. Use the same asset matrix gathered before implementation. Run the focused package tests first. Then run the project's broader required test target when applicable. A passing URL test proves string construction only; it does not prove the downloaded file is the correct binary. ## Download Each Platform's Binary and Check Its Format and Architecture Build the installer before cross-platform verification. First download the current platform's artifact without override flags. Inspect the resulting file to catch HTML error pages, compressed data mistaken for executables, and empty files. Run the repository's platform-matrix verification script for the tool. Verify every supported combination, not only the machine running the test. Use a file-identification tool or equivalent binary parser to confirm format and architecture. Expected evidence commonly includes: - Linux x86-64 as a 64-bit ELF executable for x86-64. - Linux ARM64 as a 64-bit ELF executable for AArch64. - macOS x86-64 as a 64-bit Mach-O executable for x86-64. - macOS ARM64 as a 64-bit Mach-O executable for ARM64. - Windows x86-64 as a PE32+ console executable for x86-64. A successful HTTP response is insufficient because a template can download the wrong platform. A successful decompression is also insufficient because the inner executable can target the wrong architecture. Capture the full matrix output without editing away failures or warnings. If a target is unavailable upstream, verify that the installer fails for that target rather than delivering an incompatible binary. Resolve all mismatches before documentation or approval. ## Regenerate the CLI Catalog and Write the Test Results in the Pull Request Follow the repository's documented process for regenerating its CLI catalog. Generate the catalog from the installer rather than manually inventing a row. Use a temporary workspace file only when needed for safe replacement. Preserve the catalog's exact start and end markers. Replace only the generated table content and associated tool count between those markers. Do not remove surrounding prose or unrelated entries. Confirm the new tool appears once with the expected description. Delete the temporary generation file after the update. Prepare a pull-request description that states: - Available and unavailable platform combinations. - The authoritative release tag and naming pattern used. - The full platform verification output, including binary formats. - Required end-to-end or broader test output when applicable. Ensure every commit carries the repository's required sign-off. Keep evidence reproducible by naming the commands and pinned version. Do not summarize away a missing platform, failed download, or architecture mismatch. ## Review the Change and Trace Download or Extraction Failures Review eligibility, mapping, tests, documentation, and evidence as separate gates. Confirm the tool is a static binary and the change is limited to the approved scope. Check required identity fields and ensure at least one valid download mapping exists. Compare every template branch with the authoritative asset matrix. Verify unsupported combinations cannot receive another platform's binary. Confirm unit tests use a pinned version and cover all supported targets. Require binary-format evidence for every claimed target before approval. Confirm the generated documentation includes the tool and preserves its boundary markers. Investigate URL mismatches by comparing the exact upstream filename and tag transformation. Investigate wrong architectures by tracing operating-system and architecture branches independently. Investigate extraction failures by comparing archive name, archive members, and configured inner binary name. Investigate runtime failures by revisiting whether the project actually ships a self-contained static binary. Do not work around a missing upstream asset with an incompatible substitute. Document legitimate upstream gaps in the pull request. Approve only when code, tests, downloaded artifacts, documentation, and reported evidence agree.