#!/usr/bin/env bash
# Starter scaffold for an agent-facing skill script. <one-line, ends with a period.>
#
# Usage:   script-template.sh [OPTIONS] <input>...
# Input:   one or more inputs as positionals; flags select behaviour
# Output:  stdout = data product only (TSV, or JSON under --json)
# Stderr:  headers, progress, warnings, errors
# Exit:    0 ok, 2 usage, 3 not-found, 4 validation, 5 missing-dep,
#          7 unavailable, 10 <domain signal — document it here>
#
# Examples:
#   script-template.sh input.txt
#   script-template.sh --json a.txt b.txt | jq '.data[]'
#   script-template.sh --out result.tsv --quiet input.txt
#
# Requires: bash 4+ (uses mapfile-style idioms); shellcheck-clean.

set -Eeuo pipefail
IFS=$'\n\t'

# --- semantic exit codes (SKILL-RESOURCE-PROTOCOL §5) ---
readonly EXIT_OK=0 EXIT_USAGE=2 EXIT_NOTFOUND=3 EXIT_VALIDATION=4
readonly EXIT_MISSING_DEP=5 EXIT_UNAVAILABLE=7 EXIT_FINDING=10

readonly SCRIPT_NAME="$(basename -- "${BASH_SOURCE[0]}")"

# --- help (stdout, exit 0, EXAMPLES mandatory) ---
usage() {
  cat <<EOF
Usage: ${SCRIPT_NAME} [OPTIONS] <input>...

Options:
  --json            emit a JSON envelope to stdout (needs jq)
  --out FILE        write output to FILE atomically (default: stdout)
  -q, --quiet       suppress progress framing on stderr
  -h, --help        show this help and exit

EXAMPLES:
  ${SCRIPT_NAME} input.txt
  ${SCRIPT_NAME} --json a.txt b.txt | jq '.data[]'
  ${SCRIPT_NAME} --out result.tsv -q input.txt
EOF
}

# --- framing helpers: human text ALWAYS to stderr, never stdout ---
log()  { [[ "$QUIET" -eq 1 ]] && return 0; printf '%s\n' "$*" >&2; }
die()  { printf 'ERROR: %s\n' "$*" >&2; exit "${2:-1}"; }

# --- cleanup trap + atomic write scaffolding ---
TMPFILE=""
cleanup() {
  local rc=$?
  [[ -n "$TMPFILE" && -e "$TMPFILE" ]] && rm -f -- "$TMPFILE"
  exit "$rc"
}
trap cleanup EXIT
trap 'die "interrupted" 130' INT TERM

# --- argument parsing: case loop, long flags, hard usage errors ---
JSON=0; QUIET=0; OUT=""; ARGS=()
while [[ $# -gt 0 ]]; do
  case "$1" in
    --json)      JSON=1 ;;
    -q|--quiet)  QUIET=1 ;;
    --out)       OUT="${2:?--out needs a value}"; shift ;;
    --out=*)     OUT="${1#*=}" ;;
    -h|--help)   usage; exit "$EXIT_OK" ;;
    --)          shift; ARGS+=("$@"); break ;;
    -*)          die "unknown flag: $1 (try --help)" "$EXIT_USAGE" ;;
    *)           ARGS+=("$1") ;;
  esac
  shift
done

# --- validation (per §5/§6) ---
[[ ${#ARGS[@]} -ge 1 ]] || die "need at least one input (try --help)" "$EXIT_USAGE"
if [[ "$JSON" -eq 1 ]]; then
  command -v jq >/dev/null 2>&1 || die "jq required for --json" "$EXIT_MISSING_DEP"
fi
for in_f in "${ARGS[@]}"; do
  [[ -e "$in_f" ]] || die "input not found: $in_f" "$EXIT_NOTFOUND"
done

# --- work: write the DATA PRODUCT to a buffer, framing to stderr ---
log "=== ${SCRIPT_NAME}: processing ${#ARGS[@]} input(s) ==="

emit_records() {
  # Replace this with real logic. Data → stdout, one TSV record per line.
  local f
  for f in "${ARGS[@]}"; do
    local lines
    lines=$(wc -l < "$f" 2>/dev/null || echo 0)
    printf '%s\t%s\n' "$f" "$lines"   # DATA → stdout
    log "  [ok] ${f} (${lines} lines)"  # framing → stderr
  done
}

if [[ "$JSON" -eq 1 ]]; then
  # Build the §4 success envelope. Booleans true/false, empty lists [], ISO-8601 Z.
  records="$(emit_records | jq -R -s -c 'split("\n")
    | map(select(length>0) | split("\t") | {file: .[0], lines: (.[1]|tonumber)})')"
  payload="$(jq -cn --argjson d "$records" \
    '{data: $d, meta: {count: ($d|length), schema: "claude-mods.bash-ops.script-template/v1"}}')"
else
  payload="$(emit_records)"
fi

# --- output: atomic write when --out, else stdout ---
if [[ -n "$OUT" ]]; then
  TMPFILE="$(mktemp -- "${OUT}.XXXXXX")" || die "mktemp failed" "$EXIT_UNAVAILABLE"
  printf '%s\n' "$payload" > "$TMPFILE"
  mv -- "$TMPFILE" "$OUT"     # atomic rename — reader never sees a partial file
  TMPFILE=""                  # disarm cleanup; the file is now $OUT
  log "wrote ${OUT}"
else
  printf '%s\n' "$payload"    # DATA → stdout
fi

exit "$EXIT_OK"

# Argument Parsing — deep dive

Robust, agent-facing argument handling. The resource protocol requires `--help`
with EXAMPLES (exit 0 to stdout) and a hard USAGE error (exit 2) on unknown flags
or extra positionals. Two idioms cover everything: the **`case` loop** (preferred,
long-flag capable) and **`getopts`** (short-flags only, more compact).

## The `case` loop (preferred)

Handles long flags (`--json`), short flags, value-taking flags, `--flag=value`,
and the `--` end-of-options sentinel. This is what `preinstall-check.sh` uses.

```bash
usage() {
  cat <<'EOF'
Usage: tool [OPTIONS] <input>...
  --json            emit JSON to stdout
  --out FILE        write result to FILE (default: stdout)
  --retries N       retry N times (default: 3)
  -q, --quiet       suppress progress on stderr
  -h, --help        show this help

EXAMPLES:
  tool input.txt
  tool --json --out result.json a.txt b.txt
  tool --retries 5 -q input.txt
EOF
}

JSON=0; QUIET=0; OUT=""; RETRIES=3; ARGS=()
while [[ $# -gt 0 ]]; do
  case "$1" in
    --json)        JSON=1 ;;
    -q|--quiet)    QUIET=1 ;;
    --out)         OUT="${2:?--out needs a value}"; shift ;;
    --out=*)       OUT="${1#*=}" ;;
    --retries)     RETRIES="${2:?--retries needs a value}"; shift ;;
    --retries=*)   RETRIES="${1#*=}" ;;
    -h|--help)     usage; exit 0 ;;
    --)            shift; ARGS+=("$@"); break ;;
    -*)            printf 'ERROR: unknown flag: %s (try --help)\n' "$1" >&2; exit 2 ;;
    *)             ARGS+=("$1") ;;
  esac
  shift
done

# validation
[[ ${#ARGS[@]} -ge 1 ]] || { printf 'ERROR: need at least one input (try --help)\n' >&2; exit 2; }
[[ "$RETRIES" =~ ^[0-9]+$ ]] || { printf 'ERROR: --retries must be an integer\n' >&2; exit 2; }
```

Key points:

- **Value-taking flags** consume `$2` then `shift` an extra time. `${2:?msg}` aborts
  with `msg` if the value is missing — clean for `set -u` scripts.
- **`--flag=value` form** handled by a parallel `--flag=*` arm using `${1#*=}`
  (strip up to the first `=`).
- **`--` sentinel** stops option parsing: everything after is positional, even if it
  starts with `-`. Essential when an input filename might be `-weird`.
- **Unknown flag** (`-*`) is a hard exit 2 — never silently ignore (protocol §6).
- **Positionals** accumulate into an array so spaces survive; consume them with
  `"${ARGS[@]}"`.
- Validate *after* parsing: required count, integer ranges, file existence (exit 3
  for a missing input file per §5).

## `getopts` (short flags only)

POSIX-portable, compact, but **no long-flag support** and no `--flag=value`. Good
for a small script with only single-letter options.

```bash
JSON=0; OUT=""; verbose=0
while getopts ':jo:vh' opt; do
  case "$opt" in
    j) JSON=1 ;;
    o) OUT="$OPTARG" ;;          # ':' after o means it takes a value
    v) verbose=1 ;;
    h) usage; exit 0 ;;
    :) printf 'ERROR: -%s needs a value\n' "$OPTARG" >&2; exit 2 ;;
    \?) printf 'ERROR: unknown flag: -%s\n' "$OPTARG" >&2; exit 2 ;;
  esac
done
shift $((OPTIND - 1))            # drop parsed options; "$@" is now positionals
```

- The **leading `:`** in `':jo:vh'` enables *silent* error mode, letting you handle
  `:` (missing value) and `\?` (unknown) yourself with proper exit-2 messages.
- A letter followed by `:` (here `o:`) takes a value in `$OPTARG`.
- `shift $((OPTIND - 1))` discards the consumed options so `"$@"` holds positionals.
- Limitations that push you to the `case` loop: `getopts` cannot do `--json`,
  cannot do `--out=x`, and clustering long flags is impossible. For anything an
  agent invokes by long name, use the `case` loop.

## Choosing between them

| Need | Use |
|---|---|
| Any long flag (`--json`, `--dry-run`) | `case` loop |
| `--flag=value` form | `case` loop |
| Agent-facing skill script | `case` loop (matches the exemplar) |
| Tiny script, only `-x -y -z` short flags, max portability | `getopts` |

## The `--help` contract (both styles)

- Writes to **stdout** and exits **0** (it is requested output, not an error).
- Includes a usage line, every option, and an **EXAMPLES** block — the protocol
  makes EXAMPLES mandatory because it is what makes the tool discoverable when the
  agent runs `--help`.
- A common compact trick (used by `preinstall-check.sh`) is to render help from the
  first-comment-block itself: `sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'` — single
  source of truth for the contract and the help text.

# Bash Footguns — reproducers and mechanisms

Each entry: what breaks, *why* at the shell-mechanics level, and the fix. These are
the bugs `shellcheck` and `set -Eeuo pipefail` exist to catch.

## 1. Unquoted expansion → word splitting + globbing

```bash
file="my report.txt"
rm $file            # runs: rm my report.txt   → tries to remove TWO files
rm "$file"          # correct
```

**Mechanism.** After parameter expansion, an *unquoted* result undergoes (a) word
splitting on `IFS` (default: space/tab/newline) then (b) pathname expansion
(globbing). `*.bak` in a variable expands to matching files; `a b` splits to two
args. Quoting suppresses both. This is the single most common shell bug.

Fix: quote everything — `"$file"`, `"${arr[@]}"`. Set `IFS=$'\n\t'` to drop space
from the split set as defence-in-depth.

## 2. `[ ]` vs `[[ ]]`

```bash
[ -n $x ]                  # if $x is empty/unset → [ -n ] → true (wrong!)
[ "$a" == "$b" ]           # == is non-POSIX in [; && doesn't work; word-splits
[[ -n $x ]]                # safe: [[ ]] does not word-split its operands
[[ "$a" == "$b" && -f c ]] # &&, ==, < all work inside [[ ]]
```

**Mechanism.** `[` is the external/builtin `test` command — its operands are
subject to normal word splitting, so an unquoted empty variable vanishes and
changes the expression's arity. `[[ ]]` is a Bash *keyword*: it parses operands
without word splitting or globbing, supports `&&`/`||`/`<`/`==` with pattern
matching and `=~` for regex. Use `[[ ]]` in Bash always; reserve `[ ]` for strict
POSIX `sh` scripts.

## 3. `$?` after assignment is always 0

```bash
output=$(might_fail)
echo $?              # prints 0 — the ASSIGNMENT succeeded, not might_fail
```

**Mechanism.** A simple assignment's exit status is that of the *last command
substitution*, but a plain `var=$(cmd)` reports the assignment builtin's status,
which is 0 unless the substitution itself errors fatally. Capture inline:

```bash
if ! output=$(might_fail); then echo "failed" >&2; fi
# or
output=$(might_fail); rc=$?       # rc only reliable when not 'local'/'declare'
```

## 4. Pipe into `while read` loses variables (subshell)

```bash
count=0
printf 'a\nb\nc\n' | while read -r line; do count=$((count+1)); done
echo "$count"        # prints 0 — the while ran in a subshell
```

**Mechanism.** Each stage of a pipeline runs in its **own subshell**. The `while`'s
variable mutations happen in a child process and evaporate when it exits. Fixes:

```bash
# process substitution — while runs in the current shell
count=0
while read -r line; do count=$((count+1)); done < <(printf 'a\nb\nc\n')
echo "$count"        # 3

# or a here-string / file redirect
while read -r line; do …; done <<< "$data"
```

(Bash's `shopt -s lastpipe` runs the last pipe stage in the current shell, but only
non-interactively and with job control off — process substitution is more portable.)

## 5. `local x=$(cmd)` masks failure under `set -e`

```bash
set -e
get() { local v=$(false); echo "reached"; }   # 'reached' prints — failure hidden
get() { local v; v=$(false); echo "nope"; }    # aborts at v=$(false)
```

**Mechanism.** `local`/`declare`/`export` are commands; their exit status is the
builtin's (0 on a valid declaration), which overrides the substitution's failing
status. `set -e` sees 0 and continues. Always split declaration and assignment when
the command's success matters.

## 6. `echo` is not portable for data

```bash
echo "-n"            # may print nothing (treated as a flag) or "-n"
echo "a\tb"          # prints literal \t or a tab depending on shell/xpg_echo
printf '%s\n' "$x"   # correct, deterministic
```

**Mechanism.** `echo`'s handling of `-n`, `-e`, and backslash escapes is
unspecified across shells and `shopt xpg_echo`. For any variable data, use
`printf '%s\n'`. Reserve `echo` for fixed, escape-free literals.

## 7. `for f in $(ls)` / parsing `ls`

```bash
for f in $(ls *.txt); do …   # breaks on spaces, newlines, globs in names
for f in *.txt; do            # correct: glob directly, no ls
  [[ -e "$f" ]] || continue   # handle "no matches" (glob stays literal)
  …
done
```

**Mechanism.** `$(ls)` produces a single string that word-splits on whitespace — a
filename with a space becomes two loop iterations. Globbing (`*.txt`) yields each
match as one word safely. Guard the no-match case (a non-matching glob expands to
itself unless `shopt -s nullglob`).

## 8. Reading a file line-by-line

```bash
while IFS= read -r line; do
  printf 'got: %s\n' "$line"
done < "$file"
# trailing line with no newline:
while IFS= read -r line || [[ -n "$line" ]]; do …; done < "$file"
```

**Mechanism.** `IFS=` (empty) stops leading/trailing whitespace trimming; `-r`
stops backslash interpretation. Without both, indentation and backslashes are
mangled. The `|| [[ -n "$line" ]]` clause catches a final line lacking a newline
(`read` returns non-zero but still sets `line`).

## 9. `pipefail` + early-closing consumer = exit 141

```bash
set -o pipefail
generate_huge_stream | head -5    # head exits after 5 lines → SIGPIPE to generator
echo $?                            # 141 (128 + 13) even though nothing is wrong
```

**Mechanism.** When `head` closes the read end, the producer gets SIGPIPE (signal
13) and dies with `128+13=141`; `pipefail` propagates that as the pipeline status.
Tolerate it: `{ generate_huge_stream || [[ $? -eq 141 ]]; } | head -5`.

## 10. Empty array under `set -u` (older Bash)

```bash
set -u
arr=()
printf '%s\n' "${arr[@]}"     # Bash <4.4: "unbound variable" error
printf '%s\n' "${arr[@]:-}"   # safe everywhere
```

**Mechanism.** Pre-4.4 Bash treated `"${arr[@]}"` of an empty array as referencing
an unset variable under `-u`. Use `"${arr[@]:-}"`, or test `((${#arr[@]}))` first.
Fixed in Bash 4.4 for `@`/`*`, but the guard keeps scripts portable to macOS 3.2
and old CI images.

## 11. `cd` without checking, then destructive op

```bash
cd "$dir" && rm -rf -- ./*     # if cd fails, rm never runs (good)
cd "$dir"; rm -rf -- ./*       # if cd fails (under no -e), rm runs in WRONG dir
```

**Mechanism.** A failed `cd` (typo, missing dir) leaves you in the *current*
directory. A following unconditional `rm -rf ./*` then wipes the wrong tree. Always
`cd … || exit 1`, or chain with `&&`, or run under `set -e`. Add `--` and `./`
prefixes so a path beginning with `-` is data, not flags.

# Strict Mode and Traps — deep dive

The error-handling backbone of a defensive Bash script. The SKILL.md body covers
the three-line preamble; this file covers the edge cases that bite in production.

## The four flags, precisely

### `set -e` (errexit) — and where it silently does nothing

`set -e` aborts the script when a command returns non-zero. It is the most useful
and the most misunderstood flag because of where it **does not** fire:

1. **Conditions.** A command in an `if`, `while`, `until`, `&&`, `||`, or negated
   with `!` is a *tested* command — its failure is expected, so `-e` ignores it.
   ```bash
   if ! grep -q foo file; then …    # grep failing here does NOT abort
   ```
2. **Inside functions called in a condition.** If `f` is invoked as `if f; then`,
   `-e` is disabled *for the entire body of `f`* (POSIX behaviour). A failing
   command deep inside `f` won't abort. This surprises everyone once.
3. **Non-final pipe stages.** Without `pipefail`, only the last command's status
   counts: `false | true` succeeds. Add `set -o pipefail`.
4. **`local`/`declare` masking.** `local x=$(cmd)` — the *assignment builtin*
   returns 0 even if `cmd` failed. Split the declaration from the assignment:
   ```bash
   local x; x=$(cmd)    # now $? reflects cmd, and -e can fire
   ```
5. **Command substitution in an unchecked statement.** `echo "$(false)"` does not
   abort under older Bash because the outer `echo` succeeds. Assign first if the
   substitution's success matters.

**When to drop `-e`.** Scripts that *inspect* exit codes themselves (a checker that
branches on whether `curl` got a 404 vs a network error) must NOT let `-e` kill the
run on the first non-zero. Those use `set -uo pipefail` and check `$?` explicitly —
this is exactly what `preinstall-check.sh` does, and why the resource protocol §2
says "use `-e` only when every failure is fatal."

### `set -u` (nounset)

Expanding an unset variable becomes a fatal error instead of an empty string —
catches typos (`$fil` vs `$file`) and missing arguments.

- `"$1"` when no `$1` was passed → aborts. Guard: `"${1:-default}"` or
  `[[ $# -ge 1 ]] || { usage; exit 2; }`.
- **Empty-array gotcha:** in Bash before 4.4, `"${arr[@]}"` on an empty array trips
  `-u`. Use `"${arr[@]:-}"` or test `[[ ${#arr[@]} -gt 0 ]]` first. (Bash 4.4+ fixed
  this for `@`/`*`.)

### `set -o pipefail`

A pipeline's exit status becomes the rightmost **non-zero** status (or 0 if all
succeed). Without it, a failing producer is invisible:

```bash
set -o pipefail
data="$(curl -fsS "$url" | jq '.x')"   # now a curl failure fails the assignment
```

**SIGPIPE / 141 caveat:** when a consumer closes the pipe early (`producer | head -1`),
the producer is killed by SIGPIPE and reports `141`. With `pipefail` this surfaces as
a pipeline failure even though nothing is wrong. Tolerate it for truncating
consumers: `{ big_producer || [[ $? -eq 141 ]]; } | head`.

### `set -E` (errtrace)

Makes an `ERR` trap inherit into shell functions, command substitutions, and
subshells. Without `-E`, your nice line-number-reporting `ERR` trap silently fails
to fire inside functions. Always pair `-E` with an `ERR` trap.

## ERR trap with context

```bash
set -Eeuo pipefail

err() {
  local rc=$?
  printf 'ERROR: rc=%d at %s:%d in %s()\n' \
    "$rc" "${BASH_SOURCE[1]:-?}" "${BASH_LINENO[0]:-?}" "${FUNCNAME[1]:-main}" >&2
  exit "$rc"
}
trap err ERR
```

`BASH_LINENO`/`BASH_SOURCE`/`FUNCNAME` are parallel stack arrays — index `[0]`/`[1]`
walk up the call stack. This turns "it failed somewhere" into "it failed at
deploy.sh:42 in push_image()".

## EXIT trap — cleanup that always runs

```bash
tmpdir="$(mktemp -d)"
cleanup() {
  local rc=$?            # capture BEFORE any command in cleanup changes $?
  rm -rf -- "$tmpdir"
  exit "$rc"            # preserve the original exit code
}
trap cleanup EXIT
```

- `EXIT` fires on normal exit, `set -e` abort, `exit N`, and — if not separately
  trapped — after the default signal handlers. It is the single most reliable place
  to release resources.
- **Capture `$?` as the first line** of the handler. Any command inside `cleanup`
  overwrites `$?`, so grab it before `rm` et al.
- A `trap … EXIT` set in a subshell only covers that subshell.

## Signal handling

```bash
interrupted=0
on_int() { interrupted=1; printf '\ninterrupted, cleaning up…\n' >&2; }
trap on_int INT TERM
```

- `INT` (Ctrl-C), `TERM` (`kill`), `HUP` (terminal closed) are the common ones.
- After handling a signal, `EXIT` still runs — so put resource release in the EXIT
  handler and use signal handlers only for *additional* behaviour (a message, a
  flag).
- To re-raise a signal with the correct exit code (`128 + signum`), reset and
  resend: `trap - INT; kill -INT $$`.
- `trap '' INT` ignores a signal; `trap - INT` restores the default.

## Idempotency and atomic writes

The resource protocol §6 requires re-running with the same inputs to be safe.

- Never write the destination directly. Write `"$dst.tmp"` (or a `mktemp` file on
  the same filesystem) and `mv -- "$tmp" "$dst"`. `mv` within one filesystem is
  atomic — a concurrent reader sees old-or-new, never a partial file. (`mv` across
  filesystems falls back to copy+unlink and is *not* atomic — keep the temp beside
  the destination.)
- Guard creation with `mkdir -p` (idempotent) rather than `mkdir` (fails if exists).
- For "create only if absent" use `set -C` (noclobber) + `>` or `mkdir` as a lock.