# mgf-example-app

The "second consumer" reference package for `mgf-common`. v0.4 Phase G3.

## Why this exists

`mgf-common` is a library, not an application. Library APIs are
best validated by **a real consumer** — not by the library's own
self-tests, which are inevitably shaped to confirm what the
library author wrote.

This package is a real, packaged consumer of `mgf-common`. It
demonstrates the canonical v0.4 ergonomic shape:

- `bootstrap()` for one-call wiring of identity + observability.
- `AppSettings(BaseAppSettings)` composing `mgf.common.settings.MgfSettings`
  as a sub-field — the canonical pattern from
  [`docs/reference/settings.md`](../docs/reference/settings.md).
- A custom CLI subcommand registered via
  `mgf.common.cli.register_cli_subcommand` (Phase E).
- `bootstrap_for_test()` in the test suite (Phase F).

Its tests are the consumer-side regression smoke for `mgf-common`
releases — when `mgf-common` cuts a new version, the compat
matrix (Phase G4) runs `example-app`'s tests against the new
wheel before the release is tagged.

## Layout

```
example_app/
├── pyproject.toml              # Standalone package config (uv path source for mgf-common)
├── README.md                   # This file
├── src/
│   └── example_app/
│       ├── __init__.py
│       ├── __main__.py         # `python -m example_app`
│       ├── cli.py              # Custom subcommand + main()
│       └── settings.py         # AppSettings composing MgfSettings
└── tests/
    └── test_smoke.py           # End-to-end consumer-side smoke
```

## Usage

```bash
# Set up
cd example_app
uv pip install --python ../.venv/bin/python -e .[dev]

# Run the CLI
uv run --python ../.venv/bin/python example-app greet --name Alice
# → "Hello, Alice!"

# The mgf-common diagnostic subcommands are reachable too:
uv run --python ../.venv/bin/python example-app doctor
uv run --python ../.venv/bin/python example-app explain

# Run the test suite
cd example_app && uv run pytest
```

## What this package is NOT

- **Not on PyPI.** `[project.classifiers]` carries
  `Private :: Do Not Upload`. The package exists in this repo;
  consumers don't depend on it.
- **Not a kitchen-sink demo.** Domain logic is intentionally
  minimal — just enough to exercise the v0.4 public surface.
  See [`examples/`](../examples/) for the layered didactic
  examples.
- **Not a starter template.** That's a future addition (a
  cookiecutter or `mgf-common new-project` subcommand). This
  package is a fixed reference, not a template.

## When to update

Update this package whenever `mgf-common` ships a new public
surface that consumers would naturally want. The package's tests
are the canonical "does the public API actually work?" check.
