feat(workflow): Mustache lambda helpers for missing-key defaults (fn.*) (#5684)

Author: hakatt

keep-ui/entities/workflows/lib/mustache.ts

@@ -15,5 +15,8 @@ export function extractMustacheVariables(yamlString: string): string[] {
       .map((match) => match[1])
       // TODO: more sophisticated validation
       .filter((variable) => variable.length > 0 && !variable.endsWith("."))
+      // Skip Mustache sigil tokens: section open (#), close (/), inverted (^),
+      // comment (!), partial (>) — these are not variable references.
+      .filter((variable) => !/^[#/^!>]/.test(variable))
   );
 }

keep-ui/entities/workflows/lib/validate-mustache-ui-builder.ts

@@ -35,6 +35,11 @@ export const validateMustacheVariableForUIBuilderStep = (
   if (!cleanedVariableName) {
     return "Empty mustache variable.";
   }
+  // Mustache sigil tokens (#, /, ^, !, >) are section/lambda syntax, not
+  // variable references — skip validation entirely.
+  if (/^[#/^!>]/.test(cleanedVariableName)) {
+    return null;
+  }
   if (cleanedVariableName === ".") {
     if (currentStep.parentId) {
       return null;

keep-ui/entities/workflows/lib/validate-mustache-yaml.ts

@@ -35,6 +35,11 @@ export const validateMustacheVariableForYAMLStep = (
   if (!cleanedVariableName) {
     return ["Empty mustache variable.", "warning"];
   }
+  // Mustache sigil tokens (#, /, ^, !, >) are section/lambda syntax, not
+  // variable references — skip validation entirely.
+  if (/^[#/^!>]/.test(cleanedVariableName)) {
+    return null;
+  }
   if (cleanedVariableName === ".") {
     if (currentStep.foreach) {
       return null;

keep/iohandler/iohandler.py

@@ -18,6 +18,21 @@
 from keep.contextmanager.contextmanager import ContextManager
 from keep.step.step_provider_parameter import StepProviderParameter
 
+# Mustache lambda helpers injected into every render context.
+# Usage in workflow YAML:  {{#fn.na}}{{ alert.someOptionalField }}{{/fn.na}}
+# When a referenced field is missing or empty the helper returns the default
+# instead of raising RenderException (safe mode is disabled automatically
+# when fn.* sections are detected — see _render()).
+WORKFLOW_HELPERS = {
+    "fn": {
+        "default": lambda text, render: render(text) or "",
+        "na":      lambda text, render: render(text) or "N/A",
+        "upper":   lambda text, render: render(text).upper(),
+        "lower":   lambda text, render: render(text).lower(),
+        "strip":   lambda text, render: render(text).strip(),
+    }
+}
+
 
 class RenderException(Exception):
     def __init__(self, message, missing_keys=None):
@@ -429,11 +444,19 @@ def _render(self, key: str, safe=False, default="", additional_context=None):
             )
             safe = False
 
+        # fn.* helper sections explicitly handle missing/empty keys — the lambda
+        # returns a default value so RenderException must not be raised.
+        if "{{#fn." in key or "{{ #fn." in key:
+            safe = False
+
         context = self.context_manager.get_full_context(exclude_providers=True)
 
         if additional_context:
             context.update(additional_context)
 
+        # Inject workflow helper lambdas so fn.* sections are resolvable.
+        context.update(WORKFLOW_HELPERS)
+
         stderr_capture = io.StringIO()
         original_stderr = sys.stderr
         sys.stderr = stderr_capture

tests/test_iohandler.py

@@ -1023,3 +1023,43 @@ def render_template(thread_id):
         t.join(timeout=30)
 
     assert not errors, f"Concurrent render raised errors: {errors}"
+
+
+# ── fn.* Mustache lambda helper tests ────────────────────────────────────────
+
+
+def test_fn_na_on_missing_key(mocked_context_manager):
+    """fn.na renders 'N/A' when the wrapped field is absent from the context."""
+    mocked_context_manager.get_full_context.return_value = {
+        "alert": {"name": "test-alert"},  # no 'slack_timestamp' field
+    }
+    iohandler = IOHandler(mocked_context_manager)
+    result = iohandler.render("ts={{#fn.na}}{{ alert.slack_timestamp }}{{/fn.na}}")
+    assert result == "ts=N/A", f"Expected 'ts=N/A', got '{result}'"
+
+
+def test_fn_default_on_missing_key(mocked_context_manager):
+    """fn.default renders an empty string when the wrapped field is absent."""
+    mocked_context_manager.get_full_context.return_value = {
+        "alert": {"name": "test-alert"},  # no 'silenceURL' field
+    }
+    iohandler = IOHandler(mocked_context_manager)
+    result = iohandler.render("url={{#fn.default}}{{ alert.silenceURL }}{{/fn.default}}")
+    assert result == "url=", f"Expected 'url=', got '{result}'"
+
+
+def test_fn_upper_lower_strip_on_present_value(mocked_context_manager):
+    """fn.upper, fn.lower, and fn.strip transform present field values correctly."""
+    mocked_context_manager.get_full_context.return_value = {
+        "alert": {"env": "  Production  "},
+    }
+    iohandler = IOHandler(mocked_context_manager)
+
+    upper = iohandler.render("{{#fn.upper}}{{ alert.env }}{{/fn.upper}}")
+    assert upper == "  PRODUCTION  ", f"fn.upper got '{upper}'"
+
+    lower = iohandler.render("{{#fn.lower}}{{ alert.env }}{{/fn.lower}}")
+    assert lower == "  production  ", f"fn.lower got '{lower}'"
+
+    strip = iohandler.render("{{#fn.strip}}{{ alert.env }}{{/fn.strip}}")
+    assert strip == "Production", f"fn.strip got '{strip}'"