Add example CLIs exercising the migration library (Phase 4)

Adds two example CLI binaries under migration/examples/cmd/ that
demonstrate the migration library API. Per the design, these are
prototype consumers — not production delivery artifacts. Production
CLIs (oc plugin, Console) will import migration/pkg/* directly.

migrate-operators-v0-to-v1:
  check   <operator|-all> [-n ns]   — readiness + compat + catalog check
  convert <operator|-all> [-n ns]   — full migration; --dry-run, --backup,
                                       --delete-operatorgroup, --continue-
                                       on-error, --acknowledge-* flags
  rollback <ce|-all>                — restore to OLMv0 management
  cleanup  <ce|-all>                — finish partial migration (Conflict)

migrate-catalogs-v0-to-v1:
  [flags]  — --dry-run, --delete-catalogsource, --acknowledge-priority-overflow

Both CLIs use the standard clientcmd kubeconfig chain (explicit flag →
KUBECONFIG env → ~/.kube/config → in-cluster) for HCP compatibility.

Built with: make build

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Todd Short <tshort@redhat.com>

Author: tmshort

go.mod

@@ -5,6 +5,7 @@ go 1.26.5
 require (
 	github.com/operator-framework/api v0.45.0
 	github.com/operator-framework/operator-controller v1.11.0
+	github.com/spf13/cobra v1.10.2
 	k8s.io/api v0.36.2
 	k8s.io/apiextensions-apiserver v0.36.2
 	k8s.io/apimachinery v0.36.2
@@ -37,12 +38,14 @@ require (
 	github.com/go-openapi/swag/yamlutils v0.26.0 // indirect
 	github.com/google/gnostic-models v0.7.1 // indirect
 	github.com/google/uuid v1.6.0 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/kr/text v0.2.0 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/sirupsen/logrus v1.9.4 // indirect
+	github.com/spf13/pflag v1.0.10 // indirect
 	github.com/x448/float16 v0.8.4 // indirect
 	go.yaml.in/yaml/v2 v2.4.4 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect

go.sum

@@ -10,6 +10,7 @@ github.com/blang/semver/v4 v4.0.0 h1:1PFHFE6yCCTv8C1TeyNNarDzntLi7wMI5i/pzqYIsAM
 github.com/blang/semver/v4 v4.0.0/go.mod h1:IbckMUScFkM3pff0VJDNKRiT6TG/YpiHIM2yvyW5YoQ=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -109,10 +110,12 @@ github.com/prometheus/procfs v0.20.1 h1:XwbrGOIplXW/AU3YhIhLODXMJYyC1isLFfYCsTEy
 github.com/prometheus/procfs v0.20.1/go.mod h1:o9EMBZGRyvDrSPH1RqdxhojkuXstoe4UlK79eF5TGGo=
 github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
 github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w=
 github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g=
 github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
 github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
+github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
 github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=

migration/examples/cmd/migrate-catalogs-v0-to-v1/main.go

@@ -0,0 +1,184 @@
+// migrate-catalogs-v0-to-v1 migrates OLMv0 CatalogSources to OLMv1 ClusterCatalogs.
+// Run this before migrate-operators-v0-to-v1.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/spf13/cobra"
+	"k8s.io/apimachinery/pkg/runtime"
+	utilruntime "k8s.io/apimachinery/pkg/util/runtime"
+	clientgoscheme "k8s.io/client-go/kubernetes/scheme"
+	"k8s.io/client-go/tools/clientcmd"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+
+	operatorsv1alpha1 "github.com/operator-framework/api/pkg/operators/v1alpha1"
+	ocv1 "github.com/operator-framework/operator-controller/api/v1"
+
+	"github.com/operator-framework/library-olm/migration/pkg/catalogmigration"
+)
+
+var scheme = runtime.NewScheme()
+
+func init() {
+	utilruntime.Must(clientgoscheme.AddToScheme(scheme))
+	utilruntime.Must(ocv1.AddToScheme(scheme))
+	utilruntime.Must(operatorsv1alpha1.AddToScheme(scheme))
+}
+
+var (
+	kubeconfig                  string
+	dryRun                      bool
+	deleteCatalogSource         bool
+	acknowledgePriorityOverflow bool
+)
+
+var rootCmd = &cobra.Command{
+	Use:   "migrate-catalogs-v0-to-v1",
+	Short: "Migrate OLMv0 CatalogSources to OLMv1 ClusterCatalogs",
+	Long: `Scans all CatalogSources across all namespaces and creates
+corresponding OLMv1 ClusterCatalogs.
+
+Only grpc-type CatalogSources with a spec.image are migratable.
+configmap, internal, and address-only CatalogSources are reported as not migratable.
+
+Run this before migrate-operators-v0-to-v1.
+
+Examples:
+  migrate-catalogs-v0-to-v1
+  migrate-catalogs-v0-to-v1 --dry-run
+  migrate-catalogs-v0-to-v1 --delete-catalogsource`,
+	RunE: runMigrateCatalogs,
+}
+
+func init() {
+	rootCmd.Flags().StringVar(&kubeconfig, "kubeconfig", "", "Path to kubeconfig file")
+	rootCmd.Flags().BoolVar(&dryRun, "dry-run", false, "Print what would be created without modifying the cluster")
+	rootCmd.Flags().BoolVar(&deleteCatalogSource, "delete-catalogsource", false, "Delete source CatalogSource after migration (only when no Subscription references it)")
+	rootCmd.Flags().BoolVar(&acknowledgePriorityOverflow, "acknowledge-priority-overflow", false, "Cap out-of-range priority at MaxInt32/MinInt32 and proceed")
+}
+
+func main() {
+	if err := rootCmd.Execute(); err != nil {
+		os.Exit(1)
+	}
+}
+
+func newClient() (client.Client, error) {
+	loadingRules := clientcmd.NewDefaultClientConfigLoadingRules()
+	if kubeconfig != "" {
+		loadingRules.ExplicitPath = kubeconfig
+	}
+
+	kubeConfig := clientcmd.NewNonInteractiveDeferredLoadingClientConfig(
+		loadingRules,
+		&clientcmd.ConfigOverrides{},
+	)
+
+	restConfig, err := kubeConfig.ClientConfig()
+	if err != nil {
+		return nil, fmt.Errorf("failed to get REST config: %w", err)
+	}
+
+	c, err := client.New(restConfig, client.Options{Scheme: scheme})
+	if err != nil {
+		return nil, fmt.Errorf("failed to create client: %w", err)
+	}
+	return c, nil
+}
+
+func runMigrateCatalogs(cmd *cobra.Command, _ []string) error {
+	c, err := newClient()
+	if err != nil {
+		return err
+	}
+
+	cm := catalogmigration.NewCatalogMigrator(c)
+	opts := catalogmigration.CatalogMigratorOptions{
+		DryRun:                      dryRun,
+		DeleteCatalogSource:         deleteCatalogSource,
+		AcknowledgePriorityOverflow: acknowledgePriorityOverflow,
+	}
+
+	if dryRun {
+		fmt.Printf("\n🔍 Dry run — no cluster changes will be made.\n\n")
+	} else {
+		fmt.Printf("\n🔄 Migrating CatalogSources to ClusterCatalogs...\n\n")
+	}
+
+	results, err := cm.MigrateCatalogs(cmd.Context(), opts)
+	if err != nil {
+		return fmt.Errorf("catalog migration failed: %w", err)
+	}
+
+	// Print results grouped by status
+	var created, adopted, skipped, errored, dryResults []catalogmigration.CatalogMigrationResult
+	for _, r := range results {
+		switch r.Status {
+		case "created":
+			created = append(created, r)
+		case "adopted":
+			adopted = append(adopted, r)
+		case "skipped":
+			skipped = append(skipped, r)
+		case "error":
+			errored = append(errored, r)
+		case "dry-run":
+			dryResults = append(dryResults, r)
+		}
+	}
+
+	if len(dryResults) > 0 {
+		fmt.Printf("Would migrate:\n")
+		for _, r := range dryResults {
+			fmt.Printf("  %-40s → %s\n    %s\n",
+				r.CatalogSourceNamespace+"/"+r.CatalogSourceName,
+				r.ClusterCatalogName, r.Reason)
+		}
+	}
+
+	if len(created) > 0 {
+		fmt.Printf("\n✅ Created (%d):\n", len(created))
+		for _, r := range created {
+			fmt.Printf("  ✓ %s/%s → ClusterCatalog/%s\n",
+				r.CatalogSourceNamespace, r.CatalogSourceName, r.ClusterCatalogName)
+		}
+	}
+
+	if len(adopted) > 0 {
+		fmt.Printf("\n✅ Adopted existing (%d):\n", len(adopted))
+		for _, r := range adopted {
+			fmt.Printf("  ✓ %s/%s → ClusterCatalog/%s\n",
+				r.CatalogSourceNamespace, r.CatalogSourceName, r.ClusterCatalogName)
+		}
+	}
+
+	if len(skipped) > 0 {
+		fmt.Printf("\n⏭  Skipped (%d):\n", len(skipped))
+		for _, r := range skipped {
+			fmt.Printf("  - %s/%s: %s\n",
+				r.CatalogSourceNamespace, r.CatalogSourceName, r.Reason)
+		}
+	}
+
+	if len(errored) > 0 {
+		fmt.Printf("\n❌ Errors (%d):\n", len(errored))
+		for _, r := range errored {
+			fmt.Printf("  ✗ %s/%s: %s\n",
+				r.CatalogSourceNamespace, r.CatalogSourceName, r.Reason)
+		}
+		return fmt.Errorf("%d catalog source(s) failed to migrate", len(errored))
+	}
+
+	total := len(created) + len(adopted)
+	if total > 0 {
+		fmt.Printf("\n✅ Done: %d ClusterCatalog(s) ready\n\n", total)
+	} else if dryRun {
+		fmt.Printf("\nDry run complete.\n\n")
+	} else {
+		fmt.Printf("\nNo migratable CatalogSources found.\n\n")
+	}
+
+	return nil
+}

migration/examples/cmd/migrate-operators-v0-to-v1/check.go

@@ -0,0 +1,121 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/operator-framework/library-olm/migration/pkg/migration"
+)
+
+var (
+	checkSubscriptionNamespace string
+	checkAll                   bool
+)
+
+var checkCmd = &cobra.Command{
+	Use:   "check [operator-name]",
+	Short: "Check readiness and compatibility without performing migration",
+	Long: `Runs all pre-migration checks (readiness and compatibility) and reports
+any issues that would prevent migration. Does not modify any cluster resources.
+
+Target is a Subscription name (with -n namespace), or --all to scan the cluster.
+
+Examples:
+  migrate-operators-v0-to-v1 check my-operator -n operators
+  migrate-operators-v0-to-v1 check --all`,
+	Args: cobra.MaximumNArgs(1),
+	RunE: runCheck,
+}
+
+func init() {
+	checkCmd.Flags().StringVarP(&checkSubscriptionNamespace, "namespace", "n", "", "Subscription namespace (required without --all)")
+	checkCmd.Flags().BoolVar(&checkAll, "all", false, "Check all Subscriptions on the cluster")
+}
+
+func runCheck(cmd *cobra.Command, args []string) error { //nolint:nestif
+	if checkAll && len(args) > 0 {
+		return fmt.Errorf("cannot specify both an operator name and --all")
+	}
+	if !checkAll && len(args) == 0 {
+		return fmt.Errorf("specify an operator name or --all")
+	}
+
+	c, restCfg, err := newClient()
+	if err != nil {
+		return err
+	}
+
+	m := migration.NewMigrator(c, restCfg)
+	m.Progress = progressFunc
+	ctx := cmd.Context()
+
+	if checkAll {
+		fmt.Printf("\n%s%s🔎 Scanning all Subscriptions...%s\n", colorBold, colorCyan, colorReset)
+		startProgress()
+		results, err := m.ScanAllSubscriptions(ctx)
+		clearProgress()
+		if err != nil {
+			return fmt.Errorf("scan failed: %w", err)
+		}
+		migration.PrintScanSummary(results, func(format string, a ...interface{}) {
+			fmt.Printf(format, a...)
+		})
+		return nil
+	}
+
+	operatorName := args[0]
+	if checkSubscriptionNamespace == "" {
+		return fmt.Errorf("-n/--namespace is required")
+	}
+
+	fmt.Printf("\n%s%s🔍 Pre-migration checks for %s/%s%s\n", colorBold, colorCyan, checkSubscriptionNamespace, operatorName, colorReset)
+
+	opts := migration.Options{
+		SubscriptionName:      operatorName,
+		SubscriptionNamespace: checkSubscriptionNamespace,
+	}
+	opts.ApplyDefaults()
+
+	sectionHeader("Readiness Checks")
+	readiness, readinessErr := m.CheckReadiness(ctx, opts)
+	if readinessErr != nil {
+		fail(fmt.Sprintf("Could not run readiness checks: %v", readinessErr))
+	} else {
+		printCheckResults(readiness.Checks)
+	}
+
+	sectionHeader("Compatibility Checks")
+	_, csv, _, profileErr := m.GetCSVAndInstallPlan(ctx, opts)
+	if profileErr != nil { //nolint:nestif
+		fail(fmt.Sprintf("Could not profile operator: %v", profileErr))
+	} else {
+		propsJSON := csv.Annotations["operatorframework.io/properties"]
+		compat, compatErr := m.CheckCompatibility(ctx, opts, csv, propsJSON)
+		if compatErr != nil {
+			fail(fmt.Sprintf("Could not run compatibility checks: %v", compatErr))
+		} else {
+			printCheckResults(compat.Checks)
+		}
+
+		sectionHeader("ClusterCatalog Availability")
+		bundleInfo, _ := m.GetBundleInfo(ctx, opts, csv, nil)
+		if bundleInfo != nil {
+			catalogName, catalogErr := m.ResolveClusterCatalog(ctx, bundleInfo, restCfg)
+			if catalogErr != nil {
+				var notFound *migration.PackageNotFoundError
+				if errors.As(catalogErr, &notFound) {
+					warn(fmt.Sprintf("No ClusterCatalog found for package %q — run migrate-catalogs-v0-to-v1 first", bundleInfo.PackageName))
+				} else {
+					warn(fmt.Sprintf("Catalog resolution error: %v", catalogErr))
+				}
+			} else {
+				success(fmt.Sprintf("ClusterCatalog available: %s", catalogName))
+			}
+		}
+	}
+
+	fmt.Println()
+	return nil
+}