skill: bash-scripting

should_trigger:
  - prompt: "Write an install script that downloads a tarball, verifies its checksum, untars it, and cleans up the temp dir even if it fails partway."
    why: "Core bundle of the skill: mktemp + EXIT trap cleanup + strict-mode header + quoted expansions. The 'cleanup even if it fails' clause is the trap requirement."
  - prompt: "My bash loop processes files fine until someone has a filename with a space, then it splits into two. What's wrong?"
    why: "The quoting/array/-print0 core. Word-splitting an unquoted expansion (SC2086) or parsing ls; the skill's highest-value section."
  - prompt: "This deploy script works on my laptop but in CI set -e doesn't catch the error and it keeps going. Why?"
    why: "Non-obvious — looks like a CI problem but is the errexit leak (assignment-with-substitution / condition context / functions). The skill owns the bash semantics, not the CI config."
  - prompt: "Make this script run on both macOS and Linux — it uses declare -A and ${var,,} and dies on the Mac."
    why: "Portability / macOS bash 3.2: associative arrays and case-folding don't exist on 3.2.57. Routes to references/portability.md workarounds."
  - prompt: "Fix all these ShellCheck SC2086 warnings correctly, not just by adding disable comments everywhere."
    why: "Non-obvious: the ask is to fix (quote the expansions), not silence. Tests that the skill teaches the correct directive discipline."
  - prompt: "Tinc un script que peta en CI però funciona al meu portàtil — el pots fer robust i portable?"
    why: "Catalan trigger. 'Peta en CI / funciona al portàtil' is the works-on-my-machine portability + strict-mode symptom the description names."
  - prompt: "My cleanup trap seems to fire twice and rm complains about a missing directory."
    why: "The double-fire trap + idempotent cleanup point. Specific symptom from the traps section."

should_not_trigger:
  - prompt: "My GitHub Actions matrix build isn't caching node_modules between jobs. How do I configure the cache key?"
    route_to: "github-actions"
    why: "Workflow structure — runners, matrix, caching, secrets. The YAML and the workflow graph, not the shell inside a run: block. Explicit description boundary."
  - prompt: "Optimize my multi-stage Dockerfile so the RUN layers cache better and the final image is smaller."
    route_to: "docker"
    why: "Dockerfile semantics and layer hygiene, not the embedded script. Routes to docker."
  - prompt: "Design a retry-with-exponential-backoff policy and a structured error taxonomy for my microservice."
    route_to: "error-handling"
    why: "Cross-language defensive-design question. This skill is only the bash-specific expression (set -e pitfalls, traps, $?); the general taxonomy is error-handling."
  - prompt: "This bash data-processing script has gotten gnarly with nested awk and arrays — rewrite it in Python."
    route_to: "python"
    why: "A deliberate language-switch decision. Once the answer is 'do it in another language', it routes to that language's skill."
  - prompt: "Set up the Makefile and task orchestration so contributors can run lint/test/build with one command."
    route_to: "project-ops"
    why: "Orchestration-layer design, not a single script body. project-ops owns the task-runner structure; bash-scripting owns the script inside a target."

capability:
  - scenario: "Harden this fragile deploy script and explain each change. It is: #!/bin/sh on line 1, then `DIR=$1; cd $DIR; for f in $(ls *.tar.gz); do tar xzf $f; done; rm -rf $DIR/build/*; declare -A envs` — it parses ls, has unquoted vars, cds without checking, no cleanup, uses a bash-5-only feature under a POSIX shebang, and there's no strict mode."
    must_include:
      - "Resolves the shebang/feature mismatch: declare -A is a bashism (and unavailable on macOS bash 3.2), so either switch the shebang to #!/usr/bin/env bash or drop the associative array — does not leave #!/bin/sh with bashisms inside."
      - "Adds a strict-mode header appropriate to the chosen shell (set -euo pipefail + IFS for bash; explains pipefail/arrays are unavailable if POSIX sh is chosen)."
      - "Quotes every expansion: \"$DIR\", \"$f\", and guards the destructive path with ${DIR:?} so an empty DIR can't become rm -rf /."
      - "Replaces `for f in $(ls *.tar.gz)` with a glob (`for f in ./*.tar.gz; do [ -e \"$f\" ] || continue`) or find -print0, killing the ls-parse and space/newline bug."
      - "Changes `cd $DIR` to `cd \"$DIR\" || exit 1` so a failed cd does not run the rest in the wrong directory (SC2164)."
      - "Adds trap-based cleanup with mktemp for any temp work (tmp=$(mktemp -d); trap 'rm -rf \"$tmp\"' EXIT), idempotent."
      - "States the result must pass `shellcheck` clean (and `shellcheck -s sh` if the POSIX path is chosen)."

# Evals — bash-scripting

These cases sanity-check the skill's routing and capability. There is no harness here; eyeball it. For each `should_trigger` prompt, read the `description` in `../SKILL.md` and confirm the symptoms (works-locally-fails-in-CI, filenames-with-spaces, leaky `set -e`, macOS bash 3.2, SC2086, the Catalan "peta en CI") plausibly fire the skill; for each `should_not_trigger` prompt, confirm the named `route_to` sibling (`github-actions`, `docker`, `error-handling`, `python`, `project-ops`) is the better owner and that the prompt is *about* that sibling's territory, not the shell body. The `capability` case is graded by hardening the given fragile deploy script and checking the result against its `must_include` rubric — the decisive test is that the produced script passes `shellcheck` clean (and `shellcheck -s sh` if the POSIX path is chosen), which `../scripts/verify.sh` runs for you against the skill's own snippets.

# Portability: bash vs POSIX sh, and the macOS bash 3.2 reality

Read this when a script must run somewhere you don't control: an unknown CI
image, a colleague's Mac, an Alpine container, a busybox device. The question
is always the same — **what is the lowest shell this will ever hit, and what
does that shell forbid?**

## Feature matrix

| Feature | bash 4+ | bash 3.2 (macOS `/bin/bash`) | POSIX `sh` (dash/busybox) |
|---|---|---|---|
| `set -o pipefail` | yes | yes | **no** (bashism) |
| Indexed arrays `arr=(…)` / `"${arr[@]}"` | yes | yes | **no** |
| Associative arrays `declare -A` | yes | **no** (3.2 lacks them) | **no** |
| `[[ … ]]`, `=~`, `&&` inside test | yes | yes | **no** (use `[ … ]`) |
| `local` in functions | yes | yes | **no** (not POSIX; dash/ksh have it as an extension) |
| `${var,,}` / `${var^^}` case fold | yes | **no** | **no** |
| `mapfile` / `readarray` | yes | **no** | **no** |
| Process substitution `<(…)` | yes | yes | **no** |
| `${ cmd; }` / `${\| cmd; }`, `GLOBSORT`, `read -E` | bash **5.3+** only | **no** | **no** |
| `[ a == b ]` | tolerated | tolerated | **no** (use `=`) |
| `echo -e` / `echo -n` | unreliable across shells — use `printf` everywhere |

Rule of thumb: if the floor is "any Unix," target POSIX `sh` and give up arrays,
`[[ ]]`, `pipefail`, and `local`. If you control the box and bash is present,
target bash but assume **3.2** unless you've verified otherwise — that rules out
associative arrays, `${var,,}`, and `mapfile`.

## macOS bash 3.2 workarounds

Apple froze `/bin/bash` at **3.2.57** (pre-GPLv3); zsh is the default login
shell since Catalina, but scripts still hit `/bin/bash`. Newer bash from
Homebrew lives at `/opt/homebrew/bin/bash` and is NOT what a `#!/bin/bash`
shebang gets. Portable substitutes:

```bash
# No associative array (declare -A). Use a function + case, or parallel arrays.
lookup() {
  case "$1" in
    dev)  echo "https://dev.example.com" ;;
    prod) echo "https://example.com" ;;
    *)    return 1 ;;
  esac
}

# No ${var,,} lowercasing. Use tr.
lower=$(printf '%s' "$var" | tr '[:upper:]' '[:lower:]')

# No mapfile. Read lines into an array with a loop (or use find -print0).
lines=()
while IFS= read -r line; do
  lines+=("$line")
done < file.txt
```

## dash / busybox gotchas

These bite POSIX-`sh` scripts that were only ever tested under bash:

- `echo -e '\n'` prints the literal `-e` under dash. Use `printf '\n'`.
- `==` inside `[ ]` is a bash extension; dash errors. Use `=`.
- `source file` is a bashism; POSIX is `. file` (dot space).
- `function name {` is a bashism; POSIX is `name() {`.
- `local` works in dash and busybox ash as an extension, but is not in the
  POSIX spec — don't rely on it if "any POSIX sh" is the contract.
- `${arr[@]}` / `(…)` arrays: dash has none. busybox ash has none.

## bash 5.3 features — guard or avoid

Bash **5.3** (released 2025-07) added in-shell command substitution `${ cmd; }`
and `${| cmd; }` (no fork; result in `REPLY`), `GLOBSORT`, `compgen` into a
variable, `read -E`, and C23 conformance. None of these run on bash 3.2 or
POSIX `sh`. If you must use one, gate it on the version and provide a fallback:

```bash
if [ "${BASH_VERSINFO[0]:-0}" -ge 5 ] && [ "${BASH_VERSINFO[1]:-0}" -ge 3 ]; then
  : "use the 5.3 feature"
else
  : "portable fallback"
fi
```

Otherwise, simply don't use them in anything that ships.

## How to test against more than your own shell

```bash
shellcheck script.sh             # default: bash dialect
shellcheck -s sh script.sh       # static check against POSIX sh
dash ./script.sh                 # actually run under dash (apt install dash)
bash --posix ./script.sh         # bash with POSIX-mode restrictions on
docker run --rm -v "$PWD":/s -w /s alpine sh script.sh   # busybox ash
```

Running under `dash` is the cheapest way to surface accidental bashisms that
ShellCheck's `-s sh` mode misses. A script that passes `shellcheck -s sh` AND
runs clean under `dash` is genuinely portable.

#!/usr/bin/env bash
set -euo pipefail

# ============================================================================
# NAME
#   verify.sh — bash-scripting self-lint gate
#
# USAGE
#   ./verify.sh [TARGET_DIR]
#   With no argument it lints the bash-scripting skill itself (the SKILL.md and
#   references/*.md fenced ```bash snippets, plus any *.sh under the skill).
#   Pass a TARGET_DIR to instead lint every *.sh under a project you are
#   hardening with this skill.
#
# WHAT IT DOES
#   1. Self-check  — extracts every ```bash fenced block from SKILL.md and
#                    references/*.md, wraps each in a strict-mode header, and
#                    runs shellcheck on it. This proves the skill never teaches
#                    code that fails its own linter. Blocks explicitly marked
#                    "# Bad" are illustrative wrong-on-purpose examples and are
#                    skipped (only the "# Good" half of a Bad/Good pair lints).
#   2. Script lint — runs shellcheck on every *.sh found under the target.
#
# GUARANTEES
#   - Read-only: never writes to or fixes the target; only reads + temp files.
#   - Graceful skip: if shellcheck is absent it prints a skip notice and EXITS 0
#     (never a false failure in an environment that lacks the linter).
#   - Clean exit on an empty/clean target: no scripts and no findings => exit 0.
#   - Portable to stock macOS bash 3.2 (no mapfile, no associative arrays).
#
# EXIT CODES
#   0  shellcheck absent (skipped), OR everything is clean.
#   1  at least one real shellcheck finding — fix it before shipping.
# ============================================================================

RED=$'\033[31m'; YEL=$'\033[33m'; GRN=$'\033[32m'; RST=$'\033[0m'
if [ -n "${NO_COLOR:-}" ]; then RED=""; YEL=""; GRN=""; RST=""; fi

ok()   { printf '%s[ok]%s %s\n'   "$GRN" "$RST" "$*"; }
warn() { printf '%s[skip]%s %s\n' "$YEL" "$RST" "$*" >&2; }
bad()  { printf '%s[FAIL]%s %s\n' "$RED" "$RST" "$*" >&2; }

# Resolve the skill root from this script's own location (scripts/ lives under it).
SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
SKILL_DIR=$(cd "$SCRIPT_DIR/.." && pwd)
TARGET="${1:-$SKILL_DIR}"

if ! command -v shellcheck >/dev/null 2>&1; then
  warn "shellcheck not installed (brew install shellcheck / https://github.com/koalaman/shellcheck) — skipping lint"
  exit 0
fi

FAILED=0
TMP=$(mktemp -d)
trap 'rm -rf "$TMP"' EXIT   # one idempotent EXIT trap — the pattern this skill teaches

# Context codes that are noise on an isolated snippet (undefined vars/functions
# defined elsewhere in the doc, missing shebang we synthesize, unresolved source,
# unused vars in a fragment). These are excluded ONLY for extracted snippets,
# never for real *.sh files.
SNIPPET_EXCLUDE="SC2148,SC2154,SC2034,SC1090,SC1091,SC2317,SC2168,SC2030,SC2031"

# extract_blocks FILE  — write each ```bash block to $TMP/<base>.NN.sh with a
# strict-mode header. Blocks whose body contains a "# Bad" line are skipped.
extract_blocks() {
  file="$1"
  base=$(basename "$file" .md)
  awk -v dir="$TMP" -v base="$base" '
    /^```bash$/ { inblk=1; n++; body=""; bad=0; next }
    /^```/      { if (inblk) {
                    inblk=0
                    if (!bad) {
                      f = sprintf("%s/%s.%02d.sh", dir, base, n)
                      printf "#!/usr/bin/env bash\nset -euo pipefail\n%s", body > f
                      close(f)
                      print f
                    }
                  }
                  next }
    inblk       { if ($0 ~ /# Bad/) bad=1; body = body $0 "\n" }
  ' "$file"
}

lint_one() { # lint_one FILE EXCLUDE
  if [ -n "$2" ]; then
    shellcheck --exclude="$2" "$1"
  else
    shellcheck "$1"
  fi
}

printf '\n=== Snippet self-check (%s) ===\n' "$SKILL_DIR"
SNIPPET_FILES=""
for src in "$SKILL_DIR/SKILL.md" "$SKILL_DIR"/references/*.md; do
  [ -e "$src" ] || continue
  while IFS= read -r snip; do
    [ -n "$snip" ] || continue
    SNIPPET_FILES="$SNIPPET_FILES $snip"
  done <<EOF
$(extract_blocks "$src")
EOF
done

if [ -z "${SNIPPET_FILES// /}" ]; then
  warn "no \`\`\`bash snippets found to check"
else
  for snip in $SNIPPET_FILES; do
    if lint_one "$snip" "$SNIPPET_EXCLUDE"; then
      ok "snippet clean: $(basename "$snip")"
    else
      bad "snippet has findings: $(basename "$snip")"
      FAILED=1
    fi
  done
fi

printf '\n=== Script lint (%s) ===\n' "$TARGET"
FOUND=0
# find -print0 + NUL read: the space/newline-safe iteration this skill preaches.
while IFS= read -r -d '' sh; do
  FOUND=1
  if shellcheck "$sh"; then
    ok "clean: $sh"
  else
    bad "findings: $sh"
    FAILED=1
  fi
done < <(find "$TARGET" -type f -name '*.sh' ! -path "*/scripts/verify.sh" -print0)

if [ "$FOUND" -eq 0 ]; then
  ok "no *.sh files under target (nothing to lint)"
fi

printf '\n=== Summary ===\n'
if [ "$FAILED" -eq 0 ]; then
  ok "shellcheck clean"
else
  bad "shellcheck findings present — fix before shipping"
fi
exit "$FAILED"