/sota-shell-scripting

name: sota-shell-scripting
description: >-
  State-of-the-art shell scripting (bash and PowerShell, defensive) for writing and auditing shell scripts, CI scripts, init/deploy scripts, container entrypoints, and Makefile recipes — and equally for the ad-hoc commands you run yourself: a grep/find/rg sweep whose result you are about to report, a one-liner pasted from a checklist, a pipeline whose exit status or empty output you are about to believe. Use when creating, modifying, reviewing or hardening shell code, AND before trusting any conclusion a shell command produced — especially an ABSENCE ("no matches", "0 results"), which a quoting bug produces identically. Trigger keywords: bash, shell script, sh, zsh, shellcheck, shfmt, CI script, Makefile shell, entrypoint script, set -euo pipefail, dotfiles, install script, cron job, wrapper script, one-liner, command line, grep sweep, search the codebase, verify a claim, no matches found, empty output, exit status, word splitting, glob, PowerShell, pwsh, .ps1, Windows CI, ErrorActionPreference.

SOTA Shell Scripting

Purpose

Produce shell scripts that survive contact with reality — unusual filenames, missing commands, partial failures, hostile input, signals, and concurrent invocation — and audit existing scripts for the defect classes that cause most production shell incidents: unquoted expansions, silent error swallowing, injection, secret leakage, and temp-file races.

Bash-focused (written for bash 5.x; macOS ships bash 3.2 and defaults to zsh — see portability rules). POSIX `sh` only when the target demands it (busybox/dash containers, init systems).

First decision: should this be shell at all?

**Do NOT use shell when any of these hold.** Recommend Python/Go (or the project's primary language) instead, and say so explicitly in BUILD and AUDIT output:

• Script exceeds ~100 lines of actual logic (not counting boilerplate/usage text).
• Needs real data structures (nested maps, JSON manipulation beyond a `jq` one-liner, sets).
• Needs granular error handling (retry *this* step, distinguish error kinds, partial rollback).
• Does arithmetic beyond integers, date math, or float comparison.
• Parses structured formats (JSON/YAML/XML) with string surgery instead of `jq`/`yq`.
• Needs portable concurrency beyond "run N jobs and `wait`".
• Is security-critical input handling (auth, parsing untrusted network data).

Shell is the right tool for: gluing processes together, CI steps, container entrypoints, small install/deploy wrappers, environment setup — anything that is mostly *invoking other programs* rather than computing.

BUILD mode

When writing or modifying shell scripts:

1. **Pick the dialect deliberately.** `#!/usr/bin/env bash` unless the target is a minimal container/init context that only guarantees POSIX `sh`. Never `#!/bin/sh` with bashisms. 2. **Start every bash script from the safety preamble** ([rules/01](rules/01-safety-baseline.md)): `set -euo pipefail`, trap-based cleanup, `IFS` discipline — and know where `set -e` does NOT fire. 3. **Quote every expansion.** `"$var"`, `"$@"`, `"$(cmd)"`. Build commands with arrays, never with string concatenation. 4. **Errors are loud and routed to stderr** with script name + context; exit codes are meaningful and documented in `--help`. 5. **Make it idempotent and interrupt-safe**: `mktemp` + `trap` cleanup, atomic writes via `mv`, check-before-create, `flock` if concurrent runs are possible. 6. **Run `shellcheck` (treat all findings as blockers, suppress only with a justifying comment) and `shfmt -d` before declaring done.** If they are unavailable locally, ask the operator to install them (router principle 6); only if they decline, state that and flag CI must run them. 7. Provide `--help` always; `--version` for distributed tools; `set -x` behind a `DEBUG`/`TRACE` env guard, never unconditionally (secret leakage).

AUDIT mode

**Coverage:** every `rules/` file's Audit checklist applies in AUDIT mode. Mark one *not applicable* only with its reason in the report — never skip a file because the thing it checks for is absent, since that absence may be the finding.

When reviewing existing shell scripts, hunt the defect classes in rules/ files bottom-up (each rules file ends with an audit checklist of grep patterns and ShellCheck codes). Run `shellcheck -S style` on every script if available; correlate findings with context — ShellCheck flags symptoms, you judge exploitability and blast radius.

Severity conventions:

| Severity | Meaning | Examples | |---|---|---| | CRITICAL | Exploitable or data-destroying now | `eval` on untrusted input; unquoted var in `rm -rf`; secrets in argv/`set -x`; curl\|bash of unpinned URL in prod | | HIGH | Will corrupt/fail on realistic input or failure | unquoted expansions in destructive paths; missing `set -e`/error checks around critical steps; predictable temp files; non-atomic config writes; missing `exec` in entrypoint (signals lost) | | MEDIUM | Latent bug or fragility | parsing `ls`; `which` instead of `command -v`; missing `pipefail`; no `--` separators; no timeouts on network calls; `echo` for variable data | | LOW | Style/maintainability with safety implications | missing `local`; `[ ]` where `[[ ]]` intended; missing `readonly`; inconsistent error messages |

Finding format:

[SEVERITY] file:line — short title (SCxxxx if applicable)
  Evidence: the offending line(s), verbatim
  Impact: what input/condition triggers it and what breaks
  Fix: concrete replacement code
  Effort: trivial | small | medium | large

Rules index

| File | Covers | |---|---| | [rules/01-safety-baseline.md](rules/01-safety-baseline.md) | Shebang discipline, `set -euo pipefail` and its real limitations, quoting & word-splitting bug catalog, **zsh-vs-bash deviations that bite pasted commands (joining, `pipestatus`; the full table, `NOMATCH` included, is [rules/06](rules/06-ad-hoc-commands.md) §1)** · **a background job's