Contributing

Contributing

How to set up a development environment, run tests, lint code, and submit pull requests to strut.

Setup

git clone https://github.com/gfargo/strut.git
cd strut

No build step — it's all bash. You just need shellcheck and bats for linting and testing.

brew install shellcheck bats-core   # macOS

Running Tests

bats tests/                    # All tests
bats tests/test_config.bats    # Single file

The test suite includes property-based tests with 100-iteration randomized loops.

Linting

shellcheck -s bash strut
find lib -name '*.sh' -print0 | xargs -0 shellcheck -s bash

Pull Request Process

1. Create a feature branch
2. Make your changes following Code Conventions
3. Add tests in tests/test_<module>.bats
4. Run bats tests/ and shellcheck to verify
5. Submit a PR

Key Test Files

Test	What It Covers
test_config.bats	Config walk-up, parsing defaults, symlink resolution
test_registry.bats	Registry dispatch routing, invalid type rejection
test_health_discovery.bats	Service/DB/port discovery from services.conf
test_init.bats	Init flag propagation to strut.conf
test_entrypoint.bats	Version round-trip, upgrade guard
test_no_hardcodes.bats	Static grep — no hardcoded references in engine
test_scaffold.bats	Org substitution, required_vars consistency
test_docker_helpers.bats	Docker pull, prune helpers
test_drift_helpers.bats	Drift detection logic
test_schema_helpers.bats	Schema management
test_utils.bats	Utility functions
test_volumes.bats	Volume management
test_topology.bats	Multi-host topology parsing, resolution, property tests
test_deploy_blue_green.bats	Blue-green deploy orchestration, state, rollback
test_local_helpers.bats	Local env validation, port checking, endpoint display
test_github_token.bats	GitHub token permission checks, creation, revocation
test_cmd_ship.bats	Ship command dry-run, flag parsing, env resolution
test_tui.bats	TUI stack/command/env discovery, picker helpers
test_audit.bats	Audit report generation, key categorization, stack suggestions
test_remote_init.bats	Remote init dry-run, arg parsing, connection resolution

See Also

• Code Conventions — Shell module standards
• Adding a New Command — Extending the CLI
• Project Structure — File layout