projectbluefin/common/shell-scripts

Shell Scripts — authoring and testability

This skill owns shell authoring and testability; CI tooling owns workflow policy and CI pitfalls owns failure diagnosis.

When to Use

• Writing or modifying a shell script under system_files/
• Writing bats tests for a shell script
• Debugging a shellcheck failure in validate.yml
• Removing a shell script from common (removal checklist)

When NOT to Use

• CI workflow configuration (pre-commit, actionlint, SHA pinning) → `ci-tooling.md`
• CI incident log and silent failure patterns → `ci-pitfalls.md`

Removing a shell script from common

When deleting system_files/bluefin/usr/bin/<script>, check its callers:

Dead apt step hazard

If the validate.yml shellcheck step was the only consumer of Install shellcheck in that job, delete the apt install step too — it becomes a silent no-op that wastes ~20 seconds per CI run and confuses future readers.

Cross-reference sweep

After deleting the script and its skill file, run:

grep -rn "<script-name>" docs/ --include="*.md" --include="*.json"

Common survivors: devmode.md advisories and image-registry.md section headers.

Core Testability Idioms

Quick reference — full patterns with WRONG/CORRECT examples in references/testability-patterns.md.

Bats Test Structure

Standard file layout, mocking, and pitfalls in references/bats-patterns.md.

Just recipe descriptions

Keep maintainer notes above the user-facing description comment. just --list uses the last comment line before a recipe's attributes as its description, so a note about dependency pins can accidentally replace the help text. Separate the notes with a blank line, then put the description immediately above the recipe's attributes.

Verify the displayed text without running the installer:

just --justfile system_files/shared/usr/share/ublue-os/just/apps.just --list

Shellcheck Reference

Directive syntax, SC code notes, and quoting fix examples in references/shellcheck-examples.md.

Red Flags

• A shell script reads from a hardcoded /proc, /dev, or /usr/share/... path without an env-var override — untestable in CI
• A bats test overrides HOME but not XDG_CONFIG_HOME — leaks to the real runner config dir
• A shellcheck disable= directive has an inline comment after it (SC1072/SC1073)
• A script's main flow runs on source (no BASH_SOURCE guard) — breaks bats loading
• --cov=tests in a pytest invocation — measures test files, not source under test

Verification

• [ ] shellcheck -S warning <file> passes on the modified script
• [ ] just test passes locally (bats + pytest)
• [ ] If a shellcheck directive was added, verify its syntax against Context7 (shellcheck library) and confirm the SC code is correct
• [ ] If a bats test uses env-var overrides, confirm the script uses ${VAR:-default} at the read site — the override does nothing without it
• [ ] If a script was removed, all 4 touch-points were checked and the cross-reference sweep returned no survivors

References