feat(cmd): add catalog syncer (#552)

This pull request introduces a new integration for catalog-based
datastore management, allowing the system to use a remote catalog
service for data persistence instead of local file storage. The changes
are designed to be non-breaking, providing configuration options to
select the desired backend and new CLI commands for migration and
synchronization. Additionally, several mock implementations are added to
support testing of the new functionality.

**Catalog Service Integration & Data Management**

* Added catalog service support for datastore management, enabling
transactional operations and providing an alternative to local file
storage. This includes a unified function (`MergeDataStoreToCatalog`)
for both initial migration and ongoing merge operations, ensuring atomic
updates and preventing data inconsistencies.
[[1]](diffhunk://#diff-6183631702722fc2a3ddbc5ec91a559eb5bfcf1f062553cebe75f8e515e6eec7R1-R22)
[[2]](diffhunk://#diff-25ea8888f88aec3194cfd2d4390d937364c653f876ed7901f7512012cbd4a9c6R1-R75)
* Added a new CLI command `datastore sync-to-catalog` for migrating all
local datastore data to the catalog service, supporting CI and
operational workflows.

**Testing & Mock Implementations**

* Added mock implementations for address reference, chain metadata, and
contract metadata stores to facilitate testing of catalog integration
and datastore operations. These mocks support fetch, get, and filter
operations for their respective data types.
(`datastore/mock_address_ref_store_test.go`
[[1]](diffhunk://#diff-0483d90cec93624656eff1726bc11354658127f5090b2a749711a57699ea69afR1-R201)
`datastore/mock_chain_metadata_store_test.go`
[[2]](diffhunk://#diff-e5c07878c88ed6de556788eae5b3250f4ec4904e2a700a26399dd056f523bb38R1-R201)
`datastore/mock_contract_metadata_store_test.go`
[[3]](diffhunk://#diff-516e47a714b875cf2f3d55628994f45e61a5061ecafe106c06589d4af8ca5141R1-R201)

https://smartcontract-it.atlassian.net/browse/CLD-782

Author: ajaskolski

.changeset/loud-spiders-end.md

@@ -0,0 +1,22 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+feat: add catalog service integration for datastore operations
+
+Features:
+- Add catalog service support for datastore management as alternative to local file storage
+- Add `MergeMigrationDataStoreCatalog` method for catalog-based datastore persistence
+- Existing `MergeMigrationDataStore` method continues to work for file-based storage (no breaking changes)
+- Add unified `MergeDataStoreToCatalog` function for both initial migration and ongoing merge operations
+- All catalog operations are transactional to prevent data inconsistencies
+- Add `DatastoreType` configuration option (`file`/`catalog`) in domain.yaml to control storage backend
+- Add new CLI command `datastore sync-to-catalog` for initial migration from file-based to catalog storage in CI
+- Add `SyncDataStoreToCatalog` method to sync entire local datastore to catalog
+- CLI automatically selects the appropriate merge method based on domain.yaml configuration
+- Catalog mode does not modify local files - all updates go directly to the catalog service
+
+Configuration:
+- Set `datastore: catalog` in domain.yaml to enable catalog mode
+- Set `datastore: file` or omit the setting to use traditional file-based storage
+- CLI commands automatically detect the configuration and use the appropriate storage backend

datastore/catalog_syncer.go

@@ -0,0 +1,75 @@
+package datastore
+
+import (
+	"context"
+	"errors"
+	"fmt"
+)
+
+// MergeDataStoreToCatalog merges data from a source DataStore (either full local state or migration-specific)
+// into a remote CatalogStore within a transaction. This ensures atomic updates - either all data is
+// successfully merged or the entire operation is rolled back on failure.
+//
+// This function serves two purposes:
+// 1. Initial migration: sync entire local datastore to catalog (full state push)
+// 2. Ongoing operations: merge migration/changeset artifacts into catalog (incremental updates)
+//
+// The operation is transactional to prevent partial failures that could lead to data inconsistencies.
+func MergeDataStoreToCatalog(ctx context.Context, sourceDS DataStore, catalog CatalogStore) error {
+	return catalog.WithTransaction(ctx, func(ctx context.Context, txCatalog BaseCatalogStore) error {
+		// Merge all address references to the catalog
+		addressRefs, err := sourceDS.Addresses().Fetch()
+		if err != nil {
+			return fmt.Errorf("failed to fetch address references from source store: %w", err)
+		}
+
+		for _, ref := range addressRefs {
+			if upsertErr := txCatalog.Addresses().Upsert(ctx, ref); upsertErr != nil {
+				return fmt.Errorf("failed to upsert address reference to catalog: %w", upsertErr)
+			}
+		}
+
+		// Merge all chain metadata to the catalog
+		chainMetadata, err := sourceDS.ChainMetadata().Fetch()
+		if err != nil {
+			return fmt.Errorf("failed to fetch chain metadata from source store: %w", err)
+		}
+
+		for _, metadata := range chainMetadata {
+			key := NewChainMetadataKey(metadata.ChainSelector)
+			if upsertErr := txCatalog.ChainMetadata().Upsert(ctx, key, metadata.Metadata); upsertErr != nil {
+				return fmt.Errorf("failed to upsert chain metadata to catalog: %w", upsertErr)
+			}
+		}
+
+		// Merge all contract metadata to the catalog
+		contractMetadata, err := sourceDS.ContractMetadata().Fetch()
+		if err != nil {
+			return fmt.Errorf("failed to fetch contract metadata from source store: %w", err)
+		}
+
+		for _, metadata := range contractMetadata {
+			key := NewContractMetadataKey(metadata.ChainSelector, metadata.Address)
+			if upsertErr := txCatalog.ContractMetadata().Upsert(ctx, key, metadata.Metadata); upsertErr != nil {
+				return fmt.Errorf("failed to upsert contract metadata to catalog: %w", upsertErr)
+			}
+		}
+
+		// Merge environment metadata to the catalog
+		envMetadata, err := sourceDS.EnvMetadata().Get()
+		if err != nil {
+			if !errors.Is(err, ErrEnvMetadataNotSet) {
+				return fmt.Errorf("failed to fetch environment metadata from source store: %w", err)
+			}
+
+			return nil
+		}
+
+		// Merge the environment metadata (upsert semantics)
+		if setErr := txCatalog.EnvMetadata().Set(ctx, envMetadata.Metadata); setErr != nil {
+			return fmt.Errorf("failed to set environment metadata in catalog: %w", setErr)
+		}
+
+		return nil
+	})
+}