"""FileSystemPort - Port for file system operations.

Contract: CNT-T1-PRT-002
Traceability: UC-001, UC-004, UC-005
"""

from pathlib import Path
from typing import Protocol


class FileSystemPort(Protocol):
    """Port interface for file system operations.

    This protocol defines the contract for file system interactions.
    Implementations should handle encoding, permissions, and error handling.
    """

    def read_file(self, path: Path) -> str:
        """Read file contents.

        Args:
            path: Path to the file

        Returns:
            File contents as string

        Raises:
            FileNotFoundError: If file does not exist
        """
        ...

    def write_file(self, path: Path, content: str) -> None:
        """Write content to file.

        Args:
            path: Path to the file
            content: Content to write
        """
        ...

    def file_exists(self, path: Path) -> bool:
        """Check if file exists.

        Args:
            path: Path to check

        Returns:
            True if file exists
        """
        ...

    def directory_exists(self, path: Path) -> bool:
        """Check if directory exists.

        Args:
            path: Path to check

        Returns:
            True if directory exists
        """
        ...

    def list_directory(self, path: Path, pattern: str = "*") -> list[Path]:
        """List directory contents matching pattern.

        Args:
            path: Directory path
            pattern: Glob pattern (default: "*")

        Returns:
            List of matching paths
        """
        ...

    def ensure_directory(self, path: Path) -> None:
        """Ensure directory exists, creating if necessary.

        Args:
            path: Directory path to ensure exists
        """
        ...
