ha-mcp-dev 8.3.0.dev2438__tar.gz → 8.3.0.dev2442__tar.gz

{ha_mcp_dev-8.3.0.dev2438/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.3.0.dev2442}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.3.0.dev2438
+Version: 8.3.0.dev2442
 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.3.0.dev2438 → ha_mcp_dev-8.3.0.dev2442}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.3.0.dev2438"
+version = "8.3.0.dev2442"
 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.3.0.dev2438 → ha_mcp_dev-8.3.0.dev2442}/src/ha_mcp/settings_ui/_i18n.py

@@ -8,11 +8,16 @@ individual translations may be incomplete and safely inherit missing values.
 from __future__ import annotations
 
 import json
+import logging
 import re
 from collections import Counter
 from pathlib import Path
 from typing import Any
 
+from . import _locale_policy
+
+_LOGGER = logging.getLogger(__name__)
+
 DEFAULT_LOCALE = "en"
 LOCALE_COOKIE = "ha_mcp_locale"
 LOCALES_DIR = Path(__file__).parent / "locales"
@@ -87,6 +92,220 @@ def _validate_tools(value: Any, *, context: str) -> dict[str, dict[str, str]]:
     return result
 
 
+def _warn_best_effort_catalog(locale: str, path: Path, exc: Exception) -> None:
+    _LOGGER.warning("Skipping best-effort locale %s from %s: %s", locale, path, exc)
+
+
+def _warn_best_effort_entry(locale: str, entry: str, exc: Exception) -> None:
+    _LOGGER.warning(
+        "Ignoring invalid best-effort locale %s %s; using English fallback: %s",
+        locale,
+        entry,
+        exc,
+    )
+
+
+def _validate_best_effort_string_map(
+    value: Any,
+    *,
+    locale: str,
+    context: str,
+    entry_kind: str,
+) -> dict[str, str]:
+    """Drop invalid best-effort strings while preserving valid siblings."""
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ValueError(f"{context} must be an object")
+
+    result: dict[str, str] = {}
+    for key, text in value.items():
+        try:
+            result.update(_validate_string_map({key: text}, context=context))
+        except ValueError as exc:
+            _warn_best_effort_entry(locale, f"{entry_kind} {key!r}", exc)
+    return result
+
+
+def _validate_best_effort_tools(
+    value: Any, *, locale: str, context: str
+) -> dict[str, dict[str, str]]:
+    """Drop invalid best-effort tool fields while preserving valid siblings."""
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ValueError(f"{context} must be an object")
+
+    result: dict[str, dict[str, str]] = {}
+    for tool_name, tool_values in value.items():
+        if not isinstance(tool_name, str) or not isinstance(tool_values, dict):
+            exc = ValueError(f"{context} entries must be objects keyed by tool name")
+            _warn_best_effort_entry(locale, f"tool {tool_name!r}", exc)
+            continue
+
+        translated: dict[str, str] = {}
+        for field, field_value in tool_values.items():
+            if field not in ("title", "description"):
+                exc = ValueError(
+                    f"{context}.{tool_name} has unsupported field: {field!r}"
+                )
+                _warn_best_effort_entry(
+                    locale, f"tool {tool_name!r} field {field!r}", exc
+                )
+                continue
+            try:
+                validated = _validate_tools(
+                    {tool_name: {field: field_value}}, context=context
+                )
+            except ValueError as exc:
+                _warn_best_effort_entry(
+                    locale, f"tool {tool_name!r} field {field!r}", exc
+                )
+                continue
+            if field in validated[tool_name]:
+                translated[field] = validated[tool_name][field]
+        if translated:
+            result[tool_name] = translated
+    return result
+
+
+def _load_catalog_file(
+    path: Path, *, best_effort_locale: str | None = None
+) -> dict[str, Any]:
+    """Load and validate one catalog without coupling it to its siblings."""
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise ImportError(f"Invalid settings UI locale catalog: {path}") from exc
+    if not isinstance(raw, dict):
+        raise ValueError(f"Locale catalog {path} must contain a JSON object")
+
+    meta = raw.get("meta")
+    if not isinstance(meta, dict):
+        raise ValueError(f"Locale catalog {path} must define a meta object")
+    native_name = meta.get("native_name")
+    direction = meta.get("dir", "ltr")
+    if not isinstance(native_name, str) or not native_name.strip():
+        raise ValueError(f"Locale catalog {path} needs meta.native_name")
+    if direction not in ("ltr", "rtl"):
+        raise ValueError(f"Locale catalog {path} meta.dir must be ltr or rtl")
+
+    unknown_sections = set(raw) - {"meta", "messages", "tool_groups", "tools"}
+    if unknown_sections:
+        raise ValueError(
+            f"Locale catalog {path} has unsupported sections: "
+            f"{sorted(unknown_sections)}"
+        )
+
+    if best_effort_locale is None:
+        messages = _validate_string_map(
+            raw.get("messages"), context=f"{path.name}.messages"
+        )
+        tool_groups = _validate_string_map(
+            raw.get("tool_groups"), context=f"{path.name}.tool_groups"
+        )
+        tools = _validate_tools(raw.get("tools"), context=f"{path.name}.tools")
+    else:
+        messages = _validate_best_effort_string_map(
+            raw.get("messages"),
+            locale=best_effort_locale,
+            context=f"{path.name}.messages",
+            entry_kind="message",
+        )
+        tool_groups = _validate_best_effort_string_map(
+            raw.get("tool_groups"),
+            locale=best_effort_locale,
+            context=f"{path.name}.tool_groups",
+            entry_kind="tool group",
+        )
+        tools = _validate_best_effort_tools(
+            raw.get("tools"),
+            locale=best_effort_locale,
+            context=f"{path.name}.tools",
+        )
+
+    return {
+        "meta": {"native_name": native_name, "dir": direction},
+        "messages": messages,
+        "tool_groups": tool_groups,
+        "tools": tools,
+    }
+
+
+def _catalog_fragment(
+    catalog: dict[str, Any],
+    *,
+    messages: dict[str, str] | None = None,
+    tools: dict[str, dict[str, str]] | None = None,
+) -> dict[str, Any]:
+    """Return a minimal catalog used to validate one translated entry."""
+    return {
+        "meta": catalog["meta"],
+        "messages": messages or {},
+        "tool_groups": {},
+        "tools": tools or {},
+    }
+
+
+def _sanitize_best_effort_catalog(
+    locale: str,
+    catalog: dict[str, Any],
+    english: dict[str, Any],
+    settings_html: Path,
+) -> dict[str, Any]:
+    """Drop only invalid translated entries so the rest of a locale survives."""
+    sanitized = {
+        "meta": dict(catalog["meta"]),
+        "messages": dict(catalog["messages"]),
+        "tool_groups": dict(catalog["tool_groups"]),
+        "tools": {
+            tool_name: dict(fields) for tool_name, fields in catalog["tools"].items()
+        },
+    }
+    known_panels = _known_panels(settings_html)
+
+    for key, translated in tuple(sanitized["messages"].items()):
+        english_messages = (
+            {key: english["messages"][key]} if key in english["messages"] else {}
+        )
+        candidate = {
+            DEFAULT_LOCALE: _catalog_fragment(english, messages=english_messages),
+            locale: _catalog_fragment(sanitized, messages={key: translated}),
+        }
+        try:
+            _validate_placeholder_parity(candidate)
+            _validate_inline_markup(candidate)
+            _validate_panel_links(candidate, settings_html, known_panels=known_panels)
+        except ValueError as exc:
+            del sanitized["messages"][key]
+            _warn_best_effort_entry(locale, f"message {key!r}", exc)
+
+    for tool_name, translated_tool in tuple(sanitized["tools"].items()):
+        for field, translated in tuple(translated_tool.items()):
+            english_field = english["tools"].get(tool_name, {}).get(field)
+            english_tools = (
+                {tool_name: {field: english_field}} if english_field is not None else {}
+            )
+            candidate = {
+                DEFAULT_LOCALE: _catalog_fragment(english, tools=english_tools),
+                locale: _catalog_fragment(
+                    sanitized,
+                    tools={tool_name: {field: translated}},
+                ),
+            }
+            try:
+                _validate_placeholder_parity(candidate)
+            except ValueError as exc:
+                del translated_tool[field]
+                _warn_best_effort_entry(
+                    locale, f"tool {tool_name!r} field {field!r}", exc
+                )
+        if not translated_tool:
+            del sanitized["tools"][tool_name]
+
+    return sanitized
+
+
 def load_catalogs(
     directory: Path = LOCALES_DIR, settings_html: Path = _SETTINGS_HTML
 ) -> dict[str, dict[str, Any]]:
@@ -106,47 +325,35 @@ def load_catalogs(
     for path in paths:
         locale = path.stem.lower().replace("_", "-")
         try:
-            raw = json.loads(path.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError) as exc:
-            raise ImportError(f"Invalid settings UI locale catalog: {path}") from exc
-        if not isinstance(raw, dict):
-            raise ValueError(f"Locale catalog {path} must contain a JSON object")
-
-        meta = raw.get("meta")
-        if not isinstance(meta, dict):
-            raise ValueError(f"Locale catalog {path} must define a meta object")
-        native_name = meta.get("native_name")
-        direction = meta.get("dir", "ltr")
-        if not isinstance(native_name, str) or not native_name.strip():
-            raise ValueError(f"Locale catalog {path} needs meta.native_name")
-        if direction not in ("ltr", "rtl"):
-            raise ValueError(f"Locale catalog {path} meta.dir must be ltr or rtl")
-
-        unknown_sections = set(raw) - {"meta", "messages", "tool_groups", "tools"}
-        if unknown_sections:
-            raise ValueError(
-                f"Locale catalog {path} has unsupported sections: "
-                f"{sorted(unknown_sections)}"
+            catalogs[locale] = _load_catalog_file(
+                path,
+                best_effort_locale=(
+                    locale if _locale_policy.is_best_effort_locale(locale) else None
+                ),
             )
-
-        catalogs[locale] = {
-            "meta": {"native_name": native_name, "dir": direction},
-            "messages": _validate_string_map(
-                raw.get("messages"), context=f"{path.name}.messages"
-            ),
-            "tool_groups": _validate_string_map(
-                raw.get("tool_groups"), context=f"{path.name}.tool_groups"
-            ),
-            "tools": _validate_tools(raw.get("tools"), context=f"{path.name}.tools"),
-        }
+        except (ImportError, ValueError) as exc:
+            if not _locale_policy.is_best_effort_locale(locale):
+                raise
+            _warn_best_effort_catalog(locale, path, exc)
 
     if DEFAULT_LOCALE not in catalogs:
         raise ImportError(
             f"The settings UI requires {DEFAULT_LOCALE}.json in {directory}"
         )
-    _validate_placeholder_parity(catalogs)
-    _validate_inline_markup(catalogs)
-    _validate_panel_links(catalogs, settings_html)
+
+    strict_catalogs = {
+        locale: catalog
+        for locale, catalog in catalogs.items()
+        if not _locale_policy.is_best_effort_locale(locale)
+    }
+    _validate_placeholder_parity(strict_catalogs)
+    _validate_inline_markup(strict_catalogs)
+    _validate_panel_links(strict_catalogs, settings_html)
+
+    for locale in sorted(set(catalogs) - set(strict_catalogs)):
+        catalogs[locale] = _sanitize_best_effort_catalog(
+            locale, catalogs[locale], catalogs[DEFAULT_LOCALE], settings_html
+        )
     return catalogs
 
 
@@ -234,7 +441,10 @@ def _known_panels(settings_html: Path = _SETTINGS_HTML) -> set[str]:
 
 
 def _validate_panel_links(
-    catalogs: dict[str, dict[str, Any]], settings_html: Path = _SETTINGS_HTML
+    catalogs: dict[str, dict[str, Any]],
+    settings_html: Path = _SETTINGS_HTML,
+    *,
+    known_panels: set[str] | None = None,
 ) -> None:
     """Reject cross-panel links that point at a tab which does not exist.
 
@@ -247,7 +457,7 @@ def _validate_panel_links(
     and group labels go through ``escapeHtml``, so a link written there shows
     as visible garbled markup rather than a dead link — wrong, but not silent.
     """
-    panels = _known_panels(settings_html)
+    panels = known_panels if known_panels is not None else _known_panels(settings_html)
     english_messages = catalogs[DEFAULT_LOCALE]["messages"]
     for locale, catalog in catalogs.items():
         for key, value in catalog["messages"].items():

ha_mcp_dev-8.3.0.dev2442/src/ha_mcp/settings_ui/_locale_policy.py

@@ -0,0 +1,13 @@
+"""Maintenance policy for intentionally best-effort locale catalogs."""
+
+from __future__ import annotations
+
+# Klingon is a novelty translation maintained by hand. It must never consume
+# machine-translation quota or block delivery for supported localizations.
+BEST_EFFORT_LOCALES = frozenset({"tlh"})
+
+
+def is_best_effort_locale(locale: str) -> bool:
+    """Return whether ``locale`` is isolated from hard localization gates."""
+    normalized = locale.lower().replace("_", "-")
+    return normalized in BEST_EFFORT_LOCALES

{ha_mcp_dev-8.3.0.dev2438 → ha_mcp_dev-8.3.0.dev2442}/src/ha_mcp/settings_ui/locales/README.md

@@ -24,6 +24,15 @@ Home Assistant language code names every file:
 - `homeassistant-addon/translations/<code>.yaml` (generated)
 - `homeassistant-addon-dev/translations/<code>.yaml` (generated)
 
+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
+produce warnings instead of failing CI or the daily locale sync. The runtime
+loader skips an invalid Klingon settings catalog, and the generator can project
+English into its add-on catalogs, so Klingon cannot prevent any other locale
+from loading or updating. All other language codes remain subject to every
+hard gate below.
+
 Add the two authored catalogs, then run `python scripts/generate_locales.py`
 and merge: the post-merge `locale-sync.yml` workflow machine-fills every string
 over its next daily runs. The component catalog may start as an empty object;