Go Edition: List & list-remote commands

[Zordrak]

Summary

Implement tfenv list (locally installed versions) and tfenv list-remote (available remote versions) commands for the Go edition.

Parent Epic

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

Motivation

These are the two listing commands that let users see what's installed locally and what's available remotely. They're straightforward but important for the user workflow of discovering and choosing versions.

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

tfenv list

• Scan ${TFENV_CONFIG_DIR}/versions/ for installed version directories
• Each subdirectory name is a version
• Sort by semver (newest first)
• Detect architecture of each installed binary using file header inspection
• Indicate the currently active version with * marker and version source
• Print to stdout, one version per line
• Error if versions directory doesn't exist or is inaccessible

Output format (matches Bash edition):

* 1.6.1 (arm64) (set by /home/user/.tfenv/version)
  1.5.0 (amd64)
  1.4.7 (amd64)

The active version is marked with * followed by the version, architecture in parentheses, and the version source in parentheses. Non-active versions are indented with two spaces.

Architecture detection:
The Bash edition uses the file command to inspect the terraform binary and extract architecture from the output:

• x86-64 / x86_64 → amd64
• aarch64 / arm64 → arm64
• 386 / i386 / 80386 → 386
• ARM, → arm
• Unrecognised → unknown

The Go edition should use debug/elf, debug/macho, and debug/pe stdlib packages to inspect binary headers natively (no file command dependency).

tfenv list-remote

• Fetch remote version list (using the remote listing package)
• Sort by semver (newest first, or reversed with TFENV_REVERSE_REMOTE)
• TFENV_SORT_VERSIONS_REMOTE=1 enables semver sort instead of server order (for Artifactory mirrors)
• Print to stdout, one version per line
• Exit 0 on success, non-zero on network failure

Output format: Plain version numbers, one per line:

1.6.1
1.6.0
1.5.7
1.5.6
...

Command Interface

tfenv list
tfenv list-remote [<regex>]

Acceptance Criteria

• tfenv list shows all installed versions sorted by semver (newest first)
• tfenv list marks the currently active version with *
• tfenv list shows the version source for the active version (e.g., set by /path/to/version)
• tfenv list shows the architecture of each installed binary (amd64, arm64, etc.)
• tfenv list with no installed versions prints No versions available error and exits non-zero
• tfenv list with inaccessible versions directory prints clear error
• tfenv list takes no arguments — exits with usage error if args given
• tfenv list prints No default set. Set with 'tfenv use <version>' when no default is active
• tfenv list-remote shows all available stable versions
• tfenv list-remote excludes pre-release versions by default
• TFENV_REVERSE_REMOTE=1 reverses the sort order for list-remote
• TFENV_SORT_VERSIONS_REMOTE=1 applies semver sort instead of server order
• list-remote takes no arguments — exits with usage error if args given
• Both commands output to stdout (one version per line)
• Exit codes: 0 on success, non-zero on failure
• Architecture detection works for ELF (Linux), Mach-O (macOS), and PE (Windows) binaries
• Acceptance tests for both commands using mock server (for list-remote)
• Acceptance tests verify sorting order and output format

Dependencies

• Depends on: Go Edition: Module scaffolding, CLI framework & multi-call entry point #489 (Go module scaffolding / CLI framework)
• Depends on: Go Edition: Configuration, state directory & platform detection #492 (Config) — state directory for list, remote URL for list-remote
• Depends on: Go Edition: Remote version listing #494 (Remote version listing) — list-remote uses the remote fetch
• Depends on: Go Edition: Logging framework #491 (Logging)

Implementation Notes

• Reference libexec/tfenv-list for local listing — note the detect_arch function (lines 90-110) and print_version function (lines 112-120)
• Reference libexec/tfenv-list-remote for remote listing
• The Bash edition uses the file command for arch detection — the Go edition should use debug/elf, debug/macho, debug/pe stdlib packages for native binary inspection (no external command dependency)
• The Bash edition does NOT accept arguments for list or list-remote — both exit with usage error if args are given
• The Bash edition uses \find (backslash to bypass aliases) to scan the versions directory — Go uses os.ReadDir()
• Version sorting MUST use semver comparison (not string sort) — hashicorp/go-version
• Issue tfenv list-remote doesn't have the versions sorted when using TFENV_REMOTE with Artifactory #401 (list-remote sorting with Artifactory) — TFENV_SORT_VERSIONS_REMOTE was added to fix this
• Issue tfenv list-remote greps the Artifactory version by mistake #400 (list-remote grep mistake with Artifactory) — proper HTML parsing avoids this
• Issue [tfenv list-remote] - not listing accurate version, only 1.22.0 #396 (list-remote not listing accurate versions) — proper implementation should fix this

Labels

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

[Zordrak]

Claimed by developer. Dispatching to feature-implementer.

[Zordrak]

Claimed by feature-implementer. Working on this.