feat: Enhance Plex management with library scanner integration and bash completion support

plex/plex-management.md

@@ -11,15 +11,16 @@ This document provides comprehensive documentation for the modern `plex.sh` scri
 The enhanced `plex.sh` script is a modern Plex service management tool that performs the following advanced tasks:
 
 1. **Smart Service Management**: Intelligent start/stop/restart operations with dependency checking
-2. **Enhanced Status Display**: Detailed service status with health indicators and port monitoring
+2. **Library Scanner Integration**: Integrated access to comprehensive library scanning operations
-3. **Safety Validation**: Pre-operation checks and post-operation verification
+3. **Enhanced Status Display**: Detailed service status with health indicators and port monitoring
-4. **Progress Indicators**: Visual feedback for all operations with timing information
+4. **Safety Validation**: Pre-operation checks and post-operation verification
-5. **Comprehensive Logging**: Detailed logging with color-coded output and timestamps
+5. **Progress Indicators**: Visual feedback for all operations with timing information
-6. **Configuration Validation**: Checks for common configuration issues
+6. **Comprehensive Logging**: Detailed logging with color-coded output and timestamps
-7. **Network Monitoring**: Port availability and network configuration validation
+7. **Configuration Validation**: Checks for common configuration issues
-8. **Process Management**: Advanced process monitoring and cleanup capabilities
+8. **Network Monitoring**: Port availability and network configuration validation
-9. **Recovery Operations**: Automatic recovery from common service issues
+9. **Process Management**: Advanced process monitoring and cleanup capabilities
-10. **Performance Monitoring**: Service health and resource usage tracking
+10. **Recovery Operations**: Automatic recovery from common service issues
+11. **Performance Monitoring**: Service health and resource usage tracking
 
 ## Related Scripts in the Plex Ecosystem
 
@@ -28,6 +29,7 @@ This script is part of a comprehensive Plex management suite:
 ### Core Management Scripts
 
 - **`plex.sh`** (this script) - Service management and control
+- **`scan-plex-libraries.sh`** ⭐ **NEW** - Comprehensive library scanning and metadata management
 - **`backup-plex.sh`** - Database backup with integrity checking and auto-repair
 - **`restore-plex.sh`** - Safe database restoration with validation
 
@@ -49,6 +51,266 @@ This script is part of a comprehensive Plex management suite:
 
 - **`plex-recent-additions.sh`** - Recent media additions reporting and statistics
 
+## Library Scanner Integration ⭐ **NEW**
+
+### Overview
+
+The `plex.sh` script now includes integrated access to comprehensive library scanning functionality through the new `scan-plex-libraries.sh` script. This integration provides seamless access to all Plex Media Scanner operations directly from the main management interface.
+
+### Library Scanner Features
+
+The integrated library scanner provides:
+
+- **Library Management**: List all Plex library sections with IDs and names
+- **Media Scanning**: Scan for new media files (individual libraries or all at once)
+- **Metadata Refresh**: Refresh library metadata with force options for complete rebuilds
+- **Deep Analysis**: Comprehensive media analysis for codec information and metadata
+- **Thumbnail Generation**: Generate preview thumbnails and fanart images
+- **Library Structure**: Display hierarchical library structure and organization
+- **Interactive Mode**: User-friendly menu system for easy library management
+- **Batch Operations**: Perform operations on all libraries or specific selections
+- **Error Handling**: Comprehensive validation and error reporting
+- **Service Integration**: Automatic Plex service status validation before operations
+
+### Scanner Integration Commands
+
+The library scanner is accessible through the main `plex.sh` script:
+
+```bash
+# Launch interactive scanner interface
+./plex.sh scan
+
+# Pass commands directly to scanner
+./plex.sh scan list                    # List all libraries
+./plex.sh scan scan                    # Scan all libraries for new media
+./plex.sh scan scan 29                 # Scan specific library (ID 29)
+./plex.sh scan refresh 29 true         # Force refresh specific library
+./plex.sh scan analyze 29 true         # Deep analyze specific library
+./plex.sh scan generate 29             # Generate thumbnails for library
+./plex.sh scan tree 29                 # Show library structure
+```
+
+### Direct Scanner Access
+
+The scanner can also be accessed directly:
+
+```bash
+# Direct script execution
+./scan-plex-libraries.sh interactive   # Interactive mode
+./scan-plex-libraries.sh list          # List libraries
+./scan-plex-libraries.sh scan          # Scan all libraries
+./scan-plex-libraries.sh -v scan 29    # Verbose scan of specific library
+
+# Via aliases (if shell configuration is loaded)
+plex-scan                               # Launch via plex.sh integration
+plex-scanner list                       # Direct scanner access
+plex-scanner scan 29                    # Direct scan of specific library
+```
+
+### Scanner Command Reference
+
+#### Core Scanner Commands
+
+- **`list`** - Display all available library sections with IDs and names
+- **`scan [section_id]`** - Scan for new media files (all libraries if no ID specified)
+- **`refresh [section_id] [force]`** - Refresh metadata (set force=true for complete refresh)
+- **`analyze [section_id] [deep]`** - Analyze media files (set deep=true for comprehensive analysis)
+- **`generate [section_id]`** - Generate thumbnails and fanart images
+- **`tree <section_id>`** - Display hierarchical library structure (requires section ID)
+- **`interactive`** - Launch interactive menu system
+
+#### Scanner Options
+
+- **`-v, --verbose`** - Enable verbose output for detailed operation information
+- **`-h, --help`** - Display comprehensive help and usage information
+
+#### Example Scanner Operations
+
+```bash
+# List all available libraries with their section IDs
+$ ./plex.sh scan list
+Available Library Sections:
+=========================
+  29: Movies
+  30: TV Shows
+  31: Music
+
+# Scan Movies library for new content
+$ ./plex.sh scan scan 29
+[>] Scanning library section 29 for new media...
+[✓] Library section 29 scan completed
+
+# Force refresh all libraries (complete metadata rebuild)
+$ ./plex.sh scan refresh "" true
+[~] Refreshing metadata for all libraries...
+[i] Refreshing section 29...
+[✓] Section 29 refreshed successfully
+[i] Refreshing section 30...
+[✓] Section 30 refreshed successfully
+[✓] All libraries refreshed successfully
+
+# Deep analyze TV Shows library
+$ ./plex.sh scan analyze 30 true
+[?] Analyzing media in library section 30...
+[✓] Library section 30 analysis completed
+
+# Generate thumbnails for Movies library
+$ ./plex.sh scan generate 29
+[*] Generating thumbnails for library section 29...
+[✓] Thumbnails generated for library section 29
+```
+
+### Interactive Scanner Mode
+
+The interactive mode provides a user-friendly menu system:
+
+```bash
+$ ./plex.sh scan
+🎬 Plex Library Scanner - Interactive Mode
+Select an operation to perform:
+
+Available Operations:
+1) List all libraries
+2) Scan libraries for new media
+3) Refresh library metadata
+4) Analyze library media
+5) Generate thumbnails
+6) Show library tree
+q) Quit
+
+Choose an option [1-6,q]: 2
+
+Scan Options:
+1) Scan all libraries
+2) Scan specific library
+Choose [1-2]: 1
+
+[>] Scanning all libraries for new media...
+[✓] All libraries scanned successfully
+```
+
+### Scanner Error Handling and Validation
+
+The library scanner includes comprehensive error handling:
+
+- **Service Validation**: Automatically checks if Plex Media Server is running
+- **Scanner Detection**: Locates Plex Media Scanner binary across different installation paths
+- **Section ID Validation**: Verifies library section IDs exist before operations
+- **Operation Verification**: Confirms successful completion of all scanner operations
+- **Graceful Failure**: Provides helpful error messages and recovery suggestions
+
+### Scanner Logging and Monitoring
+
+All scanner operations are logged:
+
+- **Operation Logs**: Detailed logs written to `/home/acedanger/shell/logs/plex-scanner.log`
+- **Timestamp Tracking**: All operations include precise timestamps
+- **Verbose Mode**: Enhanced debugging information available with `-v` flag
+- **Status Reporting**: Real-time status updates during long-running operations
+
+### Scanner Performance Considerations
+
+For optimal performance:
+
+- **Large Libraries**: Scanner operations may take considerable time for large media collections
+- **Deep Analysis**: Deep analysis is resource-intensive, use selectively
+- **Concurrent Operations**: Avoid running multiple scanner operations simultaneously
+- **System Resources**: Scanner operations can be CPU and I/O intensive during execution
+
+### Scanner Best Practices
+
+Recommended usage patterns:
+
+1. **Regular Scanning**: Set up regular scans for libraries with frequent media additions
+2. **Selective Operations**: Use specific section IDs for targeted operations when possible
+3. **Monitor Progress**: Use verbose mode to understand operation progress and impact
+4. **Service Health**: Ensure Plex service is healthy before performing scanner operations
+5. **Batch Operations**: For multiple libraries, consider using "scan all" for efficiency
+
+### Scanner Troubleshooting
+
+Common issues and solutions:
+
+1. **"Plex Media Server is not running"**
+   - Start Plex: `./plex.sh start`
+   - Verify status: `./plex.sh status`
+
+2. **"Plex Media Scanner binary not found"**
+   - Verify Plex installation is complete
+   - Check if binary exists in standard locations
+   - Ensure proper system PATH configuration
+
+3. **"Section ID not found"**
+   - Use `./plex.sh scan list` to see valid section IDs
+   - Verify the library hasn't been deleted or renamed
+
+4. **Scanner operations timeout or fail**
+   - Check system resources (CPU, memory, disk I/O)
+   - Verify media files are accessible and not corrupted
+   - Review scanner logs for detailed error information
+
+### Scanner Bash Completion ⭐ **NEW**
+
+The library scanner includes comprehensive bash completion support:
+
+#### Tab Completion Features
+
+- **Command Completion**: Tab completion for all scanner commands and options
+- **Context-Aware**: Different completions based on command context
+- **Boolean Flags**: Smart completion for `true`/`false` values where applicable
+- **Alias Support**: Completion works with all plex-related aliases
+
+#### Example Tab Completion Usage
+
+```bash
+# Main plex.sh command completion
+$ ./plex.sh <TAB>
+start  stop  restart  status  scan  repair  nuclear  help
+
+# Scanner sub-command completion
+$ ./plex.sh scan <TAB>
+list  scan  refresh  analyze  generate  tree  interactive  -v  --verbose  -h  --help
+
+# Boolean flag completion for refresh and analyze
+$ ./plex.sh scan refresh 29 <TAB>
+true  false
+
+$ ./plex.sh scan analyze 29 <TAB>
+true  false
+
+# Direct scanner completion
+$ ./scan-plex-libraries.sh <TAB>
+list  scan  refresh  analyze  generate  tree  interactive
+
+# Alias completion
+$ plex-scan <TAB>
+list  scan  refresh  analyze  generate  tree  interactive
+
+$ plex-scanner <TAB>
+list  scan  refresh  analyze  generate  tree  interactive
+```
+
+#### Completion Installation
+
+Bash completion is automatically installed by the setup scripts:
+
+- **Automatic Setup**: Installed by `bootstrap.sh` and `setup.sh`
+- **Shell Integration**: Sourced in `.zshrc` for immediate availability
+- **Alias Support**: Works with all plex-related aliases (`plex`, `plex-scan`, `plex-scanner`, etc.)
+
+#### Manual Completion Setup
+
+If needed, completion can be enabled manually:
+
+```bash
+# Enable bash completion in zsh
+autoload -U +X bashcompinit && bashcompinit
+autoload -U compinit && compinit -u
+
+# Source the completion script
+source /home/acedanger/shell/completions/plex-scripts-completion.bash
+```
+
 ## Enhanced Features
 
 ### Smart Terminal Detection and Color Output
@@ -139,6 +401,9 @@ Shows:
 
 # Display comprehensive status
 ./plex.sh status
+
+# Launch library scanner
+./plex.sh scan
 ```
 
 ### Available Commands
@@ -151,9 +416,20 @@ The script supports the following commands:
 ./plex.sh stop       # Stop Plex Media Server
 ./plex.sh restart    # Restart Plex Media Server (also accepts 'reload')
 ./plex.sh status     # Show detailed service status (also accepts 'info')
+./plex.sh scan       # Launch library scanner (NEW)
 ./plex.sh logs       # Display recent Plex Media Server logs
 ./plex.sh help       # Show help message (also accepts '--help' or '-h')
 
+# Library scanner operations (NEW)
+./plex.sh scan                          # Interactive scanner mode
+./plex.sh scan list                     # List all library sections
+./plex.sh scan scan                     # Scan all libraries for new media
+./plex.sh scan scan 29                  # Scan specific library (ID 29)
+./plex.sh scan refresh 29 true          # Force refresh specific library
+./plex.sh scan analyze 29 true          # Deep analyze specific library
+./plex.sh scan generate 29              # Generate thumbnails for library
+./plex.sh scan tree 29                  # Show library structure
+
 # Logs command with options
 ./plex.sh logs       # Display last 20 lines of Plex logs
 ./plex.sh logs -n 50 # Display last 50 lines of Plex logs
@@ -185,8 +461,17 @@ The `plex.sh` script is designed to work seamlessly with other Plex management s
 # Used by recovery scripts for service control
 ./recover-plex-database.sh  # Uses plex.sh for service management
 
+# Library scanner integration with service management
+./plex.sh scan scan           # Scan all libraries
+./plex.sh scan refresh "" true  # Force refresh all libraries after service restart
+
 # Manual integration with porcelain output
 ./plex.sh --porcelain start  # For use in scripts/automation
+
+# Scanner integration in maintenance scripts
+./plex.sh scan scan           # Regular media scanning
+./plex.sh scan analyze        # Weekly deep analysis
+./plex.sh scan generate       # Thumbnail regeneration
 ```
 
 ### Security and Safety Features
@@ -434,6 +719,11 @@ For scheduled operations:
 
 # Daily health check
 0 6 * * * /home/acedanger/shell/plex/plex.sh status --validate
+
+# Automated library scanning (NEW)
+0 4 * * * /home/acedanger/shell/plex/plex.sh scan scan          # Daily scan for new media
+0 2 * * 0 /home/acedanger/shell/plex/plex.sh scan refresh "" true  # Weekly metadata refresh
+0 1 * * 1 /home/acedanger/shell/plex/plex.sh scan analyze       # Weekly media analysis
 ```
 
 ## Exit Codes and Return Values