Tooling

The operational shell scripts that consumer projects run - build, provision, database, deployment and notification commands - live in .vortex/tooling/ and are published as the standalone drevops/vortex-tooling Composer package. Consumer projects install the package and run the scripts from vendor/bin/vortex-*.

Package layout

Path	Purpose
src/	The shipped scripts - the only directory in the published archive
tests/unit/	BATS unit tests covering the shipped scripts
playground/	Manual scripts that hit live services (Slack, JIRA, New Relic); not automated

tests/ and playground/ are stripped from the published archive via .gitattributes export-ignore.

While developing Vortex itself, the template's root composer.json resolves the package from the in-tree copy through a path repository with a pinned version; the installer strips that entry so consumer sites resolve the published package from Packagist.

Script conventions

Every shipped script follows the same pattern: an environment-loading header that reads .env and .env.local while letting real environment variables win, set -eu with an opt-in VORTEX_DEBUG=1 trace, variables with defaults, and the shared output helpers.

The output helpers have a strict contract:

• info opens and closes an operation.
• task announces work that is starting - and every task must be closed by a pass or a fail, even when the work itself cannot fail, so the reader can always tell whether a step succeeded.
• note is a standalone remark that starts no task.
• fail reports the failure and aborts.

task "Disabling Search API Solr server."
drush search-api:server-disable solr || true
pass "Disabled Search API Solr server."

The || true in this example is deliberate: the disable is best-effort because the Solr server is not enabled in every environment, and the contract still requires the closing pass so the step reports an outcome.

See Template > Authoring scripts for the full authoring requirements shared by all shell scripts in the template.

Testing

The scripts are tested at 3 levels:

• Unit - BATS tests in tooling/tests/unit/ cover the shipped scripts with external commands mocked. Run them from .vortex/:

  cd .vortex
  ahoy test-bats
  
  # Run a single test file.
  ahoy test-bats tooling/tests/unit/deploy.bats

• Integration - the scripts are exercised end-to-end by the template's PHPUnit functional tests in .vortex/tests/ - see Template > Testing.

• Manual - tooling/playground/ holds scripts that hit live services. They are not automated; see tooling/playground/README.md.

Publishing

The Vortex - Publish tooling workflow (.github/workflows/vortex-publish-tooling.yml) mirrors .vortex/tooling/ to the drevops/vortex-tooling repository on every push to main, 2.x, and any branch whose name contains vortex-tooling, matching the source branch name. The published commit subject matches the source commit subject, and the body records provenance.

The package version is injected at publish time - never hardcode a version in the package composer.json.

Releases of the package are tagged on the mirror repository. When the tooling changed since the last release, it is tagged before the Vortex release, so the template can require the new tag - see Release > Tagging.