# Changelog

All notable changes to this project will be documented in this file. The format
is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this
project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.2.2] — 2026-08-07

### Fixed
- `dir download` could not restore a tree containing read-only
  directories — which the Go module cache is throughout (0555 dirs,
  0444 files). Extraction applied each archived mode as the entry
  landed, so the first file written into a restored 0555 directory
  failed with `permission denied`. Directories are now created
  writable and their recorded mode applied once extraction finishes,
  files are written writable and chmod'ed afterwards, and a read-only
  file left by an earlier restore is replaced instead of erroring.
  Caught by this repo's own CI on the first cache HIT of the new
  `gomod/*.tar.zst` key (build #295).

## [0.2.1] — 2026-08-07

### Fixed
- `install.sh` verified the download with `sha256sum -c --ignore-missing`,
  a coreutils extension busybox rejects — so on Alpine, which is what
  several manifests using this run on, the bootstrap aborted with a bogus
  "checksum mismatch". The hash is now compared as a plain string, which
  busybox, coreutils and macOS `shasum` all handle.
- `install.sh` stages the binary inside the target directory and renames
  it into place, so installing over a `cacher` that is currently running
  can't fail with ETXTBSY.

## [0.2.0] — 2026-08-07

### Added
- `--exec <script>` on `download`, `dir download` and `docker download` —
  on a cache miss the script runs through `sh -c` and its result seeds
  the cache. Generalises the `--url` and `--pull` fallbacks to anything
  expressible as a shell command, which collapses the
  restore-or-build `if`/`fi` block CI manifests repeat per cache:

  ```sh
  cacher dir download "gomod/{hash}.tar.zst" ~/go/pkg/mod \
    --hash-from go.sum --exec 'go mod download'
  ```

  The destination directory is created before the script runs; the seed
  upload is best-effort; a failing script is fatal and propagates its own
  exit status.
- `--optional` on `download` and `dir download` — a cache miss exits 0
  instead of 1/3, so `set -e` manifests no longer need a trailing
  `|| echo "cache miss"`.
- `install.sh`, published next to the binaries: detects the platform,
  verifies against `checksums.txt`, installs into `~/.local/bin` and, on
  builds.sr.ht, appends the `PATH` export to `~/.buildenv`. Reduces the
  bootstrap task to
  `curl -sSL https://bigbes.pages.srht.bigb.es/ci-cacher/install.sh | sh`.

## [0.1.2] — 2026-05-26

### Changed
- Landing page: widen body `max-width` from 44rem to 55rem.

## [0.1.1] — 2026-05-26

### Added
- `cacher docker download --pull` — on cache miss, falls back to
  `docker pull <image:tag>` and seeds the S3 cache. Mirrors the
  `--url` fallback on file download; collapses the if/else
  cache-or-pull bash dance in CI manifests to a single command.

### Changed
- Runtime errors (cache miss, key not found) no longer dump the cobra
  Usage block; the short error line is enough for scripted callers.
  Argument-validation errors still show usage.

## [0.1.0] — 2026-05-26

First public release. Replaces the `s3_cache_or_curl` /
`s3_cache_docker_image` shell helpers in `tarantool-protobuf/.builds/lib/ci-lib.sh`
with a single static Go binary.

### Added
- `cacher init` / `cacher doctor` — persist config to
  `~/.config/cacher/config.toml` and smoke-test S3 credentials (HEAD bucket
  + 1-byte canary write/read/delete).
- `cacher download` / `upload` / `exists` / `list` / `delete` for single
  files. Download falls back to `--url` on cache miss and back-fills the
  cache. Optional `--sha256` verifies the fetched content.
- `cacher docker {exists,download,upload}` — streamed `docker save | zstd`
  → S3 multipart upload (and inverse). Pure-Go zstd via
  [klauspost/compress](https://github.com/klauspost/compress), no external
  `zstd` binary on the host.
- `cacher dir {download,upload}` — tar+zstd of a directory tree keyed by
  content hash. Closes the gap left by the shell version, which only
  cached single files.
- `cacher key` — resolve a key template (substituting `{hash}`) for shell
  scripting.
- `--hash-from <path>` (repeatable; files or directories) on every command.
  For a single file path the digest exactly matches `sha256sum file | cut -c1-N`,
  so existing keys migrate without recomputation.
- `--arch-suffix` opt-in to suffix every key with `-<goos>-<goarch>`.
- `list --recursive` for flat listing; `list --root` to ignore the
  configured prefix and list at bucket root. Default output style mirrors
  `aws s3 ls` (delimited by `/`).
- Garage-compatible defaults: path-style addressing, signature v4,
  request/response checksum calculation set to `when_required` (Garage
  doesn't implement boto3 1.36+ trailing CRC32 checksums).
- End-to-end test suite (`go test -tags=e2e`) against a real Garage
  container via `testcontainers-go` using `dxflrs/garage:v2.3.0`'s
  `--single-node --default-bucket` mode.
- builds.sr.ht CI: `unit.yml` (every push), `e2e.yml` (every push, with
  Docker), `publish.yml` (tags only, ships cross-platform binaries via
  goreleaser to pages.sr.ht and as build artifacts).
- Static landing page at
  [bigbes.pages.srht.bigb.es/ci-cacher/](https://bigbes.pages.srht.bigb.es/ci-cacher/).

### Fixed
- `doctor` uses ListObjectsV2 (1-key) instead of HeadBucket — Garage
  rejects HeadBucket with 403 even for valid credentials.
- Config path is `~/.config/cacher/config.toml` on every platform
  (previously fell into `~/Library/Application Support/cacher` on macOS
  via `os.UserConfigDir`). cacher is a CI tool; dev-macs and Linux runners
  must look in the same place.

[Unreleased]: https://git.srht.bigb.es/~bigbes/ci-cacher/log/master
[0.2.2]: https://git.srht.bigb.es/~bigbes/ci-cacher/refs/v0.2.2
[0.2.1]: https://git.srht.bigb.es/~bigbes/ci-cacher/refs/v0.2.1
[0.2.0]: https://git.srht.bigb.es/~bigbes/ci-cacher/refs/v0.2.0
[0.1.2]: https://git.srht.bigb.es/~bigbes/ci-cacher/refs/v0.1.2
[0.1.1]: https://git.srht.bigb.es/~bigbes/ci-cacher/refs/v0.1.1
[0.1.0]: https://git.srht.bigb.es/~bigbes/ci-cacher/refs/v0.1.0