Issues/8 workflow conditionsguards evaluate when during planning

docs/reference/cmdlets/Invoke-IdlePlan.md

@@ -13,7 +13,7 @@ Executes an IdLE plan.
 ## SYNTAX
 
 ```
-Invoke-IdlePlan [-Plan] <Object> [[-Providers] <Object>] [[-EventSink] <Object>]
+Invoke-IdlePlan [-Plan] <Object> [[-Providers] <Hashtable>] [[-EventSink] <Object>]
  [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
@@ -41,15 +41,15 @@ Aliases:
 Required: True
 Position: 1
 Default value: None
-Accept pipeline input: False
+Accept pipeline input: True (ByValue)
 Accept wildcard characters: False
 ```
 
 ### -Providers
 Provider registry/collection passed through to execution.
 
 ```yaml
-Type: Object
+Type: Hashtable
 Parameter Sets: (All)
 Aliases:
 
@@ -129,7 +129,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## OUTPUTS
 
-### System.Object
+### PSCustomObject (PSTypeName: IdLE.ExecutionResult)
 ## NOTES
 
 ## RELATED LINKS

docs/usage/workflows.md

@@ -45,12 +45,12 @@ The host maps step types to step implementations via a step registry.
 
 ## Conditional steps
 
-Steps can be skipped using declarative `When` conditions.
+Steps can be skipped using declarative `Condition` key.
 
 Example:
 
 ```powershell
-When = @{
+Condition = @{
   Path   = 'Plan.LifecycleEvent'
   Equals = 'Joiner'
 }

examples/workflows/joiner-with-condition.psd1

@@ -0,0 +1,32 @@
+@{
+  Name           = 'Joiner - Condition Demo'
+  LifecycleEvent = 'Joiner'
+  Steps          = @(
+    @{
+      Name = 'EmitOnlyForJoiner'
+      Type = 'IdLE.Step.EmitEvent'
+      Condition = @{
+        Equals = @{
+          Path   = 'Plan.LifecycleEvent'
+          Value  = 'Joiner'
+        }
+      }
+      With = @{
+        Message = 'This step runs only if Plan.LifecycleEvent == Joiner.'
+      }
+    }
+    @{
+      Name = 'SkipForJoiner'
+      Type = 'IdLE.Step.EmitEvent'
+      Condition = @{
+        Equals = @{
+          Path   = 'Plan.LifecycleEvent'
+          Value = 'Leaver'
+        }
+      }
+      With = @{
+        Message = 'You should never see this in a Joiner run.'
+      }
+    }
+  )
+}

src/IdLE.Core/Private/Test-IdleCondition.ps1

@@ -0,0 +1,146 @@
+function Test-IdleCondition {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [ValidateNotNull()]
+        [hashtable] $Condition,
+
+        [Parameter(Mandatory)]
+        [ValidateNotNull()]
+        [object] $Context
+    )
+
+    # Evaluates a declarative Condition (data-only) against the provided context.
+    #
+    # Supported schema (validated by Test-IdleConditionSchema):
+    # - Groups: All | Any | None  (each contains an array/list of condition nodes)
+    # - Operators:
+    #   - Equals    = @{ Path = '<path>'; Value  = <value>  }
+    #   - NotEquals = @{ Path = '<path>'; Value  = <value>  }
+    #   - Exists    = '<path>' OR @{ Path = '<path>' }
+    #   - In        = @{ Path = '<path>'; Values = <array|scalar> }
+    #
+    # Paths are resolved via Get-IdleValueByPath against the provided $Context.
+    # For readability in configuration, a leading "context." prefix is ignored.
+
+    $schemaErrors = Test-IdleConditionSchema -Condition $Condition -StepName $null
+    if (@($schemaErrors).Count -gt 0) {
+        $msg = "Condition schema validation failed: {0}" -f ([string]::Join(' ', @($schemaErrors)))
+        throw [System.ArgumentException]::new($msg, 'Condition')
+    }
+
+    function Resolve-IdleConditionPathValue {
+        [CmdletBinding()]
+        param(
+            [Parameter(Mandatory)]
+            [ValidateNotNullOrEmpty()]
+            [string] $Path
+        )
+
+        # Allow "context." prefix for readability in config files.
+        $effectivePath = if ($Path.StartsWith('context.')) { $Path.Substring(8) } else { $Path }
+
+        return Get-IdleValueByPath -Object $Context -Path $effectivePath
+    }
+
+    function Test-IdleConditionNode {
+        [CmdletBinding()]
+        param(
+            [Parameter(Mandatory)]
+            [ValidateNotNull()]
+            [System.Collections.IDictionary] $Node
+        )
+
+        # GROUPS
+        if ($Node.Contains('All')) {
+            foreach ($child in @($Node.All)) {
+                if (-not (Test-IdleConditionNode -Node ([System.Collections.IDictionary]$child))) {
+                    return $false
+                }
+            }
+            return $true
+        }
+
+        if ($Node.Contains('Any')) {
+            foreach ($child in @($Node.Any)) {
+                if (Test-IdleConditionNode -Node ([System.Collections.IDictionary]$child)) {
+                    return $true
+                }
+            }
+            return $false
+        }
+
+        if ($Node.Contains('None')) {
+            foreach ($child in @($Node.None)) {
+                if (Test-IdleConditionNode -Node ([System.Collections.IDictionary]$child)) {
+                    return $false
+                }
+            }
+            return $true
+        }
+
+        # OPERATORS
+        if ($Node.Contains('Equals')) {
+            $op = $Node.Equals
+
+            $actual = Resolve-IdleConditionPathValue -Path ([string]$op.Path)
+            $expected = $op.Value
+
+            # Stable semantics: compare as strings (keeps config predictable across providers/types).
+            return ([string]$actual -eq [string]$expected)
+        }
+
+        if ($Node.Contains('NotEquals')) {
+            $op = $Node.NotEquals
+
+            $actual = Resolve-IdleConditionPathValue -Path ([string]$op.Path)
+            $expected = $op.Value
+
+            return ([string]$actual -ne [string]$expected)
+        }
+
+        if ($Node.Contains('Exists')) {
+            $existsVal = $Node.Exists
+
+            $path = if ($existsVal -is [string]) {
+                [string]$existsVal
+            } else {
+                [string]$existsVal.Path
+            }
+
+            $value = Resolve-IdleConditionPathValue -Path $path
+            return ($null -ne $value)
+        }
+
+        if ($Node.Contains('In')) {
+            $op = $Node.In
+
+            $actual = Resolve-IdleConditionPathValue -Path ([string]$op.Path)
+            $values = $op.Values
+
+            if ($null -eq $values) {
+                return $false
+            }
+
+            # Treat scalar and array uniformly.
+            $candidates = if ($values -is [System.Collections.IEnumerable] -and -not ($values -is [string])) {
+                @($values)
+            } else {
+                @($values)
+            }
+
+            foreach ($candidate in $candidates) {
+                if ([string]$actual -eq [string]$candidate) {
+                    return $true
+                }
+            }
+
+            return $false
+        }
+
+        # Should never happen due to schema validation.
+        return $false
+    }
+
+    return (Test-IdleConditionNode -Node $Condition)
+}