npm - claude-flow-novice - Versions diffs - 2.18.6 → 2.18.8 - Mend

claude-flow-novice 2.18.6 → 2.18.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1000) hide show

package/claude-assets/skills/cfn-sprint-execution/lib/checkpoint/SKILL.md DELETED Viewed

@@ -1,333 +0,0 @@
-# CFN Wave Checkpoint Skill
-## Overview
-Wave checkpoint mechanism provides crash recovery, orphan container detection, and automated resumption capabilities for CFN Docker orchestration. Enables orchestrators to survive process failures and resume wave execution without losing work or leaving orphaned containers.
-## Architecture
-### Checkpoint Flow
-```
-execute_waves()
-    ├── spawn_wave(task_id, wave_num)
-    │   └── save_checkpoint(task_id, wave_num, container_ids, ...)
-    ├── monitor_wave(task_id, wave_num)
-    │   └── CRASH: Container/process dies
-    └── RESUME: detect_checkpoint() → resume_wave() → cleanup_orphans()
-```
-### Storage
-- **Primary**: Redis keys with TTL
-- **Format**: JSON serialized checkpoint data
-- **Key Pattern**: `cfn:wave:checkpoint:{task_id}:{wave_number}`
-- **Index**: `cfn:wave:checkpoints:{task_id}` (set of all wave numbers)
-### Checkpoint Data Structure
-```json
-{
-  "task_id": "task-123",
-  "wave_number": 1,
-  "container_ids": ["id1", "id2", "id3"],
-  "spawn_time": 1700000000,
-  "expected_count": 3,
-  "created_at": "2024-11-14T12:00:00Z",
-  "status": "in_progress"
-}
-```
-## Components
-### 1. save-checkpoint.sh
-Saves execution state before or during wave spawning. Non-blocking: if Redis unavailable, continues execution.
-**Operations:**
-- `save TASK_ID WAVE_NUMBER CONTAINER_IDS SPAWN_TIME EXPECTED_COUNT`
-- `exists TASK_ID [WAVE_NUMBER]`
-- `get TASK_ID WAVE_NUMBER`
-- `update-status TASK_ID WAVE_NUMBER STATUS`
-**Usage:**
-```bash
-# Save checkpoint before monitoring
-./save-checkpoint.sh save task-123 1 "id1,id2,id3" 1700000000 3
-# Check if checkpoint exists
-./save-checkpoint.sh exists task-123 1
-# Get checkpoint data
-./save-checkpoint.sh get task-123 1
-# Update status to completed
-./save-checkpoint.sh update-status task-123 1 "completed"
-```
-**Exit Codes:**
-- 0: Success
-- 1: Validation error
-- 2: Redis connection error
-### 2. resume-wave.sh
-Detects checkpoints and resumes orphaned containers. Verifies containers still running, updates status.
-**Operations:**
-- `resume TASK_ID [WAVE_NUMBER]`
-- `get-resumable TASK_ID`
-- `verify TASK_ID WAVE_NUMBER`
-**Usage:**
-```bash
-# Resume all waves with checkpoints
-./resume-wave.sh resume task-123
-# Resume specific wave
-./resume-wave.sh resume task-123 1
-# Get list of resumable waves
-./resume-wave.sh get-resumable task-123
-# Verify container status for wave
-./resume-wave.sh verify task-123 1
-```
-**Exit Codes:**
-- 0: Success
-- 1: Validation error / No checkpoints found
-- 2: Redis connection error
-### 3. cleanup-orphans.sh
-Removes orphaned containers while preserving logs for post-mortem analysis.
-**Operations:**
-- `cleanup TASK_ID [WAVE_NUMBER]`
-- `list TASK_ID [WAVE_NUMBER]`
-- `summary TASK_ID`
-**Configuration:**
-- `LOG_PRESERVE_DIR`: Directory for preserved logs (default: `.logs/wave-recovery`)
-- `DRY_RUN`: Preview cleanup without removing (default: `false`)
-**Usage:**
-```bash
-# Clean all orphaned containers for task
-./cleanup-orphans.sh cleanup task-123
-# Clean specific wave orphans
-./cleanup-orphans.sh cleanup task-123 1
-# List orphaned containers (no cleanup)
-./cleanup-orphans.sh list task-123
-# View cleanup summary
-./cleanup-orphans.sh summary task-123
-# Dry-run: preview cleanup
-DRY_RUN=true ./cleanup-orphans.sh cleanup task-123
-```
-**Exit Codes:**
-- 0: Success
-- 1: Validation error
-- 2: Cleanup errors occurred
-## Integration with orchestrate.sh
-### Checkpoint Detection
-Add to `execute_waves()` before spawning:
-```bash
-execute_waves() {
-    local task_id="$1"
-    local plan_file="$2"
-    # Check for existing checkpoint
-    if source "./.claude/skills/cfn-wave-checkpoint/save-checkpoint.sh" && \
-       checkpoint_exists "$task_id"; then
-        log "Found checkpoint, resuming..."
-        # Resume execution
-        source "./.claude/skills/cfn-wave-checkpoint/resume-wave.sh"
-        resume_wave "$task_id"
-        # Continue monitoring from checkpoint
-    else
-        # Normal execution path
-        # ... spawn and monitor waves ...
-    fi
-}
-```
-### Checkpoint Saving
-Add after successful wave spawn:
-```bash
-# In spawn_wave completion
-if $(./.claude/skills/cfn-wave-checkpoint/save-checkpoint.sh \
-    save "$task_id" "$wave_num" "$container_ids" "$(date +%s)" "$batch_count"); then
-    log_success "Checkpoint saved for recovery"
-fi
-```
-### Orphan Cleanup
-Add to wave cleanup phase:
-```bash
-# After wave completion
-$(./.claude/skills/cfn-wave-checkpoint/cleanup-orphans.sh \
-    cleanup "$task_id" "$wave_num")
-```
-## Recovery Scenarios
-### Scenario 1: Orchestrator Crash During Wave Spawn
-1. Orchestrator dies while spawning containers
-2. Some containers started, recorded in checkpoint
-3. On restart:
-   - Detect checkpoint for wave N
-   - Resume from checkpoint
-   - Verify containers still running
-   - Continue monitoring
-### Scenario 2: Network Failure During Monitoring
-1. Network disconnects during wave monitoring
-2. Checkpoint persisted in Redis
-3. On recovery:
-   - Detect checkpoint
-   - Verify containers still exist (they continue running in Docker)
-   - Resume monitoring from last recorded state
-   - Complete monitoring
-### Scenario 3: Unplanned Process Termination
-1. Orchestrator killed (OOM, signal 9, etc.)
-2. Checkpoint in Redis, containers in Docker
-3. Recovery process:
-   - Scan Redis for checkpoints
-   - List all containers for task
-   - Clean up orphans with log preservation
-   - Option to resume from checkpoint
-## Best Practices
-### Checkpoint Lifecycle
-1. **Create**: Save checkpoint immediately after successful spawn
-2. **Update**: Mark as "in_progress", then "monitoring"
-3. **Complete**: Mark as "completed" when wave finishes
-4. **Clean**: Archive logs, remove checkpoint from Redis
-### Log Preservation
-- All container logs saved to `.logs/wave-recovery/{task_id}/wave-{number}/`
-- Includes Docker inspect output for debugging
-- Preserved even if containers are removed
-- Accessible for post-mortem analysis
-### Redis Configuration
-- TTL: 3600 seconds (1 hour, configurable via `CHECKPOINT_TTL`)
-- Namespace: `cfn:wave:checkpoint:*`
-- Indexed by: `cfn:wave:checkpoints:{task_id}`
-- Cleanup: TTL-based auto-expiration
-### Error Handling
-```bash
-# Non-fatal checkpoint errors
-if ! save_checkpoint ...; then
-    log_warning "Checkpoint save failed, continuing without recovery"
-    # Execution continues
-fi
-# Fatal resume errors
-if ! resume_wave ...; then
-    log_error "Failed to resume from checkpoint"
-    # Decide: retry, abort, or manual intervention
-fi
-```
-## Testing
-Test suite validates:
-1. **Checkpoint Creation**
-   - Save with container IDs
-   - Verify Redis storage
-   - Check data structure
-2. **Checkpoint Recovery**
-   - Detect existing checkpoints
-   - Verify containers exist
-   - Update status correctly
-3. **Orphan Detection**
-   - Find containers for task/wave
-   - Preserve logs before cleanup
-   - Record cleanup metadata
-4. **Edge Cases**
-   - Redis unavailable (non-blocking)
-   - Containers removed externally
-   - Partial wave completion
-   - Multiple concurrent tasks
-## Limitations
-- Redis required for cross-process recovery
-- Docker labels must be set for container filtering
-- Log preservation depends on disk space
-- TTL means checkpoints expire after 1 hour
-## Future Enhancements
-1. **Distributed Checkpointing**
-   - Multi-region Redis replication
-   - Checkpoint mirroring
-2. **Enhanced Analytics**
-   - Failure root cause analysis
-   - Recovery success metrics
-3. **Automatic Remediation**
-   - Self-healing on detected failures
-   - Automatic container replacement
-4. **Checkpoint Versioning**
-   - Multiple checkpoint snapshots
-   - Rollback to earlier state
-## Configuration Variables
-```bash
-# Redis connection
-REDIS_HOST=localhost
-REDIS_PORT=6379
-REDIS_PASSWORD=
-# Checkpoint settings
-CHECKPOINT_TTL=3600           # 1 hour
-LOG_PRESERVE_DIR=.logs/wave-recovery
-# Cleanup behavior
-DRY_RUN=false                 # Preview mode
-CLEANUP_PARALLEL=5            # Parallel cleanup workers
-```
-## Related Skills
-- `cfn-docker-wave-execution`: Wave spawning and monitoring
-- `cfn-docker-redis-coordination`: Redis communication layer
-- `cfn-error-batching-strategy`: Wave batching and planning

package/claude-assets/skills/cfn-sprint-execution/lib/checkpoint/cleanup-orphans.sh DELETED Viewed

@@ -1,374 +0,0 @@
-#!/bin/bash
-################################################################################
-# CFN Wave Checkpoint - Cleanup Orphaned Containers
-# Purpose: Remove containers from failed orchestrator runs, preserve logs
-# Version: 1.0.0
-# Exit Codes: 0=success, 1=validation_error, 2=cleanup_error
-################################################################################
-set -euo pipefail
-# Script configuration
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../" && pwd)"
-# Redis configuration
-readonly REDIS_HOST="${REDIS_HOST:-localhost}"
-readonly REDIS_PORT="${REDIS_PORT:-6379}"
-readonly DEFAULT_REDIS_DB=0
-readonly DEFAULT_TIMEOUT=30
-readonly CHECKPOINT_TTL="${CHECKPOINT_TTL:-3600}"
-# Helper: Check Redis connection
-check_redis_connection() {
-    if ! command -v redis-cli &> /dev/null; then
-        return 1
-    fi
-    redis-cli -h "$REDIS_HOST" -p "$REDIS_PORT" ping >/dev/null 2>&1
-    return $?
-}
-# Color codes
-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'
-# Configuration
-LOG_PRESERVE_DIR="${LOG_PRESERVE_DIR:-./.logs/wave-recovery}"
-DRY_RUN=${DRY_RUN:-false}
-# 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_error() {
-    echo -e "${RED}[ERROR]${NC} $(date '+%H:%M:%S') $*" >&2
-}
-log_warning() {
-    echo -e "${YELLOW}[WARN]${NC} $(date '+%H:%M:%S') $*" >&2
-}
-log_debug() {
-    echo -e "${CYAN}[DEBUG]${NC} $(date '+%H:%M:%S') $*" >&2
-}
-################################################################################
-# ORPHAN CONTAINER DETECTION AND CLEANUP
-################################################################################
-cleanup_orphans() {
-    local task_id="$1"
-    local wave_number="${2:-}"
-    if [[ -z "$task_id" ]]; then
-        log_error "Usage: cleanup_orphans TASK_ID [WAVE_NUMBER]"
-        return 1
-    fi
-    log_info "Starting orphan container cleanup for task=$task_id"
-    # Verify Redis connectivity
-    if ! check_redis_connection >/dev/null 2>&1; then
-        log_warning "Redis not available - proceeding with Docker-only cleanup"
-    fi
-    local cleanup_count=0
-    local failed_count=0
-    if [[ -z "$wave_number" ]]; then
-        # Clean all waves for this task
-        log_info "Scanning for all orphaned containers in task=$task_id"
-        local orphans
-        orphans=$(docker ps -a --filter "label=cfn.task=$task_id" --format "{{.ID}}" 2>/dev/null || echo "")
-        if [[ -z "$orphans" ]]; then
-            log_info "No orphaned containers found for task=$task_id"
-            return 0
-        fi
-        while IFS= read -r container_id; do
-            if [[ -n "$container_id" ]]; then
-                if _cleanup_container "$container_id" "$task_id"; then
-                    ((cleanup_count++))
-                else
-                    ((failed_count++))
-                fi
-            fi
-        done <<< "$orphans"
-    else
-        # Clean specific wave
-        log_info "Scanning for orphaned containers in task=$task_id wave=$wave_number"
-        local orphans
-        orphans=$(docker ps -a \
-            --filter "label=cfn.task=$task_id" \
-            --filter "label=cfn.wave=$wave_number" \
-            --format "{{.ID}}" 2>/dev/null || echo "")
-        if [[ -z "$orphans" ]]; then
-            log_info "No orphaned containers found for wave $wave_number"
-            return 0
-        fi
-        while IFS= read -r container_id; do
-            if [[ -n "$container_id" ]]; then
-                if _cleanup_container "$container_id" "$task_id" "$wave_number"; then
-                    ((cleanup_count++))
-                else
-                    ((failed_count++))
-                fi
-            fi
-        done <<< "$orphans"
-    fi
-    log_success "Orphan cleanup complete: $cleanup_count removed, $failed_count failed"
-    if [[ $failed_count -gt 0 ]]; then
-        return 2
-    fi
-    return 0
-}
-################################################################################
-# SINGLE CONTAINER CLEANUP
-################################################################################
-_cleanup_container() {
-    local container_id="$1"
-    local task_id="$2"
-    local wave_number="${3:-}"
-    log_info "Cleaning up container: $container_id"
-    # Preserve logs before cleanup
-    if ! _preserve_logs "$container_id" "$task_id" "$wave_number"; then
-        log_warning "Failed to preserve logs for container $container_id"
-    fi
-    # Get container info for post-mortem
-    local container_info
-    container_info=$(docker ps -a --filter "id=$container_id" --format "json" 2>/dev/null || echo "{}")
-    # Stop container if running
-    if docker ps --filter "id=$container_id" --format "{{.ID}}" 2>/dev/null | grep -q "$container_id"; then
-        log_debug "Stopping container $container_id"
-        if [[ "$DRY_RUN" == "true" ]]; then
-            log_debug "[DRY_RUN] Would stop container: docker stop $container_id"
-        else
-            docker stop "$container_id" 2>/dev/null || log_warning "Failed to stop container gracefully"
-        fi
-    fi
-    # Remove container
-    log_debug "Removing container $container_id"
-    if [[ "$DRY_RUN" == "true" ]]; then
-        log_debug "[DRY_RUN] Would remove container: docker rm -f $container_id"
-        return 0
-    else
-        if docker rm -f "$container_id" 2>/dev/null; then
-            log_success "Removed orphaned container: $container_id"
-            # Record removal in cleanup log
-            _record_cleanup "$container_id" "$task_id" "$container_info"
-            return 0
-        else
-            log_error "Failed to remove container: $container_id"
-            return 1
-        fi
-    fi
-}
-################################################################################
-# LOG PRESERVATION
-################################################################################
-_preserve_logs() {
-    local container_id="$1"
-    local task_id="$2"
-    local wave_number="${3:-unknown}"
-    # Create log directory structure
-    local log_dir="$LOG_PRESERVE_DIR/${task_id}/wave-${wave_number}"
-    if [[ "$DRY_RUN" == "true" ]]; then
-        log_debug "[DRY_RUN] Would preserve logs to: $log_dir"
-        return 0
-    fi
-    mkdir -p "$log_dir" 2>/dev/null || {
-        log_warning "Failed to create log directory: $log_dir"
-        return 1
-    }
-    # Extract and save container logs
-    local log_file="${log_dir}/${container_id}.log"
-    if docker logs "$container_id" > "$log_file" 2>&1; then
-        log_debug "Preserved logs to: $log_file"
-        # Also save container inspect output
-        docker inspect "$container_id" > "${log_dir}/${container_id}.inspect.json" 2>/dev/null || true
-        return 0
-    else
-        log_warning "Failed to extract logs for container $container_id"
-        return 1
-    fi
-}
-################################################################################
-# CLEANUP RECORDING
-################################################################################
-_record_cleanup() {
-    local container_id="$1"
-    local task_id="$2"
-    local container_info="$3"
-    if [[ "$DRY_RUN" == "true" ]]; then
-        return 0
-    fi
-    # Create cleanup record in Redis
-    if check_redis_connection >/dev/null 2>&1; then
-        local cleanup_record
-        cleanup_record=$(jq -n \
-            --arg container_id "$container_id" \
-            --arg task_id "$task_id" \
-            --arg cleaned_at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-            --arg container_info "$container_info" \
-            '{
-                container_id: $container_id,
-                task_id: $task_id,
-                cleaned_at: $cleaned_at,
-                container_info: ($container_info | fromjson)
-            }')
-        redis-cli \
-            -h "${REDIS_HOST:-localhost}" \
-            -p "${REDIS_PORT:-6379}" \
-            LPUSH "cfn:wave:cleanup-records:${task_id}" "$cleanup_record" 2>/dev/null || true
-    fi
-    # Also record in local file
-    local cleanup_log="${LOG_PRESERVE_DIR}/${task_id}/cleanup.log"
-    mkdir -p "$(dirname "$cleanup_log")" 2>/dev/null || true
-    {
-        echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) | Removed container: $container_id"
-        if [[ -n "$container_info" ]]; then
-            echo "  Info: $container_info"
-        fi
-    } >> "$cleanup_log" 2>/dev/null || true
-}
-################################################################################
-# LIST ORPHANED CONTAINERS
-################################################################################
-list_orphans() {
-    local task_id="$1"
-    local wave_number="${2:-}"
-    if [[ -z "$task_id" ]]; then
-        log_error "Usage: list_orphans TASK_ID [WAVE_NUMBER]"
-        return 1
-    fi
-    local filter_args="--filter=label=cfn.task=$task_id"
-    if [[ -n "$wave_number" ]]; then
-        filter_args="$filter_args --filter=label=cfn.wave=$wave_number"
-    fi
-    log_info "Listing orphaned containers for task=$task_id"
-    docker ps -a $filter_args --format "table {{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Labels}}" 2>/dev/null || {
-        log_error "Failed to list containers"
-        return 1
-    }
-}
-################################################################################
-# CLEANUP SUMMARY
-################################################################################
-cleanup_summary() {
-    local task_id="$1"
-    if [[ -z "$task_id" ]]; then
-        log_error "Usage: cleanup_summary TASK_ID"
-        return 1
-    fi
-    log_info "Cleanup summary for task=$task_id"
-    # Count cleanup records
-    if check_redis_connection >/dev/null 2>&1; then
-        local record_count
-        record_count=$(redis-cli \
-            -h "${REDIS_HOST:-localhost}" \
-            -p "${REDIS_PORT:-6379}" \
-            LLEN "cfn:wave:cleanup-records:${task_id}" 2>/dev/null || echo "0")
-        echo "Containers cleaned: $record_count"
-    fi
-    # Count preserved logs
-    if [[ -d "$LOG_PRESERVE_DIR/$task_id" ]]; then
-        local log_count
-        log_count=$(find "$LOG_PRESERVE_DIR/$task_id" -type f -name "*.log" 2>/dev/null | wc -l)
-        echo "Logs preserved: $log_count"
-        echo "Log directory: $LOG_PRESERVE_DIR/$task_id"
-    fi
-}
-################################################################################
-# MAIN OPERATION DISPATCH
-################################################################################
-main() {
-    local operation="${1:-}"
-    shift || true
-    case "$operation" in
-        cleanup)
-            # cleanup TASK_ID [WAVE_NUMBER]
-            cleanup_orphans "$@"
-            ;;
-        list)
-            # list TASK_ID [WAVE_NUMBER]
-            list_orphans "$@"
-            ;;
-        summary)
-            # summary TASK_ID
-            cleanup_summary "$@"
-            ;;
-        *)
-            log_error "Unknown operation: $operation"
-            echo "Available operations: cleanup, list, summary"
-            return 1
-            ;;
-    esac
-}
-# Execute if not sourced
-if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
-    main "$@"
-fi