ha-mcp-dev 8.6.0.dev2909__tar.gz → 8.6.0.dev2925__tar.gz

{ha_mcp_dev-8.6.0.dev2909 → ha_mcp_dev-8.6.0.dev2925}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.6.0.dev2909
+Version: 8.6.0.dev2925
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-8.6.0.dev2909 → ha_mcp_dev-8.6.0.dev2925}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2909"
+version = "8.6.0.dev2925"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-8.6.0.dev2909 → ha_mcp_dev-8.6.0.dev2925}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2909"
+version = "8.6.0.dev2925"
 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.6.0.dev2909 → ha_mcp_dev-8.6.0.dev2925}/src/ha_mcp/config.py

@@ -30,7 +30,6 @@ from ha_mcp.config_registry import (
     BACKUP_OVERRIDE_FIELDS as BACKUP_OVERRIDE_FIELDS,
     BETA_FEATURE_FIELDS as BETA_FEATURE_FIELDS,
     FEATURE_FLAG_FIELDS as FEATURE_FLAG_FIELDS,
-    AdvancedField as AdvancedField,
     BackupOverrideField as BackupOverrideField,
     FeatureFlagField as FeatureFlagField,
 )
@@ -275,122 +274,3 @@ def _reset_global_settings() -> None:
     # tool off?" should see the next gate fire logged. This keeps
     # the dedup tight to the lifetime of one cached Settings.
     _BETA_GATE_LOGGED.clear()
-
-
-# Import-time validator for cross-registry invariants.
-#
-# Catches a class of silent runtime bugs at module load:
-#  - registry rows referencing fields that don't exist on ``Settings``
-#    (rename / removal drift)
-#  - registries overlapping by name (same field applied by two
-#    ``_apply_*_overrides`` functions with potentially divergent
-#    coercion policies)
-#  - bounds entries pointing at non-numeric fields (would silently
-#    no-op in the apply loop)
-#  - choices entries pointing at non-str fields (same)
-#  - ``BETA_FEATURE_FIELDS`` referencing names not in
-#    ``FEATURE_FLAG_FIELDS`` (master gate would write to phantom
-#    Settings attributes)
-def _validate_registry_fields_exist(
-    settings_fields: set[str],
-    advanced_names: set[str],
-    flag_names: set[str],
-    backup_names: set[str],
-) -> None:
-    """Every registry row must reference a real Settings field."""
-    for registry_name, names in (
-        ("ADVANCED_SETTINGS_FIELDS", advanced_names),
-        ("FEATURE_FLAG_FIELDS", flag_names),
-        ("BACKUP_OVERRIDE_FIELDS", backup_names),
-    ):
-        missing = names - settings_fields
-        if missing:
-            raise RuntimeError(
-                f"{registry_name} references fields not on Settings: {sorted(missing)}"
-            )
-
-
-def _validate_registries_disjoint(
-    advanced_names: set[str], flag_names: set[str], backup_names: set[str]
-) -> None:
-    """Registries must be name-disjoint to avoid double-apply with divergent policies."""
-    overlaps = {
-        ("advanced", "flags"): advanced_names & flag_names,
-        ("advanced", "backup"): advanced_names & backup_names,
-        ("flags", "backup"): flag_names & backup_names,
-    }
-    for (a, b), shared in overlaps.items():
-        if shared:
-            raise RuntimeError(
-                f"Registry overlap between {a} and {b}: {sorted(shared)}. "
-                "Each field must be applied by exactly one of "
-                "_apply_feature_flag_overrides / _apply_advanced_overrides "
-                "/ _apply_backup_overrides."
-            )
-
-
-def _validate_advanced_bounds(advanced_by_name: dict[str, AdvancedField]) -> None:
-    """_ADVANCED_SETTINGS_BOUNDS keys must be advanced fields AND numeric."""
-    for name in _ADVANCED_SETTINGS_BOUNDS:
-        if name not in advanced_by_name:
-            raise RuntimeError(
-                f"_ADVANCED_SETTINGS_BOUNDS[{name!r}] is not in "
-                "ADVANCED_SETTINGS_FIELDS"
-            )
-        if advanced_by_name[name].ftype not in (int, float):
-            raise RuntimeError(
-                f"_ADVANCED_SETTINGS_BOUNDS[{name!r}] is on a non-numeric "
-                f"field (type={advanced_by_name[name].ftype.__name__})"
-            )
-
-
-def _validate_advanced_choices(advanced_by_name: dict[str, AdvancedField]) -> None:
-    """_ADVANCED_SETTINGS_CHOICES keys must be advanced fields AND str."""
-    for name in _ADVANCED_SETTINGS_CHOICES:
-        if name not in advanced_by_name:
-            raise RuntimeError(
-                f"_ADVANCED_SETTINGS_CHOICES[{name!r}] is not in "
-                "ADVANCED_SETTINGS_FIELDS"
-            )
-        if advanced_by_name[name].ftype is not str:
-            raise RuntimeError(
-                f"_ADVANCED_SETTINGS_CHOICES[{name!r}] is on a non-str "
-                f"field (type={advanced_by_name[name].ftype.__name__})"
-            )
-
-
-def _validate_beta_subset(flag_names: set[str]) -> None:
-    """BETA_FEATURE_FIELDS must be a subset of FEATURE_FLAG_FIELDS.
-
-    The master gate writes to them via setattr; phantom names would
-    silently land on extras with no effect on the runtime gate.
-    """
-    beta_set = set(BETA_FEATURE_FIELDS)
-    not_in_flags = beta_set - flag_names
-    if not_in_flags:
-        raise RuntimeError(
-            f"BETA_FEATURE_FIELDS contains names not in FEATURE_FLAG_FIELDS: "
-            f"{sorted(not_in_flags)}"
-        )
-
-
-def _validate_registries() -> None:
-    settings_fields = set(Settings.model_fields.keys())
-
-    advanced_names = {f.field for f in ADVANCED_SETTINGS_FIELDS}
-    flag_names = {f.field for f in FEATURE_FLAG_FIELDS}
-    backup_names = {f.field for f in BACKUP_OVERRIDE_FIELDS}
-
-    _validate_registry_fields_exist(
-        settings_fields, advanced_names, flag_names, backup_names
-    )
-    _validate_registries_disjoint(advanced_names, flag_names, backup_names)
-
-    advanced_by_name = {f.field: f for f in ADVANCED_SETTINGS_FIELDS}
-    _validate_advanced_bounds(advanced_by_name)
-    _validate_advanced_choices(advanced_by_name)
-
-    _validate_beta_subset(flag_names)
-
-
-_validate_registries()

{ha_mcp_dev-8.6.0.dev2909 → ha_mcp_dev-8.6.0.dev2925}/src/ha_mcp/config_backup.py

@@ -8,6 +8,7 @@ from ha_mcp._version import is_running_in_addon
 from ha_mcp.config_registry import (
     _BACKUP_OVERRIDE_FILENAME,
     BACKUP_OVERRIDE_FIELDS,
+    SETTING_BOUNDS,
     RegistryFieldType,
 )
 from ha_mcp.config_settings import Settings
@@ -125,10 +126,9 @@ def _read_backup_override_file() -> dict[str, object]:
 
 
 def _coerce_backup_int_value(field_name: str, raw: object) -> tuple[bool, Any]:
-    """Coerce + per-field range-check one int-typed BACKUP_OVERRIDE_FIELDS value.
+    """Coerce + range-check one int-typed BACKUP_OVERRIDE_FIELDS value.
 
-    Split out of ``_coerce_backup_override_value`` (mccabe complexity):
-    handles the int-parse plus the three field-specific range checks.
+    Split out of ``_coerce_backup_override_value`` (mccabe complexity).
     """
     if isinstance(raw, bool) or not isinstance(raw, int):
         logger.warning(
@@ -138,32 +138,14 @@ def _coerce_backup_int_value(field_name: str, raw: object) -> tuple[bool, Any]:
         )
         return False, None
     coerced = int(raw)
-    if field_name == "auto_backup_throttle_minutes" and not 0 <= coerced <= 1440:
+    bounds = SETTING_BOUNDS.get(field_name)
+    if bounds is not None and not bounds[0] <= coerced <= bounds[1]:
         logger.warning(
-            "backup_settings.json: auto_backup_throttle_minutes=%d out of "
-            "range 0..1440; ignoring",
-            coerced,
-        )
-        return False, None
-    if field_name == "auto_backup_retain_per_entity" and not 1 <= coerced <= 10_000:
-        logger.warning(
-            "backup_settings.json: auto_backup_retain_per_entity=%d out of "
-            "range 1..10000; ignoring",
-            coerced,
-        )
-        return False, None
-    if field_name == "auto_backup_calendar_lookahead_days" and not 1 <= coerced <= 365:
-        logger.warning(
-            "backup_settings.json: auto_backup_calendar_lookahead_days=%d out of "
-            "range 1..365; ignoring",
-            coerced,
-        )
-        return False, None
-    if field_name == "snapshot_delete_min_age_days" and not 0 <= coerced <= 365:
-        logger.warning(
-            "backup_settings.json: snapshot_delete_min_age_days=%d out of "
-            "range 0..365; ignoring",
+            "backup_settings.json: %s=%d out of range %g..%g; ignoring",
+            field_name,
             coerced,
+            bounds[0],
+            bounds[1],
         )
         return False, None
     return True, coerced

ha_mcp_dev-8.6.0.dev2925/src/ha_mcp/config_meta.py

@@ -0,0 +1,85 @@
+"""Metadata that ``Settings`` fields carry about where each setting appears.
+
+Each field declares its facts once, as ``Annotated[<type>, Setting(...)]``.
+``config_registry`` derives the web UI and override tables from it, and
+``scripts/generate_app_options.py`` derives the app (add-on) options.
+"""
+
+from dataclasses import dataclass
+from typing import Literal
+
+from pydantic.fields import FieldInfo
+
+__all__ = [
+    "BETA_MASTER",
+    "AdvancedSection",
+    "AppOption",
+    "Setting",
+    "SettingSurface",
+    "setting_of",
+]
+
+# Closed set of UI section names. The advanced renderer in
+# settings_ui/__init__.py picks a DOM container per section; a typo would render
+# the row into nothing.
+AdvancedSection = Literal[
+    "connection",
+    "search",
+    "operations",
+    "diagnostics",
+    "tools_surface",
+    "sidecar",
+    "beta_codemode",
+    "beta_yamlkeys",
+    "developer",
+]
+
+# The feature flag that gates every ``beta`` flag.
+BETA_MASTER = "enable_beta_features"
+
+# Which web UI surface edits the setting: the feature toggles, the Advanced
+# section, or the auto-backup settings. Each has its own override file.
+SettingSurface = Literal["feature", "advanced", "backup"]
+
+
+@dataclass(frozen=True)
+class AppOption:
+    """The setting is an option on the app's Configuration page.
+
+    ``start.py`` exports the option to the setting's env var. An option that
+    only some flavors declare is exported only when ``options.json`` has the
+    key: an exported value marks the setting as app-managed in the web UI,
+    and Supervisor rejects a save of a key the flavor does not declare.
+    """
+
+    flavors: tuple[Literal["stable", "dev"], ...] = ("stable", "dev")
+    # The dev flavor's default when it differs from the field default.
+    dev_default: bool | None = None
+    # Supervisor requires the option; every other option is optional ("?").
+    required: bool = False
+
+
+@dataclass(frozen=True)
+class Setting:
+    """What a ``Settings`` field means outside the model itself."""
+
+    surface: SettingSurface | None = None
+    # Advanced settings only: the UI section, and whether the UI may edit it.
+    section: AdvancedSection | None = None
+    editable: bool = True
+    # Gated by the ``enable_beta_features`` master toggle.
+    beta: bool = False
+    app: AppOption | None = None
+    restart_required: bool = False
+    # Inclusive bounds. ``off_value`` is a value outside them that means off.
+    range: tuple[float, float] | None = None
+    off_value: int | None = None
+    choices: tuple[str, ...] | None = None
+    # An env value that does not parse or is out of range logs a warning and
+    # gives the default, instead of failing the settings validation.
+    lenient: bool = False
+
+
+def setting_of(field: FieldInfo) -> Setting | None:
+    """Return the ``Setting`` a model field is annotated with, if any."""
+    return next((m for m in field.metadata if isinstance(m, Setting)), None)

ha_mcp_dev-8.6.0.dev2925/src/ha_mcp/config_registry.py

@@ -0,0 +1,269 @@
+"""Registries of runtime-editable settings and their validation bounds.
+
+Every table is derived from the ``Setting`` metadata on the ``Settings``
+fields; add or change a setting there, not here.
+"""
+
+from typing import NamedTuple
+
+from pydantic.fields import FieldInfo
+
+from ha_mcp.config_meta import (
+    BETA_MASTER,
+    AdvancedSection,
+    Setting,
+    SettingSurface,
+    setting_of,
+)
+from ha_mcp.config_settings import Settings
+
+__all__ = [
+    "ADDON_SYNCED_ADVANCED_FIELDS",
+    "ADVANCED_RESTART_REQUIRED",
+    "ADVANCED_SETTINGS_FIELDS",
+    "BACKUP_OVERRIDE_FIELDS",
+    "BETA_FEATURE_FIELDS",
+    "FEATURE_FLAG_FIELDS",
+    "SETTING_BOUNDS",
+    "_ADVANCED_SETTINGS_BOUNDS",
+    "_ADVANCED_SETTINGS_CHOICES",
+    "_ADVANCED_SETTINGS_SENTINELS",
+    "_BACKUP_OVERRIDE_FILENAME",
+    "_FEATURE_FLAG_INT_BOUNDS",
+    "_FEATURE_FLAG_OVERRIDE_FILENAME",
+    "AdvancedField",
+    "AdvancedSection",
+    "BackupOverrideField",
+    "FeatureFlagField",
+    "OverrideField",
+    "RegistryFieldType",
+]
+
+# ===== Typed registry shapes =====
+#
+# NamedTuples preserve positional-unpack compatibility (existing
+# ``for fname, env, ftype in FEATURE_FLAG_FIELDS:`` iteration sites keep
+# working) AND add attribute access (``f.field`` / ``f.env`` / ``f.ftype``)
+# for new call sites.
+
+# Allowed python types for the override-apply machinery in
+# ``_apply_*_overrides``. Anything outside this set silently falls into
+# the ``else: continue`` arm of the type switch and the override is
+# dropped, so ``_ftype`` below rejects any other field type at import.
+RegistryFieldType = type[bool] | type[int] | type[float] | type[str]
+
+
+class OverrideField(NamedTuple):
+    """One row of an override-style registry (feature flags + backup
+    settings + any future ``(field, env, ftype)`` registry).
+
+    NOTE: adding a field here is a BREAKING change for every positional
+    unpack site (e.g. ``for f, e, t in FEATURE_FLAG_FIELDS:``). Prefer
+    a new NamedTuple over extending this one if a registry needs
+    additional metadata.
+    """
+
+    field: str
+    env: str
+    ftype: RegistryFieldType
+
+
+# Aliases preserve the readable names callers use at construction sites
+# (``FeatureFlagField(...)`` reads more clearly than ``OverrideField(...)``
+# inside FEATURE_FLAG_FIELDS) while ensuring the two registries can never
+# drift apart at the type level.
+FeatureFlagField = OverrideField
+BackupOverrideField = OverrideField
+
+
+class AdvancedField(NamedTuple):
+    """One row of ADVANCED_SETTINGS_FIELDS.
+
+    NOTE: adding a field here is a BREAKING change for every positional
+    unpack site (e.g. ``for f, e, t, s, ed in ADVANCED_SETTINGS_FIELDS:``).
+    """
+
+    field: str
+    env: str
+    ftype: RegistryFieldType
+    section: AdvancedSection
+    editable: bool
+
+
+def _check_setting(name: str, field: FieldInfo, setting: Setting) -> None:
+    """Raise when a field's ``Setting`` metadata cannot mean what it says.
+
+    Each of these would otherwise be a silent no-op at runtime: a range
+    that the type switch in the apply loops never reads, a UI row rendered
+    into no section, or a master gate writing to a field it cannot gate.
+    """
+    numeric = field.annotation in (int, float)
+    problems = [
+        (setting.range is not None and not numeric, "a range on a non-numeric field"),
+        (
+            setting.choices is not None and field.annotation is not str,
+            "choices on a non-str field",
+        ),
+        (
+            setting.off_value is not None and setting.range is None,
+            "an off value without a range",
+        ),
+        (
+            setting.lenient and setting.range is None and setting.choices is None,
+            "lenient parsing with nothing to check",
+        ),
+        (
+            (setting.surface == "advanced") != (setting.section is not None),
+            "a section on a non-advanced setting, or an advanced setting without one",
+        ),
+        (
+            setting.beta
+            and (setting.surface != "feature" or field.annotation is not bool),
+            "a beta flag that is not a bool feature flag",
+        ),
+        (field.alias is None, "no env var alias"),
+        (
+            setting.surface is not None
+            and field.annotation not in (bool, int, float, str),
+            "a web UI surface on a type the override files cannot store",
+        ),
+        (
+            setting.app is not None and field.annotation not in (bool, int, str),
+            "an app option of a type start.py cannot check",
+        ),
+        # start.py treats the dev-only app options, apart from the master,
+        # as the beta sub-flags the master gates.
+        (
+            setting.beta and (setting.app is None or setting.app.flavors != ("dev",)),
+            "a beta flag that is not a dev-only app option",
+        ),
+        (
+            setting.app is not None
+            and setting.app.flavors == ("dev",)
+            and not setting.beta
+            and name != BETA_MASTER,
+            "a dev-only app option that is not a beta flag",
+        ),
+    ]
+    for failed, problem in problems:
+        if failed:
+            raise RuntimeError(f"Settings.{name} has {problem}")
+
+
+def _settings_of(surface: SettingSurface) -> list[tuple[str, FieldInfo, Setting]]:
+    """Return the ``Settings`` fields of one web UI surface, in field order."""
+    fields = []
+    for name, field in Settings.model_fields.items():
+        setting = setting_of(field)
+        if setting is not None and setting.surface == surface:
+            fields.append((name, field, setting))
+    return fields
+
+
+for _name, _field in Settings.model_fields.items():
+    if (_setting := setting_of(_field)) is not None:
+        _check_setting(_name, _field, _setting)
+
+
+def _env(field: FieldInfo) -> str:
+    assert field.alias is not None
+    return field.alias
+
+
+def _ftype(field: FieldInfo) -> RegistryFieldType:
+    assert field.annotation in (bool, int, float, str)
+    return field.annotation
+
+
+FEATURE_FLAG_FIELDS: tuple[FeatureFlagField, ...] = tuple(
+    FeatureFlagField(name, _env(field), _ftype(field))
+    for name, field, _setting in _settings_of("feature")
+)
+
+# Beta sub-flags gated by ``enable_beta_features``. Consumed by the master
+# gate inside ``_apply_feature_flag_overrides``; the per-field UI and save
+# logic iterates ``FEATURE_FLAG_FIELDS`` as for any other flag.
+BETA_FEATURE_FIELDS: tuple[str, ...] = tuple(
+    name for name, _field, setting in _settings_of("feature") if setting.beta
+)
+
+# Override-file location is the same data dir that holds tool_config.json
+# (resolved via ``utils.data_paths.get_data_dir`` — ``HA_MCP_CONFIG_DIR``,
+# addon ``/data``, ``~/.ha-mcp``, or a tmpdir fallback).
+# Imported lazily inside helpers to avoid a circular import at module
+# load.
+_FEATURE_FLAG_OVERRIDE_FILENAME = "feature_flags.json"
+
+# Fields already in ``FEATURE_FLAG_FIELDS`` are not advanced settings: the
+# UI sources them from there, so the per-field env-pin / addon-Supervisor
+# routing stays the same for those rows.
+ADVANCED_SETTINGS_FIELDS: tuple[AdvancedField, ...] = tuple(
+    AdvancedField(name, _env(field), _ftype(field), setting.section, setting.editable)
+    for name, field, setting in _settings_of("advanced")
+    if setting.section is not None  # always, by _check_setting; narrows the type
+)
+
+BACKUP_OVERRIDE_FIELDS: tuple[BackupOverrideField, ...] = tuple(
+    BackupOverrideField(name, _env(field), _ftype(field))
+    for name, field, _setting in _settings_of("backup")
+)
+
+# The inclusive range of every setting that has one, for the override-file,
+# web UI and dev-tool write paths.
+SETTING_BOUNDS: dict[str, tuple[float, float]] = {
+    name: setting.range
+    for name, field in Settings.model_fields.items()
+    if (setting := setting_of(field)) is not None and setting.range is not None
+}
+
+_FEATURE_FLAG_INT_BOUNDS: dict[str, tuple[float, float]] = {
+    f.field: SETTING_BOUNDS[f.field]
+    for f in FEATURE_FLAG_FIELDS
+    if f.field in SETTING_BOUNDS
+}
+_ADVANCED_SETTINGS_BOUNDS: dict[str, tuple[float, float]] = {
+    f.field: SETTING_BOUNDS[f.field]
+    for f in ADVANCED_SETTINGS_FIELDS
+    if f.field in SETTING_BOUNDS
+}
+
+# Values outside the range that mean "off" (sidecar_pin_port: 0 = ephemeral).
+# The UI emits min=off value so the number input can still express it; the
+# override-apply and UI-POST paths accept the off value OR the range.
+_ADVANCED_SETTINGS_SENTINELS: dict[str, int] = {
+    name: setting.off_value
+    for name, _field, setting in _settings_of("advanced")
+    if setting.off_value is not None
+}
+
+# Allowed values for enum-like string fields (renders as <select> in UI).
+_ADVANCED_SETTINGS_CHOICES: dict[str, tuple[str, ...]] = {
+    name: setting.choices
+    for name, _field, setting in _settings_of("advanced")
+    if setting.choices is not None
+}
+
+# Advanced fields that take effect only after a restart of the MCP server.
+ADVANCED_RESTART_REQUIRED: frozenset[str] = frozenset(
+    name
+    for name, _field, setting in _settings_of("advanced")
+    if setting.restart_required
+)
+
+# Advanced fields that are also app options. In addon mode, start.py writes
+# their env vars from /data/options.json, so the override file would be
+# ignored at next boot anyway — writes must route through Supervisor
+# /addons/self/options instead. ``_origin_for_advanced_field`` returns
+# ``'addon'`` for these in addon mode; ``_save_advanced_settings``
+# batches addon-origin writes and POSTs them via Supervisor.
+ADDON_SYNCED_ADVANCED_FIELDS: tuple[str, ...] = tuple(
+    name for name, _field, setting in _settings_of("advanced") if setting.app
+)
+
+# Override-file location is the same data dir that holds tool_config.json
+# (resolved via ``utils.data_paths.get_data_dir`` — ``HA_MCP_CONFIG_DIR``,
+# addon ``/data``, ``~/.ha-mcp``, or a tmpdir fallback).
+# Imported lazily inside helpers to avoid a circular import at module
+# load (``utils.data_paths`` imports from ``_version`` which imports
+# from ``config`` transitively in some test layouts).
+_BACKUP_OVERRIDE_FILENAME = "backup_settings.json"