shell-scriptinglisted

# Shell Scripting Guidelines Applies to: any `*.sh` file in this repo. Common locations: `scripts/`, `.githooks/`. ## General Principles - Clean, simple, concise. Easy to read. - Comments where helpful for understanding; avoid commentary on what well-named identifiers already say. - Concise echo for status; avoid noisy logging. - Use `shellcheck` when available. - Default assumption: scripts are for automation/testing, not production systems, unless stated. - Safe expansions: double-quote variable references (`"$var"`), use `${var}` for clarity, never `eval`. - Prefer modern Bash (`[[ ]]`, `local`, arrays) when portability allows; fall back to POSIX only when needed. - Use dedicated parsers (`jq`, `yq`) for structured data instead of ad-hoc grep/awk. ## Error Handling & Safety - Always: `set -euo pipefail`. - Validate required parameters before doing anything. - Provide error messages with context. - Use `trap` to clean up temp files / unexpected exits. - Declare constants with `readonly`. - Use `mktemp` for temp files/dirs; remove in cleanup. ## Script Structure - Shebang: `#!/bin/bash` unless told otherwise. - Header comment explaining purpose. - Default values at top. - Functions for reusable blocks. - Keep `main` flow readable. ## JSON / YAML - Prefer `jq` for JSON, `yq` for YAML. - Quote filters (`jq '.foo'`); use `--raw-output` for plain strings. - Validate fields exist; check `jq` exit status or `// empty`. - Combine with `set -euo pipefail` so parse errors ar