"""Snapshot flag encoding.

Extracted from ``mgf.vm.operations.snapshot`` (Wave 1). Pure string
transformation — no provider dispatch — so it lives in core. The
``create``/``revert``/``delete`` provider-dispatch bodies stay in the
adapter.
"""

from __future__ import annotations


def encode_flags(description: str, *, quiesce: bool, external: bool) -> str:
    """Prefix the description with a flags marker.

    Encoding keeps provider compatibility while a follow-up threads real
    flags through the contract without a breaking change. Format::

        [vmanager:quiesce,external] user description here

    The libvirt adapter parses this prefix off and converts it to real
    libvirt flags; a mock backend simply stores it as part of the
    snapshot's ``description`` field.
    """
    flags: list[str] = []
    if quiesce:
        flags.append("quiesce")
    if external:
        flags.append("external")
    if not flags:
        return description
    prefix = f"[vmanager:{','.join(flags)}]"
    if description:
        return f"{prefix} {description}"
    return prefix


__all__ = ["encode_flags"]
