bash-executor

What this skill does

# Bash Executor Skill

Execute bash commands and shell scripts safely with comprehensive error handling, security validation, and best practices.

> **Plugin**: my-first-plugin | **Version**: 1.0.0

## When to Use This Skill

Use this skill when the user needs to:
- Execute system commands and utilities
- Process text files (grep, sed, awk, cut, sort)
- Manage files and directories
- Run CLI tools (curl, wget, git, docker)
- Create shell scripts for automation
- Parse command output and logs
- Execute batch operations
- System administration tasks

## Core Capabilities

1. **Safe Command Execution**: Validates commands before running
2. **Error Handling**: Comprehensive exit code checking
3. **Security Validation**: Blocks dangerous patterns
4. **Dry-Run Mode**: Preview commands before execution
5. **Output Capture**: Structured stdout/stderr handling
6. **Timeout Protection**: Prevents hanging processes
7. **Script Generation**: Creates reusable bash scripts

## Execution Workflow

### Step 1: Understand the Task
Determine if bash is the right tool:
- ✅ System operations, file management
- ✅ Text processing with standard tools
- ✅ CLI tool orchestration
- ❌ Complex logic (use Python/Node.js)
- ❌ API calls (use Node.js/Python)

### Step 2: Validate Commands
Check for dangerous patterns:
```bash
bash scripts/validate_command.sh "<command>"
```

### Step 3: Execute Safely
Use the helper script:
```bash
bash scripts/execute_bash.sh "<command>" [timeout]
# OR for scripts:
bash scripts/execute_bash.sh <script-file> [timeout]
```

### Step 4: Handle Errors
Check exit codes and provide meaningful feedback:
- Exit 0: Success
- Exit 1-127: Command-specific errors
- Exit 124: Timeout
- Exit 126: Permission denied
- Exit 127: Command not found

## Security Guidelines

### CRITICAL: Always Block These Patterns

❌ **NEVER Allow**:
```bash
rm -rf /              # System destruction
dd if=/dev/zero       # Disk wiping
:(){ :|:& };:        # Fork bombs
chmod 777 /          # Permission destruction
curl | bash          # Arbitrary code execution
eval $user_input     # Code injection
mkfs.*               # Filesystem formatting
```

✅ **Safe Patterns**:
```bash
ls -la                        # Directory listing
grep "pattern" file.txt       # Text search
find . -name "*.log"          # File finding
tar -czf backup.tar.gz dir/   # Archiving
sed 's/old/new/g' file.txt   # Text replacement
```

### Command Validation Rules

1. **No Root Operations**: Reject commands requiring sudo/root
2. **Path Restrictions**: Operations only in current directory or subdirectories
3. **No Destructive Commands**: Block rm -rf, dd, mkfs without confirmation
4. **No Arbitrary Downloads**: Validate URLs before wget/curl
5. **No Process Killing**: Restrict kill, killall commands

## Error Handling Best Practices

### Always Check Exit Codes
```bash
#!/bin/bash
set -euo pipefail  # Exit on error, undefined vars, pipe failures

if some_command; then
    echo "Success"
else
    echo "Failed with exit code: $?"
    exit 1
fi
```

### Use Trap for Cleanup
```bash
#!/bin/bash

cleanup() {
    echo "Cleaning up..."
    rm -f /tmp/tempfile
}

trap cleanup EXIT ERR

# Your commands here
```

### Validate Input
```bash
#!/bin/bash

FILE="${1:-}"

if [[ -z "$FILE" ]]; then
    echo "Error: File argument required" >&2
    exit 1
fi

if [[ ! -f "$FILE" ]]; then
    echo "Error: File not found: $FILE" >&2
    exit 1
fi
```

## Common Use Cases

### 1. File Management

**Create Directory Structure**:
```bash
mkdir -p project/{src,tests,docs,config}
echo "Created project structure"
```

**Find and Process Files**:
```bash
#!/bin/bash
# Find all .log files modified in last 7 days
find . -name "*.log" -mtime -7 -type f | while read -r file; do
    echo "Processing: $file"
    # Process each file
done
```

**Bulk Rename Files**:
```bash
#!/bin/bash
# Rename all .txt files to .md
for file in *.txt; do
    if [[ -f "$file" ]]; then
        mv "$file" "${file%.txt}.md"
        echo "Renamed: $file -> ${file%.txt}.md"
    fi
done
```

### 2. Text Processing

**Search and Extract**:
```bash
#!/bin/bash
# Extract email addresses from file
grep -Eo '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}' input.txt | \
    sort -u > emails.txt
echo "Extracted $(wc -l < emails.txt) unique emails"
```

**CSV Processing**:
```bash
#!/bin/bash
# Extract specific columns from CSV
cut -d',' -f1,3,5 input.csv | \
    grep -v "^#" | \
    sort > output.csv
```

**Log Analysis**:
```bash
#!/bin/bash
# Count error types in log file
awk '/ERROR/ {print $5}' app.log | \
    sort | uniq -c | sort -rn
```

### 3. System Operations

**Disk Usage Analysis**:
```bash
#!/bin/bash
# Find largest directories
du -h --max-depth=1 2>/dev/null | \
    sort -hr | head -20
```

**Process Management**:
```bash
#!/bin/bash
# Check if process is running
if pgrep -f "myapp" > /dev/null; then
    echo "Process is running"
    pgrep -f "myapp" | xargs ps -p
else
    echo "Process is not running"
fi
```

**Archive and Compress**:
```bash
#!/bin/bash
# Create dated backup
DATE=$(date +%Y%m%d)
tar -czf "backup_${DATE}.tar.gz" \
    --exclude='node_modules' \
    --exclude='.git' \
    ./project/
echo "Backup created: backup_${DATE}.tar.gz"
```

### 4. Data Pipeline

**Download and Process**:
```bash
#!/bin/bash
set -euo pipefail

URL="https://example.com/data.json"
OUTPUT="processed_data.json"

# Download
curl -fsSL "$URL" -o raw_data.json

# Process with jq
jq '.items[] | select(.status == "active")' raw_data.json > "$OUTPUT"

echo "Processed data saved to $OUTPUT"
```

**Multi-Step Pipeline**:
```bash
#!/bin/bash
set -euo pipefail

# Step 1: Download
echo "Downloading data..."
wget -q https://example.com/data.csv -O data.csv

# Step 2: Clean
echo "Cleaning data..."
sed 's/\r$//' data.csv | # Remove carriage returns
    grep -v '^$' |        # Remove empty lines
    tr -s ' ' > cleaned.csv

# Step 3: Analyze
echo "Analyzing..."
awk -F',' '{sum+=$3} END {print "Total:", sum}' cleaned.csv

echo "Pipeline completed"
```

### 5. Git Operations

**Repository Setup**:
```bash
#!/bin/bash
set -euo pipefail

REPO_NAME="${1:-my-repo}"

mkdir -p "$REPO_NAME"
cd "$REPO_NAME"

git init
echo "# $REPO_NAME" > README.md
echo "node_modules/" > .gitignore
echo ".env" >> .gitignore

git add .
git commit -m "Initial commit"

echo "Repository initialized: $REPO_NAME"
```

**Branch Management**:
```bash
#!/bin/bash
# Create feature branch from main
git checkout main
git pull origin main
git checkout -b feature/new-feature
echo "Created and switched to feature/new-feature"
```

### 6. Docker Operations

**Container Management**:
```bash
#!/bin/bash
# Stop and remove all containers
docker ps -aq | xargs -r docker stop
docker ps -aq | xargs -r docker rm
echo "All containers stopped and removed"
```

**Image Cleanup**:
```bash
#!/bin/bash
# Remove dangling images
docker images -f "dangling=true" -q | xargs -r docker rmi
echo "Dangling images removed"
```

## Advanced Patterns

### Parallel Execution
```bash
#!/bin/bash
# Process files in parallel
find . -name "*.txt" -print0 | \
    xargs -0 -P 4 -I {} bash -c 'process_file "$@"' _ {}
```

### Progress Monitoring
```bash
#!/bin/bash
# Show progress for long operations
TOTAL=$(ls -1 *.txt | wc -l)
COUNT=0

for file in *.txt; do
    COUNT=$((COUNT + 1))
    echo "Processing $COUNT/$TOTAL: $file"
    # Process file
done
```

### Error Recovery
```bash
#!/bin/bash
# Retry on failure
MAX_RETRIES=3
RETRY_DELAY=5

for i in $(seq 1 $MAX_RETRIES); do
    if some_command; then
        echo "Success on attempt $i"
        break
    else
        echo "Failed attempt $i/$MAX_RETRIES"
        if [[ $i -lt $MAX_RETRIES ]]; then
            echo "Retrying in ${RETRY_DELAY}s..."
            sleep $RETRY_DELAY
        fi
    fi
done
```

## Helper Scripts Available

### Execute Command/Script
```bash
bash scripts/execute_bash.sh "<command>" [timeout]
bash scripts/execute_bash.sh script.sh [timeout]
```

### Validate Command
```bash
bash scripts/vali