ha-mcp-dev 8.4.0.dev2496__tar.gz → 8.4.0.dev2497__tar.gz

{ha_mcp_dev-8.4.0.dev2496/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.4.0.dev2497}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.0.dev2496
+Version: 8.4.0.dev2497
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.4.0.dev2496"
+version = "8.4.0.dev2497"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497}/src/ha_mcp/__main__.py

@@ -1040,7 +1040,7 @@ def _is_running_in_container() -> bool:
     so the bind host alone can't tell a loopback-only deployment from a
     LAN-reachable one — the default-path warning would be a false positive
     for every container. Container deployments are hardened through the
-    published guidance instead (AGENTS.md -> Docker; the add-on
+    published guidance instead (docs/agents/development.md -> Docker; the add-on
     auto-generates a secret path).
     """
     # Docker writes /.dockerenv; Podman writes /run/.containerenv.

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497}/src/ha_mcp/server.py

@@ -1719,7 +1719,7 @@ class HomeAssistantSmartMCPServer:
         predicates honest. Tier 2/3 in degraded mode raise so the
         caller gets a clear error instead of a confusing empty result.
         Tool-level failures raise ``ToolError`` (via
-        ``raise_tool_error``) per AGENTS.md, so clients see
+        ``raise_tool_error``) per .gemini/styleguide.md, so clients see
         ``isError=true`` rather than a success payload with an
         embedded error.
         """

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497}/src/ha_mcp/settings_ui/locales/README.md

@@ -16,14 +16,18 @@ cross-surface wording cannot drift.
 
 ## Adding a language
 
-A language ships on **all four** translated surfaces or not at all, and one
-Home Assistant language code names every file:
+A language ships on **all four** translated surfaces or not at all, with one
+Home Assistant language code used across every corresponding file:
 
 - `src/ha_mcp/settings_ui/locales/<code>.json` (this directory; authored)
 - `custom_components/ha_mcp_tools/translations/<code>.json` (authored)
 - `homeassistant-addon/translations/<code>.yaml` (generated)
 - `homeassistant-addon-dev/translations/<code>.yaml` (generated)
 
+<!-- Keep the following marker line intact; locale parity tests parse it. -->
+The current code set `cs`, `de`, `eo`, `es`, `fr`, `it`, `ko`, `nl`, `pl`, `ru`, `sv`, `tlh`, and `zh-Hans` names every file:
+the parity test keeps this documentation aligned with the shipped catalogs.
+
 Klingon (`tlh`) is the one best-effort exception. Its catalogs may be edited
 manually and still ship, but the automatic translation planner never queues
 them. Missing strings use English fallback; invalid or stale Klingon catalogs
@@ -57,10 +61,9 @@ surface resting on a single anchor loses its register in exactly that run —
 `test_component_samples_survive_their_own_anchor_being_queued` pins the
 survival. To fill them in your own PR instead, run
 `scripts/translate_locales.py` yourself and review its output like any
-other diff. Also add the new code to the locale list in the repository-root
-`AGENTS.md`
-§ Translations — that list is pinned by
-`test_agents_md_lists_every_shipped_locale`. The engine reads the target
+other diff. Also add the new code to the current code set near the top of this
+guide; `test_locale_readme_lists_every_shipped_locale` pins that list to the
+shipped catalogs. The engine reads the target
 language from `meta.native_name`, so any language an LLM can write — natural
 or constructed — needs no pipeline change.
 
@@ -109,6 +112,10 @@ In PR CI (ungated — `tests/src/unit/test_locale_parity.py` unless another file
 is named):
 
 - Every surface carries the same set of language codes.
+- Settings UI `messages` may omit keys because English is the per-key
+  fallback, but a locale may not carry a key absent from `en.json`: nothing
+  can render it. `tool_groups` and `tools` must instead match the renderable
+  keys exactly.
 - Every decided `Decision` outcome (all but `pending`) and every
   `PredicateOp` operator has a word in every catalog, non-blank — and in every
   catalog but `en.json` not still spelled the way the backend does
@@ -148,9 +155,14 @@ In the post-merge `locale-sync.yml` workflow only (the same files, gated behind
 these, and the daily sync owes them afterwards):
 
 - `tool_groups` and `tools` name exactly the renderable groups and tools.
+  The check parses the registered tool set from source rather than trusting
+  generated `tools.json`, so a broken generator cannot validate its own stale
+  output.
 - At most 5% of this catalog's `messages`, and 5% of its `tools` texts, may be
-  byte-identical to English or missing outright; the component catalogs allow
-  15%, because they carry product names as keys of their own. A single tool
+  byte-identical to English or missing outright. The 5% ceiling also applies
+  independently to each generated app projection computed from the canonical
+  store. Component catalogs allow 15%, because they carry product names as
+  keys of their own. A single tool
   whose `title` *and* `description` are both still English fails by name
   however small the share.
 - The English each translation was written against is hashed in
@@ -159,3 +171,75 @@ these, and the daily sync owes them afterwards):
   `scripts/translate_locales.py` retranslates exactly those keys and repins
   the baseline. Adding a language does not change any English source, so no
   baseline regeneration is needed for it.
+`test_locale_sync_gate_shape.py` pins this gated workflow wiring. A successful
+`locale-sync.yml` run pushes the regenerated catalogs straight to `master`
+with the release App credential and can include everything merged since the
+previous run.
+
+## English changes and retranslation
+
+An English change is a one-place edit:
+
+- Settings messages: `en.json` `messages`.
+- Tool title or summary: the tool definition; English `tools` is intentionally
+  empty in `en.json`.
+- Component config flow: `strings.json` plus component `en.json`.
+
+After a canonical app-option or feature string changes, run
+`python scripts/generate_locales.py` so the generated projections match. A
+pull request does not owe machine translations. The daily post-merge
+`locale-sync.yml` compares English-source hashes in
+`tests/src/unit/locale_source_baseline.json`, translates changed or missing
+keys through the configured Gemini-compatible endpoint, validates placeholders
+and markup, regenerates projections, and repins the baseline.
+
+To supply a human translation in the same pull request, edit the authored
+catalogs and run `python scripts/update_locale_baseline.py`. The baseline is
+what tells the next sync that the translation covers the current English;
+without that repin, the sync will correctly treat the value as stale and
+replace it. Running `scripts/translate_locales.py` locally also repins after
+its machine-generated pass.
+
+A locale pull request that remained open while its English source changed needs
+special review. Compare its affected values with that surface's current English
+before merging. An old translated value can still have the right key and a
+translated-looking value, so ordinary parity and untranslated-share checks
+cannot detect the stale meaning. Repinning is not a repair because it blesses
+the stale value; delete or update the value so the planner queues the correct
+work. Issue #1993 is the precedent: an English policy changed from ALL-match
+to ANY-match while one locale still asserted the opposite. Numbers and
+code-like identifiers are the cheap signal because rewording often moves one;
+`test_translations_keep_english_numbers_and_identifiers` checks them across
+all three authored surfaces, but cannot replace semantic review.
+
+Tool docstring summaries are English translation sources. Editing a summary
+queues its translated title/description in every locale. `Field(description=)`
+text is not in this baseline. For a feature-gated tool, the user-facing
+`FEATURE_GATED_TOOLS` stub is the translation source; changing only the
+parsed docstring holds that key stale until a human confirms the stub remains
+accurate and runs `python scripts/update_locale_baseline.py`.
+
+## Sync failures and recovery
+
+The translation workflow uses conservative pacing and retries transient 429,
+5xx, and timeout failures with backoff. A repeatedly failing request records
+its strings as failed and continues; two dead batches stop the run before it
+burns the remaining quota.
+
+A partial run commits completed translations plus
+`tests/src/unit/locale_sync_progress.json`. Rerun the workflow or wait for the
+next daily run; it resumes from that file. Only a fully successful run repins
+the baseline and removes progress, so incomplete translation work remains
+visible as a red sync.
+
+When the engine is unavailable, a human may translate the dry-run list, run
+`python scripts/generate_locales.py` and
+`python scripts/update_locale_baseline.py`, and open a normal pull request.
+Human edits win because the machine touches only missing or stale strings. The
+provider boundary is `_call_gemini`, configured by `GEMINI_API_URL`,
+`GEMINI_MODEL`, and `GEMINI_API_KEY`.
+
+The Webhook Proxy app and its bundled integration remain English-only by
+decision. Their tests intentionally reject an accidental partial catalog.
+Any other new catalog directory fails until it is translated across every
+required surface or explicitly added to the English-only decision.

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497}/src/ha_mcp/tools/best_practice_result.py

@@ -1,8 +1,9 @@
 """Warning accumulator and skill-reference routing for the best-practice checks.
 
 Split out of :mod:`best_practice_checker` so a check module can emit a warning
-without importing the checker back (AGENTS.md - Module Size). Nothing here
-inspects a config; it only carries warnings and builds the ' See ...' suffix.
+without importing the checker back (see `.gemini/styleguide.md` § Tool
+Consolidation and Module Size). Nothing here inspects a config; it only carries
+warnings and builds the ' See ...' suffix.
 """
 
 _SKILL_URI_PREFIX = "skill://home-assistant-best-practices/references"

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497}/src/ha_mcp/tools/bulk_selector.py

@@ -837,8 +837,8 @@ async def resolve_bulk_selector(
     hidden_count = len(directly_hidden | hidden_selected | excluded_and_hidden)
     warnings: list[str] = list(visibility_warnings)
     if hidden_count:
-        # AGENTS.md "Return Values": a degraded result belongs in the
-        # top-level warnings list, not just a bare count the caller has no
+        # .gemini/styleguide.md "Tool Tags and Return Values": a degraded
+        # result belongs in top-level warnings, not a bare count the caller has no
         # actionable text for. `counts.hidden` alone cannot tell a user
         # "three entities you wanted controlled were skipped" from "your
         # exclusion was redundant" -- this at least names that something

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497}/src/ha_mcp/tools/error_log_parsing.py

@@ -10,8 +10,9 @@ It also owns the window/pagination unit the two response paths share: how
 large a window one fetch asks for, and how the response describes where that
 window sat and how to read further back.
 
-Split out of ``tools_utility`` under AGENTS.md § Module Size: neither the
-parsing nor the window arithmetic touches the client or the tool plumbing.
+Split out of ``tools_utility`` under `.gemini/styleguide.md` § Tool
+Consolidation and Module Size: neither parsing nor window arithmetic touches
+the client or tool plumbing.
 """
 
 import re

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497}/src/ha_mcp/tools/log_common.py

@@ -1,10 +1,10 @@
 """Shared plumbing for the ``ha_get_logs`` log sources.
 
 Constants, parameter coercion and the cross-source warning rules that every
-source uses, with no dependency on any particular one of them. Split out of
-``tools_utility`` under AGENTS.md § Module Size; the per-source fetchers live in
-``log_sources`` and ``log_sources_supervisor``, and the tool surface in
-``tools_logs``.
+source uses, with no dependency on any particular one. Split from
+``tools_utility`` under `.gemini/styleguide.md` § Tool Consolidation and
+Module Size; per-source fetchers live in ``log_sources`` and
+``log_sources_supervisor``, and the tool surface in ``tools_logs``.
 """
 
 import re

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497}/src/ha_mcp/tools/log_sources.py

@@ -6,7 +6,8 @@ alone: every fetcher here is a thin shell around one client call, and the
 dispatch, validation and tool registration they share live with the host class.
 The Supervisor-backed sources are in ``log_sources_supervisor``.
 
-Split out of ``tools_utility`` under AGENTS.md § Module Size.
+Split out of ``tools_utility`` under `.gemini/styleguide.md` § Tool
+Consolidation and Module Size.
 """
 
 import logging

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497}/src/ha_mcp/tools/log_sources_supervisor.py

@@ -5,7 +5,8 @@ Separate from ``log_sources`` because these two reach Home Assistant through
 Supervisor rather than Core, and carry the whole token/role error vocabulary
 that follows from it. Mixed into ``LogTools`` (``tools_logs``).
 
-Split out of ``tools_utility`` under AGENTS.md § Module Size.
+Split out of ``tools_utility`` under `.gemini/styleguide.md` § Tool
+Consolidation and Module Size.
 """
 
 from typing import Any, Literal, NoReturn

ha_mcp_dev-8.4.0.dev2497/src/ha_mcp/tools/radio/__init__.py

@@ -0,0 +1,7 @@
+"""Per-radio handler modules for the ``ha_manage_radio`` tool.
+
+Each radio (Z-Wave, Zigbee/ZHA, Matter, Thread) gets its own handler module so
+no single file spans every protocol (see `.gemini/styleguide.md` § Tool
+Consolidation and Module Size). The ``tools_radio`` module wires them
+together behind one MCP tool.
+"""

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497}/src/ha_mcp/tools/tools_config_dashboards.py

@@ -2200,9 +2200,9 @@ class DashboardConfigTools:
 
         config_hash: str | None = compute_config_hash(config)
 
-        # Warn-don't-truncate (AGENTS.md Return Values): the walker covers
-        # cards / card / custom_fields / states containers and stops at
-        # the depth bound, so neither a depth-truncated search nor a
+        # Warn-don't-truncate (.gemini/styleguide.md Tool Tags and Return
+        # Values): the walker covers cards / card / custom_fields / states and
+        # stops at the depth bound, so neither a depth-truncated search nor a
         # search over a dashboard carrying a non-traversed child-bearing
         # shape may read as an authoritative complete result. Disclosure
         # keys off the *presence* of such a shape (collected during the

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497}/src/ha_mcp/tools/tools_logs.py

@@ -5,7 +5,8 @@ registration. The sources themselves are mixed in from ``log_sources`` (Core)
 and ``log_sources_supervisor`` (Supervisor), their shared plumbing lives in
 ``log_common``, and the error-log window arithmetic in ``error_log_parsing``.
 
-Split out of ``tools_utility`` under AGENTS.md § Module Size.
+Split out of ``tools_utility`` under `.gemini/styleguide.md` § Tool
+Consolidation and Module Size.
 """
 
 from typing import Annotated, Any, Literal

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497}/src/ha_mcp/tools/tools_service.py

@@ -564,8 +564,8 @@ def _attach_resolution_to_response(
     """Attach ``resolution.summary()`` to a response, surfacing its warnings
     at the top level.
 
-    Per AGENTS.md "Return Values", ``warnings`` is always a top-level
-    ``list[str]``, never nested inside another field.
+    Per .gemini/styleguide.md "Tool Tags and Return Values", ``warnings``
+    is always a top-level ``list[str]``, never nested inside another field.
     ``resolution.summary()`` nests its own warnings (e.g. "N entities were
     hidden") under ``resolution`` for internal cohesion, so this pops them
     back out. ``response`` may already carry dispatch-time warnings (e.g.
@@ -2296,8 +2296,8 @@ class ServiceTools:
         """Resolve one structural selector and, unless ``dry_run``, dispatch it.
 
         Split out of ``ha_bulk_control`` to keep that tool's own McCabe
-        complexity under the repo's C901 threshold (AGENTS.md — no per-file
-        exemptions).
+        complexity under the repo's C901 threshold
+        (docs/agents/development.md — no per-file exemptions).
         """
         if action is None:
             raise_tool_error(

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497}/src/ha_mcp/tools/tools_system.py

@@ -1970,7 +1970,7 @@ class SystemTools:
             # A ToolError (incl. one re-raised by _reraise_if_fatal) carries the
             # MCP isError contract — let it reach ha_get_system_health's own
             # ``except ToolError: raise`` instead of being demoted to a section
-            # error string here (AGENTS.md error-handling guard pattern).
+            # error string here (.gemini/styleguide.md structured-error guard pattern).
             raise
         except Exception as e:
             _reraise_if_fatal(e)

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497}/src/ha_mcp/tools/tools_utility.py

@@ -2,7 +2,8 @@
 Utility tools for Home Assistant MCP server.
 
 Template evaluation. The log tools that used to share this module are in
-``tools_logs`` and its helper modules, split out under AGENTS.md § Module Size.
+``tools_logs`` and its helpers, split out under `.gemini/styleguide.md` §
+Tool Consolidation and Module Size.
 """
 
 import logging

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497}/src/ha_mcp/tools/util_helpers.py

@@ -1628,8 +1628,8 @@ async def apply_entity_category(
 
     Updates result_dict in-place: sets ``'category'`` on success, or appends
     to the top-level ``'warnings'`` list on failure. The list shape mirrors
-    the canonical response contract documented in ``AGENTS.md`` →
-    *Writing MCP Tools → Return Values*.
+    the canonical response contract documented in ``.gemini/styleguide.md`` →
+    *Tool Tags and Return Values*.
 
     Args:
         client: HomeAssistantClient instance

{ha_mcp_dev-8.4.0.dev2496 → ha_mcp_dev-8.4.0.dev2497/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.0.dev2496
+Version: 8.4.0.dev2497
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

ha_mcp_dev-8.4.0.dev2496/src/ha_mcp/tools/radio/__init__.py

@@ -1,6 +0,0 @@
-"""Per-radio handler modules for the ``ha_manage_radio`` tool.
-
-Each radio (Z-Wave, Zigbee/ZHA, Matter, Thread) gets its own handler module so
-no single file spans every protocol (keeps modules focused per AGENTS.md). The
-``tools_radio`` module wires them together behind one MCP tool.
-"""