# Plugins Strut ships a lightweight plugin system so operators can extend the CLI with project-specific commands without forking the engine. Drop a `cmd_.sh` file in `.strut/plugins/` under your project root and strut will discover it at startup and dispatch `strut ` or `strut ` to it. ## Why plugins Strut's core commands are deliberately generic. Teams often have workflows on top of them — a blessed deploy-and-announce pipeline, a custom metrics pull, a bespoke bulk rotation — that shouldn't live in the engine. Plugins give you the familiar `strut …` namespace for those workflows while keeping strut itself upgradeable. ## Directory layout ``` my-project/ ├── strut.conf ├── stacks/ │ └── api/ └── .strut/ └── plugins/ ├── cmd_ship.sh # strut ship ├── cmd_announce.sh # strut announce "..." └── cmd_metrics.sh # strut metrics ``` Plugins live under `${PROJECT_ROOT}/.strut/plugins/`. The filename must match `cmd_.sh`; everything else is ignored. The `` portion is the command name operators will type. ## Plugin contract Every plugin file must define `plugin_main`. `plugin_help` is optional but strongly recommended — it's what `strut list plugins` and `strut help ` show. ```bash #!/usr/bin/env bash # .strut/plugins/cmd_ship.sh set -euo pipefail plugin_help() { echo "Validate, deploy, then announce to #releases" } plugin_main() { local stack="$1"; local env_name="$2"; shift 2 strut "$stack" validate --env "$env_name" strut "$stack" deploy --env "$env_name" strut notify test slack } ``` ### Argument conventions - **Top-level plugins** — `strut [args…]`. `plugin_main` receives the raw args. - **Stack-level plugins** — `strut [--env ] [args…]`. Strut parses the universal flags (`--env`, `--services`, `--json`, `--dry-run`) before calling you, then invokes `plugin_main "$stack" "$env_name" ""`. The first two positional args are always stack name and env name. ### What your plugin can use Plugins are sourced in a subshell after all of strut's libraries are loaded, so you have direct access to strut's helpers: | Helper | Purpose | |--------|---------| | `log`, `ok`, `warn`, `fail`, `error` | logging primitives | | `run_cmd`, `run_cmd_eval` | dry-run aware command execution | | `build_ssh_opts` | consistent SSH option builder | | `resolve_compose_cmd` | stack-scoped docker-compose project naming | | `out_table_header`, `out_table_row`, `out_table_render` | table output | | `out_json_object`, `out_json_field`, … | streamed JSON output | Calling `strut` itself is fully supported — plugins are re-entrant. ## Discovery & dispatch 1. After strut loads its core libraries, it scans `${PROJECT_ROOT}/.strut/plugins/` for `cmd_*.sh` files. 2. The plugin registry records each name and file path — no sourcing yet. 3. When a command name comes in: - **Core commands always win.** `strut deploy`, `strut list`, `strut doctor` etc. never get routed to a plugin of the same name. - **Stacks always win.** At the top level, if `$1` is a stack directory, strut dispatches to the stack regardless of plugin names. You can't shadow a stack. - Otherwise, if a plugin matches, strut sources the file in a subshell and invokes `plugin_main`. 4. `strut list plugins` renders the registry; `strut help ` runs the plugin's `plugin_help`. ## Listing and help ```bash strut list plugins # table view strut list plugins --json # machine-readable strut help ship # runs plugin_help from cmd_ship.sh ``` ## Safety model - **Subshell isolation.** Plugin code runs in a `(...)` subshell. A plugin that calls `exit 1`, hits `set -e`, or gets killed does not crash strut. - **Operator privileges.** Plugins run with the same permissions as the shell invoking strut — no sandbox. Only ship plugins you trust. - **Core precedence.** A plugin named `cmd_deploy.sh` will never run as `strut deploy`. Plugin names must not collide with core commands (use `cmd_ship.sh` etc.). ## Writing a plugin — end to end ```bash $ mkdir -p .strut/plugins $ cat > .strut/plugins/cmd_ship.sh <<'EOF' #!/usr/bin/env bash set -euo pipefail plugin_help() { echo "Validate + deploy + post-deploy hook" } plugin_main() { local stack="$1" env="$2" log "shipping $stack to $env" strut "$stack" validate --env "$env" strut "$stack" deploy --env "$env" ok "shipped $stack → $env" } EOF $ strut list plugins Plugins: Name Description File ---- --------------------------------- -------------------------------- ship Validate + deploy + post-deploy … /path/.strut/plugins/cmd_ship.sh $ strut api ship --env prod ``` ## Testing plugins The `lib/plugins.sh` module is itself covered by `tests/test_plugins.bats`, which doubles as a working reference for plugin authors — it shows how to structure a plugin and assert its behavior end-to-end through the strut entrypoint.