"""Version discovery -- the repo-root ``VERSION`` file is the single source
of truth for the release version ("everything from here on out is vX.Y.Z"
= bump ``VERSION`` and commit).

The plugin lives at ``<repo>/gateway-plugin`` (installed into
``~/.hermes/plugins/iris`` as a symlink in production), so the ``VERSION``
file is one directory up. The value is advertised to the app in
``hello.ack`` (``server_caps.app_version``) so the app can show which
gateway version it is talking to.
"""

from __future__ import annotations

from pathlib import Path

_FALLBACK = "unknown"


def plugin_version() -> str:
    """The release version from ``<repo>/VERSION``, or ``"unknown"``."""
    candidate = Path(__file__).resolve().parent.parent / "VERSION"
    try:
        version = candidate.read_text().strip()
    except OSError:
        return _FALLBACK
    return version or _FALLBACK