claude-flow-novice 2.18.5 → 2.18.6

package/.claude/skills/cfn-operations/lib/file/lib/atomic-write.sh

@@ -0,0 +1,294 @@
+#!/bin/bash
+#
+# Atomic Write Operations Library
+#
+# Provides atomic file write functions with SHA256 verification.
+# Part of Task 4.2: Centralized File Locking & Atomic Operations
+#
+
+#
+# Calculate SHA256 checksum of content
+#
+# Usage: calculate_checksum <content>
+#
+calculate_checksum() {
+  local content="$1"
+  echo -n "$content" | sha256sum | awk '{print $1}'
+}
+
+#
+# Calculate SHA256 checksum of file
+#
+# Usage: calculate_file_checksum <file-path>
+#
+calculate_file_checksum() {
+  local file_path="$1"
+
+  if [ ! -f "$file_path" ]; then
+    echo "Error: File not found: $file_path" >&2
+    return 1
+  fi
+
+  sha256sum "$file_path" | awk '{print $1}'
+}
+
+#
+# Write file atomically
+#
+# Usage: atomic_write_file <file-path> <content> [--checksum] [--backup] [--lock]
+#
+atomic_write_file() {
+  local file_path="$1"
+  local content="$2"
+  shift 2
+
+  if [ -z "$file_path" ]; then
+    echo "Error: file-path required" >&2
+    return 1
+  fi
+
+  local verify_checksum=0
+  local create_backup=0
+  local use_lock=0
+  local lock_info=""
+
+  # Parse options
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --checksum)
+        verify_checksum=1
+        shift
+        ;;
+      --backup)
+        create_backup=1
+        shift
+        ;;
+      --lock)
+        use_lock=1
+        shift
+        ;;
+      *)
+        shift
+        ;;
+    esac
+  done
+
+  local start_time
+  start_time=$(date +%s%3N)
+
+  # Acquire lock if requested
+  if [ "$use_lock" -eq 1 ]; then
+    lock_info=$(acquire_file_lock "$file_path" --timeout 30000)
+    if [ $? -ne 0 ]; then
+      echo "Error: Failed to acquire lock for $file_path" >&2
+      return 1
+    fi
+  fi
+
+  local dir
+  dir=$(dirname "$file_path")
+
+  local temp_path
+  temp_path="${dir}/.$(basename "$file_path").$(date +%s%N).tmp"
+
+  local backup_path=""
+  local success=0
+
+  # Calculate expected checksum
+  local expected_checksum
+  expected_checksum=$(calculate_checksum "$content")
+
+  # Create backup if requested and file exists
+  if [ "$create_backup" -eq 1 ] && [ -f "$file_path" ]; then
+    local timestamp
+    timestamp=$(date -u +"%Y-%m-%dT%H-%M-%S")
+    backup_path="${file_path}.${timestamp}.backup"
+
+    cp "$file_path" "$backup_path" 2>/dev/null || {
+      echo "Error: Failed to create backup" >&2
+      [ -n "$lock_info" ] && release_file_lock "$lock_info"
+      return 1
+    }
+
+    echo "Backup created: $backup_path" >&2
+  fi
+
+  # Write to temporary file
+  echo -n "$content" > "$temp_path" || {
+    echo "Error: Failed to write temporary file" >&2
+    [ -n "$lock_info" ] && release_file_lock "$lock_info"
+    return 1
+  }
+
+  # Verify checksum if requested
+  if [ "$verify_checksum" -eq 1 ]; then
+    local actual_checksum
+    actual_checksum=$(calculate_file_checksum "$temp_path")
+
+    if [ "$actual_checksum" != "$expected_checksum" ]; then
+      echo "Error: Checksum verification failed" >&2
+      echo "  Expected: $expected_checksum" >&2
+      echo "  Actual:   $actual_checksum" >&2
+      rm -f "$temp_path"
+      [ -n "$lock_info" ] && release_file_lock "$lock_info"
+      return 1
+    fi
+
+    echo "Checksum verified: $actual_checksum" >&2
+  fi
+
+  # Preserve permissions if file exists
+  if [ -f "$file_path" ]; then
+    chmod --reference="$file_path" "$temp_path" 2>/dev/null || true
+  fi
+
+  # Atomic move
+  if mv "$temp_path" "$file_path" 2>/dev/null; then
+    success=1
+  else
+    echo "Error: Failed to move temporary file to target" >&2
+
+    # Rollback from backup if available
+    if [ -n "$backup_path" ] && [ -f "$backup_path" ]; then
+      cp "$backup_path" "$file_path" 2>/dev/null && {
+        echo "Restored from backup after failed write" >&2
+      }
+    fi
+
+    rm -f "$temp_path"
+    [ -n "$lock_info" ] && release_file_lock "$lock_info"
+    return 1
+  fi
+
+  # Get file size
+  local bytes_written
+  bytes_written=$(stat -f%z "$file_path" 2>/dev/null || stat -c%s "$file_path" 2>/dev/null || echo "0")
+
+  local end_time
+  end_time=$(date +%s%3N)
+  local duration=$((end_time - start_time))
+
+  # Release lock if acquired
+  if [ -n "$lock_info" ]; then
+    release_file_lock "$lock_info"
+  fi
+
+  # Output result as JSON
+  jq -n \
+    --argjson success "$success" \
+    --arg filePath "$file_path" \
+    --arg checksum "$expected_checksum" \
+    --argjson bytesWritten "$bytes_written" \
+    --argjson durationMs "$duration" \
+    --arg backupPath "$backup_path" \
+    '{
+      success: $success,
+      filePath: $filePath,
+      checksum: $checksum,
+      bytesWritten: $bytesWritten,
+      durationMs: $durationMs,
+      backupPath: $backupPath
+    }'
+}
+
+#
+# Read file atomically
+#
+# Usage: atomic_read_file <file-path> [--expected-checksum HASH]
+#
+atomic_read_file() {
+  local file_path="$1"
+  shift
+
+  if [ -z "$file_path" ]; then
+    echo "Error: file-path required" >&2
+    return 1
+  fi
+
+  if [ ! -f "$file_path" ]; then
+    echo "Error: File not found: $file_path" >&2
+    return 1
+  fi
+
+  local expected_checksum=""
+
+  # Parse options
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --expected-checksum)
+        expected_checksum="$2"
+        shift 2
+        ;;
+      *)
+        shift
+        ;;
+    esac
+  done
+
+  # Read content
+  local content
+  content=$(cat "$file_path")
+
+  # Calculate checksum
+  local actual_checksum
+  actual_checksum=$(calculate_checksum "$content")
+
+  # Verify if expected checksum provided
+  if [ -n "$expected_checksum" ]; then
+    if [ "$actual_checksum" != "$expected_checksum" ]; then
+      echo "Error: Checksum verification failed" >&2
+      echo "  Expected: $expected_checksum" >&2
+      echo "  Actual:   $actual_checksum" >&2
+      return 1
+    fi
+  fi
+
+  # Output result as JSON
+  jq -n \
+    --arg content "$content" \
+    --arg checksum "$actual_checksum" \
+    '{
+      content: $content,
+      checksum: $checksum
+    }'
+}
+
+#
+# Verify file checksum
+#
+# Usage: verify_file_checksum <file-path> <expected-checksum>
+#
+verify_file_checksum() {
+  local file_path="$1"
+  local expected_checksum="$2"
+
+  if [ -z "$file_path" ] || [ -z "$expected_checksum" ]; then
+    echo "Error: file-path and expected-checksum required" >&2
+    return 1
+  fi
+
+  if [ ! -f "$file_path" ]; then
+    echo "Error: File not found: $file_path" >&2
+    return 1
+  fi
+
+  local actual_checksum
+  actual_checksum=$(calculate_file_checksum "$file_path")
+
+  local matches=0
+  if [ "$actual_checksum" = "$expected_checksum" ]; then
+    matches=1
+  fi
+
+  jq -n \
+    --arg filePath "$file_path" \
+    --arg expected "$expected_checksum" \
+    --arg actual "$actual_checksum" \
+    --argjson matches "$matches" \
+    '{
+      filePath: $filePath,
+      expectedChecksum: $expected,
+      actualChecksum: $actual,
+      matches: $matches
+    }'
+}

package/.claude/skills/cfn-operations/lib/file/lib/lock.sh

@@ -0,0 +1,361 @@
+#!/bin/bash
+#
+# File Lock Operations Library
+#
+# Provides file locking functions for bash scripts.
+# Part of Task 4.2: Centralized File Locking & Atomic Operations
+#
+
+# Lock directory
+LOCK_DIR="${CFN_LOCK_DIR:-/tmp/cfn-locks}"
+
+# Ensure lock directory exists
+mkdir -p "$LOCK_DIR" 2>/dev/null || true
+
+#
+# Acquire a file lock
+#
+# Usage: acquire_file_lock <file-path> [--agent-id ID] [--timeout MS]
+#
+# Returns: LOCK_ID:LOCK_PATH
+#
+acquire_file_lock() {
+  local file_path="$1"
+  shift
+
+  if [ -z "$file_path" ]; then
+    echo "Error: file-path required" >&2
+    return 1
+  fi
+
+  local agent_id=""
+  local timeout=300000  # 5 minutes default
+  local retry_interval=100  # 100ms default
+
+  # Parse options
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --agent-id)
+        agent_id="$2"
+        shift 2
+        ;;
+      --timeout)
+        timeout="$2"
+        shift 2
+        ;;
+      --retry-interval)
+        retry_interval="$2"
+        shift 2
+        ;;
+      *)
+        shift
+        ;;
+    esac
+  done
+
+  # Generate lock ID
+  local lock_id
+  lock_id="lock-$(date +%s%N | tail -c 10)-$$"
+
+  # Calculate lock file path (hash of target file path)
+  local file_hash
+  file_hash=$(echo -n "$file_path" | sha256sum | cut -c1-16)
+  local lock_path="${LOCK_DIR}/${file_hash}.lock"
+
+  # Calculate timeout deadline
+  local start_time
+  start_time=$(date +%s%3N)
+  local deadline=$((start_time + timeout))
+
+  local acquired=0
+
+  while [ "$(date +%s%3N)" -lt "$deadline" ]; do
+    # Check if lock exists
+    if [ -f "$lock_path" ]; then
+      # Check if lock is stale
+      if is_lock_stale "$lock_path" "$timeout"; then
+        echo "Warning: Removing stale lock: $lock_path" >&2
+        rm -f "$lock_path"
+      else
+        # Wait and retry
+        sleep "${retry_interval:0:1}.${retry_interval:1}" 2>/dev/null || sleep 0.1
+        continue
+      fi
+    fi
+
+    # Try to create lock
+    local owner_data
+    owner_data=$(create_lock_metadata "$lock_id" "$file_path" "$agent_id" "$timeout")
+
+    # Write lock file atomically
+    if echo "$owner_data" > "${lock_path}.tmp" && mv "${lock_path}.tmp" "$lock_path" 2>/dev/null; then
+      # Verify we won the race
+      local verify_lock_id
+      verify_lock_id=$(jq -r '.lockId' "$lock_path" 2>/dev/null || echo "")
+
+      if [ "$verify_lock_id" = "$lock_id" ]; then
+        acquired=1
+        break
+      else
+        # Lost the race
+        sleep "${retry_interval:0:1}.${retry_interval:1}" 2>/dev/null || sleep 0.1
+        continue
+      fi
+    else
+      sleep "${retry_interval:0:1}.${retry_interval:1}" 2>/dev/null || sleep 0.1
+      continue
+    fi
+  done
+
+  if [ "$acquired" -eq 0 ]; then
+    echo "Error: Failed to acquire lock on $file_path (timeout after ${timeout}ms)" >&2
+    return 1
+  fi
+
+  local acquisition_time=$(($(date +%s%3N) - start_time))
+  echo "Lock acquired: $lock_id ($acquisition_time ms)" >&2
+  echo "${lock_id}:${lock_path}"
+}
+
+#
+# Release a file lock
+#
+# Usage: release_file_lock <lock-id>
+#
+release_file_lock() {
+  local lock_info="$1"
+
+  if [ -z "$lock_info" ]; then
+    echo "Error: lock-info required (format: LOCK_ID:LOCK_PATH)" >&2
+    return 1
+  fi
+
+  local lock_id="${lock_info%%:*}"
+  local lock_path="${lock_info#*:}"
+
+  if [ ! -f "$lock_path" ]; then
+    echo "Warning: Lock file not found: $lock_path" >&2
+    return 0
+  fi
+
+  # Verify ownership
+  local verify_lock_id
+  verify_lock_id=$(jq -r '.lockId' "$lock_path" 2>/dev/null || echo "")
+
+  if [ "$verify_lock_id" != "$lock_id" ]; then
+    echo "Error: Lock ownership mismatch (expected: $lock_id, actual: $verify_lock_id)" >&2
+    return 1
+  fi
+
+  # Remove lock file
+  rm -f "$lock_path"
+  echo "Lock released: $lock_id" >&2
+}
+
+#
+# Renew a file lock
+#
+# Usage: renew_file_lock <lock-id> [--extension MS]
+#
+renew_file_lock() {
+  local lock_info="$1"
+  shift
+
+  if [ -z "$lock_info" ]; then
+    echo "Error: lock-info required (format: LOCK_ID:LOCK_PATH)" >&2
+    return 1
+  fi
+
+  local extension=300000  # 5 minutes default
+
+  # Parse options
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --extension)
+        extension="$2"
+        shift 2
+        ;;
+      *)
+        shift
+        ;;
+    esac
+  done
+
+  local lock_id="${lock_info%%:*}"
+  local lock_path="${lock_info#*:}"
+
+  if [ ! -f "$lock_path" ]; then
+    echo "Error: Lock file not found: $lock_path" >&2
+    return 1
+  fi
+
+  # Read current metadata
+  local metadata
+  metadata=$(cat "$lock_path")
+
+  # Verify ownership
+  local verify_lock_id
+  verify_lock_id=$(echo "$metadata" | jq -r '.lockId')
+
+  if [ "$verify_lock_id" != "$lock_id" ]; then
+    echo "Error: Lock ownership mismatch during renewal" >&2
+    return 1
+  fi
+
+  # Update expiration
+  local new_expires_at
+  new_expires_at=$(date -u -d "+${extension} milliseconds" +"%Y-%m-%dT%H:%M:%S.%3NZ" 2>/dev/null || date -u +"%Y-%m-%dT%H:%M:%S.000Z")
+
+  local renewal_count
+  renewal_count=$(echo "$metadata" | jq -r '.renewalCount')
+  renewal_count=$((renewal_count + 1))
+
+  # Update metadata
+  local updated_metadata
+  updated_metadata=$(echo "$metadata" | jq \
+    --arg expires "$new_expires_at" \
+    --arg renewed "$(date -u +"%Y-%m-%dT%H:%M:%S.%3NZ")" \
+    --argjson count "$renewal_count" \
+    '.expiresAt = $expires | .lastRenewedAt = $renewed | .renewalCount = $count')
+
+  # Write updated metadata
+  echo "$updated_metadata" > "$lock_path"
+
+  echo "Lock renewed: $lock_id (renewals: $renewal_count)" >&2
+}
+
+#
+# Force release a lock
+#
+# Usage: force_release_lock <lock-path>
+#
+force_release_lock() {
+  local lock_path="$1"
+
+  if [ -z "$lock_path" ]; then
+    echo "Error: lock-path required" >&2
+    return 1
+  fi
+
+  if [ ! -f "$lock_path" ]; then
+    echo "Warning: Lock file not found: $lock_path" >&2
+    return 0
+  fi
+
+  # Read lock metadata for logging
+  local lock_id
+  lock_id=$(jq -r '.lockId' "$lock_path" 2>/dev/null || echo "unknown")
+
+  # Force remove
+  rm -f "$lock_path"
+  echo "Lock force-released: $lock_id (path: $lock_path)" >&2
+}
+
+#
+# Check if lock is stale
+#
+# Usage: is_lock_stale <lock-path> <timeout-ms>
+#
+is_lock_stale() {
+  local lock_path="$1"
+  local timeout_ms="${2:-300000}"
+
+  if [ ! -f "$lock_path" ]; then
+    return 0  # Missing lock is considered stale
+  fi
+
+  # Read expiration time
+  local expires_at
+  expires_at=$(jq -r '.expiresAt' "$lock_path" 2>/dev/null || echo "")
+
+  if [ -z "$expires_at" ]; then
+    return 0  # Invalid lock is stale
+  fi
+
+  # Convert to epoch
+  local expires_epoch
+  expires_epoch=$(date -d "$expires_at" +%s 2>/dev/null || echo "0")
+
+  local now_epoch
+  now_epoch=$(date +%s)
+
+  if [ "$now_epoch" -gt "$expires_epoch" ]; then
+    return 0  # Expired
+  else
+    return 1  # Not stale
+  fi
+}
+
+#
+# Create lock metadata JSON
+#
+# Usage: create_lock_metadata <lock-id> <file-path> <agent-id> <timeout-ms>
+#
+create_lock_metadata() {
+  local lock_id="$1"
+  local file_path="$2"
+  local agent_id="$3"
+  local timeout_ms="$4"
+
+  local acquired_at
+  acquired_at=$(date -u +"%Y-%m-%dT%H:%M:%S.%3NZ")
+
+  local expires_at
+  expires_at=$(date -u -d "+${timeout_ms} milliseconds" +"%Y-%m-%dT%H:%M:%S.%3NZ" 2>/dev/null || date -u +"%Y-%m-%dT%H:%M:%S.000Z")
+
+  local hostname
+  hostname=$(hostname)
+
+  jq -n \
+    --arg lockId "$lock_id" \
+    --arg filePath "$file_path" \
+    --argjson pid "$$" \
+    --arg agentId "$agent_id" \
+    --arg hostname "$hostname" \
+    --arg acquiredAt "$acquired_at" \
+    --arg expiresAt "$expires_at" \
+    --argjson timeoutMs "$timeout_ms" \
+    --argjson renewalCount 0 \
+    '{
+      lockId: $lockId,
+      filePath: $filePath,
+      owner: {
+        pid: $pid,
+        agentId: $agentId,
+        hostname: $hostname
+      },
+      acquiredAt: $acquiredAt,
+      expiresAt: $expiresAt,
+      timeoutMs: $timeoutMs,
+      renewalCount: $renewalCount
+    }'
+}
+
+#
+# Get lock metrics
+#
+get_lock_metrics() {
+  local lock_count=0
+  local stale_count=0
+
+  if [ -d "$LOCK_DIR" ]; then
+    lock_count=$(find "$LOCK_DIR" -name "*.lock" 2>/dev/null | wc -l)
+
+    for lock_file in "$LOCK_DIR"/*.lock; do
+      [ -f "$lock_file" ] || continue
+      if is_lock_stale "$lock_file" 300000; then
+        stale_count=$((stale_count + 1))
+      fi
+    done
+  fi
+
+  jq -n \
+    --argjson activeLocks "$lock_count" \
+    --argjson staleLocks "$stale_count" \
+    --arg lockDir "$LOCK_DIR" \
+    '{
+      activeLocks: $activeLocks,
+      staleLocks: $staleLocks,
+      lockDirectory: $lockDir
+    }'
+}