feat: Add Plex scripts documentation and enhance monitoring script with detailed checks and recommendations

2025-12-06 02:20:11 -08:00 · 2025-06-03 08:59:11 -04:00
parent 6e6b263c53
commit 94dc0e6c5b
2 changed files with 278 additions and 48 deletions
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -42,6 +42,17 @@ This repository contains:
 - **docs/docker-bootstrap-testing-framework.md**: Detailed documentation for the Docker-based bootstrap validation framework
 - **dotfiles/README.md**: Documentation for dotfiles setup and usage

+### Plex Scripts
+
+- **plex.sh**: Main Plex Media Server management script
+- **backup-plex.sh**: Automated backup system for Plex databases and configurations
+- **monitor-plex-backup.sh**: Monitoring and reporting for backup operations
+- **restore-plex.sh**: Database and configuration restoration utilities
+- **validate-plex-backups.sh**: Backup integrity verification system
+- **test-plex-backup.sh**: Testing framework for backup operations
+- **integration-test-plex.sh**: End-to-end integration testing for Plex services
+- **plex-recent-additions.sh**: Recent media additions reporting
+
 ## Style Guidelines

 When suggesting code or modifications:
@@ -159,3 +170,221 @@ For contributors and Copilot suggestions:
   - Run tests before submitting changes
   - Document what was changed and why
   - Consider both Ubuntu, Debian, and Fedora compatibility
+
+## Automatic Code Validation and Critical Error Checking
+
+When generating or modifying shell scripts, GitHub Copilot must automatically validate code and check for critical errors before suggesting changes.
+
+### Mandatory Validation Checks
+
+1. **Syntax Validation**:
+   - Always verify proper `if`/`fi`, `for`/`done`, `while`/`done` matching
+   - Check for balanced brackets: `[`, `]`, `[[`, `]]`
+   - Ensure proper function definition syntax: `function_name() { ... }`
+   - Validate case statement structure: `case`/`esac` matching
+   - Check for missing quotes around variables in conditions
+
+2. **Control Flow Validation**:
+   - Verify `else` statements have corresponding `if` statements
+   - Check that nested conditionals are properly indented and closed
+   - Ensure `break` and `continue` are only used within loops
+   - Validate that functions return appropriate exit codes
+
+3. **Variable and Quote Validation**:
+   - Always quote variables to prevent word splitting: `"$VARIABLE"`
+   - Check for undefined variables being used
+   - Validate array syntax and indexing
+   - Ensure proper escaping in strings containing special characters
+
+### Critical Logic Error Patterns to Check
+
+Based on analysis of plex scripts, watch for these common issues:
+
+1. **Service Management Logic**:
+   ```bash
+   # CORRECT: Check service status before operations
+   if sudo systemctl is-active --quiet plexmediaserver; then
+       sudo systemctl stop plexmediaserver
+   fi
+
+   # INCORRECT: Assuming service state without checking
+   sudo systemctl stop plexmediaserver  # May fail if already stopped
+   ```
+
+2. **File Operation Safety**:
+   ```bash
+   # CORRECT: Check file existence and permissions
+   if [[ -f "$BACKUP_FILE" && -r "$BACKUP_FILE" ]]; then
+       # Process file
+   else
+       echo "Error: Backup file not found or not readable"
+       exit 1
+   fi
+
+   # INCORRECT: Operating on files without validation
+   tar -xzf "$BACKUP_FILE"  # May fail silently
+   ```
+
+3. **Directory Operations**:
+   ```bash
+   # CORRECT: Verify directory creation and permissions
+   if ! mkdir -p "$BACKUP_DIR"; then
+       echo "Error: Failed to create backup directory"
+       exit 1
+   fi
+
+   # Set proper permissions
+   chmod 755 "$BACKUP_DIR"
+
+   # INCORRECT: Assuming directory operations succeed
+   mkdir -p "$BACKUP_DIR"
+   cd "$BACKUP_DIR"  # May fail if mkdir failed
+   ```
+
+4. **Database Operations**:
+   ```bash
+   # CORRECT: Validate database integrity before and after operations
+   if ! sqlite3 "$DB_FILE" "PRAGMA integrity_check;" | grep -q "ok"; then
+       echo "Error: Database integrity check failed"
+       exit 1
+   fi
+
+   # INCORRECT: Operating on database without validation
+   sqlite3 "$DB_FILE" ".backup backup.db"  # May corrupt if DB is damaged
+   ```
+
+5. **Parallel Processing Safety**:
+   ```bash
+   # CORRECT: Proper parallel job management with wait
+   for file in "${files[@]}"; do
+       process_file "$file" &
+       ((++job_count))
+
+       # Limit concurrent jobs
+       if (( job_count >= MAX_JOBS )); then
+           wait
+           job_count=0
+       fi
+   done
+   wait  # Wait for remaining jobs
+
+   # INCORRECT: Uncontrolled parallel execution
+   for file in "${files[@]}"; do
+       process_file "$file" &  # May overwhelm system
+   done
+   ```
+
+### Error Handling Patterns
+
+1. **Function Error Handling**:
+   ```bash
+   # CORRECT: Proper function with error handling
+   backup_database() {
+       local db_file="$1"
+       local backup_file="$2"
+
+       if [[ -z "$db_file" || -z "$backup_file" ]]; then
+           echo "Error: Missing required parameters"
+           return 1
+       fi
+
+       if [[ ! -f "$db_file" ]]; then
+           echo "Error: Database file not found: $db_file"
+           return 1
+       fi
+
+       if ! sqlite3 "$db_file" ".backup $backup_file"; then
+           echo "Error: Database backup failed"
+           return 1
+       fi
+
+       return 0
+   }
+   ```
+
+2. **Cleanup on Error**:
+   ```bash
+   # CORRECT: Cleanup trap for error handling
+   cleanup() {
+       if [[ -n "$TEMP_DIR" && -d "$TEMP_DIR" ]]; then
+           rm -rf "$TEMP_DIR"
+       fi
+
+       if [[ "$SERVICE_STOPPED" == "true" ]]; then
+           sudo systemctl start plexmediaserver
+       fi
+   }
+
+   trap cleanup EXIT ERR
+   ```
+
+### Validation Checklist for Code Generation
+
+Before suggesting any shell script code, verify:
+
+- [ ] All `if` statements have matching `fi`
+- [ ] All `for`/`while` loops have matching `done`
+- [ ] All `case` statements have matching `esac`
+- [ ] Functions are properly defined with `()` and `{}`
+- [ ] Variables are quoted in conditions and expansions
+- [ ] File operations check for existence and permissions
+- [ ] Service operations verify current state before changes
+- [ ] Database operations include integrity checks
+- [ ] Parallel operations are properly managed with job limits
+- [ ] Error handling includes cleanup and restoration
+- [ ] Exit codes are properly set and checked
+- [ ] Temporary files and directories are cleaned up
+
+### Testing Integration
+
+When modifying scripts:
+
+1. **Syntax Check**: Always run `bash -n script.sh` validation
+2. **Logic Testing**: Test with various input conditions
+3. **Error Scenarios**: Test failure modes and recovery
+4. **Integration Testing**: Verify interaction with system services
+5. **Permission Testing**: Test with different user privileges
+
+### Common Anti-Patterns to Avoid
+
+1. **Unmatched Control Structures**:
+   ```bash
+   # WRONG: Missing fi
+   if [[ condition ]]; then
+       do_something
+   # Missing fi here
+   ```
+
+2. **Unsafe Variable Expansion**:
+   ```bash
+   # WRONG: Unquoted variables
+   if [ $VAR = "value" ]; then  # Will break if VAR contains spaces
+
+   # CORRECT:
+   if [[ "$VAR" = "value" ]]; then
+   ```
+
+3. **Ignoring Command Failures**:
+   ```bash
+   # WRONG: Not checking critical command results
+   sudo systemctl stop plexmediaserver
+   # Continue without knowing if stop succeeded
+
+   # CORRECT:
+   if ! sudo systemctl stop plexmediaserver; then
+       echo "Error: Failed to stop Plex service"
+       exit 1
+   fi
+   ```
+
+4. **Race Conditions in Service Management**:
+   ```bash
+   # WRONG: Race condition
+   sudo systemctl stop plexmediaserver
+   sudo systemctl start plexmediaserver  # May start before stop completes
+
+   # CORRECT:
+   sudo systemctl stop plexmediaserver
+   sleep 2  # Allow time for clean shutdown
+   sudo systemctl start plexmediaserver
+   ```