"""``mgf.common.cli`` — top-level CLI helpers.

See: ``docs/reference/cli.md``.

Closes the closed-box leak around CLI exit-code policy + the
boilerplate top-level ``except AppError`` ladder.

Four surfaces:

  - **Exit-code constants** — :data:`EXIT_SUCCESS`,
    :data:`EXIT_CONFIG_ERROR`, :data:`EXIT_OPERATION_ERROR`,
    :data:`EXIT_GUEST_ERROR`, :data:`EXIT_ENVIRONMENT_ERROR`,
    :data:`EXIT_PROVIDER_ERROR`, :data:`EXIT_VAULT_ERROR`,
    :data:`EXIT_APP_ERROR`, :data:`EXIT_UNKNOWN`. Stable across
    the 0.x window — any bump is a breaking change (rule API-04).

  - **Translator** — :func:`run_and_translate` (call-style),
    :func:`translate_exceptions` (decorator-style),
    :func:`main_entry` (one-liner that also calls ``sys.exit``).
    All three route untyped exceptions through
    :func:`mgf.common.observability.report_now` so the crash
    file lands on disk before the process exits.

  - **Settings provenance** — :func:`field_provenance`,
    :func:`env_vars_known_to_mgf`, :class:`FieldSource`,
    :data:`SourceKind`. The same shim that powers
    ``mgf-common explain``, exposed publicly so consumers can
    build their own settings-debug UIs (admin pages, support
    tooling) without reaching past us into pydantic-settings.
    Promoted from private in v0.4 Phase A.

  - **Subcommand registry** — :func:`register_cli_subcommand`
    (canonical) / :func:`subcommand` (short alias),
    :func:`unregister_cli_subcommand`, :class:`CliSubcommand`,
    :func:`build_cli`. Consumers register their own subcommands
    and build a ready-to-run argparse parser via :func:`build_cli`
    without re-implementing exit-code translation. Added in v0.4
    Phase E; the ``subcommand`` short alias closes FEEDBACK V04-02
    in v0.4.1. As of v0.47 the library registers NO built-ins of
    its own (the former ``explain`` / ``doctor`` / … moved to
    ``mgf-fed[cli]``), so ``build_cli()`` returns an empty parser
    until a consumer registers subcommands.

Phase 5 of the v0.3 closed-box reshape introduced the first two;
Phase A of the v0.4 reshape added the third; Phase E added the
fourth.

Drop-in usage::

    from mgf.common.cli import run_and_translate, EXIT_SUCCESS

    def main(argv: list[str]) -> int:
        # ... your real CLI logic; raise typed exceptions as needed
        return EXIT_SUCCESS

    if __name__ == "__main__":
        import sys
        sys.exit(run_and_translate(main, sys.argv[1:]))
"""

from __future__ import annotations

# v0.47 federation reorg: the end-user subcommands (explain /
# validate / doctor / migrate / standards / agents / catch-up / …)
# moved out of the library into mgf-fed (`pip install
# 'mgf-fed[cli]'`). mgf-common is now a pure importable library —
# it ships the CLI *infrastructure* (exit codes, the translator,
# field-provenance, the subcommand registry) but registers NO
# built-in subcommands. `build_cli()` therefore returns an empty
# parser until a consumer registers its own subcommands; the four
# former built-ins are no longer pre-registered here.
from mgf.common.cli._exit_codes import (
    EXIT_APP_ERROR,
    EXIT_CONFIG_ERROR,
    EXIT_ENVIRONMENT_ERROR,
    EXIT_GUEST_ERROR,
    EXIT_OPERATION_ERROR,
    EXIT_PROVIDER_ERROR,
    EXIT_SUCCESS,
    EXIT_UNKNOWN,
    EXIT_VAULT_ERROR,
)
from mgf.common.cli._handler import (
    main_entry,
    run_and_translate,
    translate_exceptions,
)
from mgf.common.cli._provenance import (
    FieldSource,
    SourceKind,
    env_vars_known_to_mgf,
    field_provenance,
)
from mgf.common.cli._subcommand_registry import (
    CliSubcommand,
    build_cli,
    dispatch,
    register_cli_subcommand,
    subcommand,
    unregister_cli_subcommand,
)

__all__ = [
    "EXIT_APP_ERROR",
    "EXIT_CONFIG_ERROR",
    "EXIT_ENVIRONMENT_ERROR",
    "EXIT_GUEST_ERROR",
    "EXIT_OPERATION_ERROR",
    "EXIT_PROVIDER_ERROR",
    "EXIT_SUCCESS",
    "EXIT_UNKNOWN",
    "EXIT_VAULT_ERROR",
    "CliSubcommand",
    "FieldSource",
    "SourceKind",
    "build_cli",
    "dispatch",
    "env_vars_known_to_mgf",
    "field_provenance",
    "main_entry",
    "register_cli_subcommand",
    "run_and_translate",
    "subcommand",
    "translate_exceptions",
    "unregister_cli_subcommand",
]
