feat(alerts): run an Ansible playbook on alert firing (task 250)

Rebuilds the deleted NUT/UPS automation as a general alert action: any metric
can drive a playbook run on transition-to-firing.

- models/alerts.py + migration 0014: AlertRule.ansible_action (JSON, admin-only,
  reuses the #546 param shape); AlertEvent.ansible_run_id links a firing event to
  the run it triggered
- core/alerts.py: pure alert_extra_vars() injects steward_alert_* context; on
  ('firing', event) with an action set, schedule _run_ansible_action (deferred
  after commit, same pattern as notifications) — fires once per transition,
  consecutive_failures_required is the debounce; system-triggered AnsibleRun
- alerts/routes.py: admin-only parse/validate of the action (source must be
  configured, playbook must exist); operators keep editing rules, action preserved
- rules_form.html: admin-only 'On firing -> run a playbook' section
- tests: unit for alert_extra_vars; integration drives record_metric to firing
  and asserts a system AnsibleRun ran the playbook with the injected var and the
  event linked to it

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tests/integration/test_alert_ansible_action.py

@@ -0,0 +1,99 @@
+"""Integration: an alert transition-to-firing triggers its Ansible action (task 250).
+
+Drives the full chain against a live Postgres + real Ansible: a breaching metric
+fires the rule, which schedules a system-triggered AnsibleRun that runs a real
+connection:local playbook receiving the injected steward_alert_* context, and the
+firing AlertEvent links to the run.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import textwrap
+import uuid
+
+import pytest
+
+pytestmark = pytest.mark.integration
+
+_NEEDS_DB = pytest.mark.skipif(
+    not os.environ.get("STEWARD_DATABASE_URL"),
+    reason="integration test needs a live Postgres (STEWARD_DATABASE_URL)",
+)
+
+
+@pytest.fixture
+def app():
+    if not os.environ.get("STEWARD_DATABASE_URL"):
+        pytest.skip("needs Postgres")
+    from steward.app import create_app
+    return create_app(testing=False)
+
+
+@_NEEDS_DB
+def test_firing_triggers_ansible_action(app, tmp_path):
+    from sqlalchemy import select
+    from steward.core.alerts import record_metric
+    from steward.models.alerts import (
+        AlertEvent, AlertOperator, AlertRule, AlertState, AlertStateEnum,
+    )
+    from steward.models.ansible import AnsibleRun, AnsibleRunStatus
+    from steward.models.users import User, UserRole
+
+    (tmp_path / "fire.yml").write_text(textwrap.dedent("""\
+        - hosts: localhost
+          connection: local
+          gather_facts: false
+          tasks:
+            - debug:
+                msg: "FIRED-{{ steward_alert_metric }}"
+    """))
+    (tmp_path / "inv.ini").write_text("localhost ansible_connection=local\n")
+
+    # An ansible source the action resolves against.
+    app.config["ANSIBLE"] = {
+        "sources": [{"name": "t", "type": "local", "path": str(tmp_path)}],
+    }
+
+    uid = str(uuid.uuid4())
+    rule_id = str(uuid.uuid4())
+    action = {"source": "t", "playbook": "fire.yml", "inventory": "inv.ini"}
+
+    async def _go():
+        async with app.db_sessionmaker() as s:
+            async with s.begin():
+                s.add(User(
+                    id=uid, username=f"u{uid[:8]}", email=f"{uid[:8]}@e.test",
+                    password_hash="x", role=UserRole.admin, is_active=True,
+                ))
+                s.add(AlertRule(
+                    id=rule_id, name="cpu hot", source_module="host_agent",
+                    resource_name="srv1", metric_name="cpu_pct",
+                    operator=AlertOperator.gt, threshold=90.0,
+                    consecutive_failures_required=1, enabled=True,
+                    ansible_action=action, created_by=uid,
+                ))
+                s.add(AlertState(rule_id=rule_id, state=AlertStateEnum.inactive))
+
+        # Breaching value → transition to firing → schedules the action task.
+        async with app.db_sessionmaker() as s:
+            async with s.begin():
+                await record_metric(s, "host_agent", "srv1", "cpu_pct", 95.0)
+
+        # Let the fire-and-forget dispatch + action tasks complete.
+        pending = [t for t in asyncio.all_tasks() if t is not asyncio.current_task()]
+        await asyncio.gather(*pending, return_exceptions=True)
+
+        async with app.db_sessionmaker() as s:
+            run = (await s.execute(
+                select(AnsibleRun).where(AnsibleRun.source_name == "t"))).scalars().first()
+            event = (await s.execute(
+                select(AlertEvent).where(AlertEvent.rule_id == rule_id))).scalar_one()
+            return run, event
+
+    run, event = asyncio.run(_go())
+    assert run is not None, "no AnsibleRun was created by the firing rule"
+    assert run.triggered_by is None  # system-triggered
+    assert run.status == AnsibleRunStatus.success, run.output
+    assert "FIRED-cpu_pct" in (run.output or "")  # injected context var reached the play
+    assert event.ansible_run_id == run.id  # firing event linked to the run

tests/test_alert_ansible.py

@@ -0,0 +1,30 @@
+"""Unit tests for alert -> Ansible action context vars (task 250)."""
+from steward.core.alerts import alert_extra_vars
+from steward.models.alerts import AlertOperator, AlertRule
+
+
+def test_alert_extra_vars_describes_the_firing():
+    rule = AlertRule(
+        name="UPS low battery", source_module="snmp", resource_name="ups",
+        metric_name="battery_status", operator=AlertOperator.lt, threshold=3.0,
+        created_by="u",
+    )
+    ev = alert_extra_vars(rule, 2.0)
+    assert "steward_alert_rule=UPS low battery" in ev
+    assert "steward_alert_source=snmp" in ev
+    assert "steward_alert_resource=ups" in ev
+    assert "steward_alert_metric=battery_status" in ev
+    assert "steward_alert_value=2.0" in ev
+    assert "steward_alert_threshold=3.0" in ev
+    assert "steward_alert_operator=<" in ev
+
+
+def test_alert_extra_vars_are_key_value_strings():
+    rule = AlertRule(
+        name="r", source_module="host_agent", resource_name="srv1",
+        metric_name="cpu_pct", operator=AlertOperator.gt, threshold=90.0,
+        created_by="u",
+    )
+    ev = alert_extra_vars(rule, 95.5)
+    assert all("=" in item for item in ev)
+    assert all(item.startswith("steward_alert_") for item in ev)