feat(cmd): add catalog syncer

.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
+	})
+}