DAAF-Contribution-Community/daaf / .claude/skills/shell-scripting
shell-scripting
FlaggedStandards for Bash and PowerShell scripts in DAAF: preambles, quoting, error handling, cleanup, testing. Use when writing or reviewing .sh/.ps1 files (hooks, lifecycle, utilities) and the host double-click launcher shims (.bat/.command under scripts/host/). Not runtime safety — that is bash-safety.sh hook.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 20.1 KB |
| references/bash-standards.md | markdown | 23.7 KB |
| references/error-handling.md | markdown | 14.1 KB |
| references/gotchas.md | markdown | 133.1 KB |
| references/powershell-standards.md | markdown | 17.8 KB |
| references/testing.md | markdown | 44.0 KB |
references/error-handling.md
View on GitHub# Error Handling
Cross-language error handling philosophy and patterns for DAAF shell scripts. Covers the fail-closed principle, user-facing output conventions, exit code standards, Docker-specific error handling, and dependency validation.
---
## Fail-Closed Principle
Security-critical scripts (hooks, safety checks) must fail closed: if the script cannot determine whether an action is safe, it must **block the action**. Uncertainty always resolves to denial.
```bash
# GOOD: fail-closed — missing dependency blocks the action
if ! command -v jq >/dev/null 2>&1; then
echo "ERROR: jq is required but not found. Cannot verify safety." >&2
exit 2 # Block (DAAF hook convention)
fi
# BAD: fail-open — missing dependency allows the action through
if ! command -v jq >/dev/null 2>&1; then
echo "WARNING: jq not found, skipping check" >&2
exit 0 # Allow (dangerous for security hooks)
fi
```
**When fail-closed applies:**
- All scripts in `.claude/hooks/`
- Any script that gates a destructive operation (backup verification, pre-deploy checks)
- Any script that validates permissions or credentials
**When fail-open is acceptable:**
- Non-critical convenience scripts (status displays, formatting helpers)
- Optional enhancement checks (style linting, optional metrics collection)
---
## User-Facing Output Conventions
### Two-Part Error Messages
Every error message must include TWO parts: **what went wrong** AND **what to do about it**:
```bash
# GOOD: explains both problem and remedy
echo "ERROR: Docker daemon is not running." >&2
echo " Fix: Start Docker Desktop, or run 'sudo systemctl start docker'" >&2
# BAD: states the problem but leaves the user stranded
echo "ERROR: Docker not available" >&2
```
```powershell
# GOOD
Write-Error "Docker daemon is not running. Start Docker Desktop or run 'sudo systemctl start docker'"
# BAD
Write-Error "Docker not available"
```
### Plain First Sentence for Messages Users See
Many messages reach a user as well as an agent: host-script output, hook denials, validation errors an agent relays. Open such a message with a plain sentence the user can act on, with no internal codes (stage numbers, gate or checklist IDs, guard names) and no terms a researcher would not know (`agent_reference/DOCUMENTATION_STANDARDS.md` § S3 Plain for Users). Detail for agents and contributors, such as the rule that fired or the section to read, follows on later lines.
```bash
# GOOD: plain first line the user can act on; agent detail after
echo "BLOCKED: Packages can't be installed while DAAF is running, because a rebuild would undo the change." >&2
echo " To add one, add it to the Dockerfile and rebuild." >&2
echo " Detail: CLAUDE.md § Runtime Package Installation." >&2
# BAD: opens with an internal code and gives the user nothing to act on
echo "BLOCKED: rule 8b match (SEG_OPEN_TOK)" >&2
```
### Output Routing
All diagnostic output goes to stderr so it does not contaminate stdout data streams:
```bash
# Status messages → stderr
echo "INFO: Starting backup..." >&2
# Error messages → stderr
echo "ERROR: Backup failed: disk full" >&2
# Data output → stdout (capturable by callers)
echo "$result"
```
### Color Formatting (Bash)
Use `tput` for portable color codes, and respect the `NO_COLOR` environment variable and non-TTY contexts:
```bash
# --- Color setup ---
if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
RED=$(tput setaf 1)
GREEN=$(tput setaf 2)
YELLOW=$(tput setaf 3)
CYAN=$(tput setaf 6)
RESET=$(tput sgr0)
else
RED="" GREEN="" YELLOW="" CYAN="" RESET=""
fi
# --- Helper functions ---
info() { echo "${CYAN}INFO:${RESET} $*" >&2; }
success() { echo "${GREEN}SUCCESS:${RESET} $*" >&2; }
warn() { echo "${YELLOW}WARNING:${RESET} $*" >&2; }
error() { echo "${RED}ERROR:${RESET} $*" >&2; }
```
**Key points:**
- `[ -t 1 ]` checks if stdout is a terminal (not a pipe or file)
- `NO_COLOR` is a community convention (https://no-color.org/) — respect it
- When colors are disabled, the helper functions still work, just without formatting
### Color Formatting (PowerShell)
PowerShell has built-in color support via `-ForegroundColor`:
```powershell
function Write-Info { param([string]$Message) Write-Host "INFO: $Message" -ForegroundColor Cyan }
function Write-Success { param([string]$Message) Write-Host "SUCCESS: $Message" -ForegroundColor Green }
function Write-Warn { param([string]$Message) Write-Host "WARNING: $Message" -ForegroundColor Yellow }
# Write-Error already has its own formatting
```
---
## Exit Code Conventions
### Standard Exit Codes
| Code | Meaning | When to Use |
|------|---------|-------------|
| 0 | Success | Script completed normally |
| 1 | General error | Catchall for unspecified failures |
| 2 | Blocked | DAAF hook convention: action should be prevented |
### Reserved Ranges for DAAF Scripts
Scripts that need more granular exit codes should use these ranges:
| Range | Category | Examples |
|-------|----------|---------|
| 0 | Success | — |
| 1 | General error | — |
| 2 | Blocked (hooks) | Safety check failed, unauthorized action |
| 10-19 | Docker failures | 10: daemon not running, 11: build failed, 12: compose failed |
| 20-29 | Configuration errors | 20: config file missing, 21: invalid config value |
| 30-39 | Dependency errors | 30: required tool missing, 31: wrong version |
### Consistent Exit in Bash
```bash
# Named exit codes for readability
readonly EXIT_SUCCESS=0
readonly EXIT_ERROR=1
readonly EXIT_BLOCKED=2
readonly EXIT_DOCKER_UNAVAILABLE=10
if ! docker info >/dev/null 2>&1; then
error "Docker daemon is not running. Start Docker Desktop."
exit "$EXIT_DOCKER_UNAVAILABLE"
fi
```
### Consistent Exit in PowerShell
```powershell
$EXIT_SUCCESS = 0
$EXIT_ERROR = 1
$EXIT_BLOCKED = 2
$EXIT_DOCKER_UNAVAILABLE = 10
if (-not (docker info 2>$null)) {
Write-Error "Docker daemon is not running. Start Docker Desktop."
exit $EXIT_DOCKER_UNAVAILABLE
}
```
---
## Docker-Specific Error Handling
Docker operations are uniquely error-prone because they combine native command exit codes, complex stderr output, asynchronous container startup, and machine-readable output formats.
### Pre-Docker Validation
Always check two things before any Docker operation:
```bash
# 1. Is Docker installed?
if ! command -v docker >/dev/null 2>&1; then
error "Docker not found. Install from https://docs.docker.com/get-docker/"
exit 10
fi
# 2. Is Docker daemon running?
if ! docker info >/dev/null 2>&1; then
error "Docker daemon is not running. Start Docker Desktop."
exit 10
fi
```
### Check Exit Codes After Every Call
```bash
# Bash — use if-not pattern (compatible with set -e)
if ! docker compose up -d; then
error "docker compose up failed. Check logs: docker compose logs"
exit 12
fi
```
```powershell
# PowerShell
docker compose up -d
if ($LASTEXITCODE -ne 0) {
Write-Error "docker compose up failed. Check logs: docker compose logs"
exit 12
}
```
### Capture Build Output
Docker build output should be captured to a log file AND displayed to the user. On failure, direct the user to the log:
```bash
BUILD_LOG="$(mktemp)"
trap 'rm -f "$BUILD_LOG"' EXIT
echo "[2/4] Building Docker image..."
if ! docker build -t myimage . 2>&1 | tee "$BUILD_LOG"; then
error "Docker build failed. Full log: $BUILD_LOG"
# Don't delete the log on failure — keep trap but skip cleanup
trap - EXIT
exit 11
fi
```
### Machine-Readable Status Checks
Never parse human-readable Docker output. Use machine-readable formats:
```bash
# GOOD: JSON output for programmatic parsing
docker compose ps --format json | jq -r '.[] | select(.State != "running") | .Name'
# GOOD: Go template for specific fields
docker inspect --format '{{.State.Status}}' mycontainer
# BAD: parsing human-readable table output
docker compose ps | grep "Up" | awk '{print $1}'
```
### Bounded Readiness Loops
When waiting for a container to become ready, always set a maximum wait time:
```bash
MAX_WAIT=60
INTERVAL=2
elapsed=0
echo "Waiting for service to be ready..."
while [ "$elapsed" -lt "$MAX_WAIT" ]; do
if docker compose exec -T myservice pg_isready >/dev/null 2>&1; then
success "Service is ready."
break
fi
sleep "$INTERVAL"
elapsed=$((elapsed + INTERVAL))
done
if [ "$elapsed" -ge "$MAX_WAIT" ]; then
error "Service did not become ready within ${MAX_WAIT}s."
# Capture diagnostic info
docker compose logs myservice >&2
exit 12
fi
```
**Key points:**
- Always have a maximum wait (`MAX_WAIT`)
- Capture stderr during readiness loops for diagnostics on timeout
- On timeout, dump container logs to help the user diagnose
### Detached-Container Diagnostics (`docker run -d`)
When a host driver launches a short-lived helper container in **detached** mode (`docker run -d …`, e.g. a backup-staging gate) and then reads its output back via `docker logs`, two conventions are mandatory. Both were established by a concrete 2026-07-14 field failure: a staging gate printed its diagnostics to **stderr** inside a detached busybox container, and on real Windows PowerShell 5.1 the host's `docker logs … 2>&1 | Out-String` capture came back **empty** — the user saw an error with no details at all.
**1. Container programs write user-facing output to STDOUT, not stderr.** The detached container's stderr does not reliably survive the host's `docker logs … 2>&1` merge across PowerShell 5.1's native `2>&1` handling. Anything the host needs to show the user — diagnostics, failure reasons, computed values — must go to the container's **stdout**:
```bash
# Inside the detached container's program:
# GOOD: user-facing diagnostics on stdout survive `docker logs` capture on PS 5.1
echo "STAGING: computed size = ${size} bytes"
echo "STAGING ERROR: source path not found: ${src}"
# BAD: stderr may be silently dropped by the host's `docker logs ... 2>&1 | Out-String`
echo "STAGING ERROR: source path not found: ${src}" >&2
```
> This is the deliberate inverse of the normal "diagnostics → stderr" rule (see § User-Facing Output Conventions). That rule is for scripts whose stderr the caller can actually see. A **detached** container's stderr is captured second-hand through `docker logs` and is not reliable across hosts, so its user-facing output belongs on stdout.
> **Host side of the same drop:** Windows PowerShell 5.1 empties the merged stderr when the host captures it under `$ErrorActionPreference = 'SilentlyContinue'`. See `gotchas.md` > "Windows PowerShell 5.1 Drops Native stderr Under `SilentlyContinue`, Even With `2>&1`" for the cause and its fix chooser (`'Continue'` for text shown to the user, `2>$null` for emptiness or stdout-only checks).
**2. Fetch `docker logs` BEFORE removing the container, and always emit a labeled fallback.** On any failure path, the driver must capture the container's logs *before* `docker rm -f` (removal destroys them), and if the captured log is empty it must print an explicit labeled line rather than silently showing nothing:
```bash
# Host driver — failure path ordering
cid="$(docker run -d … staging-image)"
if ! docker wait "$cid" | grep -q '^0$'; then
# 1. Fetch logs FIRST — they vanish once the container is removed
logs="$(docker logs "$cid" 2>&1)"
# 2. THEN remove the container
docker rm -f "$cid" >/dev/null 2>&1 || true
# 3. ALWAYS surface either the log or an explicit fallback — never silence
if [ -n "$logs" ]; then
error "Staging container failed. Container output:"
printf '%s\n' "$logs" >&2
else
error "Staging container failed (no details could be retrieved from the staging container)."
fi
exit 12
fi
```
**Why the fallback line matters:** an empty-log failure with no fallback is indistinguishable from success-with-no-output to the user — they see an error code and nothing else. The explicit "(no details could be retrieved…)" line tells them the failure is real *and* that the diagnostics were lost, which is itself actionable (it points at the stdout/stderr routing above).
---
## Dependency Validation
Check all external dependencies at script start, before any mutations:
### Bash Pattern
```bash
# --- Preflight ---
missing=()
for cmd in docker jq git curl; do
if ! command -v "$cmd" >/dev/null 2>&1; then
missing+=("$cmd")
fi
done
if [ ${#missing[@]} -gt 0 ]; then
error "Missing required tools: ${missing[*]}"
echo " Install with your package manager, e.g.:" >&2
echo " apt-get install ${missing[*]}" >&2
echo " brew install ${missing[*]}" >&2
exit 30
fi
```
### PowerShell Pattern
```powershell
# --- Preflight ---
$missing = @()
foreach ($cmd in @('docker', 'git')) {
if (-not (Get-Command $cmd -ErrorAction SilentlyContinue)) {
$missing += $cmd
}
}
if ($missing.Count -gt 0) {
Write-Error "Missing required tools: $($missing -join ', '). Install before proceeding."
exit 30
}
```
### Version Checks
When a minimum version is required, validate it explicitly:
```bash
# Check Docker Compose v2
if ! docker compose version >/dev/null 2>&1; then
error "Docker Compose v2 required. Found: legacy docker-compose."
echo " Upgrade: https://docs.docker.com/compose/install/" >&2
exit 31
fi
```
---
## DAAF Composability Patterns
### DAAF_NESTED Flag
When scripts call other scripts, use `DAAF_NESTED` to suppress interactive behavior:
```bash
# Outer script
export DAAF_NESTED=1
bash ./inner_script.sh
ec=$?
unset DAAF_NESTED
if [ $ec -ne 0 ]; then
error "Inner script failed with exit code $ec"
exit $ec
fi
```
```bash
# Inner script (at the end)
if [ "${DAAF_NESTED:-}" != "1" ]; then
echo ""
echo "Press Enter to close..."
read -r
fi
exit "$exit_code"
```
### Idempotent Operations
Scripts should be safe to run multiple times. Check for prior state before acting:
```bash
# Idempotent backup
if [ -d "$BACKUP_DIR" ]; then
info "Backup already exists at $BACKUP_DIR — skipping."
else
info "Creating backup at $BACKUP_DIR..."
cp -r "$TARGET_DIR" "$BACKUP_DIR"
fi
# Idempotent container start
if docker compose ps --format json | jq -e '.[] | select(.Name == "myservice" and .State == "running")' >/dev/null 2>&1; then
info "Service already running — skipping start."
else
docker compose up -d myservice
fi
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |