letsbe-sysadmin/app/playwright_scenarios/__init__.py

"""Playwright scenario registry.

This module provides the central registry for all available Playwright scenarios.
Scenarios are registered at import time and looked up by name during execution.

Usage:
    from app.playwright_scenarios import get_scenario, list_scenarios

    # Get a specific scenario
    scenario = get_scenario("nextcloud_initial_setup")

    # List all available scenarios
    available = list_scenarios()
"""

from typing import Optional

from app.playwright_scenarios.base import BaseScenario, ScenarioOptions, ScenarioResult

# Registry mapping scenario names to scenario classes
_SCENARIO_REGISTRY: dict[str, type[BaseScenario]] = {}


def register_scenario(scenario_class: type[BaseScenario]) -> type[BaseScenario]:
    """Decorator to register a scenario class.

    Usage:
        @register_scenario
        class MyScenario(BaseScenario):
            ...

    Args:
        scenario_class: The scenario class to register

    Returns:
        The scenario class (unchanged)

    Raises:
        ValueError: If a scenario with the same name is already registered
    """
    # Create instance to get the name
    instance = scenario_class()
    name = instance.name

    if name in _SCENARIO_REGISTRY:
        raise ValueError(
            f"Scenario '{name}' is already registered by {_SCENARIO_REGISTRY[name].__name__}"
        )

    _SCENARIO_REGISTRY[name] = scenario_class
    return scenario_class


def get_scenario(name: str) -> Optional[BaseScenario]:
    """Get a scenario instance by name.

    Args:
        name: The scenario name (e.g., 'nextcloud_initial_setup')

    Returns:
        Scenario instance if found, None otherwise
    """
    scenario_class = _SCENARIO_REGISTRY.get(name)
    if scenario_class is None:
        return None
    return scenario_class()


def list_scenarios() -> list[dict[str, str]]:
    """List all registered scenarios with their metadata.

    Returns:
        List of dictionaries with scenario name, description, and required inputs
    """
    result = []
    for name, scenario_class in sorted(_SCENARIO_REGISTRY.items()):
        instance = scenario_class()
        result.append({
            "name": name,
            "description": instance.description,
            "required_inputs": instance.required_inputs,
            "optional_inputs": instance.optional_inputs,
        })
    return result


def get_scenario_names() -> list[str]:
    """Get list of all registered scenario names.

    Returns:
        Sorted list of scenario names
    """
    return sorted(_SCENARIO_REGISTRY.keys())


# Import scenario modules to trigger registration
# Add imports here as new scenarios are created:
from app.playwright_scenarios import echo  # noqa: F401
from app.playwright_scenarios.nextcloud import initial_setup  # noqa: F401

__all__ = [
    "BaseScenario",
    "ScenarioOptions",
    "ScenarioResult",
    "register_scenario",
    "get_scenario",
    "list_scenarios",
    "get_scenario_names",
]