fix(settings-ui): unblock tool list rendering + always-emit settings_url

Two regressions surfaced while testing PR #1381 against Claude Desktop.

1. Settings page stuck on "Loading...".

   stopSidecar()'s JS confirm() prompt used a single-quoted string
   'Stop the settings server?\n\n' inside the Python triple-quoted
   _SETTINGS_HTML. Python consumed the \n\n as literal newlines, so
   the rendered <script> contained a JS string spanning two physical
   lines — an unrecoverable SyntaxError that aborted the entire
   script before loadTools() could run. The in-page error handler
   (window.addEventListener('error', ...)) cannot catch parse-time
   errors, so the user saw only the initial "Loading..." indicator
   with no diagnostic. Escape the backslashes in the Python source
   so the JS engine sees the intended \n\n escape sequence.

2. settings_url invisible to fields=-projecting callers.

   An LLM that minimized payload via fields=["system_info"] (or any
   narrow projection) would lose the settings_url field, since the
   projection ran *after* settings_url was added to the result. With
   the field absent the LLM cannot hand the URL to the user even
   when it knows the user is asking for it. Move the settings_url
   emission to *after* project_fields so it survives every
   projection, and surface it in the main tool docstring (which
   LLMs read first) instead of relying on the fields= enum
   description that less-attentive LLMs may skip.

Regression tests:
  - test_rendered_script_parses_as_javascript shells out to
    `node --check` against the rendered <script> body so any future
    raw-newline-in-JS-string regression fails fast with a precise
    parser diagnostic. Skipped when node is not on PATH (the test
    matrix installs node already).
  - test_settings_url_survives_fields_projection pins the new
    always-emit-regardless-of-projection contract.

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

Author: kingpanther13

src/ha_mcp/settings_ui.py

@@ -610,7 +610,7 @@ def apply_tool_visibility(
 async function stopSidecar() {
   const btn = document.getElementById('stopSidecarBtn');
   if (!confirm(
-    'Stop the settings server?\n\n' +
+    'Stop the settings server?\\n\\n' +
     'A "disabled" sentinel file will be written so the server does not ' +
     'respawn the next time ha-mcp starts. To re-enable, delete the file ' +
     'at ~/.ha-mcp/settings_ui_disabled (or unset HA_MCP_DISABLE_SETTINGS_UI).'

src/ha_mcp/tools/tools_search.py

@@ -1231,7 +1231,10 @@ async def ha_get_overview(
                     "area_analysis, ai_insights, pagination, partial, warnings, "
                     "device_types, service_availability, system_info, "
                     "notification_count, notifications, repair_count, repairs, "
-                    "repairs_error, tool_discovery."
+                    "repairs_error, tool_discovery. The ``settings_url`` "
+                    "field (stdio mode only, see tool description) is not "
+                    "subject to this projection — it is always included "
+                    "when the settings-UI sidecar is running."
                 ),
             ),
         ] = None,
@@ -1249,6 +1252,14 @@ async def ha_get_overview(
         Use fields= to project the response to only the keys you need — a
         significantly smaller payload when fetching a single sub-section (e.g.
         fields=["system_info"] returns just that section instead of the full overview).
+
+        When the ha-mcp settings-UI sidecar is running (stdio mode, e.g.
+        Claude Desktop / Claude Code), the response always includes a
+        ``settings_url`` field — the local URL to the tool-configuration
+        page. Hand this URL to the user when they ask how to enable or
+        disable tools or change server settings. ``settings_url`` is
+        emitted regardless of ``fields=`` projection so it stays
+        discoverable even when callers minimize the response.
         """
         # Validate fields= early so a malformed value returns VALIDATION_FAILED
         # with parameter="fields" (ha_get_overview has no outer try/except, so
@@ -1441,16 +1452,22 @@ async def ha_get_overview(
         # the FastMCP server directly. A leftover URL file from a prior
         # stdio run on the same machine could in principle be surfaced
         # by an HTTP-mode process — acceptable because the URL itself
-        # is gated by the random secret path either way. Added before
-        # the fields= projection so callers can request just
-        # ``settings_url`` via ``fields=["settings_url"]``.
+        # is gated by the random secret path either way.
+        #
+        # Added *after* ``project_fields`` so it survives every
+        # ``fields=`` projection — even an LLM that calls
+        # ``fields=["system_info"]`` (to minimize payload) still sees
+        # the URL and can hand it to the user. Hiding it behind the
+        # projection made it effectively invisible to less-attentive
+        # LLMs that scanned only the documented ``fields=`` enum.
         from ..stdio_settings_sidecar import read_sidecar_url
 
+        projected = project_fields(result, parsed_fields)
         sidecar_url = read_sidecar_url()
         if sidecar_url:
-            result["settings_url"] = sidecar_url
+            projected["settings_url"] = sidecar_url
 
-        return project_fields(result, parsed_fields)
+        return projected
 
     @mcp.tool(
         tags={"Search & Discovery"},

tests/src/unit/test_overview_system_info.py

@@ -372,3 +372,28 @@ async def test_settings_url_omitted_when_no_sidecar(
         )
         result = await overview_tool(detail_level="minimal")
         assert "settings_url" not in result
+
+    @pytest.mark.asyncio
+    async def test_settings_url_survives_fields_projection(
+        self, overview_tool, monkeypatch
+    ):
+        """``settings_url`` MUST be returned even when ``fields=`` filters
+        the rest of the payload.
+
+        A less-attentive LLM that minimizes payload via
+        ``fields=["system_info"]`` (or any narrow projection) would
+        otherwise lose the URL silently — and the LLM cannot hand the
+        user a URL it never receives. Pinning the post-projection
+        emission keeps ``settings_url`` discoverable regardless of how
+        the caller scopes the overview response.
+        """
+        url = "http://127.0.0.1:8099/private_abc/settings"
+        monkeypatch.setattr(
+            "ha_mcp.stdio_settings_sidecar.read_sidecar_url",
+            lambda: url,
+        )
+        result = await overview_tool(fields=["system_info"])
+        assert result.get("settings_url") == url
+        # system_info is still projected; settings_url is the only
+        # extra survivor (plus the always-retained success/warnings).
+        assert "system_info" in result

tests/src/unit/test_settings_ui.py

@@ -505,9 +505,7 @@ def _patch_supervisor_client(
         cm.__aenter__ = AsyncMock(return_value=mock_client)
         cm.__aexit__ = AsyncMock(return_value=None)
         factory = MagicMock(return_value=cm)
-        patcher = patch(
-            "ha_mcp.settings_ui.make_supervisor_httpx_client", factory
-        )
+        patcher = patch("ha_mcp.settings_ui.make_supervisor_httpx_client", factory)
         return patcher, mock_client
 
     @pytest.mark.asyncio
@@ -707,3 +705,62 @@ async def test_invalid_slug_in_body_falls_back_to_self(self, monkeypatch, body):
             await restart(request)
 
         mock_client.post.assert_awaited_once_with("/addons/self/restart")
+
+
+class TestRenderedHTMLJsSyntax:
+    """The settings page HTML is built from a Python triple-quoted string.
+
+    Python consumes ``\\n`` inside that string as a real newline. If the
+    author writes ``'foo\\n\\nbar'`` intending the JavaScript escape
+    sequence, the rendered ``<script>`` contains a raw newline inside a
+    single-quoted JS string literal — an unrecoverable SyntaxError that
+    aborts the *entire* script before any handler runs, leaving the
+    page stuck on its initial ``Loading...`` indicator forever. The
+    page-level ``window.addEventListener('error', ...)`` cannot catch
+    parse-time SyntaxErrors, so the user sees no diagnostic at all.
+    """
+
+    def _extract_script(self) -> str:
+        from ha_mcp.settings_ui import _SETTINGS_HTML
+
+        start = _SETTINGS_HTML.find("<script>")
+        end = _SETTINGS_HTML.find("</script>")
+        assert start != -1 and end != -1 and end > start
+        return _SETTINGS_HTML[start + len("<script>") : end]
+
+    def test_rendered_script_parses_as_javascript(self, tmp_path: Path):
+        """The rendered ``<script>`` body must parse as valid JavaScript.
+
+        A parse-time SyntaxError aborts the entire script before any
+        handler runs, leaving the page stuck on its initial
+        ``Loading...`` indicator with no in-page diagnostic (the
+        page-level ``window.addEventListener('error', ...)`` cannot
+        catch parse-time errors). The canonical trigger is a
+        Python-consumed ``\\n`` escape leaving a raw newline inside a
+        single-quoted JS string — but any other ill-formed JS would
+        be just as fatal.
+
+        Shells out to ``node --check`` for a faithful parse. Skipped
+        when node isn't available so a missing dev dependency doesn't
+        block local runs; CI installs node (see ``test.yml``).
+        """
+        import shutil
+        import subprocess
+
+        if shutil.which("node") is None:
+            pytest.skip("node not installed — install Node.js to run this test")
+
+        script = self._extract_script()
+        js_file = tmp_path / "settings_ui_script.js"
+        js_file.write_text(script, encoding="utf-8")
+        result = subprocess.run(
+            ["node", "--check", str(js_file)],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            raise AssertionError(
+                "Settings UI <script> body failed node --check:\n"
+                f"stdout: {result.stdout}\nstderr: {result.stderr}"
+            )