20 lines
1.5 KiB
Markdown
20 lines
1.5 KiB
Markdown
# Scripting Conventions
|
|
|
|
## Bash safety
|
|
|
|
- Open every script with `set -euo pipefail` — fail fast on errors, unset vars, and pipeline failures.
|
|
- `grep` exits 1 on no match — under `set -e` use `grep ... || true`; under `pipefail`, beware `grep ... | head` triggering SIGPIPE (use `|| true` on the grep side).
|
|
- One stdin per process — never pipe into a command that also reads a heredoc; pick one input source.
|
|
- Validate JSON before consuming: `jq empty <file>` or `python3 -m json.tool <file>`. Especially before dispatch loops that iterate over JSON state.
|
|
- Quote all expansions: `"$var"`, `"${array[@]}"`. Bare expansions split on whitespace.
|
|
- Edit-tool `replace_all` is a substring match — a short `old_string` like `2` will corrupt `24` → `244`. Make `old_string` unique (add surrounding context) or use individual targeted edits.
|
|
|
|
## Conventions
|
|
|
|
- All scripts live in `scripts/` and run from the repository root
|
|
- Scripts should be idempotent and safe to re-run
|
|
- Use colour output for pass/fail indicators in verification scripts
|
|
- Verification scripts should check for default/insecure credentials and print remediation instructions on failure
|
|
- Scripts should exit non-zero on failure so `&&` chains work naturally
|
|
- **Never hardcode secrets, tokens, or access keys in scripts.** Accept them via environment variables, stdin, or `@file` references. If a script needs a secret at runtime, read it from `~/dev/claude/secrets/` or accept it as a parameter — never embed it.
|