Add Terraform module for multi-environment deployments

CHANGELOG.md

@@ -1,3 +1,18 @@
+## [2.2.0] - 2025-12-15
+
+### Added
+- **Terraform module**: New workflow automation for multi-environment Terraform deployments
+  - `tf_run` function for executing terraform commands with automatic shared vars inclusion
+  - `tf_build_chdir`, `tf_build_var_file`, `tf_is_auto_approve_env` helper functions
+  - Pattern targets: `terraform/init/%`, `terraform/plan/%`, `terraform/apply/%`, `terraform/destroy/%`, `terraform/validate/%`, `terraform/output/%`, `terraform/state/list/%`, `terraform/refresh/%`
+  - Utility targets: `terraform/fmt`, `terraform/fmt/check`, `terraform/version`
+  - Configuration: `tf_bin`, `tf_root_dir`, `tf_env_dir`, `tf_shared_vars` (multi-file support), `tf_auto_approve_envs`, `tf_destroy_confirm`, `tf_chdir_flag`
+  - Comprehensive test suite (15 tests, 36 assertions)
+- **LocalStack module enhancements**:
+  - `localstack/s3/ls` target with optional `bucket=` parameter
+  - `localstack/sqs/ls` target for listing queues
+  - Comprehensive test suite (11 tests, 26 assertions)
+
 ## [2.1.1] - 2025-12-10
 
 ### Changed

CLAUDE.md

@@ -319,10 +319,18 @@ Before writing module code, review `main.mk` for active settings:
 - `.SECONDEXPANSION:` - enables `$$@` and `$$*` in prerequisites for dynamic expansion
 
 ### Changelog
-When making significant changes, update `CHANGELOG.md`:
+**IMPORTANT**: When making significant changes, you MUST update `CHANGELOG.md`. This includes:
+- New modules
+- New features or targets
+- Breaking changes
+- Bug fixes
+
+Rules:
 - Follow [Keep a Changelog](https://keepachangelog.com/) format
 - Group changes under: Added, Changed, Deprecated, Removed, Fixed, Security
 - Include version number and date for releases
+- Bump minor version (e.g., 2.1.0 → 2.2.0) for new features/modules
+- Bump patch version (e.g., 2.1.0 → 2.1.1) for bug fixes
 
 ### Trello Board
 **Board ID: `vBmmD6it`** - Must be set at the start of each session using `mcp__trello__set_active_board`.

modules/infrastructure/terraform/mod_config.mk

@@ -0,0 +1,64 @@
+#####################################################################################
+# Terraform Module Configuration
+#####################################################################################
+
+## @var tf_bin
+## @desc Path to terraform binary
+## @type string
+## @default terraform
+## @group terraform
+tf_bin ?= terraform
+
+## @var tf_root_dir
+## @desc Root terraform directory (for fmt, validate operations)
+## @type string
+## @default terraform
+## @group terraform
+tf_root_dir ?= terraform
+
+## @var tf_env_dir
+## @desc Environment directory relative to project root
+## @type string
+## @default terraform/environments
+## @group terraform
+## @example tf_env_dir=infra/envs make terraform/plan/dev
+tf_env_dir ?= terraform/environments
+
+## @var tf_shared_vars
+## @desc Shared tfvars file paths, space-delimited (relative to environment directory)
+## @desc For paths with spaces, use mb_space_guard: $(call mb_space_guard,path with spaces/file.tfvars)
+## @type string
+## @default (empty - no shared vars)
+## @group terraform
+## @example tf_shared_vars=../../shared/common.tfvars
+## @example tf_shared_vars=../../shared/common.tfvars ../../shared/secrets.tfvars
+tf_shared_vars ?=
+
+## @var tf_default_env
+## @desc Default environment name for convenience targets
+## @type string
+## @default local
+## @group terraform
+tf_default_env ?= local
+
+## @var tf_auto_approve_envs
+## @desc Space-separated list of environments where auto-approve is enabled
+## @type string
+## @default local
+## @group terraform
+## @example tf_auto_approve_envs=local dev
+tf_auto_approve_envs ?= local
+
+## @var tf_destroy_confirm
+## @desc Require confirmation before destroy operations
+## @type boolean
+## @default $(mb_true)
+## @group terraform
+tf_destroy_confirm ?= $(mb_true)
+
+## @var tf_chdir_flag
+## @desc Use -chdir flag (requires terraform 0.14+)
+## @type boolean
+## @default $(mb_true)
+## @group terraform
+tf_chdir_flag ?= $(mb_true)

modules/infrastructure/terraform/mod_info.mk

@@ -0,0 +1,6 @@
+mb_module_name := terraform
+mb_module_version := 1.0.0
+mb_module_description := Terraform workflow automation for multi-environment deployments
+mb_module_author := AntonioCS
+mb_module_license := MIT
+mb_module_depends :=

modules/infrastructure/terraform/terraform.mk

@@ -0,0 +1,163 @@
+#####################################################################################
+# Terraform Module
+# Workflow Automation for Multi-Environment Deployments
+#
+# Version: 1.0.0
+# Author: AntonioCS
+# License: MIT
+#####################################################################################
+# Overview:
+#   Provides reusable terraform workflow targets for managing infrastructure
+#   across multiple environments (local, dev, staging, prod, etc.)
+#
+# Prerequisites:
+#   - terraform CLI installed and in PATH
+#   - Environment directories under tf_env_dir
+#
+# Key Pattern:
+#   make terraform/<command>/<environment>
+#
+# Examples:
+#   make terraform/init/local
+#   make terraform/plan/dev
+#   make terraform/apply/prod
+#
+#####################################################################################
+
+ifndef __MB_MODULES_TERRAFORM__
+__MB_MODULES_TERRAFORM__ := 1
+
+#####################################################################################
+# Helper Functions
+#####################################################################################
+
+## @function tf_build_chdir
+## @desc Build the -chdir argument or empty string based on tf_chdir_flag
+## @arg 1: env (required) - Environment name
+## @returns -chdir=<path> or empty string
+## @group terraform
+define tf_build_chdir
+$(strip \
+	$(if $(value 1),,$(call mb_printf_error,$0: env required)) \
+	$(eval $0_arg1_env := $(strip $1)) \
+	$(if $(filter $(mb_true),$(tf_chdir_flag)), \
+		-chdir=$(tf_env_dir)/$($0_arg1_env) \
+	) \
+)
+endef
+
+## @function tf_build_var_file
+## @desc Build -var-file arguments for each file in tf_shared_vars
+## @desc Supports multiple space-delimited paths. Use mb_space_guard for paths with spaces.
+## @returns -var-file="<path>" for each file, or empty string if tf_shared_vars is empty
+## @group terraform
+## @example Single file: -var-file="common.tfvars"
+## @example Multiple: -var-file="common.tfvars" -var-file="secrets.tfvars"
+define tf_build_var_file
+$(strip \
+	$(if $(value tf_shared_vars), \
+		$(foreach $0_file,$(tf_shared_vars), \
+			-var-file="$(call mb_space_unguard,$($0_file))" \
+		) \
+	) \
+)
+endef
+
+## @function tf_is_auto_approve_env
+## @desc Check if environment is in auto-approve list
+## @arg 1: env (required) - Environment name
+## @returns $(mb_true) if auto-approve, empty otherwise
+## @group terraform
+define tf_is_auto_approve_env
+$(strip \
+	$(if $(value 1),,$(call mb_printf_error,$0: env required)) \
+	$(eval $0_arg1_env := $(strip $1)) \
+	$(if $(filter $($0_arg1_env),$(tf_auto_approve_envs)),$(mb_true)) \
+)
+endef
+
+## @function tf_run
+## @desc Execute terraform command in environment directory
+## @desc Automatically includes shared tfvars if tf_shared_vars is set
+## @arg 1: env (required) - Environment name (e.g., local, dev, prod)
+## @arg 2: command (required) - Terraform command (e.g., init, plan, apply)
+## @arg 3: extra_args (optional) - Additional arguments
+## @returns Command output via mb_invoke
+## @group terraform
+## @example $(call tf_run,local,init)
+## @example $(call tf_run,dev,plan,-detailed-exitcode)
+## @example $(call tf_run,prod,apply,-auto-approve)
+define tf_run
+$(strip \
+	$(if $(value 1),,$(call mb_printf_error,$0: env required)) \
+	$(if $(value 2),,$(call mb_printf_error,$0: command required)) \
+	$(eval $0_arg1_env := $(strip $1)) \
+	$(eval $0_arg2_cmd := $(strip $2)) \
+	$(eval $0_arg3_extra := $(if $(value 3),$(strip $3))) \
+	$(eval $0_chdir := $(call tf_build_chdir,$($0_arg1_env))) \
+	$(eval $0_var_file := $(call tf_build_var_file)) \
+	$(call mb_invoke,$(tf_bin) $($0_chdir) $($0_arg2_cmd) $($0_var_file) $($0_arg3_extra)) \
+)
+endef
+
+ifndef __MB_TEST_DISCOVERY__
+#####################################################################################
+# Generic Terraform Targets (pattern rules)
+#####################################################################################
+
+terraform/init/%: ## Initialize Terraform for environment (usage: make terraform/init/local)
+	$(call mb_printf_info,Initializing Terraform for $* environment...)
+	$(call tf_run,$*,init)
+
+terraform/plan/%: ## Plan Terraform changes (usage: make terraform/plan/dev)
+	$(call mb_printf_info,Planning Terraform changes for $* environment...)
+	$(call tf_run,$*,plan)
+
+terraform/apply/%: ## Apply Terraform changes (usage: make terraform/apply/local)
+	$(call mb_printf_info,Applying Terraform for $* environment...)
+	$(if $(call tf_is_auto_approve_env,$*), \
+		$(call tf_run,$*,apply,-auto-approve), \
+		$(call tf_run,$*,apply) \
+	)
+
+terraform/destroy/%: ## Destroy Terraform infrastructure (usage: make terraform/destroy/local)
+	$(if $(filter $(mb_true),$(tf_destroy_confirm)), \
+		$(call mb_user_confirm,This will destroy all infrastructure in $* environment!) \
+	)
+	$(if $(call tf_is_auto_approve_env,$*), \
+		$(call tf_run,$*,destroy,-auto-approve), \
+		$(call tf_run,$*,destroy) \
+	)
+
+terraform/validate/%: ## Validate Terraform configuration (usage: make terraform/validate/local)
+	$(call mb_printf_info,Validating Terraform configuration for $*...)
+	$(call tf_run,$*,validate)
+
+terraform/output/%: ## Show Terraform outputs (usage: make terraform/output/local)
+	$(call tf_run,$*,output)
+
+terraform/state/list/%: ## List Terraform state resources (usage: make terraform/state/list/local)
+	$(call tf_run,$*,state list)
+
+terraform/refresh/%: ## Refresh Terraform state (usage: make terraform/refresh/local)
+	$(call mb_printf_info,Refreshing Terraform state for $*...)
+	$(call tf_run,$*,refresh)
+
+#####################################################################################
+# Utility Targets
+#####################################################################################
+
+terraform/fmt: ## Format all Terraform files in tf_root_dir
+	$(call mb_printf_info,Formatting Terraform files in $(tf_root_dir)...)
+	$(call mb_invoke,$(tf_bin) fmt -recursive $(tf_root_dir))
+
+terraform/fmt/check: ## Check if Terraform files are formatted
+	$(call mb_printf_info,Checking Terraform formatting in $(tf_root_dir)...)
+	$(call mb_invoke,$(tf_bin) fmt -check -recursive $(tf_root_dir))
+
+terraform/version: ## Show Terraform version
+	$(call mb_invoke,$(tf_bin) version)
+
+endif # __MB_TEST_DISCOVERY__
+
+endif # __MB_MODULES_TERRAFORM__