from __future__ import annotations

from typing import Protocol, runtime_checkable

from abcreg import AnnotatedProtocolMeta  # type: ignore[import-untyped]
from fastapi import Request
from starlette.responses import Response


@runtime_checkable
class Action(Protocol, metaclass=AnnotatedProtocolMeta):
    """
    Action: A per-project action provided by a plugin.

    ``project`` is the project path/slug as used in URLs (under PROJECTROOT).
    Subclass this protocol, or register a virtual subclass with ``@Action.register``.
    """

    def action_name(self) -> str: ...

    def action(self, project: str, req: Request | None = None) -> Response | None: ...