feat(hooks): fire lifecycle hooks on terraform output and refresh

Store-write hooks (kind: store, and type: store steps) could only fire
on plan/apply/deploy/test, so backfilling a store from infrastructure
already deployed (before hooks existed, or outside Atmos entirely)
meant forcing a re-apply. Adds before/after.terraform.output and
before/after.terraform.refresh events, wired the same way as the
existing terraform subcommands (cmd/terraform/output.go, refresh.go,
and the terraformHookEvents multi-component dispatch), so a hook can
now bind to after.terraform.output to sync a value without an apply.

Closes #1055.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: osterman

agent-skills/skills/atmos-hooks/SKILL.md

@@ -60,6 +60,9 @@ Use before/after events for component operations, for example:
 - `before.terraform.apply`, `after.terraform.apply`
 - `before.terraform.deploy`, `after.terraform.deploy`
 - `before.terraform.test`, `after.terraform.test`
+- `before.terraform.output`, `after.terraform.output` — fires for `atmos terraform output`,
+  useful for backfilling a store from already-deployed infrastructure without an `apply`
+- `before.terraform.refresh`, `after.terraform.refresh`
 
 Kubernetes provides `before`/`after` events for `render`, `diff`/`plan`, `apply`/`deploy`,
 `delete`, and `validate`. Native Helm provides `template`, `diff`, `apply`/`deploy`, and

cmd/terraform/output.go

@@ -16,6 +16,7 @@ import (
 	"github.com/cloudposse/atmos/pkg/flags"
 	"github.com/cloudposse/atmos/pkg/flags/compat"
 	ghactions "github.com/cloudposse/atmos/pkg/github/actions"
+	h "github.com/cloudposse/atmos/pkg/hooks"
 	"github.com/cloudposse/atmos/pkg/perf"
 	"github.com/cloudposse/atmos/pkg/schema"
 	tfoutput "github.com/cloudposse/atmos/pkg/terraform/output"
@@ -42,7 +43,25 @@ Without --format, passes through to native terraform/tofu output command.
 For complete Terraform/OpenTofu documentation, see:
   https://developer.hashicorp.com/terraform/cli/commands/output
   https://opentofu.org/docs/cli/commands/output`,
-	RunE: func(cmd *cobra.Command, args []string) error {
+	PreRunE: func(cmd *cobra.Command, args []string) error {
+		return runBeforeHooks(h.BeforeTerraformOutput, cmd, args)
+	},
+	RunE: func(cmd *cobra.Command, args []string) (runErr error) {
+		// Reset before any early return so the deferred hook and PostRunE read
+		// consistent state.
+		wasMultiComponentExecution = false
+
+		// On failure, run after hooks with error context. Cobra skips PostRunE on
+		// error, so this is the only place the after.terraform.output hook fires
+		// when reading outputs fails. In multi-component mode the per-component
+		// hook already fired for each component, so the global error call is
+		// suppressed to avoid double-firing.
+		defer func() {
+			if runErr != nil && !wasMultiComponentExecution {
+				runHooksOnErrorWithOutput(h.AfterTerraformOutput, cmd, args, runErr, "")
+			}
+		}()
+
 		v := viper.GetViper()
 		if err := terraformParser.BindFlagsToViper(cmd, v); err != nil {
 			return err
@@ -56,6 +75,14 @@ For complete Terraform/OpenTofu documentation, see:
 		}
 		return outputRunWithFormat(cmd, args, format)
 	},
+	PostRunE: func(cmd *cobra.Command, args []string) error {
+		// In multi-component mode, per-component hooks already fired inside the
+		// affected/all/query dispatch. Calling them again here would double-fire.
+		if wasMultiComponentExecution {
+			return nil
+		}
+		return runHooksWithOutput(h.AfterTerraformOutput, cmd, args, "")
+	},
 }
 
 // outputRunWithFormat executes terraform output with atmos formatting.

cmd/terraform/refresh.go

@@ -4,6 +4,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/cloudposse/atmos/cmd/internal"
+	h "github.com/cloudposse/atmos/pkg/hooks"
 )
 
 // refreshCmd represents the terraform refresh command.
@@ -15,9 +16,35 @@ var refreshCmd = &cobra.Command{
 For complete Terraform/OpenTofu documentation, see:
   https://developer.hashicorp.com/terraform/cli/commands/refresh
   https://opentofu.org/docs/cli/commands/refresh`,
-	RunE: func(cmd *cobra.Command, args []string) error {
+	PreRunE: func(cmd *cobra.Command, args []string) error {
+		return runBeforeHooks(h.BeforeTerraformRefresh, cmd, args)
+	},
+	RunE: func(cmd *cobra.Command, args []string) (runErr error) {
+		// Reset before any early return so the deferred hook and PostRunE read
+		// consistent state.
+		wasMultiComponentExecution = false
+
+		// On failure, run after hooks with error context. Cobra skips PostRunE on
+		// error, so this is the only place the after.terraform.refresh hook fires
+		// when a refresh fails. In multi-component mode the per-component hook
+		// already fired for each component, so the global error call is
+		// suppressed to avoid double-firing.
+		defer func() {
+			if runErr != nil && !wasMultiComponentExecution {
+				runHooksOnErrorWithOutput(h.AfterTerraformRefresh, cmd, args, runErr, "")
+			}
+		}()
+
 		return terraformRun(terraformCmd, cmd, args)
 	},
+	PostRunE: func(cmd *cobra.Command, args []string) error {
+		// In multi-component mode, per-component hooks already fired inside the
+		// affected/all/query dispatch. Calling them again here would double-fire.
+		if wasMultiComponentExecution {
+			return nil
+		}
+		return runHooksWithOutput(h.AfterTerraformRefresh, cmd, args, "")
+	},
 }
 
 func init() {

cmd/terraform/utils.go

@@ -616,6 +616,10 @@ func terraformHookEvents(subCommand string) (before, after h.HookEvent, ok bool)
 		return h.BeforeTerraformApply, h.AfterTerraformApply, true
 	case "deploy":
 		return h.BeforeTerraformDeploy, h.AfterTerraformDeploy, true
+	case "output":
+		return h.BeforeTerraformOutput, h.AfterTerraformOutput, true
+	case "refresh":
+		return h.BeforeTerraformRefresh, h.AfterTerraformRefresh, true
 	default:
 		return "", "", false
 	}

cmd/terraform/utils_hooks_test.go

@@ -416,6 +416,48 @@ func TestApplyPostRunE_SuppressedWhenMultiComponent(t *testing.T) {
 	assert.NoError(t, err, "PostRunE must fire normally in single-component mode")
 }
 
+// TestOutputPostRunE_SuppressedWhenMultiComponent verifies that outputCmd.PostRunE
+// returns nil without error when wasMultiComponentExecution is true (multi-component
+// mode), mirroring the apply/deploy/plan PostRunE suppression contract.
+func TestOutputPostRunE_SuppressedWhenMultiComponent(t *testing.T) {
+	t.Chdir("../../examples/demo-stacks")
+
+	orig := wasMultiComponentExecution
+	defer func() { wasMultiComponentExecution = orig }()
+
+	cmd := newHookTestCmd()
+	cmd.Use = "output"
+
+	wasMultiComponentExecution = true
+	err := outputCmd.PostRunE(cmd, []string{"--stack", "dev", "myapp"})
+	assert.NoError(t, err, "PostRunE must be suppressed when wasMultiComponentExecution is true")
+
+	wasMultiComponentExecution = false
+	err = outputCmd.PostRunE(cmd, []string{"--stack", "dev", "myapp"})
+	assert.NoError(t, err, "PostRunE must fire normally in single-component mode")
+}
+
+// TestRefreshPostRunE_SuppressedWhenMultiComponent verifies that refreshCmd.PostRunE
+// returns nil without error when wasMultiComponentExecution is true (multi-component
+// mode), mirroring the apply/deploy/plan PostRunE suppression contract.
+func TestRefreshPostRunE_SuppressedWhenMultiComponent(t *testing.T) {
+	t.Chdir("../../examples/demo-stacks")
+
+	orig := wasMultiComponentExecution
+	defer func() { wasMultiComponentExecution = orig }()
+
+	cmd := newHookTestCmd()
+	cmd.Use = "refresh"
+
+	wasMultiComponentExecution = true
+	err := refreshCmd.PostRunE(cmd, []string{"--stack", "dev", "myapp"})
+	assert.NoError(t, err, "PostRunE must be suppressed when wasMultiComponentExecution is true")
+
+	wasMultiComponentExecution = false
+	err = refreshCmd.PostRunE(cmd, []string{"--stack", "dev", "myapp"})
+	assert.NoError(t, err, "PostRunE must fire normally in single-component mode")
+}
+
 // TestDeployRunE_DeferGuard verifies the RunE defer-guard contract in
 // deploy.go: the global error hook (runHooksOnErrorWithOutput) must fire
 // when runErr is non-nil AND wasMultiComponentExecution is false, and must
@@ -521,6 +563,88 @@ func TestDeployRunE_DeferGuard(t *testing.T) {
 	}
 }
 
+// TestOutputRefreshRunE_DeferGuard verifies the RunE defer-guard contract
+// shared by output.go and refresh.go: the global error hook
+// (runHooksOnErrorWithOutput) must fire when runErr is non-nil AND
+// wasMultiComponentExecution is false, and must be suppressed when
+// wasMultiComponentExecution is true (multi-component mode, where
+// per-component hooks already fired inside the affected/all/query
+// dispatch). Mirrors TestDeployRunE_DeferGuard for output.go's and
+// refresh.go's guards.
+func TestOutputRefreshRunE_DeferGuard(t *testing.T) {
+	subcommands := []struct {
+		name  string
+		use   string
+		event hooks.HookEvent
+	}{
+		{name: "output", use: "output", event: hooks.AfterTerraformOutput},
+		{name: "refresh", use: "refresh", event: hooks.AfterTerraformRefresh},
+	}
+
+	for _, sub := range subcommands {
+		t.Run(sub.name, func(t *testing.T) {
+			origGuard := wasMultiComponentExecution
+			origHook := runHooksOnErrorWithOutput
+			defer func() {
+				wasMultiComponentExecution = origGuard
+				runHooksOnErrorWithOutput = origHook
+			}()
+
+			var called bool
+			var calledEvent hooks.HookEvent
+			var calledErr error
+			runHooksOnErrorWithOutput = func(event hooks.HookEvent, _ *cobra.Command, _ []string, cmdErr error, _ string) {
+				called = true
+				calledEvent = event
+				calledErr = cmdErr
+			}
+
+			cmd := newHookTestCmd()
+			cmd.Use = sub.use
+			args := []string{"--stack", "dev", "myapp"}
+
+			// invokeDefer mirrors the RunE defer-guard body in output.go/refresh.go.
+			// Any change to the production guard must be reflected here.
+			invokeDefer := func(runErr error) {
+				if runErr != nil && !wasMultiComponentExecution {
+					runHooksOnErrorWithOutput(sub.event, cmd, args, runErr, "")
+				}
+			}
+
+			runErr := errors.New("terraform " + sub.name + " failed")
+
+			tests := []struct {
+				name           string
+				runErr         error
+				multiComponent bool
+				expectCalled   bool
+			}{
+				{name: "non-nil error + single-component → hook fires", runErr: runErr, multiComponent: false, expectCalled: true},
+				{name: "non-nil error + multi-component → hook suppressed", runErr: runErr, multiComponent: true, expectCalled: false},
+				{name: "nil error + single-component → hook does not fire", runErr: nil, multiComponent: false, expectCalled: false},
+				{name: "nil error + multi-component → hook does not fire", runErr: nil, multiComponent: true, expectCalled: false},
+			}
+
+			for _, tc := range tests {
+				t.Run(tc.name, func(t *testing.T) {
+					called = false
+					calledEvent = ""
+					calledErr = nil
+					wasMultiComponentExecution = tc.multiComponent
+
+					invokeDefer(tc.runErr)
+
+					assert.Equal(t, tc.expectCalled, called, "hook firing did not match expectation")
+					if tc.expectCalled {
+						assert.Equal(t, sub.event, calledEvent, "hook event mismatch")
+						assert.Equal(t, runErr, calledErr, "hook did not receive original runErr")
+					}
+				})
+			}
+		})
+	}
+}
+
 // TestTerraformNodeHooksAfter_DeployExitCodeForwarding verifies that the exit
 // code extracted from execErr is forwarded correctly, matching the plan
 // component hook behaviour.
@@ -598,8 +722,8 @@ func TestTerraformNodeHooksAfter_ApplyExitCodeForwarding(t *testing.T) {
 func TestWirePerComponentHook(t *testing.T) {
 	withoutCIDetection(t)
 
-	t.Run("plan/deploy/apply install a non-nil NodeHooks", func(t *testing.T) {
-		for _, sub := range []string{"plan", "deploy", "apply"} {
+	t.Run("plan/deploy/apply/output/refresh install a non-nil NodeHooks", func(t *testing.T) {
+		for _, sub := range []string{"plan", "deploy", "apply", "output", "refresh"} {
 			t.Run(sub, func(t *testing.T) {
 				info := &schema.ConfigAndStacksInfo{
 					TerraformPlanCIResultHandler: nil,
@@ -663,8 +787,8 @@ func TestWirePerComponentHook(t *testing.T) {
 	t.Run("unknown subcommand leaves NodeHooks unset", func(t *testing.T) {
 		// `init`, `validate`, etc. are valid terraform subcommands but they do
 		// not have per-component hooks today. The helper must be a no-op
-		// for anything outside the {plan, deploy, apply} set so other
-		// subcommands don't accidentally start firing hooks.
+		// for anything outside the {plan, deploy, apply, output, refresh} set
+		// so other subcommands don't accidentally start firing hooks.
 		for _, sub := range []string{"destroy", "init", "validate", ""} {
 			t.Run(sub, func(t *testing.T) {
 				info := &schema.ConfigAndStacksInfo{}
@@ -683,7 +807,7 @@ func TestWirePerComponentHook(t *testing.T) {
 		t.Chdir("../../examples/demo-stacks")
 		cmd := newHookTestCmd()
 
-		for _, sub := range []string{"plan", "deploy", "apply"} {
+		for _, sub := range []string{"plan", "deploy", "apply", "output", "refresh"} {
 			t.Run(sub, func(t *testing.T) {
 				info := &schema.ConfigAndStacksInfo{
 					Stack:            "dev",
@@ -702,7 +826,7 @@ func TestWirePerComponentHook(t *testing.T) {
 		}
 	})
 
-	t.Run("the three subcommands wire to distinct events", func(t *testing.T) {
+	t.Run("the five subcommands wire to distinct events", func(t *testing.T) {
 		// Sanity check: a future edit that copy-pastes one case over another
 		// (e.g. apply ends up using the plan event) wouldn't be caught by the
 		// nil/non-nil assertions above. Assert the wired before/after events
@@ -714,16 +838,19 @@ func TestWirePerComponentHook(t *testing.T) {
 			require.True(t, ok)
 			return nodeHooks.beforeEvent, nodeHooks.afterEvent
 		}
-		planBefore, planAfter := eventsFor("plan")
-		applyBefore, applyAfter := eventsFor("apply")
-		deployBefore, deployAfter := eventsFor("deploy")
-
-		assert.NotEqual(t, planAfter, applyAfter, "plan and apply must fire different after-events")
-		assert.NotEqual(t, planAfter, deployAfter, "plan and deploy must fire different after-events")
-		assert.NotEqual(t, applyAfter, deployAfter, "apply and deploy must fire different after-events")
-		assert.NotEqual(t, planBefore, applyBefore, "plan and apply must fire different before-events")
-		assert.NotEqual(t, planBefore, deployBefore, "plan and deploy must fire different before-events")
-		assert.NotEqual(t, applyBefore, deployBefore, "apply and deploy must fire different before-events")
+		subs := []string{"plan", "apply", "deploy", "output", "refresh"}
+		before := make(map[string]hooks.HookEvent, len(subs))
+		after := make(map[string]hooks.HookEvent, len(subs))
+		for _, sub := range subs {
+			before[sub], after[sub] = eventsFor(sub)
+		}
+
+		for i, a := range subs {
+			for _, b := range subs[i+1:] {
+				assert.NotEqual(t, after[a], after[b], "%s and %s must fire different after-events", a, b)
+				assert.NotEqual(t, before[a], before[b], "%s and %s must fire different before-events", a, b)
+			}
+		}
 	})
 }
 

pkg/hooks/event.go

@@ -15,6 +15,10 @@ const (
 	BeforeTerraformPlan            HookEvent = "before.terraform.plan"
 	BeforeTerraformTest            HookEvent = "before.terraform.test"
 	AfterTerraformTest             HookEvent = "after.terraform.test"
+	BeforeTerraformOutput          HookEvent = "before.terraform.output"
+	AfterTerraformOutput           HookEvent = "after.terraform.output"
+	BeforeTerraformRefresh         HookEvent = "before.terraform.refresh"
+	AfterTerraformRefresh          HookEvent = "after.terraform.refresh"
 	BeforeTerraformDeploy          HookEvent = "before.terraform.deploy"
 	AfterTerraformDeploy           HookEvent = "after.terraform.deploy"
 	AfterTerraformDestroyAggregate HookEvent = "after.terraform.destroy.aggregate"

pkg/hooks/event_test.go

@@ -17,6 +17,10 @@ func TestHookEvent_IsPostExecution(t *testing.T) {
 		{name: "before-plan is pre-execution", event: BeforeTerraformPlan, want: false},
 		{name: "after-plan is post-execution", event: AfterTerraformPlan, want: true},
 		{name: "after-apply is post-execution", event: AfterTerraformApply, want: true},
+		{name: "before-output is pre-execution", event: BeforeTerraformOutput, want: false},
+		{name: "after-output is post-execution", event: AfterTerraformOutput, want: true},
+		{name: "before-refresh is pre-execution", event: BeforeTerraformRefresh, want: false},
+		{name: "after-refresh is post-execution", event: AfterTerraformRefresh, want: true},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -30,3 +34,13 @@ func TestHookEvent_Normalize_InitNotAliased(t *testing.T) {
 	assert.Equal(t, BeforeTerraformInit, BeforeTerraformInit.Normalize())
 	assert.Equal(t, AfterTerraformInit, AfterTerraformInit.Normalize())
 }
+
+func TestHookEvent_Normalize_OutputRefreshNotAliased(t *testing.T) {
+	// output and refresh are read-only operations with no deploy-style alias —
+	// they normalize to themselves, and must stay distinct from apply/plan so a
+	// hook scoped to one does not cross-fire on the other.
+	assert.Equal(t, BeforeTerraformOutput, BeforeTerraformOutput.Normalize())
+	assert.Equal(t, AfterTerraformOutput, AfterTerraformOutput.Normalize())
+	assert.Equal(t, BeforeTerraformRefresh, BeforeTerraformRefresh.Normalize())
+	assert.Equal(t, AfterTerraformRefresh, AfterTerraformRefresh.Normalize())
+}