"""FileOrigin registration and query wrappers.

Registration (``register_origin`` / ``unregister_origin``) wraps
``FreeCADGui.addOrigin()`` / ``removeOrigin()`` with validation.

Query functions (``list_origins``, ``active_origin``, etc.) route
through the ``kcsdk`` C++ module.  The kcsdk module is required for
query operations.
"""

import FreeCAD

try:
    import kcsdk as _kcsdk
except ImportError:
    _kcsdk = None

_REQUIRED_METHODS = ("id", "name", "type", "ownsDocument")


def _gui():
    """Lazy import of FreeCADGui (not available in console mode)."""
    import FreeCADGui

    return FreeCADGui


def _require_kcsdk():
    if _kcsdk is None:
        raise RuntimeError(
            "kcsdk module not available. "
            "The kindred_sdk requires the kcsdk C++ module (libKCSDK)."
        )


def register_origin(origin):
    """Register a FileOrigin with FreeCADGui.

    *origin* must be a Python object implementing at least ``id()``,
    ``name()``, ``type()``, and ``ownsDocument(doc)`` methods.
    """
    missing = [m for m in _REQUIRED_METHODS if not hasattr(origin, m)]
    if missing:
        raise TypeError(f"origin is missing required methods: {', '.join(missing)}")

    try:
        _gui().addOrigin(origin)
        FreeCAD.Console.PrintLog(f"kindred_sdk: Registered origin '{origin.id()}'\n")
    except Exception as e:
        FreeCAD.Console.PrintWarning(f"kindred_sdk: Failed to register origin: {e}\n")


def unregister_origin(origin):
    """Remove a previously registered FileOrigin."""
    try:
        _gui().removeOrigin(origin)
        FreeCAD.Console.PrintLog(f"kindred_sdk: Unregistered origin '{origin.id()}'\n")
    except Exception as e:
        FreeCAD.Console.PrintWarning(f"kindred_sdk: Failed to unregister origin: {e}\n")


def list_origins():
    """Return IDs of all registered origins.

    Returns
    -------
    list[str]
        Origin IDs (always includes ``"local"``).
    """
    _require_kcsdk()
    try:
        return _kcsdk.list_origins()
    except Exception as e:
        FreeCAD.Console.PrintWarning(f"kindred_sdk: list_origins failed: {e}\n")
        return []


def active_origin():
    """Return info about the currently active origin.

    Returns
    -------
    dict or None
        Origin info dict with keys: ``id``, ``name``, ``nickname``,
        ``type``, ``tracksExternally``, ``requiresAuthentication``,
        ``supportsRevisions``, ``supportsBOM``, ``supportsPartNumbers``,
        ``connectionState``.
    """
    _require_kcsdk()
    try:
        return _kcsdk.active_origin()
    except Exception as e:
        FreeCAD.Console.PrintWarning(f"kindred_sdk: active_origin failed: {e}\n")
        return None


def set_active_origin(origin_id):
    """Set the active origin by ID.

    Parameters
    ----------
    origin_id : str
        The origin ID to activate.

    Returns
    -------
    bool
        True if the origin was found and activated.
    """
    _require_kcsdk()
    try:
        return _kcsdk.set_active_origin(origin_id)
    except Exception as e:
        FreeCAD.Console.PrintWarning(f"kindred_sdk: set_active_origin failed: {e}\n")
        return False


def get_origin(origin_id):
    """Get info about a specific origin by ID.

    Parameters
    ----------
    origin_id : str
        The origin ID to look up.

    Returns
    -------
    dict or None
        Origin info dict, or None if not found.
    """
    _require_kcsdk()
    try:
        return _kcsdk.get_origin(origin_id)
    except Exception as e:
        FreeCAD.Console.PrintWarning(f"kindred_sdk: get_origin failed: {e}\n")
        return None