feat(dummy): add new controls for the destroy phase

modules/dummy/.terraform-docs.yml

@@ -0,0 +1,48 @@
+formatter: "markdown"
+
+version: ""
+
+header-from: docs/header.md
+footer-from: docs/footer.md
+
+recursive:
+  enabled: false
+  path: modules
+  include-main: true
+
+sections:
+  hide: []
+  show: []
+
+content: ""
+
+output:
+  file: "README.md"
+  mode: inject
+  template: |-
+    <!-- BEGIN_TF_DOCS -->
+    {{ .Content }}
+    <!-- END_TF_DOCS -->
+
+output-values:
+  enabled: false
+  from: ""
+
+sort:
+  enabled: true
+  by: name
+
+settings:
+  anchor: true
+  color: true
+  default: true
+  description: false
+  escape: true
+  hide-empty: false
+  html: true
+  indent: 2
+  lockfile: true
+  read-comments: true
+  required: true
+  sensitive: true
+  type: true

modules/dummy/README.md

@@ -1,102 +1,128 @@
-# Terraform Diagnostic Executor Module
+<!-- BEGIN_TF_DOCS -->
+# **Dummy Terraform Module**
 
-This module is designed for DevOps testing and CI/CD pipeline validation. It provides features to simulate network latency (sleep) and catastrophic failures (crash) at both the terraform plan and terraform apply stages.
+## Overview
 
-It leverages the external data source (for plan-time checks) and null_resource with local-exec provisioners (for apply-time actions).
+This Terraform module is designed for DevOps testing and CI/CD pipeline validation. It provides controls to simulate latency and failures at every phase of the Terraform lifecycle — plan, apply, and destroy — without affecting real infrastructure.
 
-## Prerequisites
+The module uses the `external` data source to execute a Node.js script for plan-time diagnostics and `null_resource` with `local-exec` provisioners for apply-time and destroy-time behavior. This makes it easy to reproduce slow or failing pipeline runs in a controlled, repeatable way.
 
-- Terraform: Required version ~> 1.0.
+Typical use cases include testing CI/CD pipeline timeouts, verifying failure-handling logic, and validating destroy-phase behavior in automated workflows.
 
-- Node.js: Must be installed and accessible via the PATH on the machine running terraform plan and terraform apply.
+## Key Features
 
-- Required Providers: hashicorp/external and hashicorp/null.
+- **Plan-time controls**: Simulate slow or failing `terraform plan` runs via a Node.js script executed by the `external` data source.
+- **Apply-time controls**: Introduce configurable delays or intentional failures during `terraform apply` using `null_resource` provisioners.
+- **Destroy-time controls**: Reliably gate sleep and crash behavior during `terraform destroy`, always present in state so destroy provisioners execute as expected.
+- **Deterministic destroy ordering**: The crash resource depends on the sleep resource, ensuring sleep always runs before crash when both are enabled.
+- **Input validation**: The `sleep_on_destroy` variable is validated to require a non-negative integer, preventing silent misconfigurations.
 
-## Module Usage
+## Basic Usage
 
-The module requires four primary boolean and numeric variables to control its diagnostic behavior.
+### Simulate apply-time delay and destroy-time failure
 
-Example
+```hcl
+module "dummy" {
+  source = "git::https://github.com/prefapp/tfm.git//modules/dummy"
 
-```terraform
-module "diagnostic_test" {
-  source           = "./node-executor"
-
-  # Base input
   instance_name    = "ci-pipeline-check"
 
-  # PLAN TIME CONTROLS
-  sleep_on_plan    = 5           # Delays 'terraform plan' by 5 seconds
-  crash_on_plan    = false       # Set to true to force 'terraform plan' failure
-
-  # APPLY TIME CONTROLS
-  sleep_on_apply   = 10          # Delays 'terraform apply' by 10 seconds
-  crash_on_apply   = false       # Set to true to force 'terraform apply' failure
-}
-
-output "plan_status" {
-  value = module.diagnostic_test.plan_message
+  sleep_on_apply   = 10
+  crash_on_destroy = true
 }
 ```
 
+### Simulate plan-time crash and destroy-time delay
 
-## Inputs
+```hcl
+module "dummy" {
+  source = "git::https://github.com/prefapp/tfm.git//modules/dummy"
 
-## Inputs
+  instance_name    = "ci-pipeline-check"
 
-| Name | Description | Type | Default | Control Phase | 
-|---|---|---|---|---|
-| `instance_name` | A unique identifier for the diagnostic run. | `string` | `"default-test"` | Both | 
-| `sleep_on_plan` | Duration in seconds to delay the `terraform plan` execution. | `number` | `0` | Plan | 
-| `crash_on_plan` | If set to true, forces `terraform plan` to fail immediately. | `bool` | `false` | Plan | 
-| `sleep_on_apply` | Duration in seconds to delay the `terraform apply` execution. | `number` | `0` | Apply | 
-| `crash_on_apply` | If set to true, forces `terraform apply` to fail immediately. | `bool` | `false` | Apply |
+  crash_on_plan    = true
+  sleep_on_destroy = 30
+}
+```
 
+## File Structure
 
-## Outputs
+```
+dummy/
+├── .terraform-docs.yml       # terraform-docs configuration
+├── README.md                 # Auto-generated documentation
+├── main.tf                   # Module resources and provisioners
+├── variables.tf              # Input variable definitions
+├── outputs.tf                # Output value definitions
+├── script.js                 # Node.js script for plan-time diagnostics
+├── _examples/                # Usage examples
+│   └── basic/                # Basic configuration example
+│       └── main.tf
+└── docs/                     # Documentation source files
+    ├── header.md             # This file
+    └── footer.md             # Additional resources and support
+```
 
-| Name | Description | Value Source | 
-| ----- | ----- | ----- | 
-| `plan_message` | A status message from the plan-time script execution. | `data.external` | 
-| `plan_timestamp` | The timestamp when the plan-time script executed. | `data.external` | 
-| `plan_slept_for_s` | The actual seconds the script slept during plan. | `data.external` | 
-| `plan_crashed` | Status indicating if the crash logic was executed during plan. | `data.external` |
+## Requirements
 
+No requirements.
 
-## Diagnostic Scenarios
+## Providers
 
-### 1. Test Plan Failure
+| Name | Version |
+|------|---------|
+| <a name="provider_external"></a> [external](#provider\_external) | n/a |
+| <a name="provider_null"></a> [null](#provider\_null) | n/a |
 
-To test how your CI/CD pipeline handles a plan failure:
+## Modules
 
-```terraform
-# Set crash_on_plan to true via command line
-terraform plan -var="crash_on_plan=true"
-```
+No modules.
 
+## Resources
 
+| Name | Type |
+|------|------|
+| [null_resource.conditional_crash](https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource) | resource |
+| [null_resource.conditional_destroy_crash](https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource) | resource |
+| [null_resource.conditional_destroy_sleep](https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource) | resource |
+| [null_resource.conditional_sleep](https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource) | resource |
+| [null_resource.diagnostic_base_logic](https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource) | resource |
+| [external_external.script_executor](https://registry.terraform.io/providers/hashicorp/external/latest/docs/data-sources/external) | data source |
 
-Expected Result: The terraform plan command will exit with a non-zero exit code (failure) as the data "external" source executes the Node.js script, which calls process.exit(1).
+## Inputs
 
-### 2. Test Apply Failure
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_crash_on_apply"></a> [crash\_on\_apply](#input\_crash\_on\_apply) | Set to true to force a non-zero exit code during the 'apply' phase. | `bool` | `false` | no |
+| <a name="input_crash_on_destroy"></a> [crash\_on\_destroy](#input\_crash\_on\_destroy) | Set to true to force a non-zero exit code during the 'destroy' phase. | `bool` | `false` | no |
+| <a name="input_crash_on_plan"></a> [crash\_on\_plan](#input\_crash\_on\_plan) | Set to true to force a non-zero exit code during the 'plan' phase. | `bool` | `false` | no |
+| <a name="input_instance_name"></a> [instance\_name](#input\_instance\_name) | A unique identifier for this module instance. | `string` | n/a | yes |
+| <a name="input_sleep_on_apply"></a> [sleep\_on\_apply](#input\_sleep\_on\_apply) | Number of seconds to sleep during the 'apply' phase. | `number` | `0` | no |
+| <a name="input_sleep_on_destroy"></a> [sleep\_on\_destroy](#input\_sleep\_on\_destroy) | Number of seconds to sleep during the 'destroy' phase. | `number` | `0` | no |
+| <a name="input_sleep_on_plan"></a> [sleep\_on\_plan](#input\_sleep\_on\_plan) | Number of seconds to sleep during the 'plan' phase. | `number` | `0` | no |
 
-To test infrastructure deployment failure:
+## Outputs
 
-```terraform
-# Set crash_on_apply to true via command line
-terraform apply -auto-approve -var="crash_on_apply=true"
-```
+| Name | Description |
+|------|-------------|
+| <a name="output_apply_resource_id"></a> [apply\_resource\_id](#output\_apply\_resource\_id) | The ID of the base null resource, indicating apply logic executed. |
+| <a name="output_script_message"></a> [script\_message](#output\_script\_message) | The message returned by the external script (ran during plan). |
+| <a name="output_script_timestamp"></a> [script\_timestamp](#output\_script\_timestamp) | The timestamp returned by the external script (ran during plan). |
 
-Expected Result: The terraform apply command will fail when it attempts to create the null_resource.diagnostic_crash_logic because its local-exec provisioner executes the exit 1 shell command.
+## Examples
 
-### 3. Test Apply Timeout/Latency
+For detailed examples, refer to the [module examples](https://github.com/prefapp/tfm/tree/main/modules/dummy/_examples):
 
-To test pipeline timeouts during execution:
+- [Basic](https://github.com/prefapp/tfm/tree/main/modules/dummy/_examples/basic) - Minimal configuration showing plan, apply, and destroy controls
 
-```
-# Set a 30 second delay during the apply phase
-terraform apply -auto-approve -var="sleep_on_apply=30"
-```
+## Resources
+
+- **Terraform null provider**: [https://registry.terraform.io/providers/hashicorp/null/latest](https://registry.terraform.io/providers/hashicorp/null/latest)
+- **Terraform external provider**: [https://registry.terraform.io/providers/hashicorp/external/latest](https://registry.terraform.io/providers/hashicorp/external/latest)
+- **Terraform local-exec provisioner**: [https://developer.hashicorp.com/terraform/language/resources/provisioners/local-exec](https://developer.hashicorp.com/terraform/language/resources/provisioners/local-exec)
 
+## Support
 
+For issues, questions, or contributions related to this module, please visit the [repository's issue tracker](https://github.com/prefapp/tfm/issues).
+<!-- END_TF_DOCS -->
 

modules/dummy/_examples/basic/main.tf

@@ -0,0 +1,29 @@
+# Basic example: simulate a 5-second delay during apply.
+# Useful for validating CI/CD pipeline timeout and failure-handling logic.
+# Set crash_on_destroy = true to test destroy-time failure behavior.
+
+module "dummy" {
+  source = "git::https://github.com/prefapp/tfm.git//modules/dummy"
+
+  instance_name = "ci-pipeline-check"
+
+  # PLAN TIME CONTROLS
+  sleep_on_plan = 0
+  crash_on_plan = false
+
+  # APPLY TIME CONTROLS
+  sleep_on_apply = 5     # Delays 'terraform apply' by 5 seconds
+  crash_on_apply = false
+
+  # DESTROY TIME CONTROLS
+  sleep_on_destroy = 0
+  crash_on_destroy = false # Set to true to force 'terraform destroy' failure
+}
+
+output "script_message" {
+  value = module.dummy.script_message
+}
+
+output "apply_resource_id" {
+  value = module.dummy.apply_resource_id
+}

modules/dummy/docs/footer.md

@@ -0,0 +1,15 @@
+## Examples
+
+For detailed examples, refer to the [module examples](https://github.com/prefapp/tfm/tree/main/modules/dummy/_examples):
+
+- [Basic](https://github.com/prefapp/tfm/tree/main/modules/dummy/_examples/basic) - Minimal configuration showing plan, apply, and destroy controls
+
+## Resources
+
+- **Terraform null provider**: [https://registry.terraform.io/providers/hashicorp/null/latest](https://registry.terraform.io/providers/hashicorp/null/latest)
+- **Terraform external provider**: [https://registry.terraform.io/providers/hashicorp/external/latest](https://registry.terraform.io/providers/hashicorp/external/latest)
+- **Terraform local-exec provisioner**: [https://developer.hashicorp.com/terraform/language/resources/provisioners/local-exec](https://developer.hashicorp.com/terraform/language/resources/provisioners/local-exec)
+
+## Support
+
+For issues, questions, or contributions related to this module, please visit the [repository's issue tracker](https://github.com/prefapp/tfm/issues).

modules/dummy/docs/header.md

@@ -0,0 +1,63 @@
+# **Dummy Terraform Module**
+
+## Overview
+
+This Terraform module is designed for DevOps testing and CI/CD pipeline validation. It provides controls to simulate latency and failures at every phase of the Terraform lifecycle — plan, apply, and destroy — without affecting real infrastructure.
+
+The module uses the `external` data source to execute a Node.js script for plan-time diagnostics and `null_resource` with `local-exec` provisioners for apply-time and destroy-time behavior. This makes it easy to reproduce slow or failing pipeline runs in a controlled, repeatable way.
+
+Typical use cases include testing CI/CD pipeline timeouts, verifying failure-handling logic, and validating destroy-phase behavior in automated workflows.
+
+## Key Features
+
+- **Plan-time controls**: Simulate slow or failing `terraform plan` runs via a Node.js script executed by the `external` data source.
+- **Apply-time controls**: Introduce configurable delays or intentional failures during `terraform apply` using `null_resource` provisioners.
+- **Destroy-time controls**: Reliably gate sleep and crash behavior during `terraform destroy`, always present in state so destroy provisioners execute as expected.
+- **Deterministic destroy ordering**: The crash resource depends on the sleep resource, ensuring sleep always runs before crash when both are enabled.
+- **Input validation**: The `sleep_on_destroy` variable is validated to require a non-negative integer, preventing silent misconfigurations.
+
+## Basic Usage
+
+### Simulate apply-time delay and destroy-time failure
+
+```hcl
+module "dummy" {
+  source = "git::https://github.com/prefapp/tfm.git//modules/dummy"
+
+  instance_name    = "ci-pipeline-check"
+
+  sleep_on_apply   = 10
+  crash_on_destroy = true
+}
+```
+
+### Simulate plan-time crash and destroy-time delay
+
+```hcl
+module "dummy" {
+  source = "git::https://github.com/prefapp/tfm.git//modules/dummy"
+
+  instance_name    = "ci-pipeline-check"
+
+  crash_on_plan    = true
+  sleep_on_destroy = 30
+}
+```
+
+## File Structure
+
+```
+dummy/
+├── .terraform-docs.yml       # terraform-docs configuration
+├── README.md                 # Auto-generated documentation
+├── main.tf                   # Module resources and provisioners
+├── variables.tf              # Input variable definitions
+├── outputs.tf                # Output value definitions
+├── script.js                 # Node.js script for plan-time diagnostics
+├── _examples/                # Usage examples
+│   └── basic/                # Basic configuration example
+│       └── main.tf
+└── docs/                     # Documentation source files
+    ├── header.md             # This file
+    └── footer.md             # Additional resources and support
+```