Go Edition: Remote version listing

[Zordrak]

Summary

Implement remote version listing — fetching and parsing available Terraform versions from HashiCorp's release infrastructure (or configured mirror).

Parent Epic

Part of #488 — Go Edition: Full Feature Parity Implementation

Motivation

The ability to list available remote versions underpins tfenv list-remote, tfenv install latest, and all version resolution that requires knowledge of what versions exist. It must handle custom mirrors (TFENV_REMOTE), version sorting, and the specific HTML format of releases.hashicorp.com.

Clean-Room Constraint

This is a clean-room implementation. Contributors MUST NOT read, reference, copy, or adapt source code from tofuutils/tenv, hashicorp/hc-install, or any other third-party tfenv-like tool. The sole reference is tfenv's own Bash source code, documentation, and test suite.

Proposed Design

Package Location

go/internal/list/ (remote listing component)

Remote Index Fetching

• HTTP GET to ${TFENV_REMOTE}/terraform/ (default: https://releases.hashicorp.com/terraform/)
• Parse HTML response to extract version numbers
• The HTML format contains links like <a href="/terraform/1.5.0/">terraform_1.5.0</a>
• Extract version strings using HTML parsing (not regex on HTML)

Version Sorting

• Parse versions using hashicorp/go-version for correct semver sorting
• Default: newest first (descending)
• TFENV_REVERSE_REMOTE=1: oldest first (ascending)

Pre-release Filtering

• By default, exclude pre-release versions (alpha, beta, rc)
• Pre-release versions are included only when explicitly requested via regex patterns

Mirror Support

• TFENV_REMOTE overrides the base URL
• The path structure (/terraform/) is appended to the remote URL
• Support authenticated mirrors via TFENV_NETRC_PATH

HTTP Client

• Use net/http stdlib
• Respect HTTPS_PROXY / HTTP_PROXY / NO_PROXY environment variables (Go stdlib handles this automatically)
• Configurable timeout
• User-Agent header: tfenv/<version>

Acceptance Criteria

• Fetches version list from ${TFENV_REMOTE}/terraform/
• Correctly parses releases.hashicorp.com HTML format
• Returns versions sorted by semver (newest first by default)
• TFENV_REVERSE_REMOTE=1 reverses sort order
• Pre-release versions (alpha, beta, rc) are excluded by default
• TFENV_REMOTE overrides the default remote URL
• TFENV_NETRC_PATH is used for authenticated requests
• HTTP errors (404, 500, network timeout) produce clear error messages
• Unit tests use httptest.Server with realistic HTML fixtures — no network dependency
• Unit tests cover edge cases: empty response, malformed HTML, single version, pre-release only
• Version parsing uses hashicorp/go-version (not string sorting)

Dependencies

• Depends on: Go Edition: Module scaffolding, CLI framework & multi-call entry point #489 (Go module scaffolding)
• Depends on: Go Edition: Configuration, state directory & platform detection #492 (Config) — needs TFENV_REMOTE, TFENV_NETRC_PATH configuration
• Depends on: Go Edition: Logging framework #491 (Logging) — needs logging for debug output

Implementation Notes

• Reference libexec/tfenv-list-remote for the Bash implementation
• The Bash edition uses curlw (a curl wrapper from lib/helpers.sh) — the Go edition uses net/http directly
• The Bash edition extracts versions with grep -o '<a href="/terraform/[^"]*' | grep -o '[0-9]\+\.[0-9]\+\.[^"/]*' — the Go edition should use proper HTML parsing (golang.org/x/net/html or strings package with the known format)
• Consider caching the version list for the duration of a single command invocation (not to disk) to avoid redundant HTTP requests
• The acceptance test mock server (from Go Edition: Acceptance test framework & mock release server #490) will serve the same format

Labels

type:feature, priority:high, complexity:small, category:list

[Zordrak]

Claimed by developer. Dispatching to feature-implementer.