"""`mgf-fed test` subcommand — federation test-supervisor frontend.

Per ``docs/standards/TESTING.md`` §19, the federation's test
supervisor (TS-22..TS-27) is the published sibling library
``mgf-test-supervisor``. This subcommand is a thin shim that
delegates to it. Users have two equivalent invocations:

  - ``mgf-test-supervisor --tier 0`` (the canonical CLI shipped
    by the supervisor itself; also available as ``mtest``)
  - ``mgf-fed test --tier 0`` (this subcommand)

Both end up calling :func:`mgf.test_supervisor.__main__.main`, so
the flag surface + exit codes + behaviour are identical. This
subcommand exists so users with ``mgf-common`` on their PATH
discover the supervisor via the canonical ``mgf-common --help``
listing, alongside ``doctor`` / ``catch-up`` / ``federation-sync``
/ ``agents`` / etc.

The supervisor itself is pure-stdlib (TS-23) so this shim's only
job is import + dispatch. The shim MUST stay trivial — heavy
lifting belongs in ``mgf.test_supervisor``.

Pre-2026-05-26 versions of this file walked up from CWD looking
for ``scripts/_mtest/__init__.py``. That pattern matched the
federation's earlier copy-paste discipline (each sibling shipped
its own copy in ``scripts/_mtest/``). Extraction to
``mgf-test-supervisor`` v0.1.0 retired that pattern: the supervisor
is now ONE installable library, and adopters delete their
in-tree copies.
"""

from __future__ import annotations

import sys
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    import argparse


def add_test_args(parser: argparse.ArgumentParser) -> None:
    """Register the ``test`` subcommand's args.

    Since the underlying supervisor's argparse setup is rich
    (--tier, --budget, --skip-quarantined, --resume, --self-check,
    --report, --quarantine, etc.), we don't try to mirror it here.
    Instead we accept ``REMAINDER`` and pass everything through.
    The supervisor's own ``--help`` is the source of truth for the
    flag surface.
    """
    parser.add_argument(
        "supervisor_args",
        nargs="*",  # `*` not `argparse.REMAINDER` so `--help` reaches the supervisor
        help=(
            "Arguments forwarded verbatim to the supervisor. Run "
            "`mgf-fed test -- --help` for the supervisor's "
            "full flag surface (--tier N | N-M, --budget T, "
            "--skip-quarantined, --resume, --fail-fast, "
            "--self-check, --report, --quarantine, --verbose)."
        ),
    )


def run_test(args: argparse.Namespace) -> int:
    """Dispatch to the installed mgf-test-supervisor library."""
    try:
        from mgf.test_supervisor.__main__ import main
    except ImportError:
        print(
            "error: `mgf-test-supervisor` is not installed.\n\n"
            "The federation test supervisor lives in the published "
            "sibling library `mgf-test-supervisor`. Install it as a "
            "dev dep:\n\n"
            "    uv add --dev mgf-test-supervisor\n\n"
            "Or, until PyPI publish, from Codeberg:\n\n"
            '    uv add --dev "mgf-test-supervisor @ '
            'git+ssh://git@codeberg.org/magogi-admin/mgf-test-supervisor.git"\n\n'
            "See `mgf-standard/docs/recipes/test-supervisor-adoption.md` for the "
            "full adoption recipe.",
            file=sys.stderr,
        )
        return 2

    return main(argv=list(args.supervisor_args))
