`repomatic.tooling.binaries` module¶

Download, verify and cache the binary tools of the registry.

The binary half of repomatic run: each tool the registry ships as a platform-specific executable is downloaded from its release page, checked against the SHA-256 the registry records, extracted, and stored in the shared cache. ensure_binary() is the entry point for code that shells out to one of these tools without going through repomatic.tooling.runner.run_tool().

The module imports neither the runner nor the metadata layer, so the gh resolver of repomatic.github.gh can import it at the top of its module.

exception repomatic.tooling.binaries.ChecksumMismatchError[source]¶

Bases: BinaryInstallError

Raised when a download does not hash to the SHA-256 the registry records.

Never retried: the same bytes fail the same way. A mismatch points at a stale pin, a moved release asset or a tampered artifact.

repomatic.tooling.binaries.install_binary(spec, *, skip_checksum=False, no_cache=False)[source]¶

Download, verify and extract a binary tool, and return its executable.

Two-layer integrity model:

Archive checksum (download time): the registry checksum is verified against the downloaded archive. This defends against supply-chain tampering and is auditable against the upstream release page.
Binary sidecar (cache hit): after a verified download, extraction, and cache store, a .sha256 sidecar is written next to the cached binary. Subsequent cache hits verify the binary against this sidecar, defending against local cache tampering between runs.

The download goes through a staging directory. When the binary stays out of the cache, the staging copy is returned, and its directory lasts as long as the process: see _STAGING_DIRS.

Parameters:

spec (ToolSpec) – Tool specification with binary set.
skip_checksum (bool) – Skip SHA-256 verification when True.
no_cache (bool) – Bypass the cache entirely when True.

Return type:

Path

Returns:

Path to the ready-to-run executable.

Raises:

BinaryInstallError – On any failure to install the binary. The subclasses UnsupportedPlatformError and ChecksumMismatchError name the two failures a caller may handle apart.

repomatic.tooling.binaries.ensure_binary(name: str) → Path[source]¶

Install a registry binary tool and return the path to its executable.

The seam for repomatic code that shells out to a third-party binary but is not itself a run_tool() invocation. It buys the same guarantees every repomatic run binary gets: the registry-pinned version, its archive verified against the recorded SHA-256, and a shared cache so repeated calls in one run download once.

Prefer this over looking the tool up on PATH. Whatever PATH offers is whichever version the machine or CI image happens to carry, unpinned and unverified, and it differs between a developer’s laptop and every runner.

Memoized per tool name: callers in a loop (format-images optimizing one PNG per call) hit the install-and-verify path once per process, not once per file. The memo ignores the cache root, which a process does not change. Failures are not memoized, so a transient download error can be retried.