feat(dashboard): add jq_transform and find_card for efficient editing (#333)

* feat(dashboard): add jq_transform and find_card for efficient editing

Implements features from issues #319 and #320 to improve dashboard
editing UX for AI agents.

## New features:

### jq_transform parameter (#319)
- Added `jq_transform` parameter to `ha_config_set_dashboard`
- Apply jq expressions to existing dashboard config instead of full replacement
- Examples: update card icon, add cards, delete cards by path
- Reduces token usage for small changes (99% reduction for single edits)

### ha_dashboard_find_card tool (#320)
- Find cards by entity_id (with wildcard support), card_type, or heading
- Returns jq_path for each match, ready for use with jq_transform
- Eliminates manual index counting from large dashboard configs

## Dependencies:
- Added jq>=1.8.0 for jq expression support

## Usage example:
```python
# Find card location
find = ha_dashboard_find_card(url_path="my-dash", entity_id="light.bedroom")
# Update using jq_path
ha_config_set_dashboard(
    url_path="my-dash",
    jq_transform=f'{find["matches"][0]["jq_path"]}.icon = "mdi:lamp"'
)
```

Closes #319
Closes #320

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* feat(dashboard): require config_hash, remove card tools, add hints

BREAKING CHANGE: Remove ha_dashboard_add_card, ha_dashboard_update_card,
ha_dashboard_remove_card tools. Use jq_transform in ha_config_set_dashboard
instead for all card operations.

Changes:
- config_hash now REQUIRED for jq_transform (optimistic locking)
- config_hash optional for full config replacement (validates if provided)
- Add card_count and hint to get_dashboard for large dashboards (30+ cards)
- Add soft warning when full-replacing large dashboards
- Document multi-op jq syntax with pipe chaining
- Add IMPORTANT warning about index shifting after delete/add ops
- Add ENABLE_DASHBOARD_PARTIAL_TOOLS feature flag for find_card
- Remove 726 lines of redundant card tool code

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* chore: remove obsolete tests for non-existent dashboard tools

Remove test file and conftest that tested dashboard resource tools
(ha_config_add_dashboard_resource, etc.) which were never implemented.
Also fix feature flag check to handle missing settings gracefully.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* test: remove E2E tests for removed card tools

Remove TestCardOperations class from E2E tests since ha_dashboard_add_card,
ha_dashboard_update_card, and ha_dashboard_remove_card have been replaced
by jq_transform in ha_config_set_dashboard.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* refactor(dashboard): improve tool guidance and use token-based threshold

Address feedback from PR review:
- Update tool description to clearly prefer jq_transform for edits
- Change threshold from card count to config size (10KB ≈ 2-3k tokens)
- Return config_size_bytes instead of card_count in get_dashboard
- Remove unused _count_cards_in_config helper

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* test: add E2E tests for jq_transform and find_card

Add comprehensive E2E tests for new features:
- jq_transform: update field, add/delete cards
- config_hash validation: conflict detection, required for jq_transform
- ha_dashboard_find_card: by entity, by type, workflow with jq_transform

Tests cover:
- Basic jq operations (update, add, delete)
- Optimistic locking (hash validation)
- find_card -> jq_transform workflow
- Error cases (missing hash, stale hash)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: julienld

pyproject.toml

@@ -26,6 +26,7 @@ classifiers = [
 dependencies = [
     "fastmcp>=2.11.0",
     "httpx>=0.27.0",
+    "jq>=1.8.0",
     'textdistance[extras]>=4.6.0; platform_machine != "arm64" and platform_machine != "aarch64" and platform_machine != "ARM64"',
     'textdistance>=4.6.0; platform_machine == "arm64" or platform_machine == "aarch64" or platform_machine == "ARM64"',
     "pydantic>=2.5.0",

src/ha_mcp/config.py

@@ -69,6 +69,11 @@ class Settings(BaseSettings):
     # Examples: "tools_config_automations,tools_config_scripts,tools_traces"
     enabled_tool_modules: str = Field("all", alias="ENABLED_TOOL_MODULES")
 
+    # Dashboard partial update tools (jq_transform, find_card)
+    # These are token-efficient alternatives to full config replacement.
+    # Disable when using clients with programmatic tool use (future).
+    enable_dashboard_partial_tools: bool = Field(True, alias="ENABLE_DASHBOARD_PARTIAL_TOOLS")
+
     @property
     def env_file_name(self) -> str:
         """Get the current environment file name."""