perf: dedupe lovelace/dashboards/list in ha_config_set_dashboard (#1085)

[Patch76]

What does this PR do?

Closes #1085. Eliminates a redundant lovelace/dashboards/list round-trip in ha_config_set_dashboard on the internal-id branch.

The pre-resolver introduced in #1075 (tools_config_dashboards.py:285) already fetches lovelace/dashboards/list to map a hyphenless internal id to the canonical url_path. The non-python_transform path then issued a second lovelace/dashboards/list (tools_config_dashboards.py:1133-1135) to check whether the dashboard exists — answering a question the pre-resolver's response already covered.

Implementation follows Option 1 from the issue (KP13 confirmed): _resolve_dashboard now returns (match, dashboards). The pre-resolver call site captures the list as pre_fetched_dashboards; the existence-check site reuses it when present, and falls back to a fresh fetch when the pre-resolver did not fire (canonical-url_path branch).

Round-trip count unchanged on every path except the optimised one:

Branch	Before	After
Internal-id, match	2	1
Internal-id, no match	1 (hyphen-check rejects)	1
Canonical url_path	1	1
Built-in lovelace	1	1

Type of change

• 🐛 Bug fix
• ✨ New feature
• 📚 Documentation
• 🔧 Maintenance/refactor
• 🧪 Tests only
• 💥 Breaking change

Testing

• I have tested these changes with a LLM agent
• All automated tests pass (uv run pytest) — 2255 passed, 1 skipped (numpy unrelated)
• Code follows style guidelines (uv run ruff check)

3 new unit tests in TestSetDashboardListCallDedup (test_set_dashboard_metadata.py):

• test_internal_id_branch_calls_list_only_once — the optimisation regression guard
• test_canonical_url_path_branch_still_calls_list_once — guards against accidentally over-caching or breaking the existing single-fetch
• test_internal_id_no_match_falls_through_to_hyphen_check — guards against accidentally fetching twice when pre-resolver finds nothing

7 existing TestResolveDashboard tests updated for the new tuple return; both arms of the tuple are asserted so a future change to either field surfaces here.

Future improvements

• Standalone lovelace/dashboards/list call sites left untouched: ha_config_get_dashboard(list_only=True) at tools_config_dashboards.py:532-534 and the YAML-mode collision check at tools_yaml_config.py:49. The issue is scoped to ha_config_set_dashboard; a wider sweep is a separate conversation.
• A client-level dashboards/list cache with lovelace_updated-event invalidation (Option 4 in the issue) could deduplicate across tool boundaries; cache lifecycle and out-of-band .storage edits are a separate conversation if anyone wants to revisit.

Checklist

• I have updated documentation if needed

[Patch76]

Implementation Summary

Choices Made:

• Option 1 (pass-through) — _resolve_dashboard returns (match, dashboards) and the pre-resolver call site plumbs the list to the existence-check site as pre_fetched_dashboards. Confirmed in issue #1085 ("Yeah I think option 1 is workable" — kingpanther13). Smallest behaviour change; both call sites already cooperate on the same dashboard.
• Three-tuple-element return on the malformed-shape arm — (None, None) rather than (None, []) so callers can distinguish "fetch failed" from "fetched but empty registry". Pinned in test_malformed_shape_logs_warning_and_returns_none_pair. Avoids the trap where a future caller treats [] as authoritative and skips a fallback fetch.
• Lazy fallback and delete sites discard the new list element via resolved, _ = await _resolve_dashboard(...) — they don't have a follow-on existence-check to reuse it.
• Test target was the public tool, not the helper alone — issue [FEATURE] Avoid redundant lovelace/dashboards/list round-trip in ha_config_set_dashboard #1085 asks for a test asserting send_websocket_message is called exactly once on the internal-id branch. That contract spans _resolve_dashboard + the existence-check site, so the regression guard tests ha_config_set_dashboard end-to-end via the same MagicMock fixture pattern as TestSetDashboardMetadataUpdate rather than only the resolver.
• perf: prefix — semver-release config (pyproject.toml:[tool.semantic_release]) treats perf as patch-bump. No user-visible behaviour change beyond the eliminated round-trip; feat: would overstate it and refactor: understates the round-trip-count contract change.
• Gemini round 1 G1 declined — suggested capturing pre_fetched_dashboards outside the if resolved is not None block. No-op today: the no-match arm raises hyphen-validation at tools_config_dashboards.py:981-993 and raise_tool_error exits before the existence-check site is reached, so the cache value would never be read. Cache placement matches design intention.
• Gemini round 2 G2 declined — re-pitched G1 on /gemini review re-trigger without reading the prior thread; same rationale stands.
• Gemini round 2 G3b adopted (ac52f74) — flagged that the existence-check fallback fetch silently degrades to [] on unexpected response shape while _resolve_dashboard's same-arm logs logger.warning. Mirroring the warning at the fallback site closes the parity gap; new test_canonical_url_path_branch_warns_on_unexpected_shape is the regression guard.
• Gemini round 2 G3a declined — DRY-up across three lovelace/dashboards/list fetch sites via a shared _fetch_dashboards_list helper would touch ha_config_get_dashboard(list_only=True), outside this PR's diff and outside [FEATURE] Avoid redundant lovelace/dashboards/list round-trip in ha_config_set_dashboard #1085's framing ("Eliminate the redundant round-trip in the internal-id case"). Belongs in its own PR.

Problems Encountered:

• None during implementation. Existing TestLazyResolveAndRetry tests survived the signature change unchanged because they go through the WebSocket mock rather than directly calling _resolve_dashboard.

Suggested Improvements (Optional Follow-ups):

• Client-level dashboards/list cache with lovelace_updated event invalidation (Option 4 in the issue) — would deduplicate across tool boundaries, but cache lifecycle, multi-instance, and out-of-band .storage edits are a separate conversation.
• ha_config_get_dashboard(list_only=True) and YAML-mode dashboard tooling call lovelace/dashboards/list separately too (tools_config_dashboards.py:532-534, tools_yaml_config.py:49). Out of scope here per the issue framing; could be folded in if a wider sweep is wanted.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request optimizes the ha_config_set_dashboard tool by eliminating a redundant websocket round-trip to the Home Assistant API. By modifying the _resolve_dashboard helper to return the full list of dashboards alongside the match result, the system can now cache and reuse this data for subsequent existence checks. This change improves efficiency for internal-id dashboard lookups while maintaining existing behavior for other paths, supported by new regression tests.

Highlights

• Performance Optimization: Refactored _resolve_dashboard to return both the matched dashboard and the raw list of dashboards, allowing callers to reuse the fetched data.
• Redundant Call Elimination: Updated ha_config_set_dashboard to reuse the pre-fetched dashboard list during the existence check, reducing round-trips from two to one on the internal-id branch.
• Regression Testing: Added comprehensive unit tests in TestSetDashboardListCallDedup to ensure the single-fetch behavior is maintained across different execution paths.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request optimizes the dashboard management tools by deduplicating redundant WebSocket calls to lovelace/dashboards/list. The _resolve_dashboard function now returns the fetched dashboard list alongside the resolution match, allowing ha_config_set_dashboard to reuse the data for its existence check. Comprehensive unit tests have been added to verify the call deduplication and ensure no regressions in various resolution scenarios. The review feedback suggests a minor improvement to make the dashboard list caching more robust by capturing the list even when a resolution match is not found.

[Patch76]

/gemini review

[gemini-code-assist]

Code Review

This pull request optimizes dashboard configuration by deduplicating WebSocket calls to the Home Assistant API. The _resolve_dashboard helper now returns the full dashboard list alongside the resolved match, allowing ha_config_set_dashboard to reuse the data for existence checks instead of performing a redundant round-trip. New unit tests verify this deduplication and the updated resolver signature. Feedback suggests capturing the dashboard list even when a match isn't found to increase robustness and refactoring duplicated fetching logic into a centralized helper function to improve maintainability.

[Patch76]

/gemini review

[gemini-code-assist]

Code Review

This pull request optimizes dashboard operations by deduplicating calls to lovelace/dashboards/list. The _resolve_dashboard function now returns the raw dashboards list alongside the match result, allowing callers like ha_config_set_dashboard to reuse the data for existence checks instead of performing a redundant round-trip. Comprehensive unit tests have been added to verify the deduplication logic and handle various response shapes from Home Assistant. I have no feedback to provide.

[kingpanther13]

Optimization is correct, tests lock the invariant in well, and the warning-parity follow-up is a strict improvement. One ask before merge — the new comments and docstrings carry PR-bound rot that's worth cleaning while you're in there:

Drop #1085 references from in-code comments and assert messages:

• tools_config_dashboards.py:284 — trailing — see issue #1085 on the docstring rationale
• tools_config_dashboards.py:961-965 and :1155-1159 — keep the dedup WHY, drop the (issue #1085) parenthetical
• test_set_dashboard_metadata.py:159-166 — drop Issue #1085 from the class docstring
• test_set_dashboard_metadata.py:206-209 — assert message restates the test name and trails with the issue number; trim to something like "internal-id branch must reuse the pre-resolver's dashboards list"

Delete low-value comments where the code already says it:

• tools_config_dashboards.py:394-395 and :1449-1450 — _, already signals discard, and the _resolve_dashboard docstring already enumerates all three call sites with their list-disposition. The inline comments are noise.
• test_tools_config_dashboards.py:92-96 — class docstring duplicates the function's own docstring and reaches across to describe the caller's dedup use case. Either delete or trim to one line about the shape.

The dedup-WHY comments themselves are worth keeping — just strip the issue references so they don't rot when #1085 is closed and forgotten.

[Patch76]

Addressed in c765653:

#1085 references dropped:

• tools_config_dashboards.py:285 — trailing — see issue #1085 removed from _resolve_dashboard docstring
• tools_config_dashboards.py:962 and :1157 — (issue #1085) parenthetical dropped from both dedup-WHY comments; the WHY itself stays
• test_set_dashboard_metadata.py:159 — class docstring's Issue #1085: prefix dropped
• test_set_dashboard_metadata.py:217-219 — assert message trimmed to "internal-id branch must reuse the pre-resolver's dashboards list"

Low-value comments deleted:

• tools_config_dashboards.py:394 and :1447 — both inline _,-discard comments removed; _resolve_dashboard's docstring already enumerates the three call sites and their list disposition
• test_tools_config_dashboards.py:91 — class docstring trimmed to one orientation line about the shape

Pre-push gates: ruff format + check, mypy, full unit suite (2256 passed, 1 numpy-skip by-design) all green.

[Patch76]

Heads-up: arm-E2E on c765653 fails on TestYamlModeDashboardRegistration::test_remove_dashboard_entry. Investigation showed this is a pre-existing test-isolation race triggered by the default --dist load xdist scheduling, unrelated to this cleanup commit (diff is comment / docstring / assert-message bytes only). Two failure modes observed across the original run + rerun: (1) remove scheduled before register, (2) register and remove on different workers with per-worker HA testcontainers. Per-run worker-map filed as #1196. Fix in flight as #1198 (single-line --dist loadscope add to pr.yml).

[kingpanther13]

Cleanups all landed in c765653 — exactly what was asked. Approving.

[github-actions]

🧪 Your changes are now in the dev channel!

Your PR has been merged to master and is available for testing in the dev channel.

Test your changes before the next stable release (biweekly Wednesday):
📖 Dev Channel Documentation

Quick start

# Run dev version
uvx ha-mcp-dev

# Check version
uvx ha-mcp-dev --version

Docker:

docker pull ghcr.io/homeassistant-ai/ha-mcp:dev
docker run --rm -i \
  -e HOMEASSISTANT_URL=http://your-ha:8123 \
  -e HOMEASSISTANT_TOKEN=your_token \
  ghcr.io/homeassistant-ai/ha-mcp:dev

---

Found an issue? Please open a new bug report and mention this PR for context.