feat: add crossplane function KCL utilities package

Signed-off-by: suin <[email protected]>

Author: suin

crossplane_function_kcl_utils/README.md

@@ -0,0 +1,51 @@
+# crossplane_function_kcl_utils
+
+A KCL package that provides schemas and utility functions for writing safer and more productive Crossplane Functions in KCL. This module enhances type safety and IDE support when working with function-kcl.
+
+## Installation
+
+To install this package, run the following command:
+
+```bash
+kcl mod add oci://ghcr.io/appthrust/kcl/crossplane_function_kcl_utils
+```
+
+## Usage
+
+### get_params()
+
+The `get_params()` function provides type-safe access to the function pipeline's parameters. While `option("params")` returns `any` type, this function returns a strongly-typed `Params` schema.
+
+```python kcl
+import crossplane_function_kcl_utils as utils
+
+# Get type-safe params
+params = utils.get_params()
+
+# Access params with IDE support
+print(params.oxr)        # Observed composite resource
+print(params.ocds)       # Observed composed resources
+print(params.dxr)        # Desired composite resource
+print(params.dcds)       # Desired composed resources
+print(params.ctx)        # Pipeline context
+print(params.extraResources)  # Extra resources
+```
+
+### Params Schema
+
+The `Params` schema provides a type-safe structure for function pipeline parameters:
+
+```python kcl
+schema Params:
+    """
+    Params are the input parameters for the function pipeline.
+    """
+    oxr: Resource           # Observed composite resource (XR)
+    ocds: {str:Composite}   # Observed composed resources
+    dxr: Resource          # Desired composite resource (XR)
+    dcds: {str:Composite}   # Desired composed resources
+    ctx: any               # Function pipeline's context
+    extraResources: {str:[Composite]}  # Extra resources
+```
+
+Note: A composed resource can be a managed resource, ProviderConfig, composite resource, or any other Crossplane resource.

crossplane_function_kcl_utils/kcl.mod

@@ -0,0 +1,4 @@
+[package]
+name = "crossplane_function_kcl_utils"
+edition = "v0.10.0"
+version = "0.0.1"

crossplane_function_kcl_utils/kcl.mod.lock

@@ -0,0 +1,71 @@
+"""
+This module provides schemas and utility functions for writing safer and more productive Crossplane Functions in KCL.
+"""
+type Resource = any
+
+schema Composite:
+    """A composed resource in Crossplane."""
+    Resource: Resource
+
+schema Params:
+    """
+    Params are the input parameters for the function pipeline.
+
+    Attributes
+    ----------
+    oxr : Resource, default is None
+        Observed composite resource (XR).
+    ocds : {str:Composite}, default is None
+        Key-value of the observed state of a composed resource. The key is the name of the composed resource.
+        Note: A composed resource is not just a managed resource - it can also be a ProviderConfig, another composite resource, or any other Crossplane resource.
+    dxr : Resource, default is None
+        Desired composite resource (XR).
+    dcds : {str:Composite}, default is None
+        Key-value of the desired state of a composed resource. The key is the name of the composed resource.
+        Note: A composed resource is not just a managed resource - it can also be a ProviderConfig, another composite resource, or any other Crossplane resource.
+    ctx : any, default is None
+        Function pipeline's context
+    extraResources : {str:[Composite]}, default is None
+        Extra resources. The key is the name of the resource and the value is a list of resources.
+
+    Examples
+    --------
+    params = get_params()
+    print(params.oxr)
+    print(params.ocds)
+    print(params.dxr)
+    print(params.dcds)
+    print(params.ctx)
+    print(params.extraResources)
+    """
+    oxr: Resource
+    ocds: {str:Composite}
+    dxr: Resource
+    dcds: {str:Composite}
+    ctx: any
+    extraResources: {str:[Composite]}
+
+get_params = lambda -> Params {
+    """
+    Get type-safe access to the function pipeline's parameters.
+    
+    Returns
+    -------
+    Params
+        A strongly-typed Params schema containing the function pipeline's parameters.
+    
+    Examples
+    --------
+    params = get_params()
+    xr = params.oxr  # Type-safe access to observed XR
+    """
+    params = option("params")
+    Params {
+        oxr = params.oxr
+        ocds = params.ocds
+        dxr = params.dxr
+        dcds = params.dcds
+        ctx = params.ctx
+        extraResources = params.extraResources
+    }
+}