feat(claimtoxr): add Options API with Name and UID

Replace ConvertClaimToXR's args with an Options struct, adding two new
ones:

- Name: explicit XR name, overrides the direct-mode default (Claim name)
  or the non-direct random suffix
- GenerateUID: set `metadata.uid` via `uuid.NewUUID()`

Existing Kind and Direct arguments are unchanged. The runner's call site
uses Options{} (without values) matching the previous behavior.

Also, the function now reutnrs `*composite.Unstructured` rather thant
`*unstructured.Unstructured`, since the produced object is conceptually
a Composite Resource. YAML/JSON marshaling continues to work via the
embedded `unstructured.Unstructured`.

The `xprin-helpers convert-claim-to-xr` command exposes the new options
as `--name` and `--gen-uid` flags. Documentation is updated accordingly.

Signed-off-by: Theo Chatzimichos <tampakrap@gmail.com>

Author: tampakrap

cmd/xprin-helpers/claimtoxr/cmd.go

@@ -37,9 +37,11 @@ type Cmd struct {
 	InputFile string `arg:"" default:"-" help:"The Claim YAML file to be converted. If not specified or '-', stdin will be used." optional:"" predictor:"file" type:"path"`
 
 	// Flags.
-	OutputFile string `help:"The file to write the generated XR YAML to. If not specified, stdout will be used."                              placeholder:"PATH" predictor:"file" short:"o" type:"path"`
-	Kind       string `help:"The kind to use for the XR. If not specified, 'X' will be prepended to the Claim's kind (e.g. Infra -> XInfra)." placeholder:"KIND" type:"string"`
-	Direct     bool   `help:"Create a direct XR without Claim references and suffix."                                                         name:"direct"      negatable:""`
+	OutputFile string `help:"The file to write the generated XR YAML to. If not specified, stdout will be used."                                                      placeholder:"PATH" predictor:"file" short:"o" type:"path"`
+	Name       string `help:"The name to use for the XR. If empty, defaults to the Claim's name (direct mode) or the Claim's name with a random suffix (non-direct)." placeholder:"NAME" type:"string"`
+	Kind       string `help:"The kind to use for the XR. If not specified, 'X' will be prepended to the Claim's kind (e.g. Infra -> XInfra)."                         placeholder:"KIND" type:"string"`
+	Direct     bool   `help:"Create a direct XR without Claim references and suffix."                                                                                 name:"direct"      negatable:""`
+	GenUID     bool   `help:"Set a fresh random metadata.uid on the generated XR."                                                                                    name:"gen-uid"`
 
 	fs afero.Fs
 }
@@ -50,26 +52,32 @@ func (c *Cmd) Help() string {
 Convert a Crossplane Claim YAML file to a Crossplane Composite Resource (XR) format.
 
 This command will:
-- Read the Claim from the provided YAML file
-- Create an XR with the same spec as the Claim
-- Set appropriate API version and kind for the XR
-- Set up the Claim reference in the XR (unless --direct is used)
-- Copy any composition selector
+  - Read the Claim from the provided YAML file
+  - Create an XR with the same spec as the Claim
+  - Set appropriate API version and kind for the XR
+  - Set up the Claim reference in the XR (unless --direct is used)
+  - Copy any composition selector
 
 Examples:
 
   # Convert claim.yaml to XR format and write to stdout (kind will be 'X' + Claim's kind)
   xprin-helpers convert-claim-to-xr claim.yaml
 
-  # Convert claim.yaml to XR format with a specific kind
-  xprin-helpers convert-claim-to-xr claim.yaml --kind MyCompositeResource
-
   # Convert claim.yaml to XR format and write to xr.yaml
   xprin-helpers convert-claim-to-xr claim.yaml -o xr.yaml
 
+  # Convert claim.yaml using an explicit XR name (overrides the default suffix or claim name)
+  xprin-helpers convert-claim-to-xr claim.yaml --name my-xr
+
+  # Convert claim.yaml to XR format with a specific kind
+  xprin-helpers convert-claim-to-xr claim.yaml --kind MyCompositeResource
+
   # Convert claim.yaml to a directly created XR (no Claim references, no name suffix)
   xprin-helpers convert-claim-to-xr claim.yaml --direct
 
+  # Convert claim.yaml and assign a fresh random metadata.uid to the XR
+  xprin-helpers convert-claim-to-xr claim.yaml --gen-uid
+
   # Convert Claim from stdin to XR format
   cat claim.yaml | xprin-helpers convert-claim-to-xr -
 `
@@ -94,7 +102,12 @@ func (c *Cmd) Run(k *kong.Context) error {
 	}
 
 	// Convert to XR
-	xr, err := ConvertClaimToXR(claim, c.Kind, c.Direct)
+	xr, err := ConvertClaimToXR(claim, Options{
+		Name:        c.Name,
+		Kind:        c.Kind,
+		Direct:      c.Direct,
+		GenerateUID: c.GenUID,
+	})
 	if err != nil {
 		return errors.Wrap(err, "failed to convert Claim to XR")
 	}

cmd/xprin-helpers/claimtoxr/converter.go

@@ -19,6 +19,7 @@ package claimtoxr
 import (
 	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
 	"k8s.io/apimachinery/pkg/runtime/schema"
+	"k8s.io/apimachinery/pkg/util/uuid"
 	"k8s.io/apiserver/pkg/storage/names"
 
 	"github.com/crossplane/crossplane-runtime/v2/pkg/errors"
@@ -41,8 +42,28 @@ const (
 	labelComposite      = "crossplane.io/composite"
 )
 
+// Options configures ConvertClaimToXR.
+type Options struct {
+	// Name is the XR name. Empty falls back to:
+	//   - claim.Name when Direct is true
+	//   - claim.Name with a random suffix when Direct is false
+	// A non-empty Name overrides both fallbacks.
+	Name string
+
+	// Kind is the XR kind. Empty defaults to "X" + claim.Kind.
+	Kind string
+
+	// Direct controls XR linkage to the claim:
+	//   - true:  no spec.claimRef; no claim-name/claim-namespace labels
+	//   - false: spec.claimRef is set; claim-name/claim-namespace labels added
+	Direct bool
+
+	// GenerateUID, when true, sets metadata.uid to a fresh random UUID.
+	GenerateUID bool
+}
+
 // ConvertClaimToXR converts a Crossplane Claim to a Composite Resource (XR).
-func ConvertClaimToXR(claim *unstructured.Unstructured, kind string, direct bool) (*unstructured.Unstructured, error) {
+func ConvertClaimToXR(claim *unstructured.Unstructured, opts Options) (*composite.Unstructured, error) {
 	if claim == nil {
 		return nil, errors.New(errNilInput)
 	}
@@ -92,7 +113,8 @@ func ConvertClaimToXR(claim *unstructured.Unstructured, kind string, direct bool
 		return nil, errors.Wrap(err, "failed to set apiVersion")
 	}
 
-	// Set XR kind - either from flag or by prepending X to Claim's kind
+	// Set XR kind - either from opts or by prepending X to Claim's kind
+	kind := opts.Kind
 	if kind == "" {
 		kind = "X" + claimKind
 	}
@@ -113,7 +135,7 @@ func ConvertClaimToXR(claim *unstructured.Unstructured, kind string, direct bool
 
 	xrName := claimName
 
-	if !direct {
+	if !opts.Direct {
 		xrName = names.SimpleNameGenerator.GenerateName(claimName + "-")
 		labels[labelClaimName] = claim.GetName()
 
@@ -128,6 +150,11 @@ func ConvertClaimToXR(claim *unstructured.Unstructured, kind string, direct bool
 		}
 	}
 
+	// Explicit Name overrides both Direct's claim-name default and the generated suffix.
+	if opts.Name != "" {
+		xrName = opts.Name
+	}
+
 	if err := xrPaved.SetString("metadata.name", xrName); err != nil {
 		return nil, errors.Wrap(err, "failed to set name")
 	}
@@ -140,6 +167,9 @@ func ConvertClaimToXR(claim *unstructured.Unstructured, kind string, direct bool
 		}
 	}
 
-	// Convert from composite.Unstructured to unstructured.Unstructured
-	return &unstructured.Unstructured{Object: xr.UnstructuredContent()}, nil
+	if opts.GenerateUID {
+		xr.SetUID(uuid.NewUUID())
+	}
+
+	return xr, nil
 }