tfv 5.0.0 → 6.0.0

package/.github/workflows/publish.yml

@@ -2,27 +2,51 @@ 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:
+  test:
     runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          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: 18
+          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
 
+```
          _        ________        __
        _| |__   / _____|\ \      / /
       |_  ___\ | |___    \ \    / /
@@ -7,226 +8,286 @@
         | |___ | |         \ \/ /
         \______\_|          \__/
 
-        Happy terraforming 😍🥂!
-  ---------------------------------------
+        Happy terraforming! 😍🥂
+    ---------------------------------
+```
+
+`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.
 
-## Installation
+![tfv demo](demo.gif)
 
-> **_NOTE:_** `tfv` should be installed `globally` so that it can be run from anywhere on your computer.
+---
+
+## 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
+```
+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
+Both `terraform` and `tfv` commands always use the **exact same binary**.
 
-```sh
-tfv -h
-```
+---
 
-> **_OUTPUT:_**
+## Store layout
 
 ```
-tfv <command>
+~/.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 }
+```
 
-Commands:
+---
 
-  tfv install <version> [option]  Install a terraform version [aliases: i]
+## Commands
 
-  tfv list [option]               List installed or available terraform versions [aliases: ls]
+### Install
 
-  tfv remove <version>            Remove terraform versions from tfv store [aliases: rm]
+```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 auto-switch                 Auto-detect and switch to your project terraform version [aliases: as]
+Aliases: `tfv i`
 
-  tfv use <version>               Switch to a specified terraform version
+---
 
-  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"
+### Switch version
 
-  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"
+```sh
+tfv use 1.9.0
+tfv use latest                       # latest installed version
+tfv use 1.8.0 --provider tofu
+```
 
-  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"
+No `sudo`. Copies binary to `~/.tfv/bin/terraform`.
 
-Options:
-  -h, --help     Show help                                             [boolean]
-  -v, --version  Show version number                                   [boolean]
-```
+---
 
-# Usage
+### Auto-switch
 
-https://github.com/marcdomain/tfv/assets/25563661/fa44f0f2-2dca-4f22-9fea-c74e4b8f767c
+Detects and switches to the version your project requires. Installs it if not already in store.
 
-# Table of Contents
+```sh
+tfv auto-switch
+tfv as                               # alias
+tfv as --provider tofu
+```
 
-<!--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-->
+Reads version from (in priority order):
 
-### Modules
+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"`
 
-- #### _INSTALL_
+---
 
-| 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       |
+### Shell hook — auto-switch on `cd`
 
-```sh
-tfv install <version>
-```
+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).
 
-Run with option
+A directory is considered a terraform project if it contains:
+- a `.terraform-version` file, **or**
+- any `*.tf` files
 
 ```sh
-tfv install <version> --arch <system-architecture>
+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
 ```
 
-EXAMPLE:
+Setup (one-time, add to your shell config):
 
 ```sh
-tfv install 1.5.7 -arch amd64
-```
-
-> NOTE:  The default *system-architecture* is the architecture of your computer (arm64, amd64, x64, etc...)
+# Bash
+echo 'eval "$(tfv shell-init bash)"' >> ~/.bashrc
 
-- #### _USE_
+# Zsh
+echo 'eval "$(tfv shell-init zsh)"' >> ~/.zshrc
 
-| Version          | Description                               |
-| ---------------- | ----------------------------------------- |
-| x.x.x            | use terraform version x.x.x               |
-| latest           | use latest version of terraform           |
+# Fish
+echo 'tfv shell-init fish | source' >> ~/.config/fish/config.fish
 
-```sh
-tfv use <version>
+# PowerShell
+echo 'Invoke-Expression (tfv shell-init powershell | Out-String)' >> $PROFILE
 ```
 
-> **_NOTE:_** You would get a password prompt. Accept it. This is a one-time request to set the terraform executable in your system path.
+After setup, entering a terraform project switches the version automatically — no manual `tfv as` needed.
 
-- #### _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          |
+### List versions
 
 ```sh
-tfv list [option]
+tfv list                             # installed versions (default)
+tfv ls --remote                      # all available versions from HashiCorp
+tfv ls --remote --provider tofu      # all available OpenTofu versions
 ```
 
-Run with alias
+Active version is marked with 🚀.
 
-```sh
-tfv ls [option]
-```
-
-- #### _REMOVE_
+---
 
-Remove terraform versions managed by tfv
+### Current version
 
 ```sh
-  tfv remove <versions>
+tfv current                          # shows active version + PATH status
+tfv which                            # alias
+tfv current --provider tofu
 ```
 
-Run with alias
-
-```sh
-  tfv rm <versions>
+Example output:
+```
+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
 ```
 
-Example
+---
+
+### Pin version
+
+Writes a `.terraform-version` file in the current directory so teammates get the same version via `tfv auto-switch`:
 
 ```sh
-  tfv rm x.y.z z.x.y
+tfv pin                              # pin currently active version
+tfv pin 1.9.0                        # pin a specific version
+tfv pin --provider tofu
 ```
 
-- #### _AUTO-SWITCH_
+---
 
-Auto-detects your project terraform version, downloads it if it's not in tfv store, and switch to the version
+### Upgrade
 
 ```sh
-  tfv auto-switch
+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
 ```
 
-Run with alias
+Also re-anchors `~/.tfv/bin` in PATH to ensure it takes precedence over any system-installed terraform.
+
+---
+
+### Remove
 
 ```sh
-  tfv as
+tfv remove 1.7.3
+tfv rm 1.7.3 1.6.6                   # remove multiple
+tfv rm 1.8.0 --provider tofu
 ```
 
-- #### _PLAN_
+Warns if you're removing the currently active version.
 
-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
-```
+### Terraform commands (via tfv)
 
-With multiple files
+All commands use the tfv-managed binary and accept extra terraform flags after `--`:
 
 ```sh
-  tfv plan --file main.tf --file network.tf
+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
 ```
 
-With extra terraform flags
+`--file` parses `.tf` files and auto-generates `-target` flags for every `resource`, `data`, and `module` block found. Comments are stripped before parsing.
 
-```sh
-  tfv plan --file main.tf -- -var="env=prod" -out=plan.out
-```
+All commands support `--provider tofu` to use OpenTofu instead.
+
+---
 
-- #### _APPLY_
+## OpenTofu support
 
-Run terraform apply with optional file-based targets.
+Every command works with OpenTofu via `--provider tofu` (or `--provider opentofu`):
 
 ```sh
-  tfv apply --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`.
 
-```sh
-  tfv apply --file main.tf -- -auto-approve
-```
+---
 
-- #### _DESTROY_
+## Windows support
 
-Run terraform destroy with optional file-based targets.
+Everything works on Windows without administrator privileges:
 
-```sh
-  tfv destroy --file main.tf
-```
+- Store: `%USERPROFILE%\.tfv\`
+- PATH: updated via `[Environment]::SetEnvironmentVariable("PATH", ..., "User")` (User scope, no admin)
+- Shell hooks: PowerShell profile integration via `tfv shell-init powershell`
 
-With auto-approve
+---
+
+## Help
 
 ```sh
-  tfv destroy --file main.tf -- -auto-approve
+tfv --help
+tfv <command> --help
 ```