020-execution-layer-reference.mdc

---
description: Reference implementation for the resilient execution layer pattern
globs: "**/*.yaml"
alwaysApply: false
---

# Execution Layer Reference Implementation

## Full Template

Copy this template when creating new pipeline steps:

```bash
#!/usr/bin/env bash

# ============================================================
# EXECUTION LAYER - Resilient wrapper for observability
# ============================================================
SCRIPT_START=$(date +%s)
declare -a ACTION_LOG=()
FINAL_EXIT_CODE=0

# Enable debug mode if requested
if [[ "$(params.DEBUG)" == "true" ]]; then
  set -x
fi

exec_action() {
  local action_name="$1"
  local timeout_secs="${2:-60}"
  shift 2
  local cmd="$*"
  
  local start_ts=$(date +%s)
  echo ""
  echo "┌─────────────────────────────────────────────────────────────"
  echo "│ ACTION: $action_name"
  echo "│ CMD: $cmd"
  echo "│ TIMEOUT: ${timeout_secs}s"
  echo "├─────────────────────────────────────────────────────────────"
  
  local output exit_code
  output=$(timeout "$timeout_secs" bash -c "$cmd" 2>&1)
  exit_code=$?
  
  local end_ts=$(date +%s)
  local duration=$((end_ts - start_ts))
  
  if [[ -n "$output" ]]; then
    echo "$output" | sed 's/^/│ /'
  fi
  
  local status
  if [[ $exit_code -eq 0 ]]; then
    status="OK"
  elif [[ $exit_code -eq 124 ]]; then
    status="TIMEOUT"
  else
    status="FAILED"
  fi
  
  echo "├─────────────────────────────────────────────────────────────"
  echo "│ STATUS: $status (exit: $exit_code, duration: ${duration}s)"
  echo "└─────────────────────────────────────────────────────────────"
  
  ACTION_LOG+=("$status|$action_name|exit=$exit_code|${duration}s")
  return $exit_code
}

execution_summary() {
  local script_exit_code=$?
  local script_end=$(date +%s)
  local total_duration=$((script_end - SCRIPT_START))
  
  echo ""
  echo "╔═════════════════════════════════════════════════════════════"
  echo "║ EXECUTION SUMMARY - <step-name>"
  echo "║ Total Duration: ${total_duration}s"
  echo "║ Final Exit Code: ${FINAL_EXIT_CODE:-$script_exit_code}"
  echo "╠═════════════════════════════════════════════════════════════"
  
  local ok_count=0 fail_count=0 timeout_count=0
  
  for entry in "${ACTION_LOG[@]}"; do
    local status=$(echo "$entry" | cut -d'|' -f1)
    local action=$(echo "$entry" | cut -d'|' -f2)
    local details=$(echo "$entry" | cut -d'|' -f3-)
    
    case "$status" in
      OK) ok_count=$((ok_count + 1)); echo "║ ✓ $action ($details)" ;;
      FAILED) fail_count=$((fail_count + 1)); echo "║ ✗ $action ($details)" ;;
      TIMEOUT) timeout_count=$((timeout_count + 1)); echo "║ ⏱ $action ($details)" ;;
    esac
  done
  
  echo "╠═════════════════════════════════════════════════════════════"
  echo "║ OK: $ok_count | FAILED: $fail_count | TIMEOUT: $timeout_count"
  echo "╚═════════════════════════════════════════════════════════════"
  
  exit ${FINAL_EXIT_CODE:-$script_exit_code}
}

trap execution_summary EXIT

# ============================================================
# RUN LOGIC - Business logic with fail-fast behavior
# ============================================================
set -eo pipefail

# Your business logic here...
```

## Usage Patterns

### Wrapping Commands

```bash
# With exec_action (preferred for external calls)
if ! exec_action "Fetch data" 60 "kubectl get pod -ojson"; then
  echo "ERROR: Failed to fetch data"
  FINAL_EXIT_CODE=1
  exit 1
fi

# Quick validation (no external call)
if [[ -z "$REQUIRED_VAR" ]]; then
  echo "ERROR: REQUIRED_VAR is empty"
  FINAL_EXIT_CODE=1
  exit 1
fi
ACTION_LOG+=("OK|Validate REQUIRED_VAR|exit=0|0s")
```

### Early Exit (Success)

```bash
if [[ "$CONDITION" == "skip" ]]; then
  ACTION_LOG+=("OK|Skip - condition met|exit=0|0s")
  FINAL_EXIT_CODE=0
  exit 0
fi
```

## Key Principles

1. **Always set FINAL_EXIT_CODE before exit** - Ensures trap reports correct status
2. **Log manual validations** - Add to ACTION_LOG for visibility
3. **Timeout all external calls** - Prevent indefinite hangs
4. **Validate before use** - Check files/vars exist before operations