tdd-pro-bash32-portability

Files (1)

• SKILL.md

SKILL.md (first lines)

# macOS Bash 3.2 + BSD-Tool Portability Checklist

**Rule:** Before writing or editing any new bash substrate, walk through this list. Don't catch these failures via spec runs — they're well-known and avoidable.

**Why:** Across CL-146..196 the same five portability bugs were repeatedly hit (associative arrays, `wc -l` padding, `printf %`, env-var passing, `set -u` + empty arrays). Each costs a debug-test-fix cycle of ~2 minutes. Treating this as a known-defect catalog saves ~10% per CL. Validated on CL-197: full H-8 promotion passed 10/10 first-run after applying this checklist (vs. ~4 spec-fix cycles per CL without it).

The canonical source-of-truth is [docs/memory/feedback-bash32-portability-checklist.md](../../../docs/memory/feedback-bash32-portability-checklist.md).

## The nine recurring portability bugs

### 1. No associative arrays

bash 3.2 (macOS default) rejects `declare -A`. Use `node -e '...'` for map/dict operations:

```bash
# WRONG — fails on macOS
declare -A counts
counts[apple]=3

# RIGHT — node handles maps
COUNT_JSON=$(KEY=apple VAL=3 node -e '
  const out = { [process.env.KEY]: Number(process.env.VAL) };
  process.stdout.write(JSON.stringify(out));
')
```

### 2. `wc -l < file` pads output with whitespace on macOS

```bash
# WRONG — actual value is "       2", not "2"
[ "$(wc -l < file)" = "2" ]

# RIGHT — strip whitespace
[ "$(wc -l < file | tr -d ' ')" = "2" ]
```

**Also patch spec files** — never trust a raw `wc -l` substring comparison.

### 3. `printf '...%\n'` is malformed

`%` starts a format spec; `%\n` is invalid. To emit a literal `%`, use `%%\n`:

```bash
# WRONG — silently produces nothing
printf 'similarity index 90%\n'

# RIGHT
printf 'similarity index 90%%\n'
```

Caught in W-9 spec setup with `similarity index 90%\n`.

### 4. Env-var passing into subshells must come FIRST

```bash
# WRONG — sets VAR in parent shell but NOT in node child
VAR=val RESULT=$(node -e 'console.log(process.env.VAR)')

# RIGHT — env-var goes inside the subshell, before the command
RESULT=$(VAR=val node -e 'console.log(process.env.VAR)')
```

Bites every node-via-bash one-liner.

### 5. `set -u` + empty array reference errors

`set -uo pipefail` + `"${ARR[@]}"` on an empty array → unbound variable error:

```bash
# WRONG — errors when ARR is empty
set -uo pipefail
ARR=()
for x in "${ARR[@]}"; do echo "$x"; done

# RIGHT — guard or use the empty-safe expansion
[[ ${#ARR[@]} -gt 0 ]] && for x in "${ARR[@]}"; do echo "$x"; done
# OR
for x in "${ARR[@]+"${ARR[@]}"}"; do echo "$x"; done
```

### 6. BSD `grep --flag-arg` confusion

`grep -E "--json..."` is read as a flag. Use `--` to end flag parsing:

```bash
# WRONG — BSD grep tries to parse --json as a flag
grep -E "--json-input" file

# RIGHT
grep -E -- "--json-input" file
```

### 7. Redirect order matters

`find ... 2>/dev/null >&2` sends find's stdout to /dev/null because `>&2` is evaluated when fd2 was just redirected:

```bash
# WRONG — stdout goes to /dev/null, not to original stderr
find . -type f 2>/dev/null >&2

# RIGHT — stdout to original stderr, then fd2 to /dev/null
find . -type f >&2 2>/dev/null
```

### 8. `node -e` does not allow top-level `return`

Code passed via `-e` runs at the top of a module, not inside a function:

```bash
# WRONG — SyntaxError: Illegal return statement
node -e '
  const x = check();
  if (!x) { return; }
  doMore(x);
'

# RIGHT — invert the condition
node -e '
  const x = check();

From drumfiend21/claude-tdd-pro, Apache-2.0.

More from drumfiend21/claude-tdd-pro