caddis-plugin: Instructions file for GitHub Copilot

Shell Scripting Guidelines

General Principles

• Generate code that is clean, simple, and concise
• Ensure scripts are easily readable and understandable
• Add comments where helpful, but don't over-comment obvious lines
• Use shellcheck for static analysis when available
• Prefer safe expansions: double-quote variable references ("$var"), use ${var} for clarity, avoid eval
• Use modern Bash features ([[ ]], local, arrays) when portability allows; fall back to POSIX when needed
• Choose reliable parsers for structured data (jq for JSON, yq for YAML)

---

Error Handling & Safety

Always Enable Strict Mode

set -euo pipefail

• set -e — Exit on any command failure
• set -u — Treat unset variables as errors
• set -o pipefail — Pipe fails if any command in the pipeline fails

Validate Inputs

# Validate required parameters before use
if [[ -z "${INPUT_FILE:-}" ]]; then
    echo "Error: INPUT_FILE is required." >&2
    exit 1
fi

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

Cleanup with Trap

Use trap to clean up temporary resources on exit, regardless of how the script terminates.

cleanup() {
    if [[ -n "${TEMP_DIR:-}" && -d "$TEMP_DIR" ]]; then
        rm -rf "$TEMP_DIR"
    fi
}
trap cleanup EXIT

Use mktemp for Temporary Files

Never hardcode temp file paths. Use mktemp and clean up via trap.

TEMP_DIR="$(mktemp -d)"
TEMP_FILE="$(mktemp)"

# These will be cleaned up by the EXIT trap

Immutable Values

Declare constants with readonly to prevent accidental modification.

readonly CONFIG_DIR="/etc/myapp"
readonly MAX_RETRIES=3
readonly SCRIPT_NAME="$(basename "$0")"

---

Script Structure

Every script should follow a consistent structure:

1. Shebang line
2. Header comment with purpose
3. Strict mode (set -euo pipefail)
4. Cleanup trap
5. Constants and default values
6. Function definitions
7. Argument parsing
8. Main execution