Code Conventions

Code Conventions

Standards for shell modules, function naming, error handling, configuration access, and testing patterns used across the strut codebase.

Shell Modules (lib/*.sh)

Every lib module must:

• Start with #!/usr/bin/env bash
• Include set -euo pipefail
• Have a header comment block: module name, description, dependencies, provided functions
• Document required sourced dependencies (e.g., # Requires: lib/utils.sh sourced first)

Function Naming

Pattern	Use	Example
cmd_<name>()	Command handlers	cmd_deploy() in lib/cmd_deploy.sh
_prefixed()	Internal helpers	_resolve_script_dir()
descriptive_name()	Public library functions	find_project_root()

Error Handling

Function	Behavior
fail "msg"	Fatal — exits 1 to stderr
warn "msg"	Non-fatal — continues to stdout
log "msg"	Informational with [strut] prefix
ok "msg"	Success with checkmark

Never use bare || return 1 without a message.

Configuration Rules

• All config is read from strut.conf via lib/config.sh
• Never hardcode org names, registry types, branch names, or service names
• Per-stack config comes from services.conf, required_vars, volume.conf, repos.conf
• Defaults are defined in load_strut_config() only

SSH Commands

Always use build_ssh_opts for consistent SSH option building. Always use validate_env_file before accessing env vars.

Compose Commands

Always use resolve_compose_cmd for consistent project naming. Never construct compose commands manually.

Dry-Run Support

• Wrap destructive operations with run_cmd or run_cmd_eval
• Check DRY_RUN=true for early exit with execution plan display

Tests (BATS)

• File naming: tests/test_<module>.bats
• Use setup() / teardown() with TEST_TMP for temp dirs
• Source test_helper/common.bash for shared helpers
• Override fail() in tests: fail() { echo "$1" >&2; return 1; }
• Property tests: 100 iterations with randomized inputs
• Static analysis tests: grep-based checks for hardcoded references