Ref Bundle

Ref Bundle recursively resolves JSON References ($ref) across JSON, YAML, and XML configuration and writes one self-contained JSON, YAML, or XML artifact.

ref-bundle config/root.yaml --output build/config.yaml

Maintaining reusable policy, runtime profiles, workflows, and other generic configuration as named components keeps root documents focused on application intent. Ref Bundle collects those modular sources for downstream tools that only accept a single file.

Documentation

The documentation follows the Diátaxis structure:

• Tutorial: bundle your first configuration
• How to build a modular configuration
• How to use the playground
• CLI reference
• $ref reference
• Explanation: why modular configuration?
• Explanation: how the implementation is organized

Install

Ref Bundle requires Python 3.10 or newer. After configuring access to the package registry used by your organization:

python -m pip install ref-bundle
ref-bundle --help

Hatch projects

To add Ref Bundle to a named Hatch environment, configure the package index and dependency in pyproject.toml:

[tool.hatch.envs.prod.env-vars]
PIP_EXTRA_INDEX_URL = "https://token:{env:TOKEN_PYPI_REGISTRY}@git.terradue.com/api/v4/projects/{env:PYPI_PROJECT_ID}/packages/pypi/simple/"

[tool.hatch.envs.prod]
path = "/app/envs/my-hatch-env"
dependencies = [
  "ref-bundle",
]

If Ref Bundle is a runtime dependency of the package itself rather than a development environment, declare it under [project] instead:

[project]
dependencies = [
  "ref-bundle",
]

Quick example

Given components/runtimes.yaml:

python:
  image: python:3.13-slim
  replicas: 2

and config.yaml:

service:
  runtime:
    $ref: components/runtimes.yaml#/python

run:

ref-bundle config.yaml --ext json --output build/config.json

The output is a single JSON document with the referenced runtime inlined.

Playground

The Streamlit playground provides an editor for trying YAML references and viewing the resolved result:

task run_playground

See Use the playground for published-container, development-container, and direct-run instructions.

Local quality checks

Install Hatch and Taskfiles then install the Git hook:

task quality:pre-commit:install

Every commit runs Ruff (including the configured McCabe complexity limit), Ruff formatting, strict mypy checks, and the pytest suite. Run the complete hook explicitly with:

task quality:pre-commit:run

License