feat(download): accept explicit version in download_or_build_binary (#687)

[gustav-fff]

Closes #687

Root cause

lua/fff/download.lua:235 download_or_build_binary() derives the download tag from git tag --points-at HEAD via fff.utils.version.current_release_tag (lua/fff/utils/version.lua:33). A release commit can carry several tags (e.g. 31be224 has v0.10.0, 0.9.7-nightly.a9df55d, and 0.10.1-nightly.31be224), and if lazy.nvim's shallow fetch does not bring the v* tag into the local repo the resolver falls through to a -nightly tag or to M.resolve(), which then constructs a nightly tag that may not have a matching release yet. Result: user pins version = "0.10.0" in lazy but the build hook downloads 0.10.1-nightly.<sha>, which sometimes 404s.

Fix

Expose an optional opts table on download_or_build_binary({ version = ..., proxy = ..., extra_curl_args = ..., timeout_ms = ... }). When version is set, ensure_downloaded receives it verbatim (bypassing the tag/HEAD heuristic). Accepts "0.10.0" or "v0.10.0" — a leading v is added only for ^%d+%.%d+%.%d+$ inputs so nightly / per-sha tags pass through untouched. timeout_ms is exposed too so users on slow hardware can raise the 2-minute cargo fallback ceiling reported in the issue (M1 Pro cold build ~6m40s). All params are optional — existing download_or_build_binary() callers are unaffected.

Steps to reproduce

Setup on origin/main (pre-fix):

{
  'dmtrKovalenko/fff.nvim',
  version = 'v0.10.0',
  build = function()
    require('fff.download').download_or_build_binary()
  end,
}

Add error('url: ' .. url) right after the url = string.format(...) line at lua/fff/download.lua:89. Restart Neovim so lazy re-runs the build hook.

Expected: the error prints https://github.com/dmtrKovalenko/fff.nvim/releases/download/v0.10.0/....
Actual (reporter): prints https://github.com/dmtrKovalenko/fff.nvim/releases/download/0.10.1-nightly.<sha>/..., and the download then 404s because that per-sha release does not exist yet.

Root-cause the divergence with git -C <lazy-checkout> tag --points-at HEAD — if the output does not contain v0.10.0, current_release_tag cannot return it and the code falls through to resolve().

How verified

Parse check: luac -p lua/fff/download.lua → OK.

Behavioral check with a mocked vim.system that captures the outbound URL:

CASE_1_UNPREFIXED ("0.10.0")  → https://github.com/dmtrKovalenko/fff.nvim/releases/download/v0.10.0/aarch64-apple-darwin.dylib
CASE_2_PREFIXED  ("v0.10.0")  → https://github.com/dmtrKovalenko/fff.nvim/releases/download/v0.10.0/aarch64-apple-darwin.dylib
CASE_3_NIGHTLY   ("nightly")  → https://github.com/dmtrKovalenko/fff.nvim/releases/download/nightly/aarch64-apple-darwin.dylib

Automated triage via Gustav. Honk-Honk 🪿

[gustav-fff]

[triage-bot] CI STATUS: initial Lua CI on commit `3b2ac9e` failed with a `need-check-nil` warning on `v:match` (lua-ls could not narrow `opts.version` locally). Fixed with a `---@cast v string` in commit `d302ce2` on branch `triage-bot/issue-687`; verified locally with `lua-language-server --configpath .luarc.ci.json --check=lua/fff/download.lua` → `no problems found`.

The PR head is not tracking the latest branch tip on GitHub's side — branch ref points at `d302ce2` but the PR still shows `3b2ac9e`. Force-with-lease and empty commits did not nudge it. May need a manual close/reopen or new push from a maintainer session to re-sync.

Honk-Honk 🪿