"""Abstract base class for tool adapters."""

from __future__ import annotations

from abc import ABC, abstractmethod

from nestdx.config.schema import ToolConfig
from nestdx.session.models import ToolRun


class ToolAdapter(ABC):
    """Base interface for all tool adapters.

    Each adapter knows how to resolve, validate, and run a specific
    AI coding tool (or a generic CLI command).
    """

    @property
    @abstractmethod
    def name(self) -> str:
        """Tool identifier (e.g., 'claude-code')."""

    @abstractmethod
    def resolve_command(self, config: ToolConfig) -> list[str]:
        """Build the command-line args list to execute."""

    @abstractmethod
    def run(self, config: ToolConfig, extra_args: list[str]) -> ToolRun:
        """Execute the tool interactively and return a ToolRun record."""

    @abstractmethod
    def validate(self) -> bool:
        """Check if the tool binary is installed / available."""

    @property
    def install_hint(self) -> str:
        """Return a helpful installation hint for this tool."""
        return f"Install '{self.name}' and ensure it is on your PATH."
