Go Edition: Pin command

[Zordrak]

Summary

Implement the tfenv pin command for the Go edition — writing a .terraform-version file in the current directory.

Parent Epic

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

Motivation

tfenv pin provides a convenient way to create a .terraform-version file in the current directory, pinning the project to the currently active Terraform version. This is a simple but useful workflow command.

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 pin

Pin Flow

1. Validate: no arguments accepted — tfenv pin takes no args (error if any given)
2. Validate: ${TFENV_CONFIG_DIR}/versions/ directory must exist and be accessible
3. Resolve the currently active version via tfenv-version-name (version-name resolution chain)
4. Write that version string to .terraform-version in the current working directory
5. Print confirmation: Pinned version by writing "${version}" to ${PWD}/.terraform-version

Output Format

The .terraform-version file contains the version string followed by a newline:

1.5.0

This is produced by echo "${version_name}" > .terraform-version in Bash, which appends a newline.

Error Cases

• Arguments given → usage: tfenv pin error, exit non-zero
• No versions directory → No versions available. Please install one with: tfenv install
• Versions directory inaccessible → tfenv versions directory is inaccessible: ${path}
• No version resolvable → error from version-name resolution (no version file, no default)

Acceptance Criteria

• tfenv pin creates .terraform-version in the current directory
• File contains the currently active version number followed by a newline
• tfenv pin with arguments prints usage error and exits non-zero
• Error if no versions installed (versions/ directory missing)
• Error if versions directory is inaccessible
• Error if no version is currently resolvable
• Overwrites existing .terraform-version if present
• Exit code 0 on success, non-zero on failure
• Confirmation message includes the version and file path
• Acceptance test verifies file creation, content, and error cases

Dependencies

• Depends on: Go Edition: Module scaffolding, CLI framework & multi-call entry point #489 (Go module scaffolding / CLI framework)
• Depends on: Go Edition: Version file resolution (.terraform-version walk) #493 (Version file resolution) — needs to resolve current version
• Depends on: Go Edition: Logging framework #491 (Logging)

Implementation Notes

• Reference libexec/tfenv-pin — only ~20 lines of logic after standalone boilerplate
• Key Bash behaviours to match:
  • Line 65: No arguments accepted
  • Lines 67-68: Versions directory must exist
  • Lines 70-71: Versions directory must be accessible
  • Lines 73-74: Resolve version via tfenv-version-name
  • Line 76: Write to .terraform-version in current directory
  • Line 77: Confirmation message with version and path
• This is one of the simplest commands — implementation should be straightforward
• Ensure the written file matches the Bash edition's format exactly (for cross-edition compatibility)
• The version resolved by tfenv-version-name may be a keyword like latest if that's what the version file says — pin writes the RESOLVED concrete version, not the keyword

Labels

type:feature, priority:high, complexity:trivial

[Zordrak]

Claimed by developer. Dispatching to feature-implementer.

[Zordrak]

Claimed by feature-implementer. Working on this.