Add per-changeset hook registration to fluent API (#796)

## Summary
- Adds `WithPreHooks(...PreHook)` and `WithPostHooks(...PostHook)` to
`ConfiguredChangeSet` and `PostProcessingChangeSet` interfaces
- Hooks are stored on `ChangeSetImpl` and `PostProcessingChangeSetImpl`,
propagated through `ThenWith`, and extracted into `registryEntry` via an
internal `hookCarrier` interface when `Add()` is called
- Multiple calls are additive (append, not replace)
- Fully backward compatible — existing `Add()` call sites and tests are
unchanged

## Test plan
- [x] Package compiles cleanly
- [x] 0 lint issues (`golangci-lint`)
- [x] All existing changeset tests pass unchanged
- Unit tests for hook registration and chaining coming in
https://smartcontract-it.atlassian.net/browse/CLD-1270

Author: bytesizedroll

.changeset/shaggy-bikes-decide.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+Add per-changeset hook registration via WithPreHooks/WithPostHooks fluent API

engine/cld/changeset/common.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"os"
 	"reflect"
+	"slices"
 	"strings"
 
 	fresolvers "github.com/smartcontractkit/chainlink-deployments-framework/changeset/resolvers"
@@ -39,6 +40,8 @@ type ChangeSet internalChangeSet
 type ConfiguredChangeSet interface {
 	ChangeSet
 	ThenWith(postProcessor PostProcessor) PostProcessingChangeSet
+	WithPreHooks(hooks ...PreHook) ConfiguredChangeSet
+	WithPostHooks(hooks ...PostHook) ConfiguredChangeSet
 }
 
 // WrappedChangeSet simply wraps a fdeployment.ChangeSetV2 to use it in the fluent interface, which hosts
@@ -264,6 +267,9 @@ type ChangeSetImpl[C any] struct {
 	// Present only when the changeset was wired with
 	// Configure(...).WithConfigResolver(...)
 	ConfigResolver fresolvers.ConfigResolver
+
+	preHooks  []PreHook
+	postHooks []PostHook
 }
 
 func (ccs ChangeSetImpl[C]) noop() {}
@@ -303,10 +309,28 @@ func (ccs ChangeSetImpl[C]) Configurations() (Configurations, error) {
 	}, nil
 }
 
-// ThenWith adds post-processing to a configured changeset
+// WithPreHooks appends pre-hooks to this changeset. Multiple calls are additive.
+func (ccs ChangeSetImpl[C]) WithPreHooks(hooks ...PreHook) ConfiguredChangeSet {
+	ccs.preHooks = append(slices.Clone(ccs.preHooks), hooks...)
+	return ccs
+}
+
+// WithPostHooks appends post-hooks to this changeset. Multiple calls are additive.
+func (ccs ChangeSetImpl[C]) WithPostHooks(hooks ...PostHook) ConfiguredChangeSet {
+	ccs.postHooks = append(slices.Clone(ccs.postHooks), hooks...)
+	return ccs
+}
+
+func (ccs ChangeSetImpl[C]) getPreHooks() []PreHook   { return ccs.preHooks }
+func (ccs ChangeSetImpl[C]) getPostHooks() []PostHook { return ccs.postHooks }
+
+// ThenWith adds post-processing to a configured changeset.
+// Hooks registered before ThenWith are carried forward.
 func (ccs ChangeSetImpl[C]) ThenWith(postProcessor PostProcessor) PostProcessingChangeSet {
 	return PostProcessingChangeSetImpl[C]{
 		changeset:     ccs,
 		postProcessor: postProcessor,
+		preHooks:      slices.Clone(ccs.preHooks),
+		postHooks:     slices.Clone(ccs.postHooks),
 	}
 }

engine/cld/changeset/postprocess.go

@@ -1,18 +1,26 @@
 package changeset
 
 import (
+	"slices"
+
 	fdeployment "github.com/smartcontractkit/chainlink-deployments-framework/deployment"
 )
 
 type PostProcessor func(e fdeployment.Environment, config fdeployment.ChangesetOutput) (fdeployment.ChangesetOutput, error)
 
-type PostProcessingChangeSet internalChangeSet
+type PostProcessingChangeSet interface {
+	internalChangeSet
+	WithPreHooks(hooks ...PreHook) PostProcessingChangeSet
+	WithPostHooks(hooks ...PostHook) PostProcessingChangeSet
+}
 
 var _ PostProcessingChangeSet = PostProcessingChangeSetImpl[any]{}
 
 type PostProcessingChangeSetImpl[C any] struct {
 	changeset     ChangeSetImpl[C]
 	postProcessor PostProcessor
+	preHooks      []PreHook
+	postHooks     []PostHook
 }
 
 func (ccs PostProcessingChangeSetImpl[C]) noop() {}
@@ -30,3 +38,18 @@ func (ccs PostProcessingChangeSetImpl[C]) Apply(env fdeployment.Environment) (fd
 func (ccs PostProcessingChangeSetImpl[C]) Configurations() (Configurations, error) {
 	return ccs.changeset.Configurations()
 }
+
+// WithPreHooks appends pre-hooks to this changeset. Multiple calls are additive.
+func (ccs PostProcessingChangeSetImpl[C]) WithPreHooks(hooks ...PreHook) PostProcessingChangeSet {
+	ccs.preHooks = append(slices.Clone(ccs.preHooks), hooks...)
+	return ccs
+}
+
+// WithPostHooks appends post-hooks to this changeset. Multiple calls are additive.
+func (ccs PostProcessingChangeSetImpl[C]) WithPostHooks(hooks ...PostHook) PostProcessingChangeSet {
+	ccs.postHooks = append(slices.Clone(ccs.postHooks), hooks...)
+	return ccs
+}
+
+func (ccs PostProcessingChangeSetImpl[C]) getPreHooks() []PreHook   { return ccs.preHooks }
+func (ccs PostProcessingChangeSetImpl[C]) getPostHooks() []PostHook { return ccs.postHooks }

engine/cld/changeset/registry.go

@@ -72,11 +72,28 @@ type registryEntry struct {
 
 	// options contains the configuration options for this changeset
 	options ChangesetConfig
+
+	preHooks  []PreHook
+	postHooks []PostHook
+}
+
+// hookCarrier is implemented by changeset types that carry hooks through the
+// fluent API chain. Add() uses this to extract hooks into the registry entry.
+type hookCarrier interface {
+	getPreHooks() []PreHook
+	getPostHooks() []PostHook
 }
 
 // newRegistryEntry creates a new registry entry for a changeset.
 func newRegistryEntry(c ChangeSet, opts ChangesetConfig) registryEntry {
-	return registryEntry{changeset: c, options: opts}
+	entry := registryEntry{changeset: c, options: opts}
+
+	if hc, ok := c.(hookCarrier); ok {
+		entry.preHooks = hc.getPreHooks()
+		entry.postHooks = hc.getPostHooks()
+	}
+
+	return entry
 }
 
 // newArchivedRegistryEntry creates a new registry entry for an archived changeset.