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: ...