tfv 5.0.1 → 6.1.0

package/.github/workflows/publish.yml

@@ -2,27 +2,67 @@ name: Publish tfv to npm registry
 
 on:
   push:
-    branches: [main]
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'   # only trigger on semver tags: v6.0.0, v6.1.0, etc.
 
 permissions:
   contents: read
   id-token: write
 
 jobs:
-  publish:
+  verify-branch:
     runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Verify tag is on main branch
+        run: |
+          git fetch origin main
+          if ! git merge-base --is-ancestor ${{ github.sha }} origin/main; then
+            echo "Error: tags must only be pushed on commits that exist on the main branch."
+            exit 1
+          fi
 
+  test:
+    needs: verify-branch
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 22
+          cache: 'npm'
+
+      - run: npm ci
+
+      - run: npm test
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
           registry-url: https://registry.npmjs.org
           cache: 'npm'
 
       - run: npm ci
 
+      - name: Verify package version matches git tag
+        run: |
+          PKG_VERSION="v$(node -p "require('./package.json').version")"
+          GIT_TAG="${{ github.ref_name }}"
+          if [ "$PKG_VERSION" != "$GIT_TAG" ]; then
+            echo "Version mismatch: package.json=$PKG_VERSION, tag=$GIT_TAG"
+            exit 1
+          fi
+
       - run: npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -1,5 +1,6 @@
-# Use `tfv` to manage multiple versions of terraform with ease
+# tfv — Terraform & OpenTofu Version Manager for macOS, Linux & Windows
 
+```text
          _        ________        __
        _| |__   / _____|\ \      / /
       |_  ___\ | |___    \ \    / /
@@ -7,229 +8,359 @@
         | |___ | |         \ \/ /
         \______\_|          \__/
 
-        Happy terraforming 😍🥂!
-  ---------------------------------------
+        Happy terraforming! 😍🥂
+    ---------------------------------
+```
 
-## Installation
+`tfv` lets you install, switch, and manage multiple versions of **Terraform** and **OpenTofu** without `sudo`. All binaries live in `~/.tfv/` — upgrading `tfv` itself never wipes your installed versions.
 
-> **_NOTE:_** `tfv` should be installed `globally` so that it can be run from anywhere on your computer.
+![tfv demo](demo.gif)
+
+---
+
+## Installation
 
 ```sh
 npm install -g tfv
 ```
 
-Run with alias
+`tfv` automatically adds `~/.tfv/bin` to your PATH on install (shell configs + Windows User PATH). Restart your terminal once after install.
 
-```sh
-npm i -g tfv
-```
+---
 
-## Help
+## How it works
 
-```sh
-tfv --help
+```text
+npm install -g tfv
+       │
+       ▼
+postInstall.js
+  ├── creates ~/.tfv/bin/, ~/.tfv/store/, ~/.tfv/cache/
+  └── adds ~/.tfv/bin to PATH (shell configs / Windows registry)
+       │
+       ▼
+tfv install 1.9.0
+  ├── fetches version list  →  ~/.tfv/cache/terraform-versions.json  (1hr TTL)
+  ├── downloads zip         →  system temp dir  (with progress bar)
+  ├── verifies SHA256       →  HashiCorp / OpenTofu checksums
+  ├── extracts binary only  →  ~/.tfv/store/terraform/1.9.0
+  └── records arch          →  ~/.tfv/store/terraform/arch.json
+       │
+       ▼
+tfv use 1.9.0
+  ├── copies ~/.tfv/store/terraform/1.9.0  →  ~/.tfv/bin/terraform
+  └── writes active version  →  ~/.tfv/active.json
+
+       │
+       ▼
+terraform plan   ← resolves to ~/.tfv/bin/terraform  (same binary as tfv)
+tfv plan         ← spawns ~/.tfv/bin/terraform directly (no PATH lookup)
 ```
 
-Run with alias
-
-```sh
-tfv -h
+Both `terraform` and `tfv` commands always use the **exact same binary**.
+
+---
+
+## Store layout
+
+```text
+~/.tfv/
+  bin/
+    terraform          ← active terraform binary (no sudo, no symlinks)
+    tofu               ← active opentofu binary
+  store/
+    terraform/
+      1.9.0            ← installed versions (binary renamed to version number)
+      1.7.3
+      arch.json        ← { "1.9.0": "arm64", "1.7.3": "amd64" }
+    opentofu/
+      1.8.0
+      arch.json
+  cache/
+    terraform-versions.json   ← remote list cached for 1 hour
+    opentofu-versions.json
+  active.json          ← { "terraform": "1.9.0", "opentofu": null }
 ```
 
-> **_OUTPUT:_**
+---
 
-```
-tfv <command>
+## Commands
 
-Commands:
+### Install
 
-  tfv install <version> [option]  Install a terraform version [aliases: i]
+```sh
+tfv install latest                   # latest stable
+tfv install 1.9.0                    # exact version
+tfv install 1.9.^                    # latest 1.9.x patch
+tfv install 1.8.0-beta1              # explicit pre-release (warns you)
+tfv install latest --provider tofu   # OpenTofu
+tfv install 1.9.0 --arch amd64       # override architecture
+```
 
-  tfv list [option]               List installed or available terraform versions [aliases: ls]
+Aliases: `tfv i`
 
-  tfv remove <version>            Remove terraform versions from tfv store [aliases: rm]
+---
 
-  tfv auto-switch                 Auto-detect and switch to your project terraform version [aliases: as]
+### Switch version
 
-  tfv use <version>               Switch to a specified terraform version
+```sh
+tfv use 1.9.0
+tfv use latest                       # latest installed version
+tfv use 1.8.0 --provider tofu
+```
 
-  tfv apply                       Run terraform apply with optional file-based targets.
-  Accepts all terraform flags after --
-  Example:
-  tfv apply --file main.tf --file network.tf -- -auto-approve -target=<TARGET> -var="env=prod"
+No `sudo`. Copies binary to `~/.tfv/bin/terraform`.
 
-  tfv destroy                     Run terraform destroy with optional file-based targets.
-  Accepts all terraform flags after --
-  Example:
-  tfv destroy --file main.tf --file network.tf -- -auto-approve -target=<TARGET> -var="env=prod"
+---
 
-  tfv plan                        Run terraform plan with optional file-based targets.
-  Accepts all terraform flags after --
-  Example:
-  tfv plan --file main.tf --file network.tf -- -auto-approve -target=<TARGET> -var="env=prod"
+### Auto-switch
 
-Options:
-  -h, --help     Show help                                             [boolean]
-  -v, --version  Show version number                                   [boolean]
+Detects and switches to the version your project requires. Installs it if not already in store.
+
+```sh
+tfv auto-switch
+tfv as                               # alias
+tfv as --provider tofu
 ```
 
-# Usage
+Reads version from (in priority order):
 
-https://github.com/marcdomain/tfv/assets/25563661/fa44f0f2-2dca-4f22-9fea-c74e4b8f767c
+1. `.terraform-version` file in current directory
+2. `terraform.tfstate` → `terraform_version` field
+3. `required_version` in any `.tf` file — supports all constraint operators:
+   `=`, `>=`, `>`, `<=`, `<`, `!=`, `~>`, and compound `">= 1.3, < 2.0"`
 
-# Table of Contents
+---
 
-<!--ts-->
-* [Table of Contents](#table-of-contents)
-    * [Modules](#modules)
-      * [install](#install)
-      * [use](#use)
-      * [list](#list)
-      * [remove](#remove)
-      * [auto-switch](#auto-switch)
-      * [plan](#plan)
-      * [apply](#apply)
-      * [destroy](#destroy)
-<!--te-->
+### Shell hook — auto-switch on `cd`
 
-### Modules
+Wraps `cd` so that entering a directory automatically switches the terraform version — but **only if the directory looks like a terraform project**. Non-terraform folders have zero overhead (one filesystem check, no subprocess).
 
-- #### _INSTALL_
+A directory is considered a terraform project if it contains:
 
-| Version          | Description                                |
-| ---------------- | ------------------------------------------ |
-| x.x.x            | Installs terraform version x.x.x           |
-| x^               | Installs latest version of release x       |
-| x.x.^            | Installs latest version of release x.x     |
-| latest           | Installs latest version of terraform       |
+- a `.terraform-version` file, **or**
+- any `*.tf` files
 
 ```sh
-tfv install <version>
+cd ~/Downloads           # no .tf files → nothing happens
+cd ~/projects/react-app  # no .tf files → nothing happens
+cd ~/projects/infra      # has main.tf  → auto-switch runs silently
+cd ~/projects/platform   # has .terraform-version → auto-switch runs silently
 ```
 
-Run with option
+Setup (one-time, add to your shell config):
 
 ```sh
-tfv install <version> --arch <system-architecture>
-```
+# Bash
+printf '\neval "$(tfv shell-init bash)"\n' >> ~/.bashrc
 
-EXAMPLE:
+# Zsh
+printf '\neval "$(tfv shell-init zsh)"\n' >> ~/.zshrc
 
-```sh
-tfv install 1.5.7 -arch amd64
+# Fish
+printf '\ntfv shell-init fish | source\n' >> ~/.config/fish/config.fish
+
+# PowerShell
+Add-Content $PROFILE "`nInvoke-Expression (tfv shell-init powershell | Out-String)"
 ```
 
-> NOTE:  The default *system-architecture* is the architecture of your computer (arm64, amd64, x64, etc...)
+After setup, entering a terraform project switches the version automatically — no manual `tfv as` needed.
 
-- #### _USE_
+`shell-init` also installs **tab completions** for all `tfv` commands and installed versions. After running the setup command above, `tfv <tab>` will complete commands, `tfv use <tab>` will complete installed versions, and `tfv --provider <tab>` will complete provider names.
 
-| Version          | Description                               |
-| ---------------- | ----------------------------------------- |
-| x.x.x            | use terraform version x.x.x               |
-| latest           | use latest version of terraform           |
+---
+
+### List versions
 
 ```sh
-tfv use <version>
+tfv list                             # installed versions (default)
+tfv ls --remote                      # all available versions from HashiCorp
+tfv ls --remote --provider tofu      # all available OpenTofu versions
 ```
 
-> **_NOTE:_** You would get a password prompt. Accept it. This is a one-time request to set the terraform executable in your system path.
+Active version is marked with 🚀.
 
-- #### _LIST_
+---
 
-| Option         | Option Alias  |                Description                                                     |
-| ---------------|---------------|--------------------------------------------------------------------------------|
-|                |               |  Defaults to listing terraform versions installed locally (in tfv store)       |
-| `--local`      |  `-l`         |  Lists all terraform versions installed locally                                |
-| `--remote`     |  `-r`         |  Lists all terraform versions available remotely, on terraform server          |
+### Current version
 
 ```sh
-tfv list [option]
+tfv current                          # shows active version + PATH status
+tfv which                            # alias
+tfv current --provider tofu
 ```
 
-Run with alias
+Example output:
 
-```sh
-tfv ls [option]
+```text
+Active terraform version: 1.9.0
+Binary: /Users/you/.tfv/bin/terraform
+Reported: Terraform v1.9.0
+PATH OK — 'terraform' resolves to tfv-managed binary
 ```
 
-- #### _REMOVE_
+---
 
-Remove terraform versions managed by tfv
+### Pin version
+
+Writes a `.terraform-version` file in the current directory so teammates get the same version via `tfv auto-switch`:
 
 ```sh
-  tfv remove <versions>
+tfv pin                              # pin currently active version
+tfv pin 1.9.0                        # pin a specific version
+tfv pin --provider tofu
 ```
 
-Run with alias
+---
+
+### Upgrade
 
 ```sh
-  tfv rm <versions>
+tfv upgrade                          # upgrade active 1.6.3 → latest 1.6.x patch
+tfv upgrade 1.9                      # install + use latest 1.9.x
+tfv upgrade latest                   # install + use absolute latest
+tfv upgrade --provider tofu
 ```
 
-Example
+Also re-anchors `~/.tfv/bin` in PATH to ensure it takes precedence over any system-installed terraform.
+
+---
+
+### Remove
 
 ```sh
-  tfv rm x.y.z z.x.y
+tfv remove 1.7.3
+tfv rm 1.7.3 1.6.6                   # remove multiple
+tfv rm 1.8.0 --provider tofu
 ```
 
-- #### _AUTO-SWITCH_
+Warns if you're removing the currently active version.
 
-Auto-detects your project terraform version, downloads it if it's not in tfv store, and switch to the version
+---
 
-```sh
-  tfv auto-switch
-```
+### Prune
 
-Run with alias
+Remove all non-active versions at once to free disk space.
 
 ```sh
-  tfv as
+tfv prune                            # remove everything except the active version
+tfv prune --keep 2                   # keep the 2 most recent + the active version
+tfv prune --provider tofu
+tfv prune --yes                      # skip confirmation prompt
 ```
 
-- #### _PLAN_
+The active version is always kept regardless of `--keep`.
 
-Run terraform plan with optional file-based targets. Parses terraform files to extract resources, data sources, and modules as targets.
+---
 
-```sh
-  tfv plan --file main.tf
-```
+### Exec
 
-With multiple files
+Run a single command with a specific installed version **without** changing the active version. Useful for cross-version testing and CI.
 
 ```sh
-  tfv plan --file main.tf --file network.tf
+tfv exec 1.9.0 -- version
+tfv exec 1.8.0 -- plan -var="env=prod"
+tfv exec 1.7.3 --provider tofu -- validate
 ```
 
-With extra terraform flags
+Pass all terraform/tofu flags after `--`.
+
+---
+
+### Doctor
+
+Run a full health check: store directories, active binaries, PATH order, PATH conflicts, and shell config.
 
 ```sh
-  tfv plan --file main.tf -- -var="env=prod" -out=plan.out
+tfv doctor
 ```
 
-- #### _APPLY_
+Example output:
 
-Run terraform apply with optional file-based targets.
+```text
+tfv doctor
 
-```sh
-  tfv apply --file main.tf
+Store
+  ✔  ~/.tfv/store/terraform/ exists
+  ✔  ~/.tfv/store/opentofu/ exists
+
+Active versions
+  ✔  terraform: active version is 1.9.0
+  ✔  terraform: binary exists
+  ✔  terraform: executes  (Terraform v1.9.0)
+  –  tofu: not set up (no versions installed)
+
+PATH
+  ✔  ~/.tfv/bin is in PATH
+  ✔  ~/.tfv/bin precedes system dirs in PATH
+  ✔  'terraform' resolves to tfv-managed binary
+  ✔  PATH block found in shell config (~/.zshrc)
+
+Cache
+  ✔  terraform version cache exists
+  –  opentofu version cache not yet created
+
+All checks passed. tfv is healthy.
 ```
 
-With auto-approve
+Exits with code 1 if any issue is found.
+
+---
+
+### Terraform commands (via tfv)
+
+All commands use the tfv-managed binary and accept extra terraform flags after `--`:
 
 ```sh
-  tfv apply --file main.tf -- -auto-approve
+tfv init
+tfv validate
+tfv fmt
+tfv fmt -- -recursive
+
+tfv plan
+tfv plan --file main.tf                        # extract targets from file
+tfv plan --file main.tf --file network.tf      # multiple files
+tfv plan --file main.tf -- -var="env=prod"     # with extra terraform flags
+
+tfv apply --file main.tf -- -auto-approve
+tfv destroy --file main.tf -- -auto-approve
 ```
 
-- #### _DESTROY_
+`--file` parses `.tf` files and auto-generates `-target` flags for every `resource`, `data`, and `module` block found. Comments are stripped before parsing.
+
+All commands support `--provider tofu` to use OpenTofu instead.
+
+---
 
-Run terraform destroy with optional file-based targets.
+## OpenTofu support
+
+Every command works with OpenTofu via `--provider tofu` (or `--provider opentofu`):
 
 ```sh
-  tfv destroy --file main.tf
+tfv install latest --provider tofu
+tfv use 1.8.0 --provider tofu
+tfv list --remote --provider tofu
+tfv current --provider tofu
+tfv plan --provider tofu
 ```
 
-With auto-approve
+OpenTofu binaries are stored separately from Terraform in `~/.tfv/store/opentofu/` and activated as `~/.tfv/bin/tofu`.
+
+---
+
+## Windows support
+
+Everything works on Windows without administrator privileges:
+
+- Store: `%USERPROFILE%\.tfv\`
+- PATH: updated via `[Environment]::SetEnvironmentVariable("PATH", ..., "User")` (User scope, no admin)
+- Shell hooks: PowerShell profile integration via `tfv shell-init powershell`
+
+---
+
+## Help
 
 ```sh
-  tfv destroy --file main.tf -- -auto-approve
+tfv --help
+tfv <command> --help
 ```