CFN Utilities Skill

Description

Reusable bash utility functions for the CFN Loop system. Provides standardized logging, error handling, retry logic, and atomic file operations with zero external dependencies.

Purpose

• Structured Logging: JSON-formatted logs compatible with TypeScript logging system
• Error Handling: Consistent error management across bash scripts
• Retry Logic: Exponential backoff for transient failures
• File Operations: Atomic writes and file locking primitives

Dependencies

• POSIX-compliant bash (4.0+)
• Coreutils (standard Linux/macOS utilities)
• No external dependencies required

Usage

Direct Function Invocation

# Source all utilities
source ./.claude/skills/cfn-utilities/execute.sh

# Use individual functions
log_info "Task started" '{"task_id":"abc123"}'
retry_with_backoff 3 2 curl https://api.example.com
atomic_write "/path/to/file.txt" "content here"

Via Execute Script

# Execute specific function
./.claude/skills/cfn-utilities/execute.sh log_json "info" "Message" '{"key":"value"}'

# Source and call
source ./.claude/skills/cfn-utilities/execute.sh
log_error "Operation failed" '{"error_code":"E001"}'

Available Functions

Logging (lib/logging.sh)

log_json(level, message, context)

log_json "info" "Task started" '{"task_id":"abc123","agent":"backend-dev"}'
# Output: {"timestamp":"2025-11-15T20:00:00Z","level":"info","message":"Task started","context":{"task_id":"abc123","agent":"backend-dev"}}

log_info(message, context)

log_info "Processing file" '{"file":"data.txt"}'

log_warn(message, context)

log_warn "Deprecated function used" '{"function":"old_func"}'

log_error(message, context)

log_error "Failed to connect" '{"host":"api.example.com","code":500}'

log_debug(message, context)

export LOG_LEVEL=debug
log_debug "Variable state" '{"var":"value"}'

Error Handling (lib/errors.sh)

error_exit(message, exit_code, context)

error_exit "Database connection failed" 1 '{"db":"postgres"}'

error_handle(message, context)

if ! validate_input "$data"; then
    error_handle "Invalid input" '{"input":"'$data'"}'
    return 1
fi

is_error_code(expected_code)

curl https://api.example.com
if is_error_code 7; then
    echo "Connection failed"
fi

Retry Logic (lib/retry.sh)

retry_with_backoff(max_attempts, base_delay_sec, command, args...)

# Retry curl with exponential backoff (2s, 4s, 8s)
retry_with_backoff 3 2 curl -f https://api.example.com/data

# Retry custom command
retry_with_backoff 5 1 cfn-spawn agent "backend-developer" --task "task"

File Operations (lib/file-ops.sh)

atomic_write(filepath, content)

atomic_write "/tmp/data.json" '{"status":"complete"}'

acquire_lock(lockfile, timeout_sec)

if acquire_lock "/tmp/resource.lock" 30; then
    # Critical section
    release_lock "/tmp/resource.lock"
fi

release_lock(lockfile)

release_lock "/tmp/resource.lock"

with_lock(lockfile, timeout_sec, command, args...)

with_lock "/tmp/database.lock" 60 ./scripts/migrate-db.sh

Integration Points

TypeScript Compatibility

Logging Format:

• JSON output compatible with

  src/utils/logging.ts

• Correlation ID format matches TypeScript UUID generation
• Timestamp format: ISO 8601 (UTC)

Error Codes:

• Error codes align with

  src/utils/errors.ts

• Exit codes: 0=success, 1=general error, 2=usage error, 130=timeout

File Locking:

• Lock files use

  .lock

  extension (same as

  src/utils/file-operations.ts

  )
• Timeout behavior matches TypeScript implementation

CFN System Integration

Used By:

• .claude/hooks/cfn-invoke-pre-edit.sh

  - atomic backup creation

• .claude/skills/cfn-coordination/

  - structured logging

• .claude/skills/cfn-loop-orchestration/orchestrate.sh

  - retry logic
• All CFN agents - standardized error handling

Correlation IDs:

# Generate correlation ID (compatible with TypeScript)
CORRELATION_ID=$(uuidgen 2>/dev/null || echo "$(date +%s)-$$-$RANDOM")
log_info "Request started" '{"correlation_id":"'$CORRELATION_ID'"}'

Testing

# Run all tests
./.claude/skills/cfn-utilities/test.sh

# Expected output:
# PASS: log_json outputs valid JSON
# PASS: retry_with_backoff succeeds after failures
# PASS: atomic_write creates file atomically
# PASS: with_lock prevents concurrent execution
# All tests passed (15/15)

Implementation Patterns

Safe Script Template

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/.claude/skills/cfn-utilities/execute.sh"

main() {
    log_info "Script started" '{"script":"'$(basename "$0")'"}'

    retry_with_backoff 3 2 risky_operation || {
        error_exit "Operation failed after retries" 1
    }

    atomic_write "/tmp/result.txt" "Success"
    log_info "Script completed" '{"status":"success"}'
}

main "$@"

Critical Section Pattern

#!/usr/bin/env bash
source ./.claude/skills/cfn-utilities/execute.sh

# Ensure only one instance modifies shared resource
with_lock "/tmp/shared-resource.lock" 30 bash -c '
    log_info "Updating shared resource"
    echo "new data" >> /tmp/shared-resource.txt
    log_info "Update complete"
'

Best Practices

1. Always use structured logging - Include context objects for debugging
2. Set strict mode - Use

   set -euo pipefail

   in all scripts
3. Use atomic operations - Prevent partial writes with atomic_write()
4. Implement retries - Handle transient failures gracefully
5. Lock shared resources - Prevent race conditions with file locks

Version History

• 1.0.0 (2025-11-15): Initial release with logging, errors, retry, and file ops