claude-flow-novice 2.18.6 → 2.18.7

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

@@ -1,239 +0,0 @@
----
-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-assets/skills/cfn-utilities/execute.sh

@@ -1,32 +0,0 @@
-#!/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-assets/skills/cfn-utilities/lib/errors.sh

@@ -1,56 +0,0 @@
-#!/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-assets/skills/cfn-utilities/lib/file-ops.sh

@@ -1,164 +0,0 @@
-#!/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-assets/skills/cfn-utilities/lib/logging.sh

@@ -1,77 +0,0 @@
-#!/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-assets/skills/cfn-utilities/lib/retry.sh

@@ -1,127 +0,0 @@
-#!/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
-}