Refactor ClusterExtension reconciler to use composable step-based pipeline

Replaces the monolithic 170-line reconcile() method with a flexible
step-based architecture that executes discrete reconciliation phases in
sequence. Each phase (`HandleFinalizers`, `RetrieveRevisionStates`,
`RetrieveRevisionMetadata`, `UnpackBundle`, `ApplyBundle`) is now a standalone
function that can be composed differently for Helm vs Boxcutter workflows.

Changes:
  - Introduce `ReconcileStepFunc` type and `ReconcileSteps` executor
  - Extract reconcile logic into individual step functions in new file
    `clusterextension_reconcile_steps.go`
  - Move `BoxcutterRevisionStatesGetter` to `boxcutter_reconcile_steps.go`
    alongside `MigrateStorage` step
  - Configure step pipelines in `main.go` for each applier type
  - Refactor tests to use functional options pattern for reconciler setup

Author: pedjak

cmd/operator-controller/main.go

@@ -587,6 +587,14 @@ func setupBoxcutter(
 		ActionClientGetter: acg,
 		RevisionGenerator:  rg,
 	}
+	ceReconciler.ReconcileSteps = []controllers.ReconcileStepFunc{
+		controllers.HandleFinalizers(ceReconciler.Finalizers),
+		controllers.MigrateStorage(ceReconciler.StorageMigrator),
+		controllers.RetrieveRevisionStates(ceReconciler.RevisionStatesGetter),
+		controllers.RetrieveRevisionMetadata(ceReconciler.Resolver),
+		controllers.UnpackBundle(ceReconciler.ImagePuller, ceReconciler.ImageCache),
+		controllers.ApplyBundle(ceReconciler.Applier),
+	}
 
 	baseDiscoveryClient, err := discovery.NewDiscoveryClientForConfig(mgr.GetConfig())
 	if err != nil {
@@ -698,6 +706,14 @@ func setupHelm(
 		Manager:                       cm,
 	}
 	ceReconciler.RevisionStatesGetter = &controllers.HelmRevisionStatesGetter{ActionClientGetter: acg}
+	ceReconciler.ReconcileSteps = []controllers.ReconcileStepFunc{
+		controllers.HandleFinalizers(ceReconciler.Finalizers),
+		controllers.RetrieveRevisionStates(ceReconciler.RevisionStatesGetter),
+		controllers.RetrieveRevisionMetadata(ceReconciler.Resolver),
+		controllers.UnpackBundle(ceReconciler.ImagePuller, ceReconciler.ImageCache),
+		controllers.ApplyBundle(ceReconciler.Applier),
+	}
+
 	return nil
 }
 

internal/operator-controller/controllers/boxcutter_reconcile_steps.go

@@ -0,0 +1,95 @@
+/*
+Copyright 2025.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package controllers
+
+import (
+	"cmp"
+	"context"
+	"fmt"
+	"slices"
+
+	apimeta "k8s.io/apimachinery/pkg/api/meta"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+
+	ocv1 "github.com/operator-framework/operator-controller/api/v1"
+	"github.com/operator-framework/operator-controller/internal/operator-controller/labels"
+)
+
+type BoxcutterRevisionStatesGetter struct {
+	Reader client.Reader
+}
+
+func (d *BoxcutterRevisionStatesGetter) GetRevisionStates(ctx context.Context, ext *ocv1.ClusterExtension) (*RevisionStates, error) {
+	// TODO: boxcutter applier has a nearly identical bit of code for listing and sorting revisions
+	//   only difference here is that it sorts in reverse order to start iterating with the most
+	//   recent revisions. We should consolidate to avoid code duplication.
+	existingRevisionList := &ocv1.ClusterExtensionRevisionList{}
+	if err := d.Reader.List(ctx, existingRevisionList, client.MatchingLabels{
+		labels.OwnerNameKey: ext.Name,
+	}); err != nil {
+		return nil, fmt.Errorf("listing revisions: %w", err)
+	}
+	slices.SortFunc(existingRevisionList.Items, func(a, b ocv1.ClusterExtensionRevision) int {
+		return cmp.Compare(a.Spec.Revision, b.Spec.Revision)
+	})
+
+	rs := &RevisionStates{}
+	for _, rev := range existingRevisionList.Items {
+		switch rev.Spec.LifecycleState {
+		case ocv1.ClusterExtensionRevisionLifecycleStateActive,
+			ocv1.ClusterExtensionRevisionLifecycleStatePaused:
+		default:
+			// Skip anything not active or paused, which should only be "Archived".
+			continue
+		}
+
+		// TODO: the setting of these annotations (happens in boxcutter applier when we pass in "revisionAnnotations")
+		//   is fairly decoupled from this code where we get the annotations back out. We may want to co-locate
+		//   the set/get logic a bit better to make it more maintainable and less likely to get out of sync.
+		rm := &RevisionMetadata{
+			Package: rev.Annotations[labels.PackageNameKey],
+			Image:   rev.Annotations[labels.BundleReferenceKey],
+			BundleMetadata: ocv1.BundleMetadata{
+				Name:    rev.Annotations[labels.BundleNameKey],
+				Version: rev.Annotations[labels.BundleVersionKey],
+			},
+		}
+
+		if apimeta.IsStatusConditionTrue(rev.Status.Conditions, ocv1.ClusterExtensionRevisionTypeSucceeded) {
+			rs.Installed = rm
+		} else {
+			rs.RollingOut = append(rs.RollingOut, rm)
+		}
+	}
+
+	return rs, nil
+}
+
+func MigrateStorage(m StorageMigrator) ReconcileStepFunc {
+	return func(ctx context.Context, state *reconcileState, ext *ocv1.ClusterExtension) (*ctrl.Result, error) {
+		objLbls := map[string]string{
+			labels.OwnerKindKey: ocv1.ClusterExtensionKind,
+			labels.OwnerNameKey: ext.GetName(),
+		}
+
+		if err := m.Migrate(ctx, ext, objLbls); err != nil {
+			return nil, fmt.Errorf("migrating storage: %w", err)
+		}
+		return nil, nil
+	}
+}