refactor(automations): vertical-slice actions and triggers by domain

surfsense_backend/app/automations/triggers/__init__.py

@@ -0,0 +1,20 @@
+"""Triggers domain: registry surface + built-in trigger packages.
+
+Each trigger lives in its own subpackage (``manual/``, ``schedule/``, ...) and
+self-registers at import time via its ``definition`` module.
+"""
+
+from __future__ import annotations
+
+from .store import all_triggers, get_trigger, register_trigger
+from .types import TriggerDefinition
+
+__all__ = [
+    "TriggerDefinition",
+    "all_triggers",
+    "get_trigger",
+    "register_trigger",
+]
+
+# Built-in triggers self-register at import time.
+from . import manual, schedule  # noqa: E402, F401

surfsense_backend/app/automations/triggers/manual/__init__.py

@@ -0,0 +1,10 @@
+"""``manual`` trigger: fired by a user clicking ``Run now``."""
+
+from __future__ import annotations
+
+from .params import ManualTriggerParams
+
+__all__ = ["ManualTriggerParams"]
+
+# Side-effect: register on the triggers store.
+from . import definition  # noqa: E402, F401

surfsense_backend/app/automations/triggers/manual/definition.py

@@ -0,0 +1,16 @@
+"""``manual`` ``TriggerDefinition`` registration."""
+
+from __future__ import annotations
+
+from ..store import register_trigger
+from ..types import TriggerDefinition
+from .params import ManualTriggerParams
+
+MANUAL_TRIGGER = TriggerDefinition(
+    type="manual",
+    description="Fire on a user-initiated 'Run now' invocation.",
+    params_schema=ManualTriggerParams.model_json_schema(),
+    payload_schema={"type": "object"},
+)
+
+register_trigger(MANUAL_TRIGGER)

surfsense_backend/app/automations/triggers/manual/params.py

@@ -0,0 +1,9 @@
+"""``ManualTriggerParams`` — params for the ``manual`` trigger (empty in v1)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ManualTriggerParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")

surfsense_backend/app/automations/triggers/schedule/__init__.py

@@ -0,0 +1,10 @@
+"""``schedule`` trigger: fired on a cron schedule in a given timezone."""
+
+from __future__ import annotations
+
+from .params import ScheduleTriggerParams
+
+__all__ = ["ScheduleTriggerParams"]
+
+# Side-effect: register on the triggers store.
+from . import definition  # noqa: E402, F401

surfsense_backend/app/automations/triggers/schedule/definition.py

@@ -0,0 +1,20 @@
+"""``schedule`` ``TriggerDefinition`` registration."""
+
+from __future__ import annotations
+
+from ..store import register_trigger
+from ..types import TriggerDefinition
+from .params import ScheduleTriggerParams
+
+SCHEDULE_TRIGGER = TriggerDefinition(
+    type="schedule",
+    description="Fire on a cron schedule in a given timezone.",
+    params_schema=ScheduleTriggerParams.model_json_schema(),
+    payload_schema={
+        "type": "object",
+        "additionalProperties": False,
+        "properties": {},
+    },
+)
+
+register_trigger(SCHEDULE_TRIGGER)

surfsense_backend/app/automations/triggers/schedule/params.py

@@ -0,0 +1,12 @@
+"""``ScheduleTriggerParams`` — params for the ``schedule`` trigger type."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ScheduleTriggerParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    cron: str = Field(..., description="Five-field cron expression.", examples=["0 9 * * 1-5"])
+    timezone: str = Field(..., description="IANA timezone.", examples=["Africa/Kigali"])

surfsense_backend/app/automations/triggers/store.py

@@ -0,0 +1,23 @@
+"""In-memory trigger registry. Populated once at process startup."""
+
+from __future__ import annotations
+
+from .types import TriggerDefinition
+
+_REGISTRY: dict[str, TriggerDefinition] = {}
+
+
+def register_trigger(trigger: TriggerDefinition) -> None:
+    """Register a trigger. Raises on duplicate type."""
+    if trigger.type in _REGISTRY:
+        raise ValueError(f"Trigger already registered: {trigger.type!r}")
+    _REGISTRY[trigger.type] = trigger
+
+
+def get_trigger(trigger_type: str) -> TriggerDefinition | None:
+    return _REGISTRY.get(trigger_type)
+
+
+def all_triggers() -> dict[str, TriggerDefinition]:
+    """Defensive snapshot of the registry."""
+    return dict(_REGISTRY)

surfsense_backend/app/automations/triggers/types.py

@@ -0,0 +1,14 @@
+"""``TriggerDefinition`` dataclass. Declarative; firing is the dispatcher's job."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class TriggerDefinition:
+    type: str
+    description: str
+    params_schema: dict[str, Any]
+    payload_schema: dict[str, Any]