core: refactor --instance to --extract-yaml (#376)

Extract YAML is more clear and aligns with the schema docs for the
Component Instance field which has an extractYAML kind.  This also
leaves the door open for additional kinds of data extractors which are
almost certainly going to be needed.

api/core/v1alpha5/types.go

@@ -332,13 +332,9 @@ type Instance struct {
 	ExtractYAML ExtractYAML `json:"extractYAML" yaml:"extractYAML"`
 }
 
-// ExtractYAML represents a cue data instance encoded as yaml.  Holos extracts data of
-// this kind using cue [encoding/yaml].
-//
-// If Path refers to a directory, all files in the directory are extracted
-// non-recursively.  Otherwise, path must refer to a file.
-//
-// [yaml.Extract]: https://pkg.go.dev/cuelang.org/go@v0.11.0/encoding/yaml#Extract
+// ExtractYAML represents a cue data instance encoded as yaml. If Path refers to
+// a directory all files in the directory are extracted non-recursively.
+// Otherwise, path must refer to a file.
 type ExtractYAML struct {
 	Path string `json:"path,omitempty" yaml:"path,omitempty"`
 }

internal/builder/instance.go

@@ -18,16 +18,16 @@ import (
 	"github.com/holos-run/holos/internal/util"
 )
 
-// loadYamlFiles loads data files represented by paths.  The files are unified
-// into one value.  If a path element is a directory, all files in the directory
-// are loaded non-recursively.
+// ExtractYAML extracts yaml encoded data from file paths.  The data is unified
+// into one [cue.Value].  If a path element is a directory, all files in the
+// directory are loaded non-recursively.
 //
 // Attribution: https://github.com/cue-lang/cue/issues/3504
-func loadYamlFiles(ctxt *cue.Context, paths []string) (cue.Value, error) {
+func ExtractYAML(ctxt *cue.Context, filepaths []string) (cue.Value, error) {
 	value := ctxt.CompileString("")
-	files := make([]string, 0, 10*len(paths))
+	files := make([]string, 0, 10*len(filepaths))
 
-	for _, path := range paths {
+	for _, path := range filepaths {
 		info, err := os.Stat(path)
 		if err != nil {
 			return value, errors.Wrap(err)
@@ -61,10 +61,11 @@ func loadYamlFiles(ctxt *cue.Context, paths []string) (cue.Value, error) {
 	return value, nil
 }
 
-// LoadInstance loads the cue configuration instance at path.  Additional
-// instances are loaded with the [cue.Context.BuildFile] method, then unified
-// into the configuration instance.
-func LoadInstance(path string, instances []string, tags []string) (*Instance, error) {
+// LoadInstance loads the cue configuration instance at path.  External data
+// file paths are loaded by calling [ExtractYAML] providing filepaths.  The
+// extracted data values are unified with the platform configuration [cue.Value]
+// in the returned [Instance].
+func LoadInstance(path string, filepaths []string, tags []string) (*Instance, error) {
 	root, leaf, err := util.FindRootLeaf(path)
 	if err != nil {
 		return nil, errors.Wrap(err)
@@ -83,7 +84,7 @@ func LoadInstance(path string, instances []string, tags []string) (*Instance, er
 		return nil, errors.Wrap(err)
 	}
 
-	value, err := loadYamlFiles(ctxt, instances)
+	value, err := ExtractYAML(ctxt, filepaths)
 	if err != nil {
 		return nil, errors.Wrap(err)
 	}

internal/cli/render/render.go

@@ -43,8 +43,8 @@ func newPlatform(cfg *holos.Config, feature holos.Flagger) *cobra.Command {
 	cmd.Flags().IntVar(&concurrency, "concurrency", runtime.NumCPU(), "number of components to render concurrently")
 	var platform string
 	cmd.Flags().StringVar(&platform, "platform", "./platform", "platform directory path")
-	var instances holos.StringSlice
-	cmd.Flags().Var(&instances, "instance", "cue instances to unify with the platform")
+	var extractYAMLs holos.StringSlice
+	cmd.Flags().Var(&extractYAMLs, "extract-yaml", "data file paths to extract and unify with the platform config")
 	var selector holos.Selector
 	cmd.Flags().VarP(&selector, "selector", "l", "label selector (e.g. label==string,label!=string)")
 	tagMap := make(holos.TagMap)
@@ -59,7 +59,7 @@ func newPlatform(cfg *holos.Config, feature holos.Flagger) *cobra.Command {
 			log.WarnContext(ctx, fmt.Sprintf(msg, platform))
 		}
 
-		inst, err := builder.LoadInstance(platform, instances, tagMap.Tags())
+		inst, err := builder.LoadInstance(platform, extractYAMLs, tagMap.Tags())
 		if err != nil {
 			return errors.Wrap(err)
 		}
@@ -109,14 +109,14 @@ func newComponent(cfg *holos.Config, feature holos.Flagger) *cobra.Command {
 	cmd.Flags().VarP(&tagMap, "inject", "t", tagHelp)
 	var concurrency int
 	cmd.Flags().IntVar(&concurrency, "concurrency", runtime.NumCPU(), "number of concurrent build steps")
-	var instances holos.StringSlice
-	cmd.Flags().Var(&instances, "instance", "cue instances to unify with the platform")
+	var extractYAMLs holos.StringSlice
+	cmd.Flags().Var(&extractYAMLs, "extract-yaml", "data file paths to extract and unify with the platform config")
 
 	cmd.RunE = func(cmd *cobra.Command, args []string) error {
 		ctx := cmd.Root().Context()
 		path := args[0]
 
-		inst, err := builder.LoadInstance(path, instances, tagMap.Tags())
+		inst, err := builder.LoadInstance(path, extractYAMLs, tagMap.Tags())
 		if err != nil {
 			return errors.Wrap(err)
 		}

internal/cli/show.go

@@ -30,15 +30,15 @@ func newShowPlatformCmd() (cmd *cobra.Command) {
 
 	var platform string
 	cmd.Flags().StringVar(&platform, "platform", "./platform", "platform directory path")
-	var instances holos.StringSlice
-	cmd.Flags().Var(&instances, "instance", "cue instances to unify with the platform")
+	var extractYAMLs holos.StringSlice
+	cmd.Flags().Var(&extractYAMLs, "extract-yaml", "data file paths to extract and unify with the platform config")
 	var format string
 	cmd.Flags().StringVar(&format, "format", "yaml", "yaml or json format")
 	tagMap := make(holos.TagMap)
 	cmd.Flags().VarP(&tagMap, "inject", "t", "set the value of a cue @tag field from a key=value pair")
 
 	cmd.RunE = func(c *cobra.Command, args []string) (err error) {
-		inst, err := builder.LoadInstance(platform, instances, tagMap.Tags())
+		inst, err := builder.LoadInstance(platform, extractYAMLs, tagMap.Tags())
 		if err != nil {
 			return errors.Wrap(err)
 		}
@@ -66,8 +66,8 @@ func newShowBuildPlanCmd() (cmd *cobra.Command) {
 
 	var platform string
 	cmd.Flags().StringVar(&platform, "platform", "./platform", "platform directory path")
-	var instances holos.StringSlice
-	cmd.Flags().Var(&instances, "instance", "cue instances to unify with the platform")
+	var extractYAMLs holos.StringSlice
+	cmd.Flags().Var(&extractYAMLs, "extract-yaml", "data file paths to extract and unify with the platform config")
 	var format string
 	cmd.Flags().StringVar(&format, "format", "yaml", "yaml or json format")
 	var selector holos.Selector
@@ -79,7 +79,7 @@ func newShowBuildPlanCmd() (cmd *cobra.Command) {
 
 	cmd.RunE = func(c *cobra.Command, args []string) (err error) {
 		path := platform
-		inst, err := builder.LoadInstance(path, instances, tagMap.Tags())
+		inst, err := builder.LoadInstance(path, extractYAMLs, tagMap.Tags())
 		if err != nil {
 			return errors.Wrap(err)
 		}