shell/.github/copilot-instructions.md

# GitHub Copilot Instructions for Shell Repository

This document provides context and guidance for GitHub Copilot when working with this shell script and dotfiles repository.

## Repository Overview

This repository contains:

1. **Shell scripts** for system administration tasks
2. **Dotfiles** for system configuration 
3. **Setup scripts** for automated environment configuration
4. **Docker-based testing framework** for validating setup across environments

## Repository Structure

- **Root directory**: Contains various utility shell scripts
- **docs/**: Documentation for individual scripts and components
- **dotfiles/**: System configuration files that get symlinked to the user's home directory
- **powershell/**: PowerShell scripts for Windows environments
- **setup/**: Setup scripts and package lists for automated environment configuration
- **.github/**: GitHub-related configuration files

## Key Files Overview

### Shell Scripts

- **bootstrap.sh**: Entry point script for automated setup
- **test-setup.sh**: Testing script for validating environment setup
- **run-docker-tests.sh**: Runner for Docker-based testing
- **update.sh**: System update scripts
- **plex.sh**: Plex Media Server management

### Configuration Files

- **setup/packages.list**: List of packages to install during setup
- **dotfiles/my-aliases.zsh**: Custom ZSH aliases
- **dotfiles/tailscale-acl.json**: Tailscale ACL configuration

### Documentation

- **README.md**: Main repository documentation
- **docs/testing.md**: Detailed documentation for the testing framework
- **dotfiles/README.md**: Documentation for dotfiles setup and usage

## Style Guidelines

When suggesting code or modifications:

1. **Shell Scripts**:
   - Use `#!/bin/bash` for most scripts
   - Include proper error handling with `set -e` where appropriate
   - For test scripts, avoid `set -e` to allow testing all components
   - Add descriptive comments for script sections
   - Use colors for terminal output when appropriate (GREEN, RED, YELLOW, etc.)
   - Use capitalized variable names (e.g., `USER_HOME=/home/user`)

2. **Docker Files**:
   - Follow Docker best practices for layer optimization
   - Use specific tags for base images rather than 'latest'
   - Include proper LABEL directives for metadata

3. **Documentation**:
   - Use proper Markdown formatting
   - Include code examples using appropriate syntax highlighting
   - Document script parameters and usage

## Testing Framework

When modifying the testing framework:

1. Make sure to test across both Ubuntu and Debian environments
2. Ensure tests continue even when individual components fail
3. Track and summarize all errors at the end of tests
4. Maintain proper error reporting and logging

### Docker Testing Enhancements

The Docker-based testing framework includes these key features:

1. **Continuous Testing**: Tests continue running even when individual package installations fail
   - Achieved by removing `set -e` from test scripts 
   - Uses a counter to track errors rather than exiting immediately

2. **Package Testing**: 
   - Dynamically reads packages from `setup/packages.list`
   - Tests each package individually
   - Maintains an array of missing packages for final reporting

3. **Summary Reporting**:
   - Provides a comprehensive summary of all failed tests
   - Suggests commands to fix missing packages
   - Saves detailed logs to a timestamped file in /tmp

4. **Cross-Platform Testing**:
   - Tests both Ubuntu and Debian environments
   - Handles platform-specific package names (e.g., `bat` vs `batcat`)

## Key Concepts

- **Shell Environment Setup**: Focuses on ZSH with Oh My Zsh and plugins
- **Docker Testing**: Validates environment setup in isolated containers
- **Dotfiles Management**: Uses symbolic links to user's home directory
- **Package Installation**: Uses apt/nala on Debian-based systems

## Main Use Cases

1. **Setting up a new development environment**: Using bootstrap.sh
2. **Managing media services**: Using plex.sh and related scripts
3. **System maintenance**: Using update.sh and backup scripts
4. **Testing configuration changes**: Using the Docker testing framework

## Code Organization Principles

1. **Modularity**: Keep scripts focused on one task
2. **Documentation**: Document all scripts and configurations
3. **Testing**: Ensure all changes are testable
4. **Cross-platform**: Support both Ubuntu and Debian where possible

## Security Practices

When suggesting security-related code:

1. **Permissions**:
   - Avoid running scripts as root unless necessary
   - Use `sudo` for specific commands rather than entire scripts
   - Set appropriate file permissions (e.g., `chmod 600` for sensitive files)

2. **Secret Management**:
   - Never include hardcoded credentials in scripts
   - Use environment variables or external secret management
   - Add sensitive files to .gitignore

3. **Input Validation**:
   - Validate and sanitize all user inputs
   - Use quotes around variables to prevent word splitting and globbing
   - Implement proper error handling for invalid inputs

4. **Network Security**:
   - Verify URLs before downloading (`curl`/`wget`)
   - Use HTTPS instead of HTTP when possible
   - Validate checksums for downloaded packages

## Contribution Guidelines

For contributors and Copilot suggestions:

1. **Script Modifications**:
   - Test all changes using the Docker testing framework
   - Update documentation when adding new functionality
   - Maintain backward compatibility when possible

2. **New Scripts**:
   - Follow the established naming conventions
   - Include a header with description, usage, and author
   - Add appropriate documentation to the docs/ directory
   - Add any new dependencies to setup/packages.list

3. **Review Process**:
   - Run tests before submitting changes
   - Document what was changed and why
   - Consider both Ubuntu and Debian compatibility