# Reference consumer profile — vm-vmanager-app

> **Project:** Desktop / Qt VM-management application
> **Status:** Original reference consumer; carries the longest history of mgf-common adoption.
> **Profile last refreshed:** 2026-05-10

vm-vmanager-app is the consumer many of the cross-cutting standards were
distilled from. It's a Qt-based desktop application that manages
local virtual machines (creation, lifecycle, snapshots, networking,
guest agents). Its shape biases toward:

- Long-running event-loop processes
- Multi-thread + multi-process boundaries (Qt GUI thread, worker
  pools, subprocess runners)
- File-system-heavy state (per-VM config, snapshot trees, vault)
- Local-only operation; no SaaS / multi-tenant requirements
- Strong cross-platform desktop expectations (Linux + macOS +
  Windows)

When the standards docs cite "the reference consumer" with no other
qualifier, vm-vmanager-app is implied.

---

## Shape at a glance

| Concern | vm-vmanager-app's shape |
|---|---|
| Manifest | `pyproject.toml` (PEP 621) |
| Layout | `src/` layout, single distribution |
| Entry point | console-script + Qt GUI launcher |
| Identity | `bootstrap(app_name="vm-vmanager-app", app_version=…)` at startup |
| Logging | mgf-common stdlib formatter + rotating file sink + GUI log-viewer dialog |
| Config | mgf-common `MgfSettings` + per-VM `VersionedFileStore[VMConfig]` |
| Vault | mgf-common encrypted file vault for guest credentials |
| Errors | mgf-common typed-exception hierarchy; surfaces via Qt error-dialog + crash reporter |
| Subprocess | mgf-common `Service` lifecycle + `CommandError` translation |
| Cancellation | mgf-common `CancellationToken` propagated to worker tasks |
| Multi-tenancy | Single-tenant (per-installation identity); no AppContext scoping |
| Web framework | none |
| Tests | pytest + Hypothesis + pytest-qt; mypy strict; ruff; coverage ≥ 85% |

---

## Pattern-by-pattern evidence

### Configuration

vm-vmanager-app uses `MgfSettings` for cross-cutting concerns (logging,
OTel, crash-dir, redaction) and `VersionedFileStore[VMConfig]` for
per-VM persistent state (one file per VM, schema-versioned, with
migration hooks). The `MgfSettings.production()` factory is the
default; staging environments use `MgfSettings.dev()`.

### Logging

`bootstrap()` installs the StreamHandler + RotatingFileHandler stack.
The GUI log-viewer dialog (LG-07 — see `mgf-fed standards LOGGING`)
tails the rotating file; the formatter is the stdlib JSON formatter.
OTel is off by default (no network egress); operators enable it
explicitly for support sessions.

### Error handling

The typed-exception hierarchy maps to:

- `EH-*` category bases (`ConfigError`, `ProviderError`,
  `OperationError`, `GuestError`, `VaultError`, `SchedulerError`,
  `HostEnvironmentError`) for the runtime failure modes
- Concrete leaves like `GuestUnreachableError`, `GuestCommandError`,
  `BootstrapError`, `CancellationError` for the subprocess +
  guest-agent + lifecycle paths

Top-level handlers per the standard:

- CLI entry: `mgf.common.cli.translate_exceptions` + EXIT_* codes
- `sys.excepthook` + threading excepthook + asyncio exception handler
- Qt worker exception pipeline (GUI thread translation, status-bar
  surface, optional crash-report email)

### Subprocess + cancellation

`mgf.common.process.Service` wraps long-running guest agents.
`CommandError` is the translation target for non-zero exits.
`CancellationToken` propagates from the GUI's "stop" button down
through worker tasks; `raise_if_cancelled()` checks at task
boundaries.

### Vault

The encrypted file vault stores guest credentials (SSH passphrases,
API tokens for cloud-VM providers). The `cryptography`-optional
extra is installed; passphrase prompts route through a Qt dialog.

---

## Known non-adoptions

vm-vmanager-app intentionally **does not** adopt:

- **OpenTelemetry exporters in default config.** Network egress is
  opt-in; a fresh install ships with `OtelSettings.exporter=None`.
  Operators enable OTLP when a support session is open.
- **The pytest plugin's `--mgf-bootstrap` fixture for GUI tests.**
  pytest-qt's `qtbot` fixture composes differently; vm-vmanager-app's
  test suite uses a thin wrapper around `bootstrap_for_test()`.
- **HTTP-01 exception hierarchy** (`HttpError`, the per-status
  leaves). vm-vmanager-app doesn't expose HTTP endpoints; the hierarchy
  doesn't apply.
- **CLAUDE.md auto-block kind detection.** vm-vmanager-app pre-dates the
  init-project shape; its `docs/CLAUDE.md` is hand-maintained.

These are documented non-adoptions, not gaps. They're consistent
with the "non-adoption-is-valid" principle in
`docs/standards/principles/non-adoption-is-valid.md`.

---

## Cross-references

- vm-vmanager-app's own repo: <https://codeberg.org/magogi-admin/vm-vmanager-app>
- vm-vmanager-app's `docs/STANDARDS_COMPLIANCE.md` — the consumer-side
  view of which federation standards it adopts + which it doesn't.
- vm-vmanager-app's `docs/COMMON.md` — the day-to-day mgf-common usage
  notes for vm-vmanager-app contributors.
- [`docs/standards/`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/) — the rules these patterns
  realise.
