# Script Header Template

**Purpose:** Standardize script metadata, usage, and error handling for all new and updated shell scripts.  
**Source:** [00-meta/ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](../00-meta/ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md) §4 (items 36–38); legacy: [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](../ALL_IMPROVEMENTS_AND_GAPS_INDEX.md).

---

## Template

```bash
#!/usr/bin/env bash
# One-line description of what the script does.
# Usage: ./path/to/script.sh [OPTIONS] [ARGS]
#   --dry-run    Print what would be done; do not change state.
#   --help       Show this usage and exit.
# Exit codes: 0 = success, 1 = usage/validation error, 2 = runtime failure.
# Recommendation: docs/10-best-practices/RECOMMENDATIONS_AND_SUGGESTIONS.md

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"   # adjust depth as needed

# Optional: logging helpers
log_info()  { echo "[INFO] $*" >&2; }
log_ok()    { echo "[OK] $*" >&2; }
log_warn()  { echo "[WARN] $*" >&2; }
log_err()   { echo "[ERROR] $*" >&2; }

# Optional: --dry-run and --help
DRY_RUN=false
for a in "$@"; do
  [[ "$a" == "--dry-run" ]] && DRY_RUN=true && break
  [[ "$a" == "--help" || "$a" == "-h" ]] && { sed -n '2,10p' "$0"; exit 0; }
done

# Your script logic below
```

---

## Rules

| Item | Rule |
|------|------|
| **Shebang** | Use `#!/usr/bin/env bash` (not `#!/bin/bash`). |
| **Error handling** | Use `set -euo pipefail` unless the script intentionally allows unset vars or ignores errors. |
| **Usage** | Document in a comment after the shebang: one-line description, `Usage:`, optional `--dry-run` / `--help`. |
| **Exit codes** | 0 = success, 1 = usage/validation, 2 = runtime failure; document in comment. |
| **Paths** | Prefer `SCRIPT_DIR` and `PROJECT_ROOT` (or equivalent) so the script works from any CWD. |

---

## Optional: progress indicator

For long-running scripts, add a simple progress message:

```bash
log_info "Step 1/5: Validating config..."
# ... do work ...
log_info "Step 2/5: Deploying..."
```

---

## Where to use

- New scripts under `scripts/` (including `scripts/verify/`, `scripts/maintenance/`, etc.).
- When touching existing scripts for fixes or features, add the header if missing.

**See also:** [IMPLEMENTATION_CHECKLIST.md](IMPLEMENTATION_CHECKLIST.md), [RECOMMENDATIONS_AND_SUGGESTIONS.md](RECOMMENDATIONS_AND_SUGGESTIONS.md).