TF Switcher

A VS Code extension that selects an exact Terraform version per workspace, reuses it from a local cache or downloads it from HashiCorp, verifies it, and prepends its directory to PATH for new or relaunched VS Code terminals only. It never modifies the machine-wide PATH.

What it does

• Status bar item → sidebar. A bottom-left status item opens the TF Switcher sidebar.
• Pick a version three ways:
  • From the Available versions dropdown (recent stable releases from HashiCorp's official Releases API, filtered to your OS/architecture, alpha/beta/rc excluded).
  • By clicking Use on a version already in the cache (no download).
  • By typing an exact version (e.g. 1.16.1) as a fallback.
• Downloads are verified. The ZIP's SHA-256 is checked against HashiCorp's published SHA256SUMS, and the extracted executable is run to confirm its version before it is installed. Extraction uses a temporary file + atomic rename, so a partial binary can never appear valid.
• Workspace-aware. The sidebar reads the workspace's required_version constraint and tells you when the active version satisfies it — or offers a one-click switch to a version that does.
• Terminal scoping. The selected version applies to new/relaunched terminals only. "Use System Terraform" restores normal PATH behavior. Terminals and shells outside VS Code are never affected.

The cache

Terraform binaries live in a cache folder with this layout:

<cache-root>\<version>\<os>_<architecture>\terraform(.exe)

For example: <cache-root>\1.9.8\windows_amd64\terraform.exe

• Default location: VS Code's per-extension global storage (globalStorageUri\versions).
• Custom location: choose any folder with Choose Cache Folder. The choice is remembered. Use Use Default Cache to go back.

Changing the cache folder does not move versions. Existing binaries stay in the previous cache; the new folder starts empty. The sidebar's cached list always reflects the currently selected cache folder, is refreshed automatically when files change on disk, and offers a manual Refresh.

Workspace version requirements (required_version)

When a .tf file in the workspace declares:

terraform {
  required_version = ">= 1.5.0, < 2.0.0"
}

the sidebar shows a banner:

• Green when the active version satisfies the constraint.
• Yellow with a Use button when it doesn't (or none is active), suggesting the newest cached-or-downloadable version that matches.

Supported operators: =, !=, >, >=, <, <=, and the pessimistic ~> (~> 1.9.0 allows >= 1.9.0, < 1.10.0; ~> 1.9 allows >= 1.9.0, < 2.0.0). Clauses are combined with AND.

Multiple root modules (multi-root workspaces)

Design decision — see "Roadmap" below. When a workspace contains several Terraform root modules with different constraints, the extension evaluates each workspace folder separately. Within a folder that declares several constraints across its .tf files, all clauses are combined (most restrictive wins).

Offline behavior

• Cached binaries always work offline.
• Manual exact-version entry always works offline.
• The release list is cached (in memory and across restarts) for 6 hours, so the dropdown keeps working offline after the first successful fetch. When offline with no prior fetch, the dropdown shows an "Offline" entry and manual entry is the fallback.

Commands

Developing

cd extension
npm install
npm run compile   # type-check + emit to out/
npm test          # compile + run unit tests (node --test)

Press F5 to launch the Extension Development Host against the test-workspace fixture folder.

If the dev host crashes on launch, a stale/partial out/ is usually the cause: run the "Compile extension" task (or npm run compile), let it finish, then F5 again.

Roadmap

• Per-folder version activation in multi-root workspaces (the scan and banner are already per-folder; activation is currently global).
• Signature verification of SHA256SUMS against HashiCorp's GPG key.
• Watch-mode build task to make F5 launches race-free.