RAES Environment Packs

RAES environment packs give a scenario a standard shape. This package defines that shape and gives you the tools to build, check, and ship a pack.

A pack holds the declarative content for one reference environment: the scenario start state, its assets, and a record of where the content came from. Authors build packs; consumers validate a pack before they trust it. The format and the tools ship together, so you validate a pack against the same version you built it against.

This repository defines and validates the format, publishes the first-party infrastructure-kit collection under kits/, and hosts major example packs under packs/. Third-party catalogs consume the same package and contracts.

What a pack looks like

example-pack/
├── pack.yaml                  # identity: name, title, version, status
├── sdl/example.sdl.yaml       # the scenario start state (RAES SDL)
└── docs/
    └── provenance-ledger.yaml # where the content came from

The start state is small to begin with:

name: example-pack
nodes:
  target:
    type: vm

Install

pip install raes-env-packs

That installs the command-line tools and the importable library:

• raes-pack-new — scaffold a new pack with a progressive wizard.
• raes-pack-mcp — expose local, host-scoped pack authoring tools.
• raes-pack-validate — the author-CI check for a catalog checkout.
• raes-pack-release — build, lint, and release-gate a pack.
• raes-pack-kit — discover, inspect, preview, add, update, replace, and remove reusable infrastructure kits.
• raes-pack-issue-skeleton — generate a pack's starter GitHub issues.

It also includes every first-party kit release. Pin the package version and use bundled_kit_source() to discover and validate the installed collection without a Git checkout. See using released kits.

Validate your first pack

Scaffold a valid minimal pack in your catalog repository and check it. The wizard generates only the files the pack needs, formats the scenario identity through RAES, and validates the result before it lands:

raes-pack-new example-pack --route minimal --yes
python -c "from raes_env_packs import validate_pack; print(validate_pack('environments/example-pack').ok)"

True

Creating a pack needs Linux: the wizard publishes it with the Linux renameat2 system call, which macOS does not provide. Kit changes and raes-pack-dist install --apply need Linux for the same reason.

validate_pack is the check a consumer runs before trusting a pack: it reads the staged files, returns a result, prints nothing, and never runs the pack's code. The quickstart walks through it step by step.

Choose your route

• Author a pack — start with the quickstart and the pack reference, then compose common infrastructure from kits.
• Consume a pack — see validating a pack.
• Contribute — read CONTRIBUTING.md.

Full documentation is on Read the Docs.

What this is and is not

This project defines the pack format and tools, publishes first-party reusable kits, and hosts major example packs. It does not run a scenario or define scenario meaning — the RAES scenario language and its semantics belong to RAES, and this project consumes them from an exactly pinned raes release. It is a single-maintainer project with no support SLA. See the limitations for the full picture.

Contributing

python3 -m venv .venv
. .venv/bin/activate
pip install -e ".[test]"
python -m unittest discover -s tests

CONTRIBUTING.md has the full setup, test, and submission path. Maintainer records — decision records, CI, and release mechanics — are indexed in docs/README.md.

Releases

Releases are managed by release-please: merge-driven, nothing hand-run. Your Conventional Commit PR title is the release decision — feat: is a minor bump, fix: a patch, docs:/chore: no release. You never edit the version or CHANGELOG.md; release-please owns both. See CONTRIBUTING.md for the details.

License

MIT — see LICENSE.