# STARTHERE — mgf-vm-interchange

> **Sibling library in the Magogi Foundation federation.**
> See [README.md](README.md) for what this library does; see
> [docs/inprogress/MGF_STANDARDS_CONFORMANCE.md](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md)
> for conformance; see
> [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md)
> for the federation contract.

`mgf-vm-interchange` is the OVA / OVF import-export sibling — parse an
`.ova`, extract the OVF spec + disk images, translate to the
engine-neutral `mgf.vm.core.VmSpec`; and the reverse, export a
`VmSpec` + disks to a portable `.ova`. OVF XML is parsed via
`defusedxml`; OVA tars are unpacked with safe-tar path validation.

---

## For consumers (using this library)

1. **Pin** in your `pyproject.toml`:
   ```toml
   dependencies = ["mgf-vm-interchange>=X.Y,<X.$((Y+1))"]
   ```
   See [CHANGELOG.md](CHANGELOG.md) for the current minor.
2. **Install:** `uv add mgf-vm-interchange` (or `pip install mgf-vm-interchange`).
3. **Surface:** `mgf.vm.interchange.__all__` — the importer
   (`import_ova`), exporter (`export_ova`), and the OVF parse layer
   (`parse_ovf`, `OVFDescriptor`). Output is `mgf.vm.core.VmSpec`.
4. **Bootstrap your app** with mgf-common first — see
   [mgf-common/STARTHERE.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/STARTHERE.md).
5. **Adopt the federation contract** — file your
   `MGF_STANDARDS_CONFORMANCE.md` per
   [DOC-15](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DOCUMENTATION.md).
6. **Run** `mgf-common catch-up` periodically to verify
   federation drift; see [FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md) §6.

---

## For contributors

See [CONTRIBUTING.md](CONTRIBUTING.md). Standards are inherited
from [mgf-common](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/).
This library parses hostile input — keep the `defusedxml` (SH-03)
and safe-tar (SH-04 / SC-15) guards intact.

---

## Quick links

| Resource | Where |
|---|---|
| Library purpose | [README.md](README.md) |
| What it depends on / who depends on it | [DEPS.md](DEPS.md) |
| Release notes | [CHANGELOG.md](CHANGELOG.md) |
| Security posture | [SECURITY.md](SECURITY.md) |
| Conformance ledger | [docs/inprogress/MGF_STANDARDS_CONFORMANCE.md](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md) |
| Federation contract | [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md) |
| Cross-project standards | [mgf-standard/docs/standards/](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/) |
