claude-flow-novice 2.18.5 → 2.18.6

package/.claude/skills/cfn-docker-runtime/lib/waves/lib/docker-helpers.sh

@@ -0,0 +1,804 @@
+#!/bin/bash
+
+################################################################################
+# CFN Docker Wave Execution - Helper Functions Library
+# Purpose: Shared utilities for Docker container lifecycle management
+# Version: 1.0.0
+# Usage: source ./lib/docker-helpers.sh
+################################################################################
+
+set -euo pipefail
+
+# Color codes for output
+readonly RED='\033[0;31m'
+readonly GREEN='\033[0;32m'
+readonly YELLOW='\033[1;33m'
+readonly BLUE='\033[0;34m'
+readonly CYAN='\033[0;36m'
+readonly NC='\033[0m'  # No Color
+
+# Logging configuration
+readonly LOG_TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+readonly SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+################################################################################
+# LOGGING FUNCTIONS
+################################################################################
+
+log_info() {
+  echo -e "${BLUE}[INFO]${NC} $(date '+%H:%M:%S') $*" >&2
+}
+
+log_success() {
+  echo -e "${GREEN}[SUCCESS]${NC} $(date '+%H:%M:%S') $*" >&2
+}
+
+log_warn() {
+  echo -e "${YELLOW}[WARN]${NC} $(date '+%H:%M:%S') $*" >&2
+}
+
+log_error() {
+  echo -e "${RED}[ERROR]${NC} $(date '+%H:%M:%S') $*" >&2
+}
+
+log_debug() {
+  if [[ "${CFN_DEBUG:-false}" == "true" ]]; then
+    echo -e "${CYAN}[DEBUG]${NC} $(date '+%H:%M:%S') $*" >&2
+  fi
+}
+
+################################################################################
+# VALIDATION FUNCTIONS
+################################################################################
+
+# Validate environment variable format and safety (CRITICAL FIX #1)
+validate_environment_variable() {
+  local var="$1"
+
+  # Format check: VAR_NAME=value
+  if ! [[ "$var" =~ ^[A-Za-z_][A-Za-z0-9_]*=.* ]]; then
+    log_error "Invalid environment variable format: $var"
+    log_error "Expected format: VAR_NAME=value"
+    return 1
+  fi
+
+  local var_name="${var%%=*}"
+
+  # Block dangerous variable names that could compromise container security
+  local -a dangerous_vars=(
+    "LD_PRELOAD"
+    "LD_LIBRARY_PATH"
+    "LD_DEBUG"
+    "DOCKER_HOST"
+    "DOCKER_CERT_PATH"
+    "DOCKER_TLS"
+    "DOCKER_TLS_VERIFY"
+    "DOCKER_API_VERSION"
+    "DOCKER_CONFIG"
+    "DOCKERHOST"
+    "DOCKER_SOCKET"
+  )
+
+  for dangerous in "${dangerous_vars[@]}"; do
+    if [[ "$var_name" == "$dangerous" ]]; then
+      log_error "Blocked dangerous environment variable: $var_name"
+      return 1
+    fi
+  done
+
+  # Validate value doesn't contain shell metacharacters (belt-and-suspenders)
+  local var_value="${var#*=}"
+  if [[ "$var_value" =~ [\$\`\(\)\{\}\&\|\;\<\>] ]]; then
+    log_warn "Environment variable contains special characters (not necessarily invalid): $var_name"
+    # Allow but warn - Docker API will handle escaping
+  fi
+
+  log_debug "Environment variable validated: $var_name"
+  return 0
+}
+
+# Validate Docker is accessible
+validate_docker_access() {
+  if ! command -v docker &> /dev/null; then
+    log_error "Docker CLI not found. Please install Docker."
+    return 1
+  fi
+
+  if ! docker version &> /dev/null; then
+    log_error "Docker daemon not accessible. Is it running?"
+    return 1
+  fi
+
+  # Verify socket access
+  if ! docker ps &> /dev/null; then
+    log_error "No permission to access Docker socket. Check user group."
+    return 1
+  fi
+
+  log_debug "Docker access validated"
+  return 0
+}
+
+# Validate jq is available
+validate_jq() {
+  if ! command -v jq &> /dev/null; then
+    log_error "jq not found. Please install jq for JSON processing."
+    return 1
+  fi
+  return 0
+}
+
+# Validate JSON file format
+validate_json_file() {
+  local file="$1"
+
+  if [[ ! -f "$file" ]]; then
+    log_error "File not found: $file"
+    return 1
+  fi
+
+  if ! jq . "$file" > /dev/null 2>&1; then
+    log_error "Invalid JSON in file: $file"
+    return 1
+  fi
+
+  log_debug "JSON file validated: $file"
+  return 0
+}
+
+# Validate memory string format (512m, 1g, etc.)
+validate_memory_string() {
+  local memory="$1"
+
+  if ! [[ "$memory" =~ ^[0-9]+(b|k|m|g|gb|mb|kb)$ ]] && ! [[ "$memory" =~ ^[0-9]+$ ]]; then
+    log_error "Invalid memory format: $memory (expected: 512m, 1g, 100, etc.)"
+    return 1
+  fi
+
+  log_debug "Memory string validated: $memory"
+  return 0
+}
+
+# Validate container cleanup pattern for safety (MEDIUM FIX #3)
+validate_container_cleanup_pattern() {
+  local pattern="$1"
+
+  # Only allow specific, safe patterns
+  # Valid: cfn-wave1-*, cfn-wave2-*, cfn-wave3-batch-1, etc.
+  if ! [[ "$pattern" =~ ^cfn-wave[0-9]+-[a-zA-Z0-9_-]+(\*)?$ ]]; then
+    log_error "Container cleanup pattern does not match safety requirements"
+    log_error "Pattern: $pattern"
+    log_error "Expected format: cfn-wave<N>-<batch-id> or cfn-wave<N>-*"
+    log_error "Examples: cfn-wave1-batch-1, cfn-wave2-*, cfn-wave3-batch_123"
+    return 1
+  fi
+
+  return 0
+}
+
+################################################################################
+# MEMORY CONVERSION FUNCTIONS
+################################################################################
+
+# Parse memory string to bytes
+# Supports: 512m, 1g, 100, 512mb, 1gb, etc.
+# Returns byte count as integer
+parse_memory() {
+  local memory="$1"
+  local bytes
+
+  if ! validate_memory_string "$memory"; then
+    return 1
+  fi
+
+  # Extract number and unit
+  local num="${memory%[a-zA-Z]*}"
+  local unit="${memory#$num}"
+
+  # Convert to lowercase for consistency
+  unit="${unit,,}"
+
+  case "$unit" in
+    b|'')
+      bytes=$((num))
+      ;;
+    k|kb)
+      bytes=$((num * 1024))
+      ;;
+    m|mb)
+      bytes=$((num * 1024 * 1024))
+      ;;
+    g|gb)
+      bytes=$((num * 1024 * 1024 * 1024))
+      ;;
+    *)
+      log_error "Unknown memory unit: $unit"
+      return 1
+      ;;
+  esac
+
+  echo "$bytes"
+  log_debug "Parsed memory: $memory -> $bytes bytes"
+}
+
+# Convert bytes to human-readable format
+format_memory() {
+  local bytes="$1"
+
+  if (( bytes < 1024 )); then
+    echo "${bytes}B"
+  elif (( bytes < 1024 * 1024 )); then
+    echo "$((bytes / 1024))KB"
+  elif (( bytes < 1024 * 1024 * 1024 )); then
+    echo "$((bytes / 1024 / 1024))MB"
+  else
+    echo "$((bytes / 1024 / 1024 / 1024))GB"
+  fi
+}
+
+################################################################################
+# ENVIRONMENT VALUE SANITIZATION (CRITICAL FIX #3)
+################################################################################
+
+# Sanitize environment variable values for safe Docker injection
+sanitize_env_value() {
+  local value="$1"
+
+  # Remove control characters (newlines, tabs, null bytes, etc.) AND shell metacharacters
+  # Keep printable ASCII + common UTF-8 characters
+  value=$(echo "$value" | LC_ALL=C tr -d '[:cntrl:];|&$(){}[]<>*?~`')
+
+  # Replace multiple spaces with single space
+  value=$(echo "$value" | sed 's/[[:space:]]\+/ /g')
+
+  # Trim leading/trailing whitespace
+  value=$(echo "$value" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+
+  # Limit length to prevent environment pollution (2048 chars max)
+  if (( ${#value} > 2048 )); then
+    log_warn "Environment value truncated from ${#value} to 2048 chars"
+    value="${value:0:2048}"
+  fi
+
+  echo "$value"
+}
+
+################################################################################
+# CONTAINER NAMING SAFETY (CRITICAL FIX #2)
+################################################################################
+
+# Generate collision-resistant container name using hash
+generate_safe_container_name() {
+  local wave_num="$1"
+  local batch_id="$2"
+
+  # Generate short hash of full batch ID to ensure uniqueness
+  local batch_hash
+  batch_hash=$(echo -n "$batch_id" | sha256sum | cut -c1-12)
+
+  # Format: cfn-wave<N>-<12-char-hash>
+  local container_name="cfn-wave${wave_num}-${batch_hash}"
+
+  echo "$container_name"
+}
+
+# Check if container name already exists
+container_name_exists() {
+  local container_name="$1"
+
+  # Use exact match filter to prevent false positives
+  if docker ps -a --filter "name=^${container_name}$" --format "{{.ID}}" | grep -q .; then
+    return 0  # Name exists
+  else
+    return 1  # Name available
+  fi
+}
+
+################################################################################
+# DOCKER CONTAINER STATUS FUNCTIONS
+################################################################################
+
+# Get container status (running, exited, failed)
+# Returns: "running" | "exited" | "failed" | "unknown"
+get_container_status() {
+  local container_id="$1"
+
+  if [[ -z "$container_id" ]]; then
+    log_error "Container ID not provided"
+    return 1
+  fi
+
+  # Get container status from docker inspect
+  local status
+  status=$(docker inspect -f '{{.State.Status}}' "$container_id" 2>/dev/null || echo "unknown")
+
+  case "$status" in
+    running)
+      echo "running"
+      ;;
+    exited)
+      echo "exited"
+      ;;
+    *)
+      echo "unknown"
+      ;;
+  esac
+}
+
+# Extract exit code from container
+# Returns: 0-255 or -1 if container is still running
+extract_exit_code() {
+  local container_id="$1"
+
+  if [[ -z "$container_id" ]]; then
+    log_error "Container ID not provided"
+    return 1
+  fi
+
+  local status exit_code
+  status=$(docker inspect -f '{{.State.Status}}' "$container_id" 2>/dev/null)
+
+  if [[ "$status" != "exited" ]]; then
+    echo "-1"
+    return 0
+  fi
+
+  exit_code=$(docker inspect -f '{{.State.ExitCode}}' "$container_id" 2>/dev/null)
+  echo "$exit_code"
+}
+
+# Get container exit status string (success, failed, timeout)
+get_exit_status() {
+  local exit_code="$1"
+
+  case "$exit_code" in
+    0)
+      echo "success"
+      ;;
+    124)
+      echo "timeout"
+      ;;
+    *)
+      echo "failed"
+      ;;
+  esac
+}
+
+# Get container creation timestamp
+get_container_started_at() {
+  local container_id="$1"
+
+  if [[ -z "$container_id" ]]; then
+    return 1
+  fi
+
+  docker inspect -f '{{.State.StartedAt}}' "$container_id" 2>/dev/null || echo ""
+}
+
+# Get container finish timestamp
+get_container_finished_at() {
+  local container_id="$1"
+
+  if [[ -z "$container_id" ]]; then
+    return 1
+  fi
+
+  docker inspect -f '{{.State.FinishedAt}}' "$container_id" 2>/dev/null || echo ""
+}
+
+################################################################################
+# CONTAINER MONITORING FUNCTIONS
+################################################################################
+
+# Wait for container to complete (exit)
+# Returns: 0 (success), 1 (failed), 2 (timeout), 3 (error)
+wait_for_container() {
+  local container_id="$1"
+  local timeout="${2:-300}"  # Default 5 minutes
+  local poll_interval="${3:-2}"  # Default 2 seconds
+
+  if [[ -z "$container_id" ]]; then
+    log_error "Container ID not provided"
+    return 3
+  fi
+
+  local start_time elapsed_time
+  start_time=$(date +%s)
+
+  log_info "Waiting for container $container_id (timeout: ${timeout}s)"
+
+  while true; do
+    elapsed_time=$(($(date +%s) - start_time))
+
+    # Check if timeout exceeded
+    if (( elapsed_time > timeout )); then
+      log_warn "Container $container_id timeout after ${timeout}s"
+      return 2
+    fi
+
+    # Check container status
+    local status
+    status=$(docker inspect -f '{{.State.Status}}' "$container_id" 2>/dev/null || echo "unknown")
+
+    if [[ "$status" == "exited" ]]; then
+      local exit_code
+      exit_code=$(docker inspect -f '{{.State.ExitCode}}' "$container_id" 2>/dev/null)
+
+      if [[ "$exit_code" == "0" ]]; then
+        log_success "Container $container_id completed successfully"
+        return 0
+      else
+        log_error "Container $container_id failed with exit code: $exit_code"
+        return 1
+      fi
+    fi
+
+    # Wait before next check
+    sleep "$poll_interval"
+  done
+}
+
+# Wait for multiple containers to complete
+# Returns: 0 (all success), 1 (some failed), 2 (timeout), 3 (error)
+wait_for_containers() {
+  local -n container_ids=$1
+  local timeout="${2:-1800}"  # Default 30 minutes
+  local poll_interval="${3:-5}"  # Default 5 seconds
+
+  if [[ ${#container_ids[@]} -eq 0 ]]; then
+    log_error "No containers provided"
+    return 3
+  fi
+
+  local start_time elapsed_time failed_count timeout_count
+  start_time=$(date +%s)
+  failed_count=0
+  timeout_count=0
+
+  log_info "Waiting for ${#container_ids[@]} containers (timeout: ${timeout}s)"
+
+  while true; do
+    elapsed_time=$(($(date +%s) - start_time))
+
+    # Check if timeout exceeded
+    if (( elapsed_time > timeout )); then
+      log_warn "Timeout waiting for containers after ${timeout}s"
+      timeout_count=$((timeout_count + ${#container_ids[@]}))
+      return 2
+    fi
+
+    # Check all containers
+    local running_count=0
+    local completed_count=0
+
+    for cid in "${container_ids[@]}"; do
+      local status
+      status=$(docker inspect -f '{{.State.Status}}' "$cid" 2>/dev/null || echo "unknown")
+
+      if [[ "$status" == "exited" ]]; then
+        completed_count=$((completed_count + 1))
+      elif [[ "$status" == "running" ]]; then
+        running_count=$((running_count + 1))
+      fi
+    done
+
+    # Log progress
+    log_debug "Progress: $completed_count completed, $running_count still running"
+
+    # All completed?
+    if (( completed_count == ${#container_ids[@]} )); then
+      # Count failures
+      for cid in "${container_ids[@]}"; do
+        local exit_code
+        exit_code=$(docker inspect -f '{{.State.ExitCode}}' "$cid" 2>/dev/null || echo "1")
+        if [[ "$exit_code" != "0" ]]; then
+          failed_count=$((failed_count + 1))
+        fi
+      done
+
+      if (( failed_count == 0 )); then
+        log_success "All $completed_count containers completed successfully"
+        return 0
+      else
+        log_error "$failed_count out of $completed_count containers failed"
+        return 1
+      fi
+    fi
+
+    # Wait before next check
+    sleep "$poll_interval"
+  done
+}
+
+################################################################################
+# CONTAINER MANIFEST FUNCTIONS
+################################################################################
+
+# Create container metadata object (for JSON output)
+create_container_manifest() {
+  local container_id="$1"
+  local batch_id="$2"
+  local tier="${3:-1}"
+  local memory_limit="${4:-512m}"
+
+  jq -n \
+    --arg container_id "$container_id" \
+    --arg batch_id "$batch_id" \
+    --arg tier "$tier" \
+    --arg memory_limit "$memory_limit" \
+    --arg status "running" \
+    --arg started_at "$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \
+    '{
+      container_id: $container_id,
+      batch_id: $batch_id,
+      tier: ($tier | tonumber),
+      memory_limit: $memory_limit,
+      status: $status,
+      started_at: $started_at
+    }'
+}
+
+# Update container manifest with completion info
+update_container_manifest() {
+  local manifest="$1"
+  local exit_code="$2"
+
+  local status
+  status=$(get_exit_status "$exit_code")
+
+  jq -n \
+    --argjson manifest "$manifest" \
+    --arg exit_code "$exit_code" \
+    --arg status "$status" \
+    --arg finished_at "$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \
+    '$manifest + {
+      status: "exited",
+      exit_code: ($exit_code | tonumber),
+      exit_status: $status,
+      finished_at: $finished_at
+    }'
+}
+
+################################################################################
+# LOGGING FUNCTIONS
+################################################################################
+
+# Retrieve container logs
+# Returns logs to stdout
+get_container_logs() {
+  local container_id="$1"
+
+  if [[ -z "$container_id" ]]; then
+    log_error "Container ID not provided"
+    return 1
+  fi
+
+  docker logs "$container_id" 2>&1 || true
+}
+
+# Save container logs to file with restricted permissions (MEDIUM FIX #1)
+save_container_logs() {
+  local container_id="$1"
+  local output_dir="$2"
+
+  if [[ -z "$container_id" ]] || [[ -z "$output_dir" ]]; then
+    log_error "Container ID and output directory required"
+    return 1
+  fi
+
+  mkdir -p "$output_dir"
+
+  # Create directory with restricted permissions (owner only)
+  chmod 700 "$output_dir" || {
+    log_warn "Failed to restrict log directory permissions: $output_dir"
+  }
+
+  local log_file="$output_dir/${container_id}.log"
+
+  # Create empty file with restricted permissions (0600 = owner read/write only)
+  touch "$log_file"
+  chmod 600 "$log_file" || {
+    log_error "Failed to set log file permissions: $log_file"
+    return 1
+  }
+
+  log_info "Saving logs for container $container_id to $log_file"
+
+  # Write logs to file with restricted permissions
+  docker logs "$container_id" > "$log_file" 2>&1 || {
+    log_error "Failed to save logs for container $container_id"
+    return 1
+  }
+
+  log_success "Logs saved: $log_file (permissions: 0600)"
+  return 0
+}
+
+################################################################################
+# CLEANUP FUNCTIONS
+################################################################################
+
+# Remove container safely
+remove_container() {
+  local container_id="$1"
+  local force="${2:-false}"
+
+  if [[ -z "$container_id" ]]; then
+    log_error "Container ID not provided"
+    return 1
+  fi
+
+  local remove_opts=()
+  if [[ "$force" == "true" ]]; then
+    remove_opts+=("-f")
+  fi
+
+  log_info "Removing container $container_id"
+  if docker rm "${remove_opts[@]}" "$container_id" > /dev/null 2>&1; then
+    log_success "Container removed: $container_id"
+    return 0
+  else
+    log_error "Failed to remove container: $container_id"
+    return 1
+  fi
+}
+
+# Remove multiple containers
+remove_containers() {
+  local -n container_ids=$1
+  local force="${2:-false}"
+
+  if [[ ${#container_ids[@]} -eq 0 ]]; then
+    log_warn "No containers to remove"
+    return 0
+  fi
+
+  local removed_count=0
+  local failed_count=0
+
+  for cid in "${container_ids[@]}"; do
+    if remove_container "$cid" "$force"; then
+      removed_count=$((removed_count + 1))
+    else
+      failed_count=$((failed_count + 1))
+    fi
+  done
+
+  log_info "Removed $removed_count containers, failed: $failed_count"
+
+  if (( failed_count == 0 )); then
+    return 0
+  else
+    return 1
+  fi
+}
+
+# Remove containers by name pattern
+remove_containers_by_pattern() {
+  local pattern="$1"
+  local force="${2:-false}"
+
+  if [[ -z "$pattern" ]]; then
+    log_error "Pattern not provided"
+    return 1
+  fi
+
+  log_info "Finding containers matching pattern: $pattern"
+
+  local container_ids=()
+  while IFS= read -r cid; do
+    container_ids+=("$cid")
+  done < <(docker ps -a --filter "name=$pattern" --format "{{.ID}}")
+
+  if [[ ${#container_ids[@]} -eq 0 ]]; then
+    log_warn "No containers found matching pattern: $pattern"
+    return 0
+  fi
+
+  log_info "Found ${#container_ids[@]} containers to remove"
+  remove_containers container_ids "$force"
+}
+
+# Remove dangling volumes
+remove_dangling_volumes() {
+  log_info "Cleaning up dangling volumes"
+
+  local volume_count
+  volume_count=$(docker volume ls -qf dangling=true | wc -l)
+
+  if (( volume_count > 0 )); then
+    docker volume rm $(docker volume ls -qf dangling=true) 2>/dev/null || true
+    log_success "Removed $volume_count dangling volumes"
+  else
+    log_info "No dangling volumes to remove"
+  fi
+
+  return 0
+}
+
+################################################################################
+# NETWORK FUNCTIONS
+################################################################################
+
+# Create Docker network if it doesn't exist
+create_network_if_missing() {
+  local network_name="${1:-cfn-network}"
+
+  if docker network inspect "$network_name" > /dev/null 2>&1; then
+    log_debug "Network already exists: $network_name"
+    return 0
+  fi
+
+  log_info "Creating Docker network: $network_name"
+  if docker network create "$network_name" > /dev/null 2>&1; then
+    log_success "Network created: $network_name"
+    return 0
+  else
+    log_error "Failed to create network: $network_name"
+    return 1
+  fi
+}
+
+# Verify network exists
+verify_network_exists() {
+  local network_name="${1:-cfn-network}"
+
+  if docker network inspect "$network_name" > /dev/null 2>&1; then
+    log_debug "Network verified: $network_name"
+    return 0
+  else
+    log_error "Network not found: $network_name"
+    return 1
+  fi
+}
+
+################################################################################
+# SUMMARY FUNCTIONS
+################################################################################
+
+# Generate execution summary JSON
+generate_execution_summary() {
+  local wave_number="$1"
+  local total_containers="$2"
+  local successful="$3"
+  local failed="$4"
+  local timeout="$5"
+
+  jq -n \
+    --arg wave_number "$wave_number" \
+    --arg total_containers "$total_containers" \
+    --arg successful "$successful" \
+    --arg failed "$failed" \
+    --arg timeout "$timeout" \
+    --arg summary_time "$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \
+    '{
+      wave_number: ($wave_number | tonumber),
+      summary_time: $summary_time,
+      metrics: {
+        total: ($total_containers | tonumber),
+        success: ($successful | tonumber),
+        failed: ($failed | tonumber),
+        timeout: ($timeout | tonumber)
+      }
+    }'
+}
+
+################################################################################
+# EXPORT FUNCTIONS (for subshells)
+################################################################################
+
+# Export all helper functions for use in subshells
+export -f log_info log_success log_warn log_error log_debug
+export -f validate_environment_variable validate_docker_access validate_jq validate_json_file validate_memory_string validate_container_cleanup_pattern
+export -f sanitize_env_value generate_safe_container_name container_name_exists
+export -f parse_memory format_memory
+export -f get_container_status extract_exit_code get_exit_status get_container_started_at get_container_finished_at
+export -f wait_for_container wait_for_containers
+export -f create_container_manifest update_container_manifest
+export -f get_container_logs save_container_logs
+export -f remove_container remove_containers remove_containers_by_pattern remove_dangling_volumes
+export -f create_network_if_missing verify_network_exists
+export -f generate_execution_summary
+
+log_debug "Docker helpers library loaded"