# RepoSync/core/base_vcs_client.py

"""
Abstract Base Class for Version Control System (VCS) clients.

This module defines the interface that all VCS clients (like Gitea, GitHub, etc.)
must implement to be compatible with the RepoSync tool.
"""

from abc import ABC, abstractmethod

class BaseVCSClient(ABC):
    """
    An abstract base class that defines the common interface for interacting
    with a version control system's API.
    """

    def __init__(self, api_url: str, token: str):
        """
        Initializes the client with the necessary API URL and access token.

        Args:
            api_url: The base URL of the VCS API endpoint.
            token: The personal access token for authentication.
        """
        self.api_url = api_url.rstrip('/')
        self.token = token
        self.headers = {
            "Authorization": f"token {self.token}",
            "Content-Type": "application/json",
        }

    @abstractmethod
    def get_repositories(self) -> list[dict]:
        """
        Retrieves a list of all repositories accessible by the user.

        Returns:
            A list of dictionaries, where each dictionary represents a repository
            and must contain at least 'name', 'ssh_url', 'http_url',
            and 'description' keys.
        """
        pass

    @abstractmethod
    def get_repository(self, repo_name: str) -> dict | None:
        """
        Retrieves a single repository by its name.

        Args:
            repo_name: The name of the repository to find.

        Returns:
            A dictionary representing the repository if found, otherwise None.
        """
        pass

    @abstractmethod
    def create_repository(self, name: str, description: str = "") -> dict:
        """
        Creates a new repository on the VCS platform.

        Args:
            name: The name for the new repository.
            description: A short description for the new repository.

        Returns:
            A dictionary representing the newly created repository.
        """
        pass