feat: add startWecker and stopWecker mutations to start/stop alarm via API

- Add startWecker mutation: starts wecker.py via subprocess if not already ringing
- Add stopWecker mutation: kills the running wecker process via SIGTERM if ringing
- Both mutations handle the 'already ringing' / 'not ringing' edge cases gracefully
- Update README with API documentation for the new mutations
- Add comprehensive tests (unit + GraphQL endpoint)

tests/test_api.py

@@ -203,6 +203,107 @@ def test_graphql_workflow():
     assert res.json()["data"]["getAlarms"] == []
 
 
+def test_start_wecker_starts_process_when_not_ringing():
+    """startWecker returns True and spawns wecker.py when not already ringing."""
+    from api.schema import Mutation
+
+    mutation = Mutation()
+
+    with patch("api.schema.is_wecker_ringing", return_value=False), \
+         patch("subprocess.Popen") as mock_popen:
+        mock_proc = mock_popen.return_value
+        mock_proc.pid = 9999
+        result = mutation.start_wecker()
+        assert result is True
+        mock_popen.assert_called_once()
+        # Verify the command contains wecker.py
+        args, kwargs = mock_popen.call_args
+        assert "wecker.py" in args[0]
+        assert kwargs.get("shell") is True
+
+
+def test_start_wecker_ignores_when_already_ringing():
+    """startWecker returns False when wecker is already ringing."""
+    from api.schema import Mutation
+
+    mutation = Mutation()
+
+    with patch("api.schema.is_wecker_ringing", return_value=True), \
+         patch("api.schema.subprocess.Popen") as mock_popen:
+        result = mutation.start_wecker()
+        assert result is False
+        mock_popen.assert_not_called()
+
+
+def test_stop_wecker_kills_process_when_ringing():
+    """stopWecker returns True and kills the process wecker is ringing."""
+    from api.schema import Mutation
+
+    mutation = Mutation()
+
+    with patch("api.schema.is_wecker_ringing", return_value=True), \
+         patch("api.schema.os.kill") as mock_kill, \
+         patch("common.PID_FILE", "/tmp/fake_wecker.pid"), \
+         patch("builtins.open") as mock_open:
+        mock_f = mock_open.return_value.__enter__.return_value
+        mock_f.read.return_value = "1234"
+        mock_kill.return_value = None
+        result = mutation.stop_wecker()
+        assert result is True
+        mock_kill.assert_called_with(1234, 15)
+
+
+def test_stop_wecker_does_nothing_when_not_ringing():
+    """stopWecker returns False when wecker is not ringing."""
+    from api.schema import Mutation
+
+    mutation = Mutation()
+
+    with patch("api.schema.is_wecker_ringing", return_value=False), \
+         patch("api.schema.os.kill") as mock_kill:
+        result = mutation.stop_wecker()
+        assert result is False
+        mock_kill.assert_not_called()
+
+
+def test_start_wecker_graphql_endpoint():
+    """GraphQL mutation startWecker works via the API."""
+    headers = {"X-API-Key": "test-secret"}
+    mutation_str = """
+    mutation {
+      startWecker
+    }
+    """
+
+    with patch("api.schema.is_wecker_ringing", return_value=False), \
+         patch("subprocess.Popen") as mock_popen:
+        mock_proc = mock_popen.return_value
+        mock_proc.pid = 9999
+        res = client.post("/graphql", json={"query": mutation_str}, headers=headers)
+        assert res.status_code == 200
+        assert res.json()["data"]["startWecker"] is True
+
+
+def test_stop_wecker_graphql_endpoint():
+    """GraphQL mutation stopWecker works via the API."""
+    headers = {"X-API-Key": "test-secret"}
+    mutation_str = """
+    mutation {
+      stopWecker
+    }
+    """
+
+    with patch("api.schema.is_wecker_ringing", return_value=True), \
+         patch("api.schema.os.kill") as mock_kill, \
+         patch("builtins.open") as mock_open:
+        mock_f = mock_open.return_value.__enter__.return_value
+        mock_f.read.return_value = "1234"
+        mock_kill.return_value = None
+        res = client.post("/graphql", json={"query": mutation_str}, headers=headers)
+        assert res.status_code == 200
+        assert res.json()["data"]["stopWecker"] is True
+
+
 def test_pid_file_same_shared_constant_in_api():
     """Ensure api.schema uses the same PID_FILE from common, not a redefinition."""
     from api import schema as api_schema