"""Abstract base class for Git provider adapters."""

import abc
from typing import Any

from app.git.types import ConnectionStatus, ProviderKind


class GitProvider(abc.ABC):
    """Provider API adapter for remote Git operations.

    This abstraction is separate from :class:`~app.git.operations.GitOperations`,
    which handles local Git subprocess workflows.
    """

    @abc.abstractmethod
    def get_kind(self) -> ProviderKind:
        """Return the provider kind identifier."""

    @abc.abstractmethod
    async def validate_connection(
        self, git_url: str, credential_id: str
    ) -> ConnectionStatus:
        """Validate that the given credential can access *git_url*.

        Returns a :class:`ConnectionStatus` indicating the result.
        """

    @abc.abstractmethod
    async def list_repositories(self, credential_id: str) -> list[dict[str, Any]]:
        """List repositories accessible with *credential_id*."""

    @abc.abstractmethod
    async def create_deploy_key(
        self, git_url: str, public_key: str
    ) -> str:
        """Register a deploy key on the remote provider.

        Returns the provider-side deploy key ID.
        """

    @abc.abstractmethod
    async def delete_deploy_key(self, git_url: str, deploy_key_id: str) -> None:
        """Remove a previously registered deploy key."""

    @abc.abstractmethod
    async def get_default_branch(self, git_url: str, credential_id: str) -> str:
        """Return the default branch name for the repository at *git_url*."""