Docs: document sortVersions() and the ordering contract for http-backend version discovery

[sassdavid]

mise latest takes the last entry of the version list — mise does not sort it. docs/dev-tools/backends/http.md documents version_expr, version_json_path and version_regex but never mentions ordering, and sortVersions() — which fixes this and is used 9× in mise's own registry configs — appears nowhere in docs/.

Repro (mise 2026.8.8, macos-arm64):

[tools."http:demo"]
version = "1.0.0"
url = "https://example.com/demo-{{ version }}.tar.gz"
version_list_url = "https://example.com/"
version_expr = '["2.3.7", "2.3.10", "2.3.9"]'

$ mise cache clear http:demo && mise latest http:demo
2.3.9     # expected 2.3.10; the same set in ascending order returns 2.3.10

Note the mise cache clear: the version list is cached, so editing version_expr has no effect until the cache is cleared — this happens even for a tool that was never installed, so it looks separate from #8880, and it's worth a sentence in the docs as well.

sort() doesn't help (lexicographic: 2.3.10 < 2.3.7). sortVersions() does, but there is no way to discover it from the docs.

The realistic trap is GitHub's releases API, which returns newest-first, so the obvious config silently selects the oldest release:

version_list_url = "https://api.github.com/repos/aws/aws-msk-iam-auth/releases"

version_json_path = ".[].tag_name"   # mise latest -> 1.0.0
version_expr = 'fromJSON(body) | map({ trimPrefix(#.tag_name, "v") }) | sortVersions()'   # -> 2.3.7

Suggested fix: one paragraph in the "Version Discovery" section stating that the produced list must be ascending, plus sortVersions() and the GitHub example above. A short list of available expr helpers would also help — int, parseInt, padStart and reverse are not available, which currently takes trial and error to find out.

Same root cause was fixed at the tool level in #8619 and #8812.

[jdx]

Thanks—confirmed. The ordering mismatch is a bug: version_order = "semver" should control both mise ls-remote output and resolution so the displayed order agrees with the version selected as latest.

I updated #12170 from a docs-only change to a behavior fix. The shared remote-list path now applies version_order after reading the source-ordered cache, preserving cache behavior and VersionInfo metadata. Because the fix is shared, it covers every backend that supports this option: HTTP, Aqua, GitHub, GitLab, and Forgejo. sortVersions() remains available when a version_expr needs a sorted intermediate value.

The cache behavior reproduced on 2026.8.8 was also real, but it was independently fixed by #12164, merged today. Listing-affecting HTTP options now partition the remote-version cache, so changing version_list_url, version_regex, version_json_path, or version_expr will not require mise cache clear after that fix is released.

AI-assisted — Tool: Codex; model: openai/gpt-5; version: unavailable.

[sassdavid]

Thank you very much for the suggestion and the corrections; everything is working.