claude-flow-novice 2.18.5 → 2.18.6

package/.claude/skills/cfn-utilities/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: cfn-utilities
+description: Reusable bash utility functions for CFN Loop - logging, error handling, retry, file operations
+version: 1.0.0
+tags: [bash, logging, error-handling, retry, file-operations, utilities]
+status: production
+category: utilities
+---
+
+# 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
+
+```bash
+# 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
+
+```bash
+# 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)**
+```bash
+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)**
+```bash
+log_info "Processing file" '{"file":"data.txt"}'
+```
+
+**log_warn(message, context)**
+```bash
+log_warn "Deprecated function used" '{"function":"old_func"}'
+```
+
+**log_error(message, context)**
+```bash
+log_error "Failed to connect" '{"host":"api.example.com","code":500}'
+```
+
+**log_debug(message, context)**
+```bash
+export LOG_LEVEL=debug
+log_debug "Variable state" '{"var":"value"}'
+```
+
+### Error Handling (lib/errors.sh)
+
+**error_exit(message, exit_code, context)**
+```bash
+error_exit "Database connection failed" 1 '{"db":"postgres"}'
+```
+
+**error_handle(message, context)**
+```bash
+if ! validate_input "$data"; then
+    error_handle "Invalid input" '{"input":"'$data'"}'
+    return 1
+fi
+```
+
+**is_error_code(expected_code)**
+```bash
+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...)**
+```bash
+# 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)**
+```bash
+atomic_write "/tmp/data.json" '{"status":"complete"}'
+```
+
+**acquire_lock(lockfile, timeout_sec)**
+```bash
+if acquire_lock "/tmp/resource.lock" 30; then
+    # Critical section
+    release_lock "/tmp/resource.lock"
+fi
+```
+
+**release_lock(lockfile)**
+```bash
+release_lock "/tmp/resource.lock"
+```
+
+**with_lock(lockfile, timeout_sec, command, args...)**
+```bash
+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**:
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+#!/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
+
+```bash
+#!/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

package/.claude/skills/cfn-utilities/execute.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# CFN Utilities - Main entry point
+# Sources all utility libraries and provides function execution
+# Usage: ./.claude/skills/cfn-utilities/execute.sh <function> <args>
+
+set -euo pipefail
+
+# Get script directory (absolute path)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source all utility libraries
+source "$SCRIPT_DIR/lib/logging.sh"
+source "$SCRIPT_DIR/lib/errors.sh"
+source "$SCRIPT_DIR/lib/retry.sh"
+source "$SCRIPT_DIR/lib/file-ops.sh"
+
+# If script is executed directly (not sourced), run the requested function
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+    if [ $# -eq 0 ]; then
+        echo "Usage: $0 <function> [args...]" >&2
+        echo "" >&2
+        echo "Available functions:" >&2
+        echo "  Logging: log_json, log_info, log_warn, log_error, log_debug" >&2
+        echo "  Errors: error_exit, error_handle, is_error_code" >&2
+        echo "  Retry: retry_with_backoff, retry_fixed, retry_until_timeout" >&2
+        echo "  File Ops: atomic_write, acquire_lock, release_lock, with_lock, is_locked" >&2
+        exit 2
+    fi
+
+    # Execute the requested function with its arguments
+    "$@"
+fi

package/.claude/skills/cfn-utilities/lib/errors.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Error handling utilities for CFN system
+# Compatible with TypeScript errors.ts conventions
+
+# Source logging if not already loaded
+if ! declare -f log_error >/dev/null 2>&1; then
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    source "$SCRIPT_DIR/logging.sh"
+fi
+
+# Log error and exit with specified code
+# Usage: error_exit "message" exit_code '{"context":"json"}'
+error_exit() {
+    local message="${1:-Unknown error}"
+    local exit_code="${2:-1}"
+    local context="${3:-{}}"
+
+    log_error "$message" "$context"
+    exit "$exit_code"
+}
+
+# Handle error without exiting (just log and return error code)
+# Usage: error_handle "message" '{"context":"json"}' || return 1
+error_handle() {
+    local message="${1:-Unknown error}"
+    local context="${2:-{}}"
+
+    log_error "$message" "$context"
+    return 1
+}
+
+# Check if exit code matches expected value
+# Usage: some_command; EXITCODE=$?; if is_error_code $EXITCODE 7; then echo "Connection failed"; fi
+is_error_code() {
+    local actual_code="${1:?Exit code required}"
+    local expected_code="${2:-1}"
+
+    [ "$actual_code" -eq "$expected_code" ]
+}
+
+# Capture error context from last failed command
+# Usage: get_error_context
+get_error_context() {
+    local exit_code=$?
+    local line_number="${BASH_LINENO[0]}"
+    local function_name="${FUNCNAME[1]}"
+
+    echo "{\"exit_code\":$exit_code,\"line\":$line_number,\"function\":\"$function_name\"}"
+}
+
+# Standard exit codes (compatible with TypeScript errors.ts)
+readonly EXIT_SUCCESS=0
+readonly EXIT_GENERAL_ERROR=1
+readonly EXIT_USAGE_ERROR=2
+readonly EXIT_TIMEOUT=130
+readonly EXIT_INTERRUPT=143

package/.claude/skills/cfn-utilities/lib/file-ops.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+# Atomic file operations and locking for CFN system
+
+# Source logging if not already loaded
+if ! declare -f log_info >/dev/null 2>&1; then
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    source "$SCRIPT_DIR/logging.sh"
+fi
+
+# Atomic file write (write-then-move pattern)
+# Usage: atomic_write "/path/to/file.txt" "content here"
+atomic_write() {
+    local filepath="${1:?Filepath required}"
+    local content="${2:?Content required}"
+
+    # Create parent directory if needed
+    local dirpath
+    dirpath=$(dirname "$filepath")
+    mkdir -p "$dirpath"
+
+    # Write to temporary file first
+    local tmpfile
+    tmpfile="${filepath}.tmp.$$"
+
+    if ! echo "$content" > "$tmpfile"; then
+        log_error "Failed to write temporary file" "{\"file\":\"$tmpfile\"}"
+        rm -f "$tmpfile"
+        return 1
+    fi
+
+    # Atomic move
+    if ! mv "$tmpfile" "$filepath"; then
+        log_error "Failed to move temporary file" "{\"tmpfile\":\"$tmpfile\",\"target\":\"$filepath\"}"
+        rm -f "$tmpfile"
+        return 1
+    fi
+
+    log_debug "Atomic write succeeded" "{\"file\":\"$filepath\",\"bytes\":${#content}}"
+    return 0
+}
+
+# Acquire file lock with timeout
+# Usage: if acquire_lock "/path/to/resource.lock" 30; then ... fi
+acquire_lock() {
+    local lockfile="${1:?Lockfile required}"
+    local timeout_sec="${2:-30}"
+
+    local start_time
+    start_time=$(date +%s)
+    local end_time=$((start_time + timeout_sec))
+
+    # Create lock directory if needed
+    local lockdir
+    lockdir=$(dirname "$lockfile")
+    mkdir -p "$lockdir"
+
+    while [ "$(date +%s)" -lt "$end_time" ]; do
+        # Try to create lock file atomically
+        if (set -o noclobber; echo $$ > "$lockfile") 2>/dev/null; then
+            log_debug "Lock acquired" "{\"lockfile\":\"$lockfile\",\"pid\":$$}"
+            return 0
+        fi
+
+        # Check if lock holder is still alive
+        if [ -f "$lockfile" ]; then
+            local lock_pid
+            lock_pid=$(cat "$lockfile" 2>/dev/null || echo "")
+
+            if [ -n "$lock_pid" ] && ! kill -0 "$lock_pid" 2>/dev/null; then
+                log_warn "Stale lock detected, removing" "{\"lockfile\":\"$lockfile\",\"stale_pid\":$lock_pid}"
+                rm -f "$lockfile"
+                continue
+            fi
+        fi
+
+        # Wait before retry
+        sleep 0.5
+    done
+
+    log_error "Failed to acquire lock (timeout)" "{\"lockfile\":\"$lockfile\",\"timeout\":$timeout_sec}"
+    return 1
+}
+
+# Release file lock
+# Usage: release_lock "/path/to/resource.lock"
+release_lock() {
+    local lockfile="${1:?Lockfile required}"
+
+    if [ ! -f "$lockfile" ]; then
+        log_warn "Lock file does not exist" "{\"lockfile\":\"$lockfile\"}"
+        return 1
+    fi
+
+    # Verify we own the lock
+    local lock_pid
+    lock_pid=$(cat "$lockfile" 2>/dev/null || echo "")
+
+    if [ "$lock_pid" != "$$" ]; then
+        log_warn "Cannot release lock owned by another process" "{\"lockfile\":\"$lockfile\",\"owner\":$lock_pid,\"current\":$$}"
+        return 1
+    fi
+
+    if ! rm -f "$lockfile"; then
+        log_error "Failed to remove lock file" "{\"lockfile\":\"$lockfile\"}"
+        return 1
+    fi
+
+    log_debug "Lock released" "{\"lockfile\":\"$lockfile\",\"pid\":$$}"
+    return 0
+}
+
+# Execute command with file lock held
+# Usage: with_lock "/path/to/resource.lock" timeout_sec command [args...]
+with_lock() {
+    local lockfile="${1:?Lockfile required}"
+    local timeout_sec="${2:?Timeout required}"
+    shift 2
+    local command=("$@")
+
+    # Acquire lock
+    if ! acquire_lock "$lockfile" "$timeout_sec"; then
+        log_error "Failed to acquire lock for command execution" "{\"lockfile\":\"$lockfile\",\"command\":\"${command[0]}\"}"
+        return 1
+    fi
+
+    # Setup trap to release lock on exit
+    trap "release_lock '$lockfile'" EXIT INT TERM
+
+    # Execute command
+    local exit_code=0
+    "${command[@]}" || exit_code=$?
+
+    # Release lock
+    release_lock "$lockfile" || true
+
+    # Remove trap
+    trap - EXIT INT TERM
+
+    return $exit_code
+}
+
+# Check if file lock exists and is held by a living process
+# Usage: if is_locked "/path/to/resource.lock"; then ... fi
+is_locked() {
+    local lockfile="${1:?Lockfile required}"
+
+    if [ ! -f "$lockfile" ]; then
+        return 1
+    fi
+
+    local lock_pid
+    lock_pid=$(cat "$lockfile" 2>/dev/null || echo "")
+
+    if [ -z "$lock_pid" ]; then
+        return 1
+    fi
+
+    # Check if process is alive
+    if kill -0 "$lock_pid" 2>/dev/null; then
+        return 0  # Locked by living process
+    else
+        return 1  # Stale lock
+    fi
+}

package/.claude/skills/cfn-utilities/lib/logging.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Structured logging utilities for CFN system
+# Compatible with TypeScript logging.ts format
+
+# Get current timestamp in ISO 8601 format (UTC)
+get_timestamp() {
+    date -u +"%Y-%m-%dT%H:%M:%SZ"
+}
+
+# Output structured JSON log
+# Usage: log_json "level" "message" '{"context":"json"}'
+log_json() {
+    local level="${1:-info}"
+    local message="${2:-}"
+    local context="${3:-{}}"
+    local timestamp
+    timestamp=$(get_timestamp)
+
+    # Escape message for JSON (basic escaping)
+    message=$(echo "$message" | sed 's/"/\\"/g' | sed 's/\\/\\\\/g')
+
+    # Output JSON (ensure context is valid JSON)
+    if [ "$context" = "{}" ]; then
+        echo "{\"timestamp\":\"$timestamp\",\"level\":\"$level\",\"message\":\"$message\"}"
+    else
+        # Remove outer braces from context and merge
+        context_inner=$(echo "$context" | sed 's/^{//' | sed 's/}*$//')
+        echo "{\"timestamp\":\"$timestamp\",\"level\":\"$level\",\"message\":\"$message\",\"context\":{$context_inner}}"
+    fi
+}
+
+# Info level log
+# Usage: log_info "message" '{"key":"value"}'
+log_info() {
+    local message="${1:-}"
+    local context="${2:-{}}"
+    log_json "info" "$message" "$context" >&2
+}
+
+# Warning level log
+# Usage: log_warn "message" '{"key":"value"}'
+log_warn() {
+    local message="${1:-}"
+    local context="${2:-{}}"
+    log_json "warn" "$message" "$context" >&2
+}
+
+# Error level log
+# Usage: log_error "message" '{"key":"value"}'
+log_error() {
+    local message="${1:-}"
+    local context="${2:-{}}"
+    log_json "error" "$message" "$context" >&2
+}
+
+# Debug level log (respects LOG_LEVEL env var)
+# Usage: LOG_LEVEL=debug log_debug "message" '{"key":"value"}'
+log_debug() {
+    local message="${1:-}"
+    local context="${2:-{}}"
+
+    # Only output if LOG_LEVEL is debug or trace
+    if [[ "${LOG_LEVEL:-info}" =~ ^(debug|trace)$ ]]; then
+        log_json "debug" "$message" "$context" >&2
+    fi
+}
+
+# Generate correlation ID (compatible with TypeScript UUID format)
+# Usage: CORRELATION_ID=$(generate_correlation_id)
+generate_correlation_id() {
+    # Try uuidgen first, fallback to timestamp+pid+random
+    if command -v uuidgen >/dev/null 2>&1; then
+        uuidgen | tr '[:upper:]' '[:lower:]'
+    else
+        echo "$(date +%s)-$$-$RANDOM"
+    fi
+}

package/.claude/skills/cfn-utilities/lib/retry.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# Retry logic with exponential backoff for CFN system
+
+# Source logging if not already loaded
+if ! declare -f log_info >/dev/null 2>&1; then
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    source "$SCRIPT_DIR/logging.sh"
+fi
+
+# Retry command with exponential backoff
+# Usage: retry_with_backoff max_attempts base_delay_sec command [args...]
+# Example: retry_with_backoff 3 2 curl -f https://api.example.com
+retry_with_backoff() {
+    local max_attempts="${1:-3}"
+    local base_delay="${2:-2}"
+    shift 2
+    local command=("$@")
+
+    local attempt=1
+    local delay=$base_delay
+
+    while [ $attempt -le "$max_attempts" ]; do
+        log_debug "Attempt $attempt/$max_attempts: ${command[*]}" "{\"attempt\":$attempt,\"max\":$max_attempts}"
+
+        # Execute command and capture exit code immediately
+        "${command[@]}"
+        local exit_code=$?
+
+        # Check if command succeeded
+        if [ $exit_code -eq 0 ]; then
+            if [ $attempt -gt 1 ]; then
+                log_info "Command succeeded after retries" "{\"attempts\":$attempt,\"command\":\"${command[0]}\"}"
+            fi
+            return 0
+        fi
+
+        # Last attempt failed
+        if [ $attempt -eq "$max_attempts" ]; then
+            log_error "Command failed after $max_attempts attempts" "{\"command\":\"${command[0]}\",\"exit_code\":$exit_code}"
+            return $exit_code
+        fi
+
+        # Calculate next delay (exponential backoff: delay = base * 2^(attempt-1))
+        log_warn "Command failed, retrying in ${delay}s" "{\"attempt\":$attempt,\"delay\":$delay,\"exit_code\":$exit_code}"
+        sleep "$delay"
+
+        attempt=$((attempt + 1))
+        delay=$((delay * 2))
+    done
+
+    return 1
+}
+
+# Retry with fixed delay (no exponential backoff)
+# Usage: retry_fixed max_attempts delay_sec command [args...]
+retry_fixed() {
+    local max_attempts="${1:-3}"
+    local delay="${2:-2}"
+    shift 2
+    local command=("$@")
+
+    local attempt=1
+
+    while [ $attempt -le "$max_attempts" ]; do
+        log_debug "Attempt $attempt/$max_attempts: ${command[*]}" "{\"attempt\":$attempt}"
+
+        "${command[@]}"
+        local exit_code=$?
+
+        if [ $exit_code -eq 0 ]; then
+            return 0
+        fi
+
+        if [ $attempt -eq "$max_attempts" ]; then
+            log_error "Command failed after $max_attempts attempts" "{\"command\":\"${command[0]}\",\"exit_code\":$exit_code}"
+            return $exit_code
+        fi
+
+        log_warn "Command failed, retrying in ${delay}s" "{\"attempt\":$attempt,\"delay\":$delay}"
+        sleep "$delay"
+
+        attempt=$((attempt + 1))
+    done
+
+    return 1
+}
+
+# Retry until timeout (wall-clock timeout instead of attempt count)
+# Usage: retry_until_timeout timeout_sec delay_sec command [args...]
+retry_until_timeout() {
+    local timeout_sec="${1:-60}"
+    local delay="${2:-2}"
+    shift 2
+    local command=("$@")
+
+    local start_time
+    start_time=$(date +%s)
+    local end_time=$((start_time + timeout_sec))
+
+    local attempt=1
+
+    while [ "$(date +%s)" -lt "$end_time" ]; do
+        log_debug "Attempt $attempt (timeout in $((end_time - $(date +%s)))s): ${command[*]}" "{\"attempt\":$attempt}"
+
+        "${command[@]}"
+        local exit_code=$?
+
+        if [ $exit_code -eq 0 ]; then
+            return 0
+        fi
+
+        local current_time
+        current_time=$(date +%s)
+
+        if [ "$current_time" -ge "$end_time" ]; then
+            log_error "Command timed out after ${timeout_sec}s" "{\"command\":\"${command[0]}\",\"attempts\":$attempt,\"exit_code\":$exit_code}"
+            return 130  # Timeout exit code
+        fi
+
+        log_warn "Command failed, retrying in ${delay}s" "{\"attempt\":$attempt,\"remaining_time\":$((end_time - current_time))}"
+        sleep "$delay"
+
+        attempt=$((attempt + 1))
+    done
+
+    return 130
+}