shell/completions/README.md

# Bash Completion for Shell Scripts

This directory contains bash completion scripts for various shell utilities in this repository.

## Overview

The completion system provides intelligent tab completion for command-line flags and options for all backup scripts in this repository. It's automatically installed and configured by the setup scripts.

## Supported Scripts

### Plex Management Scripts ⭐ **NEW**

#### plex.sh
- `start` - Start Plex Media Server
- `stop` - Stop Plex Media Server
- `restart` - Restart Plex Media Server
- `status` - Show detailed service status
- `scan` - Launch library scanner (with sub-commands)
- `repair` - Repair database corruption issues
- `nuclear` - Nuclear database recovery (last resort)
- `help` - Show help message

#### scan-plex-libraries.sh
- `list` - List all library sections
- `scan` - Scan for new media (with optional section ID)
- `refresh` - Refresh metadata (with optional section ID and force flag)
- `analyze` - Analyze media (with optional section ID and deep flag)
- `generate` - Generate thumbnails (with optional section ID)
- `tree` - Show library tree structure (requires section ID)
- `interactive` - Interactive mode
- `-v`, `--verbose` - Enable verbose output
- `-h`, `--help` - Show help message

#### Plex Aliases
- `plex`, `px` - Main plex.sh script with command completion
- `plex-start`, `plex-stop`, `plex-restart`, `plex-status` - Direct service commands
- `plex-scan` - Library scanner via plex.sh (supports scanner sub-commands)
- `plex-scanner` - Direct access to scan-plex-libraries.sh

### Backup Scripts

#### backup-immich.sh

- `--help`, `-h` - Show help message
- `--dry-run` - Preview backup without executing
- `--no-upload` - Skip B2 upload (local backup only)
- `--verbose` - Enable verbose logging

### backup-plex.sh

- `--help`, `-h` - Show help message
- `--auto-repair` - Automatically attempt to repair corrupted databases
- `--check-integrity` - Only check database integrity, don't backup
- `--non-interactive` - Run in non-interactive mode (for automation)
- `--no-parallel` - Disable parallel verification (slower but safer)
- `--no-performance` - Disable performance monitoring
- `--webhook=URL` - Send notifications to webhook URL
- `--email=ADDRESS` - Send notifications to email address

### backup-media.sh

- `--help`, `-h` - Show help message
- `--dry-run` - Show what would be backed up without actually doing it
- `--no-verify` - Skip backup verification
- `--sequential` - Run backups sequentially instead of in parallel
- `--interactive` - Ask for confirmation before each backup
- `--webhook URL` - Custom webhook URL for notifications

### Generic backup scripts (backup-docker.sh, etc.)

- `--help`, `-h` - Show help message
- `--dry-run` - Preview mode
- `--verbose` - Verbose output
- `--no-upload` - Skip upload operations
- `--webhook` - Webhook URL for notifications

## Installation

The completion system is **automatically installed** when you run the setup scripts:

1. **bootstrap.sh** - Makes completion scripts executable
2. **setup.sh** - Copies completion scripts to the user's local completion directory (`~/.local/share/bash-completion/completions/`)
3. **.zshrc** - Sources the completion scripts in zsh with bash compatibility mode

### Automatic Setup Process

When you run `./setup/bootstrap.sh` or `./setup/setup.sh`, the system will:

- Install bash completion support in zsh
- Copy completion scripts to the standard completion directory
- Ensure completion scripts are executable
- Source the completion in your shell configuration

### Manual Installation

If you need to install manually or re-install:

```bash
# Enable bash completion compatibility in zsh
autoload -U +X bashcompinit && bashcompinit
autoload -U compinit && compinit -u

# Load custom backup scripts completion
if [ -f "$HOME/shell/completions/backup-scripts-completion.bash" ]; then
    source "$HOME/shell/completions/backup-scripts-completion.bash"
fi

# Load Plex scripts completion
if [ -f "$HOME/shell/completions/plex-scripts-completion.bash" ]; then
    source "$HOME/shell/completions/plex-scripts-completion.bash"
fi

# Load environment backup completion
if [ -f "$HOME/shell/completions/env-backup-completion.bash" ]; then
    source "$HOME/shell/completions/env-backup-completion.bash"
fi
```

## Usage Examples

### Basic Tab Completion

```bash
# Type the script name and start typing an option
$ backup-immich.sh --<TAB>
--help  --dry-run  --no-upload  --verbose

# Continue typing to filter
$ backup-immich.sh --d<TAB>
$ backup-immich.sh --dry-run
```

### Plex Script Completion ⭐ **NEW**

```bash
# Main plex.sh command completion
$ plex.sh <TAB>
start  stop  restart  status  scan  repair  nuclear  help

# Scanner sub-command completion when using scan
$ plex.sh scan <TAB>
list  scan  refresh  analyze  generate  tree  interactive  -v  --verbose  -h  --help

# Direct scanner script completion
$ scan-plex-libraries.sh <TAB>
list  scan  refresh  analyze  generate  tree  interactive

# Scanner options completion
$ scan-plex-libraries.sh -<TAB>
-v  --verbose  -h  --help

# Boolean flag completion for refresh and analyze
$ scan-plex-libraries.sh refresh 29 <TAB>
true  false

$ scan-plex-libraries.sh analyze 29 <TAB>
true  false

# Alias completion works too
$ plex-scan <TAB>
list  scan  refresh  analyze  generate  tree  interactive

$ plex-scanner <TAB>
list  scan  refresh  analyze  generate  tree  interactive
```

### Webhook URL Completion

```bash
# For scripts that support webhook URLs
$ backup-plex.sh --webhook <TAB>
https://notify.peterwood.rocks/lab

# Or for inline webhook options
$ backup-plex.sh --webhook=<TAB>
https://notify.peterwood.rocks/lab
```

### Path-based Completion

Completion works with various invocation methods:

```bash
# Direct script name (if in PATH)
backup-immich.sh --<TAB>

# Relative path
./backup-immich.sh --<TAB>

# Absolute path
/home/acedanger/shell/immich/backup-immich.sh --<TAB>
```

## Features

### Intelligent Argument Completion

- **Flag completion**: All available flags for each script
- **Value completion**: Suggests common values for specific options
- **Context-aware**: Different completions based on script type

### Cross-Script Support

- **Specific completions**: Tailored for each backup script
- **Generic fallback**: Common options for any backup script
- **Pattern matching**: Automatic completion for `*backup*.sh` scripts

### Advanced Features

- **Webhook URL suggestions**: Common webhook endpoints
- **Email address completion**: For notification options
- **Multi-word option support**: Handles `--option value` and `--option=value`

## Troubleshooting

### Completion Not Working

1. Verify the completion script is sourced:

   ```bash
   complete -p | grep backup
   ```

2. Reload your shell configuration:

   ```bash
   source ~/.zshrc
   ```

3. Check if bashcompinit is enabled:

   ```bash
   # Should be in your .zshrc
   autoload -U +X bashcompinit && bashcompinit
   ```

### Adding New Scripts

To add completion for a new backup script:

1. Add the script patterns to the completion file
2. Define specific options for the script
3. Register the completion function

Example:

```bash
# Add to backup-scripts-completion.bash
complete -F _backup_generic_completion your-new-backup-script.sh
```

## Development

### Testing Completions

Use the test script to verify completions work:

```bash
./test-completion.sh
```

### Adding New Options

1. Update the relevant completion function in `backup-scripts-completion.bash`
2. Add the new option to the `opts` variable
3. Handle any special argument completion if needed
4. Test the completion with `compgen -W "options" -- "prefix"`

### Custom Completion Functions

Each script can have its own completion function following this pattern:

```bash
_script_name_completion() {
    local cur prev opts
    COMPREPLY=()
    cur="${COMP_WORDS[COMP_CWORD]}"
    prev="${COMP_WORDS[COMP_CWORD-1]}"

    opts="--option1 --option2 --option3"

    # Handle special cases
    case "${prev}" in
        --special-option)
            COMPREPLY=( $(compgen -W "value1 value2" -- ${cur}) )
            return 0
            ;;
    esac

    # Standard flag completion
    if [[ ${cur} == -* ]]; then
        COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
        return 0
    fi
}
```