"""Storage provider protocol — unified interface for external storage backends."""

from __future__ import annotations

from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable

if TYPE_CHECKING:
    from grover.models.internal.results import FileOperationResult, FileSearchResult


@runtime_checkable
class StorageProvider(Protocol):
    """External storage operations — disk I/O, queries, and reconciliation.

    Handles content I/O, file operations, metadata, queries (glob/grep/tree),
    and DB-storage reconciliation for an external storage backend (e.g. local
    disk). When ``storage_provider`` is ``None`` on ``DatabaseFileSystem``,
    all content lives in the DB content column.
    """

    # Core content operations
    async def read_content(self, path: str) -> str | None: ...

    async def write_content(self, path: str, content: str) -> None: ...

    async def delete_content(self, path: str) -> None: ...

    async def move_content(self, src: str, dest: str) -> None: ...

    async def copy_content(self, src: str, dest: str) -> None: ...

    async def exists(self, path: str) -> bool: ...

    async def mkdir(self, path: str, parents: bool = True) -> None: ...

    async def get_info(self, path: str) -> FileOperationResult: ...

    # Storage-level queries (disk glob/grep/tree/list_dir)
    async def storage_glob(self, pattern: str, path: str = "/") -> FileSearchResult: ...

    async def storage_grep(self, pattern: str, path: str = "/", **kwargs: Any) -> FileSearchResult: ...

    async def storage_tree(self, path: str = "/", max_depth: int | None = None) -> FileSearchResult: ...

    async def storage_list_dir(self, path: str) -> FileSearchResult: ...

    # Reconciliation (sync external storage with DB)
    async def reconcile(self, **kwargs: Any) -> FileOperationResult: ...


# Backward-compat aliases
SupportsStorageQueries = StorageProvider
SupportsStorageReconcile = StorageProvider
