Add a description field for zarf variable / constant declarations (#844)

docs/4-user-guide/3-zarf-schema.md

@@ -1420,6 +1420,21 @@ Must be one of:
 </blockquote>
 </details>
 
+<details>
+<summary><strong> <a name="variables_items_description"></a>description</strong>
+
+</summary>
+&nbsp;
+<blockquote>
+
+**Description:** A description of the variable to be used when prompting the user a value
+
+| Type | `string` |
+| ---- | -------- |
+
+</blockquote>
+</details>
+
 <details>
 <summary><strong> <a name="variables_items_default"></a>default</strong>
 
@@ -1518,6 +1533,21 @@ Must be one of:
 </blockquote>
 </details>
 
+<details>
+<summary><strong> <a name="constants_items_description"></a>description</strong>
+
+</summary>
+&nbsp;
+<blockquote>
+
+**Description:** A description of the constant to explain its purpose on package create or deploy confirmation prompts
+
+| Type | `string` |
+| ---- | -------- |
+
+</blockquote>
+</details>
+
 </blockquote>
 </details>
 

examples/package-variables/README.md

@@ -24,6 +24,7 @@ In the zarf.yaml you would add the name of the variable in the `variables` secti
 ```yaml
 variables:
   name: DATABASE_USERNAME
+  description: "The username for the database"
 ```
 
 :::note

examples/package-variables/zarf.yaml

@@ -14,6 +14,7 @@ variables:
   - name: "DOG"
     default: "woof"
   - name: "CAT"
+    description: "What sound does a cat make?"
     prompt: true
   - name: "FOX"
     default: "###ZARF_PKG_VAR_CONFIG_MAP###"

src/config/variables.go

@@ -5,9 +5,9 @@ import (
 	"strings"
 
 	"github.com/AlecAivazis/survey/v2"
+	"github.com/defenseunicorns/zarf/src/internal/message"
 	"github.com/defenseunicorns/zarf/src/internal/utils"
 	"github.com/defenseunicorns/zarf/src/types"
-	"github.com/pterm/pterm"
 )
 
 // FillActiveTemplate handles setting the active variables and reloading the base template.
@@ -25,7 +25,9 @@ func FillActiveTemplate() error {
 
 	for key, value := range packageVariables {
 		if value == nil && !CommonOptions.Confirm {
-			setVal, err := promptVariable(key, "")
+			setVal, err := promptVariable(types.ZarfPackageVariable{
+				Name: key,
+			})
 
 			if err == nil {
 				packageVariables[key] = &setVal
@@ -64,7 +66,7 @@ func SetActiveVariables() error {
 		// Variable is set to prompt the user
 		if variable.Prompt && !CommonOptions.Confirm {
 			// Prompt the user for the variable
-			val, err := promptVariable(variable.Name, variable.Default)
+			val, err := promptVariable(variable)
 
 			if err != nil {
 				return err
@@ -105,17 +107,18 @@ func InjectImportedConstant(importedConstant types.ZarfPackageConstant) {
 	}
 }
 
-func promptVariable(varName string, varDefault string) (string, error) {
-	var value string
+func promptVariable(variable types.ZarfPackageVariable) (value string, err error) {
 
-	pterm.Println()
+	if variable.Description != "" {
+		message.Question(variable.Description)
+	}
 
 	prompt := &survey.Input{
-		Message: "Please provide a value for '" + varName + "'",
-		Default: varDefault,
+		Message: fmt.Sprintf("Please provide a value for \"%s\"", variable.Name),
+		Default: variable.Default,
 	}
 
-	if err := survey.AskOne(prompt, &value); err != nil {
+	if err = survey.AskOne(prompt, &value); err != nil {
 		return "", err
 	}
 

src/types/package.go

@@ -31,15 +31,18 @@ type ZarfBuildData struct {
 	Version      string `json:"version"`
 }
 
-// ZarfPackageVariable are variables that can be used to dynaically template K8s resources.
+// ZarfPackageVariable are variables that can be used to dynamically template K8s resources.
 type ZarfPackageVariable struct {
-	Name    string `json:"name" jsonschema:"description=The name to be used for the variable,pattern=^[A-Z_]+$"`
-	Default string `json:"default,omitempty" jsonschema:"description=The default value to use for the variable"`
-	Prompt  bool   `json:"prompt,omitempty" jsonschema:"description=Whether to prompt the user for input for this variable"`
+	Name        string `json:"name" jsonschema:"description=The name to be used for the variable,pattern=^[A-Z_]+$"`
+	Description string `json:"description,omitempty" jsonschema:"description=A description of the variable to be used when prompting the user a value"`
+	Default     string `json:"default,omitempty" jsonschema:"description=The default value to use for the variable"`
+	Prompt      bool   `json:"prompt,omitempty" jsonschema:"description=Whether to prompt the user for input for this variable"`
 }
 
-// ZarfPackageConstant are constants that can be used to dynaically template K8s resources.
+// ZarfPackageConstant are constants that can be used to dynamically template K8s resources.
 type ZarfPackageConstant struct {
 	Name  string `json:"name" jsonschema:"description=The name to be used for the constant,pattern=^[A-Z_]+$"`
 	Value string `json:"value" jsonschema:"description=The value to set for the constant during deploy"`
+	// Include a description that will only be displayed during package create/deploy confirm prompts
+	Description string `json:"description,omitempty" jsonschema:"description=A description of the constant to explain its purpose on package create or deploy confirmation prompts"`
 }

src/ui/lib/api-types.ts

@@ -338,6 +338,11 @@ export interface ZarfComponentScripts {
 }
 
 export interface ZarfPackageConstant {
+    /**
+     * A description of the constant to explain its purpose on package create or deploy
+     * confirmation prompts
+     */
+    description?: string;
     /**
      * The name to be used for the constant
      */
@@ -395,6 +400,10 @@ export interface ZarfPackageVariable {
      * The default value to use for the variable
      */
     default?: string;
+    /**
+     * A description of the variable to be used when prompting the user a value
+     */
+    description?: string;
     /**
      * The name to be used for the variable
      */
@@ -855,6 +864,7 @@ const typeMap: any = {
         { json: "timeoutSeconds", js: "timeoutSeconds", typ: u(undefined, 0) },
     ], false),
     "ZarfPackageConstant": o([
+        { json: "description", js: "description", typ: u(undefined, "") },
         { json: "name", js: "name", typ: "" },
         { json: "value", js: "value", typ: "" },
     ], false),
@@ -869,6 +879,7 @@ const typeMap: any = {
     ], false),
     "ZarfPackageVariable": o([
         { json: "default", js: "default", typ: u(undefined, "") },
+        { json: "description", js: "description", typ: u(undefined, "") },
         { json: "name", js: "name", typ: "" },
         { json: "prompt", js: "prompt", typ: u(undefined, true) },
     ], false),

zarf.schema.json

@@ -512,6 +512,10 @@
         "value": {
           "type": "string",
           "description": "The value to set for the constant during deploy"
+        },
+        "description": {
+          "type": "string",
+          "description": "A description of the constant to explain its purpose on package create or deploy confirmation prompts"
         }
       },
       "additionalProperties": false,
@@ -527,6 +531,10 @@
           "type": "string",
           "description": "The name to be used for the variable"
         },
+        "description": {
+          "type": "string",
+          "description": "A description of the variable to be used when prompting the user a value"
+        },
         "default": {
           "type": "string",
           "description": "The default value to use for the variable"