amp: when conditional

Author: Gjergj

AGENTS.md

@@ -3770,6 +3770,47 @@ tasks:
 - If inventory file is not found, dibra errors
 - Circular group references are detected and reported
 
+## when
+
+Conditionally executes a task. The condition is evaluated against the same variable context used for templates (`vars`, `hostvars`, `inventory_hostname`, `group_names`, registered results, etc.). If the condition resolves to false, the task is skipped. If the condition cannot be evaluated, the task fails.
+
+**Syntax**:
+- String expression using Jinja-style syntax (`==`, `!=`, `>`, `>=`, `<`, `<=`, `and`, `or`, `not`, `in`, `is defined`, filters like `default`, `length`)
+- Boolean literal (`true`/`false`)
+- Number (`0` is false, non-zero is true)
+- List of conditions (all must be true)
+
+```yaml
+- name: Run only on web hosts
+  copy:
+    content: "web"
+    dest: /tmp/web.txt
+  when: '"web" in group_names'
+
+- name: Multiple conditions (AND)
+  copy:
+    content: "ready"
+    dest: /tmp/ready.txt
+  when:
+    - app.enabled
+    - (app.port | int) > 1024
+
+- name: Use filters
+  copy:
+    content: "fallback"
+    dest: /tmp/fallback.txt
+  when: (missing_value | default("fallback")) == "fallback"
+
+- name: Boolean literal
+  ping:
+  when: true
+```
+
+**Behavior**:
+- Skipped tasks report `skipped: true`, `changed: false`, and `msg: "when condition false"` in register results.
+- `include_tasks`: if the `when` condition is false, no tasks are included.
+- `import_tasks`: parent `when` conditions are merged with imported task conditions (logical AND).
+
 ## import_tasks
 
 Imports a list of tasks from another YAML file, inserting them into the current playbook at parse time (static include). This is a controller-side directive, not a remote module.

cmd/controller/main.go

@@ -47,6 +47,7 @@ type ModuleRequest struct {
 type GenericResponse struct {
 	Changed  bool     `json:"changed"`
 	Failed   bool     `json:"failed"`
+	Skipped  bool     `json:"skipped"`
 	Msg      string   `json:"msg,omitempty"`
 	RC       int      `json:"rc"`
 	Stdout   string   `json:"stdout,omitempty"`
@@ -461,6 +462,31 @@ func main() {
 			hostContext["vars"] = resolved.Namespaces
 			flattened := hostContext
 
+			if len(task.When) > 0 {
+				shouldRun, err := template.EvaluateWhen([]interface{}(task.When), flattened)
+				if err != nil {
+					fmt.Printf("    ✗ FAILED: when condition error: %v\n", err)
+					if task.Register != "" {
+						registerResult(hostRuntimeVars, host.Name, task, map[string]interface{}{
+							"failed": true,
+							"msg":    fmt.Sprintf("when condition error: %v", err),
+						})
+					}
+					continue
+				}
+				if !shouldRun {
+					fmt.Printf("    ↷ SKIPPED (when condition false)\n")
+					if task.Register != "" {
+						registerResult(hostRuntimeVars, host.Name, task, map[string]interface{}{
+							"changed": false,
+							"skipped": true,
+							"msg":     "when condition false",
+						})
+					}
+					continue
+				}
+			}
+
 			var modReq ModuleRequest
 
 			switch {
@@ -2383,7 +2409,13 @@ func main() {
 				continue
 			}
 
-			if resp.Failed {
+			if resp.Skipped {
+				fmt.Printf("    ↷ SKIPPED")
+				if resp.Msg != "" {
+					fmt.Printf(" - %s", resp.Msg)
+				}
+				fmt.Println()
+			} else if resp.Failed {
 				fmt.Printf("    ✗ FAILED: %s\n", resp.Msg)
 				if *verbose && resp.Stderr != "" {
 					fmt.Printf("    Stderr: %s\n", resp.Stderr)
@@ -2496,6 +2528,7 @@ func genericResponseToMap(resp GenericResponse) map[string]interface{} {
 	result := map[string]interface{}{
 		"changed": resp.Changed,
 		"failed":  resp.Failed,
+		"skipped": resp.Skipped,
 		"rc":      resp.RC,
 		"msg":     resp.Msg,
 		"stdout":  resp.Stdout,

cue/schema/base.cue

@@ -19,11 +19,12 @@ package schema
 }
 
 #Task: {
-	name:      string
-	register?: string
-	vars?: {[string]: _}
-	import_tasks?: string | #ImportTasks
-	include_tasks?: string | #IncludeTasks
+        name:      string
+        register?: string
+        vars?: {[string]: _}
+        when?: string | bool | number | [...(string|bool|number)]
+        import_tasks?: string | #ImportTasks
+        include_tasks?: string | #IncludeTasks
 
 	{ping:                     #Ping} |
 	{apt:                      #Apt} |

internal/config/config.go

@@ -2,6 +2,7 @@ package config
 
 import (
 	"bytes"
+	"encoding/json"
 	"fmt"
 	"os"
 	"reflect"
@@ -67,9 +68,70 @@ func (p *IncludeTasksParams) UnmarshalYAML(node *yaml.Node) error {
 	return nil
 }
 
+type When []interface{}
+
+func (w *When) UnmarshalYAML(node *yaml.Node) error {
+	var raw interface{}
+	if err := node.Decode(&raw); err != nil {
+		return err
+	}
+	normalized, err := normalizeWhenValue(raw)
+	if err != nil {
+		return err
+	}
+	*w = normalized
+	return nil
+}
+
+func (w *When) UnmarshalJSON(data []byte) error {
+	var raw interface{}
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return err
+	}
+	normalized, err := normalizeWhenValue(raw)
+	if err != nil {
+		return err
+	}
+	*w = normalized
+	return nil
+}
+
+func normalizeWhenValue(raw interface{}) (When, error) {
+	if raw == nil {
+		return nil, nil
+	}
+
+	switch v := raw.(type) {
+	case When:
+		return v, nil
+	case string, bool, int, int32, int64, float32, float64, uint, uint32, uint64:
+		return When{v}, nil
+	case []string:
+		normalized := make(When, len(v))
+		for i, item := range v {
+			normalized[i] = item
+		}
+		return normalized, nil
+	case []interface{}:
+		normalized := make(When, len(v))
+		for i, item := range v {
+			switch item.(type) {
+			case string, bool, int, int32, int64, float32, float64, uint, uint32, uint64:
+				normalized[i] = item
+			default:
+				return nil, fmt.Errorf("when list entries must be strings, booleans, or numbers")
+			}
+		}
+		return normalized, nil
+	default:
+		return nil, fmt.Errorf("when must be a string, boolean, number, or list")
+	}
+}
+
 type Task struct {
 	Name                    string                         `json:"name" yaml:"name"`
 	Vars                    map[string]interface{}         `json:"vars,omitempty" yaml:"vars,omitempty"`
+	When                    When                           `json:"when,omitempty" yaml:"when,omitempty"`
 	ImportTasks             *ImportTasksParams             `json:"import_tasks,omitempty" yaml:"import_tasks,omitempty"`
 	IncludeTasks            *IncludeTasksParams            `json:"include_tasks,omitempty" yaml:"include_tasks,omitempty"`
 	SourceDir               string                         `yaml:"-"`
@@ -135,24 +197,24 @@ type Task struct {
 }
 
 type TemplateParams struct {
-	Src                string `json:"src" yaml:"src"`
-	Dest               string `json:"dest" yaml:"dest"`
-	Mode               string `json:"mode,omitempty" yaml:"mode,omitempty"`
-	Owner              string `json:"owner,omitempty" yaml:"owner,omitempty"`
-	Group              string `json:"group,omitempty" yaml:"group,omitempty"`
-	Backup             bool   `json:"backup" yaml:"backup"`
-	Force              *bool  `json:"force,omitempty" yaml:"force,omitempty"`
-	Follow             bool   `json:"follow" yaml:"follow"`
-	Validate           string `json:"validate,omitempty" yaml:"validate,omitempty"`
-	NewlineSequence    string `json:"newline_sequence,omitempty" yaml:"newline_sequence,omitempty"`
+	Src                 string `json:"src" yaml:"src"`
+	Dest                string `json:"dest" yaml:"dest"`
+	Mode                string `json:"mode,omitempty" yaml:"mode,omitempty"`
+	Owner               string `json:"owner,omitempty" yaml:"owner,omitempty"`
+	Group               string `json:"group,omitempty" yaml:"group,omitempty"`
+	Backup              bool   `json:"backup" yaml:"backup"`
+	Force               *bool  `json:"force,omitempty" yaml:"force,omitempty"`
+	Follow              bool   `json:"follow" yaml:"follow"`
+	Validate            string `json:"validate,omitempty" yaml:"validate,omitempty"`
+	NewlineSequence     string `json:"newline_sequence,omitempty" yaml:"newline_sequence,omitempty"`
 	VariableStartString string `json:"variable_start_string,omitempty" yaml:"variable_start_string,omitempty"`
 	VariableEndString   string `json:"variable_end_string,omitempty" yaml:"variable_end_string,omitempty"`
 	BlockStartString    string `json:"block_start_string,omitempty" yaml:"block_start_string,omitempty"`
 	BlockEndString      string `json:"block_end_string,omitempty" yaml:"block_end_string,omitempty"`
 	CommentStartString  string `json:"comment_start_string,omitempty" yaml:"comment_start_string,omitempty"`
 	CommentEndString    string `json:"comment_end_string,omitempty" yaml:"comment_end_string,omitempty"`
-	TrimBlocks         *bool  `json:"trim_blocks,omitempty" yaml:"trim_blocks,omitempty"`
-	LstripBlocks       *bool  `json:"lstrip_blocks,omitempty" yaml:"lstrip_blocks,omitempty"`
+	TrimBlocks          *bool  `json:"trim_blocks,omitempty" yaml:"trim_blocks,omitempty"`
+	LstripBlocks        *bool  `json:"lstrip_blocks,omitempty" yaml:"lstrip_blocks,omitempty"`
 }
 
 type DockerSwarmServiceParams struct {
@@ -820,9 +882,9 @@ type DockerImageParams struct {
 	Pull interface{} `json:"pull,omitempty" yaml:"pull,omitempty"` // string (missing/always/never) or bool for backward compat
 
 	// Force flags (separated for clarity)
-	ForcePull   bool `json:"force_pull,omitempty" yaml:"force_pull,omitempty"`   // Force pull even if image exists
+	ForcePull   bool `json:"force_pull,omitempty" yaml:"force_pull,omitempty"`     // Force pull even if image exists
 	ForceRemove bool `json:"force_remove,omitempty" yaml:"force_remove,omitempty"` // Force remove (removes containers using the image)
-	ForceTag    bool `json:"force_tag,omitempty" yaml:"force_tag,omitempty"`    // Force tag even if target exists
+	ForceTag    bool `json:"force_tag,omitempty" yaml:"force_tag,omitempty"`       // Force tag even if target exists
 	ForceSource bool `json:"force_source,omitempty" yaml:"force_source,omitempty"` // Deprecated: use force_pull or force_remove
 
 	// Registry authentication

internal/config/import_tasks.go

@@ -77,6 +77,12 @@ func expandImportTasks(tasks []Task, baseDir string, renderPath func(string) (st
 			}
 		}
 
+		if len(task.When) > 0 {
+			for i := range importedTasks {
+				importedTasks[i].When = mergeWhen(task.When, importedTasks[i].When)
+			}
+		}
+
 		newStack := append(append([]string{}, stack...), absPath)
 		newBaseDir := filepath.Dir(absPath)
 		expanded, err := expandImportTasks(importedTasks, newBaseDir, renderPath, newStack, depth+1)
@@ -90,6 +96,19 @@ func expandImportTasks(tasks []Task, baseDir string, renderPath func(string) (st
 	return result, nil
 }
 
+func mergeWhen(parent When, child When) When {
+	if len(parent) == 0 {
+		return child
+	}
+	if len(child) == 0 {
+		return parent
+	}
+	merged := make(When, 0, len(parent)+len(child))
+	merged = append(merged, parent...)
+	merged = append(merged, child...)
+	return merged
+}
+
 func loadTasksFile(path string) ([]Task, error) {
 	data, err := os.ReadFile(path)
 	if err != nil {