Developer Guide

git clone https://github.com/HeepX/heepx-sdk
cd heepx-sdk
pip install -e ".[dev]"
pre-commit install

Running checks

ruff check .
ruff format --check .
mypy src
pytest --cov=heepx --cov-report=term-missing --cov-fail-under=90

All four run in CI across Linux, macOS, and Windows. pytest alone excludes the network-marked smoke tests against the real HeepX GitHub org — run those explicitly with pytest -m network.

Project layout

src/heepx/
  __init__.py       the frozen six-function public API
  cache/             on-disk cache: extract, manifest, evict
  capability/        the Capability value object + loader
  downloader/        fetch bytes from a URL (http:// or file://)
  metadata/          CAPABILITY.yaml parsing (full HXS-META schema)
  registry/          Registry ABC + GitHubRegistry (default) + LocalRegistry
  verification/       checksum + fingerprint + the SignatureVerifier stub
  cli.py             the hx command

This is an independent, unofficial client — it has no bundled capability content of its own. Every capability it loads comes from a real repository in github.com/HeepX by default.

Contributing

The public API (the six functions above) is frozen for this release — a new function is permanent, so add one deliberately, not incidentally. See CONTRIBUTING.md for the full process, and GOVERNANCE.md for how API and CLI changes get decided.