feat: Add article that documents common terraformWrapper use-cases (#25)

Thanks to the following GitHub use-cases:

https://github.com/juspay/chutney/blob/b6bd15d8635bc085f394a6fc3a659ad422a9df79/modules/flake-parts/terranix.nix

https://github.com/baduhai/nix-config/blob/c3650b73a1310c61c2e67afe0d1347bc4dac852a/terranix/terminus.nix

Author: sshine

src/SUMMARY.md

@@ -6,6 +6,7 @@
 - [Getting started](getting-started.md)
   - [What is Terraform / OpenTofu?](what-is-terranix.md)
   - [Getting started with flakes](getting-started-with-flakes.md)
+  - [Customizing the Terraform binary](terraform-wrapper.md)
   - [Differences between terranix and HCL](terranix-vs-hcl.md)
 - [Functions](functions.md)
 - [Modules](modules.md)

src/terraform-wrapper.md

@@ -0,0 +1,110 @@
+# Customizing the Terraform binary
+
+When using terranix with [flake-parts][getting-started-flakes], the `terraformWrapper`
+option lets you control which Terraform implementation is used, bundle provider plugins,
+and run custom commands around each invocation. By default it uses `pkgs.terraform`.
+
+All options live under `terranix.terranixConfigurations.<name>.terraformWrapper`.
+
+[getting-started-flakes]: getting-started-with-flakes.html
+[flake-module]: https://github.com/terranix/terranix/blob/main/flake-module.nix
+
+## Using OpenTofu
+
+To use [OpenTofu](https://opentofu.org/) instead of Terraform, set the `package` option:
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs";
+    terranix.url = "github:terranix/terranix";
+    terranix.inputs.nixpkgs.follows = "nixpkgs";
+    flake-parts.url = "github:hercules-ci/flake-parts";
+    flake-parts.inputs.nixpkgs-lib.follows = "nixpkgs";
+  };
+
+  outputs = inputs@{ flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      imports = [ inputs.terranix.flakeModules.default ];
+      systems = [ "x86_64-linux" ];
+      perSystem = { pkgs, ... }: {
+        terranix.terranixConfigurations.default = {
+          terraformWrapper.package = pkgs.opentofu;
+          modules = [ ./config.nix ];
+        };
+      };
+    };
+}
+```
+
+This replaces every `terraform` call in the generated scripts (`init`, `apply`, `plan`, `destroy`) with `tofu`.
+
+## Bundling provider plugins
+
+You can pre-bundle provider plugins so that `terraform init` doesn't need to download them:
+
+```nix
+terranix.terranixConfigurations.default = {
+  terraformWrapper.package = pkgs.terraform.withPlugins (p: [
+    p.aws
+  ]);
+  modules = [ ./config.nix ];
+};
+```
+
+This works the same way for OpenTofu:
+
+```nix
+terraformWrapper.package = pkgs.opentofu.withPlugins (p: [
+  p.aws
+  p.null
+  p.external
+]);
+```
+
+## Running commands before or after Terraform
+
+The `prefixText` and `suffixText` options inject shell commands that run before and after
+every Terraform invocation. A common use case is exporting secrets:
+
+```nix
+terraformWrapper.prefixText = ''
+  export TF_VAR_hcloud_token="$(cat /run/secrets/hcloud-token)"
+'';
+```
+
+Or running a cleanup step afterwards:
+
+```nix
+terraformWrapper.suffixText = ''
+  echo "Terraform finished, cleaning up temp files..."
+  rm -f /tmp/tf-scratch-*
+'';
+```
+
+## Extra runtime inputs
+
+When your `prefixText` or `suffixText` call external programs, add them to `extraRuntimeInputs` so they're available on `PATH`:
+
+```nix
+terraformWrapper.extraRuntimeInputs = [ pkgs.jq pkgs.awscli2 ];
+```
+
+For example, to fetch a secret from AWS Secrets Manager before each run:
+
+```nix
+terranix.terranixConfigurations.default = {
+  terraformWrapper = {
+    extraRuntimeInputs = [ pkgs.jq pkgs.awscli2 ];
+    prefixText = ''
+      export TF_VAR_db_password="$(
+        aws secretsmanager get-secret-value \
+          --secret-id my-db-password \
+          --query SecretString \
+          --output text
+      )"
+    '';
+  };
+  modules = [ ./config.nix ];
+};
+```