"""``mgf-fed sync-prompt`` — print the federation sync/conformance prompt.

The federation **sync prompt** is the canonical, copy-paste procedure an AI
agent (or human) follows to bring a federation project into conformance with
the *current* standards — it's the body the ``/sync`` slash command runs. It
leads with the resolve-don't-copy entry points (``mgf-fed agents`` /
``standards`` / ``catch-up``) and classifies the project as NEW / IN-SYNC /
OUT-OF-SYNC, so one prompt serves every onboarding state.

The prompt is the ``federation-sync-prompt`` recipe in the
``mgf-standard`` sibling (the federation's standards + process source of
truth, a runtime dependency of ``mgf-common``). It ships as wheel data there
and is resolved through ``mgf.standard.read_recipe()`` — so the single
source of truth is the installed package, not a hand-copied command body that
drifts. This mirrors how ``mgf-fed standards`` resolves the corpus through
``mgf.standard.standards_dir()``: we reach only the documented public
seam, never the private ``_recipes`` data dir, keeping the closed-box rule
intact.

One-shot: no flags. Resolve → print. If ``mgf-standard`` is missing or too
old to carry the recipes seam (it landed in 0.1.3), print an actionable error
pointing at the sibling checkout / Codeberg copy.
"""

from __future__ import annotations

import sys
from typing import TYPE_CHECKING

from mgf.common.cli import EXIT_SUCCESS, EXIT_UNKNOWN

if TYPE_CHECKING:
    import argparse


# The recipe file stem in mgf-standard's docs/recipes/ corpus.
_RECIPE = "federation-sync-prompt"


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

    Currently no flags — the subcommand is a pure print of the recipe
    resolved from ``mgf-standard``. Flag-less keeps the surface stable;
    any future variation (e.g. ``--paths`` to print the resolved file path,
    mirroring ``mgf-fed standards --paths``) is an additive change.
    """
    # No flags today; parser is shaped for future expansion.


def run_sync_prompt(_args: argparse.Namespace) -> int:
    """Print the federation sync/conformance prompt.

    Resolves the ``federation-sync-prompt`` recipe through
    ``mgf.standard.read_recipe`` so the output is always the version this
    project pins. Returns :data:`mgf.common.cli.EXIT_SUCCESS` on success, or
    :data:`mgf.common.cli.EXIT_UNKNOWN` with an actionable stderr message if
    the recipe cannot be resolved.
    """
    text = _resolve_recipe()
    if text is None:
        print(
            "error: the federation sync prompt is not installed. It ships in "
            "the `mgf-standard` extra as the `federation-sync-prompt` "
            "recipe — install it:\n"
            "    pip install -U 'mgf-common[standards]'   "
            "(or: uv add 'mgf-common[standards]')\n"
            "The corpus is an optional, Codeberg-only extra; a plain "
            "mgf-common install does not carry it. Editable-sibling "
            "alternative: read "
            "../mgf-standard/docs/recipes/federation-sync-prompt.md.",
            file=sys.stderr,
        )
        return EXIT_UNKNOWN

    print(text, end="" if text.endswith("\n") else "\n")
    return EXIT_SUCCESS


def _resolve_recipe() -> str | None:
    """Return the sync-prompt recipe text, or ``None`` if unresolvable.

    Delegates to :func:`mgf.standard.read_recipe` — the public seam over
    the recipes corpus shipped as ``mgf-standard`` wheel data. Returns
    ``None`` if ``mgf-standard`` is missing, too old to carry the recipes
    seam (no ``read_recipe`` — pre-0.1.3), or the data cannot be located, so
    the caller can print an actionable error.
    """
    try:
        import mgf.standard
    except (ModuleNotFoundError, ImportError):
        return None
    read_recipe = getattr(mgf.standard, "read_recipe", None)
    if read_recipe is None:
        return None
    try:
        result = read_recipe(_RECIPE)
    except (FileNotFoundError, ValueError, OSError):
        return None
    return result if isinstance(result, str) else None


__all__ = ["add_sync_prompt_args", "run_sync_prompt"]
