fix: reject malformed feature-flags payload instead of silent no-op (#1865)

* fix: reject malformed feature-flags payload instead of silent no-op

POST /api/settings/features defaulted a missing `flags` key to `{}`, so a
flat body (e.g. {"enable_lite_docstrings": true}) silently applied nothing
yet returned success=true/restart_required=true — worse than a visible
no-op, since the caller believed the flag changed and a restart was
pending when nothing happened.

Require the nested {"flags": {...}} shape: reject a body without a `flags`
object (400 with the correct shape in the message) and reject an empty
`flags` object. The web UI always POSTs {"flags": {[field]: value}}, so
only malformed external/scripted callers are affected.

Closes #1840

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

* fix: add actionable suggestions to feature-flags shape errors

Address Gemini review: the two new VALIDATION_INVALID_PARAMETER responses
now carry a `suggestions` entry per the styleguide's progressive-disclosure
rule, guiding the caller to the correct {"flags": {...}} shape. Regression
tests assert the suggestion is present.

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

---------

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kingpanther13

src/ha_mcp/settings_ui/__init__.py

@@ -1982,12 +1982,39 @@ async def _save_feature_flags(request: Request) -> JSONResponse:
                 ),
                 status_code=400,
             )
-        raw_flags = body.get("flags", {})
+        # Require the nested ``{"flags": {...}}`` shape. A flat body
+        # (e.g. ``{"enable_lite_docstrings": true}``) has no ``flags``
+        # key, so a lenient ``body.get("flags", {})`` default silently
+        # dropped every field and still returned
+        # ``success=True``/``restart_required=True`` — worse than a
+        # visible no-op, because the caller believed the flag changed
+        # and a restart was pending when nothing happened (#1840).
+        raw_flags = body.get("flags")
         if not isinstance(raw_flags, dict):
             return JSONResponse(
                 create_error_response(
                     ErrorCode.VALIDATION_INVALID_PARAMETER,
-                    "'flags' must be an object mapping field names to values",
+                    "Request body must contain a 'flags' object mapping "
+                    'field names to values, e.g. {"flags": '
+                    '{"enable_lite_docstrings": true}}. A flat body such '
+                    'as {"enable_lite_docstrings": true} is not accepted.',
+                    suggestions=[
+                        'Wrap the flags in a "flags" object, e.g. '
+                        '{"flags": {"enable_lite_docstrings": true}}.',
+                    ],
+                ),
+                status_code=400,
+            )
+        if not raw_flags:
+            return JSONResponse(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    "'flags' object is empty; include at least one "
+                    "feature-flag field to update.",
+                    suggestions=[
+                        'Include at least one field inside "flags", e.g. '
+                        '{"flags": {"enable_lite_docstrings": true}}.',
+                    ],
                 ),
                 status_code=400,
             )

tests/src/unit/test_settings_ui.py

@@ -2174,6 +2174,60 @@ async def test_read_only_mode_save_round_trips_into_settings(
         get_data_dir.cache_clear()
         _reset_global_settings()
 
+    @pytest.mark.asyncio
+    async def test_flat_body_rejected_not_silent_noop(self, monkeypatch, tmp_path):
+        """A flat body (missing the ``flags`` wrapper) must 400, not
+        silently no-op with ``success``/``restart_required`` (#1840).
+
+        Before the fix, ``POST {"enable_lite_docstrings": true}``
+        returned ``{"success": true, "applied": {}, "mode": "file",
+        "restart_required": true}`` — worse than a plain no-op, since a
+        caller believed the flag changed and a restart was pending when
+        nothing happened. No override file should be written either.
+        """
+        post_handler = self._capture_post_handler(monkeypatch, tmp_path)
+
+        resp = await post_handler(self._make_request({"enable_lite_docstrings": True}))
+
+        assert resp.status_code == 400
+        body = json.loads(resp.body)
+        assert body["success"] is False
+        assert body["error"]["code"] == "VALIDATION_INVALID_PARAMETER"
+        # Progressive disclosure: the error guides the caller to the shape.
+        assert body["error"]["suggestion"]
+        # A rejected save must not persist anything.
+        assert not (tmp_path / "feature_flags.json").exists()
+
+    @pytest.mark.asyncio
+    async def test_empty_flags_object_rejected(self, monkeypatch, tmp_path):
+        """An explicitly empty ``flags`` object applies nothing and must
+        400 rather than falsely reporting ``restart_required`` (#1840)."""
+        post_handler = self._capture_post_handler(monkeypatch, tmp_path)
+
+        resp = await post_handler(self._make_request({"flags": {}}))
+
+        assert resp.status_code == 400
+        body = json.loads(resp.body)
+        assert body["success"] is False
+        assert body["error"]["code"] == "VALIDATION_INVALID_PARAMETER"
+        assert body["error"]["suggestion"]
+        assert not (tmp_path / "feature_flags.json").exists()
+
+    @pytest.mark.asyncio
+    async def test_non_dict_flags_rejected(self, monkeypatch, tmp_path):
+        """``flags`` present but not an object (e.g. a list) must 400."""
+        post_handler = self._capture_post_handler(monkeypatch, tmp_path)
+
+        resp = await post_handler(
+            self._make_request({"flags": ["enable_lite_docstrings"]})
+        )
+
+        assert resp.status_code == 400
+        body = json.loads(resp.body)
+        assert body["success"] is False
+        assert body["error"]["code"] == "VALIDATION_INVALID_PARAMETER"
+        assert not (tmp_path / "feature_flags.json").exists()
+
 
 class TestSaveToolsResponseShape:
     """Pins the unified ``{success, applied, mode, restart_required}``