"""``mgf-fed federation-sync`` — print the federation-sync message.

Closes [PAPER-57](../../../../FEEDBACK.md). The federation-sync message
is the canonical "please run before next merge" notification that
goes from the federation maintainer to consumer projects whenever
mgf-common crosses a MINOR. Pre-PAPER-57 the message was hand-crafted
in chat, and the literal pin window in the body went stale the moment
mgf-common shipped a new MINOR (consumers reading the verbatim message
on 2026-05-18 saw ``>=0.37,<0.38`` while mgf-common was at ``0.38.0``).

The fix: parametrize the pin window from ``mgf.common.__version__`` at
the moment the message is generated. Now whoever sends the message
(maintainer, AI agent, automation) invokes
``mgf-fed federation-sync`` and pastes the output — the pin window
is always live.

The shape is deliberately one-shot: no flags, no template variables,
no overrides. Live ``__version__`` → live pin window → standard
message body. If the message needs to evolve, edit the constant at
the bottom of this module and ship a new mgf-common minor.
"""

from __future__ import annotations

from typing import TYPE_CHECKING

import mgf.common
from mgf.common.cli import EXIT_SUCCESS

from mgf.fed.cli._version_pin import current_pin_window

if TYPE_CHECKING:
    import argparse


_MESSAGE_TEMPLATE = """\
mgf-common federation sync — please run before next merge

mgf-common is at v{version}. To stay in sync with the federation:

1. Bump your mgf-common pin in `pyproject.toml`:

    "mgf-common{pin}"

2. Re-resolve the dep tree:

    uv sync   # or `pip install -e '.[dev]'`

3. Run `mgf-fed catch-up` to verify the project still passes the
   federation contract (DOC-16 / DOC-17) under the new pin. If any
   findings come back, `mgf-fed catch-up --apply` covers the
   mechanical fixes; the rest are normal PR review surface.

4. If your project also depends on federation siblings (mgf-http,
   mgf-fastapi, mgf-sqlalchemy, mgf-alembic, mgf-apiprobe, mgf-django),
   their pin walks are tracked in the per-cycle aggregated cutover
   doc at `docs/cutover/federation-v<X.Y>.md` in this repo. Read it
   before walking sibling pins — the table is the 30-second triage
   (PAPER-35).

Questions / friction / objections: file via the FEEDBACK.md process —
run `mgf-fed feedback-howto` to see the submission template.
"""


def add_federation_sync_args(_subparser: argparse.ArgumentParser) -> None:
    """Register flags for ``mgf-fed federation-sync``.

    Currently no flags — the subcommand is a pure print of the
    templated sync message. Flag-less keeps the surface stable; any
    future variation (e.g., ``--for-sibling=<name>`` if siblings
    grow distinct sync templates) is an additive change.
    """
    # No flags today; parser is shaped for future expansion.


def run_federation_sync(_args: argparse.Namespace) -> int:
    """Print the federation-sync message with the live pin window.

    The pin window is computed from :data:`mgf.common.__version__`
    via :func:`mgf.fed.cli._version_pin.current_pin_window`, so
    the output is always in lockstep with the installed release.

    Returns :data:`mgf.common.cli.EXIT_SUCCESS` unconditionally — this is
    a print command with no failure modes.
    """
    print(
        _MESSAGE_TEMPLATE.format(
            version=mgf.common.__version__,
            pin=current_pin_window(),
        ),
        end="",
    )
    return EXIT_SUCCESS


__all__ = [
    "add_federation_sync_args",
    "run_federation_sync",
]
