fix: allow editing default dashboard without hyphen in url_path (#591) (#592)

* fix: allow editing default dashboard without hyphen in url_path (#591)

The `ha_config_set_dashboard` tool rejected url_paths without hyphens
(like "lovelace") even for existing dashboards. The hyphen requirement
only applies when creating new dashboards in Home Assistant.

- Move hyphen validation from blanket check to create-only path
- Add "default" as alias for the default "lovelace" dashboard
- Update tool description and dashboard guide documentation
- Add E2E test for default dashboard editing

Closes #591

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Update src/ha_mcp/tools/tools_config_dashboards.py

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* fix: keep early hyphen validation with lovelace exception, fix E2E tests

Move hyphen validation back to early-exit position (before WebSocket
calls) to avoid NameError on invalid url_paths, but add exception for
"lovelace" so the default dashboard can be edited.

Rewrite E2E test to work on fresh HA instances where the default
dashboard isn't a storage-mode dashboard - assert that "lovelace" and
"default" are not rejected by hyphen validation rather than trying to
actually edit the default dashboard config.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: treat lovelace as always-existing to prevent create attempt

The built-in default dashboard ("lovelace") isn't listed by
lovelace/dashboards/list on fresh HA instances, causing the code
to try creating a new dashboard with that url_path. HA's own API
then rejects it with its own hyphen validation.

Force dashboard_exists=True when url_path is "lovelace" so the
code never attempts to create a dashboard that already exists
as a built-in.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: 3 people

src/ha_mcp/resources/dashboard_guide.md

@@ -53,9 +53,10 @@ Complete guide for designing Home Assistant dashboards: structure, built-in card
 
 ### Critical Validation Rules
 
-**url_path MUST contain hyphen (-)**
-- Valid: "my-dashboard"
+**New dashboard url_path must contain hyphen (-)**
+- Valid: "my-dashboard", "mobile-view"
 - Invalid: "mydashboard" → REJECTED
+- Exception: "lovelace" and "default" target the built-in default dashboard
 
 **Dashboard ID vs url_path:**
 - `dashboard_id`: Internal identifier (returned on create, used for update/delete)
@@ -508,7 +509,7 @@ card_config = {
 
 | Issue | Solution |
 |-------|----------|
-| url_path rejected | Add hyphen: "my-dashboard" not "mydashboard" |
+| url_path rejected | New dashboards need hyphen: "my-dashboard" not "mydashboard". Use "lovelace" or "default" for the default dashboard. |
 | Entity not found | Use full ID: "light.living_room" not "living_room" |
 | Features not working | Match feature type to entity domain |
 | Custom card not loading | Check resource type is "module", verify URL |

src/ha_mcp/tools/tools_config_dashboards.py

@@ -16,7 +16,11 @@
 from pydantic import Field
 
 from ..config import get_global_settings
-from ..utils.python_sandbox import PythonSandboxError, get_security_documentation, safe_execute
+from ..utils.python_sandbox import (
+    PythonSandboxError,
+    get_security_documentation,
+    safe_execute,
+)
 from .helpers import log_tool_usage
 from .util_helpers import parse_json_param
 
@@ -25,6 +29,7 @@
 # Try to import jq - it's not available on Windows ARM64
 try:
     import jq  # noqa: F401 - Used to check availability, re-imported in function
+
     JQ_AVAILABLE = True
 except ImportError:
     JQ_AVAILABLE = False
@@ -98,7 +103,9 @@ async def _verify_config_unchanged(
         get_data["url_path"] = url_path
 
     result = await client.send_websocket_message(get_data)
-    current_config = result.get("result", result) if isinstance(result, dict) else result
+    current_config = (
+        result.get("result", result) if isinstance(result, dict) else result
+    )
 
     if not isinstance(current_config, dict):
         return {"success": True}  # Can't verify, proceed anyway
@@ -193,29 +200,33 @@ def _find_cards_in_config(
                     if not isinstance(card, dict):
                         continue
                     if _card_matches(card, entity_id, card_type, heading):
-                        matches.append({
-                            "view_index": view_idx,
-                            "section_index": section_idx,
-                            "card_index": card_idx,
-                            "jq_path": f".views[{view_idx}].sections[{section_idx}].cards[{card_idx}]",
-                            "card_type": card.get("type"),
-                            "card_config": card,
-                        })
+                        matches.append(
+                            {
+                                "view_index": view_idx,
+                                "section_index": section_idx,
+                                "card_index": card_idx,
+                                "jq_path": f".views[{view_idx}].sections[{section_idx}].cards[{card_idx}]",
+                                "card_type": card.get("type"),
+                                "card_config": card,
+                            }
+                        )
         else:
             # Flat view (masonry, panel, sidebar)
             cards = view.get("cards", [])
             for card_idx, card in enumerate(cards):
                 if not isinstance(card, dict):
                     continue
                 if _card_matches(card, entity_id, card_type, heading):
-                    matches.append({
-                        "view_index": view_idx,
-                        "section_index": None,
-                        "card_index": card_idx,
-                        "jq_path": f".views[{view_idx}].cards[{card_idx}]",
-                        "card_type": card.get("type"),
-                        "card_config": card,
-                    })
+                    matches.append(
+                        {
+                            "view_index": view_idx,
+                            "section_index": None,
+                            "card_index": card_idx,
+                            "jq_path": f".views[{view_idx}].cards[{card_idx}]",
+                            "card_type": card.get("type"),
+                            "card_config": card,
+                        }
+                    )
 
     return matches
 
@@ -239,8 +250,7 @@ def _card_matches(
         card_entities = card.get("entities", [])
         if isinstance(card_entities, list):
             all_entities = [card_entity] + [
-                e.get("entity", e) if isinstance(e, dict) else e
-                for e in card_entities
+                e.get("entity", e) if isinstance(e, dict) else e for e in card_entities
             ]
         else:
             all_entities = [card_entity]
@@ -362,7 +372,9 @@ async def ha_config_get_dashboard(
             config = response.get("result") if isinstance(response, dict) else response
 
             # Compute hash for optimistic locking in subsequent operations
-            config_hash = _compute_config_hash(config) if isinstance(config, dict) else None
+            config_hash = (
+                _compute_config_hash(config) if isinstance(config, dict) else None
+            )
 
             # Calculate config size for progressive disclosure hint
             config_size = len(json.dumps(config)) if isinstance(config, dict) else 0
@@ -411,8 +423,9 @@ async def ha_config_set_dashboard(
         url_path: Annotated[
             str,
             Field(
-                description="Unique URL path for dashboard (must contain hyphen, "
-                "e.g., 'my-dashboard', 'mobile-view')"
+                description="Dashboard URL path (e.g., 'my-dashboard'). "
+                "Use 'default' or 'lovelace' for the default dashboard. "
+                "New dashboards must use a hyphenated path."
             ),
         ],
         config: Annotated[
@@ -430,7 +443,7 @@ async def ha_config_set_dashboard(
                 description="jq expression to transform existing dashboard config. "
                 "Mutually exclusive with config and python_transform. Requires config_hash for validation. "
                 "Examples: '.views[0].sections[1].cards[0].icon = \"mdi:thermometer\"', "
-                "'.views[0].cards += [{\"type\": \"button\", \"entity\": \"light.bedroom\"}]', "
+                '\'.views[0].cards += [{"type": "button", "entity": "light.bedroom"}]\', '
                 "'del(.views[0].sections[0].cards[2])'. "
                 "MULTI-OP: Chain with '|': 'del(.views[0].cards[2]) | .views[0].cards[0].icon = \"mdi:new\"'. "
                 "Use ha_dashboard_find_card() to get jq_path for targeted edits."
@@ -447,8 +460,7 @@ async def ha_config_set_dashboard(
                 "Simple: python_transform=\"config['views'][0]['cards'][0]['icon'] = 'mdi:lamp'\" "
                 "Pattern: python_transform=\"for card in config['views'][0]['cards']: if 'light' in card.get('entity', ''): card['icon'] = 'mdi:lightbulb'\" "
                 "Multi-op: python_transform=\"config['views'][0]['cards'][0]['icon'] = 'mdi:lamp'; del config['views'][0]['cards'][2]\" "
-                "\n\n"
-                + get_security_documentation(),
+                "\n\n" + get_security_documentation(),
             ),
         ] = None,
         config_hash: Annotated[
@@ -483,7 +495,8 @@ async def ha_config_set_dashboard(
         Creates a new dashboard or updates an existing one with the provided configuration.
         Supports three modes: full config replacement, Python transformation, OR jq-based transformation.
 
-        IMPORTANT: url_path must contain a hyphen (-) to be valid.
+        Use 'default' or 'lovelace' to target the built-in default dashboard.
+        New dashboards require a hyphenated url_path (e.g., 'my-dashboard').
 
         WHEN TO USE WHICH MODE:
         - python_transform: RECOMMENDED for edits. Surgical/pattern-based updates, works on all platforms.
@@ -601,15 +614,22 @@ async def ha_config_set_dashboard(
         (title, icon), use ha_config_update_dashboard_metadata().
         """
         try:
-            # Validate url_path contains hyphen
-            if "-" not in url_path:
+            # Handle "default" as alias for the default dashboard
+            # (matches ha_config_get_dashboard behavior)
+            if url_path == "default":
+                url_path = "lovelace"
+
+            # Validate url_path contains hyphen for new dashboards
+            # The built-in "lovelace" dashboard is exempt since it already exists
+            if "-" not in url_path and url_path != "lovelace":
                 return {
                     "success": False,
                     "action": "set",
                     "error": "url_path must contain a hyphen (-)",
                     "suggestions": [
                         f"Try '{url_path.replace('_', '-')}' instead",
                         "Use format like 'my-dashboard' or 'mobile-view'",
+                        "Use 'lovelace' or 'default' to edit the default dashboard",
                     ],
                 }
 
@@ -728,7 +748,9 @@ async def ha_config_set_dashboard(
 
                 save_result = await client.send_websocket_message(save_data)
 
-                if isinstance(save_result, dict) and not save_result.get("success", True):
+                if isinstance(save_result, dict) and not save_result.get(
+                    "success", True
+                ):
                     error_msg = save_result.get("error", {})
                     if isinstance(error_msg, dict):
                         error_msg = error_msg.get("message", str(error_msg))
@@ -793,14 +815,18 @@ async def ha_config_set_dashboard(
                         ],
                     }
 
-                current_config = response.get("result") if isinstance(response, dict) else response
+                current_config = (
+                    response.get("result") if isinstance(response, dict) else response
+                )
                 if not isinstance(current_config, dict):
                     return {
                         "success": False,
                         "action": "jq_transform",
                         "url_path": url_path,
                         "error": "Current dashboard config is invalid",
-                        "suggestions": ["Initialize dashboard with 'config' parameter first"],
+                        "suggestions": [
+                            "Initialize dashboard with 'config' parameter first"
+                        ],
                     }
 
                 # Validate config_hash for optimistic locking
@@ -819,7 +845,9 @@ async def ha_config_set_dashboard(
                     }
 
                 # Apply jq transformation
-                transformed_config, error = _apply_jq_transform(current_config, jq_transform)
+                transformed_config, error = _apply_jq_transform(
+                    current_config, jq_transform
+                )
                 if error:
                     return {
                         "success": False,
@@ -843,7 +871,9 @@ async def ha_config_set_dashboard(
 
                 save_result = await client.send_websocket_message(save_data)
 
-                if isinstance(save_result, dict) and not save_result.get("success", True):
+                if isinstance(save_result, dict) and not save_result.get(
+                    "success", True
+                ):
                     error_msg = save_result.get("error", {})
                     if isinstance(error_msg, dict):
                         error_msg = error_msg.get("message", str(error_msg))
@@ -860,7 +890,9 @@ async def ha_config_set_dashboard(
 
                 # Compute new hash for potential chaining
                 # transformed_config is guaranteed to be a dict here (validated above)
-                new_config_hash = _compute_config_hash(cast(dict[str, Any], transformed_config))
+                new_config_hash = _compute_config_hash(
+                    cast(dict[str, Any], transformed_config)
+                )
 
                 return {
                     "success": True,
@@ -885,6 +917,11 @@ async def ha_config_set_dashboard(
                 d.get("url_path") == url_path for d in existing_dashboards
             )
 
+            # The built-in default dashboard ("lovelace") is always present
+            # but isn't listed by lovelace/dashboards/list on fresh installs
+            if url_path == "lovelace":
+                dashboard_exists = True
+
             # If dashboard doesn't exist, create it
             dashboard_id = None
             if not dashboard_exists:
@@ -950,7 +987,10 @@ async def ha_config_set_dashboard(
                 # For existing dashboards, optionally validate config_hash and warn on large replacement
                 if dashboard_exists:
                     # Fetch current config for validation/comparison
-                    get_data: dict[str, Any] = {"type": "lovelace/config", "force": True}
+                    get_data: dict[str, Any] = {
+                        "type": "lovelace/config",
+                        "force": True,
+                    }
                     if url_path:
                         get_data["url_path"] = url_path
                     current_response = await client.send_websocket_message(get_data)
@@ -1039,7 +1079,7 @@ async def ha_config_set_dashboard(
                 "error": str(e),
                 "suggestions": [
                     "Ensure url_path is unique (not already in use for different dashboard type)",
-                    "Verify url_path contains a hyphen",
+                    "New dashboards require a hyphenated url_path",
                     "Check that you have admin permissions",
                     "Verify config format is valid Lovelace JSON",
                 ],
@@ -1446,7 +1486,6 @@ async def ha_get_card_documentation(
                 "error": str(e),
             }
 
-
     # =========================================================================
     # Dashboard Resource Management Tools
     # =========================================================================
@@ -1483,7 +1522,9 @@ async def ha_get_card_documentation(
     async def ha_dashboard_find_card(
         url_path: Annotated[
             str | None,
-            Field(description="Dashboard URL path, e.g. 'lovelace-home'. Omit for default."),
+            Field(
+                description="Dashboard URL path, e.g. 'lovelace-home'. Omit for default."
+            ),
         ] = None,
         entity_id: Annotated[
             str | None,
@@ -1505,7 +1546,9 @@ async def ha_dashboard_find_card(
         ] = None,
         include_config: Annotated[
             bool,
-            Field(description="Include full card configuration in results (increases output size)."),
+            Field(
+                description="Include full card configuration in results (increases output size)."
+            ),
         ] = False,
     ) -> dict[str, Any]:
         """
@@ -1590,7 +1633,9 @@ async def ha_dashboard_find_card(
                     "action": "find_card",
                     "url_path": url_path,
                     "error": "Dashboard config is empty or invalid",
-                    "suggestions": ["Initialize dashboard with ha_config_set_dashboard"],
+                    "suggestions": [
+                        "Initialize dashboard with ha_config_set_dashboard"
+                    ],
                 }
 
             # Check for strategy dashboard
@@ -1630,7 +1675,8 @@ async def ha_dashboard_find_card(
                 "matches": matches,
                 "match_count": len(matches),
                 "hint": "Use jq_path with ha_config_set_dashboard(jq_transform=...) for targeted updates"
-                if matches else "No matches found. Try broader search criteria.",
+                if matches
+                else "No matches found. Try broader search criteria.",
             }
 
         except asyncio.CancelledError:
@@ -1653,4 +1699,3 @@ async def ha_dashboard_find_card(
                     "Verify dashboard with ha_config_get_dashboard(list_only=True)",
                 ],
             }
-