Go Edition: Use command

[Zordrak]

Summary

Implement the tfenv use command for the Go edition — switching the active Terraform version.

Parent Epic

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

Motivation

tfenv use sets the active Terraform version by writing to the default version file. It must resolve version specifiers, verify the version is installed, and update the version file atomically.

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

Command Interface

tfenv use <version>
tfenv use latest
tfenv use latest:<regex>
tfenv use latest-allowed
tfenv use min-required
tfenv use -              # Switch to previous version

When called without arguments, reads .terraform-version or default version file, or TFENV_TERRAFORM_VERSION.

Use Flow

1. If argument is -, read previous version from ${TFENV_CONFIG_DIR}/version.prev
2. If no argument and no TFENV_TERRAFORM_VERSION, read from version file chain
3. Resolve version specifier → concrete version number
4. Verify the version is installed in ${TFENV_CONFIG_DIR}/versions/${version}/
5. Verify the terraform binary exists and is executable
6. If not installed and TFENV_AUTO_INSTALL=true, install it first
7. Save current version as previous: If ${TFENV_CONFIG_DIR}/version exists and differs from the new version, copy its content to ${TFENV_CONFIG_DIR}/version.prev
8. Write new version to ${TFENV_CONFIG_DIR}/version (the default version file)
9. Print confirmation: Switching default version to v${version}
10. If the default version file is overridden by a .terraform-version file in the search path, print warning: Default version file overridden by <path>, changing the default version has no effect

Previous Version (tfenv use -)

• Reads ${TFENV_CONFIG_DIR}/version.prev to get the last-used version
• Error if version.prev does not exist ("No previous version to switch to")
• Error if version.prev is empty
• Strips carriage returns from the file content (Windows compatibility)
• The version.prev file is updated on every successful use (including use -)

Version File Writing

• Write to ${TFENV_CONFIG_DIR}/version
• Atomic write: write to temp file, then rename
• File contains just the version number (e.g., 1.5.0\n)

Version Resolution for latest Keywords

When use is called with latest, latest:<regex>, etc., the resolution searches locally installed versions first (not remote). Remote is only consulted if TFENV_AUTO_INSTALL=true and no local match is found. This is different from install, which always checks remote. Reference: libexec/tfenv-use lines 112-140.

Acceptance Criteria

• tfenv use 1.5.0 sets the default version to 1.5.0
• tfenv use latest resolves and sets the latest installed version
• tfenv use latest:^1.5 resolves and sets the latest installed 1.5.x
• tfenv use latest-allowed resolves from HCL constraints
• tfenv use min-required resolves minimum from HCL constraints
• tfenv use - switches to the previous version
• tfenv use - errors clearly if no previous version exists
• tfenv use (no args) reads from .terraform-version or default version file or TFENV_TERRAFORM_VERSION
• Error if specified version is not installed (and auto-install is off)
• Auto-install triggers if version is missing and TFENV_AUTO_INSTALL=true
• Current version is saved to version.prev before overwriting
• version.prev is NOT written when the new version equals the current version
• Default version file is updated atomically
• Warning printed when .terraform-version overrides the default version file
• Terraform binary is verified present and executable before confirming switch
• Exit code 0 on success, non-zero on failure
• Confirmation message printed on success
• Acceptance tests verify version switching, file content, and use -
• Acceptance tests verify override warning

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 version file
• Depends on: Go Edition: Version resolution engine (latest, latest-allowed, min-required) #495 (Version resolution engine) — resolves keywords
• Depends on: Go Edition: Logging framework #491 (Logging)
• Soft dependency on: Go Edition: Install command #497 (Install command) — for auto-install integration

Implementation Notes

• Reference libexec/tfenv-use for the Bash implementation (190 lines including standalone boilerplate)
• Key Bash behaviours to match:
  • Lines 78-88: tfenv use - reads version.prev file
  • Lines 89-102: No-arg resolution from version file or TFENV_TERRAFORM_VERSION
  • Lines 161-168: Save current version to version.prev before overwriting
  • Lines 175-178: Override warning when .terraform-version overrides default
• The use command with latest keywords should filter against locally installed versions by default (not remote), unless the version needs to be installed
• The Bash edition writes a plain version file (not a symlink). The Go edition should do the same.
• Pre-release filtering: when latest is used with a numeric-only regex, exclude pre-release versions (containing -). When the regex contains letters, include pre-releases. Reference: libexec/tfenv-use lines 114-129.
• Issue After successfully installing a version it's not possible to use it ("should be impossible") #387 ("should be impossible" error after install) is relevant — ensure use works immediately after install
• Issue terraform not using tfenv used version #440 (terraform not using tfenv-used version) is relevant context

Labels

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

[Zordrak]

Claimed by developer. Dispatching to feature-implementer.