# mgf-vm-interchange

> **OVA / OVF import-export sibling library for the Magogi Foundation
> distributed vm-vmanager-app.** Parse an `.ova`, extract the OVF spec
> + disk images, translate to engine-neutral `VmSpec`. And the reverse:
> export a `VmSpec` + disks to a portable `.ova`.

| Field | Value |
|---|---|
| **Status** | Pre-`0.1.0`. Extracted per D-C9. |
| **Federation sibling.** | Depends on `mgf-common` + `mgf-vm-core` + `defusedxml`. |
| **Conformance level.** | **L2 — Standard.** Per-rule ledger: [`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md). |
| **License.** | MIT. |
| **Python.** | 3.11 / 3.12 / 3.13. |

---

## Where the docs live

> **`vm-vmanager-docs`** — `~/PycharmProjects/vm-vmanager-docs/` ·
> Codeberg: `vm-vmanager-docs`

| What | Where |
|---|---|
| Why this is its own sibling (D-C9) | `vm-vmanager-docs/DECISIONS.md` |
| Architecture (registry consumer) | `vm-vmanager-docs/ARCHITECTURE.md` §8 (registry is the cross-platform backbone) |
| Roadmap (Phase 0 Stream F → consumed by CP in Phase 2) | `vm-vmanager-docs/ROADMAP.md` |

---

## What this library is — and why it's a sibling

OVA/OVF is a **portable, vendor-neutral VM packaging format** that
exists outside any one hypervisor. Parsing it well is a real,
reusable capability — incident response tools, migration tools,
cloud-image bakers all want it.

That makes it a sibling per D-C9: lifted out of the old vm-vmanager-app
interchange subsystem, consumed by `vm-vmanager-control-plane`
(for `vmanager image import file.ova`) and available to anyone
else.

## What this library contains

(Phase 0 — sibling extraction from `mgf-vm/src/mgf/vm/interchange/`.)

```
src/mgf/vm/interchange/
├── __init__.py
├── py.typed
├── ova/                 # tar (un)packing with safe-tar discipline (SH-04)
├── ovf/                 # OVF XML parse/render via defusedxml (SH-03)
├── translate.py         # OVF spec ↔ mgf.vm.core.VmSpec
└── exceptions.py        # typed errors at the import/export seam
```

---

## What this library does NOT contain

- **No VM driving.** Translation is to/from `VmSpec`; instantiating
  is the consumer's job (via the SDK + adapters).
- **No registry storage.** Blobs go to the registry's S3 backend
  (`vm-vmanager-control-plane.ImageRegistry`); this library handles
  format conversion, not bytes-at-rest.

---

## Install

```bash
pip install mgf-vm-interchange
```

## Develop

```bash
cd ~/PycharmProjects/mgf_vm_interchange
uv venv --python 3.12
uv sync --extra dev
uv run pytest -q
uv run mypy --strict src/
uv run ruff check src tests
uv run lint-imports
```

## Federation context

Sibling library. Per discipline: `USERS.md`, `STANDARDS_NOTE.md`,
`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`.

Security: parses OVF from attacker-controlled input. `defusedxml`
mandatory (SH-03). OVA tar extraction validates paths (SC-15).
