feat(utils): introduce merge sequence

Introduced ExecuteOnChainSequenceAndMerge util which originated from ccip tooling api [here](https://github.com/smartcontractkit/chainlink-ccip/blob/298ed1c38d5cda61a688beb2494a96a5409daf3d/deployment/utils/sequences/sequences.go#L46)

This utils allows user to execute multiple sequence and accumulate their results into an object call OnChainOutput

JIRA: https://smartcontract-it.atlassian.net/browse/CLD-2464

Author: graham-chainlink

changeset/sequenceutils/merge.go

@@ -0,0 +1,34 @@
+package sequenceutils
+
+import (
+	"fmt"
+
+	"github.com/smartcontractkit/chainlink-deployments-framework/operations"
+)
+
+// ExecuteOnChainSequenceAndMerge executes a sequence and merges the output into the given OnChainOutput.
+// On sequence execution failure, the accumulated agg is returned unchanged together with the error.
+func ExecuteOnChainSequenceAndMerge[IN any, DEP any](
+	b operations.Bundle,
+	deps DEP,
+	seq *operations.Sequence[IN, OnChainOutput, DEP],
+	input IN,
+	agg OnChainOutput,
+) (OnChainOutput, error) {
+	report, err := operations.ExecuteSequence(b, seq, deps, input)
+	if err != nil {
+		return agg, fmt.Errorf("failed to execute %s: %w", seq.ID(), err)
+	}
+	agg.BatchOps = append(agg.BatchOps, report.Output.BatchOps...)
+	agg.Metadata.Addresses = append(agg.Metadata.Addresses, report.Output.Metadata.Addresses...)
+	agg.Metadata.Contracts = append(agg.Metadata.Contracts, report.Output.Metadata.Contracts...)
+	agg.Metadata.Chains = append(agg.Metadata.Chains, report.Output.Metadata.Chains...)
+	if report.Output.Metadata.Env != nil {
+		if agg.Metadata.Env != nil {
+			return agg, fmt.Errorf("conflicting env metadata from sequence %s", seq.ID())
+		}
+		agg.Metadata.Env = report.Output.Metadata.Env
+	}
+
+	return agg, nil
+}

changeset/sequenceutils/merge_test.go

@@ -0,0 +1,111 @@
+package sequenceutils
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/Masterminds/semver/v3"
+	mcms_types "github.com/smartcontractkit/mcms/types"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smartcontractkit/chainlink-deployments-framework/datastore"
+	"github.com/smartcontractkit/chainlink-deployments-framework/operations"
+)
+
+func TestExecuteOnChainSequenceAndMerge_success(t *testing.T) {
+	t.Parallel()
+
+	env := testEnvironment(t)
+	seq := testSequence(t, func(_ operations.Bundle, _ struct{}, _ struct{}) (OnChainOutput, error) {
+		return OnChainOutput{
+			BatchOps: []mcms_types.BatchOperation{sampleBatchOp()},
+			Metadata: datastore.MetadataBundle{
+				Addresses: []datastore.AddressRef{{
+					Address:       "0xabc",
+					ChainSelector: 1,
+					Type:          "Timelock",
+					Version:       semver.MustParse("1.0.0"),
+				}},
+				Chains: []datastore.ChainMetadata{{ChainSelector: 1, Metadata: "chain-a"}},
+			},
+		}, nil
+	})
+
+	agg, err := ExecuteOnChainSequenceAndMerge(env.OperationsBundle, struct{}{}, seq, struct{}{}, OnChainOutput{})
+	require.NoError(t, err)
+	require.Len(t, agg.BatchOps, 1)
+	require.Len(t, agg.Metadata.Addresses, 1)
+	require.Len(t, agg.Metadata.Chains, 1)
+}
+
+func TestExecuteOnChainSequenceAndMerge_preservesAggOnExecuteFailure(t *testing.T) {
+	t.Parallel()
+
+	env := testEnvironment(t)
+	seqErr := errors.New("sequence failed")
+
+	okSeq := testSequence(t, func(_ operations.Bundle, _ struct{}, _ struct{}) (OnChainOutput, error) {
+		return OnChainOutput{
+			Metadata: datastore.MetadataBundle{
+				Addresses: []datastore.AddressRef{{
+					Address:       "0xabc",
+					ChainSelector: 1,
+					Type:          "Timelock",
+					Version:       semver.MustParse("1.0.0"),
+				}},
+			},
+		}, nil
+	})
+	failSeq := testSequence(t, func(_ operations.Bundle, _ struct{}, _ struct{}) (OnChainOutput, error) {
+		return OnChainOutput{}, seqErr
+	})
+
+	agg, err := ExecuteOnChainSequenceAndMerge(env.OperationsBundle, struct{}{}, okSeq, struct{}{}, OnChainOutput{})
+	require.NoError(t, err)
+	require.Len(t, agg.Metadata.Addresses, 1)
+
+	agg, err = ExecuteOnChainSequenceAndMerge(env.OperationsBundle, struct{}{}, failSeq, struct{}{}, agg)
+	require.Error(t, err)
+	require.ErrorContains(t, err, seqErr.Error())
+	require.Len(t, agg.Metadata.Addresses, 1)
+}
+
+func TestExecuteOnChainSequenceAndMerge_appendsChainsWithoutDeduping(t *testing.T) {
+	t.Parallel()
+
+	env := testEnvironment(t)
+	seq := testSequence(t, func(_ operations.Bundle, _ struct{}, _ struct{}) (OnChainOutput, error) {
+		return OnChainOutput{
+			Metadata: datastore.MetadataBundle{
+				Chains: []datastore.ChainMetadata{{ChainSelector: 1, Metadata: "a"}},
+			},
+		}, nil
+	})
+
+	agg := OnChainOutput{}
+	agg, err := ExecuteOnChainSequenceAndMerge(env.OperationsBundle, struct{}{}, seq, struct{}{}, agg)
+	require.NoError(t, err)
+	agg, err = ExecuteOnChainSequenceAndMerge(env.OperationsBundle, struct{}{}, seq, struct{}{}, agg)
+	require.NoError(t, err)
+	require.Len(t, agg.Metadata.Chains, 2)
+	require.Equal(t, uint64(1), agg.Metadata.Chains[0].ChainSelector)
+	require.Equal(t, uint64(1), agg.Metadata.Chains[1].ChainSelector)
+}
+
+func TestExecuteOnChainSequenceAndMerge_envConflict(t *testing.T) {
+	t.Parallel()
+
+	env := testEnvironment(t)
+	envMeta := &datastore.EnvMetadata{Metadata: "staging"}
+	seq := testSequence(t, func(_ operations.Bundle, _ struct{}, _ struct{}) (OnChainOutput, error) {
+		return OnChainOutput{
+			Metadata: datastore.MetadataBundle{Env: envMeta},
+		}, nil
+	})
+
+	agg := OnChainOutput{Metadata: datastore.MetadataBundle{Env: &datastore.EnvMetadata{Metadata: "prod"}}}
+	agg, err := ExecuteOnChainSequenceAndMerge(env.OperationsBundle, struct{}{}, seq, struct{}{}, agg)
+	require.Error(t, err)
+	require.ErrorContains(t, err, "conflicting env metadata")
+	require.Equal(t, "prod", agg.Metadata.Env.Metadata)
+}