"""
Backend abstraction for Lazarus Pit cells.

Every backend must implement the same contract so that cells,
teams, and operators do not need to know how a cell is actually running.
"""

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Optional


@dataclass
class BackendResult:
    success: bool
    stdout: str = ""
    stderr: str = ""
    pid: Optional[int] = None
    message: str = ""


class Backend(ABC):
    """Abstract cell backend."""

    name: str = "abstract"

    @abstractmethod
    def spawn(self, cell_id: str, hermes_home: str, command: list, env: Optional[dict] = None) -> BackendResult:
        """Spawn the cell process/environment."""
        ...

    @abstractmethod
    def probe(self, cell_id: str) -> BackendResult:
        """Check if the cell is alive and responsive."""
        ...

    @abstractmethod
    def logs(self, cell_id: str, tail: int = 50) -> BackendResult:
        """Return recent logs from the cell."""
        ...

    @abstractmethod
    def close(self, cell_id: str) -> BackendResult:
        """Gracefully close the cell."""
        ...

    @abstractmethod
    def destroy(self, cell_id: str) -> BackendResult:
        """Forcefully destroy the cell and all runtime state."""
        ...