✨ Add alpha update command for 3-way project upgrade

This commit introduces the `kubebuilder alpha update` command, which enables users to upgrade their Kubebuilder projects via a 3-way Git merge strategy.

The update flow:
- Creates an 'ancestor' branch based on the original scaffold version
- Extracts the user's current project state into a 'current' branch
- Generates a fresh scaffold using the target version in the 'upgrade' branch
- Merges changes into a 'merge' branch, preserving user code and applying updates

This mechanism allows users to safely adopt new scaffolding and maintain their custom logic with minimal manual effort.

Author: vitorfloriano

pkg/cli/alpha.go

@@ -31,6 +31,7 @@ const (
 var alphaCommands = []*cobra.Command{
 	newAlphaCommand(),
 	alpha.NewScaffoldCommand(),
+	alpha.NewUpdateCommand(),
 }
 
 func newAlphaCommand() *cobra.Command {

pkg/cli/alpha/internal/common/common.go

@@ -0,0 +1,53 @@
+/*
+Copyright 2025 The Kubernetes Authors.
+
+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 common
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/spf13/afero"
+
+	"sigs.k8s.io/kubebuilder/v4/pkg/config/store"
+	"sigs.k8s.io/kubebuilder/v4/pkg/config/store/yaml"
+	"sigs.k8s.io/kubebuilder/v4/pkg/machinery"
+)
+
+// LoadProjectConfig load the project config.
+func LoadProjectConfig(inputDir string) (store.Store, error) {
+	projectConfig := yaml.New(machinery.Filesystem{FS: afero.NewOsFs()})
+	if err := projectConfig.LoadFrom(fmt.Sprintf("%s/%s", inputDir, yaml.DefaultPath)); err != nil {
+		return nil, fmt.Errorf("failed to load PROJECT file: %w", err)
+	}
+	return projectConfig, nil
+}
+
+// GetInputPath will return the input path for the project.
+func GetInputPath(inputPath string) (string, error) {
+	if inputPath == "" {
+		cwd, err := os.Getwd()
+		if err != nil {
+			return "", fmt.Errorf("failed to get working directory: %w", err)
+		}
+		inputPath = cwd
+	}
+	projectPath := fmt.Sprintf("%s/%s", inputPath, yaml.DefaultPath)
+	if _, err := os.Stat(projectPath); os.IsNotExist(err) {
+		return "", fmt.Errorf("project path %q does not exist: %w", projectPath, err)
+	}
+	return inputPath, nil
+}

pkg/cli/alpha/internal/generate.go

@@ -23,13 +23,12 @@ import (
 	"os/exec"
 	"strings"
 
+	"sigs.k8s.io/kubebuilder/v4/pkg/cli/alpha/internal/common"
+
 	log "github.com/sirupsen/logrus"
 
-	"github.com/spf13/afero"
 	"sigs.k8s.io/kubebuilder/v4/pkg/config"
 	"sigs.k8s.io/kubebuilder/v4/pkg/config/store"
-	"sigs.k8s.io/kubebuilder/v4/pkg/config/store/yaml"
-	"sigs.k8s.io/kubebuilder/v4/pkg/machinery"
 	"sigs.k8s.io/kubebuilder/v4/pkg/model/resource"
 	"sigs.k8s.io/kubebuilder/v4/pkg/plugin"
 	"sigs.k8s.io/kubebuilder/v4/pkg/plugin/util"
@@ -46,9 +45,9 @@ type Generate struct {
 
 // Generate handles the migration and scaffolding process.
 func (opts *Generate) Generate() error {
-	projectConfig, err := loadProjectConfig(opts.InputDir)
+	projectConfig, err := common.LoadProjectConfig(opts.InputDir)
 	if err != nil {
-		return err
+		return fmt.Errorf("error loading project config: %v", err)
 	}
 
 	if opts.OutputDir == "" {
@@ -138,7 +137,7 @@ func (opts *Generate) Generate() error {
 // Validate ensures the options are valid and kubebuilder is installed.
 func (opts *Generate) Validate() error {
 	var err error
-	opts.InputDir, err = getInputPath(opts.InputDir)
+	opts.InputDir, err = common.GetInputPath(opts.InputDir)
 	if err != nil {
 		return fmt.Errorf("error getting input path %q: %w", opts.InputDir, err)
 	}
@@ -151,15 +150,6 @@ func (opts *Generate) Validate() error {
 	return nil
 }
 
-// Helper function to load the project configuration.
-func loadProjectConfig(inputDir string) (store.Store, error) {
-	projectConfig := yaml.New(machinery.Filesystem{FS: afero.NewOsFs()})
-	if err := projectConfig.LoadFrom(fmt.Sprintf("%s/%s", inputDir, yaml.DefaultPath)); err != nil {
-		return nil, fmt.Errorf("failed to load PROJECT file: %w", err)
-	}
-	return projectConfig, nil
-}
-
 // Helper function to create the output directory.
 func createDirectory(outputDir string) error {
 	if err := os.MkdirAll(outputDir, 0o755); err != nil {
@@ -276,22 +266,6 @@ func createAPIWithDeployImage(resourceData v1alpha1.ResourceData) error {
 	return nil
 }
 
-// Helper function to get input path.
-func getInputPath(inputPath string) (string, error) {
-	if inputPath == "" {
-		cwd, err := os.Getwd()
-		if err != nil {
-			return "", fmt.Errorf("failed to get working directory: %w", err)
-		}
-		inputPath = cwd
-	}
-	projectPath := fmt.Sprintf("%s/%s", inputPath, yaml.DefaultPath)
-	if _, err := os.Stat(projectPath); os.IsNotExist(err) {
-		return "", fmt.Errorf("project path %q does not exist: %w", projectPath, err)
-	}
-	return inputPath, nil
-}
-
 // Helper function to get Init arguments for Kubebuilder.
 func getInitArgs(s store.Store) []string {
 	var args []string