add v2 modularization CI gates, release workflow, and runbook

Five gate scripts (acyclic deps, single source, SIV placement, no replaces, release-mode build), a checks workflow, a manual lockstep release workflow, and the release runbook. Structural gates skip until the /v2 submodules exist, so they land green now and enforce automatically once the split arrives.

Author: james00012

.github/workflows/v2-checks.yml

@@ -0,0 +1,54 @@
+name: v2 Modularization Checks
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  acyclic-deps:
+    name: Acyclic dependency graph
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: bash scripts/check-acyclic-deps.sh
+
+  single-source:
+    name: Single source of truth per package path
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: bash scripts/check-single-source.sh
+
+  siv-placement:
+    name: /v2 SIV placement
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: bash scripts/check-siv-placement.sh
+
+  consumer-simulation:
+    name: External consumer simulation (GOWORK=off)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up mise
+        uses: jdx/mise-action@v3
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Release-mode build (all 16 modules pin + external consumer, GOWORK=off)
+        run: bash scripts/check-release-mode.sh
+
+  release-prep-guard:
+    name: No local terratest replaces (release commits only)
+    runs-on: ubuntu-latest
+    if: |
+      startsWith(github.ref, 'refs/tags/modules/') ||
+      contains(github.event.head_commit.message, '[release-prep]')
+    steps:
+      - uses: actions/checkout@v4
+      - run: bash scripts/check-no-replaces.sh

.github/workflows/v2-release.yml

@@ -0,0 +1,108 @@
+name: v2 Release (lockstep tag push)
+
+# Manual-trigger workflow that pushes the full v2 tag set from a release-prep commit.
+# Procedure documented in docs/v2-release-runbook.md.
+#
+# Use this AFTER:
+#   - scripts/release-prep.sh ran on the release-prep branch
+#   - The release-prep commit was reviewed and approved
+#   - check-no-replaces.sh passes on that commit
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to tag (e.g. v2.0.0-beta.1). Applied to every submodule.'
+        required: true
+        type: string
+      commit_sha:
+        description: 'SHA of the release-prep commit to tag.'
+        required: true
+        type: string
+      dry_run:
+        description: 'If true, print the tag commands without pushing.'
+        required: false
+        type: boolean
+        default: true
+
+permissions:
+  contents: write
+
+jobs:
+  verify:
+    name: Pre-flight checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.commit_sha }}
+      - run: bash scripts/check-no-replaces.sh
+      - run: bash scripts/check-acyclic-deps.sh
+      - run: bash scripts/check-single-source.sh
+      - run: bash scripts/check-siv-placement.sh
+
+  tag-and-push:
+    name: Push lockstep tags
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.commit_sha }}
+          fetch-depth: 0
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Tag in dependency order
+        env:
+          VERSION: ${{ inputs.version }}
+          DRY_RUN: ${{ inputs.dry_run }}
+        run: |
+          set -e
+
+          # Same order as docs/v2-release-runbook.md.
+          ORDER=(
+            modules/core
+            modules/ssh modules/httphelper modules/dnshelper
+            modules/docker modules/packer modules/database modules/opa
+            modules/aws modules/azure modules/gcp modules/k8s modules/helm
+            modules/terraform modules/terragrunt modules/teststructure
+           
+          )
+
+          for path in "${ORDER[@]}"; do
+            tag="${path}/v2/${VERSION}"
+            if [ "$DRY_RUN" = "true" ]; then
+              echo "DRY-RUN would tag: $tag"
+            else
+              git tag -a "$tag" -m "v2 lockstep release $VERSION"
+              git push origin "$tag"
+              echo "pushed $tag"
+            fi
+          done
+
+      - name: Verify proxy serves each tag
+        if: ${{ inputs.dry_run == false }}
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          # Allow the proxy a moment to populate after push.
+          sleep 30
+          fail=0
+          for path in modules/core modules/ssh modules/httphelper modules/dnshelper modules/docker modules/packer modules/database modules/opa modules/aws modules/azure modules/gcp modules/k8s modules/helm modules/terraform modules/terragrunt modules/teststructure; do
+            url="https://proxy.golang.org/github.com/gruntwork-io/terratest/${path}/v2/@v/${VERSION}.info"
+            code=$(curl -s -o /dev/null -w '%{http_code}' "$url")
+            if [ "$code" = "200" ]; then
+              echo "  $path: 200"
+            else
+              echo "::error::$path: $code from $url"
+              fail=1
+            fi
+          done
+          if [ "$fail" -ne 0 ]; then
+            echo "::error::Proxy verification failed. Some tags may need a few minutes; retry the verify step manually if so."
+            exit 1
+          fi

docs/v2-release-runbook.md

@@ -0,0 +1,86 @@
+# Terratest v2 Release Runbook
+
+How to cut a coordinated release of the v2 submodules. Read this before tagging.
+
+## Layout
+
+v2 is split into per-domain modules under `modules/<name>/`, each declaring
+`module github.com/gruntwork-io/terratest/modules/<name>/v2`. Local development
+uses the root `go.work`, which resolves every submodule to its local tree, so the
+submodule `go.mod` files do not need internal `require` lines or `replace`
+directives during normal development.
+
+## Why pinning is a release-time step (do not commit it early)
+
+The submodules' `go.mod` files are deliberately left without cross-module
+`require` lines on `main`. Pinning a sibling `require` to the to-be-published
+version (e.g. `core/v2 v2.0.0-beta.1`) BREAKS the workspace build until that tag
+actually exists: `go.work` does not shadow an unpublished required version, so
+`go build` and `go work sync` try to fetch the missing revision and fail. The pin
+must therefore happen on a short-lived release-prep branch, immediately before the
+tags are pushed, never on the modularization PR.
+
+CI validates the release-mode build continuously without committing the pin: the
+`GOWORK=off` check generates the pinned state with throwaway `replace` directives,
+builds a consumer, and discards it (see `scripts/`).
+
+## Pre-flight (on a release-prep branch)
+
+1. Choose the version, e.g. `v2.0.0-beta.1`.
+2. Pin each module, in dependency order (core first, then helpers, tooling,
+   platforms, k8s/helm, IaC). For each module:
+   - Add a temporary `replace` for EVERY sibling it transitively needs, not just
+     its direct imports. Tidy follows transitive edges, so a partial replace set
+     fails with `unknown revision` on a deeper sibling.
+   - Seed the module with the root `go.mod`'s exact dependency versions before
+     tidying (copy its `require` lines in). Otherwise tidy floats deps to the
+     latest compatible release and you get silent version drift, e.g. the Azure
+     SDK advancing to a release that drops a symbol the code uses
+     (`undefined: armmonitor.DiagnosticSettingsClient`). The code is tested
+     against the root's pinned versions; the submodules must inherit them.
+   - `GOWORK=off go mod tidy` to populate external `require`s and `go.sum`.
+
+`scripts/check-release-mode.sh` performs this exact pin (transitive replaces +
+root-version seeding + an all-module external consumer build under `GOWORK=off`)
+in a throwaway and reverts it, and runs in CI on every PR so the release-mode
+build is validated continuously without committing the pin or needing tags.
+3. Set every internal `require` to the exact version being tagged, then DROP all
+   internal `replace` directives. Do not run `go work sync` against the unpinned
+   tree.
+4. CI guard: `grep -nH '^replace github.com/gruntwork-io/terratest' modules/*/go.mod`
+   must return zero before tagging.
+5. Move `test/` to its own module here too if not already done, and pin it the
+   same way (it is test-only, so committed `replace`s are acceptable for it).
+
+## Tag push order
+
+All tags point at the same release commit. Each tag name puts the `/v2` SIV in the
+tag itself: `modules/<name>/v2/<version>` (NOT `modules/<name>/<version>`, which
+the proxy cannot associate with the `/v2` module path). Push in dependency order:
+
+1. `modules/core/v2/v2.0.0-beta.1`
+2. helpers: `ssh`, `httphelper`, `dnshelper`
+3. tooling: `docker`, `packer`, `database`, `opa`
+4. platforms: `aws`, `azure`, `gcp`, then `k8s`, `helm`
+5. IaC: `terraform`, `terragrunt`, `teststructure`
+
+After each tier, probe the proxy before continuing:
+`curl -o /dev/null -w '%{http_code}' https://proxy.golang.org/github.com/gruntwork-io/terratest/modules/<name>/v2/@v/<version>.info`
+should return 200.
+
+## Verify
+
+Run the `test-external/` consumer against the published tags with `GOWORK=off`. A
+clean external consumer should resolve, build, and test green with zero local
+references.
+
+## If a tag is wrong
+
+Proxy tags are immutable. Recover by cutting the next patch (`v2.0.0-beta.2`),
+never by editing in place. The pre-flight checks exist to keep this rare.
+
+## Beta to GA
+
+After the beta soaks (suggested two weeks minimum), repeat the same procedure at
+`v2.0.0` with no suffix: same release commit shape, same tag sequence, same proxy
+verification, then announce.

scripts/check-acyclic-deps.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# check-acyclic-deps.sh — fails CI if any submodule's production code imports a
+# module from a strictly higher tier. Enforces the v2 layering rule:
+# core → helpers → tooling → platforms → IaC, downward-only.
+#
+# Test files (*_test.go) are excluded; cross-module test-only imports are allowed
+# (e.g. modules/core/logger/parser_test imports modules/shell/v2 — legal per the
+# RFC's external _test package rule).
+
+set -uo pipefail
+
+# Tier assignment. Lower number = lower layer.
+declare -A TIER=(
+  [core]=0
+  [ssh]=1
+  [httphelper]=1
+  [dnshelper]=1
+  [docker]=2
+  [packer]=2
+  [database]=2
+  [opa]=2
+  [aws]=3
+  [azure]=3
+  [gcp]=3
+  [k8s]=3
+  [helm]=3
+  [terraform]=4
+  [terragrunt]=4
+  [teststructure]=4
+)
+
+# Pre-split guard: the tier rule only holds once packages are relocated into
+# their /v2 submodules. Until then the flat tree has no tiers to enforce.
+if ! ls modules/*/go.mod >/dev/null 2>&1; then
+  echo "acyclic-deps check: skipped (no /v2 submodules present yet)"
+  exit 0
+fi
+
+fail=0
+
+for dir in modules/*/; do
+  importer=$(basename "$dir")
+  importer_tier="${TIER[$importer]:-99}"
+
+  # Scan all .go files in the submodule recursively, excluding test files.
+  while IFS= read -r gofile; do
+    while IFS= read -r importee; do
+      [ -z "$importee" ] && continue
+      importee_tier="${TIER[$importee]:-99}"
+      if [ "$importee_tier" -gt "$importer_tier" ]; then
+        echo "::error file=${gofile}::tier violation — $importer (tier $importer_tier) imports $importee (tier $importee_tier)"
+        fail=1
+      fi
+    done < <(grep -oE '"github\.com/gruntwork-io/terratest/modules/[a-z][a-z0-9-]*' "$gofile" 2>/dev/null \
+      | awk -F'/' '{print $NF}' \
+      | sort -u)
+  done < <(find "$dir" -name '*.go' -not -name '*_test.go' 2>/dev/null)
+done
+
+if [ "$fail" -ne 0 ]; then
+  echo "::error::Tier-violation imports detected. Imports must flow downward only."
+  exit 1
+fi
+
+echo "acyclic-deps check: OK"

scripts/check-no-replaces.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# check-no-replaces.sh — fails the build if a release commit still contains local
+# `replace github.com/gruntwork-io/terratest/...` directives. Required before
+# tagging the lockstep release.
+#
+# Invoked only when the workflow runs in "release-prep" mode (controlled by a
+# CI env var or a manual workflow_dispatch). Dev branches keep their replaces.
+
+set -euo pipefail
+
+matches=$(grep -nH '^replace github.com/gruntwork-io/terratest' modules/*/go.mod cmd/*/go.mod 2>/dev/null || true)
+
+if [ -n "$matches" ]; then
+  echo "::error::Local terratest replace directives present in release commit:"
+  echo "$matches" | sed 's/^/    /'
+  echo "::error::Strip them before tagging (see docs/v2-release-runbook.md)."
+  exit 1
+fi
+
+echo "no-replaces check: OK"

scripts/check-release-mode.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# check-release-mode.sh — validates the v2 modules build in release mode
+# (GOWORK=off) WITHOUT needing published tags.
+#
+# For each module it: (1) adds throwaway internal `replace`s for every sibling,
+# (2) seeds the module with the ROOT go.mod's exact dependency versions so naive
+# tidy cannot float a dep to an incompatible newer release, then (3) tidies.
+# Finally it builds an external consumer that imports every module. All changes
+# are reverted on exit; nothing is committed.
+set -uo pipefail
+cd "$(git rev-parse --show-toplevel)"
+export GOFLAGS="${GOFLAGS:--tags=aws,azure,azure_ci_excluded,azureslim,compute,gcp,helm,kubeall,kubernetes,network}"
+B="github.com/gruntwork-io/terratest/modules"
+ORDER="core ssh httphelper dnshelper docker packer database opa aws azure gcp k8s helm terraform terragrunt teststructure"
+
+# Pre-split guard: until the /v2 submodules exist, there is nothing to validate.
+# This lets the gate land and run green before the modularization commit, and do
+# the real release-mode build afterward.
+if ! ls modules/*/go.mod >/dev/null 2>&1; then
+  echo "release-mode check: skipped (no /v2 submodules present yet)"
+  exit 0
+fi
+
+cleanup() {
+  git checkout -- modules/ go.work.sum >/dev/null 2>&1 || true
+  git status --porcelain 2>/dev/null | awk '/^\?\?.*modules\/.*\/go\.sum$/{print $2}' | xargs -r rm -f
+  [ -n "${TMP:-}" ] && rm -rf "$TMP"
+}
+trap cleanup EXIT
+
+# Exact dependency versions the code is tested against, from the root module.
+REQARGS=$(go mod edit -json go.mod | jq -r '.Require[]? | "-require=\(.Path)@\(.Version)"' | tr '\n' ' ')
+
+fail=0
+for m in $ORDER; do
+  ( cd "modules/$m"
+    for s in $ORDER; do [ "$s" = "$m" ] || go mod edit -replace="$B/$s/v2=../$s"; done
+    # shellcheck disable=SC2086
+    go mod edit $REQARGS
+    GOWORK=off go mod tidy ) 2>/tmp/cr_$m.err || { echo "::error::release-mode tidy failed: modules/$m"; tail -4 /tmp/cr_$m.err; fail=1; }
+done
+[ "$fail" -ne 0 ] && { echo "release-mode check: FAILED (per-module pin)"; exit 1; }
+
+TMP=$(mktemp -d)
+{ echo "module releasecheckconsumer"; echo "go 1.26"; } > "$TMP/go.mod"
+for s in $ORDER; do
+  go mod edit -modfile="$TMP/go.mod" -require="$B/$s/v2@v2.0.0" -replace="$B/$s/v2=$(pwd)/modules/$s"
+done
+{
+  echo "package main"; echo "import ("
+  echo "  _ \"$B/core/v2/random\""; echo "  _ \"$B/core/v2/files\""; echo "  _ \"$B/core/v2/collections\""; echo "  _ \"$B/core/v2/formatting\""
+  for s in ssh httphelper dnshelper docker packer database opa aws azure gcp k8s helm terraform terragrunt teststructure; do echo "  _ \"$B/$s/v2\""; done
+  echo ")"; echo "func main() {}"
+} > "$TMP/main.go"
+( cd "$TMP" && GOWORK=off go mod tidy && GOWORK=off go build ./... ) 2>/tmp/cr_consumer.err \
+  || { echo "::error::external consumer failed to build in release mode"; tail -10 /tmp/cr_consumer.err; echo "release-mode check: FAILED (consumer)"; exit 1; }
+
+echo "release-mode check: OK (all 16 modules pin at root versions + external consumer builds with GOWORK=off)"